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
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}.
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
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.
36 @node Keymap Terminology
37 @section Keymap Terminology
41 @cindex binding of a 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
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 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},
97 @node Format of Keymaps
98 @section Format of Keymaps
99 @cindex format of keymaps
100 @cindex keymap format
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
110 Several kinds of elements may appear in a keymap, after the symbol
111 @code{keymap} that begins it:
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.
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
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.
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}.
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}.
183 (9 . lisp-indent-line)
187 (127 . backward-delete-char-untabify)
196 ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
198 ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
199 (24 . lisp-send-defun)))
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}.
215 (fset 'foo '(keymap))
220 (keymapp (current-global-map))
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.
245 @result{} (keymap [nil nil nil @dots{} nil nil])
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}).
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}.
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.
278 (setq map (copy-keymap (current-local-map)))
282 ;; @r{(This implements meta characters.)}
284 (83 . center-paragraph)
286 (9 . tab-to-tab-stop))
290 (eq map (current-local-map))
294 (equal map (current-local-map))
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:
309 (keymap @var{bindings}@dots{} . @var{parent-keymap})
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}.
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
343 Here is an example showing how to make a keymap that inherits
344 from @code{text-mode-map}:
347 (let ((map (make-sparse-keymap)))
348 (set-keymap-parent map text-mode-map)
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
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:
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}.
381 @code{help-map} is the global keymap for the @kbd{C-h} prefix key.
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.
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}.
401 @cindex @kbd{C-x @key{RET}}
403 @code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
409 @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
416 @code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
423 @code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
428 @vindex vc-prefix-map
429 @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
434 @vindex facemenu-keymap
435 @code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
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
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
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
473 (use-local-map (make-sparse-keymap))
477 (local-set-key "\C-p" ctl-x-map)
481 (key-binding "\C-p\C-f")
486 (key-binding "\C-p6")
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}).
508 @section Active Keymaps
509 @cindex active keymap
510 @cindex global 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
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.
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
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
587 @result{} (keymap [set-mark-command beginning-of-line @dots{}
588 delete-backward-char])
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
604 (10 . eval-print-last-sexp)
605 (9 . lisp-indent-line)
606 (127 . backward-delete-char-untabify)
616 @defun current-minor-mode-maps
617 This function returns a list of the keymaps of currently enabled minor modes.
620 @defun use-global-map keymap
621 This function makes @var{keymap} the new current global keymap. It
624 It is very unusual to change the global keymap.
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.
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
641 (@var{variable} . @var{keymap})
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
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}
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
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.
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
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.
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
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}.
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
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
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:
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}
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}.
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.
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}.
776 @cindex list in keymap
777 The meaning of a list depends on the types of the elements of the list.
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).
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
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}:
795 (@var{othermap} . @var{othertype})
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.''
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
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
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.
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
852 (keymap (9 . lisp-indent-line)
853 (127 . backward-delete-char-untabify)
854 (27 keymap (17 . indent-sexp) (24 . eval-defun)))
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:
870 (lookup-key (current-global-map) "\C-x\C-f")
874 (lookup-key (current-global-map) "\C-x\C-f12345")
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.
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
901 (lookup-key (current-global-map) "\M-f")
902 @result{} forward-word
905 (lookup-key (current-global-map) "\ef")
906 @result{} forward-word
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.
916 @deffn Command undefined
917 Used in keymaps to undefine keys. It calls @code{ding}, but does
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.
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.
934 (key-binding "\C-x\C-f")
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.
945 The argument @var{accept-defaults} controls checking for default bindings,
946 as in @code{lookup-key} (above).
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.
954 The argument @var{accept-defaults} controls checking for default bindings,
955 as in @code{lookup-key} (above).
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
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).
976 @defvar meta-prefix-char
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:
994 meta-prefix-char ; @r{The default value.}
999 @result{} backward-word
1002 ?\C-x ; @r{The print representation}
1003 @result{} 24 ; @r{of a character.}
1006 (setq meta-prefix-char 24)
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!}
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}}.
1024 @node Changing Key Bindings
1025 @section Changing Key Bindings
1026 @cindex changing key bindings
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
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}).
1090 Here is an example that creates a sparse keymap and makes a number of
1095 (setq map (make-sparse-keymap))
1099 (define-key map "\C-f" 'forward-char)
1100 @result{} forward-char
1104 @result{} (keymap (6 . forward-char))
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
1115 (24 keymap ; @kbd{C-x}
1116 (102 . forward-word)) ; @kbd{f}
1117 (6 . forward-char)) ; @kbd{C-f}
1121 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1122 (define-key map "\C-p" ctl-x-map)
1124 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
1128 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1129 (define-key map "\C-p\C-f" 'foo)
1134 @result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
1135 (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1137 (102 . forward-word))
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
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
1160 (substitute-key-definition
1161 'find-file 'find-file-read-only (current-global-map))
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,
1173 (substitute-key-definition
1174 'delete-backward-char 'my-funny-delete
1179 puts the special deletion command in @code{my-map} for whichever keys
1180 are globally bound to the standard deletion command.
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.
1189 Here is an example showing a keymap before and after substitution:
1197 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1201 (substitute-key-definition 'olddef-1 'newdef map)
1206 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
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
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:
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)
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,
1267 (global-set-key "\C-x\C-\\" 'next-line)
1274 (global-set-key [?\C-x ?\C-\\] 'next-line)
1281 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1285 redefines @kbd{C-x C-\} to move down a line.
1288 (global-set-key [M-mouse-1] 'mouse-set-point)
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:
1302 (global-set-key "@"o" 'my-function) ; bind o-umlaut
1309 (global-set-key ?@"o 'my-function) ; bind o-umlaut
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}.
1330 (global-set-key @var{key} @var{definition})
1332 (define-key (current-global-map) @var{key} @var{definition})
1337 @deffn Command global-unset-key key
1338 @cindex unbinding keys
1339 This function removes the binding of @var{key} from the current
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:
1348 (global-unset-key "\C-l")
1352 (global-set-key "\C-l\C-l" 'redraw-display)
1357 This function is implemented simply using @code{define-key}:
1361 (global-unset-key @var{key})
1363 (define-key (current-global-map) @var{key} nil)
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}.
1374 (local-set-key @var{key} @var{definition})
1376 (define-key (current-local-map) @var{key} @var{definition})
1381 @deffn Command local-unset-key key
1382 This function removes the binding of @var{key} from the current
1387 (local-unset-key @var{key})
1389 (define-key (current-local-map) @var{key} nil)
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
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
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)
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))
1435 (83 . center-paragraph)
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
1449 (accessible-keymaps (current-global-map))
1450 @result{} (("" keymap [set-mark-command beginning-of-line @dots{}
1451 delete-backward-char])
1454 ("^H" keymap (118 . describe-variable) @dots{}
1455 (8 . help-for-help))
1458 ("^X" keymap [x-flush-mouse-queue @dots{}
1459 backward-kill-sentence])
1462 ("^[" keymap [mark-sexp backward-sexp @dots{}
1463 backward-kill-word])
1465 ("^X4" keymap (15 . display-buffer) @dots{})
1468 (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1473 These are not all the keymaps you would see in actuality.
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
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.
1509 (where-is-internal 'describe-function)
1510 @result{} ("\^hf" "\^hd")
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}.
1538 @section Menu Keymaps
1539 @cindex menu keymaps
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.
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.
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
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}).
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
1589 * Menu Separators:: Drawing a horizontal line through a menu.
1590 * Alias Menu Items:: Using command aliases in menu items.
1593 @node Simple Menu Items
1594 @subsubsection Simple Menu Items
1596 The simpler and older way to define a menu keymap binding
1600 (@var{item-string} . @var{real-binding})
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:
1611 (@var{item-string} @var{help} . @var{real-binding})
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
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
1644 @c This line is not too long--rms.
1646 (@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
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
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:
1664 (menu-item @var{item-name})
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:
1675 (menu-item @var{item-name} @var{real-binding}
1676 . @var{item-property-list})
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:
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
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:
1718 (menu-item "Debug on Error" toggle-debug-on-error
1720 . (and (boundp 'debug-on-error)
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
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.
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:
1775 (menu-item @var{separator-type})
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:
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.
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:
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)
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,
1864 (put 'make-read-only 'menu-alias t)
1865 (put 'make-writable 'menu-alias t)
1869 causes menu items for @code{make-read-only} and @code{make-writable} to
1870 show the keyboard bindings for @code{toggle-read-only}.
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
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
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.
1941 This way of using menus in an Emacs-like editor was inspired by the
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
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:
1960 (defvar menu-bar-print-menu (make-sparse-keymap "Print"))
1964 Next we define the menu items:
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]
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))
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
1998 (put 'print-region 'menu-enable 'mark-active)
1999 (put 'ps-print-region-with-faces 'menu-enable 'mark-active)
2002 Here is how we make this menu appear as an item in the parent menu:
2005 (define-key menu-bar-tools-menu [print]
2006 (cons "Print" menu-bar-print-menu))
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
2016 If you wanted to attach the same print menu to a mouse click, you
2020 (define-key global-map [C-S-down-mouse-1]
2021 menu-bar-print-menu)
2024 We could equally well use an extended menu item (@pxref{Extended Menu
2025 Items}) for @code{print-region}, like this:
2028 (define-key menu-bar-print-menu [print-region]
2029 '(menu-item "Print Region" print-region
2030 :enable mark-active))
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:
2040 (define-key menu-bar-print-menu [print-region]
2041 '(menu-item "Print Region" print-region
2042 :visible mark-active))
2046 @subsection The 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
2077 Here's an example of setting up a menu bar item:
2081 (modify-frame-parameters (selected-frame)
2082 '((menu-bar-lines . 2)))
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")))
2093 ;; @r{Define specific subcommands in this menu.}
2094 (define-key global-map
2095 [menu-bar words forward]
2096 '("Forward word" . forward-word))
2099 (define-key global-map
2100 [menu-bar words backward]
2101 '("Backward word" . backward-word))
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
2111 (define-key dired-mode-map [menu-bar edit] 'undefined)
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
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.
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
2136 @subsection Tool bars
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:
2155 (define-key global-map [tool-bar @var{key}] @var{item})
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:
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:
2184 Used when the item is enabled and selected.
2186 Used when the item is enabled and deselected.
2188 Used when the item is disabled and selected.
2190 Used when the item is disabled and deselected.
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
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:
2211 (global-set-key [tool-bar]
2212 '(menu-item "tool bar" ignore
2213 :filter (lambda (ignore) tool-bar-map)))
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
2224 There are two convenience functions for defining tool bar items, as
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:
2243 (defvar foo-tool-bar-map
2244 (let ((tool-bar-map (make-sparse-keymap)))
2245 (tool-bar-add-item @dots{})
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.
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
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.
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.
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.
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
2296 Thus, if the original item was defined this way,
2299 (define-key global-map [tool-bar shell]
2300 '(menu-item "Shell" shell
2301 :image (image :type xpm :file "shell.xpm")))
2305 then here is how you can define clicking on the same tool bar image with
2309 (define-key global-map [tool-bar S-shell] 'some-command)
2312 @xref{Function Keys}, for more information about how to add modifiers to
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
2337 (define-key-after my-menu [drink]
2338 '("Drink" . drink-command) 'eat)
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}:
2350 (lookup-key shell-mode-map [menu-bar signals])
2351 [work] '("Work" . work-command) 'break)