25.6.2 Reading One Event

The lowest level functions for command input are those which read a single event. These functions often make a distinction between command events, which are user actions (keystrokes and mouse actions), and other events, which serve as communication between SXEmacs and the window system.

Function: next-event &optional event prompt

This function reads and returns the next available event from the window system or terminal driver, waiting if necessary until an event is available. Pass this object to dispatch-event to handle it. If an event object is supplied, it is filled in and returned; otherwise a new event object will be created.

Events can come directly from the user, from a keyboard macro, or from unread-command-events.

In most cases, the function next-command-event is more appropriate.

Function: next-command-event &optional event prompt

This function returns the next available “user” event from the window system or terminal driver. Pass this object to dispatch-event to handle it. If an event object is supplied, it is filled in and returned, otherwise a new event object will be created.

The event returned will be a keyboard, mouse press, or mouse release event. If there are non-command events available (mouse motion, sub-process output, etc) then these will be executed (with dispatch-event) and discarded. This function is provided as a convenience; it is equivalent to the Lisp code

  (while (progn
           (next-event event)
           (not (or (key-press-event-p event)
                    (button-press-event-p event)
                    (button-release-event-p event)
                    (menu-event-p event))))
           (dispatch-event event))

Here is what happens if you call next-command-event and then press the right-arrow function key:

(next-command-event)
     ⇒ #<keypress-event right>

Function: read-char

This function reads and returns a character of command input. If a mouse click is detected, an error is signalled. The character typed is returned as an ASCII value.

Note: This function is retained for compatibility with Emacs 18, and is most likely the wrong thing for you to be using: consider using next-command-event instead.

Function: enqueue-eval-event function object

This function adds an eval event to the back of the queue. The eval event will be the next event read after all pending events.