keymaps.texi 90.1 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.
Dave Love's avatar
Dave Love committed
3
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000
4
@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

@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.
31
* Remapping Commands::          Bindings that translate one command to another.
Richard M. Stallman's avatar
Richard M. Stallman committed
32 33
* Key Binding Commands::        Interactive interfaces for redefining keys.
* Scanning Keymaps::            Looking through all keymaps, for printing help.
34
* Menu Keymaps::		Defining a menu as a keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
35 36 37 38 39 40 41 42 43 44 45 46 47 48
@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
49 50
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
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65

  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
66
no more events can be added to it).  If the binding is @code{nil},
Richard M. Stallman's avatar
Richard M. Stallman committed
67 68 69 70 71 72 73 74 75
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
76 77 78 79 80 81 82 83 84 85 86
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
87 88 89 90 91

  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
92
keymaps}, which belong to currently enabled minor modes.  (Not all minor
Richard M. Stallman's avatar
Richard M. Stallman committed
93 94 95 96 97 98 99 100 101 102 103 104 105 106
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.
107 108 109
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.
Richard M. Stallman's avatar
Richard M. Stallman committed
110

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

114 115 116 117 118
@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
119

120
@item (t .@: @var{binding})
Richard M. Stallman's avatar
Richard M. Stallman committed
121
@cindex default key binding
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.

128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145
@item @var{char-table}
If an element of a keymap is a char-table, it counts as holding
bindings for all character events with no modifier bits
(@pxref{modifier bits}): element @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 char-table is called a @dfn{full
keymap}.  Other keymaps are called @dfn{sparse keymaps}.

When a keymap contains a char-table vector, it always defines a
binding for each character without modifiers.  However, if the binding
is @code{nil}, it doesn't constitute a definition.  @code{nil} takes
precedence over a default binding or a binding in the parent keymap.
So in a full keymap, default bindings are not meaningful for
characters without modifiers.  They can still apply to characters with
modifier bits and to non-character events.  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
146

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

@cindex meta characters lookup
157
  Keymaps do not directly record bindings for the meta characters.
Gerd Moellmann's avatar
Gerd Moellmann committed
158 159 160 161 162 163 164 165 166 167
Instead, meta characters are regarded for 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 internally 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}).

  This conversion applies only to characters, not to function keys or
other input events; thus, @kbd{M-@key{end}} has nothing to do with
@kbd{@key{ESC} @key{end}}.
Richard M. Stallman's avatar
Richard M. Stallman committed
168 169 170 171 172 173 174 175

  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
176
@result{}
Richard M. Stallman's avatar
Richard M. Stallman committed
177 178
@end group
@group
179
(keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
180
 ;; @key{TAB}
181
 (9 . lisp-indent-line)
Richard M. Stallman's avatar
Richard M. Stallman committed
182 183 184
@end group
@group
 ;; @key{DEL}
185
 (127 . backward-delete-char-untabify)
Richard M. Stallman's avatar
Richard M. Stallman committed
186 187
@end group
@group
188
 (3 keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
189
    ;; @kbd{C-c C-l}
190
    (12 . run-lisp))
Richard M. Stallman's avatar
Richard M. Stallman committed
191 192
@end group
@group
193
 (27 keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
194
     ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
195
     (17 . indent-sexp)
Richard M. Stallman's avatar
Richard M. Stallman committed
196
     ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
197
     (24 . lisp-send-defun)))
Richard M. Stallman's avatar
Richard M. Stallman committed
198 199 200 201 202
@end group
@end example

@defun keymapp object
This function returns @code{t} if @var{object} is a keymap, @code{nil}
203
otherwise.  More precisely, this function tests for a list whose
204 205
@sc{car} is @code{keymap}, or for a symbol whose function definition
satisfies @code{keymapp}.
Richard M. Stallman's avatar
Richard M. Stallman committed
206 207 208 209 210 211 212

