2 @c This is part of the SXEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c Copyright (C) 1996 Ben Wing.
5 @c Copyright (C) 2005 Sebastian Freundt <hroptatyr@sxemacs.org>
6 @c See the file lispref.texi for copying conditions.
7 @setfilename ../../info/keymaps.info
9 @node Keymaps, Menus, Command Loop, Top
13 @c This section is largely different from the one in FSF Emacs.
15 The bindings between input events and commands are recorded in data
16 structures called @dfn{keymaps}. Each binding in a keymap associates
17 (or @dfn{binds}) an individual event type either with another keymap or
18 with a command. When an event is bound to a keymap, that keymap is
19 used to look up the next input event; this continues until a command
20 is found. The whole process is called @dfn{key lookup}.
23 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
24 * Format of Keymaps:: What a keymap looks like as a Lisp object.
25 * Creating Keymaps:: Functions to create and copy keymaps.
26 * Inheritance and Keymaps:: How one keymap can inherit the bindings
28 * Key Sequences:: How to specify key sequences.
29 * Prefix Keys:: Defining a key with a keymap as its definition.
30 * Active Keymaps:: Each buffer has a local keymap
31 to override the standard (global) bindings.
32 A minor mode can also override them.
33 * Key Lookup:: How extracting elements from keymaps works.
34 * Functions for Key Lookup:: How to request key lookup.
35 * Changing Key Bindings:: Redefining a key in a keymap.
36 * Key Binding Commands:: Interactive interfaces for redefining keys.
37 * Scanning Keymaps:: Looking through all keymaps, for printing help.
38 * Other Keymap Functions:: Miscellaneous keymap functions.
42 @node Keymap Terminology
43 @section Keymap Terminology
47 @cindex binding of a key
51 A @dfn{keymap} is a table mapping event types to definitions (which
52 can be any Lisp objects, though only certain types are meaningful for
53 execution by the command loop). Given an event (or an event type) and a
54 keymap, SXEmacs can get the event's definition. Events mapped in keymaps
55 include keypresses, button presses, and button releases
58 A sequence of input events that form a unit is called a
59 @dfn{key sequence}, or @dfn{key} for short. A sequence of one event
60 is always a key sequence, and so are some multi-event sequences.
62 A keymap determines a binding or definition for any key sequence. If
63 the key sequence is a single event, its binding is the definition of the
64 event in the keymap. The binding of a key sequence of more than one
65 event is found by an iterative process: the binding of the first event
66 is found, and must be a keymap; then the second event's binding is found
67 in that keymap, and so on until all the events in the key sequence are
70 If the binding of a key sequence is a keymap, we call the key sequence
71 a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
72 no more events can be added to it). If the binding is @code{nil},
73 we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
74 @kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
75 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
76 keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more
79 The rule for finding the binding of a key sequence assumes that the
80 intermediate bindings (found for the events before the last) are all
81 keymaps; if this is not so, the sequence of events does not form a
82 unit---it is not really a key sequence. In other words, removing one or
83 more events from the end of any valid key must always yield a prefix
84 key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
85 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
87 Note that the set of possible multi-event key sequences depends on the
88 bindings for prefix keys; therefore, it can be different for different
89 keymaps, and can change when bindings are changed. However, a one-event
90 sequence is always a key sequence, because it does not depend on any
91 prefix keys for its well-formedness.
93 At any time, several primary keymaps are @dfn{active}---that is, in
94 use for finding key bindings. These are the @dfn{global map}, which is
95 shared by all buffers; the @dfn{local keymap}, which is usually
96 associated with a specific major mode; and zero or more @dfn{minor mode
97 keymaps}, which belong to currently enabled minor modes. (Not all minor
98 modes have keymaps.) The local keymap bindings shadow (i.e., take
99 precedence over) the corresponding global bindings. The minor mode
100 keymaps shadow both local and global keymaps. @xref{Active Keymaps},
104 @node Format of Keymaps
105 @section Format of Keymaps
106 @cindex format of keymaps
107 @cindex keymap format
109 A keymap is a primitive type that associates events with their
110 bindings. Note that this is different from Emacs 18 and FSF Emacs,
111 where keymaps are lists.
113 @defun keymapp object
114 This function returns @code{t} if @var{object} is a keymap, @code{nil}
119 @node Creating Keymaps
120 @section Creating Keymaps
121 @cindex creating keymaps
123 Here we describe the functions for creating keymaps.
125 @defun make-keymap &optional name
126 This function constructs and returns a new keymap object. All entries
127 in it are @code{nil}, meaning ``command undefined''.
129 Optional argument @var{name} specifies a name to assign to the keymap,
130 as in @code{set-keymap-name}. This name is only a debugging
131 convenience; it is not used except when printing the keymap.
134 @defun make-sparse-keymap &optional name
135 This function constructs and returns a new keymap object. All entries
136 in it are @code{nil}, meaning ``command undefined''. The only
137 difference between this function and @code{make-keymap} is that this
138 function returns a ``smaller'' keymap (one that is expected to contain
139 fewer entries). As keymaps dynamically resize, this distinction is not
142 Optional argument @var{name} specifies a name to assign to the keymap,
143 as in @code{set-keymap-name}. This name is only a debugging
144 convenience; it is not used except when printing the keymap.
147 @defun set-keymap-name keymap new-name
148 This function assigns a ``name'' to a keymap. The name is only a
149 debugging convenience; it is not used except when printing the keymap.
152 @defun keymap-name keymap
153 This function returns the ``name'' of a keymap, as assigned using
154 @code{set-keymap-name}.
157 @defun copy-keymap keymap
158 This function returns a copy of @var{keymap}. Any keymaps that
159 appear directly as bindings in @var{keymap} are also copied recursively,
160 and so on to any number of levels. However, recursive copying does not
161 take place when the definition of a character is a symbol whose function
162 definition is a keymap; the same symbol appears in the new copy.
166 (setq map (copy-keymap (current-local-map)))
167 @result{} #<keymap 3 entries 0x21f80>
171 (eq map (current-local-map))
174 @ignore @c Doesn't work!
176 (equal map (current-local-map))
184 @node Inheritance and Keymaps
185 @section Inheritance and Keymaps
186 @cindex keymap inheritance
187 @cindex inheriting a keymap's bindings
188 @cindex keymap parent
189 @cindex parent of a keymap
191 A keymap can inherit the bindings of other keymaps. The other
192 keymaps are called the keymap's @dfn{parents}, and are set with
193 @code{set-keymap-parents}. When searching for a binding for a key
194 sequence in a particular keymap, that keymap itself will first be
195 searched; then, if no binding was found in the map and it has parents,
196 the first parent keymap will be searched; then that keymap's parent will
197 be searched, and so on, until either a binding for the key sequence is
198 found, or a keymap without a parent is encountered. At this point,
199 the search will continue with the next parent of the most recently
200 encountered keymap that has another parent, etc. Essentially, a
201 depth-first search of all the ancestors of the keymap is conducted.
203 @code{(current-global-map)} is the default parent of all keymaps.
205 @defun set-keymap-parents keymap parents
206 This function sets the parent keymaps of @var{keymap} to the list
209 If you change the bindings in one of the keymaps in @var{parents} using
210 @code{define-key} or other key-binding functions, these changes are
211 visible in @var{keymap} unless shadowed by bindings in that map or in
212 earlier-searched ancestors. The converse is not true: if you use
213 @code{define-key} to change @var{keymap}, that affects the bindings in
214 that map, but has no effect on any of the keymaps in @var{parents}.
217 @defun keymap-parents keymap
218 This function returns the list of parent keymaps of @var{keymap}, or
219 @code{nil} if @var{keymap} has no parents.
222 As an alternative to specifying a parent, you can also specify a
223 @dfn{default binding} that is used whenever a key is not otherwise bound
224 in the keymap. This is useful for terminal emulators, for example,
225 which may want to trap all keystrokes and pass them on in some modified
226 format. Note that if you specify a default binding for a keymap,
227 neither the keymap's parents nor the current global map are searched for
230 @defun set-keymap-default-binding keymap command
231 This function sets the default binding of @var{keymap} to @var{command},
232 or @code{nil} if no default is desired.
235 @defun keymap-default-binding keymap
236 This function returns the default binding of @var{keymap}, or @code{nil}
242 @section Key Sequences
243 @cindex key sequences
245 Contrary to popular belief, the world is not @sc{ascii}. When running
246 under a window manager, SXEmacs can tell the difference between, for
247 example, the keystrokes @kbd{control-h}, @kbd{control-shift-h}, and
248 @kbd{backspace}. You can, in fact, bind different commands to each of
251 A @dfn{key sequence} is a set of keystrokes. A @dfn{keystroke} is a
252 keysym and some set of modifiers (such as @key{CONTROL} and @key{META}).
253 A @dfn{keysym} is what is printed on the keys on your keyboard.
255 A keysym may be represented by a symbol, or (if and only if it is
256 equivalent to an @sc{ascii} character in the range 32 - 255) by a
257 character or its equivalent @sc{ascii} code. The @kbd{A} key may be
258 represented by the symbol @code{A}, the character @code{?A}, or by the
259 number 65. The @kbd{break} key may be represented only by the symbol
262 A keystroke may be represented by a list: the last element of the list
263 is the key (a symbol, character, or number, as above) and the preceding
264 elements are the symbolic names of modifier keys (@key{CONTROL},
265 @key{META}, @key{SUPER}, @key{HYPER}, @key{ALT}, and @key{SHIFT}).
266 Thus, the sequence @kbd{control-b} is represented by the forms
267 @code{(control b)}, @code{(control ?b)}, and @code{(control 98)}. A
268 keystroke may also be represented by an event object, as returned by the
269 @code{next-command-event} and @code{read-key-sequence} functions.
271 Note that in this context, the keystroke @kbd{control-b} is @emph{not}
272 represented by the number 2 (the @sc{ascii} code for @samp{^B}) or the
273 character @code{?\^B}. See below.
275 The @key{SHIFT} modifier is somewhat of a special case. You should
276 not (and cannot) use @code{(meta shift a)} to mean @code{(meta A)},
277 since for characters that have @sc{ascii} equivalents, the state of the
278 shift key is implicit in the keysym (@samp{a} vs. @samp{A}). You also
279 cannot say @code{(shift =)} to mean @code{+}, as that sort of thing
280 varies from keyboard to keyboard. The @key{SHIFT} modifier is for use
281 only with characters that do not have a second keysym on the same key,
282 such as @code{backspace} and @code{tab}.
284 A key sequence is a vector of keystrokes. As a degenerate case,
285 elements of this vector may also be keysyms if they have no modifiers.
286 That is, the @kbd{A} keystroke is represented by all of these forms:
289 A ?A 65 (A) (?A) (65)
290 [A] [?A] [65] [(A)] [(?A)] [(65)]
293 the @kbd{control-a} keystroke is represented by these forms:
296 (control A) (control ?A) (control 65)
297 [(control A)] [(control ?A)] [(control 65)]
300 the key sequence @kbd{control-c control-a} is represented by these
304 [(control c) (control a)] [(control ?c) (control ?a)]
305 [(control 99) (control 65)] etc.
308 Mouse button clicks work just like keypresses: @code{(control
309 button1)} means pressing the left mouse button while holding down the
310 control key. @code{[(control c) (shift button3)]} means
311 @kbd{control-c}, hold @key{SHIFT}, click right.
313 Commands may be bound to the mouse-button up-stroke rather than the
314 down-stroke as well. @code{button1} means the down-stroke, and
315 @code{button1up} means the up-stroke. Different commands may be bound
316 to the up and down strokes, though that is probably not what you want,
319 For backward compatibility, a key sequence may also be represented by
320 a string. In this case, it represents the key sequence(s) that would
321 produce that sequence of @sc{ascii} characters in a purely @sc{ascii}
322 world. For example, a string containing the @sc{ascii} backspace
323 character, @code{"\^H"}, would represent two key sequences:
324 @code{(control h)} and @code{backspace}. Binding a command to this will
325 actually bind both of those key sequences. Likewise for the following
334 control @@ control space
337 After binding a command to two key sequences with a form like
340 (define-key global-map "\^X\^I" 'command-1)
344 it is possible to redefine only one of those sequences like so:
347 (define-key global-map [(control x) (control i)] 'command-2)
348 (define-key global-map [(control x) tab] 'command-3)
351 Of course, all of this applies only when running under a window
352 system. If you're talking to SXEmacs through a @sc{tty} connection, you
353 don't get any of these features.
355 @defun event-matches-key-specifier-p event key-specifier
356 This function returns non-@code{nil} if @var{event} matches
357 @var{key-specifier}, which can be any valid form representing a key
358 sequence. This can be useful, e.g., to determine if the user pressed
359 @code{help-char} or @code{quit-char}.
367 A @dfn{prefix key} has an associated keymap that defines what to do
368 with key sequences that start with the prefix key. For example,
369 @kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
370 the variable @code{ctl-x-map}. Here is a list of the standard prefix
371 keys of SXEmacs and their keymaps:
376 @code{help-map} is used for events that follow @kbd{C-h}.
380 @vindex mode-specific-map
381 @code{mode-specific-map} is for events that follow @kbd{C-c}. This
382 map is not actually mode specific; its name was chosen to be informative
383 for the user in @kbd{C-h b} (@code{display-bindings}), where it
384 describes the main use of the @kbd{C-c} prefix key.
389 @findex Control-X-prefix
390 @code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
391 map is also the function definition of @code{Control-X-prefix}.
396 @code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}.
402 @code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
409 The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
410 that have no special name.
415 @code{esc-map} is an evil hack that is present for compatibility
416 purposes with Emacs 18. Defining a key in @code{esc-map} is equivalent
417 to defining the same key in @code{global-map} but with the @key{META}
418 prefix added. You should @emph{not} use this in your code. (This map is
419 also the function definition of @code{ESC-prefix}.)
422 The binding of a prefix key is the keymap to use for looking up the
423 events that follow the prefix key. (It may instead be a symbol whose
424 function definition is a keymap. The effect is the same, but the symbol
425 serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is
426 the symbol @code{Control-X-prefix}, whose function definition is the
427 keymap for @kbd{C-x} commands. (The same keymap is also the value of
430 Prefix key definitions can appear in any active keymap. The
431 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
432 keys appear in the global map, so these prefix keys are always
433 available. Major and minor modes can redefine a key as a prefix by
434 putting a prefix key definition for it in the local map or the minor
435 mode's map. @xref{Active Keymaps}.
437 If a key is defined as a prefix in more than one active map, then its
438 various definitions are in effect merged: the commands defined in the
439 minor mode keymaps come first, followed by those in the local map's
440 prefix definition, and then by those from the global map.
442 In the following example, we make @kbd{C-p} a prefix key in the local
443 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
444 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
445 like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
450 (use-local-map (make-sparse-keymap))
454 (local-set-key "\C-p" ctl-x-map)
458 (key-binding "\C-p\C-f")
463 (key-binding "\C-p6")
468 @defun define-prefix-command symbol &optional mapvar
469 @cindex prefix command
470 This function defines @var{symbol} as a prefix command: it creates a
471 keymap and stores it as @var{symbol}'s function definition.
472 Storing the symbol as the binding of a key makes the key a prefix key
473 that has a name. If optional argument @var{mapvar} is not specified,
474 it also sets @var{symbol} as a variable, to have the keymap as its
475 value. (If @var{mapvar} is given and is not @code{t}, its value is
476 stored as the value of @var{symbol}.) The function returns @var{symbol}.
478 In Emacs version 18, only the function definition of @var{symbol} was
479 set, not the value as a variable.
484 @section Active Keymaps
485 @cindex active keymap
486 @cindex global keymap
489 SXEmacs normally contains many keymaps; at any given time, just a few of
490 them are @dfn{active} in that they participate in the interpretation
491 of user input. These are the global keymap, the current buffer's
492 local keymap, and the keymaps of any enabled minor modes.
494 The @dfn{global keymap} holds the bindings of keys that are defined
495 regardless of the current buffer, such as @kbd{C-f}. The variable
496 @code{global-map} holds this keymap, which is always active.
498 Each buffer may have another keymap, its @dfn{local keymap}, which may
499 contain new or overriding definitions for keys. The current buffer's
500 local keymap is always active except when @code{overriding-local-map} or
501 @code{overriding-terminal-local-map} overrides it. Extents and text
502 properties can specify an alternative local map for certain parts of the
503 buffer; see @ref{Extents and Events}.
505 Each minor mode may have a keymap; if it does, the keymap is active
506 when the minor mode is enabled.
508 The variable @code{overriding-local-map} and
509 @code{overriding-terminal-local-map}, if non-@code{nil}, specify other
510 local keymaps that override the buffer's local map and all the minor
513 All the active keymaps are used together to determine what command to
514 execute when a key is entered. SXEmacs searches these maps one by one, in
515 order of decreasing precedence, until it finds a binding in one of the maps.
519 For key-presses, the order of keymaps searched is:
523 the @code{keymap} property of any extent(s) or text properties at point;
525 any applicable minor-mode maps;
527 the current local map of the current buffer;
529 the current global map.
532 For mouse-clicks, the order of keymaps searched is:
536 the current local map of the @code{mouse-grabbed-buffer} if any;
538 the @code{keymap} property of any extent(s) at the position of the click
539 (this includes modeline extents);
541 the @code{modeline-map} of the buffer corresponding to the modeline
542 under the mouse (if the click happened over a modeline);
544 the value of @code{toolbar-map} in the current buffer (if the click
545 happened over a toolbar);
547 the current local map of the buffer under the mouse (does not
548 apply to toolbar clicks);
550 any applicable minor-mode maps;
552 the current global map.
555 Note that if @code{overriding-local-map} or
556 @code{overriding-terminal-local-map} is non-@code{nil}, @emph{only}
557 those two maps and the current global map are searched.
559 The procedure for searching a single keymap is called
560 @dfn{key lookup}; see @ref{Key Lookup}.
562 @cindex major mode keymap
563 Since every buffer that uses the same major mode normally uses the
564 same local keymap, you can think of the keymap as local to the mode. A
565 change to the local keymap of a buffer (using @code{local-set-key}, for
566 example) is seen also in the other buffers that share that keymap.
568 The local keymaps that are used for Lisp mode, C mode, and several
569 other major modes exist even if they have not yet been used. These
570 local maps are the values of the variables @code{lisp-mode-map},
571 @code{c-mode-map}, and so on. For most other modes, which are less
572 frequently used, the local keymap is constructed only when the mode is
573 used for the first time in a session.
575 The minibuffer has local keymaps, too; they contain various completion
576 and exit commands. @xref{Intro to Minibuffers}.
578 @xref{Standard Keymaps}, for a list of standard keymaps.
580 @defun current-keymaps &optional event-or-keys
581 This function returns a list of the current keymaps that will be
582 searched for bindings. This lists keymaps such as the current local map
583 and the minor-mode maps, but does not list the parents of those keymaps.
584 @var{event-or-keys} controls which keymaps will be listed. If
585 @var{event-or-keys} is a mouse event (or a vector whose last element is
586 a mouse event), the keymaps for that mouse event will be listed.
587 Otherwise, the keymaps for key presses will be listed.
591 This variable contains the default global keymap that maps SXEmacs
592 keyboard input to commands. The global keymap is normally this keymap.
593 The default global keymap is a full keymap that binds
594 @code{self-insert-command} to all of the printing characters.
596 It is normal practice to change the bindings in the global map, but you
597 should not assign this variable any value other than the keymap it starts
601 @defun current-global-map
602 This function returns the current global keymap. This is the
603 same as the value of @code{global-map} unless you change one or the
609 @result{} #<keymap global-map 639 entries 0x221>
614 @defun current-local-map &optional buffer
615 This function returns @var{buffer}'s local keymap, or @code{nil}
616 if it has none. @var{buffer} defaults to the current buffer.
618 In the following example, the keymap for the @samp{*scratch*} buffer
619 (using Lisp Interaction mode) has a number of entries, including one
620 prefix key, @kbd{C-x}.
625 @result{} #<keymap lisp-interaction-mode-map 5 entries 0x558>
626 (describe-bindings-internal (current-local-map))
627 @result{} ; @r{Inserted into the buffer:}
628 backspace backward-delete-char-untabify
629 linefeed eval-print-last-sexp
631 C-j eval-print-last-sexp
632 C-x << Prefix Command >>
633 M-tab lisp-complete-symbol
634 M-; lisp-indent-for-comment
635 M-C-i lisp-complete-symbol
638 Alt-backspace backward-kill-sexp
648 @defun current-minor-mode-maps
649 This function returns a list of the keymaps of currently enabled minor modes.
652 @defun use-global-map keymap
653 This function makes @var{keymap} the new current global keymap. It
656 It is very unusual to change the global keymap.
659 @defun use-local-map keymap &optional buffer
660 This function makes @var{keymap} the new local keymap of @var{buffer}.
661 @var{buffer} defaults to the current buffer. If @var{keymap} is
662 @code{nil}, then the buffer has no local keymap. @code{use-local-map}
663 returns @code{nil}. Most major mode commands use this function.
667 @defvar minor-mode-map-alist
668 This variable is an alist describing keymaps that may or may not be
669 active according to the values of certain variables. Its elements look
673 (@var{variable} . @var{keymap})
676 The keymap @var{keymap} is active whenever @var{variable} has a
677 non-@code{nil} value. Typically @var{variable} is the variable that
678 enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
680 Note that elements of @code{minor-mode-map-alist} do not have the same
681 structure as elements of @code{minor-mode-alist}. The map must be the
682 @sc{cdr} of the element; a list with the map as the second element will
685 What's more, the keymap itself must appear in the @sc{cdr}. It does not
686 work to store a variable in the @sc{cdr} and make the map the value of
689 When more than one minor mode keymap is active, their order of priority
690 is the order of @code{minor-mode-map-alist}. But you should design
691 minor modes so that they don't interfere with each other. If you do
692 this properly, the order will not matter.
694 See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
695 Minor Modes}, for more information about minor modes.
699 This variable holds the keymap consulted for mouse-clicks on the
700 modeline of a window. This variable may be buffer-local; its value will
701 be looked up in the buffer of the window whose modeline was clicked
706 This variable holds the keymap consulted for mouse-clicks over a
710 @defvar mouse-grabbed-buffer
711 If non-@code{nil}, a buffer which should be consulted first for all
712 mouse activity. When a mouse-click is processed, it will first be
713 looked up in the local-map of this buffer, and then through the normal
714 mechanism if there is no binding for that click. This buffer's value of
715 @code{mode-motion-hook} will be consulted instead of the
716 @code{mode-motion-hook} of the buffer of the window under the mouse.
717 You should @emph{bind} this, not set it.
720 @defvar overriding-local-map
721 If non-@code{nil}, this variable holds a keymap to use instead of the
722 buffer's local keymap and instead of all the minor mode keymaps. This
723 keymap, if any, overrides all other maps that would have been active,
724 except for the current global map.
727 @defvar overriding-terminal-local-map
728 If non-@code{nil}, this variable holds a keymap to use instead of the
729 buffer's local keymap and instead of all the minor mode keymaps, but for
730 the selected console only. (In other words, this variable is always
731 console-local; putting a keymap here only applies to keystrokes coming
732 from the selected console. @xref{Consoles and Devices}.) This keymap,
733 if any, overrides all other maps that would have been active, except for
734 the current global map.
743 @dfn{Key lookup} is the process of finding the binding of a key
744 sequence from a given keymap. Actual execution of the binding is not
747 Key lookup uses just the event type of each event in the key
748 sequence; the rest of the event is ignored. In fact, a key sequence
749 used for key lookup may designate mouse events with just their types
750 (symbols) instead of with entire mouse events (lists). @xref{Events}.
751 Such a pseudo-key-sequence is insufficient for @code{command-execute},
752 but it is sufficient for looking up or rebinding a key.
754 When the key sequence consists of multiple events, key lookup
755 processes the events sequentially: the binding of the first event is
756 found, and must be a keymap; then the second event's binding is found in
757 that keymap, and so on until all the events in the key sequence are used
758 up. (The binding thus found for the last event may or may not be a
759 keymap.) Thus, the process of key lookup is defined in terms of a
760 simpler process for looking up a single event in a keymap. How that is
761 done depends on the type of object associated with the event in that
764 Let's use the term @dfn{keymap entry} to describe the value found by
765 looking up an event type in a keymap. (This doesn't include the item
766 string and other extra elements in menu key bindings because
767 @code{lookup-key} and other key lookup functions don't include them in
768 the returned value.) While any Lisp object may be stored in a keymap as
769 a keymap entry, not all make sense for key lookup. Here is a list of
770 the meaningful kinds of keymap entries:
774 @cindex @code{nil} in keymap
775 @code{nil} means that the events used so far in the lookup form an
776 undefined key. When a keymap fails to mention an event type at all, and
777 has no default binding, that is equivalent to a binding of @code{nil}
781 @cindex keymap in keymap
782 The events used so far in the lookup form a prefix key. The next
783 event of the key sequence is looked up in @var{keymap}.
786 @cindex command in keymap
787 The events used so far in the lookup form a complete key,
788 and @var{command} is its binding. @xref{What Is a Function}.
791 @cindex string in keymap
792 The array (either a string or a vector) is a keyboard macro. The events
793 used so far in the lookup form a complete key, and the array is its
794 binding. See @ref{Keyboard Macros}, for more information. (Note that
795 you cannot use a shortened form of a key sequence here, such as
796 @code{(control y)}; you must use the full form @code{[(control y)]}.
797 @xref{Key Sequences}.)
800 @cindex list in keymap
801 The meaning of a list depends on the types of the elements of the list.
805 @cindex @code{lambda} in keymap
806 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
807 lambda expression. This is presumed to be a command, and is treated as
811 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
812 type, then this is an @dfn{indirect entry}:
815 (@var{othermap} . @var{othertype})
818 When key lookup encounters an indirect entry, it looks up instead the
819 binding of @var{othertype} in @var{othermap} and uses that.
821 This feature permits you to define one key as an alias for another key.
822 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
823 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
824 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
828 @cindex symbol in keymap
829 The function definition of @var{symbol} is used in place of
830 @var{symbol}. If that too is a symbol, then this process is repeated,
831 any number of times. Ultimately this should lead to an object that is
832 a keymap, a command or a keyboard macro. A list is allowed if it is a
833 keymap or a command, but indirect entries are not understood when found
836 Note that keymaps and keyboard macros (strings and vectors) are not
837 valid functions, so a symbol with a keymap, string, or vector as its
838 function definition is invalid as a function. It is, however, valid as
839 a key binding. If the definition is a keyboard macro, then the symbol
840 is also valid as an argument to @code{command-execute}
841 (@pxref{Interactive Call}).
843 @cindex @code{undefined} in keymap
844 The symbol @code{undefined} is worth special mention: it means to treat
845 the key as undefined. Strictly speaking, the key is defined, and its
846 binding is the command @code{undefined}; but that command does the same
847 thing that is done automatically for an undefined key: it rings the bell
848 (by calling @code{ding}) but does not signal an error.
850 @cindex preventing prefix key
851 @code{undefined} is used in local keymaps to override a global key
852 binding and make the key ``undefined'' locally. A local binding of
853 @code{nil} would fail to do this because it would not override the
856 @item @var{anything else}
857 If any other type of object is found, the events used so far in the
858 lookup form a complete key, and the object is its binding, but the
859 binding is not executable as a command.
862 In short, a keymap entry may be a keymap, a command, a keyboard macro,
863 a symbol that leads to one of them, or an indirection or @code{nil}.
866 @node Functions for Key Lookup
867 @section Functions for Key Lookup
869 Here are the functions and variables pertaining to key lookup.
871 @defun lookup-key keymap key &optional accept-defaults
872 This function returns the definition of @var{key} in @var{keymap}. If
873 the string or vector @var{key} is not a valid key sequence according to
874 the prefix keys specified in @var{keymap} (which means it is ``too
875 long'' and has extra events at the end), then the value is a number, the
876 number of events at the front of @var{key} that compose a complete key.
879 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
880 considers default bindings as well as bindings for the specific events
881 in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
882 the specific sequence @var{key}, ignoring default bindings except when
883 you explicitly ask about them.
885 All the other functions described in this chapter that look up keys use
890 (lookup-key (current-global-map) "\C-x\C-f")
894 (lookup-key (current-global-map) "\C-x\C-f12345")
899 If @var{key} begins with the character whose value is contained in
900 @code{meta-prefix-char}, that character is implicitly removed and the
901 @key{META} modifier added to the key. Thus, the first example below is
902 handled by conversion into the second example.
906 (lookup-key (current-global-map) "\ef")
907 @result{} forward-word
910 (lookup-key (current-global-map) "\M-f")
911 @result{} forward-word
915 Unlike @code{read-key-sequence}, this function does not modify the
916 specified events in ways that discard information (@pxref{Key Sequence
917 Input}). In particular, it does not convert letters to lower case.
920 @deffn Command undefined
921 Used in keymaps to undefine keys. If a key sequence is defined to this,
922 invoking this key sequence causes a ``key undefined'' error, just as if
923 the key sequence had no binding.
926 @defun key-binding key &optional accept-defaults
927 This function returns the binding for @var{key} in the current
928 keymaps, trying all the active keymaps. The result is @code{nil} if
929 @var{key} is undefined in the keymaps.
932 The argument @var{accept-defaults} controls checking for default
933 bindings, as in @code{lookup-key} (above).
937 (key-binding "\C-x\C-f")
939 (key-binding '(control home))
940 @result{} beginning-of-buffer
941 (key-binding [escape escape escape])
942 @result{} keyboard-escape-quit
947 @defun local-key-binding keys &optional accept-defaults
948 This function returns the binding for @var{keys} in the current
949 local keymap, or @code{nil} if it is undefined there.
952 The argument @var{accept-defaults} controls checking for default bindings,
953 as in @code{lookup-key} (above).
956 @defun global-key-binding keys &optional accept-defaults
957 This function returns the binding for command @var{keys} in the
958 current global keymap, or @code{nil} if it is undefined there.
961 The argument @var{accept-defaults} controls checking for default bindings,
962 as in @code{lookup-key} (above).
966 @defun minor-mode-key-binding key &optional accept-defaults
967 This function returns a list of all the active minor mode bindings of
968 @var{key}. More precisely, it returns an alist of pairs
969 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
970 variable that enables the minor mode, and @var{binding} is @var{key}'s
971 binding in that mode. If @var{key} has no minor-mode bindings, the
974 If the first binding is not a prefix command, all subsequent bindings
975 from other minor modes are omitted, since they would be completely
976 shadowed. Similarly, the list omits non-prefix bindings that follow
979 The argument @var{accept-defaults} controls checking for default
980 bindings, as in @code{lookup-key} (above).
983 @defvar meta-prefix-char
985 This variable is the meta-prefix character code. It is used when
986 translating a two-character sequence to a meta character so it can be
987 looked up in a keymap. For useful results, the value should be a prefix
988 event (@pxref{Prefix Keys}). The default value is @code{?\^[} (integer
989 27), which is the @sc{ascii} character usually produced by the @key{ESC}
992 As long as the value of @code{meta-prefix-char} remains @code{?\^[},
993 key lookup translates @kbd{@key{ESC} b} into @kbd{M-b}, which is
994 normally defined as the @code{backward-word} command. However, if you
995 set @code{meta-prefix-char} to @code{?\^X} (i.e. the keystroke
996 @kbd{C-x}) or its equivalent @sc{ascii} code @code{24}, then SXEmacs will
997 translate @kbd{C-x b} (whose standard binding is the
998 @code{switch-to-buffer} command) into @kbd{M-b}.
1002 meta-prefix-char ; @r{The default value.}
1003 @result{} ?\^[ ; @r{Under SXEmacs.}
1004 @result{} 27 ; @r{Under XEmacs 19.}
1008 @result{} backward-word
1011 ?\C-x ; @r{The print representation}
1012 ; @r{of a character.}
1013 @result{} ?\^X ; @r{Under SXEmacs.}
1014 @result{} 24 ; @r{Under XEmacs 19.}
1017 (setq meta-prefix-char 24)
1021 (key-binding "\C-xb")
1022 @result{} backward-word ; @r{Now, typing @kbd{C-x b} is}
1023 ; @r{like typing @kbd{M-b}.}
1025 (setq meta-prefix-char ?\e) ; @r{Avoid confusion!}
1026 ; @r{Restore the default value!}
1027 @result{} ?\^[ ; @r{Under SXEmacs.}
1028 @result{} 27 ; @r{Under XEmacs 19.}
1034 @node Changing Key Bindings
1035 @section Changing Key Bindings
1036 @cindex changing key bindings
1039 The way to rebind a key is to change its entry in a keymap. If you
1040 change a binding in the global keymap, the change is effective in all
1041 buffers (though it has no direct effect in buffers that shadow the
1042 global binding with a local one). If you change the current buffer's
1043 local map, that usually affects all buffers using the same major mode.
1044 The @code{global-set-key} and @code{local-set-key} functions are
1045 convenient interfaces for these operations (@pxref{Key Binding
1046 Commands}). You can also use @code{define-key}, a more general
1047 function; then you must specify explicitly the map to change.
1049 The way to specify the key sequence that you want to rebind is
1050 described above (@pxref{Key Sequences}).
1052 For the functions below, an error is signaled if @var{keymap} is not a
1053 keymap or if @var{key} is not a string or vector representing a key
1054 sequence. You can use event types (symbols) as shorthand for events
1057 @defun define-key keymap key binding
1058 This function sets the binding for @var{key} in @var{keymap}. (If
1059 @var{key} is more than one event long, the change is actually made
1060 in another keymap reached from @var{keymap}.) The argument
1061 @var{binding} can be any Lisp object, but only certain types are
1062 meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
1063 The value returned by @code{define-key} is @var{binding}.
1065 @cindex invalid prefix key error
1066 @cindex key sequence error
1067 Every prefix of @var{key} must be a prefix key (i.e., bound to a
1068 keymap) or undefined; otherwise an error is signaled.
1070 If some prefix of @var{key} is undefined, then @code{define-key} defines
1071 it as a prefix key so that the rest of @var{key} may be defined as
1075 Here is an example that creates a sparse keymap and makes a number of
1080 (setq map (make-sparse-keymap))
1081 @result{} #<keymap 0 entries 0xbee>
1084 (define-key map "\C-f" 'forward-char)
1085 @result{} forward-char
1089 @result{} #<keymap 1 entry 0xbee>
1090 (describe-bindings-internal map)
1091 @result{} ; @r{(Inserted in buffer)}
1096 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
1097 (define-key map "\C-xf" 'forward-word)
1098 @result{} forward-word
1102 @result{} #<keymap 2 entries 0xbee>
1103 (describe-bindings-internal map)
1104 @result{} ; @r{(Inserted in buffer)}
1106 C-x << Prefix Command >>
1112 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
1113 (define-key map "\C-p" ctl-x-map)
1115 @result{} #<keymap Control-X-prefix 77 entries 0x3bf>
1119 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
1120 (define-key map "\C-p\C-f" 'foo)
1125 @result{} #<keymap 3 entries 0xbee>
1126 (describe-bindings-internal map)
1127 @result{} ; @r{(Inserted in buffer)}
1129 C-p << Prefix command Control-X-prefix >>
1130 C-x << Prefix Command >>
1132 C-p tab indent-rigidly
1133 C-p $ set-selective-display
1135 C-p ( start-kbd-macro
1138 C-p C-x exchange-point-and-mark
1139 C-p C-z suspend-or-iconify-emacs
1140 C-p M-escape repeat-complex-command
1141 C-p M-C-[ repeat-complex-command
1145 C-p 4 . find-tag-other-window
1147 C-p 4 C-o display-buffer
1149 C-p 5 0 delete-frame
1151 C-p 5 C-f find-file-other-frame
1155 C-p a i g inverse-add-global-abbrev
1156 C-p a i l inverse-add-mode-abbrev
1161 Note that storing a new binding for @kbd{C-p C-f} actually works by
1162 changing an entry in @code{ctl-x-map}, and this has the effect of
1163 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
1166 @defun substitute-key-definition olddef newdef keymap &optional oldmap prefix
1167 @cindex replace bindings
1168 This function replaces @var{olddef} with @var{newdef} for any keys in
1169 @var{keymap} that were bound to @var{olddef}. In other words,
1170 @var{olddef} is replaced with @var{newdef} wherever it appears. Prefix
1171 keymaps are checked recursively.
1173 The function returns @code{nil}.
1175 For example, this redefines @kbd{C-x C-f}, if you do it in an SXEmacs with
1180 (substitute-key-definition
1181 'find-file 'find-file-read-only (current-global-map))
1186 If @var{oldmap} is non-@code{nil}, then its bindings determine which
1187 keys to rebind. The rebindings still happen in @var{keymap}, not in
1188 @var{oldmap}. Thus, you can change one map under the control of the
1189 bindings in another. For example,
1192 (substitute-key-definition
1193 'delete-backward-char 'my-funny-delete
1198 puts the special deletion command in @code{my-map} for whichever keys
1199 are globally bound to the standard deletion command.
1201 If argument @var{prefix} is non-@code{nil}, then only those occurrences
1202 of @var{olddef} found in keymaps accessible through the keymap bound to
1203 @var{prefix} in @var{keymap} are redefined. See also
1204 @code{accessible-keymaps}.
1208 Prefix keymaps that appear within @var{keymap} are not checked
1209 recursively for keys bound to @var{olddef}; they are not changed at all.
1210 Perhaps it would be better to check nested keymaps recursively.
1213 @ignore @c #### fix this up.
1214 Here is an example showing a keymap before and after substitution:
1222 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
1226 (substitute-key-definition 'olddef-1 'newdef map)
1231 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
1237 @defun suppress-keymap keymap &optional nodigits
1238 @cindex @code{self-insert-command} override
1239 This function changes the contents of the full keymap @var{keymap} by
1240 making all the printing characters undefined. More precisely, it binds
1241 them to the command @code{undefined}. This makes ordinary insertion of
1242 text impossible. @code{suppress-keymap} returns @code{nil}.
1244 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
1245 digits to run @code{digit-argument}, and @kbd{-} to run
1246 @code{negative-argument}. Otherwise it makes them undefined like the
1247 rest of the printing characters.
1249 @cindex yank suppression
1250 @cindex @code{quoted-insert} suppression
1251 The @code{suppress-keymap} function does not make it impossible to
1252 modify a buffer, as it does not suppress commands such as @code{yank}
1253 and @code{quoted-insert}. To prevent any modification of a buffer, make
1254 it read-only (@pxref{Read Only Buffers}).
1256 Since this function modifies @var{keymap}, you would normally use it
1257 on a newly created keymap. Operating on an existing keymap
1258 that is used for some other purpose is likely to cause trouble; for
1259 example, suppressing @code{global-map} would make it impossible to use
1262 Most often, @code{suppress-keymap} is used to initialize local
1263 keymaps of modes such as Rmail and Dired where insertion of text is not
1264 desirable and the buffer is read-only. Here is an example taken from
1265 the file @file{<sxemacs-src>/lisp/dired.el}, showing how the local keymap for
1266 Dired mode is set up:
1271 (setq dired-mode-map (make-keymap))
1272 (suppress-keymap dired-mode-map)
1273 (define-key dired-mode-map "r" 'dired-rename-file)
1274 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
1275 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
1276 (define-key dired-mode-map "v" 'dired-view-file)
1277 (define-key dired-mode-map "e" 'dired-find-file)
1278 (define-key dired-mode-map "f" 'dired-find-file)
1285 @node Key Binding Commands
1286 @section Commands for Binding Keys
1288 This section describes some convenient interactive interfaces for
1289 changing key bindings. They work by calling @code{define-key}.
1291 People often use @code{global-set-key} in their @file{init.el} file for
1292 simple customization. For example,
1295 (global-set-key "\C-x\C-\\" 'next-line)
1302 (global-set-key [(control ?x) (control ?\\)] 'next-line)
1309 (global-set-key [?\C-x ?\C-\\] 'next-line)
1313 redefines @kbd{C-x C-\} to move down a line.
1316 (global-set-key [(meta button1)] 'mouse-set-point)
1320 redefines the first (leftmost) mouse button, typed with the Meta key, to
1321 set point where you click.
1323 @deffn Command global-set-key key definition
1324 This function sets the binding of @var{key} in the current global map
1325 to @var{definition}.
1329 (global-set-key @var{key} @var{definition})
1331 (define-key (current-global-map) @var{key} @var{definition})
1336 @deffn Command global-unset-key key
1337 @cindex unbinding keys
1338 This function removes the binding of @var{key} from the current
1341 One use of this function is in preparation for defining a longer key
1342 that uses @var{key} as a prefix---which would not be allowed if
1343 @var{key} has a non-prefix binding. For example:
1347 (global-unset-key "\C-l")
1351 (global-set-key "\C-l\C-l" 'redraw-display)
1356 This function is implemented simply using @code{define-key}:
1360 (global-unset-key @var{key})
1362 (define-key (current-global-map) @var{key} nil)
1367 @deffn Command local-set-key key definition
1368 This function sets the binding of @var{key} in the current local
1369 keymap to @var{definition}.
1373 (local-set-key @var{key} @var{definition})
1375 (define-key (current-local-map) @var{key} @var{definition})
1380 @deffn Command local-unset-key key
1381 This function removes the binding of @var{key} from the current
1386 (local-unset-key @var{key})
1388 (define-key (current-local-map) @var{key} nil)
1394 @node Scanning Keymaps
1395 @section Scanning Keymaps
1397 This section describes functions used to scan all the current keymaps,
1398 or all keys within a keymap, for the sake of printing help information.
1400 @defun accessible-keymaps keymap &optional prefix
1401 This function returns a list of all the keymaps that can be accessed
1402 (via prefix keys) from @var{keymap}. The value is an association list
1403 with elements of the form @code{(@var{key} .@: @var{map})}, where
1404 @var{key} is a prefix key whose definition in @var{keymap} is
1407 The elements of the alist are ordered so that the @var{key} increases
1408 in length. The first element is always @code{([] .@: @var{keymap})},
1409 because the specified keymap is accessible from itself with a prefix of
1412 If @var{prefix} is given, it should be a prefix key sequence; then
1413 @code{accessible-keymaps} includes only the submaps whose prefixes start
1414 with @var{prefix}. These elements look just as they do in the value of
1415 @code{(accessible-keymaps)}; the only difference is that some elements
1418 In the example below, the returned alist indicates that the key
1419 @kbd{C-x}, which is displayed as @samp{[(control x)]}, is a prefix key
1420 whose definition is the keymap @code{#<keymap ((control x) #<keymap
1421 emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>}. (The strange
1422 notation for the keymap's name indicates that this is an internal submap
1423 of @code{emacs-lisp-mode-map}. This is because
1424 @code{lisp-interaction-mode-map} has set up @code{emacs-lisp-mode-map}
1425 as its parent, and @code{lisp-interaction-mode-map} defines no key
1426 sequences beginning with @kbd{C-x}.)
1431 @result{} #<keymap lisp-interaction-mode-map 5 entries 0x558>
1432 (accessible-keymaps (current-local-map))
1433 @result{}(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
1435 #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
1440 The following example shows the results of calling
1441 @code{accessible-keymaps} on a large, complex keymap. Notice how
1442 some keymaps were given explicit names using @code{set-keymap-name};
1443 those submaps without explicit names are given descriptive names
1444 indicating their relationship to their enclosing keymap.
1448 (accessible-keymaps (current-global-map))
1449 @result{} (([] . #<keymap global-map 639 entries 0x221>)
1450 ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
1451 ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
1452 ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
1454 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1456 ([(meta control \[)] .
1457 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1459 ([f1] . #<keymap help-map 33 entries 0x4ec>)
1460 ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
1461 ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
1462 ([(control x) \6] . #<keymap 13 entries 0x4d2>)
1464 #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1466 ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
1467 ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
1468 ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
1469 ([(control x) a i] .
1470 #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1477 @defun map-keymap function keymap &optional sort-first
1478 This function applies @var{function} to each element of @var{keymap}.
1479 @var{function} will be called with two arguments: a key-description
1480 list, and the binding. The order in which the elements of the keymap
1481 are passed to the function is unspecified. If the function inserts new
1482 elements into the keymap, it may or may not be called with them later.
1483 No element of the keymap will ever be passed to the function more than
1486 The function will not be called on elements of this keymap's parents
1487 (@pxref{Inheritance and Keymaps}) or upon keymaps which are contained
1488 within this keymap (multi-character definitions). It will be called on
1489 @key{META} characters since they are not really two-character sequences.
1491 If the optional third argument @var{sort-first} is non-@code{nil}, then
1492 the elements of the keymap will be passed to the mapper function in a
1493 canonical order. Otherwise, they will be passed in hash (that is,
1494 random) order, which is faster.
1497 @defun keymap-fullness keymap
1498 This function returns the number of bindings in the keymap.
1501 @defun where-is-internal definition &optional keymaps firstonly noindirect event-or-keys
1502 This function returns a list of key sequences (of any length) that are
1503 bound to @var{definition} in a set of keymaps.
1505 The argument @var{definition} can be any object; it is compared with all
1506 keymap entries using @code{eq}.
1508 @var{keymaps} can be either a keymap (meaning search in that keymap and the
1509 current global keymap) or a list of keymaps (meaning search in exactly
1510 those keymaps and no others). If @var{keymaps} is nil, search in the currently
1511 applicable maps for @var{event-or-keys}.
1513 If @var{keymaps} is a keymap, then the maps searched are @var{keymaps} and
1514 the global keymap. If @var{keymaps} is a list of keymaps, then the maps
1515 searched are exactly those keymaps, and no others. If @var{keymaps} is
1516 @code{nil}, then the maps used are the current active keymaps for
1517 @var{event-or-keys} (this is equivalent to specifying
1518 @code{(current-keymaps @var{event-or-keys})} as the argument to
1521 If @var{firstonly} is non-@code{nil}, then the value is a single
1522 vector representing the first key sequence found, rather than a list of
1523 all possible key sequences.
1524 @ignore @c #### Should fix where-is to be more like FSF
1525 If @var{firstonly} is @code{non-ascii}, then the value is a single
1526 string representing the first key sequence found, rather than a list of
1527 all possible key sequences. If @var{firstonly} is @code{t}, then the
1528 value is the first key sequence, except that key sequences consisting
1529 entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
1530 characters) are preferred to all other key sequences.
1533 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
1534 follow indirect keymap bindings. This makes it possible to search for
1535 an indirect definition itself.
1537 This function is used by @code{where-is} (@pxref{Help, , Help, sxemacs,
1538 The SXEmacs Lisp Reference Manual}).
1542 (where-is-internal 'describe-function)
1543 @result{} ([(control h) d] [(control h) f] [f1 d] [f1 f])
1548 @defun describe-bindings-internal map &optional all shadow prefix mouse-only-p
1549 This function inserts (into the current buffer) a list of all defined
1550 keys and their definitions in @var{map}. Optional second argument
1551 @var{all} says whether to include even ``uninteresting'' definitions,
1552 i.e. symbols with a non-@code{nil} @code{suppress-keymap} property.
1553 Third argument @var{shadow} is a list of keymaps whose bindings shadow
1554 those of map; if a binding is present in any shadowing map, it is not
1555 printed. Fourth argument @var{prefix}, if non-@code{nil}, should be a
1556 key sequence; only bindings which start with that key sequence will be
1557 printed. Fifth argument @var{mouse-only-p} says to only print bindings
1561 @code{describe-bindings-internal} is used to implement the
1562 help command @code{describe-bindings}.
1564 @deffn Command describe-bindings &optional prefix mouse-only-p
1565 This function creates a listing of all defined keys and their
1566 definitions. It writes the listing in a buffer named @samp{*Help*} and
1567 displays it in a window.
1569 If optional argument @var{prefix} is non-@code{nil}, it should be a
1570 prefix key; then the listing includes only keys that start with
1573 When several characters with consecutive @sc{ascii} codes have the
1574 same definition, they are shown together, as
1575 @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
1576 know the @sc{ascii} codes to understand which characters this means.
1577 For example, in the default global map, the characters @samp{@key{SPC}
1578 ..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32,
1579 @kbd{~} is @sc{ascii} 126, and the characters between them include all
1580 the normal printing characters, (e.g., letters, digits, punctuation,
1581 etc.@:); all these characters are bound to @code{self-insert-command}.
1583 If the second optional argument @var{mouse-only-p} (prefix arg,
1584 interactively) is non-@code{nil} then only the mouse bindings are
1589 @node Other Keymap Functions
1590 @section Other Keymap Functions
1592 @defun set-keymap-prompt keymap new-prompt
1593 This function sets the ``prompt'' of @var{keymap} to string
1594 @var{new-prompt}, or @code{nil} if no prompt is desired. The prompt is
1595 shown in the echo-area when reading a key-sequence to be looked-up in
1599 @defun keymap-prompt keymap &optional use-inherited
1600 This function returns the ``prompt'' of the given keymap.
1601 If @var{use-inherited} is non-@code{nil}, any parent keymaps
1602 will also be searched for a prompt.