2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/keymaps
6 @node Keymaps, Modes, Command Loop, Top
10 The bindings between input events and commands are recorded in data
11 structures called @dfn{keymaps}. Each binding in a keymap associates
12 (or @dfn{binds}) an individual event type either with another keymap or
13 with a command. When an event is bound to a keymap, that keymap is
14 used to look up the next input event; this continues until a command
15 is found. The whole process is called @dfn{key lookup}.
18 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
19 * Format of Keymaps:: What a keymap looks like as a Lisp object.
20 * Creating Keymaps:: Functions to create and copy keymaps.
21 * Inheritance and Keymaps:: How one keymap can inherit the bindings
23 * Prefix Keys:: Defining a key with a keymap as its definition.
24 * Active Keymaps:: Each buffer has a local keymap
25 to override the standard (global) bindings.
26 A minor mode can also override them.
27 * Key Lookup:: How extracting elements from keymaps works.
28 * Functions for Key Lookup:: How to request key lookup.
29 * Changing Key Bindings:: Redefining a key in a keymap.
30 * Key Binding Commands:: Interactive interfaces for redefining keys.
31 * Scanning Keymaps:: Looking through all keymaps, for printing help.
32 * Menu Keymaps:: A keymap can define a menu.
35 @node Keymap Terminology
36 @section Keymap Terminology
40 @cindex binding of a key
44 A @dfn{keymap} is a table mapping event types to definitions (which
45 can be any Lisp objects, though only certain types are meaningful for
46 execution by the command loop). Given an event (or an event type) and a
47 keymap, Emacs can get the event's definition. Events include ordinary
48 @sc{ASCII} characters, function keys, and mouse actions (@pxref{Input
51 A sequence of input events that form a unit is called a
52 @dfn{key sequence}, or @dfn{key} for short. A sequence of one event
53 is always a key sequence, and so are some multi-event sequences.
55 A keymap determines a binding or definition for any key sequence. If
56 the key sequence is a single event, its binding is the definition of the
57 event in the keymap. The binding of a key sequence of more than one
58 event is found by an iterative process: the binding of the first event
59 is found, and must be a keymap; then the second event's binding is found
60 in that keymap, and so on until all the events in the key sequence are
63 If the binding of a key sequence is a keymap, we call the key sequence
64 a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
65 no more events can be added to it). If the binding is @code{nil},
66 we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
67 @kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
68 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
69 keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more
72 The rule for finding the binding of a key sequence assumes that the
73 intermediate bindings (found for the events before the last) are all
74 keymaps; if this is not so, the sequence of events does not form a
75 unit---it is not really a key sequence. In other words, removing one or
76 more events from the end of any valid key must always yield a prefix
77 key. For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix
78 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
80 Note that the set of possible multi-event key sequences depends on the
81 bindings for prefix keys; therefore, it can be different for different
82 keymaps, and can change when bindings are changed. However, a one-event
83 sequence is always a key sequence, because it does not depend on any
84 prefix keys for its well-formedness.
86 At any time, several primary keymaps are @dfn{active}---that is, in
87 use for finding key bindings. These are the @dfn{global map}, which is
88 shared by all buffers; the @dfn{local keymap}, which is usually
89 associated with a specific major mode; and zero or more @dfn{minor mode
90 keymaps}, which belong to currently enabled minor modes. (Not all minor
91 modes have keymaps.) The local keymap bindings shadow (i.e., take
92 precedence over) the corresponding global bindings. The minor mode
93 keymaps shadow both local and global keymaps. @xref{Active Keymaps},
96 @node Format of Keymaps
97 @section Format of Keymaps
98 @cindex format of keymaps
101 @cindex sparse keymap
103 A keymap is a list whose @sc{car} is the symbol @code{keymap}. The
104 remaining elements of the list define the key bindings of the keymap.
105 Use the function @code{keymapp} (see below) to test whether an object is
108 Each ordinary binding applies to events of a particular @dfn{event
109 type}, which is always a character or a symbol. @xref{Classifying
112 An ordinary element of a keymap is a cons cell of the form
113 @code{(@var{type} .@: @var{binding})}. This specifies one binding, for
114 events of type @var{type}.
116 @cindex default key binding
118 A cons cell whose @sc{car} is @code{t} is a @dfn{default key binding};
119 any event not bound by other elements of the keymap is given
120 @var{binding} as its binding. Default bindings allow a keymap to bind
121 all possible event types without having to enumerate all of them. A
122 keymap that has a default binding completely masks any lower-precedence
125 If an element of a keymap is a vector, the vector counts as bindings
126 for all the @sc{ASCII} characters; vector element @var{n} is the binding
127 for the character with code @var{n}. This is a compact way to
128 record lots of bindings. A keymap with such a vector is called a
129 @dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}.
131 When a keymap contains a vector, it always defines a binding for every
132 @sc{ASCII} character even if the vector element is @code{nil}. Such a
133 binding of @code{nil} overrides any default binding in the keymap.
134 However, default bindings are still meaningful for events that are not
135 @sc{ASCII} characters. A binding of @code{nil} does @emph{not}
136 override lower-precedence keymaps; thus, if the local map gives a
137 binding of @code{nil}, Emacs uses the binding from the global map.
139 @cindex keymap prompt string
140 @cindex overall prompt string
141 @cindex prompt string of keymap
142 Aside from bindings, a keymap can also have a string as an element.
143 This is called the @dfn{overall prompt string} and makes it possible to
144 use the keymap as a menu. @xref{Menu Keymaps}.
146 @cindex meta characters lookup
147 Keymaps do not directly record bindings for the meta characters, whose
148 codes are from 128 to 255. Instead, meta characters are regarded for
149 purposes of key lookup as sequences of two characters, the first of
150 which is @key{ESC} (or whatever is currently the value of
151 @code{meta-prefix-char}). Thus, the key @kbd{M-a} is really represented
152 as @kbd{@key{ESC} a}, and its global binding is found at the slot for
153 @kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).
155 Here as an example is the local keymap for Lisp mode, a sparse
156 keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
157 C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
167 (9 . lisp-indent-line)
171 (127 . backward-delete-char-untabify)
180 ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
182 ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
183 (24 . lisp-send-defun)))
187 @defun keymapp object
188 This function returns @code{t} if @var{object} is a keymap, @code{nil}
189 otherwise. More precisely, this function tests for a list whose
190 @sc{car} is @code{keymap}.
198 (keymapp (current-global-map))
204 @node Creating Keymaps
205 @section Creating Keymaps
206 @cindex creating keymaps
208 Here we describe the functions for creating keymaps.
210 @defun make-keymap &optional prompt
211 This function creates and returns a new full keymap (i.e., one
212 containing a vector of length 128 for defining all the @sc{ASCII}
213 characters). The new keymap initially binds all @sc{ASCII} characters
214 to @code{nil}, and does not bind any other kind of event.
219 @result{} (keymap [nil nil nil @dots{} nil nil])
223 If you specify @var{prompt}, that becomes the overall prompt string for
224 the keymap. The prompt string is useful for menu keymaps (@pxref{Menu
228 @defun make-sparse-keymap &optional prompt
229 This function creates and returns a new sparse keymap with no entries.
230 The new keymap does not bind any events. The argument @var{prompt}
231 specifies a prompt string, as in @code{make-keymap}.
241 @defun copy-keymap keymap
242 This function returns a copy of @var{keymap}. Any keymaps that
243 appear directly as bindings in @var{keymap} are also copied recursively,
244 and so on to any number of levels. However, recursive copying does not
245 take place when the definition of a character is a symbol whose function
246 definition is a keymap; the same symbol appears in the new copy.
251 (setq map (copy-keymap (current-local-map)))
255 ;; @r{(This implements meta characters.)}
257 (83 . center-paragraph)
259 (9 . tab-to-tab-stop))
263 (eq map (current-local-map))
267 (equal map (current-local-map))
273 @node Inheritance and Keymaps
274 @section Inheritance and Keymaps
275 @cindex keymap inheritance
276 @cindex inheriting a keymap's bindings
278 A keymap can inherit the bindings of another keymap. Do do this, make
279 a keymap whose ``tail'' is another existing keymap to inherit from.
280 Such a keymap looks like this:
283 (keymap @var{bindings}@dots{} . @var{other-keymap})
287 The effect is that this keymap inherits all the bindings of
288 @var{other-keymap}, whatever they may be at the time a key is looked up,
289 but can add to them or override them with @var{bindings}.
291 If you change the bindings in @var{other-keymap} using @code{define-key}
292 or other key-binding functions, these changes are visible in the
293 inheriting keymap unless shadowed by @var{bindings}. The converse is
294 not true: if you use @code{define-key} to change the inheriting keymap,
295 that affects @var{bindings}, but has no effect on @var{other-keymap}.
297 Here is an example showing how to make a keymap that inherits
298 from @code{text-mode-map}:
301 (setq my-mode-map (cons 'keymap text-mode-map))
308 A @dfn{prefix key} has an associated keymap that defines what to do
309 with key sequences that start with the prefix key. For example,
310 @kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
311 the variable @code{ctl-x-map}. Here is a list of the standard prefix
312 keys of Emacs and their keymaps:
318 @code{esc-map} is used for events that follow @key{ESC}. Thus, the
319 global definitions of all meta characters are actually found here. This
320 map is also the function definition of @code{ESC-prefix}.
324 @code{help-map} is used for events that follow @kbd{C-h}.
328 @vindex mode-specific-map
329 @code{mode-specific-map} is for events that follow @kbd{C-c}. This
330 map is not actually mode specific; its name was chosen to be informative
331 for the user in @kbd{C-h b} (@code{display-bindings}), where it
332 describes the main use of the @kbd{C-c} prefix key.
337 @findex Control-X-prefix
338 @code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
339 map is also the function definition of @code{Control-X-prefix}.
344 @code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}.
350 @code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
357 The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
358 that have no special name.
361 The binding of a prefix key is the keymap to use for looking up the
362 events that follow the prefix key. (It may instead be a symbol whose
363 function definition is a keymap. The effect is the same, but the symbol
364 serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is
365 the symbol @code{Control-X-prefix}, whose function definition is the
366 keymap for @kbd{C-x} commands. (The same keymap is also the value of
369 Prefix key definitions can appear in any active keymap. The
370 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
371 keys appear in the global map, so these prefix keys are always
372 available. Major and minor modes can redefine a key as a prefix by
373 putting a prefix key definition for it in the local map or the minor
374 mode's map. @xref{Active Keymaps}.
376 If a key is defined as a prefix in more than one active map, then its
377 various definitions are in effect merged: the commands defined in the
378 minor mode keymaps come first, followed by those in the local map's
379 prefix definition, and then by those from the global map.
381 In the following example, we make @kbd{C-p} a prefix key in the local
382 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
383 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
384 like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
389 (use-local-map (make-sparse-keymap))
393 (local-set-key "\C-p" ctl-x-map)
397 (key-binding "\C-p\C-f")
402 (key-binding "\C-p6")
407 @defun define-prefix-command symbol
408 @cindex prefix command
409 This function defines @var{symbol} as a prefix command: it creates a
410 full keymap and stores it as @var{symbol}'s function definition.
411 Storing the symbol as the binding of a key makes the key a prefix key
412 that has a name. The function also sets @var{symbol} as a variable, to
413 have the keymap as its value. It returns @var{symbol}.
415 In Emacs version 18, only the function definition of @var{symbol} was
416 set, not the value as a variable.
420 @section Active Keymaps
421 @cindex active keymap
422 @cindex global keymap
425 Emacs normally contains many keymaps; at any given time, just a few of
426 them are @dfn{active} in that they participate in the interpretation
427 of user input. These are the global keymap, the current buffer's
428 local keymap, and the keymaps of any enabled minor modes.
430 The @dfn{global keymap} holds the bindings of keys that are defined
431 regardless of the current buffer, such as @kbd{C-f}. The variable
432 @code{global-map} holds this keymap, which is always active.
434 Each buffer may have another keymap, its @dfn{local keymap}, which may
435 contain new or overriding definitions for keys. The current buffer's
436 local keymap is always active except when @code{overriding-local-map}
437 overrides it. Text properties can specify an alternative local map for
438 certain parts of the buffer; see @ref{Special Properties}.
440 Each minor mode may have a keymap; if it does, the keymap is active
441 when the minor mode is enabled.
443 The variable @code{overriding-local-map}, if non-@code{nil}, specifies
444 another local keymap that overrides the buffer's local map and all the
447 All the active keymaps are used together to determine what command to
448 execute when a key is entered. Emacs searches these maps one by one, in
449 order of decreasing precedence, until it finds a binding in one of the maps.
451 Normally, Emacs @emph{first} searches for the key in the minor mode
452 maps (one map at a time); if they do not supply a binding for the key,
453 Emacs searches the local map; if that too has no binding, Emacs then
454 searches the global map. However, if @code{overriding-local-map} is
455 non-@code{nil}, Emacs searches that map first, followed by the global
458 The procedure for searching a single keymap is called
459 @dfn{key lookup}; see @ref{Key Lookup}.
461 @cindex major mode keymap
462 Since every buffer that uses the same major mode normally uses the
463 same local keymap, you can think of the keymap as local to the mode. A
464 change to the local keymap of a buffer (using @code{local-set-key}, for
465 example) is seen also in the other buffers that share that keymap.
467 The local keymaps that are used for Lisp mode, C mode, and several
468 other major modes exist even if they have not yet been used. These
469 local maps are the values of the variables @code{lisp-mode-map},
470 @code{c-mode-map}, and so on. For most other modes, which are less
471 frequently used, the local keymap is constructed only when the mode is
472 used for the first time in a session.
474 The minibuffer has local keymaps, too; they contain various completion
475 and exit commands. @xref{Intro to Minibuffers}.
477 @xref{Standard Keymaps}, for a list of standard keymaps.
480 This variable contains the default global keymap that maps Emacs
481 keyboard input to commands. The global keymap is normally this keymap.
482 The default global keymap is a full keymap that binds
483 @code{self-insert-command} to all of the printing characters.
485 It is normal practice to change the bindings in the global map, but you
486 should not assign this variable any value other than the keymap it starts
490 @defun current-global-map
491 This function returns the current global keymap. This is the
492 same as the value of @code{global-map} unless you change one or the
498 @result{} (keymap [set-mark-command beginning-of-line @dots{}
499 delete-backward-char])
504 @defun current-local-map
505 This function returns the current buffer's local keymap, or @code{nil}
506 if it has none. In the following example, the keymap for the
507 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
508 in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
515 (10 . eval-print-last-sexp)
516 (9 . lisp-indent-line)
517 (127 . backward-delete-char-untabify)
527 @defun current-minor-mode-maps
528 This function returns a list of the keymaps of currently enabled minor modes.
531 @defun use-global-map keymap
532 This function makes @var{keymap} the new current global keymap. It
535 It is very unusual to change the global keymap.
538 @defun use-local-map keymap
539 This function makes @var{keymap} the new local keymap of the current
540 buffer. If @var{keymap} is @code{nil}, then the buffer has no local
541 keymap. @code{use-local-map} returns @code{nil}. Most major mode
542 commands use this function.
546 @defvar minor-mode-map-alist
547 This variable is an alist describing keymaps that may or may not be
548 active according to the values of certain variables. Its elements look
552 (@var{variable} . @var{keymap})
555 The keymap @var{keymap} is active whenever @var{variable} has a
556 non-@code{nil} value. Typically @var{variable} is the variable that
557 enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
559 Note that elements of @code{minor-mode-map-alist} do not have the same
560 structure as elements of @code{minor-mode-alist}. The map must be the
561 @sc{cdr} of the element; a list with the map as the second element will
564 What's more, the keymap itself must appear in the @sc{cdr}. It does not
565 work to store a variable in the @sc{cdr} and make the map the value of
568 When more than one minor mode keymap is active, their order of priority
569 is the order of @code{minor-mode-map-alist}. But you should design
570 minor modes so that they don't interfere with each other. If you do
571 this properly, the order will not matter.
573 See also @code{minor-mode-key-binding} in @ref{Functions for Key
574 Lookup}. See @ref{Keymaps and Minor Modes}, for more information about
578 @defvar overriding-local-map
579 If non-@code{nil}, this variable holds a keymap to use instead of the
580 buffer's local keymap and instead of all the minor mode keymaps. This
581 keymap, if any, overrides all other maps that would have been active,
582 except for the current global map.
585 @defvar overriding-local-map-menu-flag
586 If this variable is non-@code{nil}, the value of
587 @code{overriding-local-map} can affect the display of the menu bar. The
588 default value is @code{nil}, so @code{overriding-local-map} has no
589 effect on the menu bar.
591 Note that @code{overriding-local-map} does affect the execution of key
592 sequences entered using the menu bar, even if it does not affect the
593 menu bar display. So if a menu bar key sequence comes in, you should
594 clear @code{overriding-local-map} before looking up and executing that
595 key sequence. Modes that use @code{overriding-local-map} would
596 typically do this anyway; normally they respond to events that they do
597 not handle by ``unreading'' them and and exiting.
605 @dfn{Key lookup} is the process of finding the binding of a key
606 sequence from a given keymap. Actual execution of the binding is not
609 Key lookup uses just the event type of each event in the key
610 sequence; the rest of the event is ignored. In fact, a key sequence
611 used for key lookup may designate mouse events with just their types
612 (symbols) instead of with entire mouse events (lists). @xref{Input
613 Events}. Such a pseudo-key-sequence is insufficient for
614 @code{command-execute}, but it is sufficient for looking up or rebinding
617 When the key sequence consists of multiple events, key lookup
618 processes the events sequentially: the binding of the first event is
619 found, and must be a keymap; then the second event's binding is found in
620 that keymap, and so on until all the events in the key sequence are used
621 up. (The binding thus found for the last event may or may not be a
622 keymap.) Thus, the process of key lookup is defined in terms of a
623 simpler process for looking up a single event in a keymap. How that is
624 done depends on the type of object associated with the event in that
627 Let's use the term @dfn{keymap entry} to describe the value found by
628 looking up an event type in a keymap. (This doesn't include the item
629 string and other extra elements in menu key bindings because
630 @code{lookup-key} and other key lookup functions don't include them in
631 the returned value.) While any Lisp object may be stored in a keymap as
632 a keymap entry, not all make sense for key lookup. Here is a list of
633 the meaningful kinds of keymap entries:
637 @cindex @code{nil} in keymap
638 @code{nil} means that the events used so far in the lookup form an
639 undefined key. When a keymap fails to mention an event type at all, and
640 has no default binding, that is equivalent to a binding of @code{nil}
644 @cindex keymap in keymap
645 The events used so far in the lookup form a prefix key. The next
646 event of the key sequence is looked up in @var{keymap}.
649 @cindex command in keymap
650 The events used so far in the lookup form a complete key,
651 and @var{command} is its binding. @xref{What Is a Function}.
655 @cindex string in keymap
656 The events used so far in the lookup form a complete key, whose
657 binding is a keyboard macro. See @ref{Keyboard Macros}, for more
661 @cindex list in keymap
662 The meaning of a list depends on the types of the elements of the list.
666 If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
667 is a keymap, and is treated as a keymap (see above).
670 @cindex @code{lambda} in keymap
671 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
672 lambda expression. This is presumed to be a command, and is treated as
676 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
677 type, then this is an @dfn{indirect entry}:
680 (@var{othermap} . @var{othertype})
683 When key lookup encounters an indirect entry, it looks up instead the
684 binding of @var{othertype} in @var{othermap} and uses that.
686 This feature permits you to define one key as an alias for another key.
687 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
688 and whose @sc{cdr} is 32 (the code for space) means, ``Use the global
689 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
693 @cindex symbol in keymap
694 The function definition of @var{symbol} is used in place of
695 @var{symbol}. If that too is a symbol, then this process is repeated,
696 any number of times. Ultimately this should lead to an object that is
697 a keymap, a command or a keyboard macro. A list is allowed if it is a
698 keymap or a command, but indirect entries are not understood when found
701 Note that keymaps and keyboard macros (strings and vectors) are not
702 valid functions, so a symbol with a keymap, string, or vector as its
703 function definition is invalid as a function. It is, however, valid as
704 a key binding. If the definition is a keyboard macro, then the symbol
705 is also valid as an argument to @code{command-execute}
706 (@pxref{Interactive Call}).
708 @cindex @code{undefined} in keymap
709 The symbol @code{undefined} is worth special mention: it means to treat
710 the key as undefined. Strictly speaking, the key is defined, and its
711 binding is the command @code{undefined}; but that command does the same
712 thing that is done automatically for an undefined key: it rings the bell
713 (by calling @code{ding}) but does not signal an error.
715 @cindex preventing prefix key
716 @code{undefined} is used in local keymaps to override a global key
717 binding and make the key ``undefined'' locally. A local binding of
718 @code{nil} would fail to do this because it would not override the
721 @item @var{anything else}
722 If any other type of object is found, the events used so far in the
723 lookup form a complete key, and the object is its binding, but the
724 binding is not executable as a command.
727 In short, a keymap entry may be a keymap, a command, a keyboard macro,
728 a symbol that leads to one of them, or an indirection or @code{nil}.
729 Here is an example of a sparse keymap with two characters bound to
730 commands and one bound to another keymap. This map is the normal value
731 of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
732 127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
737 (keymap (9 . lisp-indent-line)
738 (127 . backward-delete-char-untabify)
739 (27 keymap (17 . indent-sexp) (24 . eval-defun)))
743 @node Functions for Key Lookup
744 @section Functions for Key Lookup
746 Here are the functions and variables pertaining to key lookup.
748 @defun lookup-key keymap key &optional accept-defaults
749 This function returns the definition of @var{key} in @var{keymap}. If
750 the string or vector @var{key} is not a valid key sequence according to
751 the prefix keys specified in @var{keymap} (which means it is ``too
752 long'' and has extra events at the end), then the value is a number, the
753 number of events at the front of @var{key} that compose a complete key.
756 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
757 considers default bindings as well as bindings for the specific events
758 in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
759 the specific sequence @var{key}, ignoring default bindings except when
760 you explicitly ask about them. (To do this, supply @code{t} as an
761 element of @var{key}; see @ref{Format of Keymaps}.)
763 All the other functions described in this chapter that look up keys use
768 (lookup-key (current-global-map) "\C-x\C-f")
772 (lookup-key (current-global-map) "\C-x\C-f12345")
777 If @var{key} contains a meta character, that character is implicitly
778 replaced by a two-character sequence: the value of
779 @code{meta-prefix-char}, followed by the corresponding non-meta
780 character. Thus, the first example below is handled by conversion into
785 (lookup-key (current-global-map) "\M-f")
786 @result{} forward-word
789 (lookup-key (current-global-map) "\ef")
790 @result{} forward-word
794 Unlike @code{read-key-sequence}, this function does not modify the
795 specified events in ways that discard information (@pxref{Key Sequence
796 Input}). In particular, it does not convert letters to lower case and
797 it does not change drag events to clicks.
800 @deffn Command undefined
801 Used in keymaps to undefine keys. It calls @code{ding}, but does
805 @defun key-binding key &optional accept-defaults
806 This function returns the binding for @var{key} in the current
807 keymaps, trying all the active keymaps. The result is @code{nil} if
808 @var{key} is undefined in the keymaps.
811 The argument @var{accept-defaults} controls checking for default
812 bindings, as in @code{lookup-key} (above).
814 An error is signaled if @var{key} is not a string or a vector.
818 (key-binding "\C-x\C-f")
824 @defun local-key-binding key &optional accept-defaults
825 This function returns the binding for @var{key} in the current
826 local keymap, or @code{nil} if it is undefined there.
829 The argument @var{accept-defaults} controls checking for default bindings,
830 as in @code{lookup-key} (above).
833 @defun global-key-binding key &optional accept-defaults
834 This function returns the binding for command @var{key} in the
835 current global keymap, or @code{nil} if it is undefined there.
838 The argument @var{accept-defaults} controls checking for default bindings,
839 as in @code{lookup-key} (above).
843 @defun minor-mode-key-binding key &optional accept-defaults
844 This function returns a list of all the active minor mode bindings of
845 @var{key}. More precisely, it returns an alist of pairs
846 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
847 variable that enables the minor mode, and @var{binding} is @var{key}'s
848 binding in that mode. If @var{key} has no minor-mode bindings, the
851 If the first binding is not a prefix command, all subsequent bindings
852 from other minor modes are omitted, since they would be completely
853 shadowed. Similarly, the list omits non-prefix bindings that follow
856 The argument @var{accept-defaults} controls checking for default
857 bindings, as in @code{lookup-key} (above).
860 @defvar meta-prefix-char
862 This variable is the meta-prefix character code. It is used when
863 translating a meta character to a two-character sequence so it can be
864 looked up in a keymap. For useful results, the value should be a prefix
865 event (@pxref{Prefix Keys}). The default value is 27, which is the
866 @sc{ASCII} code for @key{ESC}.
868 As long as the value of @code{meta-prefix-char} remains 27, key
869 lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
870 defined as the @code{backward-word} command. However, if you set
871 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
872 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
873 @code{switch-to-buffer} command.
877 meta-prefix-char ; @r{The default value.}
882 @result{} backward-word
885 ?\C-x ; @r{The print representation}
886 @result{} 24 ; @r{of a character.}
889 (setq meta-prefix-char 24)
894 @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is}
895 ; @r{like typing @kbd{C-x b}.}
897 (setq meta-prefix-char 27) ; @r{Avoid confusion!}
898 @result{} 27 ; @r{Restore the default value!}
903 @node Changing Key Bindings
904 @section Changing Key Bindings
905 @cindex changing key bindings
908 The way to rebind a key is to change its entry in a keymap. If you
909 change a binding in the global keymap, the change is effective in all
910 buffers (though it has no direct effect in buffers that shadow the
911 global binding with a local one). If you change the current buffer's
912 local map, that usually affects all buffers using the same major mode.
913 The @code{global-set-key} and @code{local-set-key} functions are
914 convenient interfaces for these operations (@pxref{Key Binding
915 Commands}). You can also use @code{define-key}, a more general
916 function; then you must specify explicitly the map to change.
918 @cindex meta character key constants
919 @cindex control character key constants
920 In writing the key sequence to rebind, it is good to use the special
921 escape sequences for control and meta characters (@pxref{String Type}).
922 The syntax @samp{\C-} means that the following character is a control
923 character and @samp{\M-} means that the following character is a meta
924 character. Thus, the string @code{"\M-x"} is read as containing a
925 single @kbd{M-x}, @code{"\C-f"} is read as containing a single
926 @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
927 containing a single @kbd{C-M-x}. You can also use this escape syntax in
928 vectors, as well as others that aren't allowed in strings; one example
929 is @samp{[?\C-\H-x home]}. @xref{Character Type}.
931 The key definition and lookup functions accept an alternate syntax for
932 event types in a key sequence that is a vector: you can use a list
933 containing modifier names plus one base event (a character or function
934 key name). For example, @code{(control ?a)} is equivalent to
935 @code{?\C-a} and @code{(hyper control left)} is equivalent to
938 For the functions below, an error is signaled if @var{keymap} is not a
939 keymap or if @var{key} is not a string or vector representing a key
940 sequence. You can use event types (symbols) as shorthand for events
943 @defun define-key keymap key binding
944 This function sets the binding for @var{key} in @var{keymap}. (If
945 @var{key} is more than one event long, the change is actually made
946 in another keymap reached from @var{keymap}.) The argument
947 @var{binding} can be any Lisp object, but only certain types are
948 meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
949 The value returned by @code{define-key} is @var{binding}.
951 @cindex invalid prefix key error
952 @cindex key sequence error
953 Every prefix of @var{key} must be a prefix key (i.e., bound to a
954 keymap) or undefined; otherwise an error is signaled.
956 If some prefix of @var{key} is undefined, then @code{define-key} defines
957 it as a prefix key so that the rest of @var{key} may be defined as
961 Here is an example that creates a sparse keymap and makes a number of
966 (setq map (make-sparse-keymap))
970 (define-key map "\C-f" 'forward-char)
971 @result{} forward-char
975 @result{} (keymap (6 . forward-char))
979 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
980 (define-key map "\C-xf" 'forward-word)
981 @result{} forward-word
986 (24 keymap ; @kbd{C-x}
987 (102 . forward-word)) ; @kbd{f}
988 (6 . forward-char)) ; @kbd{C-f}
992 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
993 (define-key map "\C-p" ctl-x-map)
995 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
999 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1000 (define-key map "\C-p\C-f" 'foo)
1005 @result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
1006 (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1008 (102 . forward-word))
1014 Note that storing a new binding for @kbd{C-p C-f} actually works by
1015 changing an entry in @code{ctl-x-map}, and this has the effect of
1016 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1019 @defun substitute-key-definition olddef newdef keymap &optional oldmap
1020 @cindex replace bindings
1021 This function replaces @var{olddef} with @var{newdef} for any keys in
1022 @var{keymap} that were bound to @var{olddef}. In other words,
1023 @var{olddef} is replaced with @var{newdef} wherever it appears. The
1024 function returns @code{nil}.
1026 For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
1031 (substitute-key-definition
1032 'find-file 'find-file-read-only (current-global-map))
1037 If @var{oldmap} is non-@code{nil}, then its bindings determine which
1038 keys to rebind. The rebindings still happen in @var{newmap}, not in
1039 @var{oldmap}. Thus, you can change one map under the control of the
1040 bindings in another. For example,
1043 (substitute-key-definition
1044 'delete-backward-char 'my-funny-delete
1049 puts the special deletion command in @code{my-map} for whichever keys
1050 are globally bound to the standard deletion command.
1054 Prefix keymaps that appear within @var{keymap} are not checked
1055 recursively for keys bound to @var{olddef}; they are not changed at all.
1056 Perhaps it would be better to check nested keymaps recursively.
1059 Here is an example showing a keymap before and after substitution:
1067 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1071 (substitute-key-definition 'olddef-1 'newdef map)
1076 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1081 @defun suppress-keymap keymap &optional nodigits
1082 @cindex @code{self-insert-command} override
1083 This function changes the contents of the full keymap @var{keymap} by
1084 making all the printing characters undefined. More precisely, it binds
1085 them to the command @code{undefined}. This makes ordinary insertion of
1086 text impossible. @code{suppress-keymap} returns @code{nil}.
1088 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1089 digits to run @code{digit-argument}, and @kbd{-} to run
1090 @code{negative-argument}. Otherwise it makes them undefined like the
1091 rest of the printing characters.
1093 @cindex yank suppression
1094 @cindex @code{quoted-insert} suppression
1095 The @code{suppress-keymap} function does not make it impossible to
1096 modify a buffer, as it does not suppress commands such as @code{yank}
1097 and @code{quoted-insert}. To prevent any modification of a buffer, make
1098 it read-only (@pxref{Read Only Buffers}).
1100 Since this function modifies @var{keymap}, you would normally use it
1101 on a newly created keymap. Operating on an existing keymap
1102 that is used for some other purpose is likely to cause trouble; for
1103 example, suppressing @code{global-map} would make it impossible to use
1106 Most often, @code{suppress-keymap} is used to initialize local
1107 keymaps of modes such as Rmail and Dired where insertion of text is not
1108 desirable and the buffer is read-only. Here is an example taken from
1109 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
1110 Dired mode is set up:
1115 (setq dired-mode-map (make-keymap))
1116 (suppress-keymap dired-mode-map)
1117 (define-key dired-mode-map "r" 'dired-rename-file)
1118 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1119 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1120 (define-key dired-mode-map "v" 'dired-view-file)
1121 (define-key dired-mode-map "e" 'dired-find-file)
1122 (define-key dired-mode-map "f" 'dired-find-file)
1128 @node Key Binding Commands
1129 @section Commands for Binding Keys
1131 This section describes some convenient interactive interfaces for
1132 changing key bindings. They work by calling @code{define-key}.
1134 People often use @code{global-set-key} in their @file{.emacs} file for
1135 simple customization. For example,
1138 (global-set-key "\C-x\C-\\" 'next-line)
1145 (global-set-key [?\C-x ?\C-\\] 'next-line)
1149 redefines @kbd{C-x C-\} to move down a line.
1152 (global-set-key [M-mouse-1] 'mouse-set-point)
1156 redefines the first (leftmost) mouse button, typed with the Meta key, to
1157 set point where you click.
1159 @deffn Command global-set-key key definition
1160 This function sets the binding of @var{key} in the current global map
1161 to @var{definition}.
1165 (global-set-key @var{key} @var{definition})
1167 (define-key (current-global-map) @var{key} @var{definition})
1172 @deffn Command global-unset-key key
1173 @cindex unbinding keys
1174 This function removes the binding of @var{key} from the current
1177 One use of this function is in preparation for defining a longer key
1178 that uses @var{key} as a prefix---which would not be allowed if
1179 @var{key} has a non-prefix binding. For example:
1183 (global-unset-key "\C-l")
1187 (global-set-key "\C-l\C-l" 'redraw-display)
1192 This function is implemented simply using @code{define-key}:
1196 (global-unset-key @var{key})
1198 (define-key (current-global-map) @var{key} nil)
1203 @deffn Command local-set-key key definition
1204 This function sets the binding of @var{key} in the current local
1205 keymap to @var{definition}.
1209 (local-set-key @var{key} @var{definition})
1211 (define-key (current-local-map) @var{key} @var{definition})
1216 @deffn Command local-unset-key key
1217 This function removes the binding of @var{key} from the current
1222 (local-unset-key @var{key})
1224 (define-key (current-local-map) @var{key} nil)
1229 @node Scanning Keymaps
1230 @section Scanning Keymaps
1232 This section describes functions used to scan all the current keymaps
1233 for the sake of printing help information.
1235 @defun accessible-keymaps keymap &optional prefix
1236 This function returns a list of all the keymaps that can be accessed
1237 (via prefix keys) from @var{keymap}. The value is an association list
1238 with elements of the form @code{(@var{key} .@: @var{map})}, where
1239 @var{key} is a prefix key whose definition in @var{keymap} is
1242 The elements of the alist are ordered so that the @var{key} increases
1243 in length. The first element is always @code{("" .@: @var{keymap})},
1244 because the specified keymap is accessible from itself with a prefix of
1247 If @var{prefix} is given, it should be a prefix key sequence; then
1248 @code{accessible-keymaps} includes only the submaps whose prefixes start
1249 with @var{prefix}. These elements look just as they do in the value of
1250 @code{(accessible-keymaps)}; the only difference is that some elements
1253 In the example below, the returned alist indicates that the key
1254 @key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
1255 definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
1260 (accessible-keymaps (current-local-map))
1261 @result{}(("" keymap
1262 (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
1263 (83 . center-paragraph)
1264 (115 . center-line))
1265 (9 . tab-to-tab-stop))
1270 (83 . center-paragraph)
1275 In the following example, @kbd{C-h} is a prefix key that uses a sparse
1276 keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
1277 Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
1278 the variable @code{ctl-x-4-map}. The event @code{mode-line} is one of
1279 several dummy events used as prefixes for mouse actions in special parts
1284 (accessible-keymaps (current-global-map))
1285 @result{} (("" keymap [set-mark-command beginning-of-line @dots{}
1286 delete-backward-char])
1289 ("^H" keymap (118 . describe-variable) @dots{}
1290 (8 . help-for-help))
1293 ("^X" keymap [x-flush-mouse-queue @dots{}
1294 backward-kill-sentence])
1297 ("^[" keymap [mark-sexp backward-sexp @dots{}
1298 backward-kill-word])
1300 ("^X4" keymap (15 . display-buffer) @dots{})
1303 (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1308 These are not all the keymaps you would see in an actual case.
1311 @defun where-is-internal command &optional keymap firstonly noindirect
1312 This function returns a list of key sequences (of any length) that are
1313 bound to @var{command} in a set of keymaps.
1315 The argument @var{command} can be any object; it is compared with all
1316 keymap entries using @code{eq}.
1318 If @var{keymap} is @code{nil}, then the maps used are the current active
1319 keymaps, disregarding @code{overriding-local-map} (that is, pretending
1320 its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
1321 maps searched are @var{keymap} and the global keymap.
1323 Usually it's best to use @code{overriding-local-map} as the expression
1324 for @var{keymap}. Then @code{where-is-internal} searches precisely the
1325 keymaps that are active. To search only the global map, pass
1326 @code{(keymap)} (an empty keymap) as @var{keymap}.
1328 If @var{firstonly} is @code{non-ascii}, then the value is a single
1329 string representing the first key sequence found, rather than a list of
1330 all possible key sequences. If @var{firstonly} is @code{t}, then the
1331 value is the first key sequence, except that key sequences consisting
1332 entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
1333 characters) are preferred to all other key sequences.
1335 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1336 follow indirect keymap bindings. This makes it possible to search for
1337 an indirect definition itself.
1339 This function is used by @code{where-is} (@pxref{Help, , Help, emacs,
1340 The GNU Emacs Manual}).
1344 (where-is-internal 'describe-function)
1345 @result{} ("\^hf" "\^hd")
1350 @deffn Command describe-bindings prefix
1351 This function creates a listing of all defined keys and their
1352 definitions. It writes the listing in a buffer named @samp{*Help*} and
1353 displays it in a window.
1355 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
1356 listing includes only keys that start with @var{prefix}.
1358 The listing describes meta characters as @key{ESC} followed by the
1359 corresponding non-meta character.
1361 When several characters with consecutive @sc{ASCII} codes have the
1362 same definition, they are shown together, as
1363 @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
1364 know the @sc{ASCII} codes to understand which characters this means.
1365 For example, in the default global map, the characters @samp{@key{SPC}
1366 ..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
1367 @kbd{~} is @sc{ASCII} 126, and the characters between them include all
1368 the normal printing characters, (e.g., letters, digits, punctuation,
1369 etc.@:); all these characters are bound to @code{self-insert-command}.
1373 @section Menu Keymaps
1374 @cindex menu keymaps
1377 A keymap can define a menu as well as bindings for keyboard keys and
1378 mouse button. Menus are usually actuated with the mouse, but they can
1379 work with the keyboard also.
1382 * Defining Menus:: How to make a keymap that defines a menu.
1383 * Mouse Menus:: How users actuate the menu with the mouse.
1384 * Keyboard Menus:: How they actuate it with the keyboard.
1385 * Menu Example:: Making a simple menu.
1386 * Menu Bar:: How to customize the menu bar.
1387 * Modifying Menus:: How to add new items to a menu.
1390 @node Defining Menus
1391 @subsection Defining Menus
1392 @cindex defining menus
1393 @cindex menu prompt string
1394 @cindex prompt string (of menu)
1396 A keymap is suitable for menu use if it has an @dfn{overall prompt
1397 string}, which is a string that appears as an element of the keymap.
1398 (@xref{Format of Keymaps}.) The string should describe the purpose of
1399 the menu. The easiest way to construct a keymap with a prompt string is
1400 to specify the string as an argument when you call @code{make-keymap} or
1401 @code{make-sparse-keymap} (@pxref{Creating Keymaps}).
1403 The order of items in the menu is the same as the order of bindings in
1404 the keymap. Since @code{define-key} puts new bindings at the front, you
1405 should define the menu items starting at the bottom of the menu and
1406 moving to the top, if you care about the order. When you add an item to
1407 an existing menu, you can specify its position in the menu using
1408 @code{define-key-after} (@pxref{Modifying Menus}).
1410 The individual bindings in the menu keymap should have item
1411 strings; these strings become the items displayed in the menu. A
1412 binding with an item string looks like this:
1415 (@var{string} . @var{real-binding})
1418 The item string for a binding should be short---one or two words. It
1419 should describe the action of the command it corresponds to.
1421 As far as @code{define-key} is concerned, @var{string} is part of the
1422 event's binding. However, @code{lookup-key} returns just
1423 @var{real-binding}, and only @var{real-binding} is used for executing
1426 You can also supply a second string, called the help string, as follows:
1429 (@var{string} @var{help-string} . @var{real-binding})
1432 Currently Emacs does not actually use @var{help-string}; it knows only
1433 how to ignore @var{help-string} in order to extract @var{real-binding}.
1434 In the future we hope to make @var{help-string} serve as extended
1435 documentation for the menu item, available on request.
1437 If @var{real-binding} is @code{nil}, then @var{string} appears in the
1438 menu but cannot be selected.
1440 If @var{real-binding} is a symbol and has a non-@code{nil}
1441 @code{menu-enable} property, that property is an expression that
1442 controls whether the menu item is enabled. Every time the keymap is
1443 used to display a menu, Emacs evaluates the expression, and it enables
1444 the menu item only if the expression's value is non-@code{nil}. When a
1445 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
1446 cannot be selected with the mouse.
1448 Sometimes it is useful to make menu items that use the ``same'' command
1449 but with different enable conditions. You can do this by defining alias
1450 commands. Here's an example that makes two aliases for
1451 @code{toggle-read-only} and gives them different enable conditions:
1454 (defalias 'make-read-only 'toggle-read-only)
1455 (put 'make-read-only 'menu-enable '(not buffer-read-only))
1456 (defalias 'make-writable 'toggle-read-only)
1457 (put 'make-writable 'menu-enable 'buffer-read-only)
1460 You've probably noticed that menu items show the equivalent keyboard key
1461 sequence (if any) to invoke the same command. To save time on
1462 recalculation, menu display caches this information in a sublist in the
1465 @c This line is not too long--rms.
1467 (@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
1470 Don't put these sublists in the menu item yourself; menu display
1471 calculates them automatically. Don't add keyboard equivalents to the
1472 item strings in a mouse menu, since that is redundant.
1474 If an alias command has no keyboard equivalent itself, menus show the
1475 keyboard equivalent of its underlying command. In the example above,
1476 menus items defined to run @code{make-read-only} or @code{make-writable}
1477 would show the keyboard equivalents of @code{toggle-read-only}.
1480 @subsection Menus and the Mouse
1482 The way to make a menu keymap produce a menu is to make it the
1483 definition of a prefix key.
1485 If the prefix key ends with a mouse event, Emacs handles the menu keymap
1486 by popping up a visible menu, so that the user can select a choice with
1487 the mouse. When the user clicks on a menu item, the event generated is
1488 whatever character or symbol has the binding that brought about that
1489 menu item. (A menu item may generate a series of events if the menu has
1490 multiple levels or comes from the menu bar.)
1492 It's often best to use a button-down event to trigger the menu. Then
1493 the user can select a menu item by releasing the button.
1495 A single keymap can appear as multiple menu panes, if you explicitly
1496 arrange for this. The way to do this is to make a keymap for each pane,
1497 then create a binding for each of those maps in the main keymap of the
1498 menu. Give each of these bindings an item string that starts with
1499 @samp{@@}. The rest of the item string becomes the name of the pane.
1500 See the file @file{lisp/mouse.el} for an example of this. Any ordinary
1501 bindings with @samp{@@}-less item strings are grouped into one pane,
1502 which appears along with the other panes explicitly created for the
1505 X toolkit menus don't have panes; instead, they can have submenus.
1506 Every nested keymap becomes a submenu, whether the item string starts
1507 with @samp{@@} or not. In a toolkit version of Emacs, the only thing
1508 special about @samp{@@} at the beginning of an item string is that the
1509 @samp{@@} doesn't appear in the menu item.
1511 You can also get multiple panes from separate keymaps. The full
1512 definition of a prefix key always comes from merging the definitions
1513 supplied by the various active keymaps (minor mode, local, and
1514 global). When more than one of these keymaps is a menu, each of them
1515 makes a separate pane or panes. @xref{Active Keymaps}.
1517 In toolkit versions of Emacs, menus don't have panes, so submenus are
1518 used to represent the separate keymaps. Each keymap's contribution
1519 becomes one submenu.
1521 A Lisp program can explicitly pop up a menu and receive the user's
1522 choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
1524 @node Keyboard Menus
1525 @subsection Menus and the Keyboard
1527 When a prefix key ending with a keyboard event (a character or function
1528 key) has a definition that is a menu keymap, the user can use the
1529 keyboard to choose a menu item.
1531 Emacs displays the menu alternatives (the item strings of the bindings)
1532 in the echo area. If they don't all fit at once, the user can type
1533 @key{SPC} to see the next line of alternatives. Successive uses of
1534 @key{SPC} eventually get to the end of the menu and then cycle around to
1535 the beginning. (The variable @code{menu-prompt-more-char} specifies
1536 which character is used for this; @key{SPC} is the default.)
1538 When the user has found the desired alternative from the menu, he or she
1539 should type the corresponding character---the one whose binding is that
1542 In a menu intended for keyboard use, each menu item must clearly
1543 indicate what character to type. The best convention to use is to make
1544 the character the first letter of the item string. That is something
1545 users will understand without being told.
1547 This way of using menus in an Emacs-like editor was inspired by the
1550 @defvar menu-prompt-more-char
1551 This variable specifies the character to use to ask to see
1552 the next line of a menu. Its initial value is 32, the code
1557 @subsection Menu Example
1559 Here is a simple example of how to set up a menu for mouse use.
1563 (make-sparse-keymap "Key Commands <==> Functions"))
1564 (fset 'help-for-keys my-menu-map)
1566 (define-key my-menu-map [bindings]
1567 '("List all keystroke commands" . describe-bindings))
1568 (define-key my-menu-map [key]
1569 '("Describe key briefly" . describe-key-briefly))
1570 (define-key my-menu-map [key-verbose]
1571 '("Describe key verbose" . describe-key))
1572 (define-key my-menu-map [function]
1573 '("Describe Lisp function" . describe-function))
1574 (define-key my-menu-map [where-is]
1575 '("Where is this command" . where-is))
1577 (define-key global-map [C-S-down-mouse-1] 'help-for-keys)
1580 The symbols used in the key sequences bound in the menu are fictitious
1581 ``function keys''; they don't appear on the keyboard, but that doesn't
1582 stop you from using them in the menu. Their names were chosen to be
1583 mnemonic, because they show up in the output of @code{where-is} and
1584 @code{apropos} to identify the corresponding menu items.
1586 However, if you want the menu to be usable from the keyboard as well,
1587 you must bind real @sc{ASCII} characters as well as fictitious function
1591 @subsection The Menu Bar
1594 Most window systems allow each frame to have a @dfn{menu bar}---a
1595 permanently displayed menu stretching horizontally across the top of the
1596 frame. The items of the menu bar are the subcommands of the fake
1597 ``function key'' @code{menu-bar}, as defined by all the active keymaps.
1599 To add an item to the menu bar, invent a fake ``function key'' of your
1600 own (let's call it @var{key}), and make a binding for the key sequence
1601 @code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
1602 so that pressing a button on the menu bar item leads to another menu.
1604 When more than one active keymap defines the same fake function key
1605 for the menu bar, the item appears just once. If the user clicks on
1606 that menu bar item, it brings up a single, combined submenu containing
1607 all the subcommands of that item---the global subcommands, the local
1608 subcommands, and the minor mode subcommands, all together.
1610 The variable @code{overriding-local-map} is normally ignored when
1611 determining the menu bar contents. That is, the menu bar is computed
1612 from the keymaps that would be active if @code{overriding-local-map}
1613 were @code{nil}. @xref{Active Keymaps}.
1615 In order for a frame to display a menu bar, its @code{menu-bar-lines}
1616 parameter must be greater than zero. Emacs uses just one line for the
1617 menu bar itself; if you specify more than one line, the other lines
1618 serve to separate the menu bar from the windows in the frame. We
1619 recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X
1622 Here's an example of setting up a menu bar item:
1626 (modify-frame-parameters (selected-frame)
1627 '((menu-bar-lines . 2)))
1631 ;; @r{Make a menu keymap (with a prompt string)}
1632 ;; @r{and make it the menu bar item's definition.}
1633 (define-key global-map [menu-bar words]
1634 (cons "Words" (make-sparse-keymap "Words")))
1638 ;; @r{Define specific subcommands in the item's menu.}
1639 (define-key global-map
1640 [menu-bar words forward]
1641 '("Forward word" . forward-word))
1644 (define-key global-map
1645 [menu-bar words backward]
1646 '("Backward word" . backward-word))
1650 A local keymap can cancel a menu bar item made by the global keymap by
1651 rebinding the same fake function key with @code{undefined} as the
1652 binding. For example, this is how Dired suppresses the @samp{Edit} menu
1656 (define-key dired-mode-map [menu-bar edit] 'undefined)
1660 @code{edit} is the fake function key used by the global map for the
1661 @samp{Edit} menu bar item. The main reason to suppress a global
1662 menu bar item is to regain space for mode-specific items.
1664 @defvar menu-bar-final-items
1665 Normally the menu bar shows global items followed by items defined by the
1668 This variable holds a list of fake function keys for items to display at
1669 the end of the menu bar rather than in normal sequence. The default
1670 value is @code{(help)}; thus, the @samp{Help} menu item normally appears
1671 at the end of the menu bar, following local menu items.
1674 @node Modifying Menus
1675 @subsection Modifying Menus
1677 When you insert a new item in an existing menu, you probably want to
1678 put it in a particular place among the menu's existing items. If you
1679 use @code{define-key} to add the item, it normally goes at the front of
1680 the menu. To put it elsewhere, use @code{define-key-after}:
1682 @defun define-key-after map key binding after
1683 Define a binding in @var{map} for @var{key}, with value @var{binding},
1684 just like @code{define-key}, but position the binding in @var{map} after
1685 the binding for the event @var{after}. The argument @var{key} should
1686 be of length one---a vector or string with just one element.
1691 (define-key-after my-menu [drink]
1692 '("Drink" . drink-command) 'eat)
1696 makes a binding for the fake function key @key{drink} and puts it
1697 right after the binding for @key{eat}.
1699 Here is how to insert an item called @samp{Work} in the @samp{Signals}
1700 menu of Shell mode, after the item @code{break}:
1704 (lookup-key shell-mode-map [menu-bar signals])
1705 [work] '("Work" . work-command) 'break)
1708 Note that @var{key} is a sequence containing just one event type, but
1709 @var{after} is just an event type (not a sequence).