typo
[emacs.git] / lispref / keymaps.texi
blobe5adfb07b46dedb85817a5cd7a88e1fdf312eb5e
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000
4 @c   Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/keymaps
7 @node Keymaps, Modes, Command Loop, Top
8 @chapter Keymaps
9 @cindex keymap
11   The bindings between input events and commands are recorded in data
12 structures called @dfn{keymaps}.  Each binding in a keymap associates
13 (or @dfn{binds}) an individual event type either to another keymap or to
14 a command.  When an event type is bound to a keymap, that keymap is used
15 to look up the next input event; this continues until a command is
16 found.  The whole process is called @dfn{key lookup}.
18 @menu
19 * Keymap Terminology::          Definitions of terms pertaining to keymaps.
20 * Format of Keymaps::           What a keymap looks like as a Lisp object.
21 * Creating Keymaps::            Functions to create and copy keymaps.
22 * Inheritance and Keymaps::     How one keymap can inherit the bindings
23                                    of another keymap.
24 * Prefix Keys::                 Defining a key with a keymap as its definition.
25 * Active Keymaps::              Each buffer has a local keymap
26                                    to override the standard (global) bindings.
27                                    A minor mode can also override them.
28 * Key Lookup::                  How extracting elements from keymaps works.
29 * Functions for Key Lookup::    How to request key lookup.
30 * Changing Key Bindings::       Redefining a key in a keymap.
31 * Key Binding Commands::        Interactive interfaces for redefining keys.
32 * Scanning Keymaps::            Looking through all keymaps, for printing help.
33 * Menu Keymaps::                Defining a menu as a keymap.
34 @end menu
36 @node Keymap Terminology
37 @section Keymap Terminology
38 @cindex key
39 @cindex keystroke
40 @cindex key binding
41 @cindex binding of a key
42 @cindex complete key
43 @cindex undefined key
45   A @dfn{keymap} is a table mapping event types to definitions (which
46 can be any Lisp objects, though only certain types are meaningful for
47 execution by the command loop).  Given an event (or an event type) and a
48 keymap, Emacs can get the event's definition.  Events include
49 characters, function keys, and mouse actions (@pxref{Input Events}).
51   A sequence of input events that form a unit is called a
52 @dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
53 is always a key sequence, and so are some multi-event sequences.
55   A keymap determines a binding or definition for any key sequence.  If
56 the key sequence is a single event, its binding is the definition of the
57 event in the keymap.  The binding of a key sequence of more than one
58 event is found by an iterative process: the binding of the first event
59 is found, and must be a keymap; then the second event's binding is found
60 in that keymap, and so on until all the events in the key sequence are
61 used up.
63   If the binding of a key sequence is a keymap, we call the key sequence
64 a @dfn{prefix key}.  Otherwise, we call it a @dfn{complete key} (because
65 no more events can be added to it).  If the binding is @code{nil},
66 we call the key @dfn{undefined}.  Examples of prefix keys are @kbd{C-c},
67 @kbd{C-x}, and @kbd{C-x 4}.  Examples of defined complete keys are
68 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}.  Examples of undefined complete
69 keys are @kbd{C-x C-g}, and @kbd{C-c 3}.  @xref{Prefix Keys}, for more
70 details.
72   The rule for finding the binding of a key sequence assumes that the
73 intermediate bindings (found for the events before the last) are all
74 keymaps; if this is not so, the sequence of events does not form a
75 unit---it is not really one key sequence.  In other words, removing one
76 or more events from the end of any valid key sequence must always yield
77 a prefix key.  For example, @kbd{C-f C-n} is not a key sequence;
78 @kbd{C-f} is not a prefix key, so a longer sequence starting with
79 @kbd{C-f} cannot be a key sequence.
81   The set of possible multi-event key sequences depends on the bindings
82 for prefix keys; therefore, it can be different for different keymaps,
83 and can change when bindings are changed.  However, a one-event sequence
84 is always a key sequence, because it does not depend on any prefix keys
85 for its well-formedness.
87   At any time, several primary keymaps are @dfn{active}---that is, in
88 use for finding key bindings.  These are the @dfn{global map}, which is
89 shared by all buffers; the @dfn{local keymap}, which is usually
90 associated with a specific major mode; and zero or more @dfn{minor mode
91 keymaps}, which belong to currently enabled minor modes.  (Not all minor
92 modes have keymaps.)  The local keymap bindings shadow (i.e., take
93 precedence over) the corresponding global bindings.  The minor mode
94 keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
95 for details.
97 @node Format of Keymaps
98 @section Format of Keymaps
99 @cindex format of keymaps
100 @cindex keymap format
101 @cindex full keymap
102 @cindex sparse keymap
104   A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
105 remaining elements of the list define the key bindings of the keymap.
106 A symbol whose function definition is a keymap is also a keymap.  Use
107 the function @code{keymapp} (see below) to test whether an object is a
108 keymap.
110   Several kinds of elements may appear in a keymap, after the symbol
111 @code{keymap} that begins it:
113 @table @code
114 @item (@var{type} .@: @var{binding})
115 This specifies one binding, for events of type @var{type}.  Each
116 ordinary binding applies to events of a particular @dfn{event type},
117 which is always a character or a symbol.  @xref{Classifying Events}.
119 @item (t .@: @var{binding})
120 @cindex default key binding
121 This specifies a @dfn{default key binding}; any event not bound by other
122 elements of the keymap is given @var{binding} as its binding.  Default
123 bindings allow a keymap to bind all possible event types without having
124 to enumerate all of them.  A keymap that has a default binding
125 completely masks any lower-precedence keymap.
127 @item @var{vector}
128 If an element of a keymap is a vector, the vector counts as bindings for
129 all the @sc{ascii} characters, codes 0 through 127; vector element
130 @var{n} is the binding for the character with code @var{n}.  This is a
131 compact way to record lots of bindings.  A keymap with such a vector is
132 called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
133 keymaps}.
135 A @code{nil} binding is used to mean that a key is explicitly not bound.
136 Just like any other binding, it takes precedence over a default binding
137 or a binding in the parent keymap, but on the other hand, it does not
138 take precedence over keymaps of lower priority.
140 When a keymap contains a vector, it always defines a binding for each
141 @sc{ascii} character, even if the vector contains @code{nil} for that
142 character.  Such a binding of @code{nil} overrides any default key
143 binding in the keymap, for @sc{ascii} characters.  However, default
144 bindings are still meaningful for events other than @sc{ascii}
145 characters.  A binding of @code{nil} does @emph{not} override
146 lower-precedence keymaps; thus, if the local map gives a binding of
147 @code{nil}, Emacs uses the binding from the global map.
149 @item @var{string}
150 @cindex keymap prompt string
151 @cindex overall prompt string
152 @cindex prompt string of keymap
153 Aside from bindings, a keymap can also have a string as an element.
154 This is called the @dfn{overall prompt string} and makes it possible to
155 use the keymap as a menu.  @xref{Defining Menus}.
156 @end table
158 @cindex meta characters lookup
159   Keymaps do not directly record bindings for the meta characters.
160 Instead, meta characters are regarded for purposes of key lookup as
161 sequences of two characters, the first of which is @key{ESC} (or
162 whatever is currently the value of @code{meta-prefix-char}).  Thus, the
163 key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
164 global binding is found at the slot for @kbd{a} in @code{esc-map}
165 (@pxref{Prefix Keys}).
167   This conversion applies only to characters, not to function keys or
168 other input events; thus, @kbd{M-@key{end}} has nothing to do with
169 @kbd{@key{ESC} @key{end}}.
171   Here as an example is the local keymap for Lisp mode, a sparse
172 keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
173 C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
175 @example
176 @group
177 lisp-mode-map
178 @result{}
179 @end group
180 @group
181 (keymap
182  ;; @key{TAB}
183  (9 . lisp-indent-line)
184 @end group
185 @group
186  ;; @key{DEL}
187  (127 . backward-delete-char-untabify)
188 @end group
189 @group
190  (3 keymap
191     ;; @kbd{C-c C-l}
192     (12 . run-lisp))
193 @end group
194 @group
195  (27 keymap
196      ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
197      (17 . indent-sexp)
198      ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
199      (24 . lisp-send-defun)))
200 @end group
201 @end example
203 @defun keymapp object
204 This function returns @code{t} if @var{object} is a keymap, @code{nil}
205 otherwise.  More precisely, this function tests for a list whose
206 @sc{car} is @code{keymap}, or for a symbol whose function definition
207 satisfies @code{keymapp}.
209 @example
210 @group
211 (keymapp '(keymap))
212     @result{} t
213 @end group
214 @group
215 (fset 'foo '(keymap))
216 (keymapp 'foo)
217     @result{} t
218 @end group
219 @group
220 (keymapp (current-global-map))
221     @result{} t
222 @end group
223 @end example
224 @end defun
226 @node Creating Keymaps
227 @section Creating Keymaps
228 @cindex creating keymaps
230   Here we describe the functions for creating keymaps.
232 @c ??? This should come after make-sparse-keymap
233 @defun make-keymap &optional prompt
234 This function creates and returns a new full keymap.  That keymap
235 contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
236 128 slots are for defining all the @sc{ascii} characters, the next 128
237 slots are for 8-bit European characters, and each one of the final 128
238 slots is for one character set of non-@sc{ascii} characters supported by
239 Emacs.  The new keymap initially binds all these characters to
240 @code{nil}, and does not bind any other kind of event.
242 @example
243 @group
244 (make-keymap)
245     @result{} (keymap [nil nil nil @dots{} nil nil])
246 @end group
247 @end example
249 If you specify @var{prompt}, that becomes the overall prompt string for
250 the keymap.  The prompt string should be provided for menu keymaps
251 (@pxref{Defining Menus}).
252 @end defun
254 @defun make-sparse-keymap &optional prompt
255 This function creates and returns a new sparse keymap with no entries.
256 The new keymap does not contain a char-table, unlike @code{make-keymap},
257 and does not bind any events.  The argument @var{prompt} specifies a
258 prompt string, as in @code{make-keymap}.
260 @example
261 @group
262 (make-sparse-keymap)
263     @result{} (keymap)
264 @end group
265 @end example
266 @end defun
268 @defun copy-keymap keymap
269 This function returns a copy of @var{keymap}.  Any keymaps that
270 appear directly as bindings in @var{keymap} are also copied recursively,
271 and so on to any number of levels.  However, recursive copying does not
272 take place when the definition of a character is a symbol whose function
273 definition is a keymap; the same symbol appears in the new copy.
274 @c Emacs 19 feature
276 @example
277 @group
278 (setq map (copy-keymap (current-local-map)))
279 @result{} (keymap
280 @end group
281 @group
282      ;; @r{(This implements meta characters.)}
283      (27 keymap
284          (83 . center-paragraph)
285          (115 . center-line))
286      (9 . tab-to-tab-stop))
287 @end group
289 @group
290 (eq map (current-local-map))
291     @result{} nil
292 @end group
293 @group
294 (equal map (current-local-map))
295     @result{} t
296 @end group
297 @end example
298 @end defun
300 @node Inheritance and Keymaps
301 @section Inheritance and Keymaps
302 @cindex keymap inheritance
303 @cindex inheriting a keymap's bindings
305   A keymap can inherit the bindings of another keymap, which we call the
306 @dfn{parent keymap}.  Such a keymap looks like this:
308 @example
309 (keymap @var{bindings}@dots{} . @var{parent-keymap})
310 @end example
312 @noindent
313 The effect is that this keymap inherits all the bindings of
314 @var{parent-keymap}, whatever they may be at the time a key is looked up,
315 but can add to them or override them with @var{bindings}.
317 If you change the bindings in @var{parent-keymap} using @code{define-key}
318 or other key-binding functions, these changes are visible in the
319 inheriting keymap unless shadowed by @var{bindings}.  The converse is
320 not true: if you use @code{define-key} to change the inheriting keymap,
321 that affects @var{bindings}, but has no effect on @var{parent-keymap}.
323 The proper way to construct a keymap with a parent is to use
324 @code{set-keymap-parent}; if you have code that directly constructs a
325 keymap with a parent, please convert the program to use
326 @code{set-keymap-parent} instead.
328 @defun keymap-parent keymap
329 This returns the parent keymap of @var{keymap}.  If @var{keymap}
330 has no parent, @code{keymap-parent} returns @code{nil}.
331 @end defun
333 @defun set-keymap-parent keymap parent
334 This sets the parent keymap of @var{keymap} to @var{parent}, and returns
335 @var{parent}.  If @var{parent} is @code{nil}, this function gives
336 @var{keymap} no parent at all.
338 If @var{keymap} has submaps (bindings for prefix keys), they too receive
339 new parent keymaps that reflect what @var{parent} specifies for those
340 prefix keys.
341 @end defun
343    Here is an example showing how to make a keymap that inherits
344 from @code{text-mode-map}:
346 @example
347 (let ((map (make-sparse-keymap)))
348   (set-keymap-parent map text-mode-map)
349   map)
350 @end example
352   A non-sparse keymap can have a parent too, but this is not very
353 useful.  A non-sparse keymap always specifies something as the binding
354 for every numeric character code without modifier bits, even if it is
355 @code{nil}, so these character's bindings are never inherited from
356 the parent keymap.
358 @node Prefix Keys
359 @section Prefix Keys
360 @cindex prefix key
362   A @dfn{prefix key} is a key sequence whose binding is a keymap.  The
363 keymap defines what to do with key sequences that extend the prefix key.
364 For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
365 also stored in the variable @code{ctl-x-map}.  This keymap defines
366 bindings for key sequences starting with @kbd{C-x}.
368   Some of the standard Emacs prefix keys use keymaps that are
369 also found in Lisp variables:
371 @itemize @bullet
372 @item
373 @vindex esc-map
374 @findex ESC-prefix
375 @code{esc-map} is the global keymap for the @key{ESC} prefix key.  Thus,
376 the global definitions of all meta characters are actually found here.
377 This map is also the function definition of @code{ESC-prefix}.
379 @item
380 @cindex @kbd{C-h}
381 @code{help-map} is the global keymap for the @kbd{C-h} prefix key.
383 @item
384 @cindex @kbd{C-c}
385 @vindex mode-specific-map
386 @code{mode-specific-map} is the global keymap for the prefix key
387 @kbd{C-c}.  This map is actually global, not mode-specific, but its name
388 provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
389 (@code{display-bindings}), since the main use of this prefix key is for
390 mode-specific bindings.
392 @item
393 @cindex @kbd{C-x}
394 @vindex ctl-x-map
395 @findex Control-X-prefix
396 @code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
397 This map is found via the function cell of the symbol
398 @code{Control-X-prefix}.
400 @item
401 @cindex @kbd{C-x @key{RET}}
402 @vindex mule-keymap
403 @code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
404 prefix key.
406 @item
407 @cindex @kbd{C-x 4}
408 @vindex ctl-x-4-map
409 @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
410 key.
412 @c Emacs 19 feature
413 @item
414 @cindex @kbd{C-x 5}
415 @vindex ctl-x-5-map
416 @code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
417 key.
419 @c Emacs 19 feature
420 @item
421 @cindex @kbd{C-x 6}
422 @vindex 2C-mode-map
423 @code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
424 key.
426 @item
427 @cindex @kbd{C-x v}
428 @vindex vc-prefix-map
429 @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
430 key.
432 @item
433 @cindex @kbd{M-g}
434 @vindex facemenu-keymap
435 @code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
436 prefix key.
438 @c Emacs 19 feature
439 @item
440 The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
441 @key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps that have no
442 special names.
443 @end itemize
445   The keymap binding of a prefix key is used for looking up the event
446 that follows the prefix key.  (It may instead be a symbol whose function
447 definition is a keymap.  The effect is the same, but the symbol serves
448 as a name for the prefix key.)  Thus, the binding of @kbd{C-x} is the
449 symbol @code{Control-X-prefix}, whose function cell holds the keymap
450 for @kbd{C-x} commands.  (The same keymap is also the value of
451 @code{ctl-x-map}.)
453   Prefix key definitions can appear in any active keymap.  The
454 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
455 keys appear in the global map, so these prefix keys are always
456 available.  Major and minor modes can redefine a key as a prefix by
457 putting a prefix key definition for it in the local map or the minor
458 mode's map.  @xref{Active Keymaps}.
460   If a key is defined as a prefix in more than one active map, then its
461 various definitions are in effect merged: the commands defined in the
462 minor mode keymaps come first, followed by those in the local map's
463 prefix definition, and then by those from the global map.
465   In the following example, we make @kbd{C-p} a prefix key in the local
466 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
467 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
468 like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
469 active keymap.
471 @example
472 @group
473 (use-local-map (make-sparse-keymap))
474     @result{} nil
475 @end group
476 @group
477 (local-set-key "\C-p" ctl-x-map)
478     @result{} nil
479 @end group
480 @group
481 (key-binding "\C-p\C-f")
482     @result{} find-file
483 @end group
485 @group
486 (key-binding "\C-p6")
487     @result{} nil
488 @end group
489 @end example
491 @defun define-prefix-command symbol &optional mapvar prompt
492 @cindex prefix command
493 This function prepares @var{symbol} for use as a prefix key's binding:
494 it creates a sparse keymap and stores it as @var{symbol}'s function
495 definition.  Subsequently binding a key sequence to @var{symbol} will
496 make that key sequence into a prefix key.  The return value is @code{symbol}.
498 This function also sets @var{symbol} as a variable, with the keymap as
499 its value.  But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
500 as a variable instead.
502 If @var{prompt} is non-@code{nil}, that becomes the overall prompt
503 string for the keymap.  The prompt string should be given for menu keymaps
504 (@pxref{Defining Menus}).
505 @end defun
507 @node Active Keymaps
508 @section Active Keymaps
509 @cindex active keymap
510 @cindex global keymap
511 @cindex local keymap
513   Emacs normally contains many keymaps; at any given time, just a few of
514 them are @dfn{active} in that they participate in the interpretation
515 of user input.  These are the global keymap, the current buffer's
516 local keymap, and the keymaps of any enabled minor modes.
518   The @dfn{global keymap} holds the bindings of keys that are defined
519 regardless of the current buffer, such as @kbd{C-f}.  The variable
520 @code{global-map} holds this keymap, which is always active.
522   Each buffer may have another keymap, its @dfn{local keymap}, which may
523 contain new or overriding definitions for keys.  The current buffer's
524 local keymap is always active except when @code{overriding-local-map}
525 overrides it.  Text properties can specify an alternative local map for
526 certain parts of the buffer; see @ref{Special Properties}.
528   Each minor mode can have a keymap; if it does, the keymap is active
529 when the minor mode is enabled.
531   The variable @code{overriding-local-map}, if non-@code{nil}, specifies
532 another local keymap that overrides the buffer's local map and all the
533 minor mode keymaps.
535   All the active keymaps are used together to determine what command to
536 execute when a key is entered.  Emacs searches these maps one by one, in
537 order of decreasing precedence, until it finds a binding in one of the
538 maps.  The procedure for searching a single keymap is called @dfn{key
539 lookup}; see @ref{Key Lookup}.
541   Normally, Emacs first searches for the key in the minor mode maps, in
542 the order specified by @code{minor-mode-map-alist}; if they do not
543 supply a binding for the key, Emacs searches the local map; if that too
544 has no binding, Emacs then searches the global map.  However, if
545 @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
546 first, before the global map.
548 @cindex major mode keymap
549   Since every buffer that uses the same major mode normally uses the
550 same local keymap, you can think of the keymap as local to the mode.  A
551 change to the local keymap of a buffer (using @code{local-set-key}, for
552 example) is seen also in the other buffers that share that keymap.
554   The local keymaps that are used for Lisp mode and some other major
555 modes exist even if they have not yet been used.  These local maps are
556 the values of variables such as @code{lisp-mode-map}.  For most major
557 modes, which are less frequently used, the local keymap is constructed
558 only when the mode is used for the first time in a session.
560   The minibuffer has local keymaps, too; they contain various completion
561 and exit commands.  @xref{Intro to Minibuffers}.
563   Emacs has other keymaps that are used in a different way---translating
564 events within @code{read-key-sequence}.  @xref{Translating Input}.
566   @xref{Standard Keymaps}, for a list of standard keymaps.
568 @defvar global-map
569 This variable contains the default global keymap that maps Emacs
570 keyboard input to commands.  The global keymap is normally this keymap.
571 The default global keymap is a full keymap that binds
572 @code{self-insert-command} to all of the printing characters.
574 It is normal practice to change the bindings in the global map, but you
575 should not assign this variable any value other than the keymap it starts
576 out with.
577 @end defvar
579 @defun current-global-map
580 This function returns the current global keymap.  This is the
581 same as the value of @code{global-map} unless you change one or the
582 other.
584 @example
585 @group
586 (current-global-map)
587 @result{} (keymap [set-mark-command beginning-of-line @dots{}
588             delete-backward-char])
589 @end group
590 @end example
591 @end defun
593 @defun current-local-map
594 This function returns the current buffer's local keymap, or @code{nil}
595 if it has none.  In the following example, the keymap for the
596 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
597 in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
598 keymap.
600 @example
601 @group
602 (current-local-map)
603 @result{} (keymap
604     (10 . eval-print-last-sexp)
605     (9 . lisp-indent-line)
606     (127 . backward-delete-char-untabify)
607 @end group
608 @group
609     (27 keymap
610         (24 . eval-defun)
611         (17 . indent-sexp)))
612 @end group
613 @end example
614 @end defun
616 @defun current-minor-mode-maps
617 This function returns a list of the keymaps of currently enabled minor modes.
618 @end defun
620 @defun use-global-map keymap
621 This function makes @var{keymap} the new current global keymap.  It
622 returns @code{nil}.
624 It is very unusual to change the global keymap.
625 @end defun
627 @defun use-local-map keymap
628 This function makes @var{keymap} the new local keymap of the current
629 buffer.  If @var{keymap} is @code{nil}, then the buffer has no local
630 keymap.  @code{use-local-map} returns @code{nil}.  Most major mode
631 commands use this function.
632 @end defun
634 @c Emacs 19 feature
635 @defvar minor-mode-map-alist
636 This variable is an alist describing keymaps that may or may not be
637 active according to the values of certain variables.  Its elements look
638 like this:
640 @example
641 (@var{variable} . @var{keymap})
642 @end example
644 The keymap @var{keymap} is active whenever @var{variable} has a
645 non-@code{nil} value.  Typically @var{variable} is the variable that
646 enables or disables a minor mode.  @xref{Keymaps and Minor Modes}.
648 Note that elements of @code{minor-mode-map-alist} do not have the same
649 structure as elements of @code{minor-mode-alist}.  The map must be the
650 @sc{cdr} of the element; a list with the map as the second element will
651 not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
652 function definition is a keymap.
654 When more than one minor mode keymap is active, their order of priority
655 is the order of @code{minor-mode-map-alist}.  But you should design
656 minor modes so that they don't interfere with each other.  If you do
657 this properly, the order will not matter.
659 See @ref{Keymaps and Minor Modes}, for more information about minor
660 modes.  See also @code{minor-mode-key-binding} (@pxref{Functions for Key
661 Lookup}).
662 @end defvar
664 @defvar minor-mode-overriding-map-alist
665 This variable allows major modes to override the key bindings for
666 particular minor modes.  The elements of this alist look like the
667 elements of @code{minor-mode-map-alist}: @code{(@var{variable}
668 . @var{keymap})}.
670 If a variable appears as an element of
671 @code{minor-mode-overriding-map-alist}, the map specified by that
672 element totally replaces any map specified for the same variable in
673 @code{minor-mode-map-alist}.
675 @code{minor-mode-overriding-map-alist} is automatically buffer-local in
676 all buffers.
677 @end defvar
679 @defvar overriding-local-map
680 If non-@code{nil}, this variable holds a keymap to use instead of the
681 buffer's local keymap and instead of all the minor mode keymaps.  This
682 keymap, if any, overrides all other maps that would have been active,
683 except for the current global map.
684 @end defvar
686 @defvar overriding-terminal-local-map
687 If non-@code{nil}, this variable holds a keymap to use instead of
688 @code{overriding-local-map}, the buffer's local keymap and all the minor
689 mode keymaps.
691 This variable is always local to the current terminal and cannot be
692 buffer-local.  @xref{Multiple Displays}.  It is used to implement
693 incremental search mode.
694 @end defvar
696 @defvar overriding-local-map-menu-flag
697 If this variable is non-@code{nil}, the value of
698 @code{overriding-local-map} or @code{overriding-terminal-local-map} can
699 affect the display of the menu bar.  The default value is @code{nil}, so
700 those map variables have no effect on the menu bar.
702 Note that these two map variables do affect the execution of key
703 sequences entered using the menu bar, even if they do not affect the
704 menu bar display.  So if a menu bar key sequence comes in, you should
705 clear the variables before looking up and executing that key sequence.
706 Modes that use the variables would typically do this anyway; normally
707 they respond to events that they do not handle by ``unreading'' them and
708 exiting.
709 @end defvar
711 @defvar special-event-map
712 This variable holds a keymap for special events.  If an event type has a
713 binding in this keymap, then it is special, and the binding for the
714 event is run directly by @code{read-event}.  @xref{Special Events}.
715 @end defvar
717 @node Key Lookup
718 @section Key Lookup
719 @cindex key lookup
720 @cindex keymap entry
722   @dfn{Key lookup} is the process of finding the binding of a key
723 sequence from a given keymap.  Actual execution of the binding is not
724 part of key lookup.
726   Key lookup uses just the event type of each event in the key sequence;
727 the rest of the event is ignored.  In fact, a key sequence used for key
728 lookup may designate mouse events with just their types (symbols)
729 instead of with entire mouse events (lists).  @xref{Input Events}.  Such
730 a ``key-sequence'' is insufficient for @code{command-execute} to run,
731 but it is sufficient for looking up or rebinding a key.
733   When the key sequence consists of multiple events, key lookup
734 processes the events sequentially: the binding of the first event is
735 found, and must be a keymap; then the second event's binding is found in
736 that keymap, and so on until all the events in the key sequence are used
737 up.  (The binding thus found for the last event may or may not be a
738 keymap.)  Thus, the process of key lookup is defined in terms of a
739 simpler process for looking up a single event in a keymap.  How that is
740 done depends on the type of object associated with the event in that
741 keymap.
743   Let's use the term @dfn{keymap entry} to describe the value found by
744 looking up an event type in a keymap.  (This doesn't include the item
745 string and other extra elements in menu key bindings, because
746 @code{lookup-key} and other key lookup functions don't include them in
747 the returned value.)  While any Lisp object may be stored in a keymap as
748 a keymap entry, not all make sense for key lookup.  Here is a table of
749 the meaningful kinds of keymap entries:
751 @table @asis
752 @item @code{nil}
753 @cindex @code{nil} in keymap
754 @code{nil} means that the events used so far in the lookup form an
755 undefined key.  When a keymap fails to mention an event type at all, and
756 has no default binding, that is equivalent to a binding of @code{nil}
757 for that event type.
759 @item @var{command}
760 @cindex command in keymap
761 The events used so far in the lookup form a complete key,
762 and @var{command} is its binding.  @xref{What Is a Function}.
764 @item @var{array}
765 @cindex string in keymap
766 The array (either a string or a vector) is a keyboard macro.  The events
767 used so far in the lookup form a complete key, and the array is its
768 binding.  See @ref{Keyboard Macros}, for more information.
770 @item @var{keymap}
771 @cindex keymap in keymap
772 The events used so far in the lookup form a prefix key.  The next
773 event of the key sequence is looked up in @var{keymap}.
775 @item @var{list}
776 @cindex list in keymap
777 The meaning of a list depends on the types of the elements of the list.
779 @itemize @bullet
780 @item
781 If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
782 is a keymap, and is treated as a keymap (see above).
784 @item
785 @cindex @code{lambda} in keymap
786 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
787 lambda expression.  This is presumed to be a command, and is treated as
788 such (see above).
790 @item
791 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
792 type, then this is an @dfn{indirect entry}:
794 @example
795 (@var{othermap} . @var{othertype})
796 @end example
798 When key lookup encounters an indirect entry, it looks up instead the
799 binding of @var{othertype} in @var{othermap} and uses that.
801 This feature permits you to define one key as an alias for another key.
802 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
803 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
804 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
805 @end itemize
807 @item @var{symbol}
808 @cindex symbol in keymap
809 The function definition of @var{symbol} is used in place of
810 @var{symbol}.  If that too is a symbol, then this process is repeated,
811 any number of times.  Ultimately this should lead to an object that is
812 a keymap, a command, or a keyboard macro.  A list is allowed if it is a
813 keymap or a command, but indirect entries are not understood when found
814 via symbols.
816 Note that keymaps and keyboard macros (strings and vectors) are not
817 valid functions, so a symbol with a keymap, string, or vector as its
818 function definition is invalid as a function.  It is, however, valid as
819 a key binding.  If the definition is a keyboard macro, then the symbol
820 is also valid as an argument to @code{command-execute}
821 (@pxref{Interactive Call}).
823 @cindex @code{undefined} in keymap
824 The symbol @code{undefined} is worth special mention: it means to treat
825 the key as undefined.  Strictly speaking, the key is defined, and its
826 binding is the command @code{undefined}; but that command does the same
827 thing that is done automatically for an undefined key: it rings the bell
828 (by calling @code{ding}) but does not signal an error.
830 @cindex preventing prefix key
831 @code{undefined} is used in local keymaps to override a global key
832 binding and make the key ``undefined'' locally.  A local binding of
833 @code{nil} would fail to do this because it would not override the
834 global binding.
836 @item @var{anything else}
837 If any other type of object is found, the events used so far in the
838 lookup form a complete key, and the object is its binding, but the
839 binding is not executable as a command.
840 @end table
842   In short, a keymap entry may be a keymap, a command, a keyboard macro,
843 a symbol that leads to one of them, or an indirection or @code{nil}.
844 Here is an example of a sparse keymap with two characters bound to
845 commands and one bound to another keymap.  This map is the normal value
846 of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
847 127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
848 @kbd{C-x}.
850 @example
851 @group
852 (keymap (9 . lisp-indent-line)
853         (127 . backward-delete-char-untabify)
854         (27 keymap (17 . indent-sexp) (24 . eval-defun)))
855 @end group
856 @end example
858 @node Functions for Key Lookup
859 @section Functions for Key Lookup
861   Here are the functions and variables pertaining to key lookup.
863 @defun lookup-key keymap key &optional accept-defaults
864 This function returns the definition of @var{key} in @var{keymap}.  All
865 the other functions described in this chapter that look up keys use
866 @code{lookup-key}.  Here are examples:
868 @example
869 @group
870 (lookup-key (current-global-map) "\C-x\C-f")
871     @result{} find-file
872 @end group
873 @group
874 (lookup-key (current-global-map) "\C-x\C-f12345")
875     @result{} 2
876 @end group
877 @end example
879 If the string or vector @var{key} is not a valid key sequence according
880 to the prefix keys specified in @var{keymap}, it must be ``too long''
881 and have extra events at the end that do not fit into a single key
882 sequence.  Then the value is a number, the number of events at the front
883 of @var{key} that compose a complete key.
885 @c Emacs 19 feature
886 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
887 considers default bindings as well as bindings for the specific events
888 in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
889 the specific sequence @var{key}, ignoring default bindings except when
890 you explicitly ask about them.  (To do this, supply @code{t} as an
891 element of @var{key}; see @ref{Format of Keymaps}.)
893 If @var{key} contains a meta character (not a function key), that
894 character is implicitly replaced by a two-character sequence: the value
895 of @code{meta-prefix-char}, followed by the corresponding non-meta
896 character.  Thus, the first example below is handled by conversion into
897 the second example.
899 @example
900 @group
901 (lookup-key (current-global-map) "\M-f")
902     @result{} forward-word
903 @end group
904 @group
905 (lookup-key (current-global-map) "\ef")
906     @result{} forward-word
907 @end group
908 @end example
910 Unlike @code{read-key-sequence}, this function does not modify the
911 specified events in ways that discard information (@pxref{Key Sequence
912 Input}).  In particular, it does not convert letters to lower case and
913 it does not change drag events to clicks.
914 @end defun
916 @deffn Command undefined
917 Used in keymaps to undefine keys.  It calls @code{ding}, but does
918 not cause an error.
919 @end deffn
921 @defun key-binding key &optional accept-defaults
922 This function returns the binding for @var{key} in the current
923 keymaps, trying all the active keymaps.  The result is @code{nil} if
924 @var{key} is undefined in the keymaps.
926 @c Emacs 19 feature
927 The argument @var{accept-defaults} controls checking for default
928 bindings, as in @code{lookup-key} (above).
930 An error is signaled if @var{key} is not a string or a vector.
932 @example
933 @group
934 (key-binding "\C-x\C-f")
935     @result{} find-file
936 @end group
937 @end example
938 @end defun
940 @defun local-key-binding key &optional accept-defaults
941 This function returns the binding for @var{key} in the current
942 local keymap, or @code{nil} if it is undefined there.
944 @c Emacs 19 feature
945 The argument @var{accept-defaults} controls checking for default bindings,
946 as in @code{lookup-key} (above).
947 @end defun
949 @defun global-key-binding key &optional accept-defaults
950 This function returns the binding for command @var{key} in the
951 current global keymap, or @code{nil} if it is undefined there.
953 @c Emacs 19 feature
954 The argument @var{accept-defaults} controls checking for default bindings,
955 as in @code{lookup-key} (above).
956 @end defun
958 @c Emacs 19 feature
959 @defun minor-mode-key-binding key &optional accept-defaults
960 This function returns a list of all the active minor mode bindings of
961 @var{key}.  More precisely, it returns an alist of pairs
962 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
963 variable that enables the minor mode, and @var{binding} is @var{key}'s
964 binding in that mode.  If @var{key} has no minor-mode bindings, the
965 value is @code{nil}.
967 If the first binding found is not a prefix definition (a keymap or a
968 symbol defined as a keymap), all subsequent bindings from other minor
969 modes are omitted, since they would be completely shadowed.  Similarly,
970 the list omits non-prefix bindings that follow prefix bindings.
972 The argument @var{accept-defaults} controls checking for default
973 bindings, as in @code{lookup-key} (above).
974 @end defun
976 @defvar meta-prefix-char
977 @cindex @key{ESC}
978 This variable is the meta-prefix character code.  It is used when
979 translating a meta character to a two-character sequence so it can be
980 looked up in a keymap.  For useful results, the value should be a prefix
981 event (@pxref{Prefix Keys}).  The default value is 27, which is the
982 @sc{ascii} code for @key{ESC}.
984 As long as the value of @code{meta-prefix-char} remains 27, key lookup
985 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
986 as the @code{backward-word} command.  However, if you were to set
987 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
988 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
989 @code{switch-to-buffer} command.  (Don't actually do this!)  Here is an
990 illustration of what would happen:
992 @smallexample
993 @group
994 meta-prefix-char                    ; @r{The default value.}
995      @result{} 27
996 @end group
997 @group
998 (key-binding "\M-b")
999      @result{} backward-word
1000 @end group
1001 @group
1002 ?\C-x                               ; @r{The print representation}
1003      @result{} 24                          ;   @r{of a character.}
1004 @end group
1005 @group
1006 (setq meta-prefix-char 24)
1007      @result{} 24
1008 @end group
1009 @group
1010 (key-binding "\M-b")
1011      @result{} switch-to-buffer            ; @r{Now, typing @kbd{M-b} is}
1012                                     ;   @r{like typing @kbd{C-x b}.}
1014 (setq meta-prefix-char 27)          ; @r{Avoid confusion!}
1015      @result{} 27                          ; @r{Restore the default value!}
1016 @end group
1017 @end smallexample
1019 This translation of one event into two happens only for characters, not
1020 for other kinds of input events.  Thus, @kbd{M-@key{F1}}, a function
1021 key, is not converted into @kbd{@key{ESC} @key{F1}}.
1022 @end defvar
1024 @node Changing Key Bindings
1025 @section Changing Key Bindings
1026 @cindex changing key bindings
1027 @cindex rebinding
1029   The way to rebind a key is to change its entry in a keymap.  If you
1030 change a binding in the global keymap, the change is effective in all
1031 buffers (though it has no direct effect in buffers that shadow the
1032 global binding with a local one).  If you change the current buffer's
1033 local map, that usually affects all buffers using the same major mode.
1034 The @code{global-set-key} and @code{local-set-key} functions are
1035 convenient interfaces for these operations (@pxref{Key Binding
1036 Commands}).  You can also use @code{define-key}, a more general
1037 function; then you must specify explicitly the map to change.
1039 @cindex meta character key constants
1040 @cindex control character key constants
1041   In writing the key sequence to rebind, it is good to use the special
1042 escape sequences for control and meta characters (@pxref{String Type}).
1043 The syntax @samp{\C-} means that the following character is a control
1044 character and @samp{\M-} means that the following character is a meta
1045 character.  Thus, the string @code{"\M-x"} is read as containing a
1046 single @kbd{M-x}, @code{"\C-f"} is read as containing a single
1047 @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
1048 containing a single @kbd{C-M-x}.  You can also use this escape syntax in
1049 vectors, as well as others that aren't allowed in strings; one example
1050 is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
1052   The key definition and lookup functions accept an alternate syntax for
1053 event types in a key sequence that is a vector: you can use a list
1054 containing modifier names plus one base event (a character or function
1055 key name).  For example, @code{(control ?a)} is equivalent to
1056 @code{?\C-a} and @code{(hyper control left)} is equivalent to
1057 @code{C-H-left}.  One advantage of such lists is that the precise
1058 numeric codes for the modifier bits don't appear in compiled files.
1060   For the functions below, an error is signaled if @var{keymap} is not a
1061 keymap or if @var{key} is not a string or vector representing a key
1062 sequence.  You can use event types (symbols) as shorthand for events
1063 that are lists.
1065 @defun define-key keymap key binding
1066 This function sets the binding for @var{key} in @var{keymap}.  (If
1067 @var{key} is more than one event long, the change is actually made
1068 in another keymap reached from @var{keymap}.)  The argument
1069 @var{binding} can be any Lisp object, but only certain types are
1070 meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
1071 The value returned by @code{define-key} is @var{binding}.
1073 If @var{key} is @code{[t]}, this sets the default binding in
1074 @var{keymap}.  When an event has no binding of its own, the Emacs
1075 command loop uses the keymap's default binding, if there is one.
1077 @cindex invalid prefix key error
1078 @cindex key sequence error
1079 Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
1080 or undefined; otherwise an error is signaled.  If some prefix of
1081 @var{key} is undefined, then @code{define-key} defines it as a prefix
1082 key so that the rest of @var{key} can be defined as specified.
1084 If there was previously no binding for @var{key} in @var{keymap}, the
1085 new binding is added at the beginning of @var{keymap}.  The order of
1086 bindings in a keymap makes no difference for keyboard input, but it
1087 does matter for menu keymaps (@pxref{Menu Keymaps}).
1088 @end defun
1090   Here is an example that creates a sparse keymap and makes a number of
1091 bindings in it:
1093 @smallexample
1094 @group
1095 (setq map (make-sparse-keymap))
1096     @result{} (keymap)
1097 @end group
1098 @group
1099 (define-key map "\C-f" 'forward-char)
1100     @result{} forward-char
1101 @end group
1102 @group
1104     @result{} (keymap (6 . forward-char))
1105 @end group
1107 @group
1108 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
1109 (define-key map "\C-xf" 'forward-word)
1110     @result{} forward-word
1111 @end group
1112 @group
1114 @result{} (keymap
1115     (24 keymap                ; @kbd{C-x}
1116         (102 . forward-word)) ;      @kbd{f}
1117     (6 . forward-char))       ; @kbd{C-f}
1118 @end group
1120 @group
1121 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1122 (define-key map "\C-p" ctl-x-map)
1123 ;; @code{ctl-x-map}
1124 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
1125 @end group
1127 @group
1128 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1129 (define-key map "\C-p\C-f" 'foo)
1130 @result{} 'foo
1131 @end group
1132 @group
1134 @result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
1135     (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1136     (24 keymap
1137         (102 . forward-word))
1138     (6 . forward-char))
1139 @end group
1140 @end smallexample
1142 @noindent
1143 Note that storing a new binding for @kbd{C-p C-f} actually works by
1144 changing an entry in @code{ctl-x-map}, and this has the effect of
1145 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1146 default global map.
1148 @defun substitute-key-definition olddef newdef keymap &optional oldmap
1149 @cindex replace bindings
1150 This function replaces @var{olddef} with @var{newdef} for any keys in
1151 @var{keymap} that were bound to @var{olddef}.  In other words,
1152 @var{olddef} is replaced with @var{newdef} wherever it appears.  The
1153 function returns @code{nil}.
1155 For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
1156 standard bindings:
1158 @smallexample
1159 @group
1160 (substitute-key-definition
1161  'find-file 'find-file-read-only (current-global-map))
1162 @end group
1163 @end smallexample
1165 @c Emacs 19 feature
1166 If @var{oldmap} is non-@code{nil}, that changes the behavior of
1167 @code{substitute-key-definition}: the bindings in @var{oldmap} determine
1168 which keys to rebind.  The rebindings still happen in @var{keymap}, not
1169 in @var{oldmap}.  Thus, you can change one map under the control of the
1170 bindings in another.  For example,
1172 @smallexample
1173 (substitute-key-definition
1174   'delete-backward-char 'my-funny-delete
1175   my-map global-map)
1176 @end smallexample
1178 @noindent
1179 puts the special deletion command in @code{my-map} for whichever keys
1180 are globally bound to the standard deletion command.
1182 @ignore
1183 @c Emacs 18 only
1184 Prefix keymaps that appear within @var{keymap} are not checked
1185 recursively for keys bound to @var{olddef}; they are not changed at all.
1186 Perhaps it would be better to check nested keymaps recursively.
1187 @end ignore
1189 Here is an example showing a keymap before and after substitution:
1191 @smallexample
1192 @group
1193 (setq map '(keymap
1194             (?1 . olddef-1)
1195             (?2 . olddef-2)
1196             (?3 . olddef-1)))
1197 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1198 @end group
1200 @group
1201 (substitute-key-definition 'olddef-1 'newdef map)
1202 @result{} nil
1203 @end group
1204 @group
1206 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1207 @end group
1208 @end smallexample
1209 @end defun
1211 @defun suppress-keymap keymap &optional nodigits
1212 @cindex @code{self-insert-command} override
1213 This function changes the contents of the full keymap @var{keymap} by
1214 making all the printing characters undefined.  More precisely, it binds
1215 them to the command @code{undefined}.  This makes ordinary insertion of
1216 text impossible.  @code{suppress-keymap} returns @code{nil}.
1218 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1219 digits to run @code{digit-argument}, and @kbd{-} to run
1220 @code{negative-argument}.  Otherwise it makes them undefined like the
1221 rest of the printing characters.
1223 @cindex yank suppression
1224 @cindex @code{quoted-insert} suppression
1225 The @code{suppress-keymap} function does not make it impossible to
1226 modify a buffer, as it does not suppress commands such as @code{yank}
1227 and @code{quoted-insert}.  To prevent any modification of a buffer, make
1228 it read-only (@pxref{Read Only Buffers}).
1230 Since this function modifies @var{keymap}, you would normally use it
1231 on a newly created keymap.  Operating on an existing keymap
1232 that is used for some other purpose is likely to cause trouble; for
1233 example, suppressing @code{global-map} would make it impossible to use
1234 most of Emacs.
1236 Most often, @code{suppress-keymap} is used to initialize local
1237 keymaps of modes such as Rmail and Dired where insertion of text is not
1238 desirable and the buffer is read-only.  Here is an example taken from
1239 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
1240 Dired mode is set up:
1242 @smallexample
1243 @group
1244 (setq dired-mode-map (make-keymap))
1245 (suppress-keymap dired-mode-map)
1246 (define-key dired-mode-map "r" 'dired-rename-file)
1247 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1248 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1249 (define-key dired-mode-map "v" 'dired-view-file)
1250 (define-key dired-mode-map "e" 'dired-find-file)
1251 (define-key dired-mode-map "f" 'dired-find-file)
1252 @dots{}
1253 @end group
1254 @end smallexample
1255 @end defun
1257 @node Key Binding Commands
1258 @section Commands for Binding Keys
1260   This section describes some convenient interactive interfaces for
1261 changing key bindings.  They work by calling @code{define-key}.
1263   People often use @code{global-set-key} in their init files
1264 (@pxref{Init File}) for simple customization.  For example,
1266 @smallexample
1267 (global-set-key "\C-x\C-\\" 'next-line)
1268 @end smallexample
1270 @noindent
1273 @smallexample
1274 (global-set-key [?\C-x ?\C-\\] 'next-line)
1275 @end smallexample
1277 @noindent
1280 @smallexample
1281 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1282 @end smallexample
1284 @noindent
1285 redefines @kbd{C-x C-\} to move down a line.
1287 @smallexample
1288 (global-set-key [M-mouse-1] 'mouse-set-point)
1289 @end smallexample
1291 @noindent
1292 redefines the first (leftmost) mouse button, typed with the Meta key, to
1293 set point where you click.
1295 @cindex non-@sc{ascii} text in keybindings
1296   Be careful when using non-@sc{ascii} text characters in Lisp
1297 specifications of keys to bind.  If these are read as multibyte text, as
1298 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
1299 must type the keys as multibyte too.  For instance, if you use this:
1301 @smallexample
1302 (global-set-key "@"o" 'my-function) ; bind o-umlaut
1303 @end smallexample
1305 @noindent
1308 @smallexample
1309 (global-set-key ?@"o 'my-function) ; bind o-umlaut
1310 @end smallexample
1312 @noindent
1313 and your language environment is multibyte Latin-1, these commands
1314 actually bind the multibyte character with code 2294, not the unibyte
1315 Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
1316 binding, you need to enter the multibyte Latin-1 character as keyboard
1317 input.  One way to do this is by using an appropriate input method
1318 (@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
1320   If you want to use a unibyte character in the key binding, you can
1321 construct the key sequence string using @code{multibyte-char-to-unibyte}
1322 or @code{string-make-unibyte} (@pxref{Converting Representations}).
1324 @deffn Command global-set-key key definition
1325 This function sets the binding of @var{key} in the current global map
1326 to @var{definition}.
1328 @smallexample
1329 @group
1330 (global-set-key @var{key} @var{definition})
1331 @equiv{}
1332 (define-key (current-global-map) @var{key} @var{definition})
1333 @end group
1334 @end smallexample
1335 @end deffn
1337 @deffn Command global-unset-key key
1338 @cindex unbinding keys
1339 This function removes the binding of @var{key} from the current
1340 global map.
1342 One use of this function is in preparation for defining a longer key
1343 that uses @var{key} as a prefix---which would not be allowed if
1344 @var{key} has a non-prefix binding.  For example:
1346 @smallexample
1347 @group
1348 (global-unset-key "\C-l")
1349     @result{} nil
1350 @end group
1351 @group
1352 (global-set-key "\C-l\C-l" 'redraw-display)
1353     @result{} nil
1354 @end group
1355 @end smallexample
1357 This function is implemented simply using @code{define-key}:
1359 @smallexample
1360 @group
1361 (global-unset-key @var{key})
1362 @equiv{}
1363 (define-key (current-global-map) @var{key} nil)
1364 @end group
1365 @end smallexample
1366 @end deffn
1368 @deffn Command local-set-key key definition
1369 This function sets the binding of @var{key} in the current local
1370 keymap to @var{definition}.
1372 @smallexample
1373 @group
1374 (local-set-key @var{key} @var{definition})
1375 @equiv{}
1376 (define-key (current-local-map) @var{key} @var{definition})
1377 @end group
1378 @end smallexample
1379 @end deffn
1381 @deffn Command local-unset-key key
1382 This function removes the binding of @var{key} from the current
1383 local map.
1385 @smallexample
1386 @group
1387 (local-unset-key @var{key})
1388 @equiv{}
1389 (define-key (current-local-map) @var{key} nil)
1390 @end group
1391 @end smallexample
1392 @end deffn
1394 @node Scanning Keymaps
1395 @section Scanning Keymaps
1397   This section describes functions used to scan all the current keymaps
1398 for the sake of printing help information.
1400 @defun accessible-keymaps keymap &optional prefix
1401 This function returns a list of all the keymaps that can be reached (via
1402 zero or more prefix keys) from @var{keymap}.  The value is an
1403 association list with elements of the form @code{(@var{key} .@:
1404 @var{map})}, where @var{key} is a prefix key whose definition in
1405 @var{keymap} is @var{map}.
1407 The elements of the alist are ordered so that the @var{key} increases
1408 in length.  The first element is always @code{("" .@: @var{keymap})},
1409 because the specified keymap is accessible from itself with a prefix of
1410 no events.
1412 If @var{prefix} is given, it should be a prefix key sequence; then
1413 @code{accessible-keymaps} includes only the submaps whose prefixes start
1414 with @var{prefix}.  These elements look just as they do in the value of
1415 @code{(accessible-keymaps)}; the only difference is that some elements
1416 are omitted.
1418 In the example below, the returned alist indicates that the key
1419 @key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
1420 definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
1421 (115 .@: foo))}.
1423 @smallexample
1424 @group
1425 (accessible-keymaps (current-local-map))
1426 @result{}(("" keymap
1427       (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
1428           (83 . center-paragraph)
1429           (115 . center-line))
1430       (9 . tab-to-tab-stop))
1431 @end group
1433 @group
1434    ("^[" keymap
1435     (83 . center-paragraph)
1436     (115 . foo)))
1437 @end group
1438 @end smallexample
1440 In the following example, @kbd{C-h} is a prefix key that uses a sparse
1441 keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
1442 Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
1443 the variable @code{ctl-x-4-map}.  The event @code{mode-line} is one of
1444 several dummy events used as prefixes for mouse actions in special parts
1445 of a window.
1447 @smallexample
1448 @group
1449 (accessible-keymaps (current-global-map))
1450 @result{} (("" keymap [set-mark-command beginning-of-line @dots{}
1451                    delete-backward-char])
1452 @end group
1453 @group
1454     ("^H" keymap (118 . describe-variable) @dots{}
1455      (8 . help-for-help))
1456 @end group
1457 @group
1458     ("^X" keymap [x-flush-mouse-queue @dots{}
1459      backward-kill-sentence])
1460 @end group
1461 @group
1462     ("^[" keymap [mark-sexp backward-sexp @dots{}
1463      backward-kill-word])
1464 @end group
1465     ("^X4" keymap (15 . display-buffer) @dots{})
1466 @group
1467     ([mode-line] keymap
1468      (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1469 @end group
1470 @end smallexample
1472 @noindent
1473 These are not all the keymaps you would see in actuality.
1474 @end defun
1476 @defun where-is-internal command &optional keymap firstonly noindirect
1477 This function is a subroutine used by the @code{where-is} command
1478 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
1479 of key sequences (of any length) that are bound to @var{command} in a
1480 set of keymaps.
1482 The argument @var{command} can be any object; it is compared with all
1483 keymap entries using @code{eq}.
1485 If @var{keymap} is @code{nil}, then the maps used are the current active
1486 keymaps, disregarding @code{overriding-local-map} (that is, pretending
1487 its value is @code{nil}).  If @var{keymap} is non-@code{nil}, then the
1488 maps searched are @var{keymap} and the global keymap.  If @var{keymap}
1489 is a list of keymaps, only those keymaps are searched.
1491 Usually it's best to use @code{overriding-local-map} as the expression
1492 for @var{keymap}.  Then @code{where-is-internal} searches precisely the
1493 keymaps that are active.  To search only the global map, pass
1494 @code{(keymap)} (an empty keymap) as @var{keymap}.
1496 If @var{firstonly} is @code{non-ascii}, then the value is a single
1497 string representing the first key sequence found, rather than a list of
1498 all possible key sequences.  If @var{firstonly} is @code{t}, then the
1499 value is the first key sequence, except that key sequences consisting
1500 entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
1501 characters) are preferred to all other key sequences.
1503 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1504 follow indirect keymap bindings.  This makes it possible to search for
1505 an indirect definition itself.
1507 @smallexample
1508 @group
1509 (where-is-internal 'describe-function)
1510     @result{} ("\^hf" "\^hd")
1511 @end group
1512 @end smallexample
1513 @end defun
1515 @deffn Command describe-bindings &optional prefix
1516 This function creates a listing of all current key bindings, and
1517 displays it in a buffer named @samp{*Help*}.  The text is grouped by
1518 modes---minor modes first, then the major mode, then global bindings.
1520 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
1521 listing includes only keys that start with @var{prefix}.
1523 The listing describes meta characters as @key{ESC} followed by the
1524 corresponding non-meta character.
1526 When several characters with consecutive @sc{ascii} codes have the
1527 same definition, they are shown together, as
1528 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
1529 know the @sc{ascii} codes to understand which characters this means.
1530 For example, in the default global map, the characters @samp{@key{SPC}
1531 ..@: ~} are described by a single line.  @key{SPC} is @sc{ascii} 32,
1532 @kbd{~} is @sc{ascii} 126, and the characters between them include all
1533 the normal printing characters, (e.g., letters, digits, punctuation,
1534 etc.@:); all these characters are bound to @code{self-insert-command}.
1535 @end deffn
1537 @node Menu Keymaps
1538 @section Menu Keymaps
1539 @cindex menu keymaps
1541 @c Emacs 19 feature
1542 A keymap can define a menu as well as bindings for keyboard keys and
1543 mouse button.  Menus are usually actuated with the mouse, but they can
1544 work with the keyboard also.
1546 @menu
1547 * Defining Menus::              How to make a keymap that defines a menu.
1548 * Mouse Menus::                 How users actuate the menu with the mouse.
1549 * Keyboard Menus::              How they actuate it with the keyboard.
1550 * Menu Example::                Making a simple menu.
1551 * Menu Bar::                    How to customize the menu bar.
1552 * Tool Bar::                    A tool bar is a row of images.
1553 * Modifying Menus::             How to add new items to a menu.
1554 @end menu
1556 @node Defining Menus
1557 @subsection Defining Menus
1558 @cindex defining menus
1559 @cindex menu prompt string
1560 @cindex prompt string (of menu)
1562 A keymap is suitable for menu use if it has an @dfn{overall prompt
1563 string}, which is a string that appears as an element of the keymap.
1564 (@xref{Format of Keymaps}.)  The string should describe the purpose of
1565 the menu's commands.  Emacs displays the overall prompt string as the
1566 menu title in some cases, depending on the toolkit (if any) used for
1567 displaying menus.@footnote{It is required for menus which do not use a
1568 toolkit, e.g.@: under MS-DOS.}  Keyboard menus also display the overall
1569 prompt string.
1571 The easiest way to construct a keymap with a prompt string is to specify
1572 the string as an argument when you call @code{make-keymap},
1573 @code{make-sparse-keymap} or @code{define-prefix-command}
1574 (@pxref{Creating Keymaps}).
1576 The order of items in the menu is the same as the order of bindings in
1577 the keymap.  Since @code{define-key} puts new bindings at the front, you
1578 should define the menu items starting at the bottom of the menu and
1579 moving to the top, if you care about the order.  When you add an item to
1580 an existing menu, you can specify its position in the menu using
1581 @code{define-key-after} (@pxref{Modifying Menus}).
1583 @menu
1584 * Simple Menu Items::       A simple kind of menu key binding,
1585                               limited in capabilities.
1586 * Extended Menu Items::     More powerful menu item definitions
1587                               let you specify keywords to enable
1588                               various features.
1589 * Menu Separators::         Drawing a horizontal line through a menu.
1590 * Alias Menu Items::        Using command aliases in menu items.
1591 @end menu
1593 @node Simple Menu Items
1594 @subsubsection Simple Menu Items
1596   The simpler and older way to define a menu keymap binding
1597 looks like this:
1599 @example
1600 (@var{item-string} . @var{real-binding})
1601 @end example
1603 @noindent
1604 The @sc{car}, @var{item-string}, is the string to be displayed in the
1605 menu.  It should be short---preferably one to three words.  It should
1606 describe the action of the command it corresponds to.
1608 You can also supply a second string, called the help string, as follows:
1610 @example
1611 (@var{item-string} @var{help} . @var{real-binding})
1612 @end example
1614 @var{help} specifies a ``help-echo'' string to display while the mouse
1615 is on that item in the same way as @code{help-echo} text properties
1616 (@pxref{Help display}).
1618 As far as @code{define-key} is concerned, @var{item-string} and
1619 @var{help-string} are part of the event's binding.  However,
1620 @code{lookup-key} returns just @var{real-binding}, and only
1621 @var{real-binding} is used for executing the key.
1623 If @var{real-binding} is @code{nil}, then @var{item-string} appears in
1624 the menu but cannot be selected.
1626 If @var{real-binding} is a symbol and has a non-@code{nil}
1627 @code{menu-enable} property, that property is an expression that
1628 controls whether the menu item is enabled.  Every time the keymap is
1629 used to display a menu, Emacs evaluates the expression, and it enables
1630 the menu item only if the expression's value is non-@code{nil}.  When a
1631 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
1632 cannot be selected.
1634 The menu bar does not recalculate which items are enabled every time you
1635 look at a menu.  This is because the X toolkit requires the whole tree
1636 of menus in advance.  To force recalculation of the menu bar, call
1637 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1639 You've probably noticed that menu items show the equivalent keyboard key
1640 sequence (if any) to invoke the same command.  To save time on
1641 recalculation, menu display caches this information in a sublist in the
1642 binding, like this:
1644 @c This line is not too long--rms.
1645 @example
1646 (@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
1647 @end example
1649 @noindent
1650 Don't put these sublists in the menu item yourself; menu display
1651 calculates them automatically.  Don't mention keyboard equivalents in
1652 the item strings themselves, since that is redundant.
1654 @node Extended Menu Items
1655 @subsubsection Extended Menu Items
1656 @kindex menu-item
1658   An extended-format menu item is a more flexible and also cleaner
1659 alternative to the simple format.  It consists of a list that starts
1660 with the symbol @code{menu-item}.  To define a non-selectable string,
1661 the item looks like this:
1663 @example
1664 (menu-item @var{item-name})
1665 @end example
1667 @noindent
1668 A string starting with two or more dashes specifies a separator line;
1669 see @ref{Menu Separators}.
1671   To define a real menu item which can be selected, the extended format
1672 item looks like this:
1674 @example
1675 (menu-item @var{item-name} @var{real-binding}
1676     . @var{item-property-list})
1677 @end example
1679 @noindent
1680 Here, @var{item-name} is an expression which evaluates to the menu item
1681 string.  Thus, the string need not be a constant.  The third element,
1682 @var{real-binding}, is the command to execute.  The tail of the list,
1683 @var{item-property-list}, has the form of a property list which contains
1684 other information.  Here is a table of the properties that are supported:
1686 @table @code
1687 @item :enable @var{form}
1688 The result of evaluating @var{form} determines whether the item is
1689 enabled (non-@code{nil} means yes).  If the item is not enabled,
1690 you can't really click on it.
1692 @item :visible @var{form}
1693 The result of evaluating @var{form} determines whether the item should
1694 actually appear in the menu (non-@code{nil} means yes).  If the item
1695 does not appear, then the menu is displayed as if this item were
1696 not defined at all.
1698 @item :help @var{help}
1699 The value of this property, @var{help}, specifies a ``help-echo'' string
1700 to display while the mouse is on that item.  This is displayed in the
1701 same way as @code{help-echo} text properties (@pxref{Help display}).
1702 Note that this must be a constant string, unlike the @code{help-echo}
1703 property for text and overlays.
1705 @item :button (@var{type} . @var{selected})
1706 This property provides a way to define radio buttons and toggle buttons.
1707 The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
1708 @code{:radio}.  The @sc{cdr}, @var{selected}, should be a form; the
1709 result of evaluating it says whether this button is currently selected.
1711 A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
1712 according to the value of @var{selected}.  The command itself should
1713 toggle @var{selected}, setting it to @code{t} if it is @code{nil},
1714 and to @code{nil} if it is @code{t}.  Here is how the menu item
1715 to toggle the @code{debug-on-error} flag is defined:
1717 @example
1718 (menu-item "Debug on Error" toggle-debug-on-error
1719            :button (:toggle
1720                     . (and (boundp 'debug-on-error)
1721                            debug-on-error)))
1722 @end example
1724 @noindent
1725 This works because @code{toggle-debug-on-error} is defined as a command
1726 which toggles the variable @code{debug-on-error}.
1728 @dfn{Radio buttons} are a group of menu items, in which at any time one
1729 and only one is ``selected.''  There should be a variable whose value
1730 says which one is selected at any time.  The @var{selected} form for
1731 each radio button in the group should check whether the variable has the
1732 right value for selecting that button.  Clicking on the button should
1733 set the variable so that the button you clicked on becomes selected.
1735 @item :key-sequence @var{key-sequence}
1736 This property specifies which key sequence is likely to be bound to the
1737 same command invoked by this menu item.  If you specify the right key
1738 sequence, that makes preparing the menu for display run much faster.
1740 If you specify the wrong key sequence, it has no effect; before Emacs
1741 displays @var{key-sequence} in the menu, it verifies that
1742 @var{key-sequence} is really equivalent to this menu item.
1744 @item :key-sequence nil
1745 This property indicates that there is normally no key binding which is
1746 equivalent to this menu item.  Using this property saves time in
1747 preparing the menu for display, because Emacs does not need to search
1748 the keymaps for a keyboard equivalent for this menu item.
1750 However, if the user has rebound this item's definition to a key
1751 sequence, Emacs ignores the @code{:keys} property and finds the keyboard
1752 equivalent anyway.
1754 @item :keys @var{string}
1755 This property specifies that @var{string} is the string to display
1756 as the keyboard equivalent for this menu item.  You can use
1757 the @samp{\\[...]} documentation construct in @var{string}.
1759 @item :filter @var{filter-fn}
1760 This property provides a way to compute the menu item dynamically.
1761 The property value @var{filter-fn} should be a function of one argument;
1762 when it is called, its argument will be @var{real-binding}.  The
1763 function should return the binding to use instead.
1764 @end table
1766 @node Menu Separators
1767 @subsubsection Menu Separators
1768 @cindex menu separators
1770   A menu separator is a kind of menu item that doesn't display any
1771 text--instead, it divides the menu into subparts with a horizontal line.
1772 A separator looks like this in the menu keymap:
1774 @example
1775 (menu-item @var{separator-type})
1776 @end example
1778 @noindent
1779 where @var{separator-type} is a string starting with two or more dashes.
1781   In the simplest case, @var{separator-type} consists of only dashes.
1782 That specifies the default kind of separator.  (For compatibility,
1783 @code{""} and @code{-} also count as separators.)
1785   Starting in Emacs 21, certain other values of @var{separator-type}
1786 specify a different style of separator.  Here is a table of them:
1788 @table @code
1789 @item "--no-line"
1790 @itemx "--space"
1791 An extra vertical space, with no actual line.
1793 @item "--single-line"
1794 A single line in the menu's foreground color.
1796 @item "--double-line"
1797 A double line in the menu's foreground color.
1799 @item "--single-dashed-line"
1800 A single dashed line in the menu's foreground color.
1802 @item "--double-dashed-line"
1803 A double dashed line in the menu's foreground color.
1805 @item "--shadow-etched-in"
1806 A single line with a 3D sunken appearance.  This is the default,
1807 used separators consisting of dashes only.
1809 @item "--shadow-etched-out"
1810 A single line with a 3D raised appearance.
1812 @item "--shadow-etched-in-dash"
1813 A single dashed line with a 3D sunken appearance.
1815 @item "--shadow-etched-out-dash"
1816 A single dashed line with a 3D raised appearance.
1818 @item "--shadow-double-etched-in"
1819 Two lines with a 3D sunken appearance.
1821 @item "--shadow-double-etched-out"
1822 Two lines with a 3D raised appearance.
1824 @item "--shadow-double-etched-in-dash"
1825 Two dashed lines with a 3D sunken appearance.
1827 @item "--shadow-double-etched-out-dash"
1828 Two dashed lines with a 3D raised appearance.
1829 @end table
1831   You can also give these names in another style, adding a colon after
1832 the double-dash and replacing each single dash with capitalization of
1833 the following word.  Thus, @code{"--:singleLine"}, is equivalent to
1834 @code{"--single-line"}.
1836   Some systems and display toolkits don't really handle all of these
1837 separator types.  If you use a type that isn't supported, the menu
1838 displays a similar kind of separator that is supported.
1840 @node Alias Menu Items
1841 @subsubsection Alias Menu Items
1843   Sometimes it is useful to make menu items that use the ``same''
1844 command but with different enable conditions.  The best way to do this
1845 in Emacs now is with extended menu items; before that feature existed,
1846 it could be done by defining alias commands and using them in menu
1847 items.  Here's an example that makes two aliases for
1848 @code{toggle-read-only} and gives them different enable conditions:
1850 @example
1851 (defalias 'make-read-only 'toggle-read-only)
1852 (put 'make-read-only 'menu-enable '(not buffer-read-only))
1853 (defalias 'make-writable 'toggle-read-only)
1854 (put 'make-writable 'menu-enable 'buffer-read-only)
1855 @end example
1857 When using aliases in menus, often it is useful to display the
1858 equivalent key bindings for the ``real'' command name, not the aliases
1859 (which typically don't have any key bindings except for the menu
1860 itself).  To request this, give the alias symbol a non-@code{nil}
1861 @code{menu-alias} property.  Thus,
1863 @example
1864 (put 'make-read-only 'menu-alias t)
1865 (put 'make-writable 'menu-alias t)
1866 @end example
1868 @noindent
1869 causes menu items for @code{make-read-only} and @code{make-writable} to
1870 show the keyboard bindings for @code{toggle-read-only}.
1872 @node Mouse Menus
1873 @subsection Menus and the Mouse
1875   The usual way to make a menu keymap produce a menu is to make it the
1876 definition of a prefix key.  (A Lisp program can explicitly pop up a
1877 menu and receive the user's choice---see @ref{Pop-Up Menus}.)
1879   If the prefix key ends with a mouse event, Emacs handles the menu keymap
1880 by popping up a visible menu, so that the user can select a choice with
1881 the mouse.  When the user clicks on a menu item, the event generated is
1882 whatever character or symbol has the binding that brought about that
1883 menu item.  (A menu item may generate a series of events if the menu has
1884 multiple levels or comes from the menu bar.)
1886   It's often best to use a button-down event to trigger the menu.  Then
1887 the user can select a menu item by releasing the button.
1889   A single keymap can appear as multiple menu panes, if you explicitly
1890 arrange for this.  The way to do this is to make a keymap for each pane,
1891 then create a binding for each of those maps in the main keymap of the
1892 menu.  Give each of these bindings an item string that starts with
1893 @samp{@@}.  The rest of the item string becomes the name of the pane.
1894 See the file @file{lisp/mouse.el} for an example of this.  Any ordinary
1895 bindings with @samp{@@}-less item strings are grouped into one pane,
1896 which appears along with the other panes explicitly created for the
1897 submaps.
1899   X toolkit menus don't have panes; instead, they can have submenus.
1900 Every nested keymap becomes a submenu, whether the item string starts
1901 with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
1902 special about @samp{@@} at the beginning of an item string is that the
1903 @samp{@@} doesn't appear in the menu item.
1905   You can also produce multiple panes or submenus from separate keymaps.
1906 The full definition of a prefix key always comes from merging the
1907 definitions supplied by the various active keymaps (minor mode, local,
1908 and global).  When more than one of these keymaps is a menu, each of
1909 them makes a separate pane or panes (when Emacs does not use an
1910 X-toolkit) or a separate submenu (when using an X-toolkit).
1911 @xref{Active Keymaps}.
1913 @node Keyboard Menus
1914 @subsection Menus and the Keyboard
1916 When a prefix key ending with a keyboard event (a character or function
1917 key) has a definition that is a menu keymap, the user can use the
1918 keyboard to choose a menu item.
1920 Emacs displays the menu's overall prompt string followed by the
1921 alternatives (the item strings of the bindings) in the echo area.  If
1922 the bindings don't all fit at once, the user can type @key{SPC} to see
1923 the next line of alternatives.  Successive uses of @key{SPC} eventually
1924 get to the end of the menu and then cycle around to the beginning.  (The
1925 variable @code{menu-prompt-more-char} specifies which character is used
1926 for this; @key{SPC} is the default.)
1928 When the user has found the desired alternative from the menu, he or she
1929 should type the corresponding character---the one whose binding is that
1930 alternative.
1932 @ignore
1933 In a menu intended for keyboard use, each menu item must clearly
1934 indicate what character to type.  The best convention to use is to make
1935 the character the first letter of the item string---that is something
1936 users will understand without being told.  We plan to change this; by
1937 the time you read this manual, keyboard menus may explicitly name the
1938 key for each alternative.
1939 @end ignore
1941 This way of using menus in an Emacs-like editor was inspired by the
1942 Hierarkey system.
1944 @defvar menu-prompt-more-char
1945 This variable specifies the character to use to ask to see
1946 the next line of a menu.  Its initial value is 32, the code
1947 for @key{SPC}.
1948 @end defvar
1950 @node Menu Example
1951 @subsection Menu Example
1952 @cindex menu definition example
1954   Here is a complete example of defining a menu keymap.  It is the
1955 definition of the @samp{Print} submenu in the @samp{Tools} menu in the
1956 menu bar, and it uses the simple menu item format (@pxref{Simple Menu
1957 Items}).  First we create the keymap, and give it a name:
1959 @example
1960 (defvar menu-bar-print-menu (make-sparse-keymap "Print"))
1961 @end example
1963 @noindent
1964 Next we define the menu items:
1966 @example
1967 (define-key menu-bar-print-menu [ps-print-region]
1968   '("Postscript Print Region" . ps-print-region-with-faces))
1969 (define-key menu-bar-print-menu [ps-print-buffer]
1970   '("Postscript Print Buffer" . ps-print-buffer-with-faces))
1971 (define-key menu-bar-print-menu [separator-ps-print]
1972   '("--"))
1973 (define-key menu-bar-print-menu [print-region]
1974   '("Print Region" . print-region))
1975 (define-key menu-bar-print-menu [print-buffer]
1976   '("Print Buffer" . print-buffer))
1977 @end example
1979 @noindent
1980 Note the symbols which the bindings are ``made for''; these appear
1981 inside square brackets, in the key sequence being defined.  In some
1982 cases, this symbol is the same as the command name; sometimes it is
1983 different.  These symbols are treated as ``function keys'', but they are
1984 not real function keys on the keyboard.  They do not affect the
1985 functioning of the menu itself, but they are ``echoed'' in the echo area
1986 when the user selects from the menu, and they appear in the output of
1987 @code{where-is} and @code{apropos}.
1989   The binding whose definition is @code{("--")} is a separator line.
1990 Like a real menu item, the separator has a key symbol, in this case
1991 @code{separator-ps-print}.  If one menu has two separators, they must
1992 have two different key symbols.
1994   Here is code to define enable conditions for two of the commands in
1995 the menu:
1997 @example
1998 (put 'print-region 'menu-enable 'mark-active)
1999 (put 'ps-print-region-with-faces 'menu-enable 'mark-active)
2000 @end example
2002   Here is how we make this menu appear as an item in the parent menu:
2004 @example
2005 (define-key menu-bar-tools-menu [print]
2006   (cons "Print" menu-bar-print-menu))
2007 @end example
2009 @noindent
2010 Note that this incorporates the submenu keymap, which is the value of
2011 the variable @code{menu-bar-print-menu}, rather than the symbol
2012 @code{menu-bar-print-menu} itself.  Using that symbol in the parent menu
2013 item would be meaningless because @code{menu-bar-print-menu} is not a
2014 command.
2016   If you wanted to attach the same print menu to a mouse click, you
2017 can do it this way:
2019 @example
2020 (define-key global-map [C-S-down-mouse-1]
2021    menu-bar-print-menu)
2022 @end example
2024   We could equally well use an extended menu item (@pxref{Extended Menu
2025 Items}) for @code{print-region}, like this:
2027 @example
2028 (define-key menu-bar-print-menu [print-region]
2029   '(menu-item "Print Region" print-region
2030               :enable mark-active))
2031 @end example
2033 @noindent
2034 With the extended menu item, the enable condition is specified
2035 inside the menu item itself.  If we wanted to make this
2036 item disappear from the menu entirely when the mark is inactive,
2037 we could do it this way:
2039 @example
2040 (define-key menu-bar-print-menu [print-region]
2041   '(menu-item "Print Region" print-region
2042               :visible mark-active))
2043 @end example
2045 @node Menu Bar
2046 @subsection The Menu Bar
2047 @cindex menu bar
2049   Most window systems allow each frame to have a @dfn{menu bar}---a
2050 permanently displayed menu stretching horizontally across the top of the
2051 frame.  The items of the menu bar are the subcommands of the fake
2052 ``function key'' @code{menu-bar}, as defined by all the active keymaps.
2054   To add an item to the menu bar, invent a fake ``function key'' of your
2055 own (let's call it @var{key}), and make a binding for the key sequence
2056 @code{[menu-bar @var{key}]}.  Most often, the binding is a menu keymap,
2057 so that pressing a button on the menu bar item leads to another menu.
2059   When more than one active keymap defines the same fake function key
2060 for the menu bar, the item appears just once.  If the user clicks on
2061 that menu bar item, it brings up a single, combined menu containing
2062 all the subcommands of that item---the global subcommands, the local
2063 subcommands, and the minor mode subcommands.
2065   The variable @code{overriding-local-map} is normally ignored when
2066 determining the menu bar contents.  That is, the menu bar is computed
2067 from the keymaps that would be active if @code{overriding-local-map}
2068 were @code{nil}.  @xref{Active Keymaps}.
2070   In order for a frame to display a menu bar, its @code{menu-bar-lines}
2071 parameter must be greater than zero.  Emacs uses just one line for the
2072 menu bar itself; if you specify more than one line, the other lines
2073 serve to separate the menu bar from the windows in the frame.  We
2074 recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{Window Frame
2075 Parameters}.
2077   Here's an example of setting up a menu bar item:
2079 @example
2080 @group
2081 (modify-frame-parameters (selected-frame)
2082                          '((menu-bar-lines . 2)))
2083 @end group
2085 @group
2086 ;; @r{Make a menu keymap (with a prompt string)}
2087 ;; @r{and make it the menu bar item's definition.}
2088 (define-key global-map [menu-bar words]
2089   (cons "Words" (make-sparse-keymap "Words")))
2090 @end group
2092 @group
2093 ;; @r{Define specific subcommands in this menu.}
2094 (define-key global-map
2095   [menu-bar words forward]
2096   '("Forward word" . forward-word))
2097 @end group
2098 @group
2099 (define-key global-map
2100   [menu-bar words backward]
2101   '("Backward word" . backward-word))
2102 @end group
2103 @end example
2105   A local keymap can cancel a menu bar item made by the global keymap by
2106 rebinding the same fake function key with @code{undefined} as the
2107 binding.  For example, this is how Dired suppresses the @samp{Edit} menu
2108 bar item:
2110 @example
2111 (define-key dired-mode-map [menu-bar edit] 'undefined)
2112 @end example
2114 @noindent
2115 @code{edit} is the fake function key used by the global map for the
2116 @samp{Edit} menu bar item.  The main reason to suppress a global
2117 menu bar item is to regain space for mode-specific items.
2119 @defvar menu-bar-final-items
2120 Normally the menu bar shows global items followed by items defined by the
2121 local maps.
2123 This variable holds a list of fake function keys for items to display at
2124 the end of the menu bar rather than in normal sequence.  The default
2125 value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
2126 at the end of the menu bar, following local menu items.
2127 @end defvar
2129 @defvar menu-bar-update-hook
2130 This normal hook is run whenever the user clicks on the menu bar, before
2131 displaying a submenu.  You can use it to update submenus whose contents
2132 should vary.
2133 @end defvar
2135 @node Tool Bar
2136 @subsection Tool bars
2137 @cindex tool bar
2139   A @dfn{tool bar} is a row of icons at the top of a frame, that execute
2140 commands when you click on them---in effect, a kind of graphical menu
2141 bar.  Emacs supports tool bars starting with version 21.
2143   The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
2144 controls how many lines' worth of height to reserve for the tool bar.  A
2145 zero value suppresses the tool bar.  If the value is nonzero, and
2146 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
2147 contracts automatically as needed to hold the specified contents.
2149   The tool bar contents are controlled by a menu keymap attached to a
2150 fake ``function key'' called @code{tool-bar} (much like the way the menu
2151 bar is controlled).  So you define a tool bar item using
2152 @code{define-key}, like this:
2154 @example
2155 (define-key global-map [tool-bar @var{key}] @var{item})
2156 @end example
2158 @noindent
2159 where @var{key} is a fake ``function key'' to distinguish this item from
2160 other items, and @var{item} is a menu item key binding (@pxref{Extended
2161 Menu Items}), which says how to display this item and how it behaves.
2163   The usual menu keymap item properties, @code{:visible},
2164 @code{:enable}, @code{:button}, and @code{:filter}, are useful in
2165 tool bar bindings and have their normal meanings.  The @var{real-binding}
2166 in the item must be a command, not a keymap; in other words, it does not
2167 work to define a tool bar icon as a prefix key.
2169   The @code{:help} property specifies a ``help-echo'' string to display
2170 while the mouse is on that item.  This is displayed in the same way as
2171 @code{help-echo} text properties (@pxref{Help display}).
2173   In addition, you should use the @code{:image} property;
2174 this is how you specify the image to display in the tool bar:
2176 @table @code
2177 @item :image @var{image}
2178 @var{images} is either a single image specification or a vector of four
2179 image specifications.  If you use a vector of four,
2180 one of them is used, depending on circumstances:
2182 @table @asis
2183 @item item 0
2184 Used when the item is enabled and selected.
2185 @item item 1
2186 Used when the item is enabled and deselected.
2187 @item item 2
2188 Used when the item is disabled and selected.
2189 @item item 3
2190 Used when the item is disabled and deselected.
2191 @end table
2192 @end table
2194 If @var{image} is a single image specification, Emacs draws the tool bar
2195 button in disabled state by applying an edge-detection algorithm to the
2196 image.
2198 The default tool bar is defined so that items specific to editing do not
2199 appear for major modes whose command symbol has a @code{mode-class}
2200 property of @code{special} (@pxref{Major Mode Conventions}).  Major
2201 modes may add items to the global bar by binding @code{[tool-bar
2202 @var{foo}]} in their local map.  It makes sense for some major modes to
2203 replace the default tool bar items completely, since not many can be
2204 accommodated conveniently, and the default bindings make this easy by
2205 using an indirection through @code{tool-bar-map}.
2207 @defvar tool-bar-map
2208 @tindex tool-bar-map
2209 By default, the global map binds @code{[tool-bar]} as follows:
2210 @example
2211 (global-set-key [tool-bar]
2212                 '(menu-item "tool bar" ignore
2213                             :filter (lambda (ignore) tool-bar-map)))
2214 @end example
2215 @noindent
2216 Thus the tool bar map is derived dynamically from the value of variable
2217 @code{tool-bar-map} and you should normally adjust the default (global)
2218 tool bar by changing that map.  Major modes may replace the global bar
2219 completely by making @code{tool-bar-map} buffer-local and set to a
2220 keymap containing only the desired items.  Info mode provides an
2221 example.
2222 @end defvar
2224 There are two convenience functions for defining tool bar items, as
2225 follows.
2227 @defun tool-bar-add-item icon def key &rest props
2228 @tindex tool-bar-add-item
2229 This function adds an item to the tool bar by modifying
2230 @code{tool-bar-map}.  The image to use is defined by @var{icon}, which
2231 is the base name of an XPM, XBM or PBM image file to located by
2232 @code{find-image}.  Given a value @samp{"exit"}, say, @file{exit.xpm},
2233 @file{exit.pbm} and @file{exit.xbm} would be searched for in that order
2234 on a color display.  On a monochrome display, the search order is
2235 @samp{.pbm}, @samp{.xbm} and @samp{.xpm}.  The binding to use is the
2236 command @var{def}, and @var{key} is the fake function key symbol in the
2237 prefix keymap.  The remaining arguments @var{props} are additional
2238 property list elements to add to the menu item specification.
2240 To define items in some local map, bind @code{`tool-bar-map} with
2241 @code{let} around calls of this function:
2242 @example
2243 (defvar foo-tool-bar-map
2244   (let ((tool-bar-map (make-sparse-keymap)))
2245     (tool-bar-add-item @dots{})
2246     @dots{}
2247     tool-bar-map))
2248 @end example
2249 @end defun
2251 @defun tool-bar-add-item-from-menu command icon &optional map &rest props
2252 @tindex tool-bar-add-item-from-menu
2253 This command is a convenience for defining tool bar items which are
2254 consistent with existing menu bar bindings.  The binding of
2255 @var{command} is looked up in the menu bar in @var{map} (default
2256 @code{global-map}) and modified to add an image specification for
2257 @var{icon}, which is looked for in the same way as by
2258 @code{tool-bar-add-item}.  The resulting binding is then placed in
2259 @code{tool-bar-map}.  @var{map} must contain an appropriate keymap bound
2260 to @code{[menu-bar]}.  The remaining arguments @var{props} are
2261 additional property list elements to add to the menu item specification.
2262 @end defun
2264 @tindex auto-resize-tool-bar
2265 @defvar auto-resize-tool-bar
2266 If this variable is non-@code{nil}, the tool bar automatically resizes to
2267 show all defined tool bar items---but not larger than a quarter of the
2268 frame's height.
2269 @end defvar
2271 @tindex auto-raise-tool-bar-items
2272 @defvar auto-raise-tool-bar-items
2273 If this variable is non-@code{nil}, tool bar items display
2274 in raised form when the mouse moves over them.
2275 @end defvar
2277 @tindex tool-bar-item-margin
2278 @defvar tool-bar-item-margin
2279 This variable specifies an extra margin to add around tool bar items.
2280 The value is an integer, a number of pixels.  The default is 1.
2281 @end defvar
2283 @tindex tool-bar-item-relief
2284 @defvar tool-bar-item-relief
2285 This variable specifies the shadow width for tool bar items.
2286 The value is an integer, a number of pixels.  The default is 3.
2287 @end defvar
2289   You can define a special meaning for clicking on a tool bar item with
2290 the shift, control, meta, etc., modifiers.  You do this by setting up
2291 additional items that relate to the original item through the fake
2292 function keys.  Specifically, the additional items should use the
2293 modified versions of the same fake function key used to name the
2294 original item.
2296   Thus, if the original item was defined this way,
2298 @example
2299 (define-key global-map [tool-bar shell]
2300   '(menu-item "Shell" shell
2301               :image (image :type xpm :file "shell.xpm")))
2302 @end example
2304 @noindent
2305 then here is how you can define clicking on the same tool bar image with
2306 the shift modifier:
2308 @example
2309 (define-key global-map [tool-bar S-shell] 'some-command)
2310 @end example
2312 @xref{Function Keys}, for more information about how to add modifiers to
2313 function keys.
2315 @node Modifying Menus
2316 @subsection Modifying Menus
2318   When you insert a new item in an existing menu, you probably want to
2319 put it in a particular place among the menu's existing items.  If you
2320 use @code{define-key} to add the item, it normally goes at the front of
2321 the menu.  To put it elsewhere in the menu, use @code{define-key-after}:
2323 @defun define-key-after map key binding &optional after
2324 Define a binding in @var{map} for @var{key}, with value @var{binding},
2325 just like @code{define-key}, but position the binding in @var{map} after
2326 the binding for the event @var{after}.  The argument @var{key} should be
2327 of length one---a vector or string with just one element.  But
2328 @var{after} should be a single event type---a symbol or a character, not
2329 a sequence.  The new binding goes after the binding for @var{after}.  If
2330 @var{after} is @code{t} or is omitted, then the new binding goes last, at
2331 the end of the keymap.  However, new bindings are added before any
2332 inherited keymap.
2334 Here is an example:
2336 @example
2337 (define-key-after my-menu [drink]
2338   '("Drink" . drink-command) 'eat)
2339 @end example
2341 @noindent
2342 makes a binding for the fake function key @key{DRINK} and puts it
2343 right after the binding for @key{EAT}.
2345 Here is how to insert an item called @samp{Work} in the @samp{Signals}
2346 menu of Shell mode, after the item @code{break}:
2348 @example
2349 (define-key-after
2350   (lookup-key shell-mode-map [menu-bar signals])
2351   [work] '("Work" . work-command) 'break)
2352 @end example
2353 @end defun