2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
4 @c 2004, 2005, 2006 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 * Key Sequences:: Key sequences as Lisp objects.
20 * Keymap Basics:: Basic concepts of keymaps.
21 * Format of Keymaps:: What a keymap looks like as a Lisp object.
22 * Creating Keymaps:: Functions to create and copy keymaps.
23 * Inheritance and Keymaps:: How one keymap can inherit the bindings
25 * Prefix Keys:: Defining a key with a keymap as its definition.
26 * Active Keymaps:: How Emacs searches the active keymaps
28 * Searching Keymaps:: A pseudo-Lisp summary of searching active maps.
29 * Controlling Active Maps:: Each buffer has a local keymap
30 to override the standard (global) bindings.
31 A minor mode can also override them.
32 * Key Lookup:: Finding a key's binding in one keymap.
33 * Functions for Key Lookup:: How to request key lookup.
34 * Changing Key Bindings:: Redefining a key in a keymap.
35 * Remapping Commands:: Bindings that translate one command to another.
36 * Key Binding Commands:: Interactive interfaces for redefining keys.
37 * Scanning Keymaps:: Looking through all keymaps, for printing help.
38 * Menu Keymaps:: Defining a menu as a keymap.
42 @section Key Sequences
47 A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
48 or more input events that form a unit. Input events include
49 characters, function keys, and mouse actions (@pxref{Input Events}).
50 The Emacs Lisp representation for a key sequence is a string or
51 vector. Unless otherwise stated, any Emacs Lisp function that accepts
52 a key sequence as an argument can handle both representations.
54 In the string representation, alphanumeric characters ordinarily
55 stand for themselves; for example, @code{"a"} represents @kbd{a} and
56 and @code{"2"} represents @kbd{2}. Control character events are
57 prefixed by the substring @code{"\C-"}, and meta characters by
58 @code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
59 In addition, the @key{TAB}, @key{RET}, @key{ESC}, and @key{DEL} events
60 are represented by @code{"\t"}, @code{"\r"}, @code{"\e"}, and
61 @code{"\d"} respectively. The string representation of a complete key
62 sequence is the concatenation of the string representations of the
63 constituent events; thus, @code{"\C-xl"} represents the key sequence
66 Key sequences containing function keys, mouse button events, or
67 non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
68 represented as strings; they have to be represented as vectors.
70 In the vector representation, each element of the vector represents
71 an input event, in its Lisp form. @xref{Input Events}. For example,
72 the vector @code{[?\C-x ?l]} represents the key sequence @kbd{C-x l}.
74 For examples of key sequences written in string and vector
75 representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
77 @defmac kbd keyseq-text
78 This macro converts the text @var{keyseq-text} (a string constant)
79 into a key sequence (a string or vector constant). The contents of
80 @var{keyseq-text} should describe the key sequence using almost the same
81 syntax used in this manual. More precisely, it uses the same syntax
82 that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
83 Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
84 function key names with @samp{<@dots{}>}.
87 (kbd "C-x") @result{} "\C-x"
88 (kbd "C-x C-f") @result{} "\C-x\C-f"
89 (kbd "C-x 4 C-f") @result{} "\C-x4\C-f"
90 (kbd "X") @result{} "X"
91 (kbd "RET") @result{} "\^M"
92 (kbd "C-c SPC") @result{} "\C-c@ "
93 (kbd "<f1> SPC") @result{} [f1 32]
94 (kbd "C-M-<down>") @result{} [C-M-down]
99 @section Keymap Basics
101 @cindex binding of a key
103 @cindex undefined key
105 A keymap is a Lisp data structure that specifies @dfn{key bindings}
106 for various key sequences.
108 A single keymap directly specifies definitions for individual
109 events. When a key sequence consists of a single event, its binding
110 in a keymap is the keymap's definition for that event. The binding of
111 a longer key sequence is found by an iterative process: first find the
112 definition of the first event (which must itself be a keymap); then
113 find the second event's definition in that keymap, and so on until all
114 the events in the key sequence have been processed.
116 If the binding of a key sequence is a keymap, we call the key sequence
117 a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
118 no more events can be added to it). If the binding is @code{nil},
119 we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
120 @kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
121 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
122 keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more
125 The rule for finding the binding of a key sequence assumes that the
126 intermediate bindings (found for the events before the last) are all
127 keymaps; if this is not so, the sequence of events does not form a
128 unit---it is not really one key sequence. In other words, removing one
129 or more events from the end of any valid key sequence must always yield
130 a prefix key. For example, @kbd{C-f C-n} is not a key sequence;
131 @kbd{C-f} is not a prefix key, so a longer sequence starting with
132 @kbd{C-f} cannot be a key sequence.
134 The set of possible multi-event key sequences depends on the bindings
135 for prefix keys; therefore, it can be different for different keymaps,
136 and can change when bindings are changed. However, a one-event sequence
137 is always a key sequence, because it does not depend on any prefix keys
138 for its well-formedness.
140 At any time, several primary keymaps are @dfn{active}---that is, in
141 use for finding key bindings. These are the @dfn{global map}, which is
142 shared by all buffers; the @dfn{local keymap}, which is usually
143 associated with a specific major mode; and zero or more @dfn{minor mode
144 keymaps}, which belong to currently enabled minor modes. (Not all minor
145 modes have keymaps.) The local keymap bindings shadow (i.e., take
146 precedence over) the corresponding global bindings. The minor mode
147 keymaps shadow both local and global keymaps. @xref{Active Keymaps},
150 @node Format of Keymaps
151 @section Format of Keymaps
152 @cindex format of keymaps
153 @cindex keymap format
155 @cindex sparse keymap
157 Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The
158 remaining elements of the list define the key bindings of the keymap.
159 A symbol whose function definition is a keymap is also a keymap. Use
160 the function @code{keymapp} (see below) to test whether an object is a
163 Several kinds of elements may appear in a keymap, after the symbol
164 @code{keymap} that begins it:
167 @item (@var{type} .@: @var{binding})
168 This specifies one binding, for events of type @var{type}. Each
169 ordinary binding applies to events of a particular @dfn{event type},
170 which is always a character or a symbol. @xref{Classifying Events}.
172 @item (t .@: @var{binding})
173 @cindex default key binding
174 This specifies a @dfn{default key binding}; any event not bound by other
175 elements of the keymap is given @var{binding} as its binding. Default
176 bindings allow a keymap to bind all possible event types without having
177 to enumerate all of them. A keymap that has a default binding
178 completely masks any lower-precedence keymap, except for events
179 explicitly bound to @code{nil} (see below).
181 @item @var{char-table}
182 If an element of a keymap is a char-table, it counts as holding
183 bindings for all character events with no modifier bits
184 (@pxref{modifier bits}): element @var{n} is the binding for the
185 character with code @var{n}. This is a compact way to record lots of
186 bindings. A keymap with such a char-table is called a @dfn{full
187 keymap}. Other keymaps are called @dfn{sparse keymaps}.
190 @cindex keymap prompt string
191 @cindex overall prompt string
192 @cindex prompt string of keymap
193 Aside from bindings, a keymap can also have a string as an element.
194 This is called the @dfn{overall prompt string} and makes it possible to
195 use the keymap as a menu. @xref{Defining Menus}.
198 When the binding is @code{nil}, it doesn't constitute a definition
199 but it does take precedence over a default binding or a binding in the
200 parent keymap. On the other hand, a binding of @code{nil} does
201 @emph{not} override lower-precedence keymaps; thus, if the local map
202 gives a binding of @code{nil}, Emacs uses the binding from the
205 @cindex meta characters lookup
206 Keymaps do not directly record bindings for the meta characters.
207 Instead, meta characters are regarded for purposes of key lookup as
208 sequences of two characters, the first of which is @key{ESC} (or
209 whatever is currently the value of @code{meta-prefix-char}). Thus, the
210 key @kbd{M-a} is internally represented as @kbd{@key{ESC} a}, and its
211 global binding is found at the slot for @kbd{a} in @code{esc-map}
212 (@pxref{Prefix Keys}).
214 This conversion applies only to characters, not to function keys or
215 other input events; thus, @kbd{M-@key{end}} has nothing to do with
216 @kbd{@key{ESC} @key{end}}.
218 Here as an example is the local keymap for Lisp mode, a sparse
219 keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
220 C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
235 ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
236 (24 . lisp-send-defun)
238 ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
242 ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
245 (127 . backward-delete-char-untabify)
249 ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
251 (9 . lisp-indent-line))
255 @defun keymapp object
256 This function returns @code{t} if @var{object} is a keymap, @code{nil}
257 otherwise. More precisely, this function tests for a list whose
258 @sc{car} is @code{keymap}, or for a symbol whose function definition
259 satisfies @code{keymapp}.
267 (fset 'foo '(keymap))
272 (keymapp (current-global-map))
278 @node Creating Keymaps
279 @section Creating Keymaps
280 @cindex creating keymaps
282 Here we describe the functions for creating keymaps.
284 @defun make-sparse-keymap &optional prompt
285 This function creates and returns a new sparse keymap with no entries.
286 (A sparse keymap is the kind of keymap you usually want.) The new
287 keymap does not contain a char-table, unlike @code{make-keymap}, and
288 does not bind any events.
297 If you specify @var{prompt}, that becomes the overall prompt string for
298 the keymap. The prompt string should be provided for menu keymaps
299 (@pxref{Defining Menus}).
302 @defun make-keymap &optional prompt
303 This function creates and returns a new full keymap. That keymap
304 contains a char-table (@pxref{Char-Tables}) with slots for all
305 characters without modifiers. The new keymap initially binds all
306 these characters to @code{nil}, and does not bind any other kind of
307 event. The argument @var{prompt} specifies a
308 prompt string, as in @code{make-sparse-keymap}.
313 @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
317 A full keymap is more efficient than a sparse keymap when it holds
318 lots of bindings; for just a few, the sparse keymap is better.
321 @defun copy-keymap keymap
322 This function returns a copy of @var{keymap}. Any keymaps that
323 appear directly as bindings in @var{keymap} are also copied recursively,
324 and so on to any number of levels. However, recursive copying does not
325 take place when the definition of a character is a symbol whose function
326 definition is a keymap; the same symbol appears in the new copy.
331 (setq map (copy-keymap (current-local-map)))
335 ;; @r{(This implements meta characters.)}
337 (83 . center-paragraph)
339 (9 . tab-to-tab-stop))
343 (eq map (current-local-map))
347 (equal map (current-local-map))
353 @node Inheritance and Keymaps
354 @section Inheritance and Keymaps
355 @cindex keymap inheritance
356 @cindex inheriting a keymap's bindings
358 A keymap can inherit the bindings of another keymap, which we call the
359 @dfn{parent keymap}. Such a keymap looks like this:
362 (keymap @var{bindings}@dots{} . @var{parent-keymap})
366 The effect is that this keymap inherits all the bindings of
367 @var{parent-keymap}, whatever they may be at the time a key is looked up,
368 but can add to them or override them with @var{bindings}.
370 If you change the bindings in @var{parent-keymap} using @code{define-key}
371 or other key-binding functions, these changes are visible in the
372 inheriting keymap unless shadowed by @var{bindings}. The converse is
373 not true: if you use @code{define-key} to change the inheriting keymap,
374 that affects @var{bindings}, but has no effect on @var{parent-keymap}.
376 The proper way to construct a keymap with a parent is to use
377 @code{set-keymap-parent}; if you have code that directly constructs a
378 keymap with a parent, please convert the program to use
379 @code{set-keymap-parent} instead.
381 @defun keymap-parent keymap
382 This returns the parent keymap of @var{keymap}. If @var{keymap}
383 has no parent, @code{keymap-parent} returns @code{nil}.
386 @defun set-keymap-parent keymap parent
387 This sets the parent keymap of @var{keymap} to @var{parent}, and returns
388 @var{parent}. If @var{parent} is @code{nil}, this function gives
389 @var{keymap} no parent at all.
391 If @var{keymap} has submaps (bindings for prefix keys), they too receive
392 new parent keymaps that reflect what @var{parent} specifies for those
396 Here is an example showing how to make a keymap that inherits
397 from @code{text-mode-map}:
400 (let ((map (make-sparse-keymap)))
401 (set-keymap-parent map text-mode-map)
405 A non-sparse keymap can have a parent too, but this is not very
406 useful. A non-sparse keymap always specifies something as the binding
407 for every numeric character code without modifier bits, even if it is
408 @code{nil}, so these character's bindings are never inherited from
415 A @dfn{prefix key} is a key sequence whose binding is a keymap. The
416 keymap defines what to do with key sequences that extend the prefix key.
417 For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
418 also stored in the variable @code{ctl-x-map}. This keymap defines
419 bindings for key sequences starting with @kbd{C-x}.
421 Some of the standard Emacs prefix keys use keymaps that are
422 also found in Lisp variables:
428 @code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus,
429 the global definitions of all meta characters are actually found here.
430 This map is also the function definition of @code{ESC-prefix}.
434 @code{help-map} is the global keymap for the @kbd{C-h} prefix key.
438 @vindex mode-specific-map
439 @code{mode-specific-map} is the global keymap for the prefix key
440 @kbd{C-c}. This map is actually global, not mode-specific, but its name
441 provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
442 (@code{display-bindings}), since the main use of this prefix key is for
443 mode-specific bindings.
448 @findex Control-X-prefix
449 @code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
450 This map is found via the function cell of the symbol
451 @code{Control-X-prefix}.
454 @cindex @kbd{C-x @key{RET}}
456 @code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
462 @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
469 @code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
476 @code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
481 @vindex vc-prefix-map
482 @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
487 @vindex facemenu-keymap
488 @code{facemenu-keymap} is the global keymap used for the @kbd{M-o}
493 The other Emacs prefix keys are @kbd{M-g}, @kbd{C-x @@}, @kbd{C-x a i},
494 @kbd{C-x @key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps
495 that have no special names.
498 The keymap binding of a prefix key is used for looking up the event
499 that follows the prefix key. (It may instead be a symbol whose function
500 definition is a keymap. The effect is the same, but the symbol serves
501 as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the
502 symbol @code{Control-X-prefix}, whose function cell holds the keymap
503 for @kbd{C-x} commands. (The same keymap is also the value of
506 Prefix key definitions can appear in any active keymap. The
507 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
508 keys appear in the global map, so these prefix keys are always
509 available. Major and minor modes can redefine a key as a prefix by
510 putting a prefix key definition for it in the local map or the minor
511 mode's map. @xref{Active Keymaps}.
513 If a key is defined as a prefix in more than one active map, then its
514 various definitions are in effect merged: the commands defined in the
515 minor mode keymaps come first, followed by those in the local map's
516 prefix definition, and then by those from the global map.
518 In the following example, we make @kbd{C-p} a prefix key in the local
519 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
520 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
521 like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
526 (use-local-map (make-sparse-keymap))
530 (local-set-key "\C-p" ctl-x-map)
534 (key-binding "\C-p\C-f")
539 (key-binding "\C-p6")
544 @defun define-prefix-command symbol &optional mapvar prompt
545 @cindex prefix command
546 @anchor{Definition of define-prefix-command}
547 This function prepares @var{symbol} for use as a prefix key's binding:
548 it creates a sparse keymap and stores it as @var{symbol}'s function
549 definition. Subsequently binding a key sequence to @var{symbol} will
550 make that key sequence into a prefix key. The return value is @code{symbol}.
552 This function also sets @var{symbol} as a variable, with the keymap as
553 its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
554 as a variable instead.
556 If @var{prompt} is non-@code{nil}, that becomes the overall prompt
557 string for the keymap. The prompt string should be given for menu keymaps
558 (@pxref{Defining Menus}).
562 @section Active Keymaps
563 @cindex active keymap
564 @cindex global keymap
567 Emacs normally contains many keymaps; at any given time, just a few
568 of them are @dfn{active}, meaning that they participate in the
569 interpretation of user input. All the active keymaps are used
570 together to determine what command to execute when a key is entered.
571 Emacs searches these keymaps one by one, in a standard order, until it
572 finds a binding in one of the keymaps.
574 Normally the active keymaps are the @code{keymap} property keymap,
575 the keymaps of any enabled minor modes, the current buffer's local
576 keymap, and the global keymap, in that order. Therefore, Emacs
577 searches for each input key sequence in all these keymaps. Here is a
578 pseudo-Lisp description of how this process works:
581 (or (if overriding-terminal-local-map
582 (@var{find-in} overriding-terminal-local-map)
583 (if overriding-local-map
584 (@var{find-in} overriding-local-map)
585 (or (@var{find-in} (get-text-property (point) 'keymap))
586 (@var{find-in-any} emulation-mode-map-alists)
587 (@var{find-in-any} minor-mode-overriding-map-alist)
588 (@var{find-in-any} minor-mode-map-alist)
589 (if (get-text-property (point) 'local-map)
590 (@var{find-in} (get-text-property (point) 'local-map))
591 (@var{find-in} (current-local-map))))))
592 (@var{find-in} (current-global-map)))
596 Here, the pseudo-function @var{find-in} means to look up the key
597 sequence in a single map, and @var{find-in-any} means to search the
598 appropriate keymaps from an alist. (Searching a single keymap for a
599 binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
601 The @dfn{global keymap} holds the bindings of keys that are defined
602 regardless of the current buffer, such as @kbd{C-f}. The variable
603 @code{global-map} holds this keymap, which is always active.
605 Each buffer may have another keymap, its @dfn{local keymap}, which
606 may contain new or overriding definitions for keys. The current
607 buffer's local keymap is always active except when
608 @code{overriding-local-map} overrides it. The @code{local-map} text
609 or overlay property can specify an alternative local keymap for certain
610 parts of the buffer; see @ref{Special Properties}.
612 Each minor mode can have a keymap; if it does, the keymap is active
613 when the minor mode is enabled. Modes for emulation can specify
614 additional active keymaps through the variable
615 @code{emulation-mode-map-alists}.
617 The highest precedence normal keymap comes from the @code{keymap}
618 text or overlay property. If that is non-@code{nil}, it is the first
619 keymap to be processed, in normal circumstances.
621 However, there are also special ways for programs to substitute
622 other keymaps for some of those. The variable
623 @code{overriding-local-map}, if non-@code{nil}, specifies a keymap
624 that replaces all the usual active keymaps except the global keymap.
625 Another way to do this is with @code{overriding-terminal-local-map};
626 it operates on a per-terminal basis. These variables are documented
629 @cindex major mode keymap
630 Since every buffer that uses the same major mode normally uses the
631 same local keymap, you can think of the keymap as local to the mode. A
632 change to the local keymap of a buffer (using @code{local-set-key}, for
633 example) is seen also in the other buffers that share that keymap.
635 The local keymaps that are used for Lisp mode and some other major
636 modes exist even if they have not yet been used. These local keymaps are
637 the values of variables such as @code{lisp-mode-map}. For most major
638 modes, which are less frequently used, the local keymap is constructed
639 only when the mode is used for the first time in a session.
641 The minibuffer has local keymaps, too; they contain various completion
642 and exit commands. @xref{Intro to Minibuffers}.
644 Emacs has other keymaps that are used in a different way---translating
645 events within @code{read-key-sequence}. @xref{Translating Input}.
647 @xref{Standard Keymaps}, for a list of standard keymaps.
649 @defun current-active-maps &optional olp
650 This returns the list of active keymaps that would be used by the
651 command loop in the current circumstances to look up a key sequence.
652 Normally it ignores @code{overriding-local-map} and
653 @code{overriding-terminal-local-map}, but if @var{olp} is
654 non-@code{nil} then it pays attention to them.
657 @defun key-binding key &optional accept-defaults no-remap
658 This function returns the binding for @var{key} according to the
659 current active keymaps. The result is @code{nil} if @var{key} is
660 undefined in the keymaps.
663 The argument @var{accept-defaults} controls checking for default
664 bindings, as in @code{lookup-key} (above).
666 When commands are remapped (@pxref{Remapping Commands}),
667 @code{key-binding} normally processes command remappings so as to
668 returns the remapped command that will actually be executed. However,
669 if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
670 remappings and returns the binding directly specified for @var{key}.
672 An error is signaled if @var{key} is not a string or a vector.
676 (key-binding "\C-x\C-f")
682 @node Searching Keymaps
683 @section Searching the Active Keymaps
685 After translation of the input events (@pxref{Translating Input})
686 Emacs looks for them in the active keymaps. Here is a pseudo-Lisp
687 description of the order in which the active keymaps are searched:
690 (or (if overriding-terminal-local-map
691 (@var{find-in} overriding-terminal-local-map)
692 (if overriding-local-map
693 (@var{find-in} overriding-local-map)
694 (or (@var{find-in} (get-text-property (point) 'keymap))
695 (@var{find-in-any} emulation-mode-map-alists)
696 (@var{find-in-any} minor-mode-overriding-map-alist)
697 (@var{find-in-any} minor-mode-map-alist)
698 (if (get-text-property (point) 'local-map)
699 (@var{find-in} (get-text-property (point) 'local-map))
700 (@var{find-in} (current-local-map))))))
701 (@var{find-in} (current-global-map)))
705 The @var{find-in} and @var{find-in-any} are pseudo functions that
706 search in one keymap and in an alist of keymaps, respectively.
710 The function finally found may be remapped
711 (@pxref{Remapping Commands}).
714 Characters that are bound to @code{self-insert-command} are translated
715 according to @code{translation-table-for-input} before insertion.
718 @code{current-active-maps} returns a list of the
719 currently active keymaps at point.
722 When a match is found (@pxref{Key Lookup}), if the binding in the
723 keymap is a function, the search is over. However if the keymap entry
724 is a symbol with a value or a string, Emacs replaces the input key
725 sequences with the variable's value or the string, and restarts the
726 search of the active keymaps.
729 @node Controlling Active Maps
730 @section Controlling the Active Keymaps
733 This variable contains the default global keymap that maps Emacs
734 keyboard input to commands. The global keymap is normally this
735 keymap. The default global keymap is a full keymap that binds
736 @code{self-insert-command} to all of the printing characters.
738 It is normal practice to change the bindings in the global keymap, but you
739 should not assign this variable any value other than the keymap it starts
743 @defun current-global-map
744 This function returns the current global keymap. This is the
745 same as the value of @code{global-map} unless you change one or the
751 @result{} (keymap [set-mark-command beginning-of-line @dots{}
752 delete-backward-char])
757 @defun current-local-map
758 This function returns the current buffer's local keymap, or @code{nil}
759 if it has none. In the following example, the keymap for the
760 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
761 in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
768 (10 . eval-print-last-sexp)
769 (9 . lisp-indent-line)
770 (127 . backward-delete-char-untabify)
780 @defun current-minor-mode-maps
781 This function returns a list of the keymaps of currently enabled minor modes.
784 @defun use-global-map keymap
785 This function makes @var{keymap} the new current global keymap. It
788 It is very unusual to change the global keymap.
791 @defun use-local-map keymap
792 This function makes @var{keymap} the new local keymap of the current
793 buffer. If @var{keymap} is @code{nil}, then the buffer has no local
794 keymap. @code{use-local-map} returns @code{nil}. Most major mode
795 commands use this function.
799 @defvar minor-mode-map-alist
800 @anchor{Definition of minor-mode-map-alist}
801 This variable is an alist describing keymaps that may or may not be
802 active according to the values of certain variables. Its elements look
806 (@var{variable} . @var{keymap})
809 The keymap @var{keymap} is active whenever @var{variable} has a
810 non-@code{nil} value. Typically @var{variable} is the variable that
811 enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
813 Note that elements of @code{minor-mode-map-alist} do not have the same
814 structure as elements of @code{minor-mode-alist}. The map must be the
815 @sc{cdr} of the element; a list with the map as the second element will
816 not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose
817 function definition is a keymap.
819 When more than one minor mode keymap is active, the earlier one in
820 @code{minor-mode-map-alist} takes priority. But you should design
821 minor modes so that they don't interfere with each other. If you do
822 this properly, the order will not matter.
824 See @ref{Keymaps and Minor Modes}, for more information about minor
825 modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key
829 @defvar minor-mode-overriding-map-alist
830 This variable allows major modes to override the key bindings for
831 particular minor modes. The elements of this alist look like the
832 elements of @code{minor-mode-map-alist}: @code{(@var{variable}
835 If a variable appears as an element of
836 @code{minor-mode-overriding-map-alist}, the map specified by that
837 element totally replaces any map specified for the same variable in
838 @code{minor-mode-map-alist}.
840 @code{minor-mode-overriding-map-alist} is automatically buffer-local in
844 @defvar overriding-local-map
845 If non-@code{nil}, this variable holds a keymap to use instead of the
846 buffer's local keymap, any text property or overlay keymaps, and any
847 minor mode keymaps. This keymap, if specified, overrides all other
848 maps that would have been active, except for the current global map.
851 @defvar overriding-terminal-local-map
852 If non-@code{nil}, this variable holds a keymap to use instead of
853 @code{overriding-local-map}, the buffer's local keymap, text property
854 or overlay keymaps, and all the minor mode keymaps.
856 This variable is always local to the current terminal and cannot be
857 buffer-local. @xref{Multiple Displays}. It is used to implement
858 incremental search mode.
861 @defvar overriding-local-map-menu-flag
862 If this variable is non-@code{nil}, the value of
863 @code{overriding-local-map} or @code{overriding-terminal-local-map} can
864 affect the display of the menu bar. The default value is @code{nil}, so
865 those map variables have no effect on the menu bar.
867 Note that these two map variables do affect the execution of key
868 sequences entered using the menu bar, even if they do not affect the
869 menu bar display. So if a menu bar key sequence comes in, you should
870 clear the variables before looking up and executing that key sequence.
871 Modes that use the variables would typically do this anyway; normally
872 they respond to events that they do not handle by ``unreading'' them and
876 @defvar special-event-map
877 This variable holds a keymap for special events. If an event type has a
878 binding in this keymap, then it is special, and the binding for the
879 event is run directly by @code{read-event}. @xref{Special Events}.
882 @defvar emulation-mode-map-alists
883 This variable holds a list of keymap alists to use for emulations
884 modes. It is intended for modes or packages using multiple minor-mode
885 keymaps. Each element is a keymap alist which has the same format and
886 meaning as @code{minor-mode-map-alist}, or a symbol with a variable
887 binding which is such an alist. The ``active'' keymaps in each alist
888 are used before @code{minor-mode-map-alist} and
889 @code{minor-mode-overriding-map-alist}.
897 @dfn{Key lookup} is the process of finding the binding of a key
898 sequence from a given keymap. The execution or use of the binding is
899 not part of key lookup.
901 Key lookup uses just the event type of each event in the key sequence;
902 the rest of the event is ignored. In fact, a key sequence used for key
903 lookup may designate a mouse event with just its types (a symbol)
904 instead of the entire event (a list). @xref{Input Events}. Such
905 a ``key sequence'' is insufficient for @code{command-execute} to run,
906 but it is sufficient for looking up or rebinding a key.
908 When the key sequence consists of multiple events, key lookup
909 processes the events sequentially: the binding of the first event is
910 found, and must be a keymap; then the second event's binding is found in
911 that keymap, and so on until all the events in the key sequence are used
912 up. (The binding thus found for the last event may or may not be a
913 keymap.) Thus, the process of key lookup is defined in terms of a
914 simpler process for looking up a single event in a keymap. How that is
915 done depends on the type of object associated with the event in that
918 Let's use the term @dfn{keymap entry} to describe the value found by
919 looking up an event type in a keymap. (This doesn't include the item
920 string and other extra elements in menu key bindings, because
921 @code{lookup-key} and other key lookup functions don't include them in
922 the returned value.) While any Lisp object may be stored in a keymap as
923 a keymap entry, not all make sense for key lookup. Here is a table of
924 the meaningful kinds of keymap entries:
928 @cindex @code{nil} in keymap
929 @code{nil} means that the events used so far in the lookup form an
930 undefined key. When a keymap fails to mention an event type at all, and
931 has no default binding, that is equivalent to a binding of @code{nil}
935 @cindex command in keymap
936 The events used so far in the lookup form a complete key,
937 and @var{command} is its binding. @xref{What Is a Function}.
940 @cindex string in keymap
941 The array (either a string or a vector) is a keyboard macro. The events
942 used so far in the lookup form a complete key, and the array is its
943 binding. See @ref{Keyboard Macros}, for more information.
946 @cindex keymap in keymap
947 The events used so far in the lookup form a prefix key. The next
948 event of the key sequence is looked up in @var{keymap}.
951 @cindex list in keymap
952 The meaning of a list depends on the types of the elements of the list.
956 If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
957 is a keymap, and is treated as a keymap (see above).
960 @cindex @code{lambda} in keymap
961 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
962 lambda expression. This is presumed to be a function, and is treated
963 as such (see above). In order to execute properly as a key binding,
964 this function must be a command---it must have an @code{interactive}
965 specification. @xref{Defining Commands}.
968 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
969 type, then this is an @dfn{indirect entry}:
972 (@var{othermap} . @var{othertype})
975 When key lookup encounters an indirect entry, it looks up instead the
976 binding of @var{othertype} in @var{othermap} and uses that.
978 This feature permits you to define one key as an alias for another key.
979 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
980 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
981 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
985 @cindex symbol in keymap
986 The function definition of @var{symbol} is used in place of
987 @var{symbol}. If that too is a symbol, then this process is repeated,
988 any number of times. Ultimately this should lead to an object that is
989 a keymap, a command, or a keyboard macro. A list is allowed if it is a
990 keymap or a command, but indirect entries are not understood when found
993 Note that keymaps and keyboard macros (strings and vectors) are not
994 valid functions, so a symbol with a keymap, string, or vector as its
995 function definition is invalid as a function. It is, however, valid as
996 a key binding. If the definition is a keyboard macro, then the symbol
997 is also valid as an argument to @code{command-execute}
998 (@pxref{Interactive Call}).
1000 @cindex @code{undefined} in keymap
1001 The symbol @code{undefined} is worth special mention: it means to treat
1002 the key as undefined. Strictly speaking, the key is defined, and its
1003 binding is the command @code{undefined}; but that command does the same
1004 thing that is done automatically for an undefined key: it rings the bell
1005 (by calling @code{ding}) but does not signal an error.
1007 @cindex preventing prefix key
1008 @code{undefined} is used in local keymaps to override a global key
1009 binding and make the key ``undefined'' locally. A local binding of
1010 @code{nil} would fail to do this because it would not override the
1013 @item @var{anything else}
1014 If any other type of object is found, the events used so far in the
1015 lookup form a complete key, and the object is its binding, but the
1016 binding is not executable as a command.
1019 In short, a keymap entry may be a keymap, a command, a keyboard macro,
1020 a symbol that leads to one of them, or an indirection or @code{nil}.
1021 Here is an example of a sparse keymap with two characters bound to
1022 commands and one bound to another keymap. This map is the normal value
1023 of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
1024 127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
1029 (keymap (9 . lisp-indent-line)
1030 (127 . backward-delete-char-untabify)
1031 (27 keymap (17 . indent-sexp) (24 . eval-defun)))
1035 @node Functions for Key Lookup
1036 @section Functions for Key Lookup
1038 Here are the functions and variables pertaining to key lookup.
1040 @defun lookup-key keymap key &optional accept-defaults
1041 This function returns the definition of @var{key} in @var{keymap}. All
1042 the other functions described in this chapter that look up keys use
1043 @code{lookup-key}. Here are examples:
1047 (lookup-key (current-global-map) "\C-x\C-f")
1051 (lookup-key (current-global-map) (kbd "C-x C-f"))
1055 (lookup-key (current-global-map) "\C-x\C-f12345")
1060 If the string or vector @var{key} is not a valid key sequence according
1061 to the prefix keys specified in @var{keymap}, it must be ``too long''
1062 and have extra events at the end that do not fit into a single key
1063 sequence. Then the value is a number, the number of events at the front
1064 of @var{key} that compose a complete key.
1067 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
1068 considers default bindings as well as bindings for the specific events
1069 in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
1070 the specific sequence @var{key}, ignoring default bindings except when
1071 you explicitly ask about them. (To do this, supply @code{t} as an
1072 element of @var{key}; see @ref{Format of Keymaps}.)
1074 If @var{key} contains a meta character (not a function key), that
1075 character is implicitly replaced by a two-character sequence: the value
1076 of @code{meta-prefix-char}, followed by the corresponding non-meta
1077 character. Thus, the first example below is handled by conversion into
1082 (lookup-key (current-global-map) "\M-f")
1083 @result{} forward-word
1086 (lookup-key (current-global-map) "\ef")
1087 @result{} forward-word
1091 Unlike @code{read-key-sequence}, this function does not modify the
1092 specified events in ways that discard information (@pxref{Key Sequence
1093 Input}). In particular, it does not convert letters to lower case and
1094 it does not change drag events to clicks.
1097 @deffn Command undefined
1098 Used in keymaps to undefine keys. It calls @code{ding}, but does
1102 @defun local-key-binding key &optional accept-defaults
1103 This function returns the binding for @var{key} in the current
1104 local keymap, or @code{nil} if it is undefined there.
1107 The argument @var{accept-defaults} controls checking for default bindings,
1108 as in @code{lookup-key} (above).
1111 @defun global-key-binding key &optional accept-defaults
1112 This function returns the binding for command @var{key} in the
1113 current global keymap, or @code{nil} if it is undefined there.
1116 The argument @var{accept-defaults} controls checking for default bindings,
1117 as in @code{lookup-key} (above).
1121 @defun minor-mode-key-binding key &optional accept-defaults
1122 This function returns a list of all the active minor mode bindings of
1123 @var{key}. More precisely, it returns an alist of pairs
1124 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
1125 variable that enables the minor mode, and @var{binding} is @var{key}'s
1126 binding in that mode. If @var{key} has no minor-mode bindings, the
1127 value is @code{nil}.
1129 If the first binding found is not a prefix definition (a keymap or a
1130 symbol defined as a keymap), all subsequent bindings from other minor
1131 modes are omitted, since they would be completely shadowed. Similarly,
1132 the list omits non-prefix bindings that follow prefix bindings.
1134 The argument @var{accept-defaults} controls checking for default
1135 bindings, as in @code{lookup-key} (above).
1138 @defvar meta-prefix-char
1140 This variable is the meta-prefix character code. It is used for
1141 translating a meta character to a two-character sequence so it can be
1142 looked up in a keymap. For useful results, the value should be a
1143 prefix event (@pxref{Prefix Keys}). The default value is 27, which is
1144 the @acronym{ASCII} code for @key{ESC}.
1146 As long as the value of @code{meta-prefix-char} remains 27, key lookup
1147 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
1148 as the @code{backward-word} command. However, if you were to set
1149 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
1150 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
1151 @code{switch-to-buffer} command. (Don't actually do this!) Here is an
1152 illustration of what would happen:
1156 meta-prefix-char ; @r{The default value.}
1160 (key-binding "\M-b")
1161 @result{} backward-word
1164 ?\C-x ; @r{The print representation}
1165 @result{} 24 ; @r{of a character.}
1168 (setq meta-prefix-char 24)
1172 (key-binding "\M-b")
1173 @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
1174 ; @r{like typing @kbd{C-x b}.}
1176 (setq meta-prefix-char 27) ; @r{Avoid confusion!}
1177 @result{} 27 ; @r{Restore the default value!}
1181 This translation of one event into two happens only for characters, not
1182 for other kinds of input events. Thus, @kbd{M-@key{F1}}, a function
1183 key, is not converted into @kbd{@key{ESC} @key{F1}}.
1186 @node Changing Key Bindings
1187 @section Changing Key Bindings
1188 @cindex changing key bindings
1191 The way to rebind a key is to change its entry in a keymap. If you
1192 change a binding in the global keymap, the change is effective in all
1193 buffers (though it has no direct effect in buffers that shadow the
1194 global binding with a local one). If you change the current buffer's
1195 local map, that usually affects all buffers using the same major mode.
1196 The @code{global-set-key} and @code{local-set-key} functions are
1197 convenient interfaces for these operations (@pxref{Key Binding
1198 Commands}). You can also use @code{define-key}, a more general
1199 function; then you must specify explicitly the map to change.
1201 When choosing the key sequences for Lisp programs to rebind, please
1202 follow the Emacs conventions for use of various keys (@pxref{Key
1203 Binding Conventions}).
1205 @cindex meta character key constants
1206 @cindex control character key constants
1207 In writing the key sequence to rebind, it is good to use the special
1208 escape sequences for control and meta characters (@pxref{String Type}).
1209 The syntax @samp{\C-} means that the following character is a control
1210 character and @samp{\M-} means that the following character is a meta
1211 character. Thus, the string @code{"\M-x"} is read as containing a
1212 single @kbd{M-x}, @code{"\C-f"} is read as containing a single
1213 @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
1214 containing a single @kbd{C-M-x}. You can also use this escape syntax in
1215 vectors, as well as others that aren't allowed in strings; one example
1216 is @samp{[?\C-\H-x home]}. @xref{Character Type}.
1218 The key definition and lookup functions accept an alternate syntax for
1219 event types in a key sequence that is a vector: you can use a list
1220 containing modifier names plus one base event (a character or function
1221 key name). For example, @code{(control ?a)} is equivalent to
1222 @code{?\C-a} and @code{(hyper control left)} is equivalent to
1223 @code{C-H-left}. One advantage of such lists is that the precise
1224 numeric codes for the modifier bits don't appear in compiled files.
1226 The functions below signal an error if @var{keymap} is not a keymap,
1227 or if @var{key} is not a string or vector representing a key sequence.
1228 You can use event types (symbols) as shorthand for events that are
1229 lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
1230 way to specify the key sequence.
1232 @defun define-key keymap key binding
1233 This function sets the binding for @var{key} in @var{keymap}. (If
1234 @var{key} is more than one event long, the change is actually made
1235 in another keymap reached from @var{keymap}.) The argument
1236 @var{binding} can be any Lisp object, but only certain types are
1237 meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
1238 The value returned by @code{define-key} is @var{binding}.
1240 If @var{key} is @code{[t]}, this sets the default binding in
1241 @var{keymap}. When an event has no binding of its own, the Emacs
1242 command loop uses the keymap's default binding, if there is one.
1244 @cindex invalid prefix key error
1245 @cindex key sequence error
1246 Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
1247 or undefined; otherwise an error is signaled. If some prefix of
1248 @var{key} is undefined, then @code{define-key} defines it as a prefix
1249 key so that the rest of @var{key} can be defined as specified.
1251 If there was previously no binding for @var{key} in @var{keymap}, the
1252 new binding is added at the beginning of @var{keymap}. The order of
1253 bindings in a keymap makes no difference for keyboard input, but it
1254 does matter for menu keymaps (@pxref{Menu Keymaps}).
1257 Here is an example that creates a sparse keymap and makes a number of
1262 (setq map (make-sparse-keymap))
1266 (define-key map "\C-f" 'forward-char)
1267 @result{} forward-char
1271 @result{} (keymap (6 . forward-char))
1275 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
1276 (define-key map (kbd "C-x f") 'forward-word)
1277 @result{} forward-word
1282 (24 keymap ; @kbd{C-x}
1283 (102 . forward-word)) ; @kbd{f}
1284 (6 . forward-char)) ; @kbd{C-f}
1288 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1289 (define-key map (kbd "C-p") ctl-x-map)
1291 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
1295 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1296 (define-key map (kbd "C-p C-f") 'foo)
1301 @result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
1302 (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1304 (102 . forward-word))
1310 Note that storing a new binding for @kbd{C-p C-f} actually works by
1311 changing an entry in @code{ctl-x-map}, and this has the effect of
1312 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1315 The function @code{substitute-key-definition} scans a keymap for
1316 keys that have a certain binding and rebinds them with a different
1317 binding. Another feature which is cleaner and can often produce the
1318 same results to remap one command into another (@pxref{Remapping
1321 @defun substitute-key-definition olddef newdef keymap &optional oldmap
1322 @cindex replace bindings
1323 This function replaces @var{olddef} with @var{newdef} for any keys in
1324 @var{keymap} that were bound to @var{olddef}. In other words,
1325 @var{olddef} is replaced with @var{newdef} wherever it appears. The
1326 function returns @code{nil}.
1328 For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
1333 (substitute-key-definition
1334 'find-file 'find-file-read-only (current-global-map))
1339 If @var{oldmap} is non-@code{nil}, that changes the behavior of
1340 @code{substitute-key-definition}: the bindings in @var{oldmap} determine
1341 which keys to rebind. The rebindings still happen in @var{keymap}, not
1342 in @var{oldmap}. Thus, you can change one map under the control of the
1343 bindings in another. For example,
1346 (substitute-key-definition
1347 'delete-backward-char 'my-funny-delete
1352 puts the special deletion command in @code{my-map} for whichever keys
1353 are globally bound to the standard deletion command.
1355 Here is an example showing a keymap before and after substitution:
1363 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1367 (substitute-key-definition 'olddef-1 'newdef map)
1372 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1377 @defun suppress-keymap keymap &optional nodigits
1378 @cindex @code{self-insert-command} override
1379 This function changes the contents of the full keymap @var{keymap} by
1380 remapping @code{self-insert-command} to the command @code{undefined}
1381 (@pxref{Remapping Commands}). This has the effect of undefining all
1382 printing characters, thus making ordinary insertion of text impossible.
1383 @code{suppress-keymap} returns @code{nil}.
1385 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1386 digits to run @code{digit-argument}, and @kbd{-} to run
1387 @code{negative-argument}. Otherwise it makes them undefined like the
1388 rest of the printing characters.
1390 @cindex yank suppression
1391 @cindex @code{quoted-insert} suppression
1392 The @code{suppress-keymap} function does not make it impossible to
1393 modify a buffer, as it does not suppress commands such as @code{yank}
1394 and @code{quoted-insert}. To prevent any modification of a buffer, make
1395 it read-only (@pxref{Read Only Buffers}).
1397 Since this function modifies @var{keymap}, you would normally use it
1398 on a newly created keymap. Operating on an existing keymap
1399 that is used for some other purpose is likely to cause trouble; for
1400 example, suppressing @code{global-map} would make it impossible to use
1403 Most often, @code{suppress-keymap} is used to initialize local
1404 keymaps of modes such as Rmail and Dired where insertion of text is not
1405 desirable and the buffer is read-only. Here is an example taken from
1406 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
1407 Dired mode is set up:
1411 (setq dired-mode-map (make-keymap))
1412 (suppress-keymap dired-mode-map)
1413 (define-key dired-mode-map "r" 'dired-rename-file)
1414 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1415 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1416 (define-key dired-mode-map "v" 'dired-view-file)
1417 (define-key dired-mode-map "e" 'dired-find-file)
1418 (define-key dired-mode-map "f" 'dired-find-file)
1424 @node Remapping Commands
1425 @section Remapping Commands
1426 @cindex remapping commands
1428 A special kind of key binding, using a special ``key sequence''
1429 which includes a command name, has the effect of @dfn{remapping} that
1430 command into another. Here's how it works. You make a key binding
1431 for a key sequence that starts with the dummy event @code{remap},
1432 followed by the command name you want to remap. Specify the remapped
1433 definition as the definition in this binding. The remapped definition
1434 is usually a command name, but it can be any valid definition for
1437 Here's an example. Suppose that My mode uses special commands
1438 @code{my-kill-line} and @code{my-kill-word}, which should be invoked
1439 instead of @code{kill-line} and @code{kill-word}. It can establish
1440 this by making these two command-remapping bindings in its keymap:
1443 (define-key my-mode-map [remap kill-line] 'my-kill-line)
1444 (define-key my-mode-map [remap kill-word] 'my-kill-word)
1447 Whenever @code{my-mode-map} is an active keymap, if the user types
1448 @kbd{C-k}, Emacs will find the standard global binding of
1449 @code{kill-line} (assuming nobody has changed it). But
1450 @code{my-mode-map} remaps @code{kill-line} to @code{my-kill-line},
1451 so instead of running @code{kill-line}, Emacs runs
1452 @code{my-kill-line}.
1454 Remapping only works through a single level. In other words,
1457 (define-key my-mode-map [remap kill-line] 'my-kill-line)
1458 (define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)
1462 does not have the effect of remapping @code{kill-line} into
1463 @code{my-other-kill-line}. If an ordinary key binding specifies
1464 @code{kill-line}, this keymap will remap it to @code{my-kill-line};
1465 if an ordinary binding specifies @code{my-kill-line}, this keymap will
1466 remap it to @code{my-other-kill-line}.
1468 @defun command-remapping command
1469 This function returns the remapping for @var{command} (a symbol),
1470 given the current active keymaps. If @var{command} is not remapped
1471 (which is the usual situation), or not a symbol, the function returns
1475 @node Key Binding Commands
1476 @section Commands for Binding Keys
1478 This section describes some convenient interactive interfaces for
1479 changing key bindings. They work by calling @code{define-key}.
1481 People often use @code{global-set-key} in their init files
1482 (@pxref{Init File}) for simple customization. For example,
1485 (global-set-key (kbd "C-x C-\\") 'next-line)
1492 (global-set-key [?\C-x ?\C-\\] 'next-line)
1499 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1503 redefines @kbd{C-x C-\} to move down a line.
1506 (global-set-key [M-mouse-1] 'mouse-set-point)
1510 redefines the first (leftmost) mouse button, entered with the Meta key, to
1511 set point where you click.
1513 @cindex non-@acronym{ASCII} text in keybindings
1514 Be careful when using non-@acronym{ASCII} text characters in Lisp
1515 specifications of keys to bind. If these are read as multibyte text, as
1516 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
1517 must type the keys as multibyte too. For instance, if you use this:
1520 (global-set-key "@"o" 'my-function) ; bind o-umlaut
1527 (global-set-key ?@"o 'my-function) ; bind o-umlaut
1531 and your language environment is multibyte Latin-1, these commands
1532 actually bind the multibyte character with code 2294, not the unibyte
1533 Latin-1 character with code 246 (@kbd{M-v}). In order to use this
1534 binding, you need to enter the multibyte Latin-1 character as keyboard
1535 input. One way to do this is by using an appropriate input method
1536 (@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}).
1538 If you want to use a unibyte character in the key binding, you can
1539 construct the key sequence string using @code{multibyte-char-to-unibyte}
1540 or @code{string-make-unibyte} (@pxref{Converting Representations}).
1542 @deffn Command global-set-key key binding
1543 This function sets the binding of @var{key} in the current global map
1548 (global-set-key @var{key} @var{binding})
1550 (define-key (current-global-map) @var{key} @var{binding})
1555 @deffn Command global-unset-key key
1556 @cindex unbinding keys
1557 This function removes the binding of @var{key} from the current
1560 One use of this function is in preparation for defining a longer key
1561 that uses @var{key} as a prefix---which would not be allowed if
1562 @var{key} has a non-prefix binding. For example:
1566 (global-unset-key "\C-l")
1570 (global-set-key "\C-l\C-l" 'redraw-display)
1575 This function is implemented simply using @code{define-key}:
1579 (global-unset-key @var{key})
1581 (define-key (current-global-map) @var{key} nil)
1586 @deffn Command local-set-key key binding
1587 This function sets the binding of @var{key} in the current local
1588 keymap to @var{binding}.
1592 (local-set-key @var{key} @var{binding})
1594 (define-key (current-local-map) @var{key} @var{binding})
1599 @deffn Command local-unset-key key
1600 This function removes the binding of @var{key} from the current
1605 (local-unset-key @var{key})
1607 (define-key (current-local-map) @var{key} nil)
1612 @node Scanning Keymaps
1613 @section Scanning Keymaps
1615 This section describes functions used to scan all the current keymaps
1616 for the sake of printing help information.
1618 @defun accessible-keymaps keymap &optional prefix
1619 This function returns a list of all the keymaps that can be reached (via
1620 zero or more prefix keys) from @var{keymap}. The value is an
1621 association list with elements of the form @code{(@var{key} .@:
1622 @var{map})}, where @var{key} is a prefix key whose definition in
1623 @var{keymap} is @var{map}.
1625 The elements of the alist are ordered so that the @var{key} increases
1626 in length. The first element is always @code{([] .@: @var{keymap})},
1627 because the specified keymap is accessible from itself with a prefix of
1630 If @var{prefix} is given, it should be a prefix key sequence; then
1631 @code{accessible-keymaps} includes only the submaps whose prefixes start
1632 with @var{prefix}. These elements look just as they do in the value of
1633 @code{(accessible-keymaps)}; the only difference is that some elements
1636 In the example below, the returned alist indicates that the key
1637 @key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
1638 definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
1643 (accessible-keymaps (current-local-map))
1644 @result{}(([] keymap
1645 (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
1646 (83 . center-paragraph)
1647 (115 . center-line))
1648 (9 . tab-to-tab-stop))
1653 (83 . center-paragraph)
1658 In the following example, @kbd{C-h} is a prefix key that uses a sparse
1659 keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
1660 Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
1661 the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of
1662 several dummy events used as prefixes for mouse actions in special parts
1667 (accessible-keymaps (current-global-map))
1668 @result{} (([] keymap [set-mark-command beginning-of-line @dots{}
1669 delete-backward-char])
1672 ("^H" keymap (118 . describe-variable) @dots{}
1673 (8 . help-for-help))
1676 ("^X" keymap [x-flush-mouse-queue @dots{}
1677 backward-kill-sentence])
1680 ("^[" keymap [mark-sexp backward-sexp @dots{}
1681 backward-kill-word])
1683 ("^X4" keymap (15 . display-buffer) @dots{})
1686 (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1691 These are not all the keymaps you would see in actuality.
1694 @defun map-keymap function keymap
1695 The function @code{map-keymap} calls @var{function} once
1696 for each binding in @var{keymap}. It passes two arguments,
1697 the event type and the value of the binding. If @var{keymap}
1698 has a parent, the parent's bindings are included as well.
1699 This works recursively: if the parent has itself a parent, then the
1700 grandparent's bindings are also included and so on.
1702 This function is the cleanest way to examine all the bindings
1706 @defun where-is-internal command &optional keymap firstonly noindirect no-remap
1707 This function is a subroutine used by the @code{where-is} command
1708 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
1709 of all key sequences (of any length) that are bound to @var{command} in a
1712 The argument @var{command} can be any object; it is compared with all
1713 keymap entries using @code{eq}.
1715 If @var{keymap} is @code{nil}, then the maps used are the current active
1716 keymaps, disregarding @code{overriding-local-map} (that is, pretending
1717 its value is @code{nil}). If @var{keymap} is a keymap, then the
1718 maps searched are @var{keymap} and the global keymap. If @var{keymap}
1719 is a list of keymaps, only those keymaps are searched.
1721 Usually it's best to use @code{overriding-local-map} as the expression
1722 for @var{keymap}. Then @code{where-is-internal} searches precisely the
1723 keymaps that are active. To search only the global map, pass
1724 @code{(keymap)} (an empty keymap) as @var{keymap}.
1726 If @var{firstonly} is @code{non-ascii}, then the value is a single
1727 vector representing the first key sequence found, rather than a list of
1728 all possible key sequences. If @var{firstonly} is @code{t}, then the
1729 value is the first key sequence, except that key sequences consisting
1730 entirely of @acronym{ASCII} characters (or meta variants of @acronym{ASCII}
1731 characters) are preferred to all other key sequences and that the
1732 return value can never be a menu binding.
1734 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1735 follow indirect keymap bindings. This makes it possible to search for
1736 an indirect definition itself.
1738 When command remapping is in effect (@pxref{Remapping Commands}),
1739 @code{where-is-internal} figures out when a command will be run due to
1740 remapping and reports keys accordingly. It also returns @code{nil} if
1741 @var{command} won't really be run because it has been remapped to some
1742 other command. However, if @var{no-remap} is non-@code{nil}.
1743 @code{where-is-internal} ignores remappings.
1747 (where-is-internal 'describe-function)
1748 @result{} ("\^hf" "\^hd")
1753 @deffn Command describe-bindings &optional prefix buffer-or-name
1754 This function creates a listing of all current key bindings, and
1755 displays it in a buffer named @samp{*Help*}. The text is grouped by
1756 modes---minor modes first, then the major mode, then global bindings.
1758 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
1759 listing includes only keys that start with @var{prefix}.
1761 The listing describes meta characters as @key{ESC} followed by the
1762 corresponding non-meta character.
1764 When several characters with consecutive @acronym{ASCII} codes have the
1765 same definition, they are shown together, as
1766 @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
1767 know the @acronym{ASCII} codes to understand which characters this means.
1768 For example, in the default global map, the characters @samp{@key{SPC}
1769 ..@: ~} are described by a single line. @key{SPC} is @acronym{ASCII} 32,
1770 @kbd{~} is @acronym{ASCII} 126, and the characters between them include all
1771 the normal printing characters, (e.g., letters, digits, punctuation,
1772 etc.@:); all these characters are bound to @code{self-insert-command}.
1774 If @var{buffer-or-name} is non-@code{nil}, it should be a buffer or a
1775 buffer name. Then @code{describe-bindings} lists that buffer's bindings,
1776 instead of the current buffer's.
1780 @section Menu Keymaps
1781 @cindex menu keymaps
1784 A keymap can define a menu as well as bindings for keyboard keys and
1785 mouse button. Menus are usually actuated with the mouse, but they can
1786 work with the keyboard also.
1789 * Defining Menus:: How to make a keymap that defines a menu.
1790 * Mouse Menus:: How users actuate the menu with the mouse.
1791 * Keyboard Menus:: How they actuate it with the keyboard.
1792 * Menu Example:: Making a simple menu.
1793 * Menu Bar:: How to customize the menu bar.
1794 * Tool Bar:: A tool bar is a row of images.
1795 * Modifying Menus:: How to add new items to a menu.
1798 @node Defining Menus
1799 @subsection Defining Menus
1800 @cindex defining menus
1801 @cindex menu prompt string
1802 @cindex prompt string (of menu)
1804 A keymap is suitable for menu use if it has an @dfn{overall prompt
1805 string}, which is a string that appears as an element of the keymap.
1806 (@xref{Format of Keymaps}.) The string should describe the purpose of
1807 the menu's commands. Emacs displays the overall prompt string as the
1808 menu title in some cases, depending on the toolkit (if any) used for
1809 displaying menus.@footnote{It is required for menus which do not use a
1810 toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the overall
1813 The easiest way to construct a keymap with a prompt string is to specify
1814 the string as an argument when you call @code{make-keymap},
1815 @code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
1816 @code{define-prefix-command} (@pxref{Definition of define-prefix-command}).
1819 @defun keymap-prompt keymap
1820 This function returns the overall prompt string of @var{keymap},
1821 or @code{nil} if it has none.
1824 The order of items in the menu is the same as the order of bindings in
1825 the keymap. Since @code{define-key} puts new bindings at the front, you
1826 should define the menu items starting at the bottom of the menu and
1827 moving to the top, if you care about the order. When you add an item to
1828 an existing menu, you can specify its position in the menu using
1829 @code{define-key-after} (@pxref{Modifying Menus}).
1832 * Simple Menu Items:: A simple kind of menu key binding,
1833 limited in capabilities.
1834 * Extended Menu Items:: More powerful menu item definitions
1835 let you specify keywords to enable
1837 * Menu Separators:: Drawing a horizontal line through a menu.
1838 * Alias Menu Items:: Using command aliases in menu items.
1841 @node Simple Menu Items
1842 @subsubsection Simple Menu Items
1844 The simpler and older way to define a menu keymap binding
1848 (@var{item-string} . @var{real-binding})
1852 The @sc{car}, @var{item-string}, is the string to be displayed in the
1853 menu. It should be short---preferably one to three words. It should
1854 describe the action of the command it corresponds to. Note that it is
1855 not generally possible to display non-@acronym{ASCII} text in menus. It will
1856 work for keyboard menus and will work to a large extent when Emacs is
1857 built with the Gtk+ toolkit.@footnote{In this case, the text is first
1858 encoded using the @code{utf-8} coding system and then rendered by the
1859 toolkit as it sees fit.}
1861 You can also supply a second string, called the help string, as follows:
1864 (@var{item-string} @var{help} . @var{real-binding})
1867 @var{help} specifies a ``help-echo'' string to display while the mouse
1868 is on that item in the same way as @code{help-echo} text properties
1869 (@pxref{Help display}).
1871 As far as @code{define-key} is concerned, @var{item-string} and
1872 @var{help-string} are part of the event's binding. However,
1873 @code{lookup-key} returns just @var{real-binding}, and only
1874 @var{real-binding} is used for executing the key.
1876 If @var{real-binding} is @code{nil}, then @var{item-string} appears in
1877 the menu but cannot be selected.
1879 If @var{real-binding} is a symbol and has a non-@code{nil}
1880 @code{menu-enable} property, that property is an expression that
1881 controls whether the menu item is enabled. Every time the keymap is
1882 used to display a menu, Emacs evaluates the expression, and it enables
1883 the menu item only if the expression's value is non-@code{nil}. When a
1884 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
1887 The menu bar does not recalculate which items are enabled every time you
1888 look at a menu. This is because the X toolkit requires the whole tree
1889 of menus in advance. To force recalculation of the menu bar, call
1890 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1892 You've probably noticed that menu items show the equivalent keyboard key
1893 sequence (if any) to invoke the same command. To save time on
1894 recalculation, menu display caches this information in a sublist in the
1897 @c This line is not too long--rms.
1899 (@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
1903 Don't put these sublists in the menu item yourself; menu display
1904 calculates them automatically. Don't mention keyboard equivalents in
1905 the item strings themselves, since that is redundant.
1907 @node Extended Menu Items
1908 @subsubsection Extended Menu Items
1911 An extended-format menu item is a more flexible and also cleaner
1912 alternative to the simple format. It consists of a list that starts
1913 with the symbol @code{menu-item}. To define a non-selectable string,
1914 the item looks like this:
1917 (menu-item @var{item-name})
1921 A string starting with two or more dashes specifies a separator line;
1922 see @ref{Menu Separators}.
1924 To define a real menu item which can be selected, the extended format
1925 item looks like this:
1928 (menu-item @var{item-name} @var{real-binding}
1929 . @var{item-property-list})
1933 Here, @var{item-name} is an expression which evaluates to the menu item
1934 string. Thus, the string need not be a constant. The third element,
1935 @var{real-binding}, is the command to execute. The tail of the list,
1936 @var{item-property-list}, has the form of a property list which contains
1937 other information. Here is a table of the properties that are supported:
1940 @item :enable @var{form}
1941 The result of evaluating @var{form} determines whether the item is
1942 enabled (non-@code{nil} means yes). If the item is not enabled,
1943 you can't really click on it.
1945 @item :visible @var{form}
1946 The result of evaluating @var{form} determines whether the item should
1947 actually appear in the menu (non-@code{nil} means yes). If the item
1948 does not appear, then the menu is displayed as if this item were
1951 @item :help @var{help}
1952 The value of this property, @var{help}, specifies a ``help-echo'' string
1953 to display while the mouse is on that item. This is displayed in the
1954 same way as @code{help-echo} text properties (@pxref{Help display}).
1955 Note that this must be a constant string, unlike the @code{help-echo}
1956 property for text and overlays.
1958 @item :button (@var{type} . @var{selected})
1959 This property provides a way to define radio buttons and toggle buttons.
1960 The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
1961 @code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
1962 result of evaluating it says whether this button is currently selected.
1964 A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
1965 according to the value of @var{selected}. The command itself should
1966 toggle @var{selected}, setting it to @code{t} if it is @code{nil},
1967 and to @code{nil} if it is @code{t}. Here is how the menu item
1968 to toggle the @code{debug-on-error} flag is defined:
1971 (menu-item "Debug on Error" toggle-debug-on-error
1973 . (and (boundp 'debug-on-error)
1978 This works because @code{toggle-debug-on-error} is defined as a command
1979 which toggles the variable @code{debug-on-error}.
1981 @dfn{Radio buttons} are a group of menu items, in which at any time one
1982 and only one is ``selected.'' There should be a variable whose value
1983 says which one is selected at any time. The @var{selected} form for
1984 each radio button in the group should check whether the variable has the
1985 right value for selecting that button. Clicking on the button should
1986 set the variable so that the button you clicked on becomes selected.
1988 @item :key-sequence @var{key-sequence}
1989 This property specifies which key sequence is likely to be bound to the
1990 same command invoked by this menu item. If you specify the right key
1991 sequence, that makes preparing the menu for display run much faster.
1993 If you specify the wrong key sequence, it has no effect; before Emacs
1994 displays @var{key-sequence} in the menu, it verifies that
1995 @var{key-sequence} is really equivalent to this menu item.
1997 @item :key-sequence nil
1998 This property indicates that there is normally no key binding which is
1999 equivalent to this menu item. Using this property saves time in
2000 preparing the menu for display, because Emacs does not need to search
2001 the keymaps for a keyboard equivalent for this menu item.
2003 However, if the user has rebound this item's definition to a key
2004 sequence, Emacs ignores the @code{:keys} property and finds the keyboard
2007 @item :keys @var{string}
2008 This property specifies that @var{string} is the string to display
2009 as the keyboard equivalent for this menu item. You can use
2010 the @samp{\\[...]} documentation construct in @var{string}.
2012 @item :filter @var{filter-fn}
2013 This property provides a way to compute the menu item dynamically.
2014 The property value @var{filter-fn} should be a function of one argument;
2015 when it is called, its argument will be @var{real-binding}. The
2016 function should return the binding to use instead.
2018 Emacs can call this function at any time that it does redisplay or
2019 operates on menu data structures, so you should write it so it can
2020 safely be called at any time.
2023 @node Menu Separators
2024 @subsubsection Menu Separators
2025 @cindex menu separators
2027 A menu separator is a kind of menu item that doesn't display any
2028 text---instead, it divides the menu into subparts with a horizontal line.
2029 A separator looks like this in the menu keymap:
2032 (menu-item @var{separator-type})
2036 where @var{separator-type} is a string starting with two or more dashes.
2038 In the simplest case, @var{separator-type} consists of only dashes.
2039 That specifies the default kind of separator. (For compatibility,
2040 @code{""} and @code{-} also count as separators.)
2042 Certain other values of @var{separator-type} specify a different
2043 style of separator. Here is a table of them:
2048 An extra vertical space, with no actual line.
2050 @item "--single-line"
2051 A single line in the menu's foreground color.
2053 @item "--double-line"
2054 A double line in the menu's foreground color.
2056 @item "--single-dashed-line"
2057 A single dashed line in the menu's foreground color.
2059 @item "--double-dashed-line"
2060 A double dashed line in the menu's foreground color.
2062 @item "--shadow-etched-in"
2063 A single line with a 3D sunken appearance. This is the default,
2064 used separators consisting of dashes only.
2066 @item "--shadow-etched-out"
2067 A single line with a 3D raised appearance.
2069 @item "--shadow-etched-in-dash"
2070 A single dashed line with a 3D sunken appearance.
2072 @item "--shadow-etched-out-dash"
2073 A single dashed line with a 3D raised appearance.
2075 @item "--shadow-double-etched-in"
2076 Two lines with a 3D sunken appearance.
2078 @item "--shadow-double-etched-out"
2079 Two lines with a 3D raised appearance.
2081 @item "--shadow-double-etched-in-dash"
2082 Two dashed lines with a 3D sunken appearance.
2084 @item "--shadow-double-etched-out-dash"
2085 Two dashed lines with a 3D raised appearance.
2088 You can also give these names in another style, adding a colon after
2089 the double-dash and replacing each single dash with capitalization of
2090 the following word. Thus, @code{"--:singleLine"}, is equivalent to
2091 @code{"--single-line"}.
2093 Some systems and display toolkits don't really handle all of these
2094 separator types. If you use a type that isn't supported, the menu
2095 displays a similar kind of separator that is supported.
2097 @node Alias Menu Items
2098 @subsubsection Alias Menu Items
2100 Sometimes it is useful to make menu items that use the ``same''
2101 command but with different enable conditions. The best way to do this
2102 in Emacs now is with extended menu items; before that feature existed,
2103 it could be done by defining alias commands and using them in menu
2104 items. Here's an example that makes two aliases for
2105 @code{toggle-read-only} and gives them different enable conditions:
2108 (defalias 'make-read-only 'toggle-read-only)
2109 (put 'make-read-only 'menu-enable '(not buffer-read-only))
2110 (defalias 'make-writable 'toggle-read-only)
2111 (put 'make-writable 'menu-enable 'buffer-read-only)
2114 When using aliases in menus, often it is useful to display the
2115 equivalent key bindings for the ``real'' command name, not the aliases
2116 (which typically don't have any key bindings except for the menu
2117 itself). To request this, give the alias symbol a non-@code{nil}
2118 @code{menu-alias} property. Thus,
2121 (put 'make-read-only 'menu-alias t)
2122 (put 'make-writable 'menu-alias t)
2126 causes menu items for @code{make-read-only} and @code{make-writable} to
2127 show the keyboard bindings for @code{toggle-read-only}.
2130 @subsection Menus and the Mouse
2132 The usual way to make a menu keymap produce a menu is to make it the
2133 definition of a prefix key. (A Lisp program can explicitly pop up a
2134 menu and receive the user's choice---see @ref{Pop-Up Menus}.)
2136 If the prefix key ends with a mouse event, Emacs handles the menu keymap
2137 by popping up a visible menu, so that the user can select a choice with
2138 the mouse. When the user clicks on a menu item, the event generated is
2139 whatever character or symbol has the binding that brought about that
2140 menu item. (A menu item may generate a series of events if the menu has
2141 multiple levels or comes from the menu bar.)
2143 It's often best to use a button-down event to trigger the menu. Then
2144 the user can select a menu item by releasing the button.
2146 A single keymap can appear as multiple menu panes, if you explicitly
2147 arrange for this. The way to do this is to make a keymap for each pane,
2148 then create a binding for each of those maps in the main keymap of the
2149 menu. Give each of these bindings an item string that starts with
2150 @samp{@@}. The rest of the item string becomes the name of the pane.
2151 See the file @file{lisp/mouse.el} for an example of this. Any ordinary
2152 bindings with @samp{@@}-less item strings are grouped into one pane,
2153 which appears along with the other panes explicitly created for the
2156 X toolkit menus don't have panes; instead, they can have submenus.
2157 Every nested keymap becomes a submenu, whether the item string starts
2158 with @samp{@@} or not. In a toolkit version of Emacs, the only thing
2159 special about @samp{@@} at the beginning of an item string is that the
2160 @samp{@@} doesn't appear in the menu item.
2162 Multiple keymaps that define the same menu prefix key produce
2163 separate panes or separate submenus.
2165 @node Keyboard Menus
2166 @subsection Menus and the Keyboard
2168 When a prefix key ending with a keyboard event (a character or function
2169 key) has a definition that is a menu keymap, the user can use the
2170 keyboard to choose a menu item.
2172 Emacs displays the menu's overall prompt string followed by the
2173 alternatives (the item strings of the bindings) in the echo area. If
2174 the bindings don't all fit at once, the user can type @key{SPC} to see
2175 the next line of alternatives. Successive uses of @key{SPC} eventually
2176 get to the end of the menu and then cycle around to the beginning. (The
2177 variable @code{menu-prompt-more-char} specifies which character is used
2178 for this; @key{SPC} is the default.)
2180 When the user has found the desired alternative from the menu, he or she
2181 should type the corresponding character---the one whose binding is that
2185 In a menu intended for keyboard use, each menu item must clearly
2186 indicate what character to type. The best convention to use is to make
2187 the character the first letter of the item string---that is something
2188 users will understand without being told. We plan to change this; by
2189 the time you read this manual, keyboard menus may explicitly name the
2190 key for each alternative.
2193 This way of using menus in an Emacs-like editor was inspired by the
2196 @defvar menu-prompt-more-char
2197 This variable specifies the character to use to ask to see
2198 the next line of a menu. Its initial value is 32, the code
2203 @subsection Menu Example
2204 @cindex menu definition example
2206 Here is a complete example of defining a menu keymap. It is the
2207 definition of the @samp{Replace} submenu in the @samp{Edit} menu in
2208 the menu bar, and it uses the extended menu item format
2209 (@pxref{Extended Menu Items}). First we create the keymap, and give
2213 (defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))
2217 Next we define the menu items:
2220 (define-key menu-bar-replace-menu [tags-repl-continue]
2221 '(menu-item "Continue Replace" tags-loop-continue
2222 :help "Continue last tags replace operation"))
2223 (define-key menu-bar-replace-menu [tags-repl]
2224 '(menu-item "Replace in tagged files" tags-query-replace
2225 :help "Interactively replace a regexp in all tagged files"))
2226 (define-key menu-bar-replace-menu [separator-replace-tags]
2232 Note the symbols which the bindings are ``made for''; these appear
2233 inside square brackets, in the key sequence being defined. In some
2234 cases, this symbol is the same as the command name; sometimes it is
2235 different. These symbols are treated as ``function keys'', but they are
2236 not real function keys on the keyboard. They do not affect the
2237 functioning of the menu itself, but they are ``echoed'' in the echo area
2238 when the user selects from the menu, and they appear in the output of
2239 @code{where-is} and @code{apropos}.
2241 The menu in this example is intended for use with the mouse. If a
2242 menu is intended for use with the keyboard, that is, if it is bound to
2243 a key sequence ending with a keyboard event, then the menu items
2244 should be bound to characters or ``real'' function keys, that can be
2245 typed with the keyboard.
2247 The binding whose definition is @code{("--")} is a separator line.
2248 Like a real menu item, the separator has a key symbol, in this case
2249 @code{separator-replace-tags}. If one menu has two separators, they
2250 must have two different key symbols.
2252 Here is how we make this menu appear as an item in the parent menu:
2255 (define-key menu-bar-edit-menu [replace]
2256 (list 'menu-item "Replace" menu-bar-replace-menu))
2260 Note that this incorporates the submenu keymap, which is the value of
2261 the variable @code{menu-bar-replace-menu}, rather than the symbol
2262 @code{menu-bar-replace-menu} itself. Using that symbol in the parent
2263 menu item would be meaningless because @code{menu-bar-replace-menu} is
2266 If you wanted to attach the same replace menu to a mouse click, you
2270 (define-key global-map [C-S-down-mouse-1]
2271 menu-bar-replace-menu)
2275 @subsection The Menu Bar
2278 Most window systems allow each frame to have a @dfn{menu bar}---a
2279 permanently displayed menu stretching horizontally across the top of the
2280 frame. The items of the menu bar are the subcommands of the fake
2281 ``function key'' @code{menu-bar}, as defined in the active keymaps.
2283 To add an item to the menu bar, invent a fake ``function key'' of your
2284 own (let's call it @var{key}), and make a binding for the key sequence
2285 @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
2286 so that pressing a button on the menu bar item leads to another menu.
2288 When more than one active keymap defines the same fake function key
2289 for the menu bar, the item appears just once. If the user clicks on
2290 that menu bar item, it brings up a single, combined menu containing
2291 all the subcommands of that item---the global subcommands, the local
2292 subcommands, and the minor mode subcommands.
2294 The variable @code{overriding-local-map} is normally ignored when
2295 determining the menu bar contents. That is, the menu bar is computed
2296 from the keymaps that would be active if @code{overriding-local-map}
2297 were @code{nil}. @xref{Active Keymaps}.
2299 In order for a frame to display a menu bar, its @code{menu-bar-lines}
2300 parameter must be greater than zero. Emacs uses just one line for the
2301 menu bar itself; if you specify more than one line, the other lines
2302 serve to separate the menu bar from the windows in the frame. We
2303 recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Layout
2306 Here's an example of setting up a menu bar item:
2310 (modify-frame-parameters (selected-frame)
2311 '((menu-bar-lines . 2)))
2315 ;; @r{Make a menu keymap (with a prompt string)}
2316 ;; @r{and make it the menu bar item's definition.}
2317 (define-key global-map [menu-bar words]
2318 (cons "Words" (make-sparse-keymap "Words")))
2322 ;; @r{Define specific subcommands in this menu.}
2323 (define-key global-map
2324 [menu-bar words forward]
2325 '("Forward word" . forward-word))
2328 (define-key global-map
2329 [menu-bar words backward]
2330 '("Backward word" . backward-word))
2334 A local keymap can cancel a menu bar item made by the global keymap by
2335 rebinding the same fake function key with @code{undefined} as the
2336 binding. For example, this is how Dired suppresses the @samp{Edit} menu
2340 (define-key dired-mode-map [menu-bar edit] 'undefined)
2344 @code{edit} is the fake function key used by the global map for the
2345 @samp{Edit} menu bar item. The main reason to suppress a global
2346 menu bar item is to regain space for mode-specific items.
2348 @defvar menu-bar-final-items
2349 Normally the menu bar shows global items followed by items defined by the
2352 This variable holds a list of fake function keys for items to display at
2353 the end of the menu bar rather than in normal sequence. The default
2354 value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
2355 at the end of the menu bar, following local menu items.
2358 @defvar menu-bar-update-hook
2359 This normal hook is run by redisplay to update the menu bar contents,
2360 before redisplaying the menu bar. You can use it to update submenus
2361 whose contents should vary. Since this hook is run frequently, we
2362 advise you to ensure that the functions it calls do not take much time
2367 @subsection Tool bars
2370 A @dfn{tool bar} is a row of icons at the top of a frame, that execute
2371 commands when you click on them---in effect, a kind of graphical menu
2374 The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
2375 controls how many lines' worth of height to reserve for the tool bar. A
2376 zero value suppresses the tool bar. If the value is nonzero, and
2377 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
2378 contracts automatically as needed to hold the specified contents.
2380 The tool bar contents are controlled by a menu keymap attached to a
2381 fake ``function key'' called @code{tool-bar} (much like the way the menu
2382 bar is controlled). So you define a tool bar item using
2383 @code{define-key}, like this:
2386 (define-key global-map [tool-bar @var{key}] @var{item})
2390 where @var{key} is a fake ``function key'' to distinguish this item from
2391 other items, and @var{item} is a menu item key binding (@pxref{Extended
2392 Menu Items}), which says how to display this item and how it behaves.
2394 The usual menu keymap item properties, @code{:visible},
2395 @code{:enable}, @code{:button}, and @code{:filter}, are useful in
2396 tool bar bindings and have their normal meanings. The @var{real-binding}
2397 in the item must be a command, not a keymap; in other words, it does not
2398 work to define a tool bar icon as a prefix key.
2400 The @code{:help} property specifies a ``help-echo'' string to display
2401 while the mouse is on that item. This is displayed in the same way as
2402 @code{help-echo} text properties (@pxref{Help display}).
2404 In addition, you should use the @code{:image} property;
2405 this is how you specify the image to display in the tool bar:
2408 @item :image @var{image}
2409 @var{images} is either a single image specification or a vector of four
2410 image specifications. If you use a vector of four,
2411 one of them is used, depending on circumstances:
2415 Used when the item is enabled and selected.
2417 Used when the item is enabled and deselected.
2419 Used when the item is disabled and selected.
2421 Used when the item is disabled and deselected.
2425 If @var{image} is a single image specification, Emacs draws the tool bar
2426 button in disabled state by applying an edge-detection algorithm to the
2429 The default tool bar is defined so that items specific to editing do not
2430 appear for major modes whose command symbol has a @code{mode-class}
2431 property of @code{special} (@pxref{Major Mode Conventions}). Major
2432 modes may add items to the global bar by binding @code{[tool-bar
2433 @var{foo}]} in their local map. It makes sense for some major modes to
2434 replace the default tool bar items completely, since not many can be
2435 accommodated conveniently, and the default bindings make this easy by
2436 using an indirection through @code{tool-bar-map}.
2438 @defvar tool-bar-map
2439 By default, the global map binds @code{[tool-bar]} as follows:
2441 (global-set-key [tool-bar]
2442 '(menu-item "tool bar" ignore
2443 :filter (lambda (ignore) tool-bar-map)))
2446 Thus the tool bar map is derived dynamically from the value of variable
2447 @code{tool-bar-map} and you should normally adjust the default (global)
2448 tool bar by changing that map. Major modes may replace the global bar
2449 completely by making @code{tool-bar-map} buffer-local and set to a
2450 keymap containing only the desired items. Info mode provides an
2454 There are two convenience functions for defining tool bar items, as
2457 @defun tool-bar-add-item icon def key &rest props
2458 This function adds an item to the tool bar by modifying
2459 @code{tool-bar-map}. The image to use is defined by @var{icon}, which
2460 is the base name of an XPM, XBM or PBM image file to be located by
2461 @code{find-image}. Given a value @samp{"exit"}, say, @file{exit.xpm},
2462 @file{exit.pbm} and @file{exit.xbm} would be searched for in that order
2463 on a color display. On a monochrome display, the search order is
2464 @samp{.pbm}, @samp{.xbm} and @samp{.xpm}. The binding to use is the
2465 command @var{def}, and @var{key} is the fake function key symbol in the
2466 prefix keymap. The remaining arguments @var{props} are additional
2467 property list elements to add to the menu item specification.
2469 To define items in some local map, bind @code{tool-bar-map} with
2470 @code{let} around calls of this function:
2472 (defvar foo-tool-bar-map
2473 (let ((tool-bar-map (make-sparse-keymap)))
2474 (tool-bar-add-item @dots{})
2480 @defun tool-bar-add-item-from-menu command icon &optional map &rest props
2481 This function is a convenience for defining tool bar items which are
2482 consistent with existing menu bar bindings. The binding of
2483 @var{command} is looked up in the menu bar in @var{map} (default
2484 @code{global-map}) and modified to add an image specification for
2485 @var{icon}, which is found in the same way as by
2486 @code{tool-bar-add-item}. The resulting binding is then placed in
2487 @code{tool-bar-map}, so use this function only for global tool bar
2490 @var{map} must contain an appropriate keymap bound to
2491 @code{[menu-bar]}. The remaining arguments @var{props} are additional
2492 property list elements to add to the menu item specification.
2495 @defun tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props
2496 This function is used for making non-global tool bar items. Use it
2497 like @code{tool-bar-add-item-from-menu} except that @var{in-map}
2498 specifies the local map to make the definition in. The argument
2499 @var{from-map} is like the @var{map} argument of
2500 @code{tool-bar-add-item-from-menu}.
2503 @defvar auto-resize-tool-bar
2504 If this variable is non-@code{nil}, the tool bar automatically resizes to
2505 show all defined tool bar items---but not larger than a quarter of the
2509 @defvar auto-raise-tool-bar-buttons
2510 If this variable is non-@code{nil}, tool bar items display
2511 in raised form when the mouse moves over them.
2514 @defvar tool-bar-button-margin
2515 This variable specifies an extra margin to add around tool bar items.
2516 The value is an integer, a number of pixels. The default is 4.
2519 @defvar tool-bar-button-relief
2520 This variable specifies the shadow width for tool bar items.
2521 The value is an integer, a number of pixels. The default is 1.
2524 @defvar tool-bar-border
2525 This variable specifies the height of the border drawn below the tool
2526 bar area. An integer value specifies height as a number of pixels.
2527 If the value is one of @code{internal-border-width} (the default) or
2528 @code{border-width}, the tool bar border height corresponds to the
2529 corresponding frame parameter.
2532 You can define a special meaning for clicking on a tool bar item with
2533 the shift, control, meta, etc., modifiers. You do this by setting up
2534 additional items that relate to the original item through the fake
2535 function keys. Specifically, the additional items should use the
2536 modified versions of the same fake function key used to name the
2539 Thus, if the original item was defined this way,
2542 (define-key global-map [tool-bar shell]
2543 '(menu-item "Shell" shell
2544 :image (image :type xpm :file "shell.xpm")))
2548 then here is how you can define clicking on the same tool bar image with
2552 (define-key global-map [tool-bar S-shell] 'some-command)
2555 @xref{Function Keys}, for more information about how to add modifiers to
2558 @node Modifying Menus
2559 @subsection Modifying Menus
2561 When you insert a new item in an existing menu, you probably want to
2562 put it in a particular place among the menu's existing items. If you
2563 use @code{define-key} to add the item, it normally goes at the front of
2564 the menu. To put it elsewhere in the menu, use @code{define-key-after}:
2566 @defun define-key-after map key binding &optional after
2567 Define a binding in @var{map} for @var{key}, with value @var{binding},
2568 just like @code{define-key}, but position the binding in @var{map} after
2569 the binding for the event @var{after}. The argument @var{key} should be
2570 of length one---a vector or string with just one element. But
2571 @var{after} should be a single event type---a symbol or a character, not
2572 a sequence. The new binding goes after the binding for @var{after}. If
2573 @var{after} is @code{t} or is omitted, then the new binding goes last, at
2574 the end of the keymap. However, new bindings are added before any
2580 (define-key-after my-menu [drink]
2581 '("Drink" . drink-command) 'eat)
2585 makes a binding for the fake function key @key{DRINK} and puts it
2586 right after the binding for @key{EAT}.
2588 Here is how to insert an item called @samp{Work} in the @samp{Signals}
2589 menu of Shell mode, after the item @code{break}:
2593 (lookup-key shell-mode-map [menu-bar signals])
2594 [work] '("Work" . work-command) 'break)
2599 arch-tag: cfb87287-9364-4e46-9e93-6c2f7f6ae794