keymaps.texi 80.3 KB
Newer Older
Richard M. Stallman's avatar
Richard M. Stallman committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Gerd Moellmann's avatar
Gerd Moellmann committed
3 4
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999
@c   Free Software Foundation, Inc. 
Richard M. Stallman's avatar
Richard M. Stallman committed
5 6 7 8 9 10 11 12
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@chapter Keymaps
@cindex keymap

  The bindings between input events and commands are recorded in data
structures called @dfn{keymaps}.  Each binding in a keymap associates
13 14 15 16
(or @dfn{binds}) an individual event type either to another keymap or to
a command.  When an event type is bound to a keymap, that keymap is used
to look up the next input event; this continues until a command is
found.  The whole process is called @dfn{key lookup}.
Richard M. Stallman's avatar
Richard M. Stallman committed
17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

@menu
* Keymap Terminology::        	Definitions of terms pertaining to keymaps.
* Format of Keymaps::		What a keymap looks like as a Lisp object.
* Creating Keymaps:: 		Functions to create and copy keymaps.
* Inheritance and Keymaps::	How one keymap can inherit the bindings
				   of another keymap.
* Prefix Keys::                 Defining a key with a keymap as its definition.
* Active Keymaps::	        Each buffer has a local keymap
                                   to override the standard (global) bindings.
				   A minor mode can also override them.
* Key Lookup::                  How extracting elements from keymaps works.
* Functions for Key Lookup::    How to request key lookup.
* Changing Key Bindings::       Redefining a key in a keymap.
* Key Binding Commands::        Interactive interfaces for redefining keys.
* Scanning Keymaps::            Looking through all keymaps, for printing help.
33
* Menu Keymaps::		Defining a menu as a keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47
@end menu

@node Keymap Terminology
@section Keymap Terminology
@cindex key
@cindex keystroke
@cindex key binding
@cindex binding of a key
@cindex complete key
@cindex undefined key

  A @dfn{keymap} is a table mapping event types to definitions (which
can be any Lisp objects, though only certain types are meaningful for
execution by the command loop).  Given an event (or an event type) and a
48 49
keymap, Emacs can get the event's definition.  Events include
characters, function keys, and mouse actions (@pxref{Input Events}).
Richard M. Stallman's avatar
Richard M. Stallman committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64

  A sequence of input events that form a unit is called a
@dfn{key sequence}, or @dfn{key} for short.  A sequence of one event
is always a key sequence, and so are some multi-event sequences.

  A keymap determines a binding or definition for any key sequence.  If
the key sequence is a single event, its binding is the definition of the
event in the keymap.  The binding of a key sequence of more than one
event is found by an iterative process: the binding of the first event
is found, and must be a keymap; then the second event's binding is found
in that keymap, and so on until all the events in the key sequence are
used up.

  If the binding of a key sequence is a keymap, we call the key sequence
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},
Richard M. Stallman's avatar
Richard M. Stallman committed
66 67 68 69 70 71 72 73 74
we call the key @dfn{undefined}.  Examples of prefix keys are @kbd{C-c},
@kbd{C-x}, and @kbd{C-x 4}.  Examples of defined complete keys are
@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}.  Examples of undefined complete
keys are @kbd{C-x C-g}, and @kbd{C-c 3}.  @xref{Prefix Keys}, for more
details.

  The rule for finding the binding of a key sequence assumes that the
intermediate bindings (found for the events before the last) are all
keymaps; if this is not so, the sequence of events does not form a
75 76 77 78 79 80 81 82 83 84 85
unit---it is not really one key sequence.  In other words, removing one
or more events from the end of any valid key sequence must always yield
a prefix key.  For example, @kbd{C-f C-n} is not a key sequence;
@kbd{C-f} is not a prefix key, so a longer sequence starting with
@kbd{C-f} cannot be a key sequence.

  The set of possible multi-event key sequences depends on the bindings
for prefix keys; therefore, it can be different for different keymaps,
and can change when bindings are changed.  However, a one-event sequence
is always a key sequence, because it does not depend on any prefix keys
for its well-formedness.
Richard M. Stallman's avatar
Richard M. Stallman committed
86 87 88 89 90

  At any time, several primary keymaps are @dfn{active}---that is, in
use for finding key bindings.  These are the @dfn{global map}, which is
shared by all buffers; the @dfn{local keymap}, which is usually
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
Richard M. Stallman's avatar
Richard M. Stallman committed
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
modes have keymaps.)  The local keymap bindings shadow (i.e., take
precedence over) the corresponding global bindings.  The minor mode
keymaps shadow both local and global keymaps.  @xref{Active Keymaps},
for details.

@node Format of Keymaps
@section Format of Keymaps
@cindex format of keymaps
@cindex keymap format
@cindex full keymap
@cindex sparse keymap

  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.

109 110
  Several kinds of elements may appear in a keymap, after the symbol
@code{keymap} that begins it:
111

112 113 114 115 116
@table @code
@item (@var{type} .@: @var{binding})
This specifies one binding, for events of type @var{type}.  Each
ordinary binding applies to events of a particular @dfn{event type},
which is always a character or a symbol.  @xref{Classifying Events}.
Richard M. Stallman's avatar
Richard M. Stallman committed
117

118
@item (t .@: @var{binding})
Richard M. Stallman's avatar
Richard M. Stallman committed
119
@cindex default key binding
120 121 122 123 124 125 126 127
This specifies a @dfn{default key binding}; any event not bound by other
elements of the keymap is given @var{binding} as its binding.  Default
bindings allow a keymap to bind all possible event types without having
to enumerate all of them.  A keymap that has a default binding
completely masks any lower-precedence keymap.

@item @var{vector}
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 130 131 132
@var{n} is the binding for the character with code @var{n}.  This is a
compact way to record lots of bindings.  A keymap with such a vector is
called a @dfn{full keymap}.  Other keymaps are called @dfn{sparse
keymaps}.
133 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 138
binding in the keymap, for @sc{ascii} characters.  However, default
bindings are still meaningful for events other than @sc{ascii}
139 140 141
characters.  A binding of @code{nil} does @emph{not} override
lower-precedence keymaps; thus, if the local map gives a binding of
@code{nil}, Emacs uses the binding from the global map.
Richard M. Stallman's avatar
Richard M. Stallman committed
142

