1 @node Keystrokes, Pull-down Menus, Frame, Top
2 @chapter Keystrokes, Key Sequences, and Key Bindings
5 This chapter discusses the character set Emacs uses for input commands
6 and inside files. You have already learned that the more frequently
7 used Emacs commands are bound to keys. For example, @kbd{Control-f} is
8 bound to @code{forward-char}. The following issues are covered:
12 How keystrokes can be represented
14 How you can create key sequences from keystrokes
16 How you can add to the available modifier keys by customizing your
17 keyboard: for example, you could have the
18 @key{Capslock} key be understood as the @key{Super} key by Emacs. A
19 @key{Super} key is used like @key{Control} or @key{Meta} in that you hold
20 it while typing another key.
23 You will also learn how to customize existing key bindings and
28 * Intro to Keystrokes:: Keystrokes as building blocks of key sequences.
29 * Representing Keystrokes:: Using lists of modifiers and keysyms to
31 * Key Sequences:: Combine key strokes into key sequences you can
33 * String Key Sequences:: Available for upward compatibility.
34 * Meta Key:: Using @key{ESC} to represent @key{Meta}
35 * Super and Hyper Keys:: Adding modifier keys on certain keyboards.
36 * Character Representation:: How characters appear in Emacs buffers.
37 * Commands:: How commands are bound to key sequences.
40 @node Intro to Keystrokes, Representing Keystrokes, Keystrokes, Keystrokes
41 @section Keystrokes as Building Blocks of Key Sequences
46 Earlier versions of Emacs used only the ASCII character set,
47 which defines 128 different character codes. Some of these codes are
48 assigned graphic symbols like @samp{a} and @samp{=}; the rest are
49 control characters, such as @kbd{Control-a} (also called @kbd{C-a}).
50 @kbd{C-a} means you hold down the @key{CTRL} key and then press
53 Keybindings in SXEmacs are not restricted to the set of
54 keystrokes that can be represented in ASCII. SXEmacs can tell the
55 difference between, for example, @kbd{Control-h}, @kbd{Control-Shift-h},
72 A keystroke is like a piano chord: you get it by simultaneously
73 striking several keys. To be more precise, a keystroke consists
74 of a possibly empty set of modifiers followed by a single
75 @dfn{keysym}. The set of modifiers is small; it consists of
76 @kbd{Control}, @kbd{Meta}, @kbd{Super}, @kbd{Hyper}, and @kbd{Shift}.
78 The rest of the keys on your keyboard, along with the mouse buttons,
79 make up the set of keysyms. A keysym is usually what is printed on the
80 keys on your keyboard. Here is a table of some of the symbolic names
94 upstroke on the left mouse button
96 upstroke on the middle mouse button
98 upstroke on the right mouse button
103 @vindex keyboard-translate-table
104 Use the variable @code{keyboard-translate-table} only if you are on a
105 dumb tty, as it cannot handle input that cannot be represented as ASCII.
106 The value of this variable is a string used as a translate table for
107 keyboard input or @code{nil}. Each character is looked up in this
108 string and the contents used instead. If the string is of length
109 @code{n}, character codes @code{N} and up are untranslated. If you are
110 running Emacs under X, you should do the translations with the
111 @code{xmodmap} program instead.
114 @node Representing Keystrokes, Key Sequences, Intro to Keystrokes, Keystrokes
115 @comment node-name, next, previous, up
116 @subsection Representing Keystrokes
119 @findex read-key-sequence
121 SXEmacs represents keystrokes as lists. Each list consists of
122 an arbitrary combination of modifiers followed by a single keysym at the
123 end of the list. If the keysym corresponds to an ASCII character, you
124 can use its character code. (A keystroke may also be represented by an
125 event object, as returned by the @code{read-key-sequence} function;
126 non-programmers need not worry about this.)
128 The following table gives some examples of how to list representations
129 for keystrokes. Each list consists of sets of modifiers followed by
134 Pressing @key{CTRL} and @kbd{a} simultaneously.
136 Another way of writing the keystroke @kbd{C-a}.
138 Yet another way of writing the keystroke @kbd{C-a}.
140 Pressing the @key{BREAK} key.
141 @item (control meta button2up)
142 Release the middle mouse button, while pressing @key{CTRL} and
145 @cindex shift modifier
146 Note: As you define keystrokes, you can use the @kbd{shift} key only
147 as a modifier with characters that do not have a second keysym on the
148 same key, such as @kbd{backspace} and @kbd{tab}. It is an error to
149 define a keystroke using the @key{shift} modifier with keysyms such as
150 @kbd{a} and @kbd{=}. The correct forms are @kbd{A} and @kbd{+}.
152 @node Key Sequences, String Key Sequences, Representing Keystrokes, Keystrokes
153 @subsection Representing Key Sequences
155 A @dfn{complete key sequence} is a sequence of keystrokes that Emacs
156 understands as a unit. Key sequences are significant because you can
157 bind them to commands. Note that not all sequences of keystrokes are
158 possible key sequences. In particular, the initial keystrokes in a key
159 sequence must make up a @dfn{prefix key sequence}.
161 Emacs represents a key sequence as a vector of keystrokes. Thus, the
162 schematic representation of a complete key sequence is as follows:
165 [(modifier .. modifier keysym) ... (modifier .. modifier keysym)]
168 Here are some examples of complete key sequences:
171 @item [(control c) (control a)]
172 Typing @kbd{C-c} followed by @kbd{C-a}
173 @item [(control c) (control 65)]
174 Typing @kbd{C-c} followed by @kbd{C-a}. (Using the ASCII code
175 for the character `a')@refill
176 @item [(control c) (break)]
177 Typing @kbd{C-c} followed by the @kbd{break} character.@refill
184 @cindex prefix key sequence
186 A @dfn{prefix key sequence} is the beginning of a series of longer
187 sequences that are valid key sequences; adding any single keystroke to
188 the end of a prefix results in a valid key sequence. For example,
189 @kbd{control-x} is standardly defined as a prefix. Thus there is a
190 two-character key sequence starting with @kbd{C-x} for each valid
191 keystroke, giving numerous possibilities. Here are some samples:
195 @kbd{[(control x) (c)]}
197 @kbd{[(control x) (control c)]}
200 Adding one character to a prefix key does not have to form a complete
201 key. It could make another, longer prefix. For example, @kbd{[(control
202 x) (\4)]} is itself a prefix that leads to any number of different
203 three-character keys, including @kbd{[(control x) (\4) (f)]},
204 @kbd{[(control x) (\4) (b)]} and so on. It would be possible to define
205 one of those three-character sequences as a prefix, creating a series of
206 four-character keys, but we did not define any of them this way.@refill
208 By contrast, the two-character sequence @kbd{[(control f) (control
209 k)]} is not a key, because the @kbd{(control f)} is a complete key
210 sequence in itself. You cannot give @kbd{[(control f (control k)]} an
211 independent meaning as a command while @kbd{(control f)} is a complete
212 sequence, because Emacs would understand @key{C-f C-k} as two
215 The predefined prefix key sequences in Emacs are @kbd{(control c)},
216 @kbd{(control x)}, @kbd{(control h)}, @kbd{[(control x) (\4)]}, and
217 @kbd{escape}. You can customize Emacs and could make new prefix keys or
218 eliminate the default key sequences. @xref{Key Bindings}. For example,
219 if you redefine @kbd{(control f)} as a prefix, @kbd{[(control f)
220 (control k)]} automatically becomes a valid key sequence (complete,
221 unless you define it as a prefix as well). Conversely, if you remove
222 the prefix definition of @kbd{[(control x) (\4)]}, @kbd{[(control x)
223 (\4) (f)]} (or @kbd{[(control x) (\4) @var{anything}]}) is no longer a
226 Note that the above paragraphs uses \4 instead of simply 4, because \4
227 is the symbol whose name is "4", and plain 4 is the integer 4, which
228 would have been interpreted as the ASCII value. Another way of
229 representing the symbol whose name is "4" is to write ?4, which would be
230 interpreted as the number 52, which is the ASCII code for the character
231 "4". We could therefore actually have written 52 directly, but that is
234 @node String Key Sequences, Meta Key, Key Sequences, Keystrokes
235 @comment node-name, next, previous, up
236 @subsection String Key Sequences
237 For backward compatibility, you may also represent a key sequence using
238 strings. For example, we have the following equivalent representations:
242 @code{[(control c) (control c)]}
244 @code{[(meta control c)]}
250 @node Meta Key, Super and Hyper Keys, String Key Sequences, Keystrokes
251 @comment node-name, next, previous, up
252 @subsection Assignment of the @key{META} Key
256 Not all terminals have the complete set of modifiers.
257 Terminals that have a @key{Meta} key allow you to type Meta characters
258 by just holding that key down. To type @kbd{Meta-a}, hold down
259 @key{META} and press @kbd{a}. On those terminals, the @key{META} key
260 works like the @key{SHIFT} key. Such a key is not always labeled
261 @key{META}, however, as this function is often a special option for a
262 key with some other primary purpose.@refill
264 If there is no @key{META} key, you can still type Meta characters
265 using two-character sequences starting with @key{ESC}. To enter
266 @kbd{M-a}, you could type @kbd{@key{ESC} a}. To enter @kbd{C-M-a}, you
267 would type @kbd{ESC C-a}. @key{ESC} is allowed on terminals with
268 Meta keys, too, in case you have formed a habit of using it.@refill
270 If you are running under X and do not have a @key{META} key, it
271 is possible to reconfigure some other key to be a @key{META}
272 key. @xref{Super and Hyper Keys}. @refill
275 Emacs believes the terminal has a @key{META} key if the variable
276 @code{meta-flag} is non-@code{nil}. Normally this is set automatically
277 according to the termcap entry for your terminal type. However, sometimes
278 the termcap entry is wrong, and then it is useful to set this variable
279 yourself. @xref{Variables}, for how to do this.
281 Note: If you are running under the X window system, the setting of
282 the @code{meta-flag} variable is irrelevant.
284 @node Super and Hyper Keys, Character Representation, Meta Key, Keystrokes
285 @comment node-name, next, previous, up
286 @subsection Assignment of the @key{SUPER} and @key{HYPER} Keys
290 Most keyboards do not, by default, have @key{SUPER} or @key{HYPER}
291 modifier keys. Under X, you can simulate the @key{SUPER} or
292 @key{HYPER} key if you want to bind keys to sequences using @kbd{super}
293 and @kbd{hyper}. You can use the @code{xmodmap} program to do this.
295 For example, to turn your @key{CAPS-LOCK} key into a @key{SUPER} key,
298 Create a file called @code{~/.xmodmap}. In this file, place the lines
301 remove Lock = Caps_Lock
302 keysym Caps_Lock = Super_L
306 The first line says that the key that is currently called @code{Caps_Lock}
307 should no longer behave as a ``lock'' key. The second line says that
308 this should now be called @code{Super_L} instead. The third line says that
309 the key called @code{Super_L} should be a modifier key, which produces the
310 @code{Mod2} modifier.
312 To create a @key{META} or @key{HYPER} key instead of a @key{SUPER} key,
313 replace the word @code{Super} above with @code{Meta} or @code{Hyper}.
315 Just after you start up X, execute the command @code{xmodmap /.xmodmap}.
316 You can add this command to the appropriate initialization file to have
317 the command executed automatically.@refill
319 If you have problems, see the documentation for the @code{xmodmap}
320 program. The X keyboard model is quite complicated, and explaining
321 it is beyond the scope of this manual. However, we reprint the
322 following description from the X Protocol document for your convenience:
327 A list of keysyms is associated with each keycode. If that list
328 (ignoring trailing @code{NoSymbol} entries) is a single keysym @samp{K},
329 then the list is treated as if it were the list
330 @code{``K NoSymbol K NoSymbol''}. If the list (ignoring trailing
331 @code{NoSymbol} entries) is a pair of keysyms @samp{K1 K2}, then the
332 list is treated as if it were the list @code{``K1 K2 K1 K2''}. If the
333 list (ignoring trailing @code{NoSymbol} entries) is a triple of keysyms
334 @samp{K1 K2 K3}, then the list is treated as if it were the list
335 @code{``K1 K2 K3 NoSymbol''}.
337 The first four elements of the list are split into two groups of
338 keysyms. Group 1 contains the first and second keysyms; Group 2 contains
339 third and fourth keysyms. Within each group, if the second element of
340 the group is NoSymbol, then the group should be treated as if the second
341 element were the same as the first element, except when the first
342 element is an alphabetic keysym @samp{K} for which both lowercase and
343 uppercase forms are defined. In that case, the group should be treated
344 as if the first element were the lowercase form of @samp{K} and the second
345 element were the uppercase form of @samp{K}.
347 The standard rules for obtaining a keysym from a KeyPress event make use of
348 only the Group 1 and Group 2 keysyms; no interpretation of other keysyms in
349 the list is given here. (That is, the last four keysyms are unused.)
351 Which group to use is determined by modifier state. Switching between
352 groups is controlled by the keysym named @code{Mode_switch}. Attach that
353 keysym to some keycode and attach that keycode to any one of the
354 modifiers Mod1 through Mod5. This modifier is called the @dfn{group
355 modifier}. For any keycode, Group 1 is used when the group modifier is
356 off, and Group 2 is used when the group modifier is on.
358 Within a group, which keysym to use is also determined by modifier
359 state. The first keysym is used when the @code{Shift} and @code{Lock}
360 modifiers are off. The second keysym is used when the @code{Shift}
361 modifier is on, or when the @code{Lock} modifier is on and the second
362 keysym is uppercase alphabetic, or when the @code{Lock} modifier is on
363 and is interpreted as @code{ShiftLock}. Otherwise, when the @code{Lock}
364 modifier is on and is interpreted as @code{CapsLock}, the state of the
365 @code{Shift} modifier is applied first to select a keysym,
366 but if that keysym is lower-case alphabetic, then the corresponding
367 upper-case keysym is used instead.
369 In addition to the above information on keysyms, we also provide the
370 following description of modifier mapping from the InterClient
371 Communications Conventions Manual:
373 @cindex modifier mapping
375 X11 supports 8 modifier bits, of which 3 are pre-assigned to
376 @code{Shift}, @code{Lock}, and @code{Control}. Each modifier bit is
377 controlled by the state of a set of keys, and these sets are specified
378 in a table accessed by @code{GetModifierMapping()} and
379 @code{SetModifierMapping()}.
381 A client needing to use one of the pre-assigned modifiers should assume
382 that the modifier table has been set up correctly to control these
383 modifiers. The @code{Lock} modifier should be interpreted as @code{Caps
384 Lock} or @code{Shift Lock} according to whether the keycodes in its
385 controlling set include @code{XK_Caps_Lock} or @code{XK_Shift_Lock}.
387 Clients should determine the meaning of a modifier bit from the keysyms
388 being used to control it.
390 A client needing to use an extra modifier, for example @code{Meta}, should:
394 Scan the existing modifier mappings.
398 If it finds a modifier that contains a keycode whose set of keysyms
399 includes @code{XK_Meta_L} or @code{XK_Meta_R}, it should use that
403 If there is no existing modifier controlled by @code{XK_Meta_L} or
404 @code{XK_Meta_R}, it should select an unused modifier bit (one with
405 an empty controlling set) and:
409 If there is a keycode with @code{XL_Meta_L} in its set of keysyms,
410 add that keycode to the set for the chosen modifier, and then:
414 If there is a keycode with @code{XL_Meta_R} in its set of keysyms,
415 add that keycode to the set for the chosen modifier, and then:
418 If the controlling set is still empty, interact with the user to
419 select one or more keys to be @code{Meta}.
424 If there are no unused modifier bits, ask the user to take corrective action.
427 This means that the @code{Mod1} modifier does not necessarily mean
428 @code{Meta}, although some applications (such as twm and emacs 18)
429 assume that. Any of the five unassigned modifier bits could mean
430 @code{Meta}; what matters is that a modifier bit is generated by a
431 keycode which is bound to the keysym @code{Meta_L} or @code{Meta_R}.
433 Therefore, if you want to make a @key{META} key, the right way
434 is to make the keycode in question generate both a @code{Meta} keysym
435 and some previously-unassigned modifier bit.
437 @node Character Representation, Commands, Super and Hyper Keys, Keystrokes
438 @comment node-name, next, previous, up
439 @section Representation of Characters
441 This section briefly discusses how characters are represented in Emacs
442 buffers. @xref{Key Sequences}, for information on representing key
443 sequences to create key bindings.
445 ASCII graphic characters in Emacs buffers are displayed with their
446 graphics. @key{LFD} is the same as a newline character; it is displayed
447 by starting a new line. @key{TAB} is displayed by moving to the next
448 tab stop column (usually every 8 spaces). Other control characters are
449 displayed as a caret (@samp{^}) followed by the non-control version of
450 the character; thus, @kbd{C-a} is displayed as @samp{^A}. Non-ASCII
451 characters 128 and up are displayed with octal escape sequences; thus,
452 character code 243 (octal), also called @kbd{M-#} when used as an input
453 character, is displayed as @samp{\243}.
455 The variable @code{ctl-arrow} may be used to alter this behavior.
458 @node Commands, , Character Representation, Keystrokes
459 @section Keys and Commands
462 @cindex customization
466 This manual is full of passages that tell you what particular keys do.
467 But Emacs does not assign meanings to keys directly. Instead, Emacs
468 assigns meanings to @dfn{functions}, and then gives keys their meanings
469 by @dfn{binding} them to functions.
471 A function is a Lisp object that can be executed as a program. Usually
472 it is a Lisp symbol that has been given a function definition; every
473 symbol has a name, usually made of a few English words separated by
474 dashes, such as @code{next-line} or @code{forward-word}. It also has a
475 @dfn{definition}, which is a Lisp program. Only some functions can be the
476 bindings of keys; these are functions whose definitions use
477 @code{interactive} to specify how to call them interactively. Such
478 functions are called @dfn{commands}, and their names are @dfn{command
479 names}. More information on this subject will appear in the @i{SXEmacs
480 Lisp Reference Manual}.
482 The bindings between keys and functions are recorded in various tables
483 called @dfn{keymaps}. @xref{Key Bindings}, for more information on key
484 sequences you can bind commands to. @xref{Keymaps}, for information on
487 When we say ``@kbd{C-n} moves down vertically one line'' we are
488 glossing over a distinction that is irrelevant in ordinary use but is
489 vital in understanding how to customize Emacs. The function
490 @code{next-line} is programmed to move down vertically. @kbd{C-n}
491 has this effect @i{because} it is bound to that function. If you rebind
492 @kbd{C-n} to the function @code{forward-word} then @kbd{C-n} will move
493 forward by words instead. Rebinding keys is a common method of
494 customization.@refill
496 The rest of this manual usually ignores this subtlety to keep
497 things simple. To give the customizer the information needed, we often
498 state the name of the command that really does the work in parentheses
499 after mentioning the key that runs it. For example, we will say that
500 ``The command @kbd{C-n} (@code{next-line}) moves point vertically
501 down,'' meaning that @code{next-line} is a command that moves vertically
502 down and @kbd{C-n} is a key that is standardly bound to it.
505 While we are on the subject of information for customization only,
506 it's a good time to tell you about @dfn{variables}. Often the
507 description of a command will say, ``To change this, set the variable
508 @code{mumble-foo}.'' A variable is a name used to remember a value.
509 Most of the variables documented in this manual exist just to facilitate
510 customization: some command or other part of Emacs uses the variable
511 and behaves differently depending on its setting. Until you are interested in
512 customizing, you can ignore the information about variables. When you
513 are ready to be interested, read the basic information on variables, and
514 then the information on individual variables will make sense.