- when you are sure that that is safe.
-
-\1f
-File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
-
-Converting Events
------------------
-
- XEmacs provides some auxiliary functions for converting between
-events and other ways of representing keys. These are useful when
-working with ASCII strings and with keymaps.
-
- - Function: character-to-event ch &optional event device
- This function converts a numeric ASCII value to an event structure,
- replete with modifier bits. CH is the character to convert, and
- EVENT is the event object to fill in. This function contains
- knowledge about what the codes "mean"--for example, the number 9 is
- converted to the character <Tab>, not the distinct character
- <Control-I>.
-
- Note that CH does not have to be a numeric value, but can be a
- symbol such as `clear' or a list such as `(control backspace)'.
-
- If `event' is not `nil', it is modified; otherwise, a new event
- object is created. In both cases, the event is returned.
-
- Optional third arg DEVICE is the device to store in the event;
- this also affects whether the high bit is interpreted as a meta
- key. A value of `nil' means use the selected device but always
- treat the high bit as meta.
-
- Beware that `character-to-event' and `event-to-character' are not
- strictly inverse functions, since events contain much more
- information than the ASCII character set can encode.
-
- - Function: event-to-character event &optional allow-extra-modifiers
- allow-meta allow-non-ascii
- This function returns the closest ASCII approximation to EVENT.
- If the event isn't a keypress, this returns `nil'.
-
- If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
- translation; it will ignore modifier keys other than <control> and
- <meta>, and will ignore the <shift> modifier on those characters
- which have no shifted ASCII equivalent (<Control-Shift-A> for
- example, will be mapped to the same ASCII code as <Control-A>).
-
- If ALLOW-META is non-`nil', then the <Meta> modifier will be
- represented by turning on the high bit of the byte returned;
- otherwise, `nil' will be returned for events containing the <Meta>
- modifier.
-
- If ALLOW-NON-ASCII is non-`nil', then characters which are present
- in the prevailing character set (*note variable
- `character-set-property': Keymaps.) will be returned as their code
- in that character set, instead of the return value being
- restricted to ASCII.
-
- Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
- ambiguous, as both use the high bit; <M-x> and <oslash> will be
- indistinguishable.
-
- - Function: events-to-keys events &optional no-mice
- Given a vector of event objects, this function returns a vector of
- key descriptors, or a string (if they all fit in the ASCII range).
- Optional arg NO-MICE means that button events are not allowed.
-
-\1f
-File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
-
-Reading Input
-=============
-
- The editor command loop reads keyboard input using the function
-`next-event' and constructs key sequences out of the events using
-`dispatch-event'. Lisp programs can also use the function
-`read-key-sequence', which reads input a key sequence at a time. See
-also `momentary-string-display' in *Note Temporary Displays::, and
-`sit-for' in *Note Waiting::. *Note Terminal Input::, for functions
-and variables for controlling terminal input modes and debugging
-terminal input.
-
- For higher-level input facilities, see *Note Minibuffers::.
-
-* Menu:
-
-* Key Sequence Input:: How to read one key sequence.
-* Reading One Event:: How to read just one event.
-* Dispatching an Event:: What to do with an event once it has been read.
-* Quoted Character Input:: Asking the user to specify a character.
-* Peeking and Discarding:: How to reread or throw away input events.
-
-\1f
-File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
-
-Key Sequence Input
-------------------
-
- Lisp programs can read input a key sequence at a time by calling
-`read-key-sequence'; for example, `describe-key' uses it to read the
-key to describe.
-
- - Function: read-key-sequence prompt
- This function reads a sequence of keystrokes or mouse clicks and
- returns it as a vector of events. It keeps reading events until
- it has accumulated a full key sequence; that is, enough to specify
- a non-prefix command using the currently active keymaps.
-
- The vector and the event objects it contains are freshly created,
- and will not be side-effected by subsequent calls to this function.
-
- The function `read-key-sequence' suppresses quitting: `C-g' typed
- while reading with this function works like any other character,
- and does not set `quit-flag'. *Note Quitting::.
-
- The argument PROMPT is either a string to be displayed in the echo
- area as a prompt, or `nil', meaning not to display a prompt.
-
- If the user selects a menu item while we are prompting for a key
- sequence, the returned value will be a vector of a single
- menu-selection event (a misc-user event). An error will be
- signalled if you pass this value to `lookup-key' or a related
- function.
-
- In the example below, the prompt `?' is displayed in the echo area,
- and the user types `C-x C-f'.
-
- (read-key-sequence "?")
-
- ---------- Echo Area ----------
- ?C-x C-f
- ---------- Echo Area ----------
-
- => [#<keypress-event control-X> #<keypress-event control-F>]
-
- If an input character is an upper-case letter and has no key binding,
-but its lower-case equivalent has one, then `read-key-sequence'
-converts the character to lower case. Note that `lookup-key' does not
-perform case conversion in this way.
-
-\1f
-File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
-
-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 XEmacs
-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
- 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. 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.
-
-\1f
-File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
-
-Dispatching an Event
---------------------
-
- - Function: dispatch-event event
- Given an event object returned by `next-event', this function
- executes it. This is the basic function that makes XEmacs respond
- to user input; it also deals with notifications from the window
- system (such as Expose events).
-
-\1f
-File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
-
-Quoted Character Input
-----------------------
-
- You can use the function `read-quoted-char' to ask the user to
-specify a character, and allow the user to specify a control or meta
-character conveniently, either literally or as an octal character code.
-The command `quoted-insert' uses this function.
-
- - Function: read-quoted-char &optional prompt
- This function is like `read-char', except that if the first
- character read is an octal digit (0-7), it reads up to two more
- octal digits (but stopping if a non-octal digit is found) and
- returns the character represented by those digits in octal.
-
- Quitting is suppressed when the first character is read, so that
- the user can enter a `C-g'. *Note Quitting::.
-
- If PROMPT is supplied, it specifies a string for prompting the
- user. The prompt string is always displayed in the echo area,
- followed by a single `-'.
-
- In the following example, the user types in the octal number 177
- (which is 127 in decimal).
-
- (read-quoted-char "What character")
-
- ---------- Echo Area ----------
- What character-177
- ---------- Echo Area ----------
-
- => 127
-
-\1f
-File: lispref.info, Node: Peeking and Discarding, Prev: Quoted Character Input, Up: Reading Input
-
-Miscellaneous Event Input Features
-----------------------------------
-
- This section describes how to "peek ahead" at events without using
-them up, how to check for pending input, and how to discard pending
-input.
-
- See also the variables `last-command-event' and `last-command-char'
-(*Note Command Loop Info::).
-
- - Variable: unread-command-events
- This variable holds a list of events waiting to be read as command
- input. The events are used in the order they appear in the list,
- and removed one by one as they are used.
-
- The variable is needed because in some cases a function reads a
- event and then decides not to use it. Storing the event in this
- variable causes it to be processed normally, by the command loop
- or by the functions to read command input.
-
- For example, the function that implements numeric prefix arguments
- reads any number of digits. When it finds a non-digit event, it
- must unread the event so that it can be read normally by the
- command loop. Likewise, incremental search uses this feature to
- unread events with no special meaning in a search, because these
- events should exit the search and then execute normally.
-
-
- - Variable: unread-command-event
- This variable holds a single event to be read as command input.
-
- This variable is mostly obsolete now that you can use
- `unread-command-events' instead; it exists only to support programs
- written for versions of XEmacs prior to 19.12.
-
- - Function: input-pending-p
- This function determines whether any command input is currently
- available to be read. It returns immediately, with value `t' if
- there is available input, `nil' otherwise. On rare occasions it
- may return `t' when no input is available.
-
- - Variable: last-input-event
- This variable is set to the last keyboard or mouse button event
- received.
-
- This variable is off limits: you may not set its value or modify
- the event that is its value, as it is destructively modified by
- `read-key-sequence'. If you want to keep a pointer to this value,
- you must use `copy-event'.
-
- Note that this variable is an alias for `last-input-char' in FSF
- Emacs.
-
- In the example below, a character is read (the character `1'). It
- becomes the value of `last-input-event', while `C-e' (from the
- `C-x C-e' command used to evaluate this expression) remains the
- value of `last-command-event'.
-
- (progn (print (next-command-event))
- (print last-command-event)
- last-input-event)
- -| #<keypress-event 1>
- -| #<keypress-event control-E>
- => #<keypress-event 1>
-
- - Variable: last-input-char
- If the value of `last-input-event' is a keyboard event, then this
- is the nearest ASCII equivalent to it. Remember that there is
- _not_ a 1:1 mapping between keyboard events and ASCII characters:
- the set of keyboard events is much larger, so writing code that
- examines this variable to determine what key has been typed is bad
- practice, unless you are certain that it will be one of a small
- set of characters.
-
- This function exists for compatibility with Emacs version 18.
-
- - Function: discard-input
- This function discards the contents of the terminal input buffer
- and cancels any keyboard macro that might be in the process of
- definition. It returns `nil'.
-
- In the following example, the user may type a number of characters
- right after starting the evaluation of the form. After the
- `sleep-for' finishes sleeping, `discard-input' discards any
- characters typed during the sleep.
-
- (progn (sleep-for 2)
- (discard-input))
- => nil