Mercurial > hg > xemacs-beta

comparison man/xemacs/keystrokes.texi @ 0:376386a54a3c r19-14

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