143
@item @var{string}
Richard M. Stallman's avatar
Richard M. Stallman committed
144 145 146
@cindex keymap prompt string
@cindex overall prompt string
@cindex prompt string of keymap
147
Aside from bindings, a keymap can also have a string as an element.
Richard M. Stallman's avatar
Richard M. Stallman committed
148
This is called the @dfn{overall prompt string} and makes it possible to
Gerd Moellmann's avatar
Gerd Moellmann committed
149
use the keymap as a menu.  @xref{Defining Menus}.
150
@end table
Richard M. Stallman's avatar
Richard M. Stallman committed
151 152

@cindex meta characters lookup
153 154
  Keymaps do not directly record bindings for the meta characters.
Instead, meta characters are regarded for
Richard M. Stallman's avatar
Richard M. Stallman committed
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
purposes of key lookup as sequences of two characters, the first of
which is @key{ESC} (or whatever is currently the value of
@code{meta-prefix-char}).  Thus, the key @kbd{M-a} is really represented
as @kbd{@key{ESC} a}, and its global binding is found at the slot for
@kbd{a} in @code{esc-map} (@pxref{Prefix Keys}).

  Here as an example is the local keymap for Lisp mode, a sparse
keymap.  It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.

@example
@group
lisp-mode-map
@result{} 
@end group
@group
(keymap 
 ;; @key{TAB}
 (9 . lisp-indent-line)                 
@end group
@group
 ;; @key{DEL}
 (127 . backward-delete-char-untabify)  
@end group
@group
 (3 keymap 
    ;; @kbd{C-c C-l}
    (12 . run-lisp))                    
@end group
@group
 (27 keymap 
     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
     (17 . indent-sexp)                 
     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
     (24 . lisp-send-defun)))           
@end group
@end example

@defun keymapp object
This function returns @code{t} if @var{object} is a keymap, @code{nil}
195
otherwise.  More precisely, this function tests for a list whose
Richard M. Stallman's avatar
Richard M. Stallman committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215
@sc{car} is @code{keymap}.

@example
@group
(keymapp '(keymap))
    @result{} t
@end group
@group
(keymapp (current-global-map))
    @result{} t
@end group
@end example
@end defun

@node Creating Keymaps
@section Creating Keymaps
@cindex creating keymaps

  Here we describe the functions for creating keymaps.

216
@c ??? This should come after make-sparse-keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
217
@defun make-keymap &optional prompt
218
This function creates and returns a new full keymap (i.e., one
219 220
containing a vector of length 128 for defining all the @sc{ascii}
characters).  The new keymap initially binds all @sc{ascii} characters
Richard M. Stallman's avatar
Richard M. Stallman committed
221 222 223 224 225 226 227 228 229 230
to @code{nil}, and does not bind any other kind of event.

@example
@group
(make-keymap)
    @result{} (keymap [nil nil nil @dots{} nil nil])
@end group
@end example

If you specify @var{prompt}, that becomes the overall prompt string for
Gerd Moellmann's avatar
Gerd Moellmann committed
231 232
the keymap.  The prompt string is useful for menu keymaps
(@pxref{Defining Menus}).
Richard M. Stallman's avatar
Richard M. Stallman committed
233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
@end defun

@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}.

@example
@group
(make-sparse-keymap)
    @result{} (keymap)
@end group
@end example
@end defun

@defun copy-keymap keymap
249
This function returns a copy of @var{keymap}.  Any keymaps that
Richard M. Stallman's avatar
Richard M. Stallman committed
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284
appear directly as bindings in @var{keymap} are also copied recursively,
and so on to any number of levels.  However, recursive copying does not
take place when the definition of a character is a symbol whose function
definition is a keymap; the same symbol appears in the new copy.
@c Emacs 19 feature

@example
@group
(setq map (copy-keymap (current-local-map)))
@result{} (keymap
@end group
@group
     ;; @r{(This implements meta characters.)}
     (27 keymap         
         (83 . center-paragraph)
         (115 . center-line))
     (9 . tab-to-tab-stop))
@end group

@group
(eq map (current-local-map))
    @result{} nil
@end group
@group
(equal map (current-local-map))
    @result{} t
@end group
@end example
@end defun

@node Inheritance and Keymaps
@section Inheritance and Keymaps
@cindex keymap inheritance
@cindex inheriting a keymap's bindings

285 286
  A keymap can inherit the bindings of another keymap, which we call the
@dfn{parent keymap}.  Such a keymap looks like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
287 288

@example
289
(keymap @var{bindings}@dots{} . @var{parent-keymap})
Richard M. Stallman's avatar
Richard M. Stallman committed
290 291 292 293
@end example

@noindent
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,
Richard M. Stallman's avatar
Richard M. Stallman committed
295 296
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}
Richard M. Stallman's avatar
Richard M. Stallman committed
298 299 300
or other key-binding functions, these changes are visible in the
inheriting keymap unless shadowed by @var{bindings}.  The converse is
not true: if you use @code{define-key} to change the inheriting keymap,
301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321
that affects @var{bindings}, but has no effect on @var{parent-keymap}.

The proper way to construct a keymap with a parent is to use
@code{set-keymap-parent}; if you have code that directly constructs a
keymap with a parent, please convert the program to use
@code{set-keymap-parent} instead.

@defun keymap-parent keymap
This returns the parent keymap of @var{keymap}.  If @var{keymap}
has no parent, @code{keymap-parent} returns @code{nil}.
@end defun

@defun set-keymap-parent keymap parent
This sets the parent keymap of @var{keymap} to @var{parent}, and returns
@var{parent}.  If @var{parent} is @code{nil}, this function gives
@var{keymap} no parent at all.

If @var{keymap} has submaps (bindings for prefix keys), they too receive
new parent keymaps that reflect what @var{parent} specifies for those
prefix keys.
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
322 323 324 325 326

Here is an example showing how to make a keymap that inherits
from @code{text-mode-map}:

@example
327 328 329
(let ((map (make-sparse-keymap)))
  (set-keymap-parent map text-mode-map)
  map)
Richard M. Stallman's avatar
Richard M. Stallman committed
330 331 332 333 334 335
@end example

@node Prefix Keys
@section Prefix Keys
@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 339 340 341
For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
also stored in the variable @code{ctl-x-map}.  This keymap defines
bindings for key sequences starting with @kbd{C-x}.

342 343
  Some of the standard Emacs prefix keys use keymaps that are
