*** empty log message ***
[emacs.git] / lispref / keymaps.texi
blob6576c3cd35fc5871412b260b4e6a719857e35a91
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/keymaps
7 @node Keymaps, Modes, Command Loop, Top
8 @chapter Keymaps
9 @cindex keymap
11   The bindings between input events and commands are recorded in data
12 structures called @dfn{keymaps}.  Each binding in a keymap associates
13 (or @dfn{binds}) an individual event type either to another keymap or to
14 a command.  When an event type is bound to a keymap, that keymap is used
15 to look up the next input event; this continues until a command is
16 found.  The whole process is called @dfn{key lookup}.
18 @menu
19 * Keymap Terminology::          Definitions of terms pertaining to keymaps.
20 * Format of Keymaps::           What a keymap looks like as a Lisp object.
21 * Creating Keymaps::            Functions to create and copy keymaps.
22 * Inheritance and Keymaps::     How one keymap can inherit the bindings
23                                    of another keymap.
24 * Prefix Keys::                 Defining a key with a keymap as its definition.
25 * Active Keymaps::              Each buffer has a local keymap
26                                    to override the standard (global) bindings.
27                                    A minor mode can also override them.
28 * Key Lookup::                  How extracting elements from keymaps works.
29 * Functions for Key Lookup::    How to request key lookup.
30 * Changing Key Bindings::       Redefining a key in a keymap.
31 * Key Binding Commands::        Interactive interfaces for redefining keys.
32 * Scanning Keymaps::            Looking through all keymaps, for printing help.
33 * Menu Keymaps::                Defining a menu as a keymap.
34 @end menu
36 @node Keymap Terminology
37 @section Keymap Terminology
38 @cindex key
39 @cindex keystroke
40 @cindex key binding
41 @cindex binding of a key
42 @cindex complete key
43 @cindex undefined key
45   A @dfn{keymap} is a table mapping event types to definitions (which
46 can be any Lisp objects, though only certain types are meaningful for
47 execution by the command loop).  Given an event (or an event type) and a
48 keymap, Emacs can get the event's definition.  Events include
49 characters, function keys, and mouse actions (@pxref{Input Events}).
51   A sequence of input events that form a unit is called a
52 @dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
53 is always a key sequence, and so are some multi-event sequences.
55   A keymap determines a binding or definition for any key sequence.  If
56 the key sequence is a single event, its binding is the definition of the
57 event in the keymap.  The binding of a key sequence of more than one
58 event is found by an iterative process: the binding of the first event
59 is found, and must be a keymap; then the second event's binding is found
60 in that keymap, and so on until all the events in the key sequence are
61 used up.
63   If the binding of a key sequence is a keymap, we call the key sequence
64 a @dfn{prefix key}.  Otherwise, we call it a @dfn{complete key} (because
65 no more events can be added to it).  If the binding is @code{nil},
66 we call the key @dfn{undefined}.  Examples of prefix keys are @kbd{C-c},
67 @kbd{C-x}, and @kbd{C-x 4}.  Examples of defined complete keys are
68 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}.  Examples of undefined complete
69 keys are @kbd{C-x C-g}, and @kbd{C-c 3}.  @xref{Prefix Keys}, for more
70 details.
72   The rule for finding the binding of a key sequence assumes that the
73 intermediate bindings (found for the events before the last) are all
74 keymaps; if this is not so, the sequence of events does not form a
75 unit---it is not really one key sequence.  In other words, removing one
76 or more events from the end of any valid key sequence must always yield
77 a prefix key.  For example, @kbd{C-f C-n} is not a key sequence;
78 @kbd{C-f} is not a prefix key, so a longer sequence starting with
79 @kbd{C-f} cannot be a key sequence.
81   The set of possible multi-event key sequences depends on the bindings
82 for prefix keys; therefore, it can be different for different keymaps,
83 and can change when bindings are changed.  However, a one-event sequence
84 is always a key sequence, because it does not depend on any prefix keys
85 for its well-formedness.
87   At any time, several primary keymaps are @dfn{active}---that is, in
88 use for finding key bindings.  These are the @dfn{global map}, which is
89 shared by all buffers; the @dfn{local keymap}, which is usually
90 associated with a specific major mode; and zero or more @dfn{minor mode
91 keymaps}, which belong to currently enabled minor modes.  (Not all minor
92 modes have keymaps.)  The local keymap bindings shadow (i.e., take
93 precedence over) the corresponding global bindings.  The minor mode
94 keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
95 for details.
97 @node Format of Keymaps
98 @section Format of Keymaps
99 @cindex format of keymaps
100 @cindex keymap format
101 @cindex full keymap
102 @cindex sparse keymap
104   A keymap is a list whose @sc{car} is the symbol @code{keymap}.  The
105 remaining elements of the list define the key bindings of the keymap.
106 Use the function @code{keymapp} (see below) to test whether an object is
107 a keymap.
109   Several kinds of elements may appear in a keymap, after the symbol
110 @code{keymap} that begins it:
112 @table @code
113 @item (@var{type} .@: @var{binding})
114 This specifies one binding, for events of type @var{type}.  Each
115 ordinary binding applies to events of a particular @dfn{event type},
116 which is always a character or a symbol.  @xref{Classifying Events}.
118 @item (t .@: @var{binding})
119 @cindex default key binding
120 This specifies a @dfn{default key binding}; any event not bound by other
121 elements of the keymap is given @var{binding} as its binding.  Default
122 bindings allow a keymap to bind all possible event types without having
123 to enumerate all of them.  A keymap that has a default binding
124 completely masks any lower-precedence keymap.
126 @item @var{vector}
127 If an element of a keymap is a vector, the vector counts as bindings for
128 all the @sc{ascii} characters, codes 0 through 127; vector element
129 @var{n} is the binding for the character with code @var{n}.  This is a
130 compact way to record lots of bindings.  A keymap with such a vector is
131 called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
132 keymaps}.
134 When a keymap contains a vector, it always defines a binding for each
135 @sc{ascii} character, even if the vector contains @code{nil} for that
136 character.  Such a binding of @code{nil} overrides any default key
137 binding in the keymap, for @sc{ascii} characters.  However, default
138 bindings are still meaningful for events other than @sc{ascii}
139 characters.  A binding of @code{nil} does @emph{not} override
140 lower-precedence keymaps; thus, if the local map gives a binding of
141 @code{nil}, Emacs uses the binding from the global map.
143 @item @var{string}
144 @cindex keymap prompt string
145 @cindex overall prompt string
146 @cindex prompt string of keymap
147 Aside from bindings, a keymap can also have a string as an element.
148 This is called the @dfn{overall prompt string} and makes it possible to
149 use the keymap as a menu.  @xref{Defining Menus}.
150 @end table
152 @cindex meta characters lookup
153   Keymaps do not directly record bindings for the meta characters.
154 Instead, meta characters are regarded for
155 purposes of key lookup as sequences of two characters, the first of
156 which is @key{ESC} (or whatever is currently the value of
157 @code{meta-prefix-char}).  Thus, the key @kbd{M-a} is really represented
158 as @kbd{@key{ESC} a}, and its global binding is found at the slot for
159 @kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).
161   Here as an example is the local keymap for Lisp mode, a sparse
162 keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
163 C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
165 @example
166 @group
167 lisp-mode-map
168 @result{} 
169 @end group
170 @group
171 (keymap 
172  ;; @key{TAB}
173  (9 . lisp-indent-line)                 
174 @end group
175 @group
176  ;; @key{DEL}
177  (127 . backward-delete-char-untabify)  
178 @end group
179 @group
180  (3 keymap 
181     ;; @kbd{C-c C-l}
182     (12 . run-lisp))                    
183 @end group
184 @group
185  (27 keymap 
186      ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
187      (17 . indent-sexp)                 
188      ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
189      (24 . lisp-send-defun)))           
190 @end group
191 @end example
193 @defun keymapp object
194 This function returns @code{t} if @var{object} is a keymap, @code{nil}
195 otherwise.  More precisely, this function tests for a list whose
196 @sc{car} is @code{keymap}.
198 @example
199 @group
200 (keymapp '(keymap))
201     @result{} t
202 @end group
203 @group
204 (keymapp (current-global-map))
205     @result{} t
206 @end group
207 @end example
208 @end defun
210 @node Creating Keymaps
211 @section Creating Keymaps
212 @cindex creating keymaps
214   Here we describe the functions for creating keymaps.
216 @c ??? This should come after make-sparse-keymap
217 @defun make-keymap &optional prompt
218 This function creates and returns a new full keymap (i.e., one
219 containing a vector of length 128 for defining all the @sc{ascii}
220 characters).  The new keymap initially binds all @sc{ascii} characters
221 to @code{nil}, and does not bind any other kind of event.
223 @example
224 @group
225 (make-keymap)
226     @result{} (keymap [nil nil nil @dots{} nil nil])
227 @end group
228 @end example
230 If you specify @var{prompt}, that becomes the overall prompt string for
231 the keymap.  The prompt string is useful for menu keymaps
232 (@pxref{Defining Menus}).
233 @end defun
235 @defun make-sparse-keymap &optional prompt
236 This function creates and returns a new sparse keymap with no entries.
237 The new keymap does not bind any events.  The argument @var{prompt}
238 specifies a prompt string, as in @code{make-keymap}.
240 @example
241 @group
242 (make-sparse-keymap)
243     @result{} (keymap)
244 @end group
245 @end example
246 @end defun
248 @defun copy-keymap keymap
249 This function returns a copy of @var{keymap}.  Any keymaps that
250 appear directly as bindings in @var{keymap} are also copied recursively,
251 and so on to any number of levels.  However, recursive copying does not
252 take place when the definition of a character is a symbol whose function
253 definition is a keymap; the same symbol appears in the new copy.
254 @c Emacs 19 feature
256 @example
257 @group
258 (setq map (copy-keymap (current-local-map)))
259 @result{} (keymap
260 @end group
261 @group
262      ;; @r{(This implements meta characters.)}
263      (27 keymap         
264          (83 . center-paragraph)
265          (115 . center-line))
266      (9 . tab-to-tab-stop))
267 @end group
269 @group
270 (eq map (current-local-map))
271     @result{} nil
272 @end group
273 @group
274 (equal map (current-local-map))
275     @result{} t
276 @end group
277 @end example
278 @end defun
280 @node Inheritance and Keymaps
281 @section Inheritance and Keymaps
282 @cindex keymap inheritance
283 @cindex inheriting a keymap's bindings
285   A keymap can inherit the bindings of another keymap, which we call the
286 @dfn{parent keymap}.  Such a keymap looks like this:
288 @example
289 (keymap @var{bindings}@dots{} . @var{parent-keymap})
290 @end example
292 @noindent
293 The effect is that this keymap inherits all the bindings of
294 @var{parent-keymap}, whatever they may be at the time a key is looked up,
295 but can add to them or override them with @var{bindings}.
297 If you change the bindings in @var{parent-keymap} using @code{define-key}
298 or other key-binding functions, these changes are visible in the
299 inheriting keymap unless shadowed by @var{bindings}.  The converse is
300 not true: if you use @code{define-key} to change the inheriting keymap,
301 that affects @var{bindings}, but has no effect on @var{parent-keymap}.
303 The proper way to construct a keymap with a parent is to use
304 @code{set-keymap-parent}; if you have code that directly constructs a
305 keymap with a parent, please convert the program to use
306 @code{set-keymap-parent} instead.
308 @defun keymap-parent keymap
309 This returns the parent keymap of @var{keymap}.  If @var{keymap}
310 has no parent, @code{keymap-parent} returns @code{nil}.
311 @end defun
313 @defun set-keymap-parent keymap parent
314 This sets the parent keymap of @var{keymap} to @var{parent}, and returns
315 @var{parent}.  If @var{parent} is @code{nil}, this function gives
316 @var{keymap} no parent at all.
318 If @var{keymap} has submaps (bindings for prefix keys), they too receive
319 new parent keymaps that reflect what @var{parent} specifies for those
320 prefix keys.
321 @end defun
323 Here is an example showing how to make a keymap that inherits
324 from @code{text-mode-map}:
326 @example
327 (let ((map (make-sparse-keymap)))
328   (set-keymap-parent map text-mode-map)
329   map)
330 @end example
332 @node Prefix Keys
333 @section Prefix Keys
334 @cindex prefix key
336   A @dfn{prefix key} is a key sequence whose binding is a keymap.  The
337 keymap defines what to do with key sequences that extend the prefix key.
338 For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
339 also stored in the variable @code{ctl-x-map}.  This keymap defines
340 bindings for key sequences starting with @kbd{C-x}.
342   Some of the standard Emacs prefix keys use keymaps that are
343 also found in Lisp variables:
345 @itemize @bullet
346 @item
347 @vindex esc-map
348 @findex ESC-prefix
349 @code{esc-map} is the global keymap for the @key{ESC} prefix key.  Thus,
350 the global definitions of all meta characters are actually found here.
351 This map is also the function definition of @code{ESC-prefix}.
353 @item
354 @cindex @kbd{C-h}
355 @code{help-map} is the global keymap for the @kbd{C-h} prefix key.
357 @item
358 @cindex @kbd{C-c}
359 @vindex mode-specific-map
360 @code{mode-specific-map} is the global keymap for the prefix key
361 @kbd{C-c}.  This map is actually global, not mode-specific, but its name
362 provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
363 (@code{display-bindings}), since the main use of this prefix key is for
364 mode-specific bindings.
366 @item
367 @cindex @kbd{C-x}
368 @vindex ctl-x-map
369 @findex Control-X-prefix
370 @code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
371 This map is found via the function cell of the symbol
372 @code{Control-X-prefix}.
374 @item
375 @cindex @kbd{C-x @key{RET}}
376 @vindex mule-keymap
377 @code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
378 prefix key.
380 @item
381 @cindex @kbd{C-x 4}
382 @vindex ctl-x-4-map
383 @code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
384 key.
386 @c Emacs 19 feature
387 @item
388 @cindex @kbd{C-x 5}
389 @vindex ctl-x-5-map
390 @code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
391 key.
393 @c Emacs 19 feature
394 @item
395 @cindex @kbd{C-x 6}
396 @vindex 2C-mode-map
397 @code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
398 key.
400 @item
401 @cindex @kbd{C-x v}
402 @vindex vc-prefix-map
403 @code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
404 key.
406 @item
407 @cindex @kbd{M-g}
408 @vindex facemenu-keymap
409 @code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
410 prefix key.
412 @c Emacs 19 feature
413 @item
414 The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
415 @key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps that have no
416 special names.
417 @end itemize
419   The keymap binding of a prefix key is used for looking up the event
420 that follows the prefix key.  (It may instead be a symbol whose function
421 definition is a keymap.  The effect is the same, but the symbol serves
422 as a name for the prefix key.)  Thus, the binding of @kbd{C-x} is the
423 symbol @code{Control-X-prefix}, whose function cell holds the keymap
424 for @kbd{C-x} commands.  (The same keymap is also the value of
425 @code{ctl-x-map}.)
427   Prefix key definitions can appear in any active keymap.  The
428 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
429 keys appear in the global map, so these prefix keys are always
430 available.  Major and minor modes can redefine a key as a prefix by
431 putting a prefix key definition for it in the local map or the minor
432 mode's map.  @xref{Active Keymaps}.
434   If a key is defined as a prefix in more than one active map, then its
435 various definitions are in effect merged: the commands defined in the
436 minor mode keymaps come first, followed by those in the local map's
437 prefix definition, and then by those from the global map.
439   In the following example, we make @kbd{C-p} a prefix key in the local
440 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
441 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
442 like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
443 active keymap.
445 @example
446 @group
447 (use-local-map (make-sparse-keymap))
448     @result{} nil
449 @end group
450 @group
451 (local-set-key "\C-p" ctl-x-map)
452     @result{} nil
453 @end group
454 @group
455 (key-binding "\C-p\C-f")
456     @result{} find-file
457 @end group
459 @group
460 (key-binding "\C-p6")
461     @result{} nil
462 @end group
463 @end example
465 @defun define-prefix-command symbol &optional mapvar prompt
466 @cindex prefix command
467 This function prepares @var{symbol} for use as a prefix key's binding:
468 it creates a sparse keymap and stores it as @var{symbol}'s function
469 definition.  Subsequently binding a key sequence to @var{symbol} will
470 make that key sequence into a prefix key.  The return value is @code{symbol}.
472 This function also sets @var{symbol} as a variable, with the keymap as
473 its value.  But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
474 as a variable instead.
476 If @var{prompt} is non-@code{nil}, that becomes the overall prompt
477 string for the keymap.  The prompt string is useful for menu keymaps
478 (@pxref{Defining Menus}).
479 @end defun
481 @node Active Keymaps
482 @section Active Keymaps
483 @cindex active keymap
484 @cindex global keymap
485 @cindex local keymap
487   Emacs normally contains many keymaps; at any given time, just a few of
488 them are @dfn{active} in that they participate in the interpretation
489 of user input.  These are the global keymap, the current buffer's
490 local keymap, and the keymaps of any enabled minor modes.
492   The @dfn{global keymap} holds the bindings of keys that are defined
493 regardless of the current buffer, such as @kbd{C-f}.  The variable
494 @code{global-map} holds this keymap, which is always active.
496   Each buffer may have another keymap, its @dfn{local keymap}, which may
497 contain new or overriding definitions for keys.  The current buffer's
498 local keymap is always active except when @code{overriding-local-map}
499 overrides it.  Text properties can specify an alternative local map for
500 certain parts of the buffer; see @ref{Special Properties}.
502   Each minor mode can have a keymap; if it does, the keymap is active
503 when the minor mode is enabled.
505   The variable @code{overriding-local-map}, if non-@code{nil}, specifies
506 another local keymap that overrides the buffer's local map and all the 
507 minor mode keymaps.
509   All the active keymaps are used together to determine what command to
510 execute when a key is entered.  Emacs searches these maps one by one, in
511 order of decreasing precedence, until it finds a binding in one of the
512 maps.  The procedure for searching a single keymap is called @dfn{key
513 lookup}; see @ref{Key Lookup}.
515   Normally, Emacs first searches for the key in the minor mode maps, in
516 the order specified by @code{minor-mode-map-alist}; if they do not
517 supply a binding for the key, Emacs searches the local map; if that too
518 has no binding, Emacs then searches the global map.  However, if
519 @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
520 first, before the global map.
522 @cindex major mode keymap
523   Since every buffer that uses the same major mode normally uses the
524 same local keymap, you can think of the keymap as local to the mode.  A
525 change to the local keymap of a buffer (using @code{local-set-key}, for
526 example) is seen also in the other buffers that share that keymap.
528   The local keymaps that are used for Lisp mode and some other major
529 modes exist even if they have not yet been used.  These local maps are
530 the values of variables such as @code{lisp-mode-map}.  For most major
531 modes, which are less frequently used, the local keymap is constructed
532 only when the mode is used for the first time in a session.
534   The minibuffer has local keymaps, too; they contain various completion
535 and exit commands.  @xref{Intro to Minibuffers}.
537   Emacs has other keymaps that are used in a different way---translating
538 events within @code{read-key-sequence}.  @xref{Translating Input}.
540   @xref{Standard Keymaps}, for a list of standard keymaps.
542 @defvar global-map
543 This variable contains the default global keymap that maps Emacs
544 keyboard input to commands.  The global keymap is normally this keymap.
545 The default global keymap is a full keymap that binds
546 @code{self-insert-command} to all of the printing characters.
548 It is normal practice to change the bindings in the global map, but you
549 should not assign this variable any value other than the keymap it starts
550 out with.
551 @end defvar
553 @defun current-global-map
554 This function returns the current global keymap.  This is the
555 same as the value of @code{global-map} unless you change one or the
556 other.
558 @example
559 @group
560 (current-global-map)
561 @result{} (keymap [set-mark-command beginning-of-line @dots{} 
562             delete-backward-char])
563 @end group
564 @end example
565 @end defun
567 @defun current-local-map
568 This function returns the current buffer's local keymap, or @code{nil}
569 if it has none.  In the following example, the keymap for the
570 @samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
571 in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
572 keymap.
574 @example
575 @group
576 (current-local-map)
577 @result{} (keymap 
578     (10 . eval-print-last-sexp) 
579     (9 . lisp-indent-line) 
580     (127 . backward-delete-char-untabify) 
581 @end group
582 @group
583     (27 keymap 
584         (24 . eval-defun) 
585         (17 . indent-sexp)))
586 @end group
587 @end example
588 @end defun
590 @defun current-minor-mode-maps
591 This function returns a list of the keymaps of currently enabled minor modes.
592 @end defun
594 @defun use-global-map keymap
595 This function makes @var{keymap} the new current global keymap.  It
596 returns @code{nil}.
598 It is very unusual to change the global keymap.
599 @end defun
601 @defun use-local-map keymap
602 This function makes @var{keymap} the new local keymap of the current
603 buffer.  If @var{keymap} is @code{nil}, then the buffer has no local
604 keymap.  @code{use-local-map} returns @code{nil}.  Most major mode
605 commands use this function.
606 @end defun
608 @c Emacs 19 feature
609 @defvar minor-mode-map-alist
610 This variable is an alist describing keymaps that may or may not be
611 active according to the values of certain variables.  Its elements look
612 like this:
614 @example
615 (@var{variable} . @var{keymap})
616 @end example
618 The keymap @var{keymap} is active whenever @var{variable} has a
619 non-@code{nil} value.  Typically @var{variable} is the variable that
620 enables or disables a minor mode.  @xref{Keymaps and Minor Modes}.
622 Note that elements of @code{minor-mode-map-alist} do not have the same
623 structure as elements of @code{minor-mode-alist}.  The map must be the
624 @sc{cdr} of the element; a list with the map as the second element will
625 not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
626 function definition is a keymap.
628 When more than one minor mode keymap is active, their order of priority
629 is the order of @code{minor-mode-map-alist}.  But you should design
630 minor modes so that they don't interfere with each other.  If you do
631 this properly, the order will not matter.
633 See @ref{Keymaps and Minor Modes}, for more information about minor
634 modes.  See also @code{minor-mode-key-binding} (@pxref{Functions for Key
635 Lookup}).
636 @end defvar
638 @defvar minor-mode-overriding-map-alist
639 This variable allows major modes to override the key bindings for
640 particular minor modes.  The elements of this alist look like the
641 elements of @code{minor-mode-map-alist}: @code{(@var{variable}
642 . @var{keymap})}.
644 If a variable appears as an element of
645 @code{minor-mode-overriding-map-alist}, the map specified by that
646 element totally replaces any map specified for the same variable in
647 @code{minor-mode-map-alist}.
649 @code{minor-mode-overriding-map-alist} is automatically buffer-local in
650 all buffers.
651 @end defvar
653 @defvar overriding-local-map
654 If non-@code{nil}, this variable holds a keymap to use instead of the
655 buffer's local keymap and instead of all the minor mode keymaps.  This
656 keymap, if any, overrides all other maps that would have been active,
657 except for the current global map.
658 @end defvar
660 @defvar overriding-terminal-local-map
661 If non-@code{nil}, this variable holds a keymap to use instead of
662 @code{overriding-local-map}, the buffer's local keymap and all the minor
663 mode keymaps.
665 This variable is always local to the current terminal and cannot be
666 buffer-local.  @xref{Multiple Displays}.  It is used to implement
667 incremental search mode.
668 @end defvar
670 @defvar overriding-local-map-menu-flag
671 If this variable is non-@code{nil}, the value of
672 @code{overriding-local-map} or @code{overriding-terminal-local-map} can
673 affect the display of the menu bar.  The default value is @code{nil}, so
674 those map variables have no effect on the menu bar.
676 Note that these two map variables do affect the execution of key
677 sequences entered using the menu bar, even if they do not affect the
678 menu bar display.  So if a menu bar key sequence comes in, you should
679 clear the variables before looking up and executing that key sequence.
680 Modes that use the variables would typically do this anyway; normally
681 they respond to events that they do not handle by ``unreading'' them and
682 exiting.
683 @end defvar
685 @defvar special-event-map
686 This variable holds a keymap for special events.  If an event type has a
687 binding in this keymap, then it is special, and the binding for the
688 event is run directly by @code{read-event}.  @xref{Special Events}.
689 @end defvar
691 @node Key Lookup
692 @section Key Lookup
693 @cindex key lookup
694 @cindex keymap entry
696   @dfn{Key lookup} is the process of finding the binding of a key
697 sequence from a given keymap.  Actual execution of the binding is not
698 part of key lookup.
700   Key lookup uses just the event type of each event in the key sequence;
701 the rest of the event is ignored.  In fact, a key sequence used for key
702 lookup may designate mouse events with just their types (symbols)
703 instead of with entire mouse events (lists).  @xref{Input Events}.  Such
704 a ``key-sequence'' is insufficient for @code{command-execute} to run,
705 but it is sufficient for looking up or rebinding a key.
707   When the key sequence consists of multiple events, key lookup
708 processes the events sequentially: the binding of the first event is
709 found, and must be a keymap; then the second event's binding is found in
710 that keymap, and so on until all the events in the key sequence are used
711 up.  (The binding thus found for the last event may or may not be a
712 keymap.)  Thus, the process of key lookup is defined in terms of a
713 simpler process for looking up a single event in a keymap.  How that is
714 done depends on the type of object associated with the event in that
715 keymap.
717   Let's use the term @dfn{keymap entry} to describe the value found by
718 looking up an event type in a keymap.  (This doesn't include the item
719 string and other extra elements in menu key bindings, because
720 @code{lookup-key} and other key lookup functions don't include them in
721 the returned value.)  While any Lisp object may be stored in a keymap as
722 a keymap entry, not all make sense for key lookup.  Here is a table of
723 the meaningful kinds of keymap entries:
725 @table @asis
726 @item @code{nil}
727 @cindex @code{nil} in keymap
728 @code{nil} means that the events used so far in the lookup form an
729 undefined key.  When a keymap fails to mention an event type at all, and
730 has no default binding, that is equivalent to a binding of @code{nil}
731 for that event type.
733 @item @var{command}
734 @cindex command in keymap
735 The events used so far in the lookup form a complete key,
736 and @var{command} is its binding.  @xref{What Is a Function}.
738 @item @var{array}
739 @cindex string in keymap
740 The array (either a string or a vector) is a keyboard macro.  The events
741 used so far in the lookup form a complete key, and the array is its
742 binding.  See @ref{Keyboard Macros}, for more information.
744 @item @var{keymap}
745 @cindex keymap in keymap
746 The events used so far in the lookup form a prefix key.  The next
747 event of the key sequence is looked up in @var{keymap}.
749 @item @var{list}
750 @cindex list in keymap
751 The meaning of a list depends on the types of the elements of the list.
753 @itemize @bullet
754 @item
755 If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
756 is a keymap, and is treated as a keymap (see above).
758 @item
759 @cindex @code{lambda} in keymap
760 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
761 lambda expression.  This is presumed to be a command, and is treated as
762 such (see above).
764 @item
765 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
766 type, then this is an @dfn{indirect entry}:
768 @example
769 (@var{othermap} . @var{othertype})
770 @end example
772 When key lookup encounters an indirect entry, it looks up instead the
773 binding of @var{othertype} in @var{othermap} and uses that.
775 This feature permits you to define one key as an alias for another key.
776 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
777 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
778 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
779 @end itemize
781 @item @var{symbol}
782 @cindex symbol in keymap
783 The function definition of @var{symbol} is used in place of
784 @var{symbol}.  If that too is a symbol, then this process is repeated,
785 any number of times.  Ultimately this should lead to an object that is
786 a keymap, a command, or a keyboard macro.  A list is allowed if it is a
787 keymap or a command, but indirect entries are not understood when found
788 via symbols.
790 Note that keymaps and keyboard macros (strings and vectors) are not
791 valid functions, so a symbol with a keymap, string, or vector as its
792 function definition is invalid as a function.  It is, however, valid as
793 a key binding.  If the definition is a keyboard macro, then the symbol
794 is also valid as an argument to @code{command-execute}
795 (@pxref{Interactive Call}).
797 @cindex @code{undefined} in keymap
798 The symbol @code{undefined} is worth special mention: it means to treat
799 the key as undefined.  Strictly speaking, the key is defined, and its
800 binding is the command @code{undefined}; but that command does the same
801 thing that is done automatically for an undefined key: it rings the bell
802 (by calling @code{ding}) but does not signal an error.
804 @cindex preventing prefix key
805 @code{undefined} is used in local keymaps to override a global key
806 binding and make the key ``undefined'' locally.  A local binding of
807 @code{nil} would fail to do this because it would not override the
808 global binding.
810 @item @var{anything else}
811 If any other type of object is found, the events used so far in the
812 lookup form a complete key, and the object is its binding, but the
813 binding is not executable as a command.
814 @end table
816   In short, a keymap entry may be a keymap, a command, a keyboard macro,
817 a symbol that leads to one of them, or an indirection or @code{nil}.
818 Here is an example of a sparse keymap with two characters bound to
819 commands and one bound to another keymap.  This map is the normal value
820 of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
821 127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
822 @kbd{C-x}.
824 @example
825 @group
826 (keymap (9 . lisp-indent-line)
827         (127 . backward-delete-char-untabify)
828         (27 keymap (17 . indent-sexp) (24 . eval-defun)))
829 @end group
830 @end example
832 @node Functions for Key Lookup
833 @section Functions for Key Lookup
835   Here are the functions and variables pertaining to key lookup.
837 @defun lookup-key keymap key &optional accept-defaults
838 This function returns the definition of @var{key} in @var{keymap}.  All
839 the other functions described in this chapter that look up keys use
840 @code{lookup-key}.  Here are examples:
842 @example
843 @group
844 (lookup-key (current-global-map) "\C-x\C-f")
845     @result{} find-file
846 @end group
847 @group
848 (lookup-key (current-global-map) "\C-x\C-f12345")
849     @result{} 2
850 @end group
851 @end example
853 If the string or vector @var{key} is not a valid key sequence according
854 to the prefix keys specified in @var{keymap}, it must be ``too long''
855 and have extra events at the end that do not fit into a single key
856 sequence.  Then the value is a number, the number of events at the front
857 of @var{key} that compose a complete key.
859 @c Emacs 19 feature
860 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
861 considers default bindings as well as bindings for the specific events
862 in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
863 the specific sequence @var{key}, ignoring default bindings except when
864 you explicitly ask about them.  (To do this, supply @code{t} as an
865 element of @var{key}; see @ref{Format of Keymaps}.)
867 If @var{key} contains a meta character, that character is implicitly
868 replaced by a two-character sequence: the value of
869 @code{meta-prefix-char}, followed by the corresponding non-meta
870 character.  Thus, the first example below is handled by conversion into
871 the second example.
873 @example
874 @group
875 (lookup-key (current-global-map) "\M-f")
876     @result{} forward-word
877 @end group
878 @group
879 (lookup-key (current-global-map) "\ef")
880     @result{} forward-word
881 @end group
882 @end example
884 Unlike @code{read-key-sequence}, this function does not modify the
885 specified events in ways that discard information (@pxref{Key Sequence
886 Input}).  In particular, it does not convert letters to lower case and
887 it does not change drag events to clicks.
888 @end defun
890 @deffn Command undefined
891 Used in keymaps to undefine keys.  It calls @code{ding}, but does
892 not cause an error.
893 @end deffn
895 @defun key-binding key &optional accept-defaults
896 This function returns the binding for @var{key} in the current
897 keymaps, trying all the active keymaps.  The result is @code{nil} if
898 @var{key} is undefined in the keymaps.
900 @c Emacs 19 feature
901 The argument @var{accept-defaults} controls checking for default
902 bindings, as in @code{lookup-key} (above).
904 An error is signaled if @var{key} is not a string or a vector.
906 @example
907 @group
908 (key-binding "\C-x\C-f")
909     @result{} find-file
910 @end group
911 @end example
912 @end defun
914 @defun local-key-binding key &optional accept-defaults
915 This function returns the binding for @var{key} in the current
916 local keymap, or @code{nil} if it is undefined there.
918 @c Emacs 19 feature
919 The argument @var{accept-defaults} controls checking for default bindings,
920 as in @code{lookup-key} (above).
921 @end defun
923 @defun global-key-binding key &optional accept-defaults
924 This function returns the binding for command @var{key} in the
925 current global keymap, or @code{nil} if it is undefined there.
927 @c Emacs 19 feature
928 The argument @var{accept-defaults} controls checking for default bindings,
929 as in @code{lookup-key} (above).
930 @end defun
932 @c Emacs 19 feature
933 @defun minor-mode-key-binding key &optional accept-defaults
934 This function returns a list of all the active minor mode bindings of
935 @var{key}.  More precisely, it returns an alist of pairs
936 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
937 variable that enables the minor mode, and @var{binding} is @var{key}'s
938 binding in that mode.  If @var{key} has no minor-mode bindings, the
939 value is @code{nil}.
941 If the first binding found is not a prefix definition (a keymap or a
942 symbol defined as a keymap), all subsequent bindings from other minor
943 modes are omitted, since they would be completely shadowed.  Similarly,
944 the list omits non-prefix bindings that follow prefix bindings.
946 The argument @var{accept-defaults} controls checking for default
947 bindings, as in @code{lookup-key} (above).
948 @end defun
950 @defvar meta-prefix-char
951 @cindex @key{ESC}
952 This variable is the meta-prefix character code.  It is used when
953 translating a meta character to a two-character sequence so it can be
954 looked up in a keymap.  For useful results, the value should be a prefix
955 event (@pxref{Prefix Keys}).  The default value is 27, which is the
956 @sc{ascii} code for @key{ESC}.
958 As long as the value of @code{meta-prefix-char} remains 27, key
959 lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
960 defined as the @code{backward-word} command.  However, if you set
961 @code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
962 translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
963 @code{switch-to-buffer} command.  Here is an illustration:
965 @smallexample
966 @group
967 meta-prefix-char                    ; @r{The default value.}
968      @result{} 27
969 @end group
970 @group
971 (key-binding "\M-b")
972      @result{} backward-word
973 @end group
974 @group
975 ?\C-x                               ; @r{The print representation}
976      @result{} 24                          ;   @r{of a character.}
977 @end group
978 @group
979 (setq meta-prefix-char 24)
980      @result{} 24      
981 @end group
982 @group
983 (key-binding "\M-b")
984      @result{} switch-to-buffer            ; @r{Now, typing @kbd{M-b} is}
985                                     ;   @r{like typing @kbd{C-x b}.}
987 (setq meta-prefix-char 27)          ; @r{Avoid confusion!}
988      @result{} 27                          ; @r{Restore the default value!}
989 @end group
990 @end smallexample
991 @end defvar
993 @node Changing Key Bindings
994 @section Changing Key Bindings
995 @cindex changing key bindings
996 @cindex rebinding
998   The way to rebind a key is to change its entry in a keymap.  If you
999 change a binding in the global keymap, the change is effective in all
1000 buffers (though it has no direct effect in buffers that shadow the
1001 global binding with a local one).  If you change the current buffer's
1002 local map, that usually affects all buffers using the same major mode.
1003 The @code{global-set-key} and @code{local-set-key} functions are
1004 convenient interfaces for these operations (@pxref{Key Binding
1005 Commands}).  You can also use @code{define-key}, a more general
1006 function; then you must specify explicitly the map to change.
1008 @cindex meta character key constants
1009 @cindex control character key constants
1010   In writing the key sequence to rebind, it is good to use the special
1011 escape sequences for control and meta characters (@pxref{String Type}).
1012 The syntax @samp{\C-} means that the following character is a control
1013 character and @samp{\M-} means that the following character is a meta
1014 character.  Thus, the string @code{"\M-x"} is read as containing a
1015 single @kbd{M-x}, @code{"\C-f"} is read as containing a single
1016 @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
1017 containing a single @kbd{C-M-x}.  You can also use this escape syntax in
1018 vectors, as well as others that aren't allowed in strings; one example
1019 is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
1021   The key definition and lookup functions accept an alternate syntax for
1022 event types in a key sequence that is a vector: you can use a list
1023 containing modifier names plus one base event (a character or function
1024 key name).  For example, @code{(control ?a)} is equivalent to
1025 @code{?\C-a} and @code{(hyper control left)} is equivalent to
1026 @code{C-H-left}.  One advantage of such lists is that the precise
1027 numeric codes for the modifier bits don't appear in compiled files.
1029   For the functions below, an error is signaled if @var{keymap} is not a
1030 keymap or if @var{key} is not a string or vector representing a key
1031 sequence.  You can use event types (symbols) as shorthand for events
1032 that are lists.
1034 @defun define-key keymap key binding
1035 This function sets the binding for @var{key} in @var{keymap}.  (If
1036 @var{key} is more than one event long, the change is actually made
1037 in another keymap reached from @var{keymap}.)  The argument
1038 @var{binding} can be any Lisp object, but only certain types are
1039 meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
1040 The value returned by @code{define-key} is @var{binding}.
1042 @cindex invalid prefix key error
1043 @cindex key sequence error
1044 Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
1045 or undefined; otherwise an error is signaled.  If some prefix of
1046 @var{key} is undefined, then @code{define-key} defines it as a prefix
1047 key so that the rest of @var{key} can be defined as specified.
1049 If there was previously no binding for @var{key} in @var{keymap}, the
1050 new binding is added at the beginning of @var{keymap}.  The order of
1051 bindings in a keymap makes no difference in most cases, but it does
1052 matter for menu keymaps (@pxref{Menu Keymaps}).
1053 @end defun
1055   Here is an example that creates a sparse keymap and makes a number of
1056 bindings in it:
1058 @smallexample
1059 @group
1060 (setq map (make-sparse-keymap))
1061     @result{} (keymap)
1062 @end group
1063 @group
1064 (define-key map "\C-f" 'forward-char)
1065     @result{} forward-char
1066 @end group
1067 @group
1069     @result{} (keymap (6 . forward-char))
1070 @end group
1072 @group
1073 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
1074 (define-key map "\C-xf" 'forward-word)
1075     @result{} forward-word
1076 @end group
1077 @group
1079 @result{} (keymap 
1080     (24 keymap                ; @kbd{C-x}
1081         (102 . forward-word)) ;      @kbd{f}
1082     (6 . forward-char))       ; @kbd{C-f}
1083 @end group
1085 @group
1086 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1087 (define-key map "\C-p" ctl-x-map)
1088 ;; @code{ctl-x-map}
1089 @result{} [nil @dots{} find-file @dots{} backward-kill-sentence] 
1090 @end group
1092 @group
1093 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1094 (define-key map "\C-p\C-f" 'foo)
1095 @result{} 'foo
1096 @end group
1097 @group
1099 @result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
1100     (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1101     (24 keymap 
1102         (102 . forward-word))
1103     (6 . forward-char))
1104 @end group
1105 @end smallexample
1107 @noindent
1108 Note that storing a new binding for @kbd{C-p C-f} actually works by
1109 changing an entry in @code{ctl-x-map}, and this has the effect of
1110 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1111 default global map.
1113 @defun substitute-key-definition olddef newdef keymap &optional oldmap
1114 @cindex replace bindings
1115 This function replaces @var{olddef} with @var{newdef} for any keys in
1116 @var{keymap} that were bound to @var{olddef}.  In other words,
1117 @var{olddef} is replaced with @var{newdef} wherever it appears.  The
1118 function returns @code{nil}.
1120 For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
1121 standard bindings:
1123 @smallexample
1124 @group
1125 (substitute-key-definition 
1126  'find-file 'find-file-read-only (current-global-map))
1127 @end group
1128 @end smallexample
1130 @c Emacs 19 feature
1131 If @var{oldmap} is non-@code{nil}, that changes the behavior of
1132 @code{substitute-key-definition}: the bindings in @var{oldmap} determine
1133 which keys to rebind.  The rebindings still happen in @var{keymap}, not
1134 in @var{oldmap}.  Thus, you can change one map under the control of the
1135 bindings in another.  For example,
1137 @smallexample
1138 (substitute-key-definition
1139   'delete-backward-char 'my-funny-delete
1140   my-map global-map)
1141 @end smallexample
1143 @noindent
1144 puts the special deletion command in @code{my-map} for whichever keys
1145 are globally bound to the standard deletion command.
1147 @ignore
1148 @c Emacs 18 only
1149 Prefix keymaps that appear within @var{keymap} are not checked
1150 recursively for keys bound to @var{olddef}; they are not changed at all.
1151 Perhaps it would be better to check nested keymaps recursively.
1152 @end ignore
1154 Here is an example showing a keymap before and after substitution:
1156 @smallexample
1157 @group
1158 (setq map '(keymap 
1159             (?1 . olddef-1) 
1160             (?2 . olddef-2) 
1161             (?3 . olddef-1)))
1162 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1163 @end group
1165 @group
1166 (substitute-key-definition 'olddef-1 'newdef map)
1167 @result{} nil
1168 @end group
1169 @group
1171 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1172 @end group
1173 @end smallexample
1174 @end defun
1176 @defun suppress-keymap keymap &optional nodigits
1177 @cindex @code{self-insert-command} override
1178 This function changes the contents of the full keymap @var{keymap} by
1179 making all the printing characters undefined.  More precisely, it binds
1180 them to the command @code{undefined}.  This makes ordinary insertion of
1181 text impossible.  @code{suppress-keymap} returns @code{nil}.
1183 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1184 digits to run @code{digit-argument}, and @kbd{-} to run
1185 @code{negative-argument}.  Otherwise it makes them undefined like the
1186 rest of the printing characters.
1188 @cindex yank suppression 
1189 @cindex @code{quoted-insert} suppression 
1190 The @code{suppress-keymap} function does not make it impossible to
1191 modify a buffer, as it does not suppress commands such as @code{yank}
1192 and @code{quoted-insert}.  To prevent any modification of a buffer, make
1193 it read-only (@pxref{Read Only Buffers}).
1195 Since this function modifies @var{keymap}, you would normally use it
1196 on a newly created keymap.  Operating on an existing keymap
1197 that is used for some other purpose is likely to cause trouble; for
1198 example, suppressing @code{global-map} would make it impossible to use
1199 most of Emacs.
1201 Most often, @code{suppress-keymap} is used to initialize local
1202 keymaps of modes such as Rmail and Dired where insertion of text is not
1203 desirable and the buffer is read-only.  Here is an example taken from
1204 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
1205 Dired mode is set up:
1207 @smallexample
1208 @group
1209 (setq dired-mode-map (make-keymap))
1210 (suppress-keymap dired-mode-map)
1211 (define-key dired-mode-map "r" 'dired-rename-file)
1212 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1213 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1214 (define-key dired-mode-map "v" 'dired-view-file)
1215 (define-key dired-mode-map "e" 'dired-find-file)
1216 (define-key dired-mode-map "f" 'dired-find-file)
1217 @dots{}
1218 @end group
1219 @end smallexample
1220 @end defun
1222 @node Key Binding Commands
1223 @section Commands for Binding Keys
1225   This section describes some convenient interactive interfaces for
1226 changing key bindings.  They work by calling @code{define-key}.
1228   People often use @code{global-set-key} in their init files
1229 (@pxref{Init File}) for simple customization.  For example,
1231 @smallexample
1232 (global-set-key "\C-x\C-\\" 'next-line)
1233 @end smallexample
1235 @noindent
1238 @smallexample
1239 (global-set-key [?\C-x ?\C-\\] 'next-line)
1240 @end smallexample
1242 @noindent
1245 @smallexample
1246 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1247 @end smallexample
1249 @noindent
1250 redefines @kbd{C-x C-\} to move down a line.
1252 @smallexample
1253 (global-set-key [M-mouse-1] 'mouse-set-point)
1254 @end smallexample
1256 @noindent
1257 redefines the first (leftmost) mouse button, typed with the Meta key, to
1258 set point where you click.
1260 @cindex non-@sc{ascii} text in keybindings
1261   Be careful when using non-@sc{ascii} text characters in Lisp
1262 specifications of keys to bind.  If these are read as multibyte text, as
1263 they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
1264 must type the keys as multibyte too.  For instance, if you use this:
1266 @smallexample
1267 (global-set-key "@"o" 'my-function) ; bind o-umlaut
1268 @end smallexample
1270 @noindent
1273 @smallexample
1274 (global-set-key ?@"o 'my-function) ; bind o-umlaut
1275 @end smallexample
1277 @noindent
1278 and your language environment is multibyte Latin-1, these commands
1279 actually bind the multibyte character with code 2294, not the unibyte
1280 Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
1281 binding, you need to enter the multibyte Latin-1 character as keyboard
1282 input.  One way to do this is by using an appropriate input method
1283 (@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
1285   If you want to use a unibyte character in the key binding, you can
1286 construct the key sequence string using @code{multibyte-char-to-unibyte}
1287 or @code{string-make-unibyte} (@pxref{Converting Representations}).
1289 @deffn Command global-set-key key definition
1290 This function sets the binding of @var{key} in the current global map
1291 to @var{definition}.
1293 @smallexample
1294 @group
1295 (global-set-key @var{key} @var{definition})
1296 @equiv{}
1297 (define-key (current-global-map) @var{key} @var{definition})
1298 @end group
1299 @end smallexample
1300 @end deffn
1302 @deffn Command global-unset-key key
1303 @cindex unbinding keys
1304 This function removes the binding of @var{key} from the current
1305 global map.
1307 One use of this function is in preparation for defining a longer key
1308 that uses @var{key} as a prefix---which would not be allowed if
1309 @var{key} has a non-prefix binding.  For example:
1311 @smallexample
1312 @group
1313 (global-unset-key "\C-l")
1314     @result{} nil
1315 @end group
1316 @group
1317 (global-set-key "\C-l\C-l" 'redraw-display)
1318     @result{} nil
1319 @end group
1320 @end smallexample
1322 This function is implemented simply using @code{define-key}:
1324 @smallexample
1325 @group
1326 (global-unset-key @var{key})
1327 @equiv{}
1328 (define-key (current-global-map) @var{key} nil)
1329 @end group
1330 @end smallexample
1331 @end deffn
1333 @deffn Command local-set-key key definition
1334 This function sets the binding of @var{key} in the current local
1335 keymap to @var{definition}.
1337 @smallexample
1338 @group
1339 (local-set-key @var{key} @var{definition})
1340 @equiv{}
1341 (define-key (current-local-map) @var{key} @var{definition})
1342 @end group
1343 @end smallexample
1344 @end deffn
1346 @deffn Command local-unset-key key
1347 This function removes the binding of @var{key} from the current
1348 local map.
1350 @smallexample
1351 @group
1352 (local-unset-key @var{key})
1353 @equiv{}
1354 (define-key (current-local-map) @var{key} nil)
1355 @end group
1356 @end smallexample
1357 @end deffn
1359 @node Scanning Keymaps
1360 @section Scanning Keymaps
1362   This section describes functions used to scan all the current keymaps
1363 for the sake of printing help information.
1365 @defun accessible-keymaps keymap &optional prefix
1366 This function returns a list of all the keymaps that can be reached (via
1367 zero or more prefix keys) from @var{keymap}.  The value is an
1368 association list with elements of the form @code{(@var{key} .@:
1369 @var{map})}, where @var{key} is a prefix key whose definition in
1370 @var{keymap} is @var{map}.
1372 The elements of the alist are ordered so that the @var{key} increases
1373 in length.  The first element is always @code{("" .@: @var{keymap})},
1374 because the specified keymap is accessible from itself with a prefix of
1375 no events.
1377 If @var{prefix} is given, it should be a prefix key sequence; then
1378 @code{accessible-keymaps} includes only the submaps whose prefixes start
1379 with @var{prefix}.  These elements look just as they do in the value of
1380 @code{(accessible-keymaps)}; the only difference is that some elements
1381 are omitted.
1383 In the example below, the returned alist indicates that the key
1384 @key{ESC}, which is displayed as @samp{^[}, is a prefix key whose
1385 definition is the sparse keymap @code{(keymap (83 .@: center-paragraph)
1386 (115 .@: foo))}.
1388 @smallexample
1389 @group
1390 (accessible-keymaps (current-local-map))
1391 @result{}(("" keymap 
1392       (27 keymap   ; @r{Note this keymap for @key{ESC} is repeated below.}
1393           (83 . center-paragraph)
1394           (115 . center-line))
1395       (9 . tab-to-tab-stop))
1396 @end group
1398 @group
1399    ("^[" keymap 
1400     (83 . center-paragraph) 
1401     (115 . foo)))
1402 @end group
1403 @end smallexample
1405 In the following example, @kbd{C-h} is a prefix key that uses a sparse
1406 keymap starting with @code{(keymap (118 . describe-variable)@dots{})}.
1407 Another prefix, @kbd{C-x 4}, uses a keymap which is also the value of
1408 the variable @code{ctl-x-4-map}.  The event @code{mode-line} is one of
1409 several dummy events used as prefixes for mouse actions in special parts
1410 of a window.
1412 @smallexample
1413 @group
1414 (accessible-keymaps (current-global-map))
1415 @result{} (("" keymap [set-mark-command beginning-of-line @dots{} 
1416                    delete-backward-char])
1417 @end group
1418 @group
1419     ("^H" keymap (118 . describe-variable) @dots{}
1420      (8 . help-for-help))
1421 @end group
1422 @group
1423     ("^X" keymap [x-flush-mouse-queue @dots{}
1424      backward-kill-sentence])
1425 @end group
1426 @group
1427     ("^[" keymap [mark-sexp backward-sexp @dots{}
1428      backward-kill-word])
1429 @end group
1430     ("^X4" keymap (15 . display-buffer) @dots{})
1431 @group
1432     ([mode-line] keymap
1433      (S-mouse-2 . mouse-split-window-horizontally) @dots{}))
1434 @end group
1435 @end smallexample
1437 @noindent
1438 These are not all the keymaps you would see in actuality.
1439 @end defun
1441 @defun where-is-internal command &optional keymap firstonly noindirect
1442 This function is a subroutine used by the @code{where-is} command
1443 (@pxref{Help, , Help, emacs,The GNU Emacs Manual}).  It returns a list
1444 of key sequences (of any length) that are bound to @var{command} in a
1445 set of keymaps.
1447 The argument @var{command} can be any object; it is compared with all
1448 keymap entries using @code{eq}.
1450 If @var{keymap} is @code{nil}, then the maps used are the current active
1451 keymaps, disregarding @code{overriding-local-map} (that is, pretending
1452 its value is @code{nil}).  If @var{keymap} is non-@code{nil}, then the
1453 maps searched are @var{keymap} and the global keymap.
1455 Usually it's best to use @code{overriding-local-map} as the expression
1456 for @var{keymap}.  Then @code{where-is-internal} searches precisely the
1457 keymaps that are active.  To search only the global map, pass
1458 @code{(keymap)} (an empty keymap) as @var{keymap}.
1460 If @var{firstonly} is @code{non-ascii}, then the value is a single
1461 string representing the first key sequence found, rather than a list of
1462 all possible key sequences.  If @var{firstonly} is @code{t}, then the
1463 value is the first key sequence, except that key sequences consisting
1464 entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
1465 characters) are preferred to all other key sequences.
1467 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1468 follow indirect keymap bindings.  This makes it possible to search for
1469 an indirect definition itself.
1471 @smallexample
1472 @group
1473 (where-is-internal 'describe-function)
1474     @result{} ("\^hf" "\^hd")
1475 @end group
1476 @end smallexample
1477 @end defun
1479 @deffn Command describe-bindings &optional prefix
1480 This function creates a listing of all current key bindings, and
1481 displays it in a buffer named @samp{*Help*}.  The text is grouped by
1482 modes---minor modes first, then the major mode, then global bindings.
1484 If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
1485 listing includes only keys that start with @var{prefix}.
1487 The listing describes meta characters as @key{ESC} followed by the
1488 corresponding non-meta character.
1490 When several characters with consecutive @sc{ascii} codes have the
1491 same definition, they are shown together, as
1492 @samp{@var{firstchar}..@var{lastchar}}.  In this instance, you need to
1493 know the @sc{ascii} codes to understand which characters this means.
1494 For example, in the default global map, the characters @samp{@key{SPC}
1495 ..@: ~} are described by a single line.  @key{SPC} is @sc{ascii} 32,
1496 @kbd{~} is @sc{ascii} 126, and the characters between them include all
1497 the normal printing characters, (e.g., letters, digits, punctuation,
1498 etc.@:); all these characters are bound to @code{self-insert-command}.
1499 @end deffn
1501 @node Menu Keymaps
1502 @section Menu Keymaps
1503 @cindex menu keymaps
1505 @c Emacs 19 feature
1506 A keymap can define a menu as well as bindings for keyboard keys and
1507 mouse button.  Menus are usually actuated with the mouse, but they can
1508 work with the keyboard also.
1510 @menu
1511 * Defining Menus::              How to make a keymap that defines a menu.
1512 * Mouse Menus::                 How users actuate the menu with the mouse.
1513 * Keyboard Menus::              How they actuate it with the keyboard.
1514 * Menu Example::                Making a simple menu.
1515 * Menu Bar::                    How to customize the menu bar.
1516 * Tool Bar::                    A tool bar is a row of images.
1517 * Modifying Menus::             How to add new items to a menu.
1518 @end menu
1520 @node Defining Menus
1521 @subsection Defining Menus
1522 @cindex defining menus
1523 @cindex menu prompt string
1524 @cindex prompt string (of menu)
1526 A keymap is suitable for menu use if it has an @dfn{overall prompt
1527 string}, which is a string that appears as an element of the keymap.
1528 (@xref{Format of Keymaps}.)  The string should describe the purpose of
1529 the menu's commands.  Emacs displays the overall prompt string as the
1530 menu title in some cases, depending on which toolkit is used for
1531 displaying menus.  Keyboard menus also display the overall prompt
1532 string.
1534 The easiest way to construct a keymap with a prompt string is to specify
1535 the string as an argument when you call @code{make-keymap} or
1536 @code{make-sparse-keymap} (@pxref{Creating Keymaps}).
1538 The order of items in the menu is the same as the order of bindings in
1539 the keymap.  Since @code{define-key} puts new bindings at the front, you
1540 should define the menu items starting at the bottom of the menu and
1541 moving to the top, if you care about the order.  When you add an item to
1542 an existing menu, you can specify its position in the menu using
1543 @code{define-key-after} (@pxref{Modifying Menus}).
1545 @menu
1546 * Simple Menu Items::       A simple kind of menu key binding,
1547                               limited in capabilities.
1548 * Extended Menu Items::     More powerful menu item definitions
1549                               let you specify keywords to enable
1550                               various features.
1551 * Menu Separators::         Drawing a horizontal line through a menu.
1552 * Alias Menu Items::        Using command aliases in menu items.
1553 @end menu
1555 @node Simple Menu Items
1556 @subsubsection Simple Menu Items
1558   The simpler and older way to define a menu keymap binding
1559 looks like this:
1561 @example
1562 (@var{item-string} . @var{real-binding})
1563 @end example
1565 @noindent
1566 The @sc{car}, @var{item-string}, is the string to be displayed in the
1567 menu.  It should be short---preferably one to three words.  It should
1568 describe the action of the command it corresponds to.
1570 You can also supply a second string, called the help string, as follows:
1572 @example
1573 (@var{item-string} @var{help-string} . @var{real-binding})
1574 @end example
1576 Currently Emacs does not actually use @var{help-string}; it knows only
1577 how to ignore @var{help-string} in order to extract @var{real-binding}.
1578 In the future we may use @var{help-string} as extended documentation for
1579 the menu item, available on request.
1581 As far as @code{define-key} is concerned, @var{item-string} and
1582 @var{help-string} are part of the event's binding.  However,
1583 @code{lookup-key} returns just @var{real-binding}, and only
1584 @var{real-binding} is used for executing the key.
1586 If @var{real-binding} is @code{nil}, then @var{item-string} appears in
1587 the menu but cannot be selected.
1589 If @var{real-binding} is a symbol and has a non-@code{nil}
1590 @code{menu-enable} property, that property is an expression that
1591 controls whether the menu item is enabled.  Every time the keymap is
1592 used to display a menu, Emacs evaluates the expression, and it enables
1593 the menu item only if the expression's value is non-@code{nil}.  When a
1594 menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
1595 cannot be selected.
1597 The menu bar does not recalculate which items are enabled every time you
1598 look at a menu.  This is because the X toolkit requires the whole tree
1599 of menus in advance.  To force recalculation of the menu bar, call
1600 @code{force-mode-line-update} (@pxref{Mode Line Format}).
1602 You've probably noticed that menu items show the equivalent keyboard key
1603 sequence (if any) to invoke the same command.  To save time on
1604 recalculation, menu display caches this information in a sublist in the
1605 binding, like this:
1607 @c This line is not too long--rms.
1608 @example
1609 (@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
1610 @end example
1612 @noindent
1613 Don't put these sublists in the menu item yourself; menu display
1614 calculates them automatically.  Don't mention keyboard equivalents in
1615 the item strings themselves, since that is redundant.
1617 @node Extended Menu Items
1618 @subsubsection Extended Menu Items
1619 @kindex menu-item
1621   An extended-format menu item is a more flexible and also cleaner
1622 alternative to the simple format.  It consists of a list that starts
1623 with the symbol @code{menu-item}.  To define a non-selectable string,
1624 the item looks like this:
1626 @example
1627 (menu-item @var{item-name})
1628 @end example
1630 @noindent
1631 A string starting with two or more dashes specifies a separator line;
1632 see @ref{Menu Separators}.
1634   To define a real menu item which can be selected, the extended format
1635 item looks like this:
1637 @example
1638 (menu-item @var{item-name} @var{real-binding}
1639     . @var{item-property-list})
1640 @end example
1642 @noindent
1643 Here, @var{item-name} is an expression which evaluates to the menu item
1644 string.  Thus, the string need not be a constant.  The third element,
1645 @var{real-binding}, is the command to execute.  The tail of the list,
1646 @var{item-property-list}, has the form of a property list which contains
1647 other information.  Here is a table of the properties that are supported:
1649 @table @code
1650 @item :enable @var{form}
1651 The result of evaluating @var{form} determines whether the item is
1652 enabled (non-@code{nil} means yes).  If the item is not enabled,
1653 you can't really click on it.
1655 @item :visible @var{form}
1656 The result of evaluating @var{form} determines whether the item should
1657 actually appear in the menu (non-@code{nil} means yes).  If the item
1658 does not appear, then the menu is displayed as if this item were
1659 not defined at all.
1661 @item :help @var{help}
1662 The value of this property, @var{help}, is the extra help string (not
1663 currently used by Emacs).
1665 @item :button (@var{type} . @var{selected})
1666 This property provides a way to define radio buttons and toggle buttons.
1667 The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
1668 @code{:radio}.  The @sc{cdr}, @var{selected}, should be a form; the
1669 result of evaluating it says whether this button is currently selected.
1671 A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
1672 according to the value of @var{selected}.  The command itself should
1673 toggle @var{selected}, setting it to @code{t} if it is @code{nil},
1674 and to @code{nil} if it is @code{t}.  Here is how the menu item
1675 to toggle the @code{debug-on-error} flag is defined:
1677 @example
1678 (menu-item "Debug on Error" toggle-debug-on-error
1679            :button (:toggle
1680                     . (and (boundp 'debug-on-error)
1681                            debug-on-error)))
1682 @end example
1684 @noindent
1685 This works because @code{toggle-debug-on-error} is defined as a command
1686 which toggles the variable @code{debug-on-error}.
1688 @dfn{Radio buttons} are a group of menu items, in which at any time one
1689 and only one is ``selected.''  There should be a variable whose value
1690 says which one is selected at any time.  The @var{selected} form for
1691 each radio button in the group should check whether the variable has the
1692 right value for selecting that button.  Clicking on the button should
1693 set the variable so that the button you clicked on becomes selected.
1695 @item :key-sequence @var{key-sequence}
1696 This property specifies which key sequence is likely to be bound to the
1697 same command invoked by this menu item.  If you specify the right key
1698 sequence, that makes preparing the menu for display run much faster.
1700 If you specify the wrong key sequence, it has no effect; before Emacs
1701 displays @var{key-sequence} in the menu, it verifies that
1702 @var{key-sequence} is really equivalent to this menu item.
1704 @item :key-sequence nil
1705 This property indicates that there is normally no key binding which is
1706 equivalent to this menu item.  Using this property saves time in
1707 preparing the menu for display, because Emacs does not need to search
1708 the keymaps for a keyboard equivalent for this menu item.
1710 However, if the user has rebound this item's definition to a key
1711 sequence, Emacs ignores the @code{:keys} property and finds the keyboard
1712 equivalent anyway.
1714 @item :keys @var{string}
1715 This property specifies that @var{string} is the string to display
1716 as the keyboard equivalent for this menu item.  You can use
1717 the @samp{\\[...]} documentation construct in @var{string}.
1719 @item :filter @var{filter-fn}
1720 This property provides a way to compute the menu item dynamically.
1721 The property value @var{filter-fn} should be a function of one argument;
1722 when it is called, its argument will be @var{real-binding}.  The
1723 function should return the binding to use instead.
1724 @end table
1726 @node Menu Separators
1727 @subsubsection Menu Separators
1728 @cindex menu separators
1730   A menu separator is a kind of menu item that doesn't display any
1731 text--instead, it divides the menu into subparts with a horizontal line.
1732 A separator looks like this in the menu keymap:
1734 @example
1735 (menu-item @var{separator-type})
1736 @end example
1738 @noindent
1739 where @var{separator-type} is a string starting with two or more dashes.
1741   In the simplest case, @var{separator-type} consists of only dashes.
1742 That specifies the default kind of separator.  (For compatibility,
1743 @code{""} and @code{-} also count as separators.)
1745   Starting in Emacs 21, certain other values of @var{separator-type}
1746 specify a different style of separator.  Here is a table of them:
1748 @table @code
1749 @item "--no-line"
1750 @itemx "--space"
1751 An extra vertical space, with no actual line.
1753 @item "--single-line"
1754 A single line in the menu's foreground color.
1756 @item "--double-line"
1757 A double line in the menu's foreground color.
1759 @item "--single-dashed-line"
1760 A single dashed line in the menu's foreground color.
1762 @item "--double-dashed-line"
1763 A double dashed line in the menu's foreground color.
1765 @item "--shadow-etched-in"
1766 A single line with a 3D sunken appearance.  This is the default,
1767 used separators consisting of dashes only.
1769 @item "--shadow-etched-out"
1770 A single line with a 3D raised appearance.
1772 @item "--shadow-etched-in-dash"
1773 A single dashed line with a 3D sunken appearance.
1775 @item "--shadow-etched-out-dash"
1776 A single dashed line with a 3D raised appearance.
1778 @item "--shadow-double-etched-in"
1779 Two lines with a 3D sunken appearance.
1781 @item "--shadow-double-etched-out"
1782 Two lines with a 3D raised appearance.
1784 @item "--shadow-double-etched-in-dash"
1785 Two dashed lines with a 3D sunken appearance.
1787 @item "--shadow-double-etched-out-dash"
1788 Two dashed lines with a 3D raised appearance.
1789 @end table
1791   You can also give these names in another style, adding a colon after
1792 the double-dash and replacing each single dash with capitalization of
1793 the following word.  Thus, @code{"--:singleLine"}, is equivalent to
1794 @code{"--single-line"}.
1796   Some systems and display toolkits don't really handle all of these
1797 separator types.  If you use a type that isn't supported, the menu
1798 displays a similar kind of separator that is supported.
1800 @node Alias Menu Items
1801 @subsubsection Alias Menu Items
1803   Sometimes it is useful to make menu items that use the ``same''
1804 command but with different enable conditions.  The best way to do this
1805 in Emacs now is with extended menu items; before that feature existed,
1806 it could be done by defining alias commands and using them in menu
1807 items.  Here's an example that makes two aliases for
1808 @code{toggle-read-only} and gives them different enable conditions:
1810 @example
1811 (defalias 'make-read-only 'toggle-read-only)
1812 (put 'make-read-only 'menu-enable '(not buffer-read-only))
1813 (defalias 'make-writable 'toggle-read-only)
1814 (put 'make-writable 'menu-enable 'buffer-read-only)
1815 @end example
1817 When using aliases in menus, often it is useful to display the
1818 equivalent key bindings for the ``real'' command name, not the aliases
1819 (which typically don't have any key bindings except for the menu
1820 itself).  To request this, give the alias symbol a non-@code{nil}
1821 @code{menu-alias} property.  Thus,
1823 @example
1824 (put 'make-read-only 'menu-alias t)
1825 (put 'make-writable 'menu-alias t)
1826 @end example
1828 @noindent
1829 causes menu items for @code{make-read-only} and @code{make-writable} to
1830 show the keyboard bindings for @code{toggle-read-only}.
1832 @node Mouse Menus
1833 @subsection Menus and the Mouse
1835   The usual way to make a menu keymap produce a menu is to make it the
1836 definition of a prefix key.  (A Lisp program can explicitly pop up a
1837 menu and receive the user's choice---see @ref{Pop-Up Menus}.)
1839   If the prefix key ends with a mouse event, Emacs handles the menu keymap
1840 by popping up a visible menu, so that the user can select a choice with
1841 the mouse.  When the user clicks on a menu item, the event generated is
1842 whatever character or symbol has the binding that brought about that
1843 menu item.  (A menu item may generate a series of events if the menu has
1844 multiple levels or comes from the menu bar.)
1846   It's often best to use a button-down event to trigger the menu.  Then
1847 the user can select a menu item by releasing the button.
1849   A single keymap can appear as multiple menu panes, if you explicitly
1850 arrange for this.  The way to do this is to make a keymap for each pane,
1851 then create a binding for each of those maps in the main keymap of the
1852 menu.  Give each of these bindings an item string that starts with
1853 @samp{@@}.  The rest of the item string becomes the name of the pane.
1854 See the file @file{lisp/mouse.el} for an example of this.  Any ordinary
1855 bindings with @samp{@@}-less item strings are grouped into one pane,
1856 which appears along with the other panes explicitly created for the
1857 submaps.
1859   X toolkit menus don't have panes; instead, they can have submenus.
1860 Every nested keymap becomes a submenu, whether the item string starts
1861 with @samp{@@} or not.  In a toolkit version of Emacs, the only thing
1862 special about @samp{@@} at the beginning of an item string is that the
1863 @samp{@@} doesn't appear in the menu item.
1865   You can also produce multiple panes or submenus from separate keymaps.
1866 The full definition of a prefix key always comes from merging the
1867 definitions supplied by the various active keymaps (minor mode, local,
1868 and global).  When more than one of these keymaps is a menu, each of
1869 them makes a separate pane or panes (when Emacs does not use an
1870 X-toolkit) or a separate submenu (when using an X-toolkit).
1871 @xref{Active Keymaps}.
1873 @node Keyboard Menus
1874 @subsection Menus and the Keyboard
1876 When a prefix key ending with a keyboard event (a character or function
1877 key) has a definition that is a menu keymap, the user can use the
1878 keyboard to choose a menu item.
1880 Emacs displays the menu's overall prompt string followed by the
1881 alternatives (the item strings of the bindings) in the echo area.  If
1882 the bindings don't all fit at once, the user can type @key{SPC} to see
1883 the next line of alternatives.  Successive uses of @key{SPC} eventually
1884 get to the end of the menu and then cycle around to the beginning.  (The
1885 variable @code{menu-prompt-more-char} specifies which character is used
1886 for this; @key{SPC} is the default.)
1888 When the user has found the desired alternative from the menu, he or she
1889 should type the corresponding character---the one whose binding is that
1890 alternative.
1892 @ignore
1893 In a menu intended for keyboard use, each menu item must clearly
1894 indicate what character to type.  The best convention to use is to make
1895 the character the first letter of the item string---that is something
1896 users will understand without being told.  We plan to change this; by
1897 the time you read this manual, keyboard menus may explicitly name the
1898 key for each alternative.
1899 @end ignore
1901 This way of using menus in an Emacs-like editor was inspired by the
1902 Hierarkey system.
1904 @defvar menu-prompt-more-char
1905 This variable specifies the character to use to ask to see
1906 the next line of a menu.  Its initial value is 32, the code
1907 for @key{SPC}.
1908 @end defvar
1910 @node Menu Example
1911 @subsection Menu Example
1912 @cindex menu definition example
1914   Here is a complete example of defining a menu keymap.  It is the
1915 definition of the @samp{Print} submenu in the @samp{Tools} menu in the
1916 menu bar, and it uses the simple menu item format (@pxref{Simple Menu
1917 Items}).  First we create the keymap, and give it a name:
1919 @example
1920 (defvar menu-bar-print-menu (make-sparse-keymap "Print"))
1921 @end example
1923 @noindent
1924 Next we define the menu items:
1926 @example
1927 (define-key menu-bar-print-menu [ps-print-region]
1928   '("Postscript Print Region" . ps-print-region-with-faces))
1929 (define-key menu-bar-print-menu [ps-print-buffer]
1930   '("Postscript Print Buffer" . ps-print-buffer-with-faces))
1931 (define-key menu-bar-print-menu [separator-ps-print]
1932   '("--"))
1933 (define-key menu-bar-print-menu [print-region]
1934   '("Print Region" . print-region))
1935 (define-key menu-bar-print-menu [print-buffer]
1936   '("Print Buffer" . print-buffer))
1937 @end example
1939 @noindent
1940 Note the symbols which the bindings are ``made for''; these appear
1941 inside square brackets, in the key sequence being defined.  In some
1942 cases, this symbol is the same as the command name; sometimes it is
1943 different.  These symbols are treated as ``function keys'', but they are
1944 not real function keys on the keyboard.  They do not affect the
1945 functioning of the menu itself, but they are ``echoed'' in the echo area
1946 when the user selects from the menu, and they appear in the output of
1947 @code{where-is} and @code{apropos}.
1949   The binding whose definition is @code{("--")} is a separator line.
1950 Like a real menu item, the separator has a key symbol, in this case
1951 @code{separator-ps-print}.  If one menu has two separators, they must
1952 have two different key symbols.
1954   Here is code to define enable conditions for two of the commands in
1955 the menu:
1957 @example
1958 (put 'print-region 'menu-enable 'mark-active)
1959 (put 'ps-print-region-with-faces 'menu-enable 'mark-active)
1960 @end example
1962   Here is how we make this menu appear as an item in the parent menu:
1964 @example
1965 (define-key menu-bar-tools-menu [print]
1966   (cons "Print" menu-bar-print-menu))
1967 @end example
1969 @noindent
1970 Note that this incorporates the submenu keymap, which is the value of
1971 the variable @code{menu-bar-print-menu}, rather than the symbol
1972 @code{menu-bar-print-menu} itself.  Using that symbol in the parent menu
1973 item would be meaningless because @code{menu-bar-print-menu} is not a
1974 command.
1976   If you wanted to attach the same print menu to a mouse click, you
1977 can do it this way:
1979 @example
1980 (define-key global-map [C-S-down-mouse-1]
1981    menu-bar-print-menu)
1982 @end example
1984   We could equally well use an extended menu item (@pxref{Extended Menu
1985 Items}) for @code{print-region}, like this:
1987 @example
1988 (define-key menu-bar-print-menu [print-region]
1989   '(menu-item "Print Region" print-region
1990               :enable mark-active))
1991 @end example
1993 @noindent
1994 With the extended menu item, the enable condition is specified
1995 inside the menu item itself.  If we wanted to make this
1996 item disappear from the menu entirely when the mark is inactive,
1997 we could do it this way:
1999 @example
2000 (define-key menu-bar-print-menu [print-region]
2001   '(menu-item "Print Region" print-region
2002               :visible mark-active))
2003 @end example
2005 @node Menu Bar
2006 @subsection The Menu Bar
2007 @cindex menu bar
2009   Most window systems allow each frame to have a @dfn{menu bar}---a
2010 permanently displayed menu stretching horizontally across the top of the
2011 frame.  The items of the menu bar are the subcommands of the fake
2012 ``function key'' @code{menu-bar}, as defined by all the active keymaps.
2014   To add an item to the menu bar, invent a fake ``function key'' of your
2015 own (let's call it @var{key}), and make a binding for the key sequence
2016 @code{[menu-bar @var{key}]}.  Most often, the binding is a menu keymap,
2017 so that pressing a button on the menu bar item leads to another menu.
2019   When more than one active keymap defines the same fake function key
2020 for the menu bar, the item appears just once.  If the user clicks on
2021 that menu bar item, it brings up a single, combined menu containing
2022 all the subcommands of that item---the global subcommands, the local
2023 subcommands, and the minor mode subcommands.
2025   The variable @code{overriding-local-map} is normally ignored when
2026 determining the menu bar contents.  That is, the menu bar is computed
2027 from the keymaps that would be active if @code{overriding-local-map}
2028 were @code{nil}.  @xref{Active Keymaps}.
2030   In order for a frame to display a menu bar, its @code{menu-bar-lines}
2031 parameter must be greater than zero.  Emacs uses just one line for the
2032 menu bar itself; if you specify more than one line, the other lines
2033 serve to separate the menu bar from the windows in the frame.  We
2034 recommend 1 or 2 as the value of @code{menu-bar-lines}.  @xref{Window Frame
2035 Parameters}.
2037   Here's an example of setting up a menu bar item:
2039 @example
2040 @group
2041 (modify-frame-parameters (selected-frame)
2042                          '((menu-bar-lines . 2)))
2043 @end group
2045 @group
2046 ;; @r{Make a menu keymap (with a prompt string)}
2047 ;; @r{and make it the menu bar item's definition.}
2048 (define-key global-map [menu-bar words]
2049   (cons "Words" (make-sparse-keymap "Words")))
2050 @end group
2052 @group
2053 ;; @r{Define specific subcommands in this menu.}
2054 (define-key global-map
2055   [menu-bar words forward]
2056   '("Forward word" . forward-word))
2057 @end group
2058 @group
2059 (define-key global-map
2060   [menu-bar words backward]
2061   '("Backward word" . backward-word))
2062 @end group
2063 @end example
2065   A local keymap can cancel a menu bar item made by the global keymap by
2066 rebinding the same fake function key with @code{undefined} as the
2067 binding.  For example, this is how Dired suppresses the @samp{Edit} menu
2068 bar item:
2070 @example
2071 (define-key dired-mode-map [menu-bar edit] 'undefined)
2072 @end example
2074 @noindent
2075 @code{edit} is the fake function key used by the global map for the
2076 @samp{Edit} menu bar item.  The main reason to suppress a global
2077 menu bar item is to regain space for mode-specific items.
2079 @defvar menu-bar-final-items
2080 Normally the menu bar shows global items followed by items defined by the
2081 local maps.
2083 This variable holds a list of fake function keys for items to display at
2084 the end of the menu bar rather than in normal sequence.  The default
2085 value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
2086 at the end of the menu bar, following local menu items.
2087 @end defvar
2089 @defvar menu-bar-update-hook
2090 This normal hook is run whenever the user clicks on the menu bar, before
2091 displaying a submenu.  You can use it to update submenus whose contents
2092 should vary.
2093 @end defvar
2095 @node Tool Bar
2096 @subsection Tool bars
2097 @cindex tool bar
2099   A @dfn{tool bar} is a row of icons at the top of a frame, that execute
2100 commands when you click on them---in effect, a kind of graphical menu
2101 bar.  Emacs supports tool bars starting with version 21.
2103   The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
2104 controls how many lines' worth of height to reserve for the tool bar.  A
2105 zero value suppresses the tool bar.  If the value is nonzero, and
2106 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
2107 contracts automatically as needed to hold the specified contents.
2109   The tool bar contents are controlled by a menu keymap attached to a
2110 fake ``function key'' called @code{tool-bar} (much like the way the menu
2111 bar is controlled).  So you define a tool bar item using
2112 @code{define-key}, like this:
2114 @example
2115 (define-key global-map [tool-bar @var{key}] @var{item})
2116 @end example
2118 @noindent
2119 where @var{key} is a fake ``function key'' to distinguish this item from
2120 other items, and @var{item} is a menu item key binding (@pxref{Extended
2121 Menu Items}), which says how to display this item and how it behaves.
2123   The usual menu keymap item properties, @code{:visible},
2124 @code{:enable}, @code{:button}, and @code{:filter}, are useful in
2125 tool bar bindings and have their normal meanings.  The @var{real-binding}
2126 in the item must be a command, not a keymap; in other words, it does not
2127 work to define a tool bar icon as a prefix key.
2129   The @code{:help} property is meaningful, and specifies a ``help-echo''
2130 string to display while the mouse is on that item.
2132   In addition, you should use the @code{:image} property;
2133 this is how you specify the image to display in the tool bar:
2135 @table @code
2136 @item :image @var{image}
2137 @var{images} is either a single image specification or a vector of four
2138 image specifications.  If you use a vector of four,
2139 one of them is used, depending on circumstances:
2141 @table @asis
2142 @item item 0
2143 Used when the item is enabled and selected.
2144 @item item 1
2145 Used when the item is enabled and deselected.
2146 @item item 2
2147 Used when the item is disabled and selected.
2148 @item item 3
2149 Used when the item is disabled and deselected.
2150 @end table
2151 @end table
2153 If @var{image} is a single image specification, Emacs draws the tool bar
2154 button in disabled state by applying an edge-detection algorithm to the
2155 image.
2157 @tindex auto-resize-tool-bar
2158 @defvar auto-resize-tool-bar
2159 If this variable is non-@code{nil}, the tool bar automatically resizes to
2160 show all defined tool bar items---but not larger than a quarter of the
2161 frame's height.
2162 @end defvar
2164 @tindex auto-raise-tool-bar-items
2165 @defvar auto-raise-tool-bar-items
2166 If this variable is non-@code{nil}, tool bar items display
2167 in raised form when the mouse moves over them.
2168 @end defvar
2170 @tindex tool-bar-item-margin
2171 @defvar tool-bar-item-margin
2172 This variable specifies an extra margin to add around tool bar items.
2173 The value is an integer, a number of pixels.  The default is 1.
2174 @end defvar
2176 @tindex tool-bar-item-relief
2177 @defvar tool-bar-item-relief
2178 This variable specifies the shadow width for tool bar items.
2179 The value is an integer, a number of pixels.  The default is 3.
2180 @end defvar
2182   You can define a special meaning for clicking on a tool bar item with
2183 the shift, control, meta, etc., modifiers.  You do this by setting up
2184 additional items that relate to the original item through the fake
2185 function keys.  Specifically, the additional items should use the
2186 modified versions of the same fake function key used to name the
2187 original item.
2189   Thus, if the original item was defined this way,
2191 @example
2192 (define-key global-map [tool-bar shell]
2193   '(menu-item "Shell" shell
2194               :image (image :type xpm :file "shell.xpm")))
2195 @end example
2197 @noindent
2198 then here is how you can define clicking on the same tool bar image with
2199 the shift modifier:
2201 @example
2202 (define-key global-map [tool-bar S-shell] 'some-command)
2203 @end example
2205 @xref{Function Keys}, for more information about how to add modifiers to
2206 function keys.
2208 @node Modifying Menus
2209 @subsection Modifying Menus
2211   When you insert a new item in an existing menu, you probably want to
2212 put it in a particular place among the menu's existing items.  If you
2213 use @code{define-key} to add the item, it normally goes at the front of
2214 the menu.  To put it elsewhere in the menu, use @code{define-key-after}:
2216 @defun define-key-after map key binding &optional after
2217 Define a binding in @var{map} for @var{key}, with value @var{binding},
2218 just like @code{define-key}, but position the binding in @var{map} after
2219 the binding for the event @var{after}.  The argument @var{key} should be
2220 of length one---a vector or string with just one element.  But
2221 @var{after} should be a single event type---a symbol or a character, not
2222 a sequence.  The new binding goes after the binding for @var{after}.  If
2223 @var{after} is @code{t} or is omitted, then the new binding goes last, at
2224 the end of the keymap.  However, new bindings are added before any
2225 inherited keymap.
2227 Here is an example:
2229 @example
2230 (define-key-after my-menu [drink]
2231   '("Drink" . drink-command) 'eat)
2232 @end example
2234 @noindent
2235 makes a binding for the fake function key @key{DRINK} and puts it
2236 right after the binding for @key{EAT}.
2238 Here is how to insert an item called @samp{Work} in the @samp{Signals}
2239 menu of Shell mode, after the item @code{break}:
2241 @example
2242 (define-key-after
2243   (lookup-key shell-mode-map [menu-bar signals])
2244   [work] '("Work" . work-command) 'break)
2245 @end example
2246 @end defun