lispref.info: Key Sequences

Keymaps

Prefix Keys

Inheritance and Keymaps

Back to Software Index

Key Sequences
=============

   Contrary to popular belief, the world is not ASCII.  When running
under a window manager, XEmacs 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 XEmacs 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'.