also found in Lisp variables:
Richard M. Stallman's avatar
Richard M. Stallman committed
344 345 346 347 348

@itemize @bullet
@item
@vindex esc-map
@findex ESC-prefix
349 350 351
@code{esc-map} is the global keymap for the @key{ESC} prefix key.  Thus,
the global definitions of all meta characters are actually found here.
This map is also the function definition of @code{ESC-prefix}.
Richard M. Stallman's avatar
Richard M. Stallman committed
352 353 354

@item
@cindex @kbd{C-h}
355
@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
Richard M. Stallman's avatar
Richard M. Stallman committed
356 357 358 359

@item
@cindex @kbd{C-c}
@vindex mode-specific-map
360 361 362 363 364
@code{mode-specific-map} is the global keymap for the prefix key
@kbd{C-c}.  This map is actually global, not mode-specific, but its name
provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
(@code{display-bindings}), since the main use of this prefix key is for
mode-specific bindings.
Richard M. Stallman's avatar
Richard M. Stallman committed
365 366 367 368 369

@item
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
370 371
@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
This map is found via the function cell of the symbol
372
@code{Control-X-prefix}.
Richard M. Stallman's avatar
Richard M. Stallman committed
373

374 375 376 377 378 379
@item
@cindex @kbd{C-x @key{RET}}
@vindex mule-keymap
@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
prefix key.

Richard M. Stallman's avatar
Richard M. Stallman committed
380 381 382
@item
@cindex @kbd{C-x 4}
@vindex ctl-x-4-map
383 384
@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
key.
Richard M. Stallman's avatar
Richard M. Stallman committed
385 386 387 388 389

@c Emacs 19 feature
@item
@cindex @kbd{C-x 5}
@vindex ctl-x-5-map
390 391
@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
key.
Richard M. Stallman's avatar
Richard M. Stallman committed
392 393 394

@c Emacs 19 feature
@item
395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416
@cindex @kbd{C-x 6}
@vindex 2C-mode-map
@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
key.

@item
@cindex @kbd{C-x v}
@vindex vc-prefix-map
@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
key.

@item
@cindex @kbd{M-g}
@vindex facemenu-keymap
@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
prefix key.

@c Emacs 19 feature
@item
The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
@key{ESC}} and @kbd{@key{ESC} @key{ESC}}.  They use keymaps that have no
special names.
Richard M. Stallman's avatar
Richard M. Stallman committed
417 418
@end itemize

419 420 421 422
  The keymap binding of a prefix key is used for looking up the event
that follows the prefix key.  (It may instead be a symbol whose function
definition is a keymap.  The effect is the same, but the symbol serves
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
Richard M. Stallman's avatar
Richard M. Stallman committed
425 426
@code{ctl-x-map}.)

427 428 429
  Prefix key definitions can appear in any active keymap.  The
definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
keys appear in the global map, so these prefix keys are always
Richard M. Stallman's avatar
Richard M. Stallman committed
430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464
available.  Major and minor modes can redefine a key as a prefix by
putting a prefix key definition for it in the local map or the minor
mode's map.  @xref{Active Keymaps}.

  If a key is defined as a prefix in more than one active map, then its
various definitions are in effect merged: the commands defined in the
minor mode keymaps come first, followed by those in the local map's
prefix definition, and then by those from the global map.

  In the following example, we make @kbd{C-p} a prefix key in the local
keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}.  Then
the binding for @kbd{C-p C-f} is the function @code{find-file}, just
like @kbd{C-x C-f}.  The key sequence @kbd{C-p 6} is not found in any
active keymap.

@example
@group
(use-local-map (make-sparse-keymap))
    @result{} nil
@end group
@group
(local-set-key "\C-p" ctl-x-map)
    @result{} nil
@end group
@group
(key-binding "\C-p\C-f")
    @result{} find-file
@end group

@group
(key-binding "\C-p6")
    @result{} nil
@end group
@end example

465
@defun define-prefix-command symbol &optional mapvar prompt
Richard M. Stallman's avatar
Richard M. Stallman committed
466
@cindex prefix command
467
This function prepares @var{symbol} for use as a prefix key's binding:
Gerd Moellmann's avatar
Gerd Moellmann committed
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}.
471 472

This function also sets @var{symbol} as a variable, with the keymap as
473 474
its value.  But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
as a variable instead.
475

476 477
If @var{prompt} is non-@code{nil}, that becomes the overall prompt
string for the keymap.  The prompt string is useful for menu keymaps
Gerd Moellmann's avatar
Gerd Moellmann committed
478
(@pxref{Defining Menus}).
Richard M. Stallman's avatar
Richard M. Stallman committed
479 480
@end defun

481 482 483 484 485
@node Active Keymaps
@section Active Keymaps
@cindex active keymap
@cindex global keymap
@cindex local keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
486

487 488 489 490
  Emacs normally contains many keymaps; at any given time, just a few of
them are @dfn{active} in that they participate in the interpretation
of user input.  These are the global keymap, the current buffer's
local keymap, and the keymaps of any enabled minor modes.
Richard M. Stallman's avatar
Richard M. Stallman committed
491

492 493 494
  The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}.  The variable
@code{global-map} holds this keymap, which is always active.
Richard M. Stallman's avatar
Richard M. Stallman committed
495

496 497 498 499 500
  Each buffer may have another keymap, its @dfn{local keymap}, which may
contain new or overriding definitions for keys.  The current buffer's
local keymap is always active except when @code{overriding-local-map}
overrides it.  Text properties can specify an alternative local map for
certain parts of the buffer; see @ref{Special Properties}.
Richard M. Stallman's avatar
Richard M. Stallman committed
501

502
  Each minor mode can have a keymap; if it does, the keymap is active
503
when the minor mode is enabled.
Richard M. Stallman's avatar
Richard M. Stallman committed
504

505 506 507
  The variable @code{overriding-local-map}, if non-@code{nil}, specifies
another local keymap that overrides the buffer's local map and all the 
minor mode keymaps.
Richard M. Stallman's avatar
Richard M. Stallman committed
508

509 510
  All the active keymaps are used together to determine what command to
execute when a key is entered.  Emacs searches these maps one by one, in
511 512 513
order of decreasing precedence, until it finds a binding in one of the
maps.  The procedure for searching a single keymap is called @dfn{key
lookup}; see @ref{Key Lookup}.
Richard M. Stallman's avatar
Richard M. Stallman committed
514

