home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / lucid / lemacs-19.6 / src / events.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-03-13  |  11.4 KB  |  356 lines
  1. /* Definitions for the new event model;
  2.    created 16-jul-91 by Jamie Zawinski
  3.    Copyright (C) 1991-1993 Free Software Foundation, Inc.
  4.  
  5. This file is part of GNU Emacs.
  6.  
  7. GNU Emacs is free software; you can redistribute it and/or modify
  8. it under the terms of the GNU General Public License as published by
  9. the Free Software Foundation; either version 2, or (at your option)
  10. any later version.
  11.  
  12. GNU Emacs is distributed in the hope that it will be useful,
  13. but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15. GNU General Public License for more details.
  16.  
  17. You should have received a copy of the GNU General Public License
  18. along with GNU Emacs; see the file COPYING.  If not, write to
  19. the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20.  
  21. #ifndef _EMACS_EVENTS_H_
  22. #define _EMACS_EVENTS_H_
  23.  
  24. /* There is one object, called an event_stream.  This object contains 
  25.    callback functions for doing the window-system dependent operations that
  26.    emacs requires.
  27.  
  28.    If emacs is compiled with support for X11 and the X Toolkit, then this
  29.    event_stream structure will contain functions that can cope with input
  30.    on emacs windows on multiple displays, as well as input from dumb tty
  31.    screens.  
  32.  
  33.    If it is desired to have emacs able to open screens on the displays of
  34.    multiple heterogeneous machines, X11 and SunView, or X11 and NeXT, for
  35.    example, then it will be necessary to construct an event_stream structure
  36.    that can cope with the given types.  Currently, the only implemented
  37.    event_streams are for dumb-ttys, and for X11 plus dumb-ttys.
  38.    
  39.    To implement this for one window system is relatively clean and simple.  
  40.    To implement this for multiple window systems is hard and hairy, so we 
  41.    are punting for now.
  42.  
  43.   The slots of the event_stream structure:
  44.  
  45.  next_event_cb        A function which fills in an emacs_event struture
  46.             with the next event available.  If there is no event
  47.             available, then this should block.
  48.  
  49.  event_pending_cb    A function which says whether there are events to be
  50.             read.  If called with an argument of 0, then this
  51.             should say whether calling the next_event_cb will
  52.             block.  If called with an argument of 1, then this
  53.             should say whether there are user-generated events
  54.             pending (that is, keypresses or mouse-clicks.)  This
  55.             is used for redisplay optimization, among other 
  56.             things.  On dumb ttys, these two results are the 
  57.             same, but under a window system, they are not.  
  58.  
  59.  handle_magic_event_cb    Emacs calls this with an event structure which
  60.               contains window-system dependent information that
  61.             emacs doesn't need to know about, but which must
  62.             happen in order.  If the next_event_cb never returns
  63.             an event of type "magic", this will never be used.
  64.  
  65.  generate_wakeup_cb    Called with an int, the number of milliseconds after
  66.               which a wakeup event should be generated; the number
  67.             of milliseconds after which this timeout should *next*
  68.             occur (or 0 if it's a one-shot); a function to call
  69.             when the wakeup occurs; and some other object which
  70.             that function will be called with.  This callback
  71.             should return an int id-number which uniquely
  72.             identifies this wakeup, and the "resignalled" wakeups.
  73.             If an implementation doesn't have millisecond
  74.             granularity, it should round up to the closest value
  75.             it can deal with.
  76.  
  77.  disable_wakeup_cb    Called with an int, the id number of a wakeup to 
  78.              discard.  This id number must have been returned by
  79.             the generate_wakeup_cb.  If the given wakeup has
  80.             already expired, this should do nothing.
  81.  
  82.  select_process_cb    These callbacks tell the underlying implementation to
  83.  unselect_process_cb    add or remove a file descriptor from the list of fds
  84.               which are polled for inferior-process input.  When
  85.             input becomes available on the given tty, an event of
  86.             type "process" should be generated.
  87.  
  88.  select_tty_cb        These callbacks tell the underlying implementation 
  89.  unselect_tty_cb    to add or remove a file descriptor from the list of
  90.               fds which are polled for user-input.  Each character
  91.             read from the fd generates a keypress event.  This
  92.             is dumb-tty-type input; anything more complicated
  93.             than that needs to be handled differently.  
  94.             (Handwave, handwave.)
  95.  
  96.             Possibly we should implement these in terms of 
  97.             select_process_cb.
  98.  
  99.  sigio_cb        A handler function for SIGIO interrupts, if on a 
  100.             system which generates them.  event_streams should
  101.             should be designed to not *require* SIGIO, but can
  102.             take advantage of it if it's present.
  103.  
  104.  Emacs has its own event structures, which are distinct from the event
  105.  structures used by X or any other window system.  It is the job of the
  106.  event_stream layer to translate to this format.
  107.  
  108.  key_press_event    
  109.     event_channel    A token representing which keyboard generated it.
  110.             For this kind of event, this is a screen object.
  111.             (This is for eventual support of multiple displays.)
  112.     timestamp        When it happened (#### in server-time or emacs-time?)
  113.     key            What keysym this is; an integer or a symbol.
  114.             If this is an integer, it will be in the printing
  115.             ASCII range: >32 and <127.
  116.     modifiers        Bucky-bits on that key: control, meta, etc.
  117.             For most keys, Shift is not a bit; that is implicit
  118.             in the keyboard layout.
  119.  button_press_event
  120.  button_release_event
  121.     event_channel    A token representing which mouse generated it.
  122.             For this kind of event, this is a screen object.
  123.     timestamp        When it happened
  124.     button        What button went down or up.
  125.     modifiers        Bucky-bits on that button: shift, control, meta, etc.
  126.     x, y        Where it was at the button-state-change (in pixels).
  127.  
  128.  pointer_motion_event
  129.     event_channel    A token representing which mouse generated it.
  130.             For this kind of event, this is a screen object.
  131.     timestamp        When it happened
  132.     x, y        Where it was after it moved (in pixels).
  133.  
  134.  process_event
  135.     timestamp        When it happened
  136.     process        the emacs "process" object in question
  137.  
  138.  timeout_event
  139.     timestamp        Now (really, when the timeout was signalled)
  140.     function        The elisp function to call for this timeout.  It is
  141.                 called with one argument, the event.
  142.     object        Some lisp object associated with this timeout, to
  143.                 make it easier to tell them apart.
  144.  
  145.  eval_event
  146.     timestamp        When it happened.
  147.     function        An elisp function to call with this event object.
  148.     object        Anything.
  149.             This kind of event is used internally; sometimes the
  150.             window system interface would like to inform emacs of
  151.             some user action (such as focusing on another screen)
  152.             but needs that to happen synchronously with the other
  153.             user input, like keypresses.
  154.  
  155.  menu_event
  156.     timestamp        When it happened.
  157.     function        An elisp function to call with this event object.
  158.     object        Anything.
  159.             This is similar to an eval_event, except that it is
  160.             generated by selections in the menubar.  It is a
  161.             "command" event, like key and mouse presses (and 
  162.             unlike mouse motion, process output, and enter and
  163.             leave window hooks.)  In many ways, eval_events are
  164.             not the same as key- or menu-events.
  165.  
  166.  magic_event
  167.             No user-serviceable parts within.  This is for things
  168.             like KeymapNotify and ExposeRegion events and so on
  169.             that emacs itself doesn't care about, but which it
  170.             must do something with for proper interaction with
  171.             the window system.
  172.  
  173.             Magic_events are handled somewhat asynchronously, just
  174.             like subprocess filters.  However, occasionally a 
  175.             magic_event needs to be handled synchronously; in that
  176.             case, the asynchronous handling of the magic_event will
  177.             push an eval_event back onto the queue, which will be 
  178.             handled synchronously later.  This is why eval_events
  179.             exist; I'm not entirely happy with this aspect of
  180.             this event model.
  181.  */
  182.  
  183.  
  184. /* The following cruft is to determine whether we have SIGIO... */
  185.  
  186. #include "config.h"
  187.  
  188. #include <signal.h>
  189.  
  190. /* Get FIONREAD, if it is available.  */
  191. #ifdef USG
  192. # include <termio.h>
  193. # include <fcntl.h>
  194. #else /* not USG */
  195. # ifndef VMS
  196. #  include <sys/ioctl.h>
  197. # endif /* not VMS */
  198. #endif /* not USG */
  199.  
  200. /* UNIPLUS systems may have FIONREAD.  */
  201. #ifdef UNIPLUS
  202. # include <sys.ioctl.h>
  203. #endif
  204.  
  205. /* Allow m- file to inhibit use of FIONREAD.  */
  206. #ifdef BROKEN_FIONREAD
  207. # undef FIONREAD
  208. #endif
  209.  
  210. #ifdef BSD4_1
  211. # define SIGIO SIGTINT
  212. #endif
  213. #ifndef FIONREAD
  214. # ifdef SIGIO
  215. #  undef SIGIO
  216. # endif
  217. #endif
  218.  
  219.  
  220. struct event_stream {
  221.   int  (*event_pending_p)    (int);
  222.   void (*next_event_cb)        (struct Lisp_Event *);
  223.   void (*handle_magic_event_cb)    (struct Lisp_Event *);
  224.   int  (*generate_wakeup_cb)    (unsigned int, unsigned int,
  225.                  Lisp_Object, Lisp_Object);
  226.   void (*disable_wakeup_cb)    (int);
  227.   void (*select_tty_cb)        (int);
  228.   void (*unselect_tty_cb)    (int);
  229.   void (*select_process_cb)    (struct Lisp_Process *);
  230.   void (*unselect_process_cb)    (struct Lisp_Process *);
  231. #ifdef SIGIO
  232.   void (*sigio_cb)        (void);
  233. #endif
  234. };
  235.  
  236.  
  237. typedef enum emacs_event_type {
  238.   empty_event,
  239.   key_press_event,
  240.   button_press_event,
  241.   button_release_event,
  242.   pointer_motion_event,
  243.   process_event,
  244.   timeout_event,
  245.   magic_event,
  246.   eval_event,
  247.   menu_event,
  248.   dead_event
  249. } emacs_event_type;
  250.  
  251. #define first_event_type empty_event
  252. #define last_event_type dead_event
  253.  
  254.  
  255. struct key_data {
  256.   int               key;
  257.   unsigned char     modifiers;
  258. };
  259.  
  260. struct button_data {
  261.   int               button;
  262.   unsigned char     modifiers;
  263.   int               x, y;
  264. };
  265.  
  266. struct motion_data {
  267.   int               x, y;
  268. };
  269.  
  270. struct process_data {
  271.   Lisp_Object       process;
  272. };
  273.  
  274. struct timeout_data {
  275.   Lisp_Object       function;
  276.   Lisp_Object        object;
  277.   int            id_number;
  278. };
  279.  
  280. struct eval_data {
  281.   Lisp_Object       function;
  282.   Lisp_Object        object;
  283. };
  284.  
  285. #if defined(HAVE_X_WINDOWS) && defined(emacs)
  286. # include <X11/Xlib.h>
  287. #endif
  288.  
  289. #ifndef MAX_UNDERLYING_EVENT_SIZE
  290. # if defined(HAVE_X_WINDOWS) && defined(emacs)
  291. #  define MAX_UNDERLYING_EVENT_SIZE (sizeof (XEvent))
  292. # else
  293. #  define MAX_UNDERLYING_EVENT_SIZE 1
  294. # endif
  295. #endif
  296.  
  297. struct magic_data {
  298.   char           underlying_event [MAX_UNDERLYING_EVENT_SIZE];
  299. };
  300.  
  301. struct Lisp_Event {
  302.   emacs_event_type    event_type;
  303.   Lisp_Object        channel;
  304.   unsigned int        timestamp;
  305.   union {
  306.     struct key_data    key;
  307.     struct button_data    button;
  308.     struct motion_data    motion;
  309.     struct process_data    process;
  310.     struct timeout_data    timeout;
  311.     struct eval_data    eval;   /* menu_event uses this too */
  312.     struct magic_data    magic;
  313.   } event;
  314.   struct Lisp_Event    *next;    /* - For dead events, this is the next dead
  315.                      one.
  316.                    - For events on the command_event_queue,
  317.                      this is the next one on the queue.
  318.                    - Otherwise it's 0.
  319.                  */
  320. };
  321.  
  322. /* This structure is basically a typeahead queue: things like wait-reading-
  323.    process-output will delay the execution of keyboard and mouse events by
  324.    pushing them here.  I'd like this to be private to event-stream.c, but
  325.    alloc.c needs to know about it in order to mark it for GC.
  326.  */
  327. struct command_event_queue {
  328.   struct Lisp_Event *head, *tail;
  329. };
  330.  
  331. extern struct command_event_queue *command_event_queue;
  332.  
  333.  
  334. /* The modifiers emacs knows about; these appear in key and button events.
  335.  */
  336. #define MOD_CONTROL    (1<<0)
  337. #define MOD_META    (1<<1)
  338. #define MOD_SUPER    (1<<2)
  339. #define MOD_HYPER    (1<<3)
  340. #define MOD_SYMBOL    (1<<4)
  341. #define MOD_SHIFT    (1<<5)  /* not used for dual-case characters */
  342.  
  343. /* Note: under X Windows, MOD_SYMBOL is generated by the Alt key if there are
  344.    both Alt and Meta keys.  If there are no Meta keys, then Alt generates
  345.    MOD_META instead.
  346.  */
  347.  
  348. #ifdef emacs
  349. /* Maybe this should be trickier */
  350. #define KEYSYM(x) (intern (x))
  351.  
  352. int event_to_character (struct Lisp_Event *, int);
  353. #endif /* emacs */
  354.  
  355. #endif /* _EMACS_EVENTS_H_ */
  356.