1 /* Definitions for the new event model;
2 created 16-jul-91 by Jamie Zawinski
3 Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
4 Copyright (C) 1995, 1996 Ben Wing.
6 This file is part of XEmacs.
8 XEmacs is free software; you can redistribute it and/or modify it
9 under the terms of the GNU General Public License as published by the
10 Free Software Foundation; either version 2, or (at your option) any
13 XEmacs is distributed in the hope that it will be useful, but WITHOUT
14 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
18 You should have received a copy of the GNU General Public License
19 along with XEmacs; see the file COPYING. If not, write to
20 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 Boston, MA 02111-1307, USA. */
23 /* Synched up with: Not in FSF. */
25 #ifndef INCLUDED_events_h_
26 #define INCLUDED_events_h_
30 /* There is one object called an event_stream. This object contains
31 callback functions for doing the window-system-dependent operations
34 If XEmacs is compiled with support for X11 and the X Toolkit, then this
35 event_stream structure will contain functions that can cope with input
36 on XEmacs windows on multiple displays, as well as input from dumb tty
39 If it is desired to have XEmacs able to open frames on the displays of
40 multiple heterogeneous machines, X11 and SunView, or X11 and NeXT, for
41 example, then it will be necessary to construct an event_stream structure
42 that can cope with the given types. Currently, the only implemented
43 event_streams are for dumb-ttys, and for X11 plus dumb-ttys,
46 To implement this for one window system is relatively simple.
47 To implement this for multiple window systems is trickier and may
48 not be possible in all situations, but it's been done for X and TTY.
50 Note that these callbacks are *NOT* console methods; that's because
51 the routines are not specific to a particular console type but must
52 be able to simultaneously cope with all allowable console types.
54 The slots of the event_stream structure:
56 next_event_cb A function which fills in an XEmacs_event structure
57 with the next event available. If there is no event
58 available, then this should block.
60 IMPORTANT: timer events and especially process
61 events *must not* be returned if there are
62 events of other types available; otherwise you
63 can end up with an infinite loop in Fdiscard_input().
65 event_pending_cb A function which says whether there are events to be
66 read. If called with an argument of 0, then this
67 should say whether calling the next_event_cb will
68 block. If called with an argument of 1, then this
69 should say whether there are user-generated events
70 pending (that is, keypresses or mouse-clicks). This
71 is used for redisplay optimization, among other
72 things. On dumb ttys, these two results are the
73 same, but under a window system, they are not.
75 If this function is not sure whether there are events
76 to be read, it *must* return 0. Otherwise various
77 undesirable effects will occur, such as redisplay
78 not occurring until the next event occurs.
80 handle_magic_event_cb XEmacs calls this with an event structure which
81 contains window-system dependent information that
82 XEmacs doesn't need to know about, but which must
83 happen in order. If the next_event_cb never returns
84 an event of type "magic", this will never be used.
86 add_timeout_cb Called with an EMACS_TIME, the absolute time at
87 which a wakeup event should be generated; and a
88 void *, which is an arbitrary value that will be
89 returned in the timeout event. The timeouts
90 generated by this function should be one-shots:
91 they fire once and then disappear. This callback
92 should return an int id-number which uniquely
93 identifies this wakeup. If an implementation
94 doesn't have microseconds or millisecond
95 granularity, it should round up to the closest
96 value it can deal with.
98 remove_timeout_cb Called with an int, the id number of a wakeup to
99 discard. This id number must have been returned by
100 the add_timeout_cb. If the given wakeup has
101 already expired, this should do nothing.
103 select_process_cb These callbacks tell the underlying implementation to
104 unselect_process_cb add or remove a file descriptor from the list of fds
105 which are polled for inferior-process input. When
106 input becomes available on the given process
107 connection, an event of type "process" should be
110 select_console_cb These callbacks tell the underlying implementation
111 unselect_console_cb to add or remove a console from the list of consoles
112 which are polled for user-input.
114 select_device_cb These callbacks are used by Unixoid event loops
115 unselect_device_cb (those that use select() and file descriptors and
116 have a separate input fd per device).
118 create_stream_pair_cb These callbacks are called by process code to
119 delete_stream_pair_cb create and delete a pair of input and output lstreams
120 which are used for subprocess I/O.
122 quitp_cb A handler function called from the `QUIT' macro which
123 should check whether the quit character has been
124 typed. On systems with SIGIO, this will not be called
125 unless the `sigio_happened' flag is true (it is set
126 from the SIGIO handler).
128 XEmacs has its own event structures, which are distinct from the event
129 structures used by X or any other window system. It is the job of the
130 event_stream layer to translate to this format.
132 NOTE: #### All timestamps should be measured as milliseconds since XEmacs
133 started. Currently they are raw server timestamps. (The X protocol
134 doesn't provide any easy way of translating between server time and
135 real process time; yuck.)
137 Every event type has the following structures:
139 channel Where this event occurred on. This will be
140 a frame, device, console, or nil, depending on the
141 event type. It is important that an object of
142 a more specific type than is actually generated
143 is not substituted -- e.g. there should not be
144 a frame inserted when a key-press event occurs,
145 because events on dead channels are automatically
150 -- for button and mouse-motion events, channel
151 will be a frame. (The translation to a window
153 -- for keyboard events, channel will be a console.
154 Note that fake keyboard events (generated
155 by `character-to-event' or something that
156 calls this, such as macros) need to have
157 the selected console stored into them when
158 the event is created. This is so that the
159 correct console-local variables (e.g. the
160 command builder) will get affected.
161 -- for timer, process, magic-eval, and eval events,
163 -- for misc-user events, channel will be a frame.
164 -- for magic events, channel will be a frame
165 (usually) or a device.
167 timestamp When this event occurred -- if not known, this
170 In addition, the following structures are specific to particular event
174 key What keysym this is; an integer or a symbol.
175 If this is an integer, it will be in the printing
176 ASCII range: >32 and <127.
177 modifiers Bucky-bits on that key: control, meta, etc.
178 Also includes buttons.
179 For many keys, Shift is not a bit; that is implicit
180 in the keyboard layout.
184 button What button went down or up.
185 modifiers Bucky-bits on that button: shift, control, meta, etc.
186 Also includes other buttons (not the one pressed).
187 x, y Where it was at the button-state-change (in pixels).
190 x, y Where it was after it moved (in pixels).
191 modifiers Bucky-bits down when the motion was detected.
194 process the XEmacs "process" object in question
197 interval_id The ID returned when the associated call to
198 add_timeout_cb() was made
199 ------ the rest of the fields are filled in by XEmacs -----
200 id_number The XEmacs timeout ID for this timeout (more
201 than one timeout event can have the same value
202 here, since XEmacs timeouts, as opposed to
203 add_timeout_cb() timeouts, can resignal
205 function An elisp function to call when this timeout is
207 object The object passed to that function.
210 function An elisp function to call with this event object.
211 internal_function An unexported function to call with this event
212 object. This allows eval events to call internal
213 functions. For a normal eval event, this field
216 This kind of event is used internally; sometimes the
217 window system interface would like to inform XEmacs of
218 some user action (such as focusing on another frame)
219 but needs that to happen synchronously with the other
220 user input, like keypresses. This is useful when
221 events are reported through callbacks rather
222 than in the standard event stream.
225 function An elisp function to call with this event object.
226 internal_function Ignored.
228 button What button went down or up.
229 modifiers Bucky-bits on that button: shift, control, meta, etc.
230 x, y Where it was at the button-state-change (in pixels).
231 This is similar to an eval_event, except that it is
232 generated by user actions: selections in the
233 menubar, scrollbar actions, or drag and drop actions.
234 It is a "command" event, like key and mouse presses
235 (and unlike mouse motion, process output, and enter
236 and leave window hooks). In many ways, eval_events
237 are not the same as keypresses or misc_user_events.
238 The button, modifiers, x, and y parts are only used
239 by the XEmacs Drag'n'Drop system. Don't depend on their
240 values for other types of misc_user_events.
243 No user-serviceable parts within. This is for things
244 like KeymapNotify and ExposeRegion events and so on
245 that XEmacs itself doesn't care about, but which it
246 must do something with for proper interaction with
249 Magic_events are handled somewhat asynchronously, just
250 like subprocess filters. However, occasionally a
251 magic_event needs to be handled synchronously; in that
252 case, the asynchronous handling of the magic_event will
253 push an eval_event back onto the queue, which will be
254 handled synchronously later. This is one of the
255 reasons why eval_events exist; I'm not entirely happy
256 with this aspect of this event model.
259 This is like an eval event but its contents are
260 not Lisp-accessible. This allows for "internal
261 eval events" that call non-Lisp-accessible functions.
262 Externally, a magic_eval_event just appears as
263 a magic_event; the Lisp programmer need not know
269 Stream pairs description
270 ------------------------
272 Since there are many possible processes/event loop combinations, the event code
273 is responsible for creating an appropriate lstream type. The process
274 implementation does not care about that implementation.
276 The Create stream pair function is passed two void* values, which identify
277 process-dependent 'handles'. The process implementation uses these handles
278 to communicate with child processes. The function must be prepared to receive
279 handle types of any process implementation. Since only one process
280 implementation exists in a particular XEmacs configuration, preprocessing
281 is a means of compiling in the support for the code which deals with particular
284 For example, a unixoid type loop, which relies on file descriptors, may be
285 asked to create a pair of streams by a unix-style process implementation.
286 In this case, the handles passed are unix file descriptors, and the code
287 may deal with these directly. Although, the same code may be used on Win32
288 system with X-Windows. In this case, Win32 process implementation passes
289 handles of type HANDLE, and the create_stream_pair function must call
290 appropriate function to get file descriptors given HANDLEs, so that these
291 descriptors may be passed to XtAddInput.
293 The handle given may have special denying value, in which case the
294 corresponding lstream should not be created.
296 The return value of the function is a unique stream identifier. It is used
297 by processes implementation, in its platform-independent part. There is
298 the get_process_from_usid function, which returns process object given its
299 USID. The event stream is responsible for converting its internal handle
302 Example is the TTY event stream. When a file descriptor signals input, the
303 event loop must determine process to which the input is destined. Thus,
304 the implementation uses process input stream file descriptor as USID, by
305 simply casting the fd value to USID type.
307 There are two special USID values. One, USID_ERROR, indicates that the stream
308 pair cannot be created. The second, USID_DONTHASH, indicates that streams are
309 created, but the event stream does not wish to be able to find the process
310 by its USID. Specifically, if an event stream implementation never calls
311 get_process_from_usid, this value should always be returned, to prevent
312 accumulating useless information on USID to process relationship.
315 /* typedef unsigned int USID; in lisp.h */
316 #define USID_ERROR ((USID)-1)
317 #define USID_DONTHASH ((USID)0)
322 int (*event_pending_p) (int);
323 void (*next_event_cb) (Lisp_Event *);
324 void (*handle_magic_event_cb) (Lisp_Event *);
325 int (*add_timeout_cb) (EMACS_TIME);
326 void (*remove_timeout_cb) (int);
327 void (*select_console_cb) (struct console *);
328 void (*unselect_console_cb) (struct console *);
329 void (*select_process_cb) (Lisp_Process *);
330 void (*unselect_process_cb) (Lisp_Process *);
331 void (*quit_p_cb) (void);
332 void (*force_event_pending) (struct frame* f);
333 USID (*create_stream_pair_cb) (void* /* inhandle*/, void* /*outhandle*/ ,
334 Lisp_Object* /* instream */,
335 Lisp_Object* /* outstream */,
337 USID (*delete_stream_pair_cb) (Lisp_Object /* instream */,
338 Lisp_Object /* outstream */);
339 int (*current_event_timestamp_cb) (struct console *);
342 /* Flags for create_stream_pair_cb() FLAGS parameter */
343 #define STREAM_PTY_FLUSHING 0x0001
344 #define STREAM_NETWORK_CONNECTION 0x0002
346 extern struct event_stream *event_stream;
348 typedef enum emacs_event_type
353 button_release_event,
354 pointer_motion_event,
364 #define first_event_type empty_event
365 #define last_event_type dead_event
396 Lisp_Object function;
402 Lisp_Object function;
406 struct misc_user_data
408 Lisp_Object function;
415 struct magic_eval_data
417 void (*internal_function) (Lisp_Object);
421 #if defined (HAVE_X_WINDOWS) && defined(emacs)
422 # include <X11/Xlib.h>
432 char underlying_tty_event;
435 GdkEvent underlying_gdk_event;
437 #ifdef HAVE_X_WINDOWS
438 XEvent underlying_x_event;
440 #ifdef HAVE_MS_WINDOWS
441 int underlying_mswindows_event;
447 struct lcrecord_header header;
448 int id; /* Id we use to identify the timeout over its lifetime */
449 int interval_id; /* Id for this particular interval; this may
450 be different each time the timeout is
452 Lisp_Object function, object; /* Function and object associated
454 EMACS_TIME next_signal_time; /* Absolute time when the timeout
455 is next going to be signalled. */
456 unsigned int resignal_msecs; /* How far after the next timeout
457 should the one after that
460 typedef struct Lisp_Timeout Lisp_Timeout;
462 DECLARE_LRECORD (timeout, Lisp_Timeout);
463 #define XTIMEOUT(x) XRECORD (x, timeout, Lisp_Timeout)
464 #define XSETTIMEOUT(x, p) XSETRECORD (x, p, timeout)
465 #define TIMEOUTP(x) RECORDP (x, timeout)
466 #define CHECK_TIMEOUT(x) CHECK_RECORD (x, timeout)
467 #define CONCHECK_TIMEOUT(x) CONCHECK_RECORD (x, timeout)
471 /* header->next (aka XEVENT_NEXT ()) is used as follows:
472 - For dead events, this is the next dead one.
473 - For events on the command_event_queue, the next one on the queue.
474 - Likewise for events chained in the command builder.
475 - Otherwise it's Qnil.
477 struct lrecord_header lheader;
479 emacs_event_type event_type;
481 unsigned int timestamp;
485 struct button_data button;
486 struct motion_data motion;
487 struct process_data process;
488 struct timeout_data timeout;
489 struct eval_data eval; /* misc_user_event no longer uses this */
490 struct misc_user_data misc; /* because it needs position information */
491 union magic_data magic;
492 struct magic_eval_data magic_eval;
496 DECLARE_LRECORD (event, Lisp_Event);
497 #define XEVENT(x) XRECORD (x, event, Lisp_Event)
498 #define XSETEVENT(x, p) XSETRECORD (x, p, event)
499 #define EVENTP(x) RECORDP (x, event)
500 #define CHECK_EVENT(x) CHECK_RECORD (x, event)
501 #define CONCHECK_EVENT(x) CONCHECK_RECORD (x, event)
503 DECLARE_LRECORD (command_builder, struct command_builder);
505 #define EVENT_CHANNEL(a) ((a)->channel)
506 #define EVENT_TYPE(a) ((a)->event_type)
507 #define XEVENT_TYPE(a) (XEVENT (a)->event_type)
508 #define EVENT_NEXT(a) ((a)->next)
509 #define XEVENT_NEXT(e) (XEVENT (e)->next)
510 #define XSET_EVENT_NEXT(e, n) do { (XEVENT (e)->next = (n)); } while (0)
512 #define EVENT_CHAIN_LOOP(event, chain) \
513 for (event = chain; !NILP (event); event = XEVENT_NEXT (event))
515 #define EVENT_LIVE_P(a) (EVENT_TYPE (a) != dead_event)
517 #define CHECK_LIVE_EVENT(x) do { \
519 if (! EVENT_LIVE_P (XEVENT (x))) \
520 dead_wrong_type_argument (Qevent_live_p, (x)); \
522 #define CONCHECK_LIVE_EVENT(x) do { \
523 CONCHECK_EVENT (x); \
524 if (! EVENT_LIVE_P (XEVENT (x))) \
525 x = wrong_type_argument (Qevent_live_p, (x)); \
529 EXFUN (Fcharacter_to_event, 4);
530 EXFUN (Fdeallocate_event, 1);
531 EXFUN (Fevent_glyph_extent, 1);
532 EXFUN (Fevent_modeline_position, 1);
533 EXFUN (Fevent_over_modeline_p, 1);
534 EXFUN (Fevent_over_toolbar_p, 1);
535 EXFUN (Fevent_over_vertical_divider_p, 1);
536 EXFUN (Fevent_point, 1);
537 EXFUN (Fevent_window, 1);
538 EXFUN (Fmake_event, 2);
540 extern Lisp_Object QKbackspace, QKdelete, QKescape, QKlinefeed, QKreturn;
541 extern Lisp_Object QKspace, QKtab, Qmouse_event_p, Vcharacter_set_property;
542 extern Lisp_Object Qcancel_mode_internal;
543 extern Lisp_Object Vmodifier_keys_sticky_time;
545 /* Note: under X Windows, XEMACS_MOD_ALT is generated by the Alt key if there are
546 both Alt and Meta keys. If there are no Meta keys, then Alt generates
547 XEMACS_MOD_META instead.
551 /* Maybe this should be trickier */
552 #define KEYSYM(x) (intern (x))
555 void format_event_object (char *buf, Lisp_Event *e, int brief);
556 void character_to_event (Emchar c, Lisp_Event *event,
558 int use_console_meta_flag,
559 int do_backspace_mapping);
560 void zero_event (Lisp_Event *e);
561 void deallocate_event_chain (Lisp_Object event);
562 Lisp_Object event_chain_tail (Lisp_Object event);
563 void enqueue_event (Lisp_Object event, Lisp_Object *head, Lisp_Object *tail);
564 Lisp_Object dequeue_event (Lisp_Object *head, Lisp_Object *tail);
565 void enqueue_event_chain (Lisp_Object event_chain, Lisp_Object *head,
567 int event_chain_count (Lisp_Object event_chain);
568 void nth_of_key_sequence_as_event (Lisp_Object seq, int n, Lisp_Object event);
569 Lisp_Object key_sequence_to_event_chain (Lisp_Object seq);
570 Lisp_Object event_chain_find_previous (Lisp_Object event_chain,
572 Lisp_Object event_chain_nth (Lisp_Object event_chain, int n);
573 Lisp_Object copy_event_chain (Lisp_Object event_chain);
574 /* True if this is a non-internal event
575 (keyboard press, menu, scrollbar, mouse button) */
576 int command_event_p (Lisp_Object event);
577 void define_self_inserting_symbol (Lisp_Object, Lisp_Object);
578 Emchar event_to_character (Lisp_Event *, int, int, int);
579 struct console *event_console_or_selected (Lisp_Object event);
581 /* from event-stream.c */
582 Lisp_Object allocate_command_builder (Lisp_Object console);
583 void enqueue_magic_eval_event (void (*fun) (Lisp_Object), Lisp_Object object);
584 void event_stream_next_event (Lisp_Event *event);
585 void event_stream_handle_magic_event (Lisp_Event *event);
586 void event_stream_select_console (struct console *con);
587 void event_stream_unselect_console (struct console *con);
588 void event_stream_select_process (Lisp_Process *proc);
589 void event_stream_unselect_process (Lisp_Process *proc);
590 USID event_stream_create_stream_pair (void* inhandle, void* outhandle,
591 Lisp_Object* instream, Lisp_Object* outstream, int flags);
592 USID event_stream_delete_stream_pair (Lisp_Object instream, Lisp_Object outstream);
593 void event_stream_quit_p (void);
595 struct low_level_timeout
599 struct low_level_timeout *next;
602 int add_low_level_timeout (struct low_level_timeout **timeout_list,
604 void remove_low_level_timeout (struct low_level_timeout **timeout_list,
606 int get_low_level_timeout_interval (struct low_level_timeout *
607 timeout_list, EMACS_TIME *interval);
608 int pop_low_level_timeout (struct low_level_timeout **timeout_list,
609 EMACS_TIME *time_out);
610 int event_stream_generate_wakeup (unsigned int milliseconds,
611 unsigned int vanilliseconds,
612 Lisp_Object function,
615 void event_stream_disable_wakeup (int id, int async_p);
616 void event_stream_deal_with_async_timeout (int interval_id);
618 int event_stream_add_async_timeout (EMACS_TIME thyme);
619 void event_stream_remove_async_timeout (int id);
621 /* from event-stream.c -- focus sanity */
622 extern int focus_follows_mouse;
623 void investigate_frame_change (void);
625 void emacs_handle_focus_change_preliminary (Lisp_Object frame_inp_and_dev);
626 void emacs_handle_focus_change_final (Lisp_Object frame_inp_and_dev);
628 Lisp_Object extract_this_command_keys_nth_mouse_event (int n);
629 Lisp_Object extract_vector_nth_mouse_event (Lisp_Object vector, int n);
631 void single_console_state (void);
632 void any_console_state (void);
633 int in_single_console_state (void);
635 extern int emacs_is_blocking;
637 extern volatile int sigint_happened;
639 #ifdef HAVE_UNIXOID_EVENT_LOOP
640 /* from event-unixoid.c */
642 /* Ceci n'est pas un pipe. */
643 extern int signal_event_pipe[];
645 void signal_fake_event (void);
646 void drain_signal_event_pipe (void);
648 extern int fake_event_occurred;
650 int event_stream_unixoid_select_console (struct console *con);
651 int event_stream_unixoid_unselect_console (struct console *con);
652 int event_stream_unixoid_select_process (Lisp_Process *proc);
653 int event_stream_unixoid_unselect_process (Lisp_Process *proc);
654 int read_event_from_tty_or_stream_desc (Lisp_Event *event,
655 struct console *con, int fd);
656 USID event_stream_unixoid_create_stream_pair (void* inhandle, void* outhandle,
657 Lisp_Object* instream,
658 Lisp_Object* outstream,
660 USID event_stream_unixoid_delete_stream_pair (Lisp_Object instream,
661 Lisp_Object outstream);
663 /* Beware: this evil macro evaluates its arg many times */
664 #define FD_TO_USID(fd) ((fd)==0 ? (USID)999999 : ((fd)<0 ? USID_DONTHASH : (USID)(fd)))
666 #endif /* HAVE_UNIXOID_EVENT_LOOP */
668 /* Define this if you want the tty event stream to be used when the
669 first console is tty, even if HAVE_X_WINDOWS is defined */
670 /* #define DEBUG_TTY_EVENT_STREAM */
674 /* #### a hack, until accelerator shit is cleaned up */
676 /* This structure is what we use to encapsulate the state of a command sequence
677 being composed; key events are executed by adding themselves to the command
678 builder; if the command builder is then complete (does not still represent
679 a prefix key sequence) it executes the corresponding command.
681 struct command_builder
683 struct lcrecord_header header;
684 Lisp_Object console; /* back pointer to the console this command
686 /* Qnil, or a Lisp_Event representing the first event read
687 * after the last command completed. Threaded. */
689 Lisp_Object prefix_events;
690 /* Qnil, or a Lisp_Event representing event in the current
691 * keymap-lookup sequence. Subsequent events are threaded via
692 * the event's next slot */
693 Lisp_Object current_events;
694 /* Last elt of above */
695 Lisp_Object most_current_event;
696 /* Last elt before function map code took over. What this means is:
697 All prefixes up to (but not including) this event have non-nil
698 bindings, but the prefix including this event has a nil binding.
699 Any events in the chain after this one were read solely because
700 we're part of a possible function key. If we end up with
701 something that's not part of a possible function key, we have to
702 unread all of those events. */
703 Lisp_Object last_non_munged_event;
704 /* One set of values for function-key-map, one for key-translation-map */
705 struct munging_key_translation
707 /* First event that can begin a possible function key sequence
708 (to be translated according to function-key-map). Normally
709 this is the first event in the chain. However, once we've
710 translated a sequence through function-key-map, this will point
711 to the first event after the translated sequence: we don't ever
712 want to translate any events twice through function-key-map, or
713 things could get really screwed up (e.g. if the user created a
714 translation loop). If this is nil, then the next-read event is
715 the first that can begin a function key sequence. */
716 Lisp_Object first_mungeable_event;
720 Bytecount echo_buf_length; /* size of echo_buf */
721 Bytecount echo_buf_index; /* index into echo_buf
722 * -1 before doing echoing for new cmd */
723 /* Self-insert-command is magic in that it doesn't always push an undo-
724 boundary: up to 20 consecutive self-inserts can happen before an undo-
725 boundary is pushed. This variable is that counter.
727 int self_insert_countdown;
730 #endif /* INCLUDED_events_h_ */