Mercurial > hg > xemacs-beta

comparison src/events.h @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ac2d302a0011
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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.
5
6 This file is part of XEmacs.
7
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
11 later version.
12
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
16 for more details.
17
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. */
22
23 /* Synched up with: Not in FSF. */
24
25 #ifndef _XEMACS_EVENTS_H_
26 #define _XEMACS_EVENTS_H_
27
28 #include "systime.h"
29
30 /* There is one object, called an event_stream. This object contains
31 callback functions for doing the window-system dependent operations that
32 XEmacs requires.
33
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
37 frames.
38
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.
44
45 To implement this for one window system is relatively simple.
46 To implement this for multiple window systems is trickier and may
47 not be possible in all situations, but it's been done for X and TTY.
48
49 Note that these callbacks are *NOT* console methods; that's because
50 the routines are not specific to a particular console type but must
51 be able to simultaneously cope with all allowable console types.
52
53 The slots of the event_stream structure:
54
55 next_event_cb A function which fills in an XEmacs_event struture
56 with the next event available. If there is no event
57 available, then this should block.
58
59 IMPORTANT: timer events and especially process
60 events *must not* be returned if there are
61 events of other types available; otherwise you
62 can end up with an infinite loop in Fdiscard_input().
63
64 event_pending_cb A function which says whether there are events to be
65 read. If called with an argument of 0, then this
66 should say whether calling the next_event_cb will
67 block. If called with an argument of 1, then this
68 should say whether there are user-generated events
69 pending (that is, keypresses or mouse-clicks). This
70 is used for redisplay optimization, among other
71 things. On dumb ttys, these two results are the
72 same, but under a window system, they are not.
73
74 If this function is not sure whether there are events
75 to be read, it *must* return 0. Otherwise various
76 undesirable effects will occur, such as redisplay
77 not occurring until the next event occurs.
78
79 handle_magic_event_cb XEmacs calls this with an event structure which
80 contains window-system dependent information that
81 XEmacs doesn't need to know about, but which must
82 happen in order. If the next_event_cb never returns
83 an event of type "magic", this will never be used.
84
85 add_timeout_cb Called with an EMACS_TIME, the absolute time at
86 which a wakeup event should be generated; and a
87 void *, which is an arbitrary value that will be
88 returned in the timeout event. The timeouts
89 generated by this function should be one-shots:
90 they fire once and then disappear. This callback
91 should return an int id-number which uniquely
92 identifies this wakeup. If an implementation
93 doesn't have microseconds or millisecond
94 granularity, it should round up to the closest
95 value it can deal with.
96
97 remove_timeout_cb Called with an int, the id number of a wakeup to
98 discard. This id number must have been returned by
99 the add_timeout_cb. If the given wakeup has
100 already expired, this should do nothing.
101
102 select_process_cb These callbacks tell the underlying implementation to
103 unselect_process_cb add or remove a file descriptor from the list of fds
104 which are polled for inferior-process input. When
105 input becomes available on the given process
106 connection, an event of type "process" should be
107 generated.
108
109 select_console_cb These callbacks tell the underlying implementation
110 unselect_console_cb to add or remove a console from the list of consoles
111 which are polled for user-input.
112
113 select_device_cb These callbacks are used by Unixoid event loops
114 unselect_device_cb (those that use select() and file descriptors and
115 have a separate input fd per device).
116
117 quitp_cb A handler function called from the `QUIT' macro which
118 should check whether the quit character has been
119 typed. On systems with SIGIO, this will not be called
120 unless the `sigio_happened' flag is true (it is set
121 from the SIGIO handler).
122
123 XEmacs has its own event structures, which are distinct from the event
124 structures used by X or any other window system. It is the job of the
125 event_stream layer to translate to this format.
126
127 NOTE: #### All timestamps should be measured as milliseconds since XEmacs
128 started. Currently many or most events have a 0 as their
129 timestamp value, and for other timestamps, they are raw server
130 timestamps. (The X protocol doesn't provide any easy way of
131 translating between server time and real process time; yuck.)
132
133 Every event type has the following structures:
134
135 channel Where this event occurred on. This will be
136 a frame, device, console, or nil, depending on the
137 event type. It is important that an object of
138 a more specific type than is actually generated
139 is not substituted -- e.g. there should not be
140 a frame inserted when a key-press event occurs,
141 because events on dead channels are automatically
142 ignored.
143
144 Specifically:
145
146 -- for button and mouse-motion events, channel
147 will be a frame. (The translation to a window
148 occurs later.)
149 -- for keyboard events, channel will be a console.
150 Note that fake keyboard events (generated
151 by `character-to-event' or something that
152 calls this, such as macros) need to have
153 the selected console stored into them when
154 the event is created. This is so that the
155 correct console-local variables (e.g. the
156 command builder) will get affected.
157 -- for timer, process, magic-eval, and eval events,
158 channel will be nil.
159 -- for scrollbar misc-user events, channel
160 will be a window.
161 -- for menubar misc-user events, channel
162 will be a frame.
163 -- for magic events, channel will be a frame
164 (usually) or a device.
165
166 timestamp When this event occurred -- if not known, this
167 is made up.
168
169 In addition, the following structures are specific to particular event
170 types:
171
172 key_press_event
173 key What keysym this is; an integer or a symbol.
174 If this is an integer, it will be in the printing
175 ASCII range: >32 and <127.
176 modifiers Bucky-bits on that key: control, meta, etc.
177 For most keys, Shift is not a bit; that is implicit
178 in the keyboard layout.
179
180 button_press_event
181 button_release_event
182 button What button went down or up.
183 modifiers Bucky-bits on that button: shift, control, meta, etc.
184 x, y Where it was at the button-state-change (in pixels).
185
186 pointer_motion_event
187 x, y Where it was after it moved (in pixels).
188 modifiers Bucky-bits down when the motion was detected.
189 (Possibly not all window systems will provide this?)
190
191 process_event
192 process the XEmacs "process" object in question
193
194 timeout_event
195 interval_id The ID returned when the associated call to
196 add_timeout_cb() was made
197 ------ the rest of the fields are filled in by XEmacs -----
198 id_number The XEmacs timeout ID for this timeout (more
199 than one timeout event can have the same value
200 here, since XEmacs timeouts, as opposed to
201 add_timeout_cb() timeouts, can resignal
202 themselves)
203 function An elisp function to call when this timeout is
204 processed.
205 object The object passed to that function.
206
207 eval_event
208 function An elisp function to call with this event object.
209 internal_function An unexported function to call with this event
210 object. This allows eval events to call internal
211 functions. For a normal eval event, this field
212 will always be 0.
213 object Anything.
214 This kind of event is used internally; sometimes the
215 window system interface would like to inform XEmacs of
216 some user action (such as focusing on another frame)
217 but needs that to happen synchronously with the other
218 user input, like keypresses. This is useful when
219 events are reported through callbacks rather
220 than in the standard event stream.
221
222 misc_user_event
223 function An elisp function to call with this event object.
224 internal_function Ignored.
225 object Anything.
226 This is similar to an eval_event, except that it is
227 generated by user actions: selections in the
228 menubar or scrollbar actions. It is a "command"
229 event, like key and mouse presses (and unlike mouse
230 motion, process output, and enter and leave window
231 hooks). In many ways, eval_events are not the same
232 as keypresses or misc_user_events.
233
234 magic_event
235 No user-serviceable parts within. This is for things
236 like KeymapNotify and ExposeRegion events and so on
237 that XEmacs itself doesn't care about, but which it
238 must do something with for proper interaction with
239 the window system.
240
241 Magic_events are handled somewhat asynchronously, just
242 like subprocess filters. However, occasionally a
243 magic_event needs to be handled synchronously; in that
244 case, the asynchronous handling of the magic_event will
245 push an eval_event back onto the queue, which will be
246 handled synchronously later. This is one of the
247 reasons why eval_events exist; I'm not entirely happy
248 with this aspect of this event model.
249
250 magic_eval_event
251 This is like an eval event but its contents are
252 not Lisp-accessible. This allows for "internal
253 eval events" that call non-Lisp-accessible functions.
254 Externally, a magic_eval_event just appears as
255 a magic_event; the Lisp programmer need not know
256 anything more.
257 */
258
259
260 struct Lisp_Event;
261 struct Lisp_Process;
262
263 struct event_stream
264 {
265 int (*event_pending_p) (int);
266 void (*next_event_cb) (struct Lisp_Event *);
267 void (*handle_magic_event_cb) (struct Lisp_Event *);
268 int (*add_timeout_cb) (EMACS_TIME);
269 void (*remove_timeout_cb) (int);
270 void (*select_console_cb) (struct console *);
271 void (*unselect_console_cb) (struct console *);
272 void (*select_process_cb) (struct Lisp_Process *);
273 void (*unselect_process_cb) (struct Lisp_Process *);
274 void (*quit_p_cb) (void);
275 };
276
277
278 extern struct event_stream *event_stream;
279
280 typedef enum emacs_event_type
281 {
282 empty_event,
283 key_press_event,
284 button_press_event,
285 button_release_event,
286 pointer_motion_event,
287 process_event,
288 timeout_event,
289 magic_event,
290 magic_eval_event,
291 eval_event,
292 misc_user_event,
293 dead_event
294 } emacs_event_type;
295
296 #define first_event_type empty_event
297 #define last_event_type dead_event
298
299
300 struct key_data
301 {
302 Lisp_Object keysym;
303 unsigned char modifiers;
304 };
305
306 struct button_data
307 {
308 int button;
309 unsigned char modifiers;
310 int x, y;
311 };
312
313 struct motion_data
314 {
315 int x, y;
316 unsigned char modifiers;
317 };
318
319 struct process_data
320 {
321 Lisp_Object process;
322 };
323
324 struct timeout_data
325 {
326 int interval_id;
327 int id_number;
328 Lisp_Object function, object;
329 };
330
331 struct eval_data
332 {
333 Lisp_Object function;
334 Lisp_Object object;
335 };
336
337 struct magic_eval_data
338 {
339 void (*internal_function) (Lisp_Object);
340 Lisp_Object object;
341 };
342
343 #if defined (HAVE_X_WINDOWS) && defined(emacs)
344 # include <X11/Xlib.h>
345 #endif
346
347 #if defined (HAVE_NEXTSTEP) && defined(emacs)
348 # import <appkit/appkit.h>
349 #endif
350
351 union magic_data
352 {
353 char underlying_tty_event;
354 #ifdef HAVE_X_WINDOWS
355 XEvent underlying_x_event;
356 #endif
357 #ifdef HAVE_NEXTSTEP
358 NXEvent underlying_ns_event;
359 #endif
360 };
361
362 struct Lisp_Event
363 {
364 /* header->next (aka XEVENT_NEXT ()) is used as follows:
365 - For dead events, this is the next dead one.
366 - For events on the command_event_queue, the next one on the queue.
367 - Likewise for events chained in the command builder.
368 - Otherwise it's Qnil.
369 */
370 struct lrecord_header lheader;
371 Lisp_Object next;
372 emacs_event_type event_type;
373 Lisp_Object channel;
374 unsigned int timestamp;
375 union
376 {
377 struct key_data key;
378 struct button_data button;
379 struct motion_data motion;
380 struct process_data process;
381 struct timeout_data timeout;
382 struct eval_data eval; /* misc_user_event uses this too */
383 union magic_data magic;
384 struct magic_eval_data magic_eval;
385 } event;
386 };
387
388 DECLARE_LRECORD (event, struct Lisp_Event);
389 #define XEVENT(x) XRECORD (x, event, struct Lisp_Event)
390 #define XSETEVENT(x, p) XSETRECORD (x, p, event)
391 #define EVENTP(x) RECORDP (x, event)
392 #define GC_EVENTP(x) GC_RECORDP (x, event)
393 #define CHECK_EVENT(x) CHECK_RECORD (x, event)
394 #define CONCHECK_EVENT(x) CONCHECK_RECORD (x, event)
395
396 DECLARE_LRECORD (command_builder, struct command_builder);
397
398 #define EVENT_CHANNEL(a) ((a)->channel)
399 #define EVENT_TYPE(a) ((a)->event_type)
400 #define XEVENT_TYPE(a) (XEVENT (a)->event_type)
401 #define EVENT_NEXT(a) ((a)->next)
402 #define XEVENT_NEXT(e) (XEVENT (e)->next)
403 #define XSET_EVENT_NEXT(e, n) do { (XEVENT (e)->next = (n)); } while (0)
404
405 #define EVENT_CHAIN_LOOP(event, chain) \
406 for (event = chain; !NILP (event); event = XEVENT_NEXT (event))
407
408 #define EVENT_LIVE_P(a) (EVENT_TYPE (a) != dead_event)
409
410 #define CHECK_LIVE_EVENT(x) \
411 do { CHECK_EVENT (x); \
412 if (! EVENTP (x) \
413 || ! EVENT_LIVE_P (XEVENT (x))) \
414 dead_wrong_type_argument (Qevent_live_p, (x)); } while (0)
415 #define CONCHECK_LIVE_EVENT(x) \
416 do { CONCHECK_EVENT (x); \
417 if (! EVENTP (x) \
418 || ! EVENT_LIVE_P (XEVENT (x))) \
419 x = wrong_type_argument (Qevent_live_p, (x)); } while (0)
420
421
422 extern Lisp_Object Qevent_live_p;
423
424 /* The modifiers XEmacs knows about; these appear in key and button events.
425 */
426 #define MOD_CONTROL (1<<0)
427 #define MOD_META (1<<1)
428 #define MOD_SUPER (1<<2)
429 #define MOD_HYPER (1<<3)
430 #define MOD_ALT (1<<4)
431 #define MOD_SHIFT (1<<5) /* not used for dual-case characters */
432
433 /* Note: under X Windows, MOD_ALT is generated by the Alt key if there are
434 both Alt and Meta keys. If there are no Meta keys, then Alt generates
435 MOD_META instead.
436 */
437
438 #ifdef emacs
439 /* Maybe this should be trickier */
440 #define KEYSYM(x) (intern (x))
441
442 Lisp_Object allocate_command_builder (Lisp_Object console);
443
444 void format_event_object (char *buf, struct Lisp_Event *e, int brief);
445 void character_to_event (Emchar c, struct Lisp_Event *event,
446 struct console *con,
447 int use_console_meta_flag);
448 void enqueue_magic_eval_event (void (*fun) (Lisp_Object), Lisp_Object object);
449 void zero_event (struct Lisp_Event *e);
450
451 void deallocate_event_chain (Lisp_Object event);
452 Lisp_Object event_chain_tail (Lisp_Object event);
453 void enqueue_event (Lisp_Object event, Lisp_Object *head, Lisp_Object *tail);
454 Lisp_Object dequeue_event (Lisp_Object *head, Lisp_Object *tail);
455 void enqueue_event_chain (Lisp_Object event_chain, Lisp_Object *head,
456 Lisp_Object *tail);
457 int event_chain_count (Lisp_Object event_chain);
458 void nth_of_key_sequence_as_event (Lisp_Object seq, int n, Lisp_Object event);
459 Lisp_Object key_sequence_to_event_chain (Lisp_Object seq);
460 Lisp_Object event_chain_find_previous (Lisp_Object event_chain,
461 Lisp_Object event);
462 Lisp_Object event_chain_nth (Lisp_Object event_chain, int n);
463 Lisp_Object copy_event_chain (Lisp_Object event_chain);
464
465 /* True is this is a non-internal event
466 (keyboard press, menu, scrollbar, mouse button) */
467 int command_event_p (Lisp_Object event);
468
469 struct console *event_console_or_selected (Lisp_Object event);
470
471 int event_stream_event_pending_p (int user);
472 void event_stream_next_event (struct Lisp_Event *event);
473 void event_stream_handle_magic_event (struct Lisp_Event *event);
474 void event_stream_select_console (struct console *c);
475 void event_stream_unselect_console (struct console *c);
476 void event_stream_select_process (struct Lisp_Process *proc);
477 void event_stream_unselect_process (struct Lisp_Process *proc);
478 void event_stream_quit_p (void);
479
480 struct low_level_timeout
481 {
482 int id;
483 EMACS_TIME time;
484 struct low_level_timeout *next;
485 };
486
487 int add_low_level_timeout (struct low_level_timeout **timeout_list,
488 EMACS_TIME thyme);
489 void remove_low_level_timeout (struct low_level_timeout **timeout_list,
490 int id);
491 int get_low_level_timeout_interval (struct low_level_timeout *
492 timeout_list, EMACS_TIME *interval);
493 int pop_low_level_timeout (struct low_level_timeout **timeout_list,
494 EMACS_TIME *time_out);
495 int event_stream_generate_wakeup (unsigned int milliseconds,
496 unsigned int vanilliseconds,
497 Lisp_Object function,
498 Lisp_Object object,
499 int async_p);
500 void event_stream_disable_wakeup (int id, int async_p);
501 void event_stream_deal_with_async_timeout (int interval_id);
502
503 /* from signal.c */
504 int event_stream_add_async_timeout (EMACS_TIME thyme);
505 void event_stream_remove_async_timeout (int id);
506
507 void emacs_handle_focus_change_preliminary (Lisp_Object frame_inp_and_dev);
508 void emacs_handle_focus_change_final (Lisp_Object frame_inp_and_dev);
509
510 Lisp_Object extract_this_command_keys_nth_mouse_event (int n);
511 Lisp_Object extract_vector_nth_mouse_event (Lisp_Object vector, int n);
512
513 void single_console_state (void);
514 void any_console_state (void);
515 int in_single_console_state (void);
516
517 #ifdef HAVE_UNIXOID_EVENT_LOOP
518 /* Ceci n'est pas un pipe. */
519 extern int signal_event_pipe[];
520
521 void signal_fake_event (void);
522 void drain_signal_event_pipe (void);
523
524 extern int fake_event_occurred;
525
526 int event_stream_unixoid_select_console (struct console *con);
527 int event_stream_unixoid_unselect_console (struct console *con);
528 int event_stream_unixoid_select_process (struct Lisp_Process *proc);
529 int event_stream_unixoid_unselect_process (struct Lisp_Process *proc);
530 int read_event_from_tty_or_stream_desc (struct Lisp_Event *event,
531 struct console *c, int fd);
532 #endif /* HAVE_UNIXOID_EVENT_LOOP */
533
534 extern int emacs_is_blocking;
535
536 extern Lisp_Object Vcontrolling_terminal;
537
538 extern volatile int sigint_happened;
539
540 /* Define this if you want the tty event stream to be used when the
541 first console is tty, even if HAVE_X_WINDOWS is defined */
542 /* #define DEBUG_TTY_EVENT_STREAM */
543
544 #endif /* emacs */
545
546 #endif /* _XEMACS_EVENTS_H_ */