515 516 517 518 519 520
  Normally, Emacs first searches for the key in the minor mode maps, in
the order specified by @code{minor-mode-map-alist}; if they do not
supply a binding for the key, Emacs searches the local map; if that too
has no binding, Emacs then searches the global map.  However, if
@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
first, before the global map.
Richard M. Stallman's avatar
Richard M. Stallman committed
521

522 523 524 525 526
@cindex major mode keymap
  Since every buffer that uses the same major mode normally uses the
same local keymap, you can think of the keymap as local to the mode.  A
change to the local keymap of a buffer (using @code{local-set-key}, for
example) is seen also in the other buffers that share that keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
527

528 529 530 531 532
  The local keymaps that are used for Lisp mode and some other major
modes exist even if they have not yet been used.  These local maps are
the values of variables such as @code{lisp-mode-map}.  For most major
modes, which are less frequently used, the local keymap is constructed
only when the mode is used for the first time in a session.
Richard M. Stallman's avatar
Richard M. Stallman committed
533

534 535
  The minibuffer has local keymaps, too; they contain various completion
and exit commands.  @xref{Intro to Minibuffers}.
Richard M. Stallman's avatar
Richard M. Stallman committed
536

537 538 539
  Emacs has other keymaps that are used in a different way---translating
events within @code{read-key-sequence}.  @xref{Translating Input}.

540
  @xref{Standard Keymaps}, for a list of standard keymaps.
Richard M. Stallman's avatar
Richard M. Stallman committed
541

542 543 544 545 546
@defvar global-map
This variable contains the default global keymap that maps Emacs
keyboard input to commands.  The global keymap is normally this keymap.
The default global keymap is a full keymap that binds
@code{self-insert-command} to all of the printing characters.
Richard M. Stallman's avatar
Richard M. Stallman committed
547

548 549 550 551
It is normal practice to change the bindings in the global map, but you
should not assign this variable any value other than the keymap it starts
out with.
@end defvar
Richard M. Stallman's avatar
Richard M. Stallman committed
552

553 554 555 556
@defun current-global-map
This function returns the current global keymap.  This is the
same as the value of @code{global-map} unless you change one or the
other.
Richard M. Stallman's avatar
Richard M. Stallman committed
557 558

@example
559 560 561 562 563
@group
(current-global-map)
@result{} (keymap [set-mark-command beginning-of-line @dots{} 
            delete-backward-char])
@end group
Richard M. Stallman's avatar
Richard M. Stallman committed
564
@end example
565
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
566

567 568 569 570
@defun current-local-map
This function returns the current buffer's local keymap, or @code{nil}
if it has none.  In the following example, the keymap for the
@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.
Richard M. Stallman's avatar
Richard M. Stallman committed
573

574 575 576 577 578 579 580 581 582 583 584 585 586 587 588
@example
@group
(current-local-map)
@result{} (keymap 
    (10 . eval-print-last-sexp) 
    (9 . lisp-indent-line) 
    (127 . backward-delete-char-untabify) 
@end group
@group
    (27 keymap 
        (24 . eval-defun) 
        (17 . indent-sexp)))
@end group
@end example
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
589

590 591 592
@defun current-minor-mode-maps
This function returns a list of the keymaps of currently enabled minor modes.
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
593

594 595 596
@defun use-global-map keymap
This function makes @var{keymap} the new current global keymap.  It
returns @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
597

598 599
It is very unusual to change the global keymap.
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
600

601 602 603 604 605 606
@defun use-local-map keymap
This function makes @var{keymap} the new local keymap of the current
buffer.  If @var{keymap} is @code{nil}, then the buffer has no local
keymap.  @code{use-local-map} returns @code{nil}.  Most major mode
commands use this function.
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
607

608 609 610 611 612
@c Emacs 19 feature
@defvar minor-mode-map-alist
This variable is an alist describing keymaps that may or may not be
active according to the values of certain variables.  Its elements look
like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
613

614 615 616
@example
(@var{variable} . @var{keymap})
@end example
Richard M. Stallman's avatar
Richard M. Stallman committed
617

618 619 620
The keymap @var{keymap} is active whenever @var{variable} has a
non-@code{nil} value.  Typically @var{variable} is the variable that
enables or disables a minor mode.  @xref{Keymaps and Minor Modes}.
Richard M. Stallman's avatar
Richard M. Stallman committed
621

622 623
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}.  The map must be the
Phillip Rulon's avatar
Phillip Rulon committed
624 625 626
@sc{cdr} of the element; a list with the map as the second element will
not do.  The @sc{cdr} can be either a keymap (a list) or a symbol whose
function definition is a keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
627

628 629 630 631
When more than one minor mode keymap is active, their order of priority
is the order of @code{minor-mode-map-alist}.  But you should design
minor modes so that they don't interfere with each other.  If you do
this properly, the order will not matter.
Richard M. Stallman's avatar
Richard M. Stallman committed
632

633 634 635 636 637 638 639 640 641
See @ref{Keymaps and Minor Modes}, for more information about minor
modes.  See also @code{minor-mode-key-binding} (@pxref{Functions for Key
Lookup}).
@end defvar

@defvar minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for
particular minor modes.  The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
642 643
. @var{keymap})}.

644
If a variable appears as an element of
645 646 647
@code{minor-mode-overriding-map-alist}, the map specified by that
element totally replaces any map specified for the same variable in
@code{minor-mode-map-alist}.
648

649 650
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
651
@end defvar
Richard M. Stallman's avatar
Richard M. Stallman committed
652

653 654 655 656 657
@defvar overriding-local-map
If non-@code{nil}, this variable holds a keymap to use instead of the
buffer's local keymap and instead of all the minor mode keymaps.  This
keymap, if any, overrides all other maps that would have been active,
except for the current global map.
Richard M. Stallman's avatar
Richard M. Stallman committed
658 659
@end defvar

660 661 662 663 664 665 666 667 668 669
@defvar overriding-terminal-local-map
If non-@code{nil}, this variable holds a keymap to use instead of
@code{overriding-local-map}, the buffer's local keymap and all the minor
mode keymaps.

This variable is always local to the current terminal and cannot be
buffer-local.  @xref{Multiple Displays}.  It is used to implement
incremental search mode.
@end defvar