@example
@group
(keymapp '(keymap))
    @result{} t
@end group
@group
213 214 215 216 217
(fset 'foo '(keymap))
(keymapp 'foo)
    @result{} t
@end group
@group
Richard M. Stallman's avatar
Richard M. Stallman committed
218 219 220 221 222 223 224 225 226 227 228 229
(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.

230
@c ??? This should come after make-sparse-keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
231
@defun make-keymap &optional prompt
232 233
This function creates and returns a new full keymap.  That keymap
contains a char-table (@pxref{Char-Tables}) with 384 slots: the first
234
128 slots are for defining all the @acronym{ASCII} characters, the next 128
235
slots are for 8-bit European characters, and each one of the final 128
236
slots is for one character set of non-@acronym{ASCII} characters supported by
237 238
Emacs.  The new keymap initially binds all these characters to
@code{nil}, and does not bind any other kind of event.
Richard M. Stallman's avatar
Richard M. Stallman committed
239 240 241 242 243 244 245 246 247

@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
Dave Love's avatar
Dave Love committed
248
the keymap.  The prompt string should be provided for menu keymaps
Gerd Moellmann's avatar
Gerd Moellmann committed
249
(@pxref{Defining Menus}).
Richard M. Stallman's avatar
Richard M. Stallman committed
250 251 252 253
@end defun

@defun make-sparse-keymap &optional prompt
This function creates and returns a new sparse keymap with no entries.
254 255 256
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}.
Richard M. Stallman's avatar
Richard M. Stallman committed
257 258 259 260 261 262 263 264 265 266

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

@defun copy-keymap keymap
267
This function returns a copy of @var{keymap}.  Any keymaps that
Richard M. Stallman's avatar
Richard M. Stallman committed
268 269 270 271 272 273 274 275 276 277 278 279 280
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.)}
281
     (27 keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
         (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

303 304
  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
305 306

@example
307
(keymap @var{bindings}@dots{} . @var{parent-keymap})
Richard M. Stallman's avatar
Richard M. Stallman committed
308 309 310 311
@end example

@noindent
The effect is that this keymap inherits all the bindings of
312
@var{parent-keymap}, whatever they may be at the time a key is looked up,
Richard M. Stallman's avatar
Richard M. Stallman committed
313 314
but can add to them or override them with @var{bindings}.

315
If you change the bindings in @var{parent-keymap} using @code{define-key}
Richard M. Stallman's avatar
Richard M. Stallman committed
316 317 318
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,
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339
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
340

341
   Here is an example showing how to make a keymap that inherits
Richard M. Stallman's avatar
Richard M. Stallman committed
342 343 344
from @code{text-mode-map}:

@example
345 346 347
(let ((map (make-sparse-keymap)))
  (set-keymap-parent map text-mode-map)
  map)
Richard M. Stallman's avatar
Richard M. Stallman committed
348 349
@end example

350 351 352 353 354 355
  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.

Richard M. Stallman's avatar
Richard M. Stallman committed
356 357 358 359
@node Prefix Keys
@section Prefix Keys
@cindex prefix key

360
  A @dfn{prefix key} is a key sequence whose binding is a keymap.  The
361
keymap defines what to do with key sequences that extend the prefix key.
362 363 364 365
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}.

366 367
  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
368 369 370 371 372

@itemize @bullet
@item
@vindex esc-map
@findex ESC-prefix
373 374 375
@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
376 377 378

@item
@cindex @kbd{C-h}
379
@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
Richard M. Stallman's avatar
Richard M. Stallman committed
380 381 382 383

@item
@cindex @kbd{C-c}
@vindex mode-specific-map
384 385 386 387 388
@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
389 390 391 392 393

@item
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
394 395
@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
396
@code{Control-X-prefix}.
Richard M. Stallman's avatar
Richard M. Stallman committed
397

398 399 400 401 402 403
@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
404 405 406
@item
@cindex @kbd{C-x 4}
@vindex ctl-x-4-map
407 408
@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
409 410 411 412 413

@c Emacs 19 feature
@item
@cindex @kbd{C-x 5}
@vindex ctl-x-5-map
414 415
@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
416 417 418

@c Emacs 19 feature
@item
419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440
@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
441 442
@end itemize

443 444 445 446
  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
447
symbol @code{Control-X-prefix}, whose function cell holds the keymap
448
for @kbd{C-x} commands.  (The same keymap is also the value of
Richard M. Stallman's avatar
Richard M. Stallman committed
449 450
@code{ctl-x-map}.)

451 452 453
  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
454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488
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

489
@defun define-prefix-command symbol &optional mapvar prompt
Richard M. Stallman's avatar
Richard M. Stallman committed
490
@cindex prefix command
491
This function prepares @var{symbol} for use as a prefix key's binding:
Gerd Moellmann's avatar
Gerd Moellmann committed
492
it creates a sparse keymap and stores it as @var{symbol}'s function
493
definition.  Subsequently binding a key sequence to @var{symbol} will
494
make that key sequence into a prefix key.  The return value is @code{symbol}.
495 496

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

500
If @var{prompt} is non-@code{nil}, that becomes the overall prompt
Dave Love's avatar
Dave Love committed
501
string for the keymap.  The prompt string should be given for menu keymaps
Gerd Moellmann's avatar
Gerd Moellmann committed
502
(@pxref{Defining Menus}).
Richard M. Stallman's avatar
Richard M. Stallman committed
503 504
@end defun

505 506 507 508 509
@node Active Keymaps
@section Active Keymaps
@cindex active keymap
@cindex global keymap
@cindex local keymap
Richard M. Stallman's avatar
Richard M. Stallman committed
510

511 512 513 514
  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
515

516 517 518
  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
519

520 521 522 523 524
  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
525

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

529
  The variable @code{overriding-local-map}, if non-@code{nil}, specifies
530
another local keymap that overrides the buffer's local map and all the
531 532
minor mode keymaps.  Modes for emulation can specify additional
active keymaps through the variable @code{emulation-mode-map-alists}.
Richard M. Stallman's avatar
Richard M. Stallman committed
533

534 535
  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
536 537 538
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
539

540 541 542 543 544 545
  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
546

547 548 549 550 551
@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
552

553 554 555 556 557
  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
558

559 560
  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
561

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

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

567 568 569 570 571
@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
572

573 574 575 576
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
577

578 579 580 581
@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
582 583

@example
584 585
@group
(current-global-map)
586
@result{} (keymap [set-mark-command beginning-of-line @dots{}
587 588
            delete-backward-char])
@end group
Richard M. Stallman's avatar
Richard M. Stallman committed
589
@end example
590
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
591

592 593 594 595
@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
596
in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
597
keymap.
Richard M. Stallman's avatar
Richard M. Stallman committed
598

599 600 601
@example
@group
(current-local-map)
602 603 604 605
@result{} (keymap
    (10 . eval-print-last-sexp)
    (9 . lisp-indent-line)
    (127 . backward-delete-char-untabify)
606 607
@end group
@group
608 609
    (27 keymap
        (24 . eval-defun)
610 611 612 613
        (17 . indent-sexp)))
@end group
@end example
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
614

615 616 617
@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
618

619 620 621
@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
622

623 624
It is very unusual to change the global keymap.
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
625

626 627 628 629 630 631
@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
632

633 634 635 636 637
@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
638

639 640 641
@example
(@var{variable} . @var{keymap})
@end example
Richard M. Stallman's avatar
Richard M. Stallman committed
642

643 644 645
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
646

647 648
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
649 650 651
@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
652

653 654 655 656
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
657

658 659 660 661 662 663 664 665 666
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}
667 668
. @var{keymap})}.

