---

18.1.2 Interface

All of the following routines and variables are exported from the "EXTENSIONS" ("EXT") package.

Function: define-keysym keysym preferred-name &rest other-names ¶

This function establishes a mapping from preferred-name to keysym for purposes of #k syntax. Other-names also map to keysym, but the system uses preferred-name when printing key-events. The names are case-insensitive simple-strings; however, if the string contains a single character, then it is used case-sensitively. Redefining a keysym or re-using names has undefined effects.

You can use this to define unused keysyms, but primarily this defines keysyms defined in the X Window System Protocol, MIT X Consortium Standard, X Version 11, Release 4. translate-key-event uses this knowledge to determine what keysyms are modifier keysyms and what keysym stand for alphabetic key-events.

Function: define-mouse-keysym button keysym name shifted-bit event-key ¶

This function defines keysym named name for key-events representing the X button cross the X event-key (:button-press or :button-release). Shifted-bit is a defined modifier name that translate-mouse-key-event sets in the key-event it returns whenever the X shift bit is set in an incoming event.

Note, by default, there are distinct keysyms for each button distinguishing whether the user pressed or released the button.

Keysym should be an one unspecified in X Window System Protocol, MIT X Consortium Standard, X Version 11, Release 4.

Function: name-keysym name ¶

This function returns the keysym named name. If name is unknown, this returns nil.

Function: keysym-names keysym ¶

This function returns the list of all names for keysym. If keysym is undefined, this returns nil.

Function: keysym-preferred-name keysym ¶

This returns the preferred name for keysym, how it is typically printed. If keysym is undefined, this returns nil.

Function: define-key-event-modifier long-name short-name ¶

This establishes long-name and short-name as modifier names for purposes of specifying key-events in #k syntax. The names are case-insensitive simple-strings. If either name is already defined, this signals an error.

The system defines the following default modifiers (first the long name, then the short name):

• "Hyper", "H"
• "Super", "S"
• "Meta", "M"
• "Control", "C"
• "Shift", "Shift"
• "Lock", "Lock"

Variable: *all-modifier-names* ¶

This variable holds all the defined modifier names.

Function: define-clx-modifier clx-mask modifier-name ¶

This function establishes a mapping from clx-mask to a defined key-event modifier-name. translate-key-event and translate-mouse-key-event can only return key-events with bits defined by this routine.

The system defines the following default mappings between CLX modifiers and key-event modifiers:

• (xlib:make-state-mask :mod-1) --> "Meta"
• (xlib:make-state-mask :control) --> "Control"
• (xlib:make-state-mask :lock) --> "Lock"
• (xlib:make-state-mask :shift) --> "Shift"

Function: make-key-event-bits &rest modifier-names ¶

This function returns bits suitable for make-key-event from the supplied modifier-names. If any name is undefined, this signals an error.

Function: key-event-modifier-mask modifier-name ¶

This function returns a mask for modifier-name. This mask is suitable for use with key-event-bits. If modifier-name is undefined, this signals an error.

Function: key-event-bits-modifiers bits ¶

This returns a list of key-event modifier names, one for each modifier set in bits.

Function: translate-key-event display scan-code bits ¶

This function translates the X scan-code and X bits to a key-event. First this maps scan-code to an X keysym using xlib:keycode->keysym looking at bits and supplying index as 1 if the X shift bit is on, 0 otherwise.

If the resulting keysym is undefined, and it is not a modifier keysym, then this signals an error. If the keysym is a modifier key, then this returns nil.

If these conditions are satisfied

• The keysym is defined.
• The X shift bit is off.
• The X lock bit is on.
• The X keysym represents a lowercase letter.

then this maps the scan-code again supplying index as 1 this time, treating the X lock bit as a caps-lock bit. If this results in an undefined keysym, this signals an error. Otherwise, this makes a key-event with the keysym and bits formed by mapping the X bits to key-event bits.

Otherwise, this makes a key-event with the keysym and bits formed by mapping the X bits to key-event bits.

Function: translate-mouse-key-event scan-code bits event-key ¶

This function translates the X button code, scan-code, and modifier bits, bits, for the X event-key into a key-event. See define-mouse-keysym.

Function: make-key-event object bits ¶

This function returns a key-event described by object with bits. Object is one of keysym, string, or key-event. When object is a key-event, this uses key-event-keysym. You can form bits with make-key-event-bits or key-event-modifier-mask.

Function: key-event-p object ¶

This function returns whether object is a key-event.

Function: key-event-bits key-event ¶

This function returns the bits field of a key-event.

Function: key-event-keysym key-event ¶

This function returns the keysym field of a key-event.

Function: char-key-event character ¶

This function returns the key-event associated with character. You can associate a key-event with a character by setf’ing this form.

Function: key-event-char key-event ¶

This function returns the character associated with key-event. You can associate a character with a key-event by setf’ing this form. The system defaultly translates key-events in some implementation dependent way for text insertion; for example, under an ASCII system, the key-event #k"C-h", as well as #k"backspace" would map to the Common Lisp character that causes a backspace.

Function: key-event-bit-p key-event bit-name ¶

This function returns whether key-event has the bit set named by bit-name. This signals an error if bit-name is undefined.

Macro: do-alpha-key-events (var kind &optional result) {form}* ¶

This macro evaluates each form with var bound to a key-event representing an alphabetic character. Kind is one of :lower, :upper, or :both, and this binds var to each key-event in order as specified in X Window System Protocol, MIT X Consortium Standard, X Version 11, Release 4. When :both is specified, this processes lowercase letters first.

Function: print-pretty-key key &optional stream long-names-p ¶

This prints key, a key-event or vector of key-events, in a user-expected fashion to stream. Long-names-p indicates whether modifiers should print with their long or short name. Stream defaults to standard-output.

Function: print-pretty-key-event key-event &optional stream long-names-p ¶

This prints key-event to stream in a user-expected fashion. Long-names-p indicates whether modifier names should appear using the long name or short name. Stream defaults to standard-output.