@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000
-@c Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
A keymap is a list whose @sc{car} is the symbol @code{keymap}. The
remaining elements of the list define the key bindings of the keymap.
-Use the function @code{keymapp} (see below) to test whether an object is
-a keymap.
+A symbol whose function definition is a keymap is also a keymap. Use
+the function @code{keymapp} (see below) to test whether an object is a
+keymap.
Several kinds of elements may appear in a keymap, after the symbol
@code{keymap} that begins it:
called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
keymaps}.
+A @code{nil} binding is used to mean that a key is explicitly not bound.
+Just like any other binding, it takes precedence over a default binding
+or a binding in the parent keymap, but on the other hand, it does not
+take precedence over keymaps of lower priority.
+
When a keymap contains a vector, it always defines a binding for each
@sc{ascii} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default key
@example
@group
lisp-mode-map
-@result{}
+@result{}
@end group
@group
-(keymap
+(keymap
;; @key{TAB}
- (9 . lisp-indent-line)
+ (9 . lisp-indent-line)
@end group
@group
;; @key{DEL}
- (127 . backward-delete-char-untabify)
+ (127 . backward-delete-char-untabify)
@end group
@group
- (3 keymap
+ (3 keymap
;; @kbd{C-c C-l}
- (12 . run-lisp))
+ (12 . run-lisp))
@end group
@group
- (27 keymap
+ (27 keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)
+ (17 . indent-sexp)
;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)))
+ (24 . lisp-send-defun)))
@end group
@end example
@defun keymapp object
This function returns @code{t} if @var{object} is a keymap, @code{nil}
otherwise. More precisely, this function tests for a list whose
-@sc{car} is @code{keymap}.
+@sc{car} is @code{keymap}, or for a symbol whose function definition
+satisfies @code{keymapp}.
@example
@group
@result{} t
@end group
@group
+(fset 'foo '(keymap))
+(keymapp 'foo)
+ @result{} t
+@end group
+@group
(keymapp (current-global-map))
@result{} t
@end group
@c ??? This should come after make-sparse-keymap
@defun make-keymap &optional prompt
-This function creates and returns a new full keymap (i.e., one
-containing a vector of length 128 for defining all the @sc{ascii}
-characters). The new keymap initially binds all @sc{ascii} characters
-to @code{nil}, and does not bind any other kind of event.
+This function creates and returns a new full keymap. That keymap
+contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
+128 slots are for defining all the @sc{ascii} characters, the next 128
+slots are for 8-bit European characters, and each one of the final 128
+slots is for one character set of non-@sc{ascii} characters supported by
+Emacs. The new keymap initially binds all these characters to
+@code{nil}, and does not bind any other kind of event.
@example
@group
@defun make-sparse-keymap &optional prompt
This function creates and returns a new sparse keymap with no entries.
-The new keymap does not bind any events. The argument @var{prompt}
-specifies a prompt string, as in @code{make-keymap}.
+The new keymap does not contain a char-table, unlike @code{make-keymap},
+and does not bind any events. The argument @var{prompt} specifies a
+prompt string, as in @code{make-keymap}.
@example
@group
@end group
@group
;; @r{(This implements meta characters.)}
- (27 keymap
+ (27 keymap
(83 . center-paragraph)
(115 . center-line))
(9 . tab-to-tab-stop))
prefix keys.
@end defun
-Here is an example showing how to make a keymap that inherits
+ Here is an example showing how to make a keymap that inherits
from @code{text-mode-map}:
@example
map)
@end example
+ A non-sparse keymap can have a parent too, but this is not very
+useful. A non-sparse keymap always specifies something as the binding
+for every numeric character code without modifier bits, even if it is
+@code{nil}, so these character's bindings are never inherited from
+the parent keymap.
+
@node Prefix Keys
@section Prefix Keys
@cindex prefix key
when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
-another local keymap that overrides the buffer's local map and all the
+another local keymap that overrides the buffer's local map and all the
minor mode keymaps.
All the active keymaps are used together to determine what command to
@example
@group
(current-global-map)
-@result{} (keymap [set-mark-command beginning-of-line @dots{}
+@result{} (keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@end example
@example
@group
(current-local-map)
-@result{} (keymap
- (10 . eval-print-last-sexp)
- (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
+@result{} (keymap
+ (10 . eval-print-last-sexp)
+ (9 . lisp-indent-line)
+ (127 . backward-delete-char-untabify)
@end group
@group
- (27 keymap
- (24 . eval-defun)
+ (27 keymap
+ (24 . eval-defun)
(17 . indent-sexp)))
@end group
@end example
@end group
@group
(setq meta-prefix-char 24)
- @result{} 24
+ @result{} 24
@end group
@group
(key-binding "\M-b")
meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
The value returned by @code{define-key} is @var{binding}.
+If @var{key} is @code{[t]}, this sets the default binding in
+@var{keymap}. When an event has no binding of its own, the Emacs
+command loop uses the keymap's default binding, if there is one.
+
@cindex invalid prefix key error
@cindex key sequence error
Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
If there was previously no binding for @var{key} in @var{keymap}, the
new binding is added at the beginning of @var{keymap}. The order of
-bindings in a keymap makes no difference in most cases, but it does
-matter for menu keymaps (@pxref{Menu Keymaps}).
+bindings in a keymap makes no difference for keyboard input, but it
+does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
Here is an example that creates a sparse keymap and makes a number of
@end group
@group
map
-@result{} (keymap
+@result{} (keymap
(24 keymap ; @kbd{C-x}
(102 . forward-word)) ; @kbd{f}
(6 . forward-char)) ; @kbd{C-f}
;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
(define-key map "\C-p" ctl-x-map)
;; @code{ctl-x-map}
-@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
+@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
@end group
@group
map
@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.}
(16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
- (24 keymap
+ (24 keymap
(102 . forward-word))
(6 . forward-char))
@end group
@smallexample
@group
-(substitute-key-definition
+(substitute-key-definition
'find-file 'find-file-read-only (current-global-map))
@end group
@end smallexample
@smallexample
@group
-(setq map '(keymap
- (?1 . olddef-1)
- (?2 . olddef-2)
+(setq map '(keymap
+ (?1 . olddef-1)
+ (?2 . olddef-2)
(?3 . olddef-1)))
@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
@end group
@code{negative-argument}. Otherwise it makes them undefined like the
rest of the printing characters.
-@cindex yank suppression
-@cindex @code{quoted-insert} suppression
+@cindex yank suppression
+@cindex @code{quoted-insert} suppression
The @code{suppress-keymap} function does not make it impossible to
modify a buffer, as it does not suppress commands such as @code{yank}
and @code{quoted-insert}. To prevent any modification of a buffer, make
@smallexample
@group
(accessible-keymaps (current-local-map))
-@result{}(("" keymap
+@result{}(("" keymap
(27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.}
(83 . center-paragraph)
(115 . center-line))
@end group
@group
- ("^[" keymap
- (83 . center-paragraph)
+ ("^[" keymap
+ (83 . center-paragraph)
(115 . foo)))
@end group
@end smallexample
@smallexample
@group
(accessible-keymaps (current-global-map))
-@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
+@result{} (("" keymap [set-mark-command beginning-of-line @dots{}
delete-backward-char])
@end group
@group
If @var{keymap} is @code{nil}, then the maps used are the current active
keymaps, disregarding @code{overriding-local-map} (that is, pretending
its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the
-maps searched are @var{keymap} and the global keymap.
+maps searched are @var{keymap} and the global keymap. If @var{keymap}
+is a list of keymaps, only those keymaps are searched.
Usually it's best to use @code{overriding-local-map} as the expression
for @var{keymap}. Then @code{where-is-internal} searches precisely the
To define items in some local map, bind @code{`tool-bar-map} with
@code{let} around calls of this function:
@example
-(defvar foo-tool-bar-map
+(defvar foo-tool-bar-map
(let ((tool-bar-map (make-sparse-keymap)))
(tool-bar-add-item @dots{})
@dots{}