2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/keymaps
6 @node Keymaps, Modes, Command Loop, Top
10 The bindings between input events and commands are recorded in data
11 structures called @dfn{keymaps}. Each binding in a keymap associates
12 (or @dfn{binds}) an individual event type either with another keymap or
13 with a command. When an event is bound to a keymap, that keymap is
14 used to look up the next input event; this continues until a command
15 is found. The whole process is called @dfn{key lookup}.
18 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
19 * Format of Keymaps:: What a keymap looks like as a Lisp object.
20 * Creating Keymaps:: Functions to create and copy keymaps.
21 * Inheritance and Keymaps:: How one keymap can inherit the bindings
23 * Prefix Keys:: Defining a key with a keymap as its definition.
24 * Active Keymaps:: Each buffer has a local keymap
25 to override the standard (global) bindings.
26 A minor mode can also override them.
27 * Key Lookup:: How extracting elements from keymaps works.
28 * Functions for Key Lookup:: How to request key lookup.
29 * Changing Key Bindings:: Redefining a key in a keymap.
30 * Key Binding Commands:: Interactive interfaces for redefining keys.
31 * Scanning Keymaps:: Looking through all keymaps, for printing help.
32 * Menu Keymaps:: A keymap can define a menu.
35 @node Keymap Terminology
36 @section Keymap Terminology
40 @cindex binding of a key
44 A @dfn{keymap} is a table mapping event types to definitions (which
45 can be any Lisp objects, though only certain types are meaningful for
46 execution by the command loop). Given an event (or an event type) and a
47 keymap, Emacs can get the event's definition. Events include ordinary
48 @sc{ASCII} characters, function keys, and mouse actions (@pxref{Input
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
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
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 a key sequence. In other words, removing one or
76 more events from the end of any valid key must always yield a prefix
77 key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
78 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
80 Note that the set of possible multi-event key sequences depends on the
81 bindings for prefix keys; therefore, it can be different for different
82 keymaps, and can change when bindings are changed. However, a one-event
83 sequence is always a key sequence, because it does not depend on any
84 prefix keys for its well-formedness.
86 At any time, several primary keymaps are @dfn{active}---that is, in
87 use for finding key bindings. These are the @dfn{global map}, which is
88 shared by all buffers; the @dfn{local keymap}, which is usually
89 associated with a specific major mode; and zero or more @dfn{minor mode
90 keymaps}, which belong to currently enabled minor modes. (Not all minor
91 modes have keymaps.) The local keymap bindings shadow (i.e., take
92 precedence over) the corresponding global bindings. The minor mode
93 keymaps shadow both local and global keymaps. @xref{Active Keymaps},
96 @node Format of Keymaps
97 @section Format of Keymaps
98 @cindex format of keymaps
101 @cindex sparse keymap
103 A keymap is a list whose @sc{car} is the symbol @code{keymap}. The
104 remaining elements of the list define the key bindings of the keymap.
105 Use the function @code{keymapp} (see below) to test whether an object is
108 Each ordinary binding applies to events of a particular @dfn{event
109 type}, which is always a character or a symbol. @xref{Classifying
112 An ordinary element of a keymap is a cons cell of the form
113 @code{(@var{type} .@: @var{binding})}. This specifies one binding, for
114 events of type @var{type}.
116 @cindex default key binding
118 A cons cell whose @sc{car} is @code{t} is a @dfn{default key binding};
119 any event not bound by other elements of the keymap is given
120 @var{binding} as its binding. Default bindings allow a keymap to bind
121 all possible event types without having to enumerate all of them. A
122 keymap that has a default binding completely masks any lower-precedence
125 If an element of a keymap is a vector, the vector counts as bindings
126 for all the @sc{ASCII} characters; vector element @var{n} is the binding
127 for the character with code @var{n}. This is a compact way to
128 record lots of bindings. A keymap with such a vector is called a
129 @dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}.
131 When a keymap contains a vector, it always defines a binding for every
132 @sc{ASCII} character even if the vector element is @code{nil}. Such a
133 binding of @code{nil} overrides any default binding in the keymap.
134 However, default bindings are still meaningful for events that are not
135 @sc{ASCII} characters. A binding of @code{nil} does @emph{not}
136 override lower-precedence keymaps; thus, if the local map gives a
137 binding of @code{nil}, Emacs uses the binding from the global map.
139 @cindex keymap prompt string
140 @cindex overall prompt string
141 @cindex prompt string of keymap
142 Aside from bindings, a keymap can also have a string as an element.
143 This is called the @dfn{overall prompt string} and makes it possible to
144 use the keymap as a menu. @xref{Menu Keymaps}.
146 @cindex meta characters lookup
147 Keymaps do not directly record bindings for the meta characters, whose
148 codes are from 128 to 255. Instead, meta characters are regarded for
149 purposes of key lookup as sequences of two characters, the first of
150 which is @key{ESC} (or whatever is currently the value of
151 @code{meta-prefix-char}). Thus, the key @kbd{M-a} is really represented
152 as @kbd{@key{ESC} a}, and its global binding is found at the slot for
153 @kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).
155 Here as an example is the local keymap for Lisp mode, a sparse
156 keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
157 C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
167 (9 . lisp-indent-line)
171 (127 . backward-delete-char-untabify)
180 ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
182 ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
183 (24 . lisp-send-defun)))
187 @defun keymapp object
188 This function returns @code{t} if @var{object} is a keymap, @code{nil}
189 otherwise. More precisely, this function tests for a list whose
190 @sc{car} is @code{keymap}.
198 (keymapp (current-global-map))
204 @node Creating Keymaps
205 @section Creating Keymaps
206 @cindex creating keymaps
208 Here we describe the functions for creating keymaps.
210 @c ??? This should come after makr-sparse-keymap
211 @defun make-keymap &optional prompt
212 This function creates and returns a new full keymap (i.e., one
213 containing a vector of length 128 for defining all the @sc{ASCII}
214 characters). The new keymap initially binds all @sc{ASCII} characters
215 to @code{nil}, and does not bind any other kind of event.
220 @result{} (keymap [nil nil nil @dots{} nil nil])
224 If you specify @var{prompt}, that becomes the overall prompt string for
225 the keymap. The prompt string is useful for menu keymaps (@pxref{Menu
229 @defun make-sparse-keymap &optional prompt
230 This function creates and returns a new sparse keymap with no entries.
231 The new keymap does not bind any events. The argument @var{prompt}
232 specifies a prompt string, as in @code{make-keymap}.
242 @defun copy-keymap keymap
243 This function returns a copy of @var{keymap}. Any keymaps that
244 appear directly as bindings in @var{keymap} are also copied recursively,
245 and so on to any number of levels. However, recursive copying does not
246 take place when the definition of a character is a symbol whose function
247 definition is a keymap; the same symbol appears in the new copy.
252 (setq map (copy-keymap (current-local-map)))
256 ;; @r{(This implements meta characters.)}
258 (83 . center-paragraph)
260 (9 . tab-to-tab-stop))
264 (eq map (current-local-map))
268 (equal map (current-local-map))
274 @node Inheritance and Keymaps
275 @section Inheritance and Keymaps
276 @cindex keymap inheritance
277 @cindex inheriting a keymap's bindings
279 A keymap can inherit the bindings of another keymap. Do do this, make
280 a keymap whose ``tail'' is another existing keymap to inherit from.
281 Such a keymap looks like this:
284 (keymap @var{bindings}@dots{} . @var{other-keymap})
288 The effect is that this keymap inherits all the bindings of
289 @var{other-keymap}, whatever they may be at the time a key is looked up,
290 but can add to them or override them with @var{bindings}.
292 If you change the bindings in @var{other-keymap} using @code{define-key}
293 or other key-binding functions, these changes are visible in the
294 inheriting keymap unless shadowed by @var{bindings}. The converse is
295 not true: if you use @code{define-key} to change the inheriting keymap,
296 that affects @var{bindings}, but has no effect on @var{other-keymap}.
298 Here is an example showing how to make a keymap that inherits
299 from @code{text-mode-map}:
302 (setq my-mode-map (cons 'keymap text-mode-map))
309 A @dfn{prefix key} has an associated keymap that defines what to do
310 with key sequences that start with the prefix key. For example,
311 @kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
312 the variable @code{ctl-x-map}. Here is a list of the standard prefix
313 keys of Emacs and their keymaps:
319 @code{esc-map} is used for events that follow @key{ESC}. Thus, the
320 global definitions of all meta characters are actually found here. This
321 map is also the function definition of @code{ESC-prefix}.
325 @code{help-map} is used for events that follow @kbd{C-h}.
329 @vindex mode-specific-map
330 @code{mode-specific-map} is for events that follow @kbd{C-c}. This
331 map is not actually mode specific; its name was chosen to be informative
332 for the user in @kbd{C-h b} (@code{display-bindings}), where it
333 describes the main use of the @kbd{C-c} prefix key.
338 @findex Control-X-prefix
339 @code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
340 map is also the function definition of @code{Control-X-prefix}.
345 @code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}.
351 @code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
358 The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
359 that have no special name.
362 The binding of a prefix key is the keymap to use for looking up the
363 events that follow the prefix key. (It may instead be a symbol whose
364 function definition is a keymap. The effect is the same, but the symbol
365 serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is
366 the symbol @code{Control-X-prefix}, whose function definition is the
367 keymap for @kbd{C-x} commands. (The same keymap is also the value of
370 Prefix key definitions can appear in any active keymap. The
371 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
372 keys appear in the global map, so these prefix keys are always
373 available. Major and minor modes can redefine a key as a prefix by
374 putting a prefix key definition for it in the local map or the minor
375 mode's map. @xref{Active Keymaps}.
377 If a key is defined as a prefix in more than one active map, then its
378 various definitions are in effect merged: the commands defined in the
379 minor mode keymaps come first, followed by those in the local map's
380 prefix definition, and then by those from the global map.
382 In the following example, we make @kbd{C-p} a prefix key in the local
383 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
384 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
385 like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
390 (use-local-map (make-sparse-keymap))
394 (local-set-key "\C-p" ctl-x-map)
398 (key-binding "\C-p\C-f")
403 (key-binding "\C-p6")
408 @defun define-prefix-command symbol
409 @cindex prefix command
410 This function defines @var{symbol} as a prefix command: it creates a
411 full keymap and stores it as @var{symbol}'s function definition.
412 Storing the symbol as the binding of a key makes the key a prefix key
413 that has a name. The function also sets @var{symbol} as a variable, to
414 have the keymap as its value. It returns @var{symbol}.
416 In Emacs version 18, only the function definition of @var{symbol} was
417 set, not the value as a variable.
421 @section Active Keymaps
422 @cindex active keymap
423 @cindex global keymap
426 Emacs normally contains many keymaps; at any given time, just a few of
427 them are @dfn{active} in that they participate in the interpretation
428 of user input. These are the global keymap, the current buffer's
429 local keymap, and the keymaps of any enabled minor modes.
431 The @dfn{global keymap} holds the bindings of keys that are defined
432 regardless of the current buffer, such as @kbd{C-f}. The variable
433 @code{global-map} holds this keymap, which is always active.
435 Each buffer may have another keymap, its @dfn{local keymap}, which may
436 contain new or overriding definitions for keys. The current buffer's
437 local keymap is always active except when @code{overriding-local-map}
438 overrides it. Text properties can specify an alternative local map for
439 certain parts of the buffer; see @ref{Special Properties}.
441 Each minor mode may have a keymap; if it does, the keymap is active
442 when the minor mode is enabled.
444 The variable @code{overriding-local-map}, if non-@code{nil}, specifies
445 another local keymap that overrides the buffer's local map and all the
448 All the active keymaps are used together to determine what command to
449 execute when a key is entered. Emacs searches these maps one by one, in
450 order of decreasing precedence, until it finds a binding in one of the maps.
452 Normally, Emacs @emph{first} searches for the key in the minor mode
453 maps (one map at a time); if they do not supply a binding for the key,
454 Emacs searches the local map; if that too has no binding, Emacs then
455 searches the global map. However, if @code{overriding-local-map} is
456 non-@code{nil}, Emacs searches that map first, followed by the global
459 The procedure for searching a single keymap is called
460 @dfn{key lookup}; see @ref{Key Lookup}.
462 @cindex major mode keymap
463 Since every buffer that uses the same major mode normally uses the
464 same local keymap, you can think of the keymap as local to the mode. A
465 change to the local keymap of a buffer (using @code{local-set-key}, for
466 example) is seen also in the other buffers that share that keymap.
468 The local keymaps that are used for Lisp mode, C mode, and several
469 other major modes exist even if they have not yet been used. These
470 local maps are the values of the variables @code{lisp-mode-map},
471 @code{c-mode-map}, and so on. For most other modes, which are less
472 frequently used, the local keymap is constructed only when the mode is
473 used for the first time in a session.
475 The minibuffer has local keymaps, too; they contain various completion
476 and exit commands. @xref{Intro to Minibuffers}.
478 @xref{Standard Keymaps}, for a list of standard keymaps.
481 This variable contains the default global keymap that maps Emacs
482 keyboard input to commands. The global keymap is normally this keymap.
483 The default global keymap is a full keymap that binds
484 @code{self-insert-command} to all of the printing characters.
486 It is normal practice to change the bindings in the global map, but you
487 should not assign this variable any value other than the keymap it starts
491 @defun current-global-map
492 This function returns the current global keymap. This is the
493 same as the value of @code{global-map} unless you change one or the
499 @result{} (keymap [set-mark-command beginning-of-line @dots{}
500 delete-backward-char])
505 @defun current-local-map
506 This function returns the current buffer's local keymap, or @code{nil}
507 if it has none. In the following example, the keymap for the
508 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
509 in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
516 (10 . eval-print-last-sexp)
517 (9 . lisp-indent-line)
518 (127 . backward-delete-char-untabify)
528 @defun current-minor-mode-maps
529 This function returns a list of the keymaps of currently enabled minor modes.
532 @defun use-global-map keymap
533 This function makes @var{keymap} the new current global keymap. It
536 It is very unusual to change the global keymap.
539 @defun use-local-map keymap
540 This function makes @var{keymap} the new local keymap of the current
541 buffer. If @var{keymap} is @code{nil}, then the buffer has no local
542 keymap. @code{use-local-map} returns @code{nil}. Most major mode
543 commands use this function.
547 @defvar minor-mode-map-alist
548 This variable is an alist describing keymaps that may or may not be
549 active according to the values of certain variables. Its elements look
553 (@var{variable} . @var{keymap})
556 The keymap @var{keymap} is active whenever @var{variable} has a
557 non-@code{nil} value. Typically @var{variable} is the variable that
558 enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
560 Note that elements of @code{minor-mode-map-alist} do not have the same
561 structure as elements of @code{minor-mode-alist}. The map must be the
562 @sc{cdr} of the element; a list with the map as the second element will
565 What's more, the keymap itself must appear in the @sc{cdr}. It does not
566 work to store a variable in the @sc{cdr} and make the map the value of
569 When more than one minor mode keymap is active, their order of priority
570 is the order of @code{minor-mode-map-alist}. But you should design
571 minor modes so that they don't interfere with each other. If you do
572 this properly, the order will not matter.
574 See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
575 Minor Modes}, for more information about minor modes.
578 @defvar overriding-local-map
579 If non-@code{nil}, this variable holds a keymap to use instead of the
580 buffer's local keymap and instead of all the minor mode keymaps. This
581 keymap, if any, overrides all other maps that would have been active,
582 except for the current global map.
585 @defvar overriding-terminal-local-map
586 If non-@code{nil}, this variable holds a keymap to use instead of
587 @code{overriding-local-map}, the buffer's local keymap and all the minor
590 This variable is always local to the current terminal and cannot be
591 buffer-local. @xref{Multiple Displays}. It is used to implement
592 incremental search mode.
595 @defvar overriding-local-map-menu-flag
596 If this variable is non-@code{nil}, the value of
597 @code{overriding-local-map} or @code{overriding-terminal-local-map} can
598 affect the display of the menu bar. The default value is @code{nil}, so
599 those map variables have no effect on the menu bar.
601 Note that these two map variables do affect the execution of key
602 sequences entered using the menu bar, even if they do not affect the
603 menu bar display. So if a menu bar key sequence comes in, you should
604 clear the variables before looking up and executing that key sequence.
605 Modes that use the variables would typically do this anyway; normally
606 they respond to events that they do not handle by ``unreading'' them and
615 @dfn{Key lookup} is the process of finding the binding of a key
616 sequence from a given keymap. Actual execution of the binding is not
619 Key lookup uses just the event type of each event in the key
620 sequence; the rest of the event is ignored. In fact, a key sequence
621 used for key lookup may designate mouse events with just their types
622 (symbols) instead of with entire mouse events (lists). @xref{Input
623 Events}. Such a pseudo-key-sequence is insufficient for
624 @code{command-execute}, but it is sufficient for looking up or rebinding
627 When the key sequence consists of multiple events, key lookup
628 processes the events sequentially: the binding of the first event is
629 found, and must be a keymap; then the second event's binding is found in
630 that keymap, and so on until all the events in the key sequence are used
631 up. (The binding thus found for the last event may or may not be a
632 keymap.) Thus, the process of key lookup is defined in terms of a
633 simpler process for looking up a single event in a keymap. How that is
634 done depends on the type of object associated with the event in that
637 Let's use the term @dfn{keymap entry} to describe the value found by
638 looking up an event type in a keymap. (This doesn't include the item
639 string and other extra elements in menu key bindings because
640 @code{lookup-key} and other key lookup functions don't include them in
641 the returned value.) While any Lisp object may be stored in a keymap as
642 a keymap entry, not all make sense for key lookup. Here is a list of
643 the meaningful kinds of keymap entries:
647 @cindex @code{nil} in keymap
648 @code{nil} means that the events used so far in the lookup form an
649 undefined key. When a keymap fails to mention an event type at all, and
650 has no default binding, that is equivalent to a binding of @code{nil}
654 @cindex keymap in keymap
655 The events used so far in the lookup form a prefix key. The next
656 event of the key sequence is looked up in @var{keymap}.
659 @cindex command in keymap
660 The events used so far in the lookup form a complete key,
661 and @var{command} is its binding. @xref{What Is a Function}.
664 @cindex string in keymap
665 The array (either a string or a vector) is a keyboard macro. The events
666 used so far in the lookup form a complete key, and the array is its
667 binding. See @ref{Keyboard Macros}, for more information.
670 @cindex list in keymap
671 The meaning of a list depends on the types of the elements of the list.
675 If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
676 is a keymap, and is treated as a keymap (see above).
679 @cindex @code{lambda} in keymap
680 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
681 lambda expression. This is presumed to be a command, and is treated as
685 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
686 type, then this is an @dfn{indirect entry}:
689 (@var{othermap} . @var{othertype})
692 When key lookup encounters an indirect entry, it looks up instead the
693 binding of @var{othertype} in @var{othermap} and uses that.
695 This feature permits you to define one key as an alias for another key.
696 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
697 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
698 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
702 @cindex symbol in keymap
703 The function definition of @var{symbol} is used in place of
704 @var{symbol}. If that too is a symbol, then this process is repeated,
705 any number of times. Ultimately this should lead to an object that is
706 a keymap, a command or a keyboard macro. A list is allowed if it is a
707 keymap or a command, but indirect entries are not understood when found
710 Note that keymaps and keyboard macros (strings and vectors) are not
711 valid functions, so a symbol with a keymap, string, or vector as its
712 function definition is invalid as a function. It is, however, valid as
713 a key binding. If the definition is a keyboard macro, then the symbol
714 is also valid as an argument to @code{command-execute}
715 (@pxref{Interactive Call}).
717 @cindex @code{undefined} in keymap
718 The symbol @code{undefined} is worth special mention: it means to treat
719 the key as undefined. Strictly speaking, the key is defined, and its
720 binding is the command @code{undefined}; but that command does the same
721 thing that is done automatically for an undefined key: it rings the bell
722 (by calling @code{ding}) but does not signal an error.
724 @cindex preventing prefix key
725 @code{undefined} is used in local keymaps to override a global key
726 binding and make the key ``undefined'' locally. A local binding of
727 @code{nil} would fail to do this because it would not override the
730 @item @var{anything else}
731 If any other type of object is found, the events used so far in the
732 lookup form a complete key, and the object is its binding, but the
733 binding is not executable as a command.
736 In short, a keymap entry may be a keymap, a command, a keyboard macro,
737 a symbol that leads to one of them, or an indirection or @code{nil}.
738 Here is an example of a sparse keymap with two characters bound to
739 commands and one bound to another keymap. This map is the normal value
740 of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
741 127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
746 (keymap (9 . lisp-indent-line)
747 (127 . backward-delete-char-untabify)
748 (27 keymap (17 . indent-sexp) (24 . eval-defun)))
752 @node Functions for Key Lookup
753 @section Functions for Key Lookup
755 Here are the functions and variables pertaining to key lookup.
757 @defun lookup-key keymap key &optional accept-defaults
758 This function returns the definition of @var{key} in @var{keymap}. If
759 the string or vector @var{key} is not a valid key sequence according to
760 the prefix keys specified in @var{keymap} (which means it is ``too
761 long'' and has extra events at the end), then the value is a number, the
762 number of events at the front of @var{key} that compose a complete key.
765 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
766 considers default bindings as well as bindings for the specific events
767 in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
768 the specific sequence @var{key}, ignoring default bindings except when
769 you explicitly ask about them. (To do this, supply @code{t} as an
770 element of @var{key}; see @ref{Format of Keymaps}.)
772 All the other functions described in this chapter that look up keys use
777 (lookup-key (current-global-map) "\C-x\C-f")
781 (lookup-key (current-global-map) "\C-x\C-f12345")
786 If @var{key} contains a meta character, that character is implicitly
787 replaced by a two-character sequence: the value of
788 @code{meta-prefix-char}, followed by the corresponding non-meta
789 character. Thus, the first example below is handled by conversion into
794 (lookup-key (current-global-map) "\M-f")
795 @result{} forward-word
798 (lookup-key (current-global-map) "\ef")
799 @result{} forward-word
803 Unlike @code{read-key-sequence}, this function does not modify the
804 specified events in ways that discard information (@pxref{Key Sequence
805 Input}). In particular, it does not convert letters to lower case and
806 it does not change drag events to clicks.
809 @deffn Command undefined
810 Used in keymaps to undefine keys. It calls @code{ding}, but does
814 @defun key-binding key &optional accept-defaults
815 This function returns the binding for @var{key} in the current
816 keymaps, trying all the active keymaps. The result is @code{nil} if
817 @var{key} is undefined in the keymaps.
820 The argument @var{accept-defaults} controls checking for default
821 bindings, as in @code{lookup-key} (above).
823 An error is signaled if @var{key} is not a string or a vector.
827 (key-binding "\C-x\C-f")
833 @defun local-key-binding key &optional accept-defaults
834 This function returns the binding for @var{key} in the current
835 local keymap, or @code{nil} if it is undefined there.
838 The argument @var{accept-defaults} controls checking for default bindings,
839 as in @code{lookup-key} (above).
842 @defun global-key-binding key &optional accept-defaults
843 This function returns the binding for command @var{key} in the
844 current global keymap, or @code{nil} if it is undefined there.
847 The argument @var{accept-defaults} controls checking for default bindings,
848 as in @code{lookup-key} (above).
852 @defun minor-mode-key-binding key &optional accept-defaults
853 This function returns a list of all the active minor mode bindings of
854 @var{key}. More precisely, it returns an alist of pairs
855 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
856 variable that enables the minor mode, and @var{binding} is @var{key}'s
857 binding in that mode. If @var{key} has no minor-mode bindings, the
860 If the first binding is not a prefix command, all subsequent bindings
861 from other minor modes are omitted, since they would be completely
862 shadowed. Similarly, the list omits non-prefix bindings that follow
865 The argument @var{accept-defaults} controls checking for default
866 bindings, as in @code{lookup-key} (above).
869 @defvar meta-prefix-char
871 This variable is the meta-prefix character code. It is used when
872 translating a meta character to a two-character sequence so it can be
873 looked up in a keymap. For useful results, the value should be a prefix
874 event (@pxref{Prefix Keys}). The default value is 27, which is the
875 @sc{ASCII} code for @key{ESC}.
877 As long as the value of @code{meta-prefix-char} remains 27, key
878 lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
879 defined as the @code{backward-word} command. However, if you set
880 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
881 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
882 @code{switch-to-buffer} command.
886 meta-prefix-char ; @r{The default value.}
891 @result{} backward-word
894 ?\C-x ; @r{The print representation}
895 @result{} 24 ; @r{of a character.}
898 (setq meta-prefix-char 24)
903 @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
904 ; @r{like typing @kbd{C-x b}.}
906 (setq meta-prefix-char 27) ; @r{Avoid confusion!}
907 @result{} 27 ; @r{Restore the default value!}
912 @node Changing Key Bindings
913 @section Changing Key Bindings
914 @cindex changing key bindings
917 The way to rebind a key is to change its entry in a keymap. If you
918 change a binding in the global keymap, the change is effective in all
919 buffers (though it has no direct effect in buffers that shadow the
920 global binding with a local one). If you change the current buffer's
921 local map, that usually affects all buffers using the same major mode.
922 The @code{global-set-key} and @code{local-set-key} functions are
923 convenient interfaces for these operations (@pxref{Key Binding
924 Commands}). You can also use @code{define-key}, a more general
925 function; then you must specify explicitly the map to change.
927 @cindex meta character key constants
928 @cindex control character key constants
929 In writing the key sequence to rebind, it is good to use the special
930 escape sequences for control and meta characters (@pxref{String Type}).
931 The syntax @samp{\C-} means that the following character is a control
932 character and @samp{\M-} means that the following character is a meta
933 character. Thus, the string @code{"\M-x"} is read as containing a
934 single @kbd{M-x}, @code{"\C-f"} is read as containing a single
935 @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
936 containing a single @kbd{C-M-x}. You can also use this escape syntax in
937 vectors, as well as others that aren't allowed in strings; one example
938 is @samp{[?\C-\H-x home]}. @xref{Character Type}.
940 The key definition and lookup functions accept an alternate syntax for
941 event types in a key sequence that is a vector: you can use a list
942 containing modifier names plus one base event (a character or function
943 key name). For example, @code{(control ?a)} is equivalent to
944 @code{?\C-a} and @code{(hyper control left)} is equivalent to
947 One advantage of using a list to represent the event type is that the
948 precise numeric codes for the modifier bits don't appear in compiled
951 For the functions below, an error is signaled if @var{keymap} is not a
952 keymap or if @var{key} is not a string or vector representing a key
953 sequence. You can use event types (symbols) as shorthand for events
956 @defun define-key keymap key binding
957 This function sets the binding for @var{key} in @var{keymap}. (If
958 @var{key} is more than one event long, the change is actually made
959 in another keymap reached from @var{keymap}.) The argument
960 @var{binding} can be any Lisp object, but only certain types are
961 meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
962 The value returned by @code{define-key} is @var{binding}.
964 @cindex invalid prefix key error
965 @cindex key sequence error
966 Every prefix of @var{key} must be a prefix key (i.e., bound to a
967 keymap) or undefined; otherwise an error is signaled.
969 If some prefix of @var{key} is undefined, then @code{define-key} defines
970 it as a prefix key so that the rest of @var{key} may be defined as
974 Here is an example that creates a sparse keymap and makes a number of
979 (setq map (make-sparse-keymap))
983 (define-key map "\C-f" 'forward-char)
984 @result{} forward-char
988 @result{} (keymap (6 . forward-char))
992 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
993 (define-key map "\C-xf" 'forward-word)
994 @result{} forward-word
999 (24 keymap ; @kbd{C-x}
1000 (102 . forward-word)) ; @kbd{f}
1001 (6 . forward-char)) ; @kbd{C-f}
1005 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1006 (define-key map "\C-p" ctl-x-map)
1008 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
1012 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1013 (define-key map "\C-p\C-f" 'foo)
1018 @result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
1019 (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1021 (102 . forward-word))
1027 Note that storing a new binding for @kbd{C-p C-f} actually works by
1028 changing an entry in @code{ctl-x-map}, and this has the effect of
1029 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1032 @defun substitute-key-definition olddef newdef keymap &optional oldmap
1033 @cindex replace bindings
1034 This function replaces @var{olddef} with @var{newdef} for any keys in
1035 @var{keymap} that were bound to @var{olddef}. In other words,
1036 @var{olddef} is replaced with @var{newdef} wherever it appears. The
1037 function returns @code{nil}.
1039 For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
1044 (substitute-key-definition
1045 'find-file 'find-file-read-only (current-global-map))
1050 If @var{oldmap} is non-@code{nil}, then its bindings determine which
1051 keys to rebind. The rebindings still happen in @var{keymap}, not in
1052 @var{oldmap}. Thus, you can change one map under the control of the
1053 bindings in another. For example,
1056 (substitute-key-definition
1057 'delete-backward-char 'my-funny-delete
1062 puts the special deletion command in @code{my-map} for whichever keys
1063 are globally bound to the standard deletion command.
1067 Prefix keymaps that appear within @var{keymap} are not checked
1068 recursively for keys bound to @var{olddef}; they are not changed at all.
1069 Perhaps it would be better to check nested keymaps recursively.
1072 Here is an example showing a keymap before and after substitution:
1080 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1084 (substitute-key-definition 'olddef-1 'newdef map)
1089 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1094 @defun suppress-keymap keymap &optional nodigits
1095 @cindex @code{self-insert-command} override
1096 This function changes the contents of the full keymap @var{keymap} by
1097 making all the printing characters undefined. More precisely, it binds
1098 them to the command @code{undefined}. This makes ordinary insertion of
1099 text impossible. @code{suppress-keymap} returns @code{nil}.
1101 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1102 digits to run @code{digit-argument}, and @kbd{-} to run
1103 @code{negative-argument}. Otherwise it makes them undefined like the
1104 rest of the printing characters.
1106 @cindex yank suppression
1107 @cindex @code{quoted-insert} suppression
1108 The @code{suppress-keymap} function does not make it impossible to
1109 modify a buffer, as it does not suppress commands such as @code{yank}
1110 and @code{quoted-insert}. To prevent any modification of a buffer, make
1111 it read-only (@pxref{Read Only Buffers}).
1113 Since this function modifies @var{keymap}, you would normally use it
1114 on a newly created keymap. Operating on an existing keymap
1115 that is used for some other purpose is likely to cause trouble; for
1116 example, suppressing @code{global-map} would make it impossible to use
1119 Most often, @code{suppress-keymap} is used to initialize local
1120 keymaps of modes such as Rmail and Dired where insertion of text is not
1121 desirable and the buffer is read-only. Here is an example taken from
1122 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
1123 Dired mode is set up:
1128 (setq dired-mode-map (make-keymap))
1129 (suppress-keymap dired-mode-map)
1130 (define-key dired-mode-map "r" 'dired-rename-file)
1131 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1132 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1133 (define-key dired-mode-map "v" 'dired-view-file)
1134 (define-key dired-mode-map "e" 'dired-find-file)
1135 (define-key dired-mode-map "f" 'dired-find-file)
1141 @node Key Binding Commands
1142 @section Commands for Binding Keys
1144 This section describes some convenient interactive interfaces for
1145 changing key bindings. They work by calling @code{define-key}.
1147 People often use @code{global-set-key} in their @file{.emacs} file for
1148 simple customization. For example,
1151 (global-set-key "\C-x\C-\\" 'next-line)
1158 (global-set-key [?\C-x ?\C-\\] 'next-line)
1165 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1169 redefines @kbd{C-x C-\} to move down a line.
1172 (global-set-key [M-mouse-1] 'mouse-set-point)
1176 redefines the first (leftmost) mouse button, typed with the Meta key, to
1177 set point where you click.
1179 @deffn Command global-set-key key definition
1180 This function sets the binding of @var{key} in the current global map
1181 to @var{definition}.
1185 (global-set-key @var{key} @var{definition})
1187 (define-key (current-global-map) @var{key} @var{definition})
1192 @deffn Command global-unset-key key
1193 @cindex unbinding keys
1194 This function removes the binding of @var{key} from the current
1197 One use of this function is in preparation for defining a longer key
1198 that uses @var{key} as a prefix---which would not be allowed if
1199 @var{key} has a non-prefix binding. For example:
1203 (global-unset-key "\C-l")
1207 (global-set-key "\C-l\C-l" 'redraw-display)
1212 This function is implemented simply using @code{define-key}:
1216 (global-unset-key @var{key})
1218 (define-key (current-global-map) @var{key} nil)
1223 @deffn Command local-set-key key definition
1224 This function sets the binding of @var{key} in the current local
1225 keymap to @var{definition}.
1229 (local-set-key @var{key} @var{definition})
1231 (define-key (current-local-map) @var{key} @var{definition})
1236 @deffn Command local-unset-key key
1237 This function removes the binding of @var{key} from the current
1242 (local-unset-key @var{key})
1244 (define-key (current-local-map) @var{key} nil)
1249 @node Scanning Keymaps
1250 @section Scanning Keymaps
1252 This section describes functions used to scan all the current keymaps
1253 for the sake of printing help information.
1255 @defun accessible-keymaps keymap &optional prefix
1256 This function returns a list of all the keymaps that can be accessed
1257 (via prefix keys) from @var{keymap}. The value is an association list
1258 with elements of the form @code{(@var{key} .@: @var{map})}, where
1259 @var{key} is a prefix key whose definition in @var{keymap} is
1262 The elements of the alist are ordered so that the @var{key} increases
1263 in length. The first element is always @code{("" .@: @var{keymap})},
1264 because the specified keymap is accessible from itself with a prefix of
1267 If @var{prefix} is given, it should be a prefix key sequence; then
1268 @code{accessible-keymaps} includes only the submaps whose prefixes start
1269 with @var{prefix}. These elements look just as they do in the value of
1270 @code{(accessible-keymaps)}; the only difference is that some elements
1273 In the example below, the returned alist indicates that the key
1274 @key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
1275 definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
1280 (accessible-keymaps (current-local-map))
1281 @result{}(("" keymap
1282 (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
1283 (83 . center-paragraph)
1284 (115 . center-line))
1285 (9 . tab-to-tab-stop))
1290 (83 . center-paragraph)
1295 In the following example, @kbd{C-h} is a prefix key that uses a sparse
1296 keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
1297 Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
1298 the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of
1299 several dummy events used as prefixes for mouse actions in special parts
1304 (accessible-keymaps (current-global-map))
1305 @result{} (("" keymap [set-mark-command beginning-of-line @dots{}
1306 delete-backward-char])
1309 ("^H" keymap (118 . describe-variable) @dots{}
1310 (8 . help-for-help))
1313 ("^X" keymap [x-flush-mouse-queue @dots{}
1314 backward-kill-sentence])
1317 ("^[" keymap [mark-sexp backward-sexp @dots{}
1318 backward-kill-word])
1320 ("^X4" keymap (15 . display-buffer) @dots{})
1323 (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1328 These are not all the keymaps you would see in an actual case.
1331 @defun where-is-internal command &optional keymap firstonly noindirect
1332 This function returns a list of key sequences (of any length) that are
1333 bound to @var{command} in a set of keymaps.
1335 The argument @var{command} can be any object; it is compared with all
1336 keymap entries using @code{eq}.
1338 If @var{keymap} is @code{nil}, then the maps used are the current active
1339 keymaps, disregarding @code{overriding-local-map} (that is, pretending
1340 its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
1341 maps searched are @var{keymap} and the global keymap.
1343 Usually it's best to use @code{overriding-local-map} as the expression
1344 for @var{keymap}. Then @code{where-is-internal} searches precisely the
1345 keymaps that are active. To search only the global map, pass
1346 @code{(keymap)} (an empty keymap) as @var{keymap}.
1348 If @var{firstonly} is @code{non-ascii}, then the value is a single
1349 string representing the first key sequence found, rather than a list of
1350 all possible key sequences. If @var{firstonly} is @code{t}, then the
1351 value is the first key sequence, except that key sequences consisting
1352 entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
1353 characters) are preferred to all other key sequences.
1355 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1356 follow indirect keymap bindings. This makes it possible to search for
1357 an indirect definition itself.
1359 This function is used by @code{where-is} (@pxref{Help, , Help, emacs,
1360 The GNU Emacs Manual}).
1364 (where-is-internal 'describe-function)
1365 @result{} ("\^hf" "\^hd")
1370 @deffn Command describe-bindings prefix
1371 This function creates a listing of all defined keys and their
1372 definitions. It writes the listing in a buffer named @samp{*Help*} and
1373 displays it in a window.
1375 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
1376 listing includes only keys that start with @var{prefix}.
1378 The listing describes meta characters as @key{ESC} followed by the
1379 corresponding non-meta character.
1381 When several characters with consecutive @sc{ASCII} codes have the
1382 same definition, they are shown together, as
1383 @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
1384 know the @sc{ASCII} codes to understand which characters this means.
1385 For example, in the default global map, the characters @samp{@key{SPC}
1386 ..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
1387 @kbd{~} is @sc{ASCII} 126, and the characters between them include all
1388 the normal printing characters, (e.g., letters, digits, punctuation,
1389 etc.@:); all these characters are bound to @code{self-insert-command}.
1393 @section Menu Keymaps
1394 @cindex menu keymaps
1397 A keymap can define a menu as well as bindings for keyboard keys and
1398 mouse button. Menus are usually actuated with the mouse, but they can
1399 work with the keyboard also.
1402 * Defining Menus:: How to make a keymap that defines a menu.
1403 * Mouse Menus:: How users actuate the menu with the mouse.
1404 * Keyboard Menus:: How they actuate it with the keyboard.
1405 * Menu Example:: Making a simple menu.
1406 * Menu Bar:: How to customize the menu bar.
1407 * Modifying Menus:: How to add new items to a menu.
1410 @node Defining Menus
1411 @subsection Defining Menus
1412 @cindex defining menus
1413 @cindex menu prompt string
1414 @cindex prompt string (of menu)
1416 A keymap is suitable for menu use if it has an @dfn{overall prompt
1417 string}, which is a string that appears as an element of the keymap.
1418 (@xref{Format of Keymaps}.) The string should describe the purpose of
1419 the menu. The easiest way to construct a keymap with a prompt string is
1420 to specify the string as an argument when you call @code{make-keymap} or
1421 @code{make-sparse-keymap} (@pxref{Creating Keymaps}).
1423 The order of items in the menu is the same as the order of bindings in
1424 the keymap. Since @code{define-key} puts new bindings at the front, you
1425 should define the menu items starting at the bottom of the menu and
1426 moving to the top, if you care about the order. When you add an item to
1427 an existing menu, you can specify its position in the menu using
1428 @code{define-key-after} (@pxref{Modifying Menus}).
1430 The individual bindings in the menu keymap should have item
1431 strings; these strings become the items displayed in the menu. A
1432 binding with an item string looks like this:
1435 (@var{string} . @var{real-binding})
1438 The item string for a binding should be short---one or two words. It
1439 should describe the action of the command it corresponds to.
1441 As far as @code{define-key} is concerned, @var{string} is part of the
1442 event's binding. However, @code{lookup-key} returns just
1443 @var{real-binding}, and only @var{real-binding} is used for executing
1446 You can also supply a second string, called the help string, as follows:
1449 (@var{string} @var{help-string} . @var{real-binding})
1452 Currently Emacs does not actually use @var{help-string}; it knows only
1453 how to ignore @var{help-string} in order to extract @var{real-binding}.
1454 In the future we may use @var{help-string} as extended documentation for
1455 the menu item, available on request.
1457 If @var{real-binding} is @code{nil}, then @var{string} appears in the
1458 menu but cannot be selected.
1460 If @var{real-binding} is a symbol and has a non-@code{nil}
1461 @code{menu-enable} property, that property is an expression that
1462 controls whether the menu item is enabled. Every time the keymap is
1463 used to display a menu, Emacs evaluates the expression, and it enables
1464 the menu item only if the expression's value is non-@code{nil}. When a
1465 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
1466 cannot be selected with the mouse.
1468 The menu bar does not recalculate which items are enabled every time you
1469 look at a menu. This is because the X toolkit requires the whole tree
1470 of menus in advance. To force recalculation of the menu bar, call
1471 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1473 Sometimes it is useful to make menu items that use the ``same'' command
1474 but with different enable conditions. You can do this by defining alias
1475 commands. Here's an example that makes two aliases for
1476 @code{toggle-read-only} and gives them different enable conditions:
1479 (defalias 'make-read-only 'toggle-read-only)
1480 (put 'make-read-only 'menu-enable '(not buffer-read-only))
1481 (defalias 'make-writable 'toggle-read-only)
1482 (put 'make-writable 'menu-enable 'buffer-read-only)
1485 You've probably noticed that menu items show the equivalent keyboard key
1486 sequence (if any) to invoke the same command. To save time on
1487 recalculation, menu display caches this information in a sublist in the
1490 @c This line is not too long--rms.
1492 (@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
1495 Don't put these sublists in the menu item yourself; menu display
1496 calculates them automatically. Don't add keyboard equivalents to the
1497 item strings in a mouse menu, since that is redundant.
1499 If an alias command has no keyboard equivalent itself, menus show the
1500 keyboard equivalent of its underlying command. In the example above,
1501 menu items defined to run @code{make-read-only} or @code{make-writable}
1502 would show the keyboard equivalents of @code{toggle-read-only}.
1505 @subsection Menus and the Mouse
1507 The way to make a menu keymap produce a menu is to make it the
1508 definition of a prefix key.
1510 If the prefix key ends with a mouse event, Emacs handles the menu keymap
1511 by popping up a visible menu, so that the user can select a choice with
1512 the mouse. When the user clicks on a menu item, the event generated is
1513 whatever character or symbol has the binding that brought about that
1514 menu item. (A menu item may generate a series of events if the menu has
1515 multiple levels or comes from the menu bar.)
1517 It's often best to use a button-down event to trigger the menu. Then
1518 the user can select a menu item by releasing the button.
1520 A single keymap can appear as multiple menu panes, if you explicitly
1521 arrange for this. The way to do this is to make a keymap for each pane,
1522 then create a binding for each of those maps in the main keymap of the
1523 menu. Give each of these bindings an item string that starts with
1524 @samp{@@}. The rest of the item string becomes the name of the pane.
1525 See the file @file{lisp/mouse.el} for an example of this. Any ordinary
1526 bindings with @samp{@@}-less item strings are grouped into one pane,
1527 which appears along with the other panes explicitly created for the
1530 X toolkit menus don't have panes; instead, they can have submenus.
1531 Every nested keymap becomes a submenu, whether the item string starts
1532 with @samp{@@} or not. In a toolkit version of Emacs, the only thing
1533 special about @samp{@@} at the beginning of an item string is that the
1534 @samp{@@} doesn't appear in the menu item.
1536 You can also get multiple panes from separate keymaps. The full
1537 definition of a prefix key always comes from merging the definitions
1538 supplied by the various active keymaps (minor mode, local, and
1539 global). When more than one of these keymaps is a menu, each of them
1540 makes a separate pane or panes. @xref{Active Keymaps}.
1542 In toolkit versions of Emacs, menus don't have panes, so submenus are
1543 used to represent the separate keymaps. Each keymap's contribution
1544 becomes one submenu.
1546 A Lisp program can explicitly pop up a menu and receive the user's
1547 choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
1549 @node Keyboard Menus
1550 @subsection Menus and the Keyboard
1552 When a prefix key ending with a keyboard event (a character or function
1553 key) has a definition that is a menu keymap, the user can use the
1554 keyboard to choose a menu item.
1556 Emacs displays the menu alternatives (the item strings of the bindings)
1557 in the echo area. If they don't all fit at once, the user can type
1558 @key{SPC} to see the next line of alternatives. Successive uses of
1559 @key{SPC} eventually get to the end of the menu and then cycle around to
1560 the beginning. (The variable @code{menu-prompt-more-char} specifies
1561 which character is used for this; @key{SPC} is the default.)
1563 When the user has found the desired alternative from the menu, he or she
1564 should type the corresponding character---the one whose binding is that
1568 In a menu intended for keyboard use, each menu item must clearly
1569 indicate what character to type. The best convention to use is to make
1570 the character the first letter of the item string---that is something
1571 users will understand without being told. We plan to change this; by
1572 the time you read this manual, keyboard menus may explicitly name the
1573 key for each alternative.
1576 This way of using menus in an Emacs-like editor was inspired by the
1579 @defvar menu-prompt-more-char
1580 This variable specifies the character to use to ask to see
1581 the next line of a menu. Its initial value is 32, the code
1586 @subsection Menu Example
1588 Here is a simple example of how to set up a menu for mouse use.
1592 (make-sparse-keymap "Key Commands <==> Functions"))
1593 (fset 'help-for-keys my-menu-map)
1595 (define-key my-menu-map [bindings]
1596 '("List all keystroke commands" . describe-bindings))
1597 (define-key my-menu-map [key]
1598 '("Describe key briefly" . describe-key-briefly))
1599 (define-key my-menu-map [key-verbose]
1600 '("Describe key verbose" . describe-key))
1601 (define-key my-menu-map [function]
1602 '("Describe Lisp function" . describe-function))
1603 (define-key my-menu-map [where-is]
1604 '("Where is this command" . where-is))
1606 (define-key global-map [C-S-down-mouse-1] 'help-for-keys)
1609 The symbols used in the key sequences bound in the menu are fictitious
1610 ``function keys''; they don't appear on the keyboard, but that doesn't
1611 stop you from using them in the menu. Their names were chosen to be
1612 mnemonic, because they show up in the output of @code{where-is} and
1613 @code{apropos} to identify the corresponding menu items.
1615 However, if you want the menu to be usable from the keyboard as well,
1616 you must bind real @sc{ASCII} characters as well as fictitious function
1620 @subsection The Menu Bar
1623 Most window systems allow each frame to have a @dfn{menu bar}---a
1624 permanently displayed menu stretching horizontally across the top of the
1625 frame. The items of the menu bar are the subcommands of the fake
1626 ``function key'' @code{menu-bar}, as defined by all the active keymaps.
1628 To add an item to the menu bar, invent a fake ``function key'' of your
1629 own (let's call it @var{key}), and make a binding for the key sequence
1630 @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
1631 so that pressing a button on the menu bar item leads to another menu.
1633 When more than one active keymap defines the same fake function key
1634 for the menu bar, the item appears just once. If the user clicks on
1635 that menu bar item, it brings up a single, combined submenu containing
1636 all the subcommands of that item---the global subcommands, the local
1637 subcommands, and the minor mode subcommands, all together.
1639 The variable @code{overriding-local-map} is normally ignored when
1640 determining the menu bar contents. That is, the menu bar is computed
1641 from the keymaps that would be active if @code{overriding-local-map}
1642 were @code{nil}. @xref{Active Keymaps}.
1644 In order for a frame to display a menu bar, its @code{menu-bar-lines}
1645 parameter must be greater than zero. Emacs uses just one line for the
1646 menu bar itself; if you specify more than one line, the other lines
1647 serve to separate the menu bar from the windows in the frame. We
1648 recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame
1651 Here's an example of setting up a menu bar item:
1655 (modify-frame-parameters (selected-frame)
1656 '((menu-bar-lines . 2)))
1660 ;; @r{Make a menu keymap (with a prompt string)}
1661 ;; @r{and make it the menu bar item's definition.}
1662 (define-key global-map [menu-bar words]
1663 (cons "Words" (make-sparse-keymap "Words")))
1667 ;; @r{Define specific subcommands in the item's menu.}
1668 (define-key global-map
1669 [menu-bar words forward]
1670 '("Forward word" . forward-word))
1673 (define-key global-map
1674 [menu-bar words backward]
1675 '("Backward word" . backward-word))
1679 A local keymap can cancel a menu bar item made by the global keymap by
1680 rebinding the same fake function key with @code{undefined} as the
1681 binding. For example, this is how Dired suppresses the @samp{Edit} menu
1685 (define-key dired-mode-map [menu-bar edit] 'undefined)
1689 @code{edit} is the fake function key used by the global map for the
1690 @samp{Edit} menu bar item. The main reason to suppress a global
1691 menu bar item is to regain space for mode-specific items.
1693 @defvar menu-bar-final-items
1694 Normally the menu bar shows global items followed by items defined by the
1697 This variable holds a list of fake function keys for items to display at
1698 the end of the menu bar rather than in normal sequence. The default
1699 value is @code{(help)}; thus, the @samp{Help} menu item normally appears
1700 at the end of the menu bar, following local menu items.
1703 @defvar menu-bar-update-hook
1704 This normal hook is run whenever the user clicks on the menu bar, before
1705 displaying a submenu. You can use it to update submenus whose contents
1709 @node Modifying Menus
1710 @subsection Modifying Menus
1712 When you insert a new item in an existing menu, you probably want to
1713 put it in a particular place among the menu's existing items. If you
1714 use @code{define-key} to add the item, it normally goes at the front of
1715 the menu. To put it elsewhere, use @code{define-key-after}:
1717 @defun define-key-after map key binding after
1718 Define a binding in @var{map} for @var{key}, with value @var{binding},
1719 just like @code{define-key}, but position the binding in @var{map} after
1720 the binding for the event @var{after}. The argument @var{key} should
1721 be of length one---a vector or string with just one element.
1726 (define-key-after my-menu [drink]
1727 '("Drink" . drink-command) 'eat)
1731 makes a binding for the fake function key @key{drink} and puts it
1732 right after the binding for @key{eat}.
1734 Here is how to insert an item called @samp{Work} in the @samp{Signals}
1735 menu of Shell mode, after the item @code{break}:
1739 (lookup-key shell-mode-map [menu-bar signals])
1740 [work] '("Work" . work-command) 'break)
1743 Note that @var{key} is a sequence containing just one event type, but
1744 @var{after} is just an event type (not a sequence).