670 671 672 673 674 675 676 677 678 679 680 681 682 683 684
@defvar overriding-local-map-menu-flag
If this variable is non-@code{nil}, the value of
@code{overriding-local-map} or @code{overriding-terminal-local-map} can
affect the display of the menu bar.  The default value is @code{nil}, so
those map variables have no effect on the menu bar.

Note that these two map variables do affect the execution of key
sequences entered using the menu bar, even if they do not affect the
menu bar display.  So if a menu bar key sequence comes in, you should
clear the variables before looking up and executing that key sequence.
Modes that use the variables would typically do this anyway; normally
they respond to events that they do not handle by ``unreading'' them and
exiting.
@end defvar

685 686 687 688 689 690
@defvar special-event-map
This variable holds a keymap for special events.  If an event type has a
binding in this keymap, then it is special, and the binding for the
event is run directly by @code{read-event}.  @xref{Special Events}.
@end defvar

691 692 693 694
@node Key Lookup
@section Key Lookup
@cindex key lookup
@cindex keymap entry
Richard M. Stallman's avatar
Richard M. Stallman committed
695

696 697 698
  @dfn{Key lookup} is the process of finding the binding of a key
sequence from a given keymap.  Actual execution of the binding is not
part of key lookup.
Richard M. Stallman's avatar
Richard M. Stallman committed
699

700 701 702 703 704 705
  Key lookup uses just the event type of each event in the key sequence;
the rest of the event is ignored.  In fact, a key sequence used for key
lookup may designate mouse events with just their types (symbols)
instead of with entire mouse events (lists).  @xref{Input Events}.  Such
a ``key-sequence'' is insufficient for @code{command-execute} to run,
but it is sufficient for looking up or rebinding a key.
Richard M. Stallman's avatar
Richard M. Stallman committed
706

707 708 709 710 711 712 713 714 715
  When the key sequence consists of multiple events, key lookup
processes the events sequentially: the binding of the first event is
found, and must be a keymap; then the second event's binding is found in
that keymap, and so on until all the events in the key sequence are used
up.  (The binding thus found for the last event may or may not be a
keymap.)  Thus, the process of key lookup is defined in terms of a
simpler process for looking up a single event in a keymap.  How that is
done depends on the type of object associated with the event in that
keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
716

717 718
  Let's use the term @dfn{keymap entry} to describe the value found by
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 721
@code{lookup-key} and other key lookup functions don't include them in
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:
Richard M. Stallman's avatar
Richard M. Stallman committed
724

725 726 727 728 729 730 731
@table @asis
@item @code{nil}
@cindex @code{nil} in keymap
@code{nil} means that the events used so far in the lookup form an
undefined key.  When a keymap fails to mention an event type at all, and
has no default binding, that is equivalent to a binding of @code{nil}
for that event type.
Richard M. Stallman's avatar
Richard M. Stallman committed
732

733 734 735 736
@item @var{command}
@cindex command in keymap
The events used so far in the lookup form a complete key,
and @var{command} is its binding.  @xref{What Is a Function}.
Richard M. Stallman's avatar
Richard M. Stallman committed
737

Karl Heuer's avatar
Karl Heuer committed
738
@item @var{array}
739
@cindex string in keymap
Karl Heuer's avatar
Karl Heuer committed
740 741 742
The array (either a string or a vector) is a keyboard macro.  The events
used so far in the lookup form a complete key, and the array is its
binding.  See @ref{Keyboard Macros}, for more information.
Richard M. Stallman's avatar
Richard M. Stallman committed
743

744 745 746 747 748
@item @var{keymap}
@cindex keymap in keymap
The events used so far in the lookup form a prefix key.  The next
event of the key sequence is looked up in @var{keymap}.

749 750 751
@item @var{list}
@cindex list in keymap
The meaning of a list depends on the types of the elements of the list.
Richard M. Stallman's avatar
Richard M. Stallman committed
752

753 754 755 756
@itemize @bullet
@item
If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list
is a keymap, and is treated as a keymap (see above).
Richard M. Stallman's avatar
Richard M. Stallman committed
757

758 759 760 761 762
@item
@cindex @code{lambda} in keymap
If the @sc{car} of @var{list} is @code{lambda}, then the list is a
lambda expression.  This is presumed to be a command, and is treated as
such (see above).
Richard M. Stallman's avatar
Richard M. Stallman committed
763

764 765 766
@item
If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
type, then this is an @dfn{indirect entry}:
Richard M. Stallman's avatar
Richard M. Stallman committed
767 768

@example
769
(@var{othermap} . @var{othertype})
Richard M. Stallman's avatar
Richard M. Stallman committed
770 771
@end example

772 773
When key lookup encounters an indirect entry, it looks up instead the
binding of @var{othertype} in @var{othermap} and uses that.
Richard M. Stallman's avatar
Richard M. Stallman committed
774

775 776
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
Karl Heuer's avatar
Karl Heuer committed
777
and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
778 779
binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
@end itemize
Richard M. Stallman's avatar
Richard M. Stallman committed
780

781 782 783 784 785
@item @var{symbol}
@cindex symbol in keymap
The function definition of @var{symbol} is used in place of
@var{symbol}.  If that too is a symbol, then this process is repeated,
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 788
keymap or a command, but indirect entries are not understood when found
via symbols.
Richard M. Stallman's avatar
Richard M. Stallman committed
789

790 791 792 793 794 795
Note that keymaps and keyboard macros (strings and vectors) are not
valid functions, so a symbol with a keymap, string, or vector as its
function definition is invalid as a function.  It is, however, valid as
a key binding.  If the definition is a keyboard macro, then the symbol
is also valid as an argument to @code{command-execute}
(@pxref{Interactive Call}).
Richard M. Stallman's avatar
Richard M. Stallman committed
796

797 798 799 800 801 802
@cindex @code{undefined} in keymap
The symbol @code{undefined} is worth special mention: it means to treat
the key as undefined.  Strictly speaking, the key is defined, and its
binding is the command @code{undefined}; but that command does the same
thing that is done automatically for an undefined key: it rings the bell
(by calling @code{ding}) but does not signal an error.
Richard M. Stallman's avatar
Richard M. Stallman committed
803

804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822
@cindex preventing prefix key
@code{undefined} is used in local keymaps to override a global key
binding and make the key ``undefined'' locally.  A local binding of
@code{nil} would fail to do this because it would not override the
global binding.

