26.5 Key Sequences

Contrary to popular belief, the world is not ASCII. When running under a window manager, SXEmacs can tell the difference between, for example, the keystrokes control-h, control-shift-h, and backspace. You can, in fact, bind different commands to each of these.

A key sequence is a set of keystrokes. A keystroke is a keysym and some set of modifiers (such as CONTROL and META). A keysym is what is printed on the keys on your keyboard.

A keysym may be represented by a symbol, or (if and only if it is equivalent to an ASCII character in the range 32 - 255) by a character or its equivalent ASCII code. The A key may be represented by the symbol A, the character ?A, or by the number 65. The break key may be represented only by the symbol break.

A keystroke may be represented by a list: the last element of the list is the key (a symbol, character, or number, as above) and the preceding elements are the symbolic names of modifier keys (CONTROL, META, SUPER, HYPER, ALT, and SHIFT). Thus, the sequence control-b is represented by the forms (control b), (control ?b), and (control 98). A keystroke may also be represented by an event object, as returned by the next-command-event and read-key-sequence functions.

Note that in this context, the keystroke control-b is not represented by the number 2 (the ASCII code for ‘^B’) or the character ?\^B. See below.

The SHIFT modifier is somewhat of a special case. You should not (and cannot) use (meta shift a) to mean (meta A), since for characters that have ASCII equivalents, the state of the shift key is implicit in the keysym (‘a’ vs. ‘A’). You also cannot say (shift =) to mean +, as that sort of thing varies from keyboard to keyboard. The SHIFT modifier is for use only with characters that do not have a second keysym on the same key, such as backspace and tab.

A key sequence is a vector of keystrokes. As a degenerate case, elements of this vector may also be keysyms if they have no modifiers. That is, the A keystroke is represented by all of these forms:

        A       ?A      65      (A)     (?A)    (65)
        [A]     [?A]    [65]    [(A)]   [(?A)]  [(65)]

the control-a keystroke is represented by these forms:

        (control A)     (control ?A)    (control 65)
        [(control A)]   [(control ?A)]  [(control 65)]

the key sequence control-c control-a is represented by these forms:

        [(control c) (control a)]       [(control ?c) (control ?a)]
        [(control 99) (control 65)]     etc.

Mouse button clicks work just like keypresses: (control button1) means pressing the left mouse button while holding down the control key. [(control c) (shift button3)] means control-c, hold SHIFT, click right.

Commands may be bound to the mouse-button up-stroke rather than the down-stroke as well. button1 means the down-stroke, and button1up means the up-stroke. Different commands may be bound to the up and down strokes, though that is probably not what you want, so be careful.

For backward compatibility, a key sequence may also be represented by a string. In this case, it represents the key sequence(s) that would produce that sequence of ASCII characters in a purely ASCII world. For example, a string containing the ASCII backspace character, "\^H", would represent two key sequences: (control h) and backspace. Binding a command to this will actually bind both of those key sequences. Likewise for the following pairs:

                control h       backspace
                control i       tab
                control m       return
                control j       linefeed
                control [       escape
                control @      control space

After binding a command to two key sequences with a form like

        (define-key global-map "\^X\^I" 'command-1)

it is possible to redefine only one of those sequences like so:

        (define-key global-map [(control x) (control i)] 'command-2)
        (define-key global-map [(control x) tab] 'command-3)

Of course, all of this applies only when running under a window system. If you’re talking to SXEmacs through a TTY connection, you don’t get any of these features.

Function: event-matches-key-specifier-p event key-specifier

This function returns non-nil if event matches key-specifier, which can be any valid form representing a key sequence. This can be useful, e.g., to determine if the user pressed help-char or quit-char.