Clozure CL Documentation

6.17. Miscellaneous

This chapter is somewhat of a catch-all for comments and features that don't fit well anywhere else.

6.17.1. Key-events

6.17.1.1. Introduction

The canonical representation of editor input is a key-event structure. Users can bind commands to keys, which are non-empty sequences of key-events. A key-event consists of an identifying token known as a keysym and a field of bits representing modifiers. Users define keysyms by supplying names that reflect the legends on their keyboard's keys. Users define modifier names similarly, but the system chooses the bit and mask for recognizing the modifier. You can use keysym and modifier names to textually specify key-events and Hemlock keys in a #k syntax. The following are some examples:


#k"C-u"
#k"Control-u"
#k"c-m-z"
#k"control-x meta-d"
#k"a"
#k"A"
#k"Linefeed"

This is convenient for use within code and in init files containing bind-key calls.

The #k syntax is delimited by double quotes, but the system parses the contents rather than reading it as a Common Lisp string. Within the double quotes, spaces separate multiple key-events. A single key-event optionally starts with modifier names terminated by hyphens. Modifier names are alphabetic sequences of characters which the system uses case-insensitively. Following modifiers is a keysym name, which is case-insensitive if it consists of multiple characters, but if the name consists of only a single character, then it is case-sensitive.

You can escape special characters --- hyphen, double quote, open angle bracket, close angle bracket, and space --- with a backslash, and you can specify a backslash by using two contiguously. You can use angle brackets to enclose a keysym name with many special characters in it. Between angle brackets appearing in a keysym name position, there are only two special characters, the closing angle bracket and backslash.

6.17.1.2. Interface

[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.

Keysym can be any object, but generally it is either an integer representing the window-system code for the event, or a keyword which allows the mapping of the keysym to its code to be defined separately.

[Function]


                            define-keysym-code keysym code

Defines the window-system code for the key event which in Hemlock is represented by keysym.

[Function]


                            define-mouse-keysym  	button keysym name shifted-bit event-key

This function defines keysym named name for key-events representing mouse click events. Shifted-bit is a defined modifier name that translate-mouse-key-event sets in the key-event it returns whenever the shift bit is set in an incoming event.

[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 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]


                            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]


                            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 a-z A-Z. When :both is specified, this processes lowercase letters first.

[Function]


                            pretty-key-string  	key &optional stream long-names-p

This returns a string representing key, a key-event or vector of key-events, in a user-expected fashion. Long-names-p indicates whether modifiers should be described by their long or short name.