25.5.7 Converting Events

SXEmacs 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 key-description &optional event console use-console-meta-flag

This function converts a keystroke description to an event structure. key-description is the specification of a key stroke, 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: key-description can be an integer, a character, a symbol such as clear or a list such as (control backspace).

If optional arg event is non-nil, it is modified; otherwise, a new event object is created. In both cases, the event is returned.

Optional third arg console is the console to store in the event, and defaults to the selected console.

If key-description is an integer or character, the high bit may be interpreted as the meta key. (This is done for backward compatibility in lots of places.) If use-console-meta-flag is nil, this will always be the case. If use-console-meta-flag is non-nil, the meta flag for console affects whether the high bit is interpreted as a meta key. (See set-input-mode.) If you don’t want this silly meta interpretation done, you should pass in a list containing the character.

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 (see variable character-set-property) will be returned as their code in that character set, instead of the return value being restricted to ASCII.

Note: 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.