13.6 The Event Stream Callback Routines

There is one object called an event_stream. This object contains callback functions for doing the window-system-dependent operations that XEmacs requires.

If XEmacs is compiled with support for X11 and the X Toolkit, then this event_stream structure will contain functions that can cope with input on SXEmacs windows on multiple displays, as well as input from dumb tty frames.

If it is desired to have SXEmacs able to open frames on the displays of multiple heterogeneous machines, X11 and SunView, or X11 and NeXT, for example, then it will be necessary to construct an event_stream structure that can cope with the given types. Currently, the only implemented event_streams are for dumb-ttys, and for X11 plus dumb-ttys, and for mswindows.

To implement this for one window system is relatively simple. To implement this for multiple window systems is trickier and may not be possible in all situations, but it's been done for X and TTY.

Note that these callbacks are NOT console methods; that's because the routines are not specific to a particular console type but must be able to simultaneously cope with all allowable console types.

The slots of the event_stream structure:

next_event_cb

A function which fills in a SXEmacs_event structure with the next event available. If there is no event available, then this should block.

IMPORTANT: timer events and especially process events *must not* be returned if there are events of other types available; otherwise you can end up with an infinite loop in Fdiscard_input().

event_pending_cb

A function which says whether there are events to be read. If called with an argument of 0, then this should say whether calling the next_event_cb will block. If called with a non-zero argument, then this should say whether there are that many user-generated events pending (that is, keypresses, mouse-clicks, dialog-box selection events, etc.). (This is used for redisplay optimization, among other things.) The difference is that the former includes process events and timer events, but the latter doesn't.

If this function is not sure whether there are events to be read, it must return 0. Otherwise various undesirable effects will occur, such as redisplay not occurring until the next event occurs.

handle_magic_event_cb

SXEmacs calls this with an event structure which contains window-system dependent information that SXEmacs doesn't need to know about, but which must happen in order. If the next_event_cb never returns an event of type "magic", this will never be used.

format_magic_event_cb

Called with a magic event; print a representation of the innards of the event to PSTREAM.

compare_magic_event_cb

Called with two magic events; return non-zero if the innards of the two are equal, zero otherwise.

hash_magic_event_cb

Called with a magic event; return a hash of the innards of the event.

add_timeout_cb

Called with an EMACS_TIME, the absolute time at which a wakeup event should be generated; and a void *, which is an arbitrary value that will be returned in the timeout event. The timeouts generated by this function should be one-shots: they fire once and then disappear. This callback should return an int id-number which uniquely identifies this wakeup. If an implementation doesn't have microseconds or millisecond granularity, it should round up to the closest value it can deal with.

remove_timeout_cb

Called with an int, the id number of a wakeup to discard. This id number must have been returned by the add_timeout_cb. If the given wakeup has already expired, this should do nothing.

select_process_cb

unselect_process_cb

These callbacks tell the underlying implementation to add or remove a file descriptor from the list of fds which are polled for inferior-process input. When input becomes available on the given process connection, an event of type "process" should be generated.

select_console_cb

unselect_console_cb

These callbacks tell the underlying implementation to add or remove a console from the list of consoles which are polled for user-input.

select_device_cb

unselect_device_cb

These callbacks are used by Unixoid event loops (those that use select() and file descriptors and have a separate input fd per device).

create_io_streams_cb

delete_io_streams_cb

These callbacks are called by process code to create the input and output lstreams which are used for subprocess I/O.

quitp_cb

A handler function called from the QUIT macro which should check whether the quit character has been typed. On systems with SIGIO, this will not be called unless the sigio_happened flag is true (it is set from the SIGIO handler).

SXEmacs has its own event structures, which are distinct from the event structures used by X or any other window system. It is the job of the event_stream layer to translate to this format.