@item @var{anything else}
If any other type of object is found, the events used so far in the
lookup form a complete key, and the object is its binding, but the
binding is not executable as a command.
@end table

  In short, a keymap entry may be a keymap, a command, a keyboard macro,
a symbol that leads to one of them, or an indirection or @code{nil}.
Here is an example of a sparse keymap with two characters bound to
commands and one bound to another keymap.  This map is the normal value
of @code{emacs-lisp-mode-map}.  Note that 9 is the code for @key{TAB},
127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
@kbd{C-x}.
Richard M. Stallman's avatar
Richard M. Stallman committed
823 824

@example
825 826 827 828 829
@group
(keymap (9 . lisp-indent-line)
        (127 . backward-delete-char-untabify)
        (27 keymap (17 . indent-sexp) (24 . eval-defun)))
@end group
Richard M. Stallman's avatar
Richard M. Stallman committed
830 831
@end example

832 833
@node Functions for Key Lookup
@section Functions for Key Lookup
Richard M. Stallman's avatar
Richard M. Stallman committed
834

835
  Here are the functions and variables pertaining to key lookup.
Richard M. Stallman's avatar
Richard M. Stallman committed
836

837
@defun lookup-key keymap key &optional accept-defaults
838 839 840
This function returns the definition of @var{key} in @var{keymap}.  All
the other functions described in this chapter that look up keys use
@code{lookup-key}.  Here are examples:
Richard M. Stallman's avatar
Richard M. Stallman committed
841

842 843 844 845 846 847 848 849 850 851
@example
@group
(lookup-key (current-global-map) "\C-x\C-f")
    @result{} find-file
@end group
@group
(lookup-key (current-global-map) "\C-x\C-f12345")
    @result{} 2
@end group
@end example
Richard M. Stallman's avatar
Richard M. Stallman committed
852

853 854 855 856 857 858 859 860 861 862 863 864 865 866 867
If the string or vector @var{key} is not a valid key sequence according
to the prefix keys specified in @var{keymap}, it must be ``too long''
and have extra events at the end that do not fit into a single key
sequence.  Then the value is a number, the number of events at the front
of @var{key} that compose a complete key.

@c Emacs 19 feature
If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
considers default bindings as well as bindings for the specific events
in @var{key}.  Otherwise, @code{lookup-key} reports only bindings for
the specific sequence @var{key}, ignoring default bindings except when
you explicitly ask about them.  (To do this, supply @code{t} as an
element of @var{key}; see @ref{Format of Keymaps}.)

If @var{key} contains a meta character, that character is implicitly
868 869 870 871
replaced by a two-character sequence: the value of
@code{meta-prefix-char}, followed by the corresponding non-meta
character.  Thus, the first example below is handled by conversion into
the second example.
Richard M. Stallman's avatar
Richard M. Stallman committed
872 873 874

@example
@group
875 876 877 878 879 880
(lookup-key (current-global-map) "\M-f")
    @result{} forward-word
@end group
@group
(lookup-key (current-global-map) "\ef")
    @result{} forward-word
Richard M. Stallman's avatar
Richard M. Stallman committed
881 882
@end group
@end example
883 884 885 886 887

Unlike @code{read-key-sequence}, this function does not modify the
specified events in ways that discard information (@pxref{Key Sequence
Input}).  In particular, it does not convert letters to lower case and
it does not change drag events to clicks.
Richard M. Stallman's avatar
Richard M. Stallman committed
888 889
@end defun

890 891 892 893 894 895 896 897 898 899 900 901 902 903 904
@deffn Command undefined
Used in keymaps to undefine keys.  It calls @code{ding}, but does
not cause an error.
@end deffn

@defun key-binding key &optional accept-defaults
This function returns the binding for @var{key} in the current
keymaps, trying all the active keymaps.  The result is @code{nil} if
@var{key} is undefined in the keymaps.

@c Emacs 19 feature
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).

An error is signaled if @var{key} is not a string or a vector.
Richard M. Stallman's avatar
Richard M. Stallman committed
905 906 907

@example
@group
908 909
(key-binding "\C-x\C-f")
    @result{} find-file
Richard M. Stallman's avatar
Richard M. Stallman committed
910 911 912 913
@end group
@end example
@end defun

914 915 916
@defun local-key-binding key &optional accept-defaults
This function returns the binding for @var{key} in the current
local keymap, or @code{nil} if it is undefined there.
Richard M. Stallman's avatar
Richard M. Stallman committed
917

918 919 920
@c Emacs 19 feature
The argument @var{accept-defaults} controls checking for default bindings,
as in @code{lookup-key} (above).
Richard M. Stallman's avatar
Richard M. Stallman committed
921 922
@end defun

923 924 925
@defun global-key-binding key &optional accept-defaults
This function returns the binding for command @var{key} in the
current global keymap, or @code{nil} if it is undefined there.
Richard M. Stallman's avatar
Richard M. Stallman committed
926 927

@c Emacs 19 feature
928 929 930
The argument @var{accept-defaults} controls checking for default bindings,
as in @code{lookup-key} (above).
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
931

932 933 934 935 936 937 938 939
@c Emacs 19 feature
@defun minor-mode-key-binding key &optional accept-defaults
This function returns a list of all the active minor mode bindings of
@var{key}.  More precisely, it returns an alist of pairs
@code{(@var{modename} . @var{binding})}, where @var{modename} is the
variable that enables the minor mode, and @var{binding} is @var{key}'s
binding in that mode.  If @var{key} has no minor-mode bindings, the
value is @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
940

941 942 943 944
If the first binding found is not a prefix definition (a keymap or a
symbol defined as a keymap), all subsequent bindings from other minor
modes are omitted, since they would be completely shadowed.  Similarly,
the list omits non-prefix bindings that follow prefix bindings.
Richard M. Stallman's avatar
Richard M. Stallman committed
945

946 947 948
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
949

950 951 952 953 954 955
@defvar meta-prefix-char
@cindex @key{ESC}
This variable is the meta-prefix character code.  It is used when
translating a meta character to a two-character sequence so it can be
looked up in a keymap.  For useful results, the value should be a prefix
event (@pxref{Prefix Keys}).  The default value is 27, which is the
956
@sc{ascii} code for @key{ESC}.
Richard M. Stallman's avatar
Richard M. Stallman committed
957