669
If a variable appears as an element of
670 671 672
@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}.
673

674 675
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
676
@end defvar
Richard M. Stallman's avatar
Richard M. Stallman committed
677

678 679 680 681 682
@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
683 684
@end defvar

685 686 687 688 689 690 691 692 693 694
@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

695 696 697 698 699 700 701 702 703 704 705 706 707 708 709
@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

710 711 712 713 714 715
@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

716 717 718 719 720 721 722 723 724 725
@defvar emulation-mode-map-alists
This variable holds a list of keymap alists to use for emulations
modes.  It is intended for modes or packages using multiple minor-mode
keymaps.  Each element is a keymap alist which has the same format and
meaning as @code{minor-mode-map-alist}, or a symbol with a variable
binding which is such an alist.  The ``active'' keymaps in each alist
are used before @code{minor-mode-map-alist} and
@code{minor-mode-overriding-map-alist}.
@end defvar

726 727 728 729
@node Key Lookup
@section Key Lookup
@cindex key lookup
@cindex keymap entry
Richard M. Stallman's avatar
Richard M. Stallman committed
730

731 732 733
  @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
734

735 736 737 738 739 740
  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
741

742 743 744 745 746 747 748 749 750
  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
751

752 753
  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
754
string and other extra elements in menu key bindings, because
755 756
@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
757
a keymap entry, not all make sense for key lookup.  Here is a table of
758
the meaningful kinds of keymap entries:
Richard M. Stallman's avatar
Richard M. Stallman committed
759

760 761 762 763 764 765 766
@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
767

768 769 770 771
@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
772

Karl Heuer's avatar
Karl Heuer committed
773
@item @var{array}
774
@cindex string in keymap
Karl Heuer's avatar
Karl Heuer committed
775 776 777
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
778

779 780 781 782 783
@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}.

784 785 786
@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
787

788 789 790 791
@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
792

793 794 795 796 797
@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
798

799 800 801
@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
802 803

@example
804
(@var{othermap} . @var{othertype})
Richard M. Stallman's avatar
Richard M. Stallman committed
805 806
@end example

807 808
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
809

810 811
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
812
and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
813 814
binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
@end itemize
Richard M. Stallman's avatar
Richard M. Stallman committed
815

816 817 818 819 820
@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
821
a keymap, a command, or a keyboard macro.  A list is allowed if it is a
822 823
keymap or a command, but indirect entries are not understood when found
via symbols.
Richard M. Stallman's avatar
Richard M. Stallman committed
824

825 826 827 828 829 830
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
831

832 833 834 835 836 837
@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
838

839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857
@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
858 859

@example
860 861 862 863 864
@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
865 866
@end example

867 868
@node Functions for Key Lookup
@section Functions for Key Lookup
Richard M. Stallman's avatar
Richard M. Stallman committed
869

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

872
@defun lookup-key keymap key &optional accept-defaults
873 874 875
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
876

877 878 879 880 881 882 883 884 885 886
@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
887

888 889 890 891 892 893 894 895 896 897 898 899 900 901
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}.)

Gerd Moellmann's avatar
Gerd Moellmann committed
902 903 904
If @var{key} contains a meta character (not a function key), that
character is implicitly replaced by a two-character sequence: the value
of @code{meta-prefix-char}, followed by the corresponding non-meta
905 906
character.  Thus, the first example below is handled by conversion into
the second example.
Richard M. Stallman's avatar
Richard M. Stallman committed
907 908 909

@example
@group
910 911 912 913 914 915
(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
916 917
@end group
@end example
918 919 920 921 922

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
923 924
@end defun

925 926 927 928 929
@deffn Command undefined
Used in keymaps to undefine keys.  It calls @code{ding}, but does
not cause an error.
@end deffn

930
@defun key-binding key &optional accept-defaults no-remap
931 932 933 934 935 936 937 938
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).

939 940 941 942 943 944
When commands are remapped (@pxref{Remapping Commands}),
@code{key-binding} normally processes command remappings so as to
returns the remapped command that will actually be executed.  However,
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.

945
An error is signaled if @var{key} is not a string or a vector.
Richard M. Stallman's avatar
Richard M. Stallman committed
946 947 948

@example
@group
949 950
(key-binding "\C-x\C-f")
    @result{} find-file
Richard M. Stallman's avatar
Richard M. Stallman committed
951 952 953 954
@end group
@end example
@end defun

955 956 957 958 959
@defun current-active-maps
This returns the list of keymaps that would be used by the command
loop in the current circumstances to look up a key sequence.
@end defun