958 959 960 961 962
As long as the value of @code{meta-prefix-char} remains 27, key
lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
defined as the @code{backward-word} command.  However, if you set
@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
963
@code{switch-to-buffer} command.  Here is an illustration:
Richard M. Stallman's avatar
Richard M. Stallman committed
964

965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985
@smallexample
@group
meta-prefix-char                    ; @r{The default value.}
     @result{} 27
@end group
@group
(key-binding "\M-b")
     @result{} backward-word
@end group
@group
?\C-x                               ; @r{The print representation}
     @result{} 24                          ;   @r{of a character.}
@end group
@group
(setq meta-prefix-char 24)
     @result{} 24      
@end group
@group
(key-binding "\M-b")
     @result{} switch-to-buffer            ; @r{Now, typing @kbd{M-b} is}
                                    ;   @r{like typing @kbd{C-x b}.}
Richard M. Stallman's avatar
Richard M. Stallman committed
986

987 988 989 990
(setq meta-prefix-char 27)          ; @r{Avoid confusion!}
     @result{} 27                          ; @r{Restore the default value!}
@end group
@end smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
991 992
@end defvar

993 994 995 996
@node Changing Key Bindings
@section Changing Key Bindings
@cindex changing key bindings
@cindex rebinding
Richard M. Stallman's avatar
Richard M. Stallman committed
997

998 999 1000 1001 1002 1003 1004 1005 1006
  The way to rebind a key is to change its entry in a keymap.  If you
change a binding in the global keymap, the change is effective in all
buffers (though it has no direct effect in buffers that shadow the
global binding with a local one).  If you change the current buffer's
local map, that usually affects all buffers using the same major mode.
The @code{global-set-key} and @code{local-set-key} functions are
convenient interfaces for these operations (@pxref{Key Binding
Commands}).  You can also use @code{define-key}, a more general
function; then you must specify explicitly the map to change.
Richard M. Stallman's avatar
Richard M. Stallman committed
1007

1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019
@cindex meta character key constants
@cindex control character key constants
  In writing the key sequence to rebind, it is good to use the special
escape sequences for control and meta characters (@pxref{String Type}).
The syntax @samp{\C-} means that the following character is a control
character and @samp{\M-} means that the following character is a meta
character.  Thus, the string @code{"\M-x"} is read as containing a
single @kbd{M-x}, @code{"\C-f"} is read as containing a single
@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as
containing a single @kbd{C-M-x}.  You can also use this escape syntax in
vectors, as well as others that aren't allowed in strings; one example
is @samp{[?\C-\H-x home]}.  @xref{Character Type}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1020

Karl Heuer's avatar
Karl Heuer committed
1021 1022 1023 1024 1025
  The key definition and lookup functions accept an alternate syntax for
event types in a key sequence that is a vector: you can use a list
containing modifier names plus one base event (a character or function
key name).  For example, @code{(control ?a)} is equivalent to
@code{?\C-a} and @code{(hyper control left)} is equivalent to
1026 1027
@code{C-H-left}.  One advantage of such lists is that the precise
numeric codes for the modifier bits don't appear in compiled files.
Karl Heuer's avatar
Karl Heuer committed
1028

1029 1030 1031 1032
  For the functions below, an error is signaled if @var{keymap} is not a
keymap or if @var{key} is not a string or vector representing a key
sequence.  You can use event types (symbols) as shorthand for events
that are lists.
Richard M. Stallman's avatar
Richard M. Stallman committed
1033

1034 1035 1036 1037 1038 1039 1040
@defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}.  (If
@var{key} is more than one event long, the change is actually made
in another keymap reached from @var{keymap}.)  The argument
@var{binding} can be any Lisp object, but only certain types are
meaningful.  (For a list of meaningful types, see @ref{Key Lookup}.)
The value returned by @code{define-key} is @var{binding}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1041

1042 1043
@cindex invalid prefix key error
@cindex key sequence error
1044 1045 1046 1047
Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
or undefined; otherwise an error is signaled.  If some prefix of
@var{key} is undefined, then @code{define-key} defines it as a prefix
key so that the rest of @var{key} can be defined as specified.
1048 1049 1050 1051 1052

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}).
1053
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
1054

1055 1056
  Here is an example that creates a sparse keymap and makes a number of
bindings in it:
Richard M. Stallman's avatar
Richard M. Stallman committed
1057

1058
@smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1059
@group
1060 1061
(setq map (make-sparse-keymap))
    @result{} (keymap)
Richard M. Stallman's avatar
Richard M. Stallman committed
1062 1063
@end group
@group
1064 1065
(define-key map "\C-f" 'forward-char)
    @result{} forward-char
Richard M. Stallman's avatar
Richard M. Stallman committed
1066 1067
@end group
@group
1068 1069
map
    @result{} (keymap (6 . forward-char))
Richard M. Stallman's avatar
Richard M. Stallman committed
1070 1071 1072
@end group

@group
1073 1074
;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
(define-key map "\C-xf" 'forward-word)
Richard M. Stallman's avatar
Richard M. Stallman committed
1075 1076 1077
    @result{} forward-word
@end group
@group
1078 1079 1080 1081 1082
map
@result{} (keymap 
    (24 keymap                ; @kbd{C-x}
        (102 . forward-word)) ;      @kbd{f}
    (6 . forward-char))       ; @kbd{C-f}
Richard M. Stallman's avatar
Richard M. Stallman committed
1083 1084
@end group

1085 1086 1087 1088 1089 1090
@group
;; @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] 
@end group
Richard M. Stallman's avatar
Richard M. Stallman committed
1091 1092

@group
1093 1094 1095
;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
(define-key map "\C-p\C-f" 'foo)
@result{} 'foo
Richard M. Stallman's avatar
Richard M. Stallman committed
1096
@end group
1097 1098 1099 1100 1101 1102 1103 1104 1105
@group
map
@result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
    (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
    (24 keymap 
        (102 . forward-word))
    (6 . forward-char))
@end group
@end smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1106

1107 1108 1109 1110 1111
@noindent
Note that storing a new binding for @kbd{C-p C-f} actually works by
changing an entry in @code{ctl-x-map}, and this has the effect of
changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
default global map.
Richard M. Stallman's avatar
Richard M. Stallman committed
1112

1113 1114 1115 1116 1117 1118
@defun substitute-key-definition olddef newdef keymap &optional oldmap
@cindex replace bindings
This function replaces @var{olddef} with @var{newdef} for any keys in
@var{keymap} that were bound to @var{olddef}.  In other words,
@var{olddef} is replaced with @var{newdef} wherever it appears.  The
function returns @code{nil}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1119

1120 1121
For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with
standard bindings:
Richard M. Stallman's avatar
Richard M. Stallman committed
1122

1123 1124 1125 1126 1127 1128
@smallexample
@group
(substitute-key-definition 
 'find-file 'find-file-read-only (current-global-map))
@end group
@end smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1129 1130

@c Emacs 19 feature
Gerd Moellmann's avatar
Gerd Moellmann committed
1131 1132 1133 1134
If @var{oldmap} is non-@code{nil}, that changes the behavior of
@code{substitute-key-definition}: the bindings in @var{oldmap} determine
which keys to rebind.  The rebindings still happen in @var{keymap}, not
in @var{oldmap}.  Thus, you can change one map under the control of the
1135
bindings in another.  For example,
Richard M. Stallman's avatar
Richard M. Stallman committed
1136

1137 1138 1139 1140 1141
@smallexample
(substitute-key-definition
  'delete-backward-char 'my-funny-delete
  my-map global-map)
@end smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1142

1143 1144 1145
@noindent
puts the special deletion command in @code{my-map} for whichever keys
are globally bound to the standard deletion command.
Richard M. Stallman's avatar
Richard M. Stallman committed
1146

1147 1148 1149 1150 1151 1152
@ignore
@c Emacs 18 only
Prefix keymaps that appear within @var{keymap} are not checked
recursively for keys bound to @var{olddef}; they are not changed at all.
Perhaps it would be better to check nested keymaps recursively.
@end ignore
Richard M. Stallman's avatar
Richard M. Stallman committed
1153

1154
Here is an example showing a keymap before and after substitution:
Richard M. Stallman's avatar
Richard M. Stallman committed
1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208

@smallexample
@group
(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

@group
(substitute-key-definition 'olddef-1 'newdef map)
@result{} nil
@end group
@group
map
@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
@end group
@end smallexample
@end defun

@defun suppress-keymap keymap &optional nodigits
@cindex @code{self-insert-command} override
This function changes the contents of the full keymap @var{keymap} by
making all the printing characters undefined.  More precisely, it binds
them to the command @code{undefined}.  This makes ordinary insertion of
text impossible.  @code{suppress-keymap} returns @code{nil}.

If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
digits to run @code{digit-argument}, and @kbd{-} to run
@code{negative-argument}.  Otherwise it makes them undefined like the
rest of the printing characters.

@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
it read-only (@pxref{Read Only Buffers}).

Since this function modifies @var{keymap}, you would normally use it
on a newly created keymap.  Operating on an existing keymap
that is used for some other purpose is likely to cause trouble; for
example, suppressing @code{global-map} would make it impossible to use
most of Emacs.

Most often, @code{suppress-keymap} is used to initialize local
keymaps of modes such as Rmail and Dired where insertion of text is not
desirable and the buffer is read-only.  Here is an example taken from
the file @file{emacs/lisp/dired.el}, showing how the local keymap for
Dired mode is set up:

@smallexample
@group
1209 1210 1211 1212 1213 1214 1215 1216 1217
(setq dired-mode-map (make-keymap))
(suppress-keymap dired-mode-map)
(define-key dired-mode-map "r" 'dired-rename-file)
(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
(define-key dired-mode-map "d" 'dired-flag-file-deleted)
(define-key dired-mode-map "v" 'dired-view-file)
(define-key dired-mode-map "e" 'dired-find-file)
(define-key dired-mode-map "f" 'dired-find-file)
@dots{}
Richard M. Stallman's avatar
Richard M. Stallman committed
1218 1219 1220 1221 1222 1223 1224 1225 1226 1227
@end group
@end smallexample
@end defun

@node Key Binding Commands
@section Commands for Binding Keys

  This section describes some convenient interactive interfaces for
changing key bindings.  They work by calling @code{define-key}.

Phillip Rulon's avatar
Phillip Rulon committed
1228 1229
  People often use @code{global-set-key} in their init files
(@pxref{Init File}) for simple customization.  For example,
1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241

@smallexample
(global-set-key "\C-x\C-\\" 'next-line)
@end smallexample

@noindent
or

@smallexample
(global-set-key [?\C-x ?\C-\\] 'next-line)
@end smallexample

Karl Heuer's avatar
Karl Heuer committed
1242 1243 1244 1245 1246 1247 1248
@noindent
or

@smallexample
(global-set-key [(control ?x) (control ?\\)] 'next-line)
@end smallexample

1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259
@noindent
redefines @kbd{C-x C-\} to move down a line.

@smallexample
(global-set-key [M-mouse-1] 'mouse-set-point)
@end smallexample

@noindent
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.

1260
@cindex non-@sc{ascii} text in keybindings
1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288
  Be careful when using non-@sc{ascii} text characters in Lisp
specifications of keys to bind.  If these are read as multibyte text, as
they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
must type the keys as multibyte too.  For instance, if you use this:

@smallexample
(global-set-key "@"o" 'my-function) ; bind o-umlaut
@end smallexample

@noindent
or

@smallexample
(global-set-key ?@"o 'my-function) ; bind o-umlaut
@end smallexample

@noindent
and your language environment is multibyte Latin-1, these commands
actually bind the multibyte character with code 2294, not the unibyte
Latin-1 character with code 246 (@kbd{M-v}).  In order to use this
binding, you need to enter the multibyte Latin-1 character as keyboard
input.  One way to do this is by using an appropriate input method
(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).

  If you want to use a unibyte character in the key binding, you can
construct the key sequence string using @code{multibyte-char-to-unibyte}
or @code{string-make-unibyte} (@pxref{Converting Representations}).

Richard M. Stallman's avatar
Richard M. Stallman committed
1289
@deffn Command global-set-key key definition
1290
This function sets the binding of @var{key} in the current global map
Richard M. Stallman's avatar
Richard M. Stallman committed
1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303
to @var{definition}.

@smallexample
@group
(global-set-key @var{key} @var{definition})
@equiv{}
(define-key (current-global-map) @var{key} @var{definition})
@end group
@end smallexample
@end deffn

@deffn Command global-unset-key key
@cindex unbinding keys
1304
This function removes the binding o