960 961 962
@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
963

964 965 966
@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
967 968
@end defun

969 970 971
@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
972 973

@c Emacs 19 feature
974 975 976
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
977

978 979 980 981 982 983 984 985
@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
986

987 988 989 990
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
991

992 993 994
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
995

996 997 998 999 1000 1001
@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
1002
@acronym{ASCII} code for @key{ESC}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1003

Gerd Moellmann's avatar
Gerd Moellmann committed
1004 1005 1006
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 were to set
1007 1008
@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
Gerd Moellmann's avatar
Gerd Moellmann committed
1009 1010
@code{switch-to-buffer} command.  (Don't actually do this!)  Here is an
illustration of what would happen:
Richard M. Stallman's avatar
Richard M. Stallman committed
1011

1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026
@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)
1027
     @result{} 24
1028 1029 1030 1031 1032
@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
1033

1034 1035 1036 1037
(setq meta-prefix-char 27)          ; @r{Avoid confusion!}
     @result{} 27                          ; @r{Restore the default value!}
@end group
@end smallexample
Gerd Moellmann's avatar
Gerd Moellmann committed
1038 1039 1040 1041

This translation of one event into two happens only for characters, not
for other kinds of input events.  Thus, @kbd{M-@key{F1}}, a function
key, is not converted into @kbd{@key{ESC} @key{F1}}.
Richard M. Stallman's avatar
Richard M. Stallman committed
1042 1043
@end defvar

1044 1045 1046 1047
@node Changing Key Bindings
@section Changing Key Bindings
@cindex changing key bindings
@cindex rebinding
Richard M. Stallman's avatar
Richard M. Stallman committed
1048

1049 1050 1051 1052 1053 1054 1055 1056 1057
  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
1058

1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070
@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
1071

Karl Heuer's avatar
Karl Heuer committed
1072 1073 1074 1075 1076
  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
1077 1078
@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
1079

1080 1081 1082 1083
  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
1084

1085 1086 1087 1088 1089 1090 1091
@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
1092

1093 1094 1095 1096
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.

1097 1098
@cindex invalid prefix key error
@cindex key sequence error
1099 1100 1101 1102
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.
1103 1104 1105

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
1106 1107
bindings in a keymap makes no difference for keyboard input, but it
does matter for menu keymaps (@pxref{Menu Keymaps}).
1108
@end defun
Richard M. Stallman's avatar
Richard M. Stallman committed
1109

1110 1111
  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
1112

1113
@smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1114
@group
1115 1116
(setq map (make-sparse-keymap))
    @result{} (keymap)
Richard M. Stallman's avatar
Richard M. Stallman committed
1117 1118
@end group
@group
1119 1120
(define-key map "\C-f" 'forward-char)
    @result{} forward-char
Richard M. Stallman's avatar
Richard M. Stallman committed
1121 1122
@end group
@group
1123 1124
map
    @result{} (keymap (6 . forward-char))
Richard M. Stallman's avatar
Richard M. Stallman committed
1125 1126 1127
@end group

@group
1128 1129
;; @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
1130 1131 1132
    @result{} forward-word
@end group
@group
1133
map
1134
@result{} (keymap
1135 1136 1137
    (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
1138 1139
@end group

1140 1141 1142 1143
@group
;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
(define-key map "\C-p" ctl-x-map)
;; @code{ctl-x-map}
1144
@result{} [nil @dots{} find-file @dots{} backward-kill-sentence]
1145
@end group
Richard M. Stallman's avatar
Richard M. Stallman committed
1146 1147

@group
1148 1149 1150
;; @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
1151
@end group
1152 1153 1154 1155
@group
map
@result{} (keymap     ; @r{Note @code{foo} in @code{ctl-x-map}.}
    (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence])
1156
    (24 keymap
1157 1158 1159 1160
        (102 . forward-word))
    (6 . forward-char))
@end group
@end smallexample
Richard M. Stallman's avatar
Richard M. Stallman committed
1161

1162 1163 1164 1165 1166
@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
1167

1168 1169 1170