428
+ − 1 @c -*-texinfo-*-
+ − 2 @c This is part of the XEmacs Lisp Reference Manual.
444
+ − 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
428
+ − 4 @c Copyright (C) 1996 Ben Wing.
+ − 5 @c See the file lispref.texi for copying conditions.
+ − 6 @setfilename ../../info/keymaps.info
+ − 7 @node Keymaps, Menus, Command Loop, Top
+ − 8 @chapter Keymaps
+ − 9 @cindex keymap
+ − 10
+ − 11 @c This section is largely different from the one in FSF Emacs.
+ − 12
+ − 13 The bindings between input events and commands are recorded in data
+ − 14 structures called @dfn{keymaps}. Each binding in a keymap associates
+ − 15 (or @dfn{binds}) an individual event type either with another keymap or
+ − 16 with a command. When an event is bound to a keymap, that keymap is
+ − 17 used to look up the next input event; this continues until a command
+ − 18 is found. The whole process is called @dfn{key lookup}.
+ − 19
+ − 20 @menu
+ − 21 * Keymap Terminology:: Definitions of terms pertaining to keymaps.
+ − 22 * Format of Keymaps:: What a keymap looks like as a Lisp object.
+ − 23 * Creating Keymaps:: Functions to create and copy keymaps.
+ − 24 * Inheritance and Keymaps:: How one keymap can inherit the bindings
+ − 25 of another keymap.
+ − 26 * Key Sequences:: How to specify key sequences.
+ − 27 * Prefix Keys:: Defining a key with a keymap as its definition.
+ − 28 * Active Keymaps:: Each buffer has a local keymap
+ − 29 to override the standard (global) bindings.
+ − 30 A minor mode can also override them.
+ − 31 * Key Lookup:: How extracting elements from keymaps works.
+ − 32 * Functions for Key Lookup:: How to request key lookup.
+ − 33 * Changing Key Bindings:: Redefining a key in a keymap.
+ − 34 * Key Binding Commands:: Interactive interfaces for redefining keys.
+ − 35 * Scanning Keymaps:: Looking through all keymaps, for printing help.
+ − 36 * Other Keymap Functions:: Miscellaneous keymap functions.
+ − 37 @end menu
+ − 38
+ − 39 @node Keymap Terminology
+ − 40 @section Keymap Terminology
+ − 41 @cindex key
+ − 42 @cindex keystroke
+ − 43 @cindex key binding
+ − 44 @cindex binding of a key
+ − 45 @cindex complete key
+ − 46 @cindex undefined key
+ − 47
+ − 48 A @dfn{keymap} is a table mapping event types to definitions (which
+ − 49 can be any Lisp objects, though only certain types are meaningful for
+ − 50 execution by the command loop). Given an event (or an event type) and a
+ − 51 keymap, XEmacs can get the event's definition. Events mapped in keymaps
+ − 52 include keypresses, button presses, and button releases
+ − 53 (@pxref{Events}).
+ − 54
+ − 55 A sequence of input events that form a unit is called a
+ − 56 @dfn{key sequence}, or @dfn{key} for short. A sequence of one event
+ − 57 is always a key sequence, and so are some multi-event sequences.
+ − 58
+ − 59 A keymap determines a binding or definition for any key sequence. If
+ − 60 the key sequence is a single event, its binding is the definition of the
+ − 61 event in the keymap. The binding of a key sequence of more than one
+ − 62 event is found by an iterative process: the binding of the first event
+ − 63 is found, and must be a keymap; then the second event's binding is found
+ − 64 in that keymap, and so on until all the events in the key sequence are
+ − 65 used up.
+ − 66
+ − 67 If the binding of a key sequence is a keymap, we call the key sequence
+ − 68 a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
+ − 69 no more events can be added to it). If the binding is @code{nil},
+ − 70 we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c},
+ − 71 @kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are
+ − 72 @kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete
+ − 73 keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more
+ − 74 details.
+ − 75
+ − 76 The rule for finding the binding of a key sequence assumes that the
+ − 77 intermediate bindings (found for the events before the last) are all
+ − 78 keymaps; if this is not so, the sequence of events does not form a
+ − 79 unit---it is not really a key sequence. In other words, removing one or
+ − 80 more events from the end of any valid key must always yield a prefix
+ − 81 key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
+ − 82 key, so a longer sequence starting with @kbd{C-f} cannot be a key.
+ − 83
+ − 84 Note that the set of possible multi-event key sequences depends on the
+ − 85 bindings for prefix keys; therefore, it can be different for different
+ − 86 keymaps, and can change when bindings are changed. However, a one-event
+ − 87 sequence is always a key sequence, because it does not depend on any
+ − 88 prefix keys for its well-formedness.
+ − 89
+ − 90 At any time, several primary keymaps are @dfn{active}---that is, in
+ − 91 use for finding key bindings. These are the @dfn{global map}, which is
+ − 92 shared by all buffers; the @dfn{local keymap}, which is usually
+ − 93 associated with a specific major mode; and zero or more @dfn{minor mode
+ − 94 keymaps}, which belong to currently enabled minor modes. (Not all minor
+ − 95 modes have keymaps.) The local keymap bindings shadow (i.e., take
+ − 96 precedence over) the corresponding global bindings. The minor mode
+ − 97 keymaps shadow both local and global keymaps. @xref{Active Keymaps},
+ − 98 for details.
+ − 99
+ − 100 @node Format of Keymaps
+ − 101 @section Format of Keymaps
+ − 102 @cindex format of keymaps
+ − 103 @cindex keymap format
+ − 104
+ − 105 A keymap is a primitive type that associates events with their
+ − 106 bindings. Note that this is different from Emacs 18 and FSF Emacs,
+ − 107 where keymaps are lists.
+ − 108
+ − 109 @defun keymapp object
+ − 110 This function returns @code{t} if @var{object} is a keymap, @code{nil}
+ − 111 otherwise.
+ − 112 @end defun
+ − 113
+ − 114 @node Creating Keymaps
+ − 115 @section Creating Keymaps
+ − 116 @cindex creating keymaps
+ − 117
+ − 118 Here we describe the functions for creating keymaps.
+ − 119
+ − 120 @defun make-keymap &optional name
+ − 121 This function constructs and returns a new keymap object. All entries
+ − 122 in it are @code{nil}, meaning ``command undefined''.
+ − 123
+ − 124 Optional argument @var{name} specifies a name to assign to the keymap,
+ − 125 as in @code{set-keymap-name}. This name is only a debugging
+ − 126 convenience; it is not used except when printing the keymap.
+ − 127 @end defun
+ − 128
+ − 129 @defun make-sparse-keymap &optional name
+ − 130 This function constructs and returns a new keymap object. All entries
+ − 131 in it are @code{nil}, meaning ``command undefined''. The only
+ − 132 difference between this function and @code{make-keymap} is that this
+ − 133 function returns a ``smaller'' keymap (one that is expected to contain
444
+ − 134 fewer entries). As keymaps dynamically resize, this distinction is not
428
+ − 135 great.
+ − 136
+ − 137 Optional argument @var{name} specifies a name to assign to the keymap,
+ − 138 as in @code{set-keymap-name}. This name is only a debugging
+ − 139 convenience; it is not used except when printing the keymap.
+ − 140 @end defun
+ − 141
+ − 142 @defun set-keymap-name keymap new-name
+ − 143 This function assigns a ``name'' to a keymap. The name is only a
+ − 144 debugging convenience; it is not used except when printing the keymap.
+ − 145 @end defun
+ − 146
+ − 147 @defun keymap-name keymap
+ − 148 This function returns the ``name'' of a keymap, as assigned using
+ − 149 @code{set-keymap-name}.
+ − 150 @end defun
+ − 151
+ − 152 @defun copy-keymap keymap
+ − 153 This function returns a copy of @var{keymap}. Any keymaps that
+ − 154 appear directly as bindings in @var{keymap} are also copied recursively,
+ − 155 and so on to any number of levels. However, recursive copying does not
+ − 156 take place when the definition of a character is a symbol whose function
+ − 157 definition is a keymap; the same symbol appears in the new copy.
+ − 158
+ − 159 @example
+ − 160 @group
+ − 161 (setq map (copy-keymap (current-local-map)))
+ − 162 @result{} #<keymap 3 entries 0x21f80>
+ − 163 @end group
+ − 164
+ − 165 @group
+ − 166 (eq map (current-local-map))
+ − 167 @result{} nil
+ − 168 @end group
+ − 169 @ignore @c Doesn't work!
+ − 170 @group
+ − 171 (equal map (current-local-map))
+ − 172 @result{} t
+ − 173 @end group
+ − 174 @end ignore
+ − 175 @end example
+ − 176 @end defun
+ − 177
+ − 178 @node Inheritance and Keymaps
+ − 179 @section Inheritance and Keymaps
+ − 180 @cindex keymap inheritance
+ − 181 @cindex inheriting a keymap's bindings
+ − 182 @cindex keymap parent
+ − 183 @cindex parent of a keymap
+ − 184
+ − 185 A keymap can inherit the bindings of other keymaps. The other
+ − 186 keymaps are called the keymap's @dfn{parents}, and are set with
+ − 187 @code{set-keymap-parents}. When searching for a binding for a key
+ − 188 sequence in a particular keymap, that keymap itself will first be
+ − 189 searched; then, if no binding was found in the map and it has parents,
+ − 190 the first parent keymap will be searched; then that keymap's parent will
+ − 191 be searched, and so on, until either a binding for the key sequence is
+ − 192 found, or a keymap without a parent is encountered. At this point,
+ − 193 the search will continue with the next parent of the most recently
+ − 194 encountered keymap that has another parent, etc. Essentially, a
+ − 195 depth-first search of all the ancestors of the keymap is conducted.
+ − 196
+ − 197 @code{(current-global-map)} is the default parent of all keymaps.
+ − 198
+ − 199 @defun set-keymap-parents keymap parents
+ − 200 This function sets the parent keymaps of @var{keymap} to the list
+ − 201 @var{parents}.
+ − 202
+ − 203 If you change the bindings in one of the keymaps in @var{parents} using
+ − 204 @code{define-key} or other key-binding functions, these changes are
+ − 205 visible in @var{keymap} unless shadowed by bindings in that map or in
+ − 206 earlier-searched ancestors. The converse is not true: if you use
+ − 207 @code{define-key} to change @var{keymap}, that affects the bindings in
+ − 208 that map, but has no effect on any of the keymaps in @var{parents}.
+ − 209 @end defun
+ − 210
+ − 211 @defun keymap-parents keymap
+ − 212 This function returns the list of parent keymaps of @var{keymap}, or
+ − 213 @code{nil} if @var{keymap} has no parents.
+ − 214 @end defun
+ − 215
+ − 216 As an alternative to specifying a parent, you can also specify a
+ − 217 @dfn{default binding} that is used whenever a key is not otherwise bound
+ − 218 in the keymap. This is useful for terminal emulators, for example,
+ − 219 which may want to trap all keystrokes and pass them on in some modified
+ − 220 format. Note that if you specify a default binding for a keymap,
+ − 221 neither the keymap's parents nor the current global map are searched for
+ − 222 key bindings.
+ − 223
+ − 224 @defun set-keymap-default-binding keymap command
+ − 225 This function sets the default binding of @var{keymap} to @var{command},
+ − 226 or @code{nil} if no default is desired.
+ − 227 @end defun
+ − 228
+ − 229 @defun keymap-default-binding keymap
+ − 230 This function returns the default binding of @var{keymap}, or @code{nil}
+ − 231 if it has none.
+ − 232 @end defun
+ − 233
+ − 234 @node Key Sequences
+ − 235 @section Key Sequences
+ − 236 @cindex key sequences
+ − 237
+ − 238 Contrary to popular belief, the world is not @sc{ascii}. When running
+ − 239 under a window manager, XEmacs can tell the difference between, for
+ − 240 example, the keystrokes @kbd{control-h}, @kbd{control-shift-h}, and
+ − 241 @kbd{backspace}. You can, in fact, bind different commands to each of
+ − 242 these.
+ − 243
+ − 244 A @dfn{key sequence} is a set of keystrokes. A @dfn{keystroke} is a
+ − 245 keysym and some set of modifiers (such as @key{CONTROL} and @key{META}).
+ − 246 A @dfn{keysym} is what is printed on the keys on your keyboard.
+ − 247
2828
+ − 248 A keysym may be represented by a symbol, by a character, or by a
+ − 249 character's Mule code. The @kbd{A} key may be represented by the symbol
+ − 250 @code{A}, the character @code{?A}, or by the number 65. The @kbd{break}
+ − 251 key may be represented only by the symbol @code{break}, and non-ASCII
+ − 252 X11 keys in general are limited to the symbol form with XEmacs.
+ − 253 @footnote{A quirk of our X11 implementation means that non-ASCII keysyms
+ − 254 have different internal representations in the X11 (with GTK) and other
+ − 255 worlds (like the TTY, or Microsoft Windows), so, for example, binding
+ − 256 @kbd{EuroSign} to a command will normally work, but will not invoke that
+ − 257 command if someone presses the Euro sign in a TTY console; conversely,
+ − 258 binding @code{(make-char 'latin-iso8859-15 #xa4)} or @code{(char-to-int
+ − 259 (make-char 'latin-iso8859-15 #xa4))} to a command will call that command
+ − 260 on a TTY console, but not in an X11 window of the same process.}
+ − 261 @footnote{See the documentation for `set-input-mode' and
+ − 262 `set-console-tty-coding-system' if you're having trouble inputting
+ − 263 non-ASCII characters in the TTY.}
428
+ − 264
+ − 265 A keystroke may be represented by a list: the last element of the list
+ − 266 is the key (a symbol, character, or number, as above) and the preceding
+ − 267 elements are the symbolic names of modifier keys (@key{CONTROL},
+ − 268 @key{META}, @key{SUPER}, @key{HYPER}, @key{ALT}, and @key{SHIFT}).
+ − 269 Thus, the sequence @kbd{control-b} is represented by the forms
+ − 270 @code{(control b)}, @code{(control ?b)}, and @code{(control 98)}. A
+ − 271 keystroke may also be represented by an event object, as returned by the
+ − 272 @code{next-command-event} and @code{read-key-sequence} functions.
+ − 273
+ − 274 Note that in this context, the keystroke @kbd{control-b} is @emph{not}
+ − 275 represented by the number 2 (the @sc{ascii} code for @samp{^B}) or the
+ − 276 character @code{?\^B}. See below.
+ − 277
+ − 278 The @key{SHIFT} modifier is somewhat of a special case. You should
+ − 279 not (and cannot) use @code{(meta shift a)} to mean @code{(meta A)},
+ − 280 since for characters that have @sc{ascii} equivalents, the state of the
+ − 281 shift key is implicit in the keysym (@samp{a} vs. @samp{A}). You also
+ − 282 cannot say @code{(shift =)} to mean @code{+}, as that sort of thing
+ − 283 varies from keyboard to keyboard. The @key{SHIFT} modifier is for use
+ − 284 only with characters that do not have a second keysym on the same key,
+ − 285 such as @code{backspace} and @code{tab}.
+ − 286
+ − 287 A key sequence is a vector of keystrokes. As a degenerate case,
+ − 288 elements of this vector may also be keysyms if they have no modifiers.
+ − 289 That is, the @kbd{A} keystroke is represented by all of these forms:
+ − 290
+ − 291 @example
440
+ − 292 A ?A 65 (A) (?A) (65)
+ − 293 [A] [?A] [65] [(A)] [(?A)] [(65)]
428
+ − 294 @end example
444
+ − 295
428
+ − 296 the @kbd{control-a} keystroke is represented by these forms:
+ − 297
+ − 298 @example
440
+ − 299 (control A) (control ?A) (control 65)
+ − 300 [(control A)] [(control ?A)] [(control 65)]
428
+ − 301 @end example
+ − 302
+ − 303 the key sequence @kbd{control-c control-a} is represented by these
+ − 304 forms:
+ − 305
+ − 306 @example
440
+ − 307 [(control c) (control a)] [(control ?c) (control ?a)]
+ − 308 [(control 99) (control 65)] etc.
428
+ − 309 @end example
+ − 310
+ − 311 Mouse button clicks work just like keypresses: @code{(control
+ − 312 button1)} means pressing the left mouse button while holding down the
+ − 313 control key. @code{[(control c) (shift button3)]} means
+ − 314 @kbd{control-c}, hold @key{SHIFT}, click right.
+ − 315
+ − 316 Commands may be bound to the mouse-button up-stroke rather than the
+ − 317 down-stroke as well. @code{button1} means the down-stroke, and
+ − 318 @code{button1up} means the up-stroke. Different commands may be bound
+ − 319 to the up and down strokes, though that is probably not what you want,
+ − 320 so be careful.
+ − 321
+ − 322 For backward compatibility, a key sequence may also be represented by
+ − 323 a string. In this case, it represents the key sequence(s) that would
+ − 324 produce that sequence of @sc{ascii} characters in a purely @sc{ascii}
+ − 325 world. For example, a string containing the @sc{ascii} backspace
+ − 326 character, @code{"\^H"}, would represent two key sequences:
+ − 327 @code{(control h)} and @code{backspace}. Binding a command to this will
+ − 328 actually bind both of those key sequences. Likewise for the following
+ − 329 pairs:
+ − 330
+ − 331 @example
440
+ − 332 control h backspace
+ − 333 control i tab
+ − 334 control m return
+ − 335 control j linefeed
+ − 336 control [ escape
+ − 337 control @@ control space
428
+ − 338 @end example
+ − 339
+ − 340 After binding a command to two key sequences with a form like
+ − 341
+ − 342 @example
440
+ − 343 (define-key global-map "\^X\^I" 'command-1)
428
+ − 344 @end example
+ − 345
+ − 346 @noindent
+ − 347 it is possible to redefine only one of those sequences like so:
+ − 348
+ − 349 @example
440
+ − 350 (define-key global-map [(control x) (control i)] 'command-2)
+ − 351 (define-key global-map [(control x) tab] 'command-3)
428
+ − 352 @end example
+ − 353
+ − 354 Of course, all of this applies only when running under a window
+ − 355 system. If you're talking to XEmacs through a @sc{tty} connection, you
+ − 356 don't get any of these features.
+ − 357
+ − 358 @defun event-matches-key-specifier-p event key-specifier
+ − 359 This function returns non-@code{nil} if @var{event} matches
+ − 360 @var{key-specifier}, which can be any valid form representing a key
+ − 361 sequence. This can be useful, e.g., to determine if the user pressed
+ − 362 @code{help-char} or @code{quit-char}.
+ − 363 @end defun
+ − 364
+ − 365 @node Prefix Keys
+ − 366 @section Prefix Keys
+ − 367 @cindex prefix key
+ − 368
+ − 369 A @dfn{prefix key} has an associated keymap that defines what to do
+ − 370 with key sequences that start with the prefix key. For example,
+ − 371 @kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
+ − 372 the variable @code{ctl-x-map}. Here is a list of the standard prefix
+ − 373 keys of XEmacs and their keymaps:
+ − 374
+ − 375 @itemize @bullet
+ − 376 @item
+ − 377 @cindex @kbd{C-h}
+ − 378 @code{help-map} is used for events that follow @kbd{C-h}.
+ − 379
+ − 380 @item
+ − 381 @cindex @kbd{C-c}
+ − 382 @vindex mode-specific-map
+ − 383 @code{mode-specific-map} is for events that follow @kbd{C-c}. This
+ − 384 map is not actually mode specific; its name was chosen to be informative
+ − 385 for the user in @kbd{C-h b} (@code{display-bindings}), where it
+ − 386 describes the main use of the @kbd{C-c} prefix key.
+ − 387
+ − 388 @item
+ − 389 @cindex @kbd{C-x}
+ − 390 @vindex ctl-x-map
+ − 391 @findex Control-X-prefix
+ − 392 @code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
+ − 393 map is also the function definition of @code{Control-X-prefix}.
+ − 394
+ − 395 @item
+ − 396 @cindex @kbd{C-x 4}
+ − 397 @vindex ctl-x-4-map
+ − 398 @code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}.
+ − 399
+ − 400 @c Emacs 19 feature
+ − 401 @item
+ − 402 @cindex @kbd{C-x 5}
+ − 403 @vindex ctl-x-5-map
+ − 404 @code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
+ − 405
+ − 406 @c Emacs 19 feature
+ − 407 @item
+ − 408 @cindex @kbd{C-x n}
+ − 409 @cindex @kbd{C-x r}
+ − 410 @cindex @kbd{C-x a}
+ − 411 The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
+ − 412 that have no special name.
+ − 413
+ − 414 @item
+ − 415 @vindex esc-map
+ − 416 @findex ESC-prefix
+ − 417 @code{esc-map} is an evil hack that is present for compatibility
+ − 418 purposes with Emacs 18. Defining a key in @code{esc-map} is equivalent
+ − 419 to defining the same key in @code{global-map} but with the @key{META}
+ − 420 prefix added. You should @emph{not} use this in your code. (This map is
+ − 421 also the function definition of @code{ESC-prefix}.)
+ − 422 @end itemize
+ − 423
+ − 424 The binding of a prefix key is the keymap to use for looking up the
+ − 425 events that follow the prefix key. (It may instead be a symbol whose
+ − 426 function definition is a keymap. The effect is the same, but the symbol
+ − 427 serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is
+ − 428 the symbol @code{Control-X-prefix}, whose function definition is the
+ − 429 keymap for @kbd{C-x} commands. (The same keymap is also the value of
+ − 430 @code{ctl-x-map}.)
+ − 431
+ − 432 Prefix key definitions can appear in any active keymap. The
+ − 433 definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix
+ − 434 keys appear in the global map, so these prefix keys are always
+ − 435 available. Major and minor modes can redefine a key as a prefix by
+ − 436 putting a prefix key definition for it in the local map or the minor
+ − 437 mode's map. @xref{Active Keymaps}.
+ − 438
+ − 439 If a key is defined as a prefix in more than one active map, then its
+ − 440 various definitions are in effect merged: the commands defined in the
+ − 441 minor mode keymaps come first, followed by those in the local map's
+ − 442 prefix definition, and then by those from the global map.
+ − 443
+ − 444 In the following example, we make @kbd{C-p} a prefix key in the local
+ − 445 keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then
+ − 446 the binding for @kbd{C-p C-f} is the function @code{find-file}, just
+ − 447 like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any
+ − 448 active keymap.
+ − 449
+ − 450 @example
+ − 451 @group
+ − 452 (use-local-map (make-sparse-keymap))
+ − 453 @result{} nil
+ − 454 @end group
+ − 455 @group
+ − 456 (local-set-key "\C-p" ctl-x-map)
+ − 457 @result{} nil
+ − 458 @end group
+ − 459 @group
+ − 460 (key-binding "\C-p\C-f")
+ − 461 @result{} find-file
+ − 462 @end group
+ − 463
+ − 464 @group
+ − 465 (key-binding "\C-p6")
+ − 466 @result{} nil
+ − 467 @end group
+ − 468 @end example
+ − 469
+ − 470 @defun define-prefix-command symbol &optional mapvar
+ − 471 @cindex prefix command
+ − 472 This function defines @var{symbol} as a prefix command: it creates a
+ − 473 keymap and stores it as @var{symbol}'s function definition.
+ − 474 Storing the symbol as the binding of a key makes the key a prefix key
+ − 475 that has a name. If optional argument @var{mapvar} is not specified,
+ − 476 it also sets @var{symbol} as a variable, to have the keymap as its
+ − 477 value. (If @var{mapvar} is given and is not @code{t}, its value is
+ − 478 stored as the value of @var{symbol}.) The function returns @var{symbol}.
+ − 479
+ − 480 In Emacs version 18, only the function definition of @var{symbol} was
+ − 481 set, not the value as a variable.
+ − 482 @end defun
+ − 483
+ − 484 @node Active Keymaps
+ − 485 @section Active Keymaps
+ − 486 @cindex active keymap
+ − 487 @cindex global keymap
+ − 488 @cindex local keymap
+ − 489
+ − 490 XEmacs normally contains many keymaps; at any given time, just a few of
+ − 491 them are @dfn{active} in that they participate in the interpretation
+ − 492 of user input. These are the global keymap, the current buffer's
+ − 493 local keymap, and the keymaps of any enabled minor modes.
+ − 494
+ − 495 The @dfn{global keymap} holds the bindings of keys that are defined
+ − 496 regardless of the current buffer, such as @kbd{C-f}. The variable
+ − 497 @code{global-map} holds this keymap, which is always active.
+ − 498
+ − 499 Each buffer may have another keymap, its @dfn{local keymap}, which may
+ − 500 contain new or overriding definitions for keys. The current buffer's
+ − 501 local keymap is always active except when @code{overriding-local-map} or
+ − 502 @code{overriding-terminal-local-map} overrides it. Extents and text
+ − 503 properties can specify an alternative local map for certain parts of the
+ − 504 buffer; see @ref{Extents and Events}.
+ − 505
+ − 506 Each minor mode may have a keymap; if it does, the keymap is active
+ − 507 when the minor mode is enabled.
+ − 508
+ − 509 The variable @code{overriding-local-map} and
+ − 510 @code{overriding-terminal-local-map}, if non-@code{nil}, specify other
+ − 511 local keymaps that override the buffer's local map and all the minor
+ − 512 mode keymaps.
+ − 513
+ − 514 All the active keymaps are used together to determine what command to
+ − 515 execute when a key is entered. XEmacs searches these maps one by one, in
+ − 516 order of decreasing precedence, until it finds a binding in one of the maps.
+ − 517
+ − 518 More specifically:
+ − 519
+ − 520 For key-presses, the order of keymaps searched is:
+ − 521
+ − 522 @itemize @bullet
+ − 523 @item
+ − 524 the @code{keymap} property of any extent(s) or text properties at point;
+ − 525 @item
+ − 526 any applicable minor-mode maps;
+ − 527 @item
+ − 528 the current local map of the current buffer;
+ − 529 @item
+ − 530 the current global map.
+ − 531 @end itemize
+ − 532
+ − 533 For mouse-clicks, the order of keymaps searched is:
+ − 534
+ − 535 @itemize @bullet
+ − 536 @item
+ − 537 the current local map of the @code{mouse-grabbed-buffer} if any;
+ − 538 @item
+ − 539 the @code{keymap} property of any extent(s) at the position of the click
+ − 540 (this includes modeline extents);
+ − 541 @item
+ − 542 the @code{modeline-map} of the buffer corresponding to the modeline
+ − 543 under the mouse (if the click happened over a modeline);
+ − 544 @item
+ − 545 the value of @code{toolbar-map} in the current buffer (if the click
+ − 546 happened over a toolbar);
+ − 547 @item
+ − 548 the current local map of the buffer under the mouse (does not
+ − 549 apply to toolbar clicks);
+ − 550 @item
+ − 551 any applicable minor-mode maps;
+ − 552 @item
+ − 553 the current global map.
+ − 554 @end itemize
+ − 555
+ − 556 Note that if @code{overriding-local-map} or
+ − 557 @code{overriding-terminal-local-map} is non-@code{nil}, @emph{only}
+ − 558 those two maps and the current global map are searched.
+ − 559
+ − 560 The procedure for searching a single keymap is called
+ − 561 @dfn{key lookup}; see @ref{Key Lookup}.
+ − 562
+ − 563 @cindex major mode keymap
+ − 564 Since every buffer that uses the same major mode normally uses the
+ − 565 same local keymap, you can think of the keymap as local to the mode. A
+ − 566 change to the local keymap of a buffer (using @code{local-set-key}, for
+ − 567 example) is seen also in the other buffers that share that keymap.
+ − 568
+ − 569 The local keymaps that are used for Lisp mode, C mode, and several
+ − 570 other major modes exist even if they have not yet been used. These
+ − 571 local maps are the values of the variables @code{lisp-mode-map},
+ − 572 @code{c-mode-map}, and so on. For most other modes, which are less
+ − 573 frequently used, the local keymap is constructed only when the mode is
+ − 574 used for the first time in a session.
+ − 575
+ − 576 The minibuffer has local keymaps, too; they contain various completion
+ − 577 and exit commands. @xref{Intro to Minibuffers}.
+ − 578
+ − 579 @xref{Standard Keymaps}, for a list of standard keymaps.
+ − 580
+ − 581 @defun current-keymaps &optional event-or-keys
+ − 582 This function returns a list of the current keymaps that will be
+ − 583 searched for bindings. This lists keymaps such as the current local map
+ − 584 and the minor-mode maps, but does not list the parents of those keymaps.
+ − 585 @var{event-or-keys} controls which keymaps will be listed. If
+ − 586 @var{event-or-keys} is a mouse event (or a vector whose last element is
+ − 587 a mouse event), the keymaps for that mouse event will be listed.
+ − 588 Otherwise, the keymaps for key presses will be listed.
+ − 589 @end defun
+ − 590
+ − 591 @defvar global-map
+ − 592 This variable contains the default global keymap that maps XEmacs
+ − 593 keyboard input to commands. The global keymap is normally this keymap.
+ − 594 The default global keymap is a full keymap that binds
+ − 595 @code{self-insert-command} to all of the printing characters.
+ − 596
+ − 597 It is normal practice to change the bindings in the global map, but you
+ − 598 should not assign this variable any value other than the keymap it starts
+ − 599 out with.
+ − 600 @end defvar
+ − 601
+ − 602 @defun current-global-map
+ − 603 This function returns the current global keymap. This is the
+ − 604 same as the value of @code{global-map} unless you change one or the
+ − 605 other.
+ − 606
+ − 607 @example
+ − 608 @group
+ − 609 (current-global-map)
+ − 610 @result{} #<keymap global-map 639 entries 0x221>
+ − 611 @end group
+ − 612 @end example
+ − 613 @end defun
+ − 614
444
+ − 615 @defun current-local-map &optional buffer
+ − 616 This function returns @var{buffer}'s local keymap, or @code{nil}
+ − 617 if it has none. @var{buffer} defaults to the current buffer.
+ − 618
+ − 619 In the following example, the keymap for the @samp{*scratch*} buffer
+ − 620 (using Lisp Interaction mode) has a number of entries, including one
+ − 621 prefix key, @kbd{C-x}.
428
+ − 622
+ − 623 @example
+ − 624 @group
+ − 625 (current-local-map)
+ − 626 @result{} #<keymap lisp-interaction-mode-map 5 entries 0x558>
+ − 627 (describe-bindings-internal (current-local-map))
+ − 628 @result{} ; @r{Inserted into the buffer:}
440
+ − 629 backspace backward-delete-char-untabify
+ − 630 linefeed eval-print-last-sexp
+ − 631 delete delete-char
+ − 632 C-j eval-print-last-sexp
+ − 633 C-x << Prefix Command >>
+ − 634 M-tab lisp-complete-symbol
+ − 635 M-; lisp-indent-for-comment
+ − 636 M-C-i lisp-complete-symbol
+ − 637 M-C-q indent-sexp
+ − 638 M-C-x eval-defun
+ − 639 Alt-backspace backward-kill-sexp
+ − 640 Alt-delete kill-sexp
428
+ − 641 @end group
+ − 642
+ − 643 @group
440
+ − 644 C-x x edebug-defun
428
+ − 645 @end group
+ − 646 @end example
+ − 647 @end defun
+ − 648
+ − 649 @defun current-minor-mode-maps
+ − 650 This function returns a list of the keymaps of currently enabled minor modes.
+ − 651 @end defun
+ − 652
+ − 653 @defun use-global-map keymap
+ − 654 This function makes @var{keymap} the new current global keymap. It
+ − 655 returns @code{nil}.
+ − 656
+ − 657 It is very unusual to change the global keymap.
+ − 658 @end defun
+ − 659
+ − 660 @defun use-local-map keymap &optional buffer
+ − 661 This function makes @var{keymap} the new local keymap of @var{buffer}.
+ − 662 @var{buffer} defaults to the current buffer. If @var{keymap} is
+ − 663 @code{nil}, then the buffer has no local keymap. @code{use-local-map}
+ − 664 returns @code{nil}. Most major mode commands use this function.
+ − 665 @end defun
+ − 666
+ − 667 @c Emacs 19 feature
+ − 668 @defvar minor-mode-map-alist
+ − 669 This variable is an alist describing keymaps that may or may not be
+ − 670 active according to the values of certain variables. Its elements look
+ − 671 like this:
+ − 672
+ − 673 @example
+ − 674 (@var{variable} . @var{keymap})
+ − 675 @end example
+ − 676
+ − 677 The keymap @var{keymap} is active whenever @var{variable} has a
+ − 678 non-@code{nil} value. Typically @var{variable} is the variable that
+ − 679 enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
+ − 680
+ − 681 Note that elements of @code{minor-mode-map-alist} do not have the same
+ − 682 structure as elements of @code{minor-mode-alist}. The map must be the
+ − 683 @sc{cdr} of the element; a list with the map as the second element will
+ − 684 not do.
+ − 685
+ − 686 What's more, the keymap itself must appear in the @sc{cdr}. It does not
+ − 687 work to store a variable in the @sc{cdr} and make the map the value of
+ − 688 that variable.
+ − 689
+ − 690 When more than one minor mode keymap is active, their order of priority
+ − 691 is the order of @code{minor-mode-map-alist}. But you should design
+ − 692 minor modes so that they don't interfere with each other. If you do
+ − 693 this properly, the order will not matter.
+ − 694
+ − 695 See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
+ − 696 Minor Modes}, for more information about minor modes.
+ − 697 @end defvar
+ − 698
+ − 699 @defvar modeline-map
+ − 700 This variable holds the keymap consulted for mouse-clicks on the
+ − 701 modeline of a window. This variable may be buffer-local; its value will
+ − 702 be looked up in the buffer of the window whose modeline was clicked
+ − 703 upon.
+ − 704 @end defvar
+ − 705
+ − 706 @defvar toolbar-map
+ − 707 This variable holds the keymap consulted for mouse-clicks over a
+ − 708 toolbar.
+ − 709 @end defvar
+ − 710
+ − 711 @defvar mouse-grabbed-buffer
+ − 712 If non-@code{nil}, a buffer which should be consulted first for all
+ − 713 mouse activity. When a mouse-click is processed, it will first be
+ − 714 looked up in the local-map of this buffer, and then through the normal
+ − 715 mechanism if there is no binding for that click. This buffer's value of
+ − 716 @code{mode-motion-hook} will be consulted instead of the
+ − 717 @code{mode-motion-hook} of the buffer of the window under the mouse.
+ − 718 You should @emph{bind} this, not set it.
+ − 719 @end defvar
+ − 720
+ − 721 @defvar overriding-local-map
+ − 722 If non-@code{nil}, this variable holds a keymap to use instead of the
+ − 723 buffer's local keymap and instead of all the minor mode keymaps. This
+ − 724 keymap, if any, overrides all other maps that would have been active,
+ − 725 except for the current global map.
+ − 726 @end defvar
+ − 727
+ − 728 @defvar overriding-terminal-local-map
+ − 729 If non-@code{nil}, this variable holds a keymap to use instead of the
+ − 730 buffer's local keymap and instead of all the minor mode keymaps, but for
+ − 731 the selected console only. (In other words, this variable is always
+ − 732 console-local; putting a keymap here only applies to keystrokes coming
+ − 733 from the selected console. @xref{Consoles and Devices}.) This keymap,
+ − 734 if any, overrides all other maps that would have been active, except for
+ − 735 the current global map.
+ − 736 @end defvar
+ − 737
+ − 738 @node Key Lookup
+ − 739 @section Key Lookup
+ − 740 @cindex key lookup
+ − 741 @cindex keymap entry
+ − 742
+ − 743 @dfn{Key lookup} is the process of finding the binding of a key
+ − 744 sequence from a given keymap. Actual execution of the binding is not
+ − 745 part of key lookup.
+ − 746
+ − 747 Key lookup uses just the event type of each event in the key
+ − 748 sequence; the rest of the event is ignored. In fact, a key sequence
+ − 749 used for key lookup may designate mouse events with just their types
+ − 750 (symbols) instead of with entire mouse events (lists). @xref{Events}.
+ − 751 Such a pseudo-key-sequence is insufficient for @code{command-execute},
+ − 752 but it is sufficient for looking up or rebinding a key.
+ − 753
+ − 754 When the key sequence consists of multiple events, key lookup
+ − 755 processes the events sequentially: the binding of the first event is
+ − 756 found, and must be a keymap; then the second event's binding is found in
+ − 757 that keymap, and so on until all the events in the key sequence are used
+ − 758 up. (The binding thus found for the last event may or may not be a
+ − 759 keymap.) Thus, the process of key lookup is defined in terms of a
+ − 760 simpler process for looking up a single event in a keymap. How that is
+ − 761 done depends on the type of object associated with the event in that
+ − 762 keymap.
+ − 763
+ − 764 Let's use the term @dfn{keymap entry} to describe the value found by
+ − 765 looking up an event type in a keymap. (This doesn't include the item
+ − 766 string and other extra elements in menu key bindings because
+ − 767 @code{lookup-key} and other key lookup functions don't include them in
+ − 768 the returned value.) While any Lisp object may be stored in a keymap as
+ − 769 a keymap entry, not all make sense for key lookup. Here is a list of
+ − 770 the meaningful kinds of keymap entries:
+ − 771
+ − 772 @table @asis
+ − 773 @item @code{nil}
+ − 774 @cindex @code{nil} in keymap
+ − 775 @code{nil} means that the events used so far in the lookup form an
+ − 776 undefined key. When a keymap fails to mention an event type at all, and
+ − 777 has no default binding, that is equivalent to a binding of @code{nil}
+ − 778 for that event type.
+ − 779
+ − 780 @item @var{keymap}
+ − 781 @cindex keymap in keymap
+ − 782 The events used so far in the lookup form a prefix key. The next
+ − 783 event of the key sequence is looked up in @var{keymap}.
+ − 784
+ − 785 @item @var{command}
+ − 786 @cindex command in keymap
+ − 787 The events used so far in the lookup form a complete key,
+ − 788 and @var{command} is its binding. @xref{What Is a Function}.
+ − 789
+ − 790 @item @var{array}
+ − 791 @cindex string in keymap
+ − 792 The array (either a string or a vector) is a keyboard macro. The events
+ − 793 used so far in the lookup form a complete key, and the array is its
+ − 794 binding. See @ref{Keyboard Macros}, for more information. (Note that
+ − 795 you cannot use a shortened form of a key sequence here, such as
+ − 796 @code{(control y)}; you must use the full form @code{[(control y)]}.
+ − 797 @xref{Key Sequences}.)
+ − 798
+ − 799 @item @var{list}
+ − 800 @cindex list in keymap
+ − 801 The meaning of a list depends on the types of the elements of the list.
+ − 802
+ − 803 @itemize @bullet
+ − 804 @item
+ − 805 @cindex @code{lambda} in keymap
+ − 806 If the @sc{car} of @var{list} is @code{lambda}, then the list is a
+ − 807 lambda expression. This is presumed to be a command, and is treated as
+ − 808 such (see above).
+ − 809
+ − 810 @item
+ − 811 If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event
+ − 812 type, then this is an @dfn{indirect entry}:
+ − 813
+ − 814 @example
+ − 815 (@var{othermap} . @var{othertype})
+ − 816 @end example
+ − 817
+ − 818 When key lookup encounters an indirect entry, it looks up instead the
+ − 819 binding of @var{othertype} in @var{othermap} and uses that.
+ − 820
+ − 821 This feature permits you to define one key as an alias for another key.
+ − 822 For example, an entry whose @sc{car} is the keymap called @code{esc-map}
+ − 823 and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
+ − 824 binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+ − 825 @end itemize
+ − 826
+ − 827 @item @var{symbol}
+ − 828 @cindex symbol in keymap
+ − 829 The function definition of @var{symbol} is used in place of
+ − 830 @var{symbol}. If that too is a symbol, then this process is repeated,
+ − 831 any number of times. Ultimately this should lead to an object that is
+ − 832 a keymap, a command or a keyboard macro. A list is allowed if it is a
+ − 833 keymap or a command, but indirect entries are not understood when found
+ − 834 via symbols.
+ − 835
+ − 836 Note that keymaps and keyboard macros (strings and vectors) are not
+ − 837 valid functions, so a symbol with a keymap, string, or vector as its
+ − 838 function definition is invalid as a function. It is, however, valid as
+ − 839 a key binding. If the definition is a keyboard macro, then the symbol
+ − 840 is also valid as an argument to @code{command-execute}
+ − 841 (@pxref{Interactive Call}).
+ − 842
+ − 843 @cindex @code{undefined} in keymap
+ − 844 The symbol @code{undefined} is worth special mention: it means to treat
+ − 845 the key as undefined. Strictly speaking, the key is defined, and its
+ − 846 binding is the command @code{undefined}; but that command does the same
+ − 847 thing that is done automatically for an undefined key: it rings the bell
+ − 848 (by calling @code{ding}) but does not signal an error.
+ − 849
+ − 850 @cindex preventing prefix key
+ − 851 @code{undefined} is used in local keymaps to override a global key
+ − 852 binding and make the key ``undefined'' locally. A local binding of
+ − 853 @code{nil} would fail to do this because it would not override the
+ − 854 global binding.
+ − 855
+ − 856 @item @var{anything else}
+ − 857 If any other type of object is found, the events used so far in the
+ − 858 lookup form a complete key, and the object is its binding, but the
+ − 859 binding is not executable as a command.
+ − 860 @end table
+ − 861
+ − 862 In short, a keymap entry may be a keymap, a command, a keyboard macro,
+ − 863 a symbol that leads to one of them, or an indirection or @code{nil}.
+ − 864
+ − 865 @node Functions for Key Lookup
+ − 866 @section Functions for Key Lookup
+ − 867
+ − 868 Here are the functions and variables pertaining to key lookup.
+ − 869
+ − 870 @defun lookup-key keymap key &optional accept-defaults
+ − 871 This function returns the definition of @var{key} in @var{keymap}. If
+ − 872 the string or vector @var{key} is not a valid key sequence according to
+ − 873 the prefix keys specified in @var{keymap} (which means it is ``too
+ − 874 long'' and has extra events at the end), then the value is a number, the
+ − 875 number of events at the front of @var{key} that compose a complete key.
+ − 876
+ − 877 @c Emacs 19 feature
+ − 878 If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+ − 879 considers default bindings as well as bindings for the specific events
+ − 880 in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
+ − 881 the specific sequence @var{key}, ignoring default bindings except when
+ − 882 you explicitly ask about them.
+ − 883
+ − 884 All the other functions described in this chapter that look up keys use
+ − 885 @code{lookup-key}.
+ − 886
+ − 887 @example
+ − 888 @group
+ − 889 (lookup-key (current-global-map) "\C-x\C-f")
+ − 890 @result{} find-file
+ − 891 @end group
+ − 892 @group
+ − 893 (lookup-key (current-global-map) "\C-x\C-f12345")
+ − 894 @result{} 2
+ − 895 @end group
+ − 896 @end example
+ − 897
+ − 898 If @var{key} begins with the character whose value is contained in
+ − 899 @code{meta-prefix-char}, that character is implicitly removed and the
+ − 900 @key{META} modifier added to the key. Thus, the first example below is
+ − 901 handled by conversion into the second example.
+ − 902
+ − 903 @example
+ − 904 @group
+ − 905 (lookup-key (current-global-map) "\ef")
+ − 906 @result{} forward-word
+ − 907 @end group
+ − 908 @group
+ − 909 (lookup-key (current-global-map) "\M-f")
+ − 910 @result{} forward-word
+ − 911 @end group
+ − 912 @end example
+ − 913
+ − 914 Unlike @code{read-key-sequence}, this function does not modify the
+ − 915 specified events in ways that discard information (@pxref{Key Sequence
+ − 916 Input}). In particular, it does not convert letters to lower case.
+ − 917 @end defun
+ − 918
+ − 919 @deffn Command undefined
+ − 920 Used in keymaps to undefine keys. If a key sequence is defined to this,
+ − 921 invoking this key sequence causes a ``key undefined'' error, just as if
+ − 922 the key sequence had no binding.
+ − 923 @end deffn
+ − 924
+ − 925 @defun key-binding key &optional accept-defaults
+ − 926 This function returns the binding for @var{key} in the current
+ − 927 keymaps, trying all the active keymaps. The result is @code{nil} if
+ − 928 @var{key} is undefined in the keymaps.
+ − 929
+ − 930 @c Emacs 19 feature
+ − 931 The argument @var{accept-defaults} controls checking for default
+ − 932 bindings, as in @code{lookup-key} (above).
+ − 933
+ − 934 @example
+ − 935 @group
+ − 936 (key-binding "\C-x\C-f")
+ − 937 @result{} find-file
+ − 938 (key-binding '(control home))
+ − 939 @result{} beginning-of-buffer
+ − 940 (key-binding [escape escape escape])
+ − 941 @result{} keyboard-escape-quit
+ − 942 @end group
+ − 943 @end example
+ − 944 @end defun
+ − 945
444
+ − 946 @defun local-key-binding keys &optional accept-defaults
+ − 947 This function returns the binding for @var{keys} in the current
428
+ − 948 local keymap, or @code{nil} if it is undefined there.
+ − 949
+ − 950 @c Emacs 19 feature
+ − 951 The argument @var{accept-defaults} controls checking for default bindings,
+ − 952 as in @code{lookup-key} (above).
+ − 953 @end defun
+ − 954
444
+ − 955 @defun global-key-binding keys &optional accept-defaults
+ − 956 This function returns the binding for command @var{keys} in the
428
+ − 957 current global keymap, or @code{nil} if it is undefined there.
+ − 958
+ − 959 @c Emacs 19 feature
+ − 960 The argument @var{accept-defaults} controls checking for default bindings,
+ − 961 as in @code{lookup-key} (above).
+ − 962 @end defun
+ − 963
+ − 964 @c Emacs 19 feature
+ − 965 @defun minor-mode-key-binding key &optional accept-defaults
+ − 966 This function returns a list of all the active minor mode bindings of
+ − 967 @var{key}. More precisely, it returns an alist of pairs
+ − 968 @code{(@var{modename} . @var{binding})}, where @var{modename} is the
+ − 969 variable that enables the minor mode, and @var{binding} is @var{key}'s
+ − 970 binding in that mode. If @var{key} has no minor-mode bindings, the
+ − 971 value is @code{nil}.
+ − 972
+ − 973 If the first binding is not a prefix command, all subsequent bindings
+ − 974 from other minor modes are omitted, since they would be completely
+ − 975 shadowed. Similarly, the list omits non-prefix bindings that follow
+ − 976 prefix bindings.
+ − 977
+ − 978 The argument @var{accept-defaults} controls checking for default
+ − 979 bindings, as in @code{lookup-key} (above).
+ − 980 @end defun
+ − 981
+ − 982 @defvar meta-prefix-char
+ − 983 @cindex @key{ESC}
+ − 984 This variable is the meta-prefix character code. It is used when
+ − 985 translating a two-character sequence to a meta character so it can be
+ − 986 looked up in a keymap. For useful results, the value should be a prefix
+ − 987 event (@pxref{Prefix Keys}). The default value is @code{?\^[} (integer
+ − 988 27), which is the @sc{ascii} character usually produced by the @key{ESC}
+ − 989 key.
+ − 990
+ − 991 As long as the value of @code{meta-prefix-char} remains @code{?\^[},
+ − 992 key lookup translates @kbd{@key{ESC} b} into @kbd{M-b}, which is
+ − 993 normally defined as the @code{backward-word} command. However, if you
+ − 994 set @code{meta-prefix-char} to @code{?\^X} (i.e. the keystroke
+ − 995 @kbd{C-x}) or its equivalent @sc{ascii} code @code{24}, then XEmacs will
+ − 996 translate @kbd{C-x b} (whose standard binding is the
+ − 997 @code{switch-to-buffer} command) into @kbd{M-b}.
+ − 998
+ − 999 @smallexample
+ − 1000 @group
+ − 1001 meta-prefix-char ; @r{The default value.}
+ − 1002 @result{} ?\^[ ; @r{Under XEmacs 20.}
+ − 1003 @result{} 27 ; @r{Under XEmacs 19.}
+ − 1004 @end group
+ − 1005 @group
+ − 1006 (key-binding "\eb")
+ − 1007 @result{} backward-word
+ − 1008 @end group
+ − 1009 @group
+ − 1010 ?\C-x ; @r{The print representation}
+ − 1011 ; @r{of a character.}
+ − 1012 @result{} ?\^X ; @r{Under XEmacs 20.}
+ − 1013 @result{} 24 ; @r{Under XEmacs 19.}
+ − 1014 @end group
+ − 1015 @group
+ − 1016 (setq meta-prefix-char 24)
444
+ − 1017 @result{} 24
428
+ − 1018 @end group
+ − 1019 @group
+ − 1020 (key-binding "\C-xb")
+ − 1021 @result{} backward-word ; @r{Now, typing @kbd{C-x b} is}
+ − 1022 ; @r{like typing @kbd{M-b}.}
+ − 1023
+ − 1024 (setq meta-prefix-char ?\e) ; @r{Avoid confusion!}
+ − 1025 ; @r{Restore the default value!}
+ − 1026 @result{} ?\^[ ; @r{Under XEmacs 20.}
+ − 1027 @result{} 27 ; @r{Under XEmacs 19.}
+ − 1028 @end group
+ − 1029 @end smallexample
+ − 1030 @end defvar
+ − 1031
+ − 1032 @node Changing Key Bindings
+ − 1033 @section Changing Key Bindings
+ − 1034 @cindex changing key bindings
+ − 1035 @cindex rebinding
+ − 1036
+ − 1037 The way to rebind a key is to change its entry in a keymap. If you
+ − 1038 change a binding in the global keymap, the change is effective in all
+ − 1039 buffers (though it has no direct effect in buffers that shadow the
+ − 1040 global binding with a local one). If you change the current buffer's
+ − 1041 local map, that usually affects all buffers using the same major mode.
+ − 1042 The @code{global-set-key} and @code{local-set-key} functions are
+ − 1043 convenient interfaces for these operations (@pxref{Key Binding
+ − 1044 Commands}). You can also use @code{define-key}, a more general
+ − 1045 function; then you must specify explicitly the map to change.
+ − 1046
+ − 1047 The way to specify the key sequence that you want to rebind is
+ − 1048 described above (@pxref{Key Sequences}).
+ − 1049
+ − 1050 For the functions below, an error is signaled if @var{keymap} is not a
+ − 1051 keymap or if @var{key} is not a string or vector representing a key
+ − 1052 sequence. You can use event types (symbols) as shorthand for events
+ − 1053 that are lists.
+ − 1054
+ − 1055 @defun define-key keymap key binding
+ − 1056 This function sets the binding for @var{key} in @var{keymap}. (If
+ − 1057 @var{key} is more than one event long, the change is actually made
+ − 1058 in another keymap reached from @var{keymap}.) The argument
+ − 1059 @var{binding} can be any Lisp object, but only certain types are
+ − 1060 meaningful. (For a list of meaningful types, see @ref{Key Lookup}.)
+ − 1061 The value returned by @code{define-key} is @var{binding}.
+ − 1062
+ − 1063 @cindex invalid prefix key error
+ − 1064 @cindex key sequence error
+ − 1065 Every prefix of @var{key} must be a prefix key (i.e., bound to a
+ − 1066 keymap) or undefined; otherwise an error is signaled.
+ − 1067
+ − 1068 If some prefix of @var{key} is undefined, then @code{define-key} defines
+ − 1069 it as a prefix key so that the rest of @var{key} may be defined as
+ − 1070 specified.
+ − 1071 @end defun
+ − 1072
+ − 1073 Here is an example that creates a sparse keymap and makes a number of
+ − 1074 bindings in it:
+ − 1075
+ − 1076 @smallexample
+ − 1077 @group
+ − 1078 (setq map (make-sparse-keymap))
+ − 1079 @result{} #<keymap 0 entries 0xbee>
+ − 1080 @end group
+ − 1081 @group
+ − 1082 (define-key map "\C-f" 'forward-char)
+ − 1083 @result{} forward-char
+ − 1084 @end group
+ − 1085 @group
+ − 1086 map
+ − 1087 @result{} #<keymap 1 entry 0xbee>
+ − 1088 (describe-bindings-internal map)
+ − 1089 @result{} ; @r{(Inserted in buffer)}
+ − 1090 C-f forward-char
+ − 1091 @end group
+ − 1092
+ − 1093 @group
+ − 1094 ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.}
+ − 1095 (define-key map "\C-xf" 'forward-word)
+ − 1096 @result{} forward-word
+ − 1097 @end group
+ − 1098 @group
+ − 1099 map
+ − 1100 @result{} #<keymap 2 entries 0xbee>
+ − 1101 (describe-bindings-internal map)
+ − 1102 @result{} ; @r{(Inserted in buffer)}
+ − 1103 C-f forward-char
+ − 1104 C-x << Prefix Command >>
+ − 1105
+ − 1106 C-x f forward-word
+ − 1107 @end group
+ − 1108
+ − 1109 @group
+ − 1110 ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.}
+ − 1111 (define-key map "\C-p" ctl-x-map)
+ − 1112 ;; @code{ctl-x-map}
+ − 1113 @result{} #<keymap Control-X-prefix 77 entries 0x3bf>
+ − 1114 @end group
+ − 1115
+ − 1116 @group
+ − 1117 ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.}
+ − 1118 (define-key map "\C-p\C-f" 'foo)
+ − 1119 @result{} foo
+ − 1120 @end group
+ − 1121 @group
+ − 1122 map
+ − 1123 @result{} #<keymap 3 entries 0xbee>
+ − 1124 (describe-bindings-internal map)
+ − 1125 @result{} ; @r{(Inserted in buffer)}
+ − 1126 C-f forward-char
+ − 1127 C-p << Prefix command Control-X-prefix >>
+ − 1128 C-x << Prefix Command >>
+ − 1129
+ − 1130 C-p tab indent-rigidly
+ − 1131 C-p $ set-selective-display
+ − 1132 C-p ' expand-abbrev
+ − 1133 C-p ( start-kbd-macro
+ − 1134 C-p ) end-kbd-macro
+ − 1135 @dots{}
+ − 1136 C-p C-x exchange-point-and-mark
+ − 1137 C-p C-z suspend-or-iconify-emacs
+ − 1138 C-p M-escape repeat-complex-command
+ − 1139 C-p M-C-[ repeat-complex-command
+ − 1140
+ − 1141 C-x f forward-word
+ − 1142
+ − 1143 C-p 4 . find-tag-other-window
+ − 1144 @dots{}
+ − 1145 C-p 4 C-o display-buffer
+ − 1146
+ − 1147 C-p 5 0 delete-frame
+ − 1148 @dots{}
+ − 1149 C-p 5 C-f find-file-other-frame
+ − 1150
+ − 1151 @dots{}
+ − 1152
+ − 1153 C-p a i g inverse-add-global-abbrev
+ − 1154 C-p a i l inverse-add-mode-abbrev
+ − 1155 @end group
+ − 1156 @end smallexample
+ − 1157
+ − 1158 @noindent
+ − 1159 Note that storing a new binding for @kbd{C-p C-f} actually works by
+ − 1160 changing an entry in @code{ctl-x-map}, and this has the effect of
+ − 1161 changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the
+ − 1162 default global map.
+ − 1163
444
+ − 1164 @defun substitute-key-definition olddef newdef keymap &optional oldmap prefix
428
+ − 1165 @cindex replace bindings
+ − 1166 This function replaces @var{olddef} with @var{newdef} for any keys in
+ − 1167 @var{keymap} that were bound to @var{olddef}. In other words,
444
+ − 1168 @var{olddef} is replaced with @var{newdef} wherever it appears. Prefix
+ − 1169 keymaps are checked recursively.
+ − 1170
+ − 1171 The function returns @code{nil}.
428
+ − 1172
+ − 1173 For example, this redefines @kbd{C-x C-f}, if you do it in an XEmacs with
+ − 1174 standard bindings:
+ − 1175
+ − 1176 @smallexample
+ − 1177 @group
444
+ − 1178 (substitute-key-definition
428
+ − 1179 'find-file 'find-file-read-only (current-global-map))
+ − 1180 @end group
+ − 1181 @end smallexample
+ − 1182
+ − 1183 @c Emacs 19 feature
+ − 1184 If @var{oldmap} is non-@code{nil}, then its bindings determine which
444
+ − 1185 keys to rebind. The rebindings still happen in @var{keymap}, not in
428
+ − 1186 @var{oldmap}. Thus, you can change one map under the control of the
+ − 1187 bindings in another. For example,
+ − 1188
+ − 1189 @smallexample
+ − 1190 (substitute-key-definition
+ − 1191 'delete-backward-char 'my-funny-delete
+ − 1192 my-map global-map)
+ − 1193 @end smallexample
+ − 1194
+ − 1195 @noindent
+ − 1196 puts the special deletion command in @code{my-map} for whichever keys
+ − 1197 are globally bound to the standard deletion command.
+ − 1198
444
+ − 1199 If argument @var{prefix} is non-@code{nil}, then only those occurrences
+ − 1200 of @var{olddef} found in keymaps accessible through the keymap bound to
+ − 1201 @var{prefix} in @var{keymap} are redefined. See also
+ − 1202 @code{accessible-keymaps}.
+ − 1203
428
+ − 1204 @ignore
+ − 1205 @c Emacs 18 only
+ − 1206 Prefix keymaps that appear within @var{keymap} are not checked
+ − 1207 recursively for keys bound to @var{olddef}; they are not changed at all.
+ − 1208 Perhaps it would be better to check nested keymaps recursively.
+ − 1209 @end ignore
+ − 1210
+ − 1211 @ignore @c #### fix this up.
+ − 1212 Here is an example showing a keymap before and after substitution:
+ − 1213
+ − 1214 @smallexample
+ − 1215 @group
444
+ − 1216 (setq map '(keymap
+ − 1217 (?1 . olddef-1)
+ − 1218 (?2 . olddef-2)
428
+ − 1219 (?3 . olddef-1)))
+ − 1220 @result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
+ − 1221 @end group
+ − 1222
+ − 1223 @group
+ − 1224 (substitute-key-definition 'olddef-1 'newdef map)
+ − 1225 @result{} nil
+ − 1226 @end group
+ − 1227 @group
+ − 1228 map
+ − 1229 @result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
+ − 1230 @end group
+ − 1231 @end smallexample
+ − 1232 @end ignore
+ − 1233 @end defun
+ − 1234
+ − 1235 @defun suppress-keymap keymap &optional nodigits
+ − 1236 @cindex @code{self-insert-command} override
+ − 1237 This function changes the contents of the full keymap @var{keymap} by
+ − 1238 making all the printing characters undefined. More precisely, it binds
+ − 1239 them to the command @code{undefined}. This makes ordinary insertion of
+ − 1240 text impossible. @code{suppress-keymap} returns @code{nil}.
+ − 1241
+ − 1242 If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines
+ − 1243 digits to run @code{digit-argument}, and @kbd{-} to run
+ − 1244 @code{negative-argument}. Otherwise it makes them undefined like the
+ − 1245 rest of the printing characters.
+ − 1246
444
+ − 1247 @cindex yank suppression
+ − 1248 @cindex @code{quoted-insert} suppression
428
+ − 1249 The @code{suppress-keymap} function does not make it impossible to
+ − 1250 modify a buffer, as it does not suppress commands such as @code{yank}
+ − 1251 and @code{quoted-insert}. To prevent any modification of a buffer, make
+ − 1252 it read-only (@pxref{Read Only Buffers}).
+ − 1253
+ − 1254 Since this function modifies @var{keymap}, you would normally use it
+ − 1255 on a newly created keymap. Operating on an existing keymap
+ − 1256 that is used for some other purpose is likely to cause trouble; for
+ − 1257 example, suppressing @code{global-map} would make it impossible to use
+ − 1258 most of XEmacs.
+ − 1259
+ − 1260 Most often, @code{suppress-keymap} is used to initialize local
+ − 1261 keymaps of modes such as Rmail and Dired where insertion of text is not
+ − 1262 desirable and the buffer is read-only. Here is an example taken from
+ − 1263 the file @file{emacs/lisp/dired.el}, showing how the local keymap for
+ − 1264 Dired mode is set up:
+ − 1265
+ − 1266 @smallexample
+ − 1267 @group
+ − 1268 @dots{}
+ − 1269 (setq dired-mode-map (make-keymap))
+ − 1270 (suppress-keymap dired-mode-map)
+ − 1271 (define-key dired-mode-map "r" 'dired-rename-file)
+ − 1272 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+ − 1273 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
+ − 1274 (define-key dired-mode-map "v" 'dired-view-file)
+ − 1275 (define-key dired-mode-map "e" 'dired-find-file)
+ − 1276 (define-key dired-mode-map "f" 'dired-find-file)
+ − 1277 @dots{}
+ − 1278 @end group
+ − 1279 @end smallexample
+ − 1280 @end defun
+ − 1281
+ − 1282 @node Key Binding Commands
+ − 1283 @section Commands for Binding Keys
+ − 1284
+ − 1285 This section describes some convenient interactive interfaces for
+ − 1286 changing key bindings. They work by calling @code{define-key}.
+ − 1287
+ − 1288 People often use @code{global-set-key} in their @file{.emacs} file for
+ − 1289 simple customization. For example,
+ − 1290
+ − 1291 @smallexample
+ − 1292 (global-set-key "\C-x\C-\\" 'next-line)
+ − 1293 @end smallexample
+ − 1294
+ − 1295 @noindent
+ − 1296 or
+ − 1297
+ − 1298 @smallexample
+ − 1299 (global-set-key [(control ?x) (control ?\\)] 'next-line)
+ − 1300 @end smallexample
+ − 1301
+ − 1302 @noindent
+ − 1303 or
+ − 1304
+ − 1305 @smallexample
+ − 1306 (global-set-key [?\C-x ?\C-\\] 'next-line)
+ − 1307 @end smallexample
+ − 1308
+ − 1309 @noindent
+ − 1310 redefines @kbd{C-x C-\} to move down a line.
+ − 1311
+ − 1312 @smallexample
+ − 1313 (global-set-key [(meta button1)] 'mouse-set-point)
+ − 1314 @end smallexample
+ − 1315
+ − 1316 @noindent
+ − 1317 redefines the first (leftmost) mouse button, typed with the Meta key, to
+ − 1318 set point where you click.
+ − 1319
+ − 1320 @deffn Command global-set-key key definition
+ − 1321 This function sets the binding of @var{key} in the current global map
+ − 1322 to @var{definition}.
+ − 1323
+ − 1324 @smallexample
+ − 1325 @group
+ − 1326 (global-set-key @var{key} @var{definition})
+ − 1327 @equiv{}
+ − 1328 (define-key (current-global-map) @var{key} @var{definition})
+ − 1329 @end group
+ − 1330 @end smallexample
+ − 1331 @end deffn
+ − 1332
+ − 1333 @deffn Command global-unset-key key
+ − 1334 @cindex unbinding keys
+ − 1335 This function removes the binding of @var{key} from the current
+ − 1336 global map.
+ − 1337
+ − 1338 One use of this function is in preparation for defining a longer key
+ − 1339 that uses @var{key} as a prefix---which would not be allowed if
+ − 1340 @var{key} has a non-prefix binding. For example:
+ − 1341
+ − 1342 @smallexample
+ − 1343 @group
+ − 1344 (global-unset-key "\C-l")
+ − 1345 @result{} nil
+ − 1346 @end group
+ − 1347 @group
+ − 1348 (global-set-key "\C-l\C-l" 'redraw-display)
+ − 1349 @result{} nil
+ − 1350 @end group
+ − 1351 @end smallexample
+ − 1352
+ − 1353 This function is implemented simply using @code{define-key}:
+ − 1354
+ − 1355 @smallexample
+ − 1356 @group
+ − 1357 (global-unset-key @var{key})
+ − 1358 @equiv{}
+ − 1359 (define-key (current-global-map) @var{key} nil)
+ − 1360 @end group
+ − 1361 @end smallexample
+ − 1362 @end deffn
+ − 1363
+ − 1364 @deffn Command local-set-key key definition
+ − 1365 This function sets the binding of @var{key} in the current local
+ − 1366 keymap to @var{definition}.
+ − 1367
+ − 1368 @smallexample
+ − 1369 @group
+ − 1370 (local-set-key @var{key} @var{definition})
+ − 1371 @equiv{}
+ − 1372 (define-key (current-local-map) @var{key} @var{definition})
+ − 1373 @end group
+ − 1374 @end smallexample
+ − 1375 @end deffn
+ − 1376
+ − 1377 @deffn Command local-unset-key key
+ − 1378 This function removes the binding of @var{key} from the current
+ − 1379 local map.
+ − 1380
+ − 1381 @smallexample
+ − 1382 @group
+ − 1383 (local-unset-key @var{key})
+ − 1384 @equiv{}
+ − 1385 (define-key (current-local-map) @var{key} nil)
+ − 1386 @end group
+ − 1387 @end smallexample
+ − 1388 @end deffn
+ − 1389
+ − 1390 @node Scanning Keymaps
+ − 1391 @section Scanning Keymaps
+ − 1392
+ − 1393 This section describes functions used to scan all the current keymaps,
+ − 1394 or all keys within a keymap, for the sake of printing help information.
+ − 1395
+ − 1396 @defun accessible-keymaps keymap &optional prefix
+ − 1397 This function returns a list of all the keymaps that can be accessed
+ − 1398 (via prefix keys) from @var{keymap}. The value is an association list
+ − 1399 with elements of the form @code{(@var{key} .@: @var{map})}, where
+ − 1400 @var{key} is a prefix key whose definition in @var{keymap} is
+ − 1401 @var{map}.
+ − 1402
+ − 1403 The elements of the alist are ordered so that the @var{key} increases
+ − 1404 in length. The first element is always @code{([] .@: @var{keymap})},
+ − 1405 because the specified keymap is accessible from itself with a prefix of
+ − 1406 no events.
+ − 1407
+ − 1408 If @var{prefix} is given, it should be a prefix key sequence; then
+ − 1409 @code{accessible-keymaps} includes only the submaps whose prefixes start
+ − 1410 with @var{prefix}. These elements look just as they do in the value of
+ − 1411 @code{(accessible-keymaps)}; the only difference is that some elements
+ − 1412 are omitted.
+ − 1413
+ − 1414 In the example below, the returned alist indicates that the key
+ − 1415 @kbd{C-x}, which is displayed as @samp{[(control x)]}, is a prefix key
+ − 1416 whose definition is the keymap @code{#<keymap ((control x) #<keymap
+ − 1417 emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>}. (The strange
+ − 1418 notation for the keymap's name indicates that this is an internal submap
+ − 1419 of @code{emacs-lisp-mode-map}. This is because
+ − 1420 @code{lisp-interaction-mode-map} has set up @code{emacs-lisp-mode-map}
+ − 1421 as its parent, and @code{lisp-interaction-mode-map} defines no key
+ − 1422 sequences beginning with @kbd{C-x}.)
+ − 1423
+ − 1424 @smallexample
+ − 1425 @group
444
+ − 1426 (current-local-map)
428
+ − 1427 @result{} #<keymap lisp-interaction-mode-map 5 entries 0x558>
+ − 1428 (accessible-keymaps (current-local-map))
+ − 1429 @result{}(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
+ − 1430 ([(control x)] .
+ − 1431 #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
+ − 1432 1 entry 0x8a2>))
+ − 1433 @end group
+ − 1434 @end smallexample
+ − 1435
+ − 1436 The following example shows the results of calling
+ − 1437 @code{accessible-keymaps} on a large, complex keymap. Notice how
+ − 1438 some keymaps were given explicit names using @code{set-keymap-name};
+ − 1439 those submaps without explicit names are given descriptive names
+ − 1440 indicating their relationship to their enclosing keymap.
+ − 1441
+ − 1442 @smallexample
+ − 1443 @group
+ − 1444 (accessible-keymaps (current-global-map))
+ − 1445 @result{} (([] . #<keymap global-map 639 entries 0x221>)
+ − 1446 ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
+ − 1447 ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
+ − 1448 ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
+ − 1449 ([(meta escape)] .
+ − 1450 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ − 1451 3 entries 0x3e0>)
+ − 1452 ([(meta control \[)] .
+ − 1453 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+ − 1454 3 entries 0x3e0>)
+ − 1455 ([f1] . #<keymap help-map 33 entries 0x4ec>)
+ − 1456 ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
+ − 1457 ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
+ − 1458 ([(control x) \6] . #<keymap 13 entries 0x4d2>)
+ − 1459 ([(control x) a] .
+ − 1460 #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ − 1461 8 entries 0x3ef>)
+ − 1462 ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
+ − 1463 ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
+ − 1464 ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
+ − 1465 ([(control x) a i] .
+ − 1466 #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+ − 1467 8 entries 0x3ef>)
+ − 1468 2 entries 0x3f5>))
+ − 1469 @end group
+ − 1470 @end smallexample
+ − 1471 @end defun
+ − 1472
+ − 1473 @defun map-keymap function keymap &optional sort-first
444
+ − 1474 This function applies @var{function} to each element of @var{keymap}.
428
+ − 1475 @var{function} will be called with two arguments: a key-description
+ − 1476 list, and the binding. The order in which the elements of the keymap
+ − 1477 are passed to the function is unspecified. If the function inserts new
+ − 1478 elements into the keymap, it may or may not be called with them later.
+ − 1479 No element of the keymap will ever be passed to the function more than
+ − 1480 once.
+ − 1481
+ − 1482 The function will not be called on elements of this keymap's parents
+ − 1483 (@pxref{Inheritance and Keymaps}) or upon keymaps which are contained
+ − 1484 within this keymap (multi-character definitions). It will be called on
+ − 1485 @key{META} characters since they are not really two-character sequences.
+ − 1486
+ − 1487 If the optional third argument @var{sort-first} is non-@code{nil}, then
+ − 1488 the elements of the keymap will be passed to the mapper function in a
+ − 1489 canonical order. Otherwise, they will be passed in hash (that is,
+ − 1490 random) order, which is faster.
+ − 1491 @end defun
+ − 1492
+ − 1493 @defun keymap-fullness keymap
+ − 1494 This function returns the number of bindings in the keymap.
+ − 1495 @end defun
+ − 1496
+ − 1497 @defun where-is-internal definition &optional keymaps firstonly noindirect event-or-keys
+ − 1498 This function returns a list of key sequences (of any length) that are
+ − 1499 bound to @var{definition} in a set of keymaps.
+ − 1500
+ − 1501 The argument @var{definition} can be any object; it is compared with all
+ − 1502 keymap entries using @code{eq}.
+ − 1503
444
+ − 1504 @var{keymaps} can be either a keymap (meaning search in that keymap and the
428
+ − 1505 current global keymap) or a list of keymaps (meaning search in exactly
444
+ − 1506 those keymaps and no others). If @var{keymaps} is nil, search in the currently
+ − 1507 applicable maps for @var{event-or-keys}.
428
+ − 1508
444
+ − 1509 If @var{keymaps} is a keymap, then the maps searched are @var{keymaps} and
+ − 1510 the global keymap. If @var{keymaps} is a list of keymaps, then the maps
+ − 1511 searched are exactly those keymaps, and no others. If @var{keymaps} is
428
+ − 1512 @code{nil}, then the maps used are the current active keymaps for
+ − 1513 @var{event-or-keys} (this is equivalent to specifying
+ − 1514 @code{(current-keymaps @var{event-or-keys})} as the argument to
+ − 1515 @var{keymaps}).
+ − 1516
+ − 1517 If @var{firstonly} is non-@code{nil}, then the value is a single
+ − 1518 vector representing the first key sequence found, rather than a list of
+ − 1519 all possible key sequences.
+ − 1520 @ignore @c #### Should fix where-is to be more like FSF
+ − 1521 If @var{firstonly} is @code{non-ascii}, then the value is a single
+ − 1522 string representing the first key sequence found, rather than a list of
+ − 1523 all possible key sequences. If @var{firstonly} is @code{t}, then the
+ − 1524 value is the first key sequence, except that key sequences consisting
+ − 1525 entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
+ − 1526 characters) are preferred to all other key sequences.
+ − 1527 @end ignore
+ − 1528
+ − 1529 If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
+ − 1530 follow indirect keymap bindings. This makes it possible to search for
+ − 1531 an indirect definition itself.
+ − 1532
446
+ − 1533 This function is used by @code{where-is} (@pxref{Help, , Help, xemacs,
+ − 1534 The XEmacs Lisp Reference Manual}).
428
+ − 1535
+ − 1536 @smallexample
+ − 1537 @group
+ − 1538 (where-is-internal 'describe-function)
+ − 1539 @result{} ([(control h) d] [(control h) f] [f1 d] [f1 f])
+ − 1540 @end group
+ − 1541 @end smallexample
+ − 1542 @end defun
+ − 1543
+ − 1544 @defun describe-bindings-internal map &optional all shadow prefix mouse-only-p
+ − 1545 This function inserts (into the current buffer) a list of all defined
+ − 1546 keys and their definitions in @var{map}. Optional second argument
+ − 1547 @var{all} says whether to include even ``uninteresting'' definitions,
+ − 1548 i.e. symbols with a non-@code{nil} @code{suppress-keymap} property.
+ − 1549 Third argument @var{shadow} is a list of keymaps whose bindings shadow
+ − 1550 those of map; if a binding is present in any shadowing map, it is not
+ − 1551 printed. Fourth argument @var{prefix}, if non-@code{nil}, should be a
+ − 1552 key sequence; only bindings which start with that key sequence will be
+ − 1553 printed. Fifth argument @var{mouse-only-p} says to only print bindings
+ − 1554 for mouse clicks.
+ − 1555 @end defun
+ − 1556
+ − 1557 @code{describe-bindings-internal} is used to implement the
+ − 1558 help command @code{describe-bindings}.
+ − 1559
444
+ − 1560 @deffn Command describe-bindings &optional prefix mouse-only-p
428
+ − 1561 This function creates a listing of all defined keys and their
+ − 1562 definitions. It writes the listing in a buffer named @samp{*Help*} and
+ − 1563 displays it in a window.
+ − 1564
444
+ − 1565 If optional argument @var{prefix} is non-@code{nil}, it should be a
+ − 1566 prefix key; then the listing includes only keys that start with
+ − 1567 @var{prefix}.
428
+ − 1568
+ − 1569 When several characters with consecutive @sc{ascii} codes have the
+ − 1570 same definition, they are shown together, as
+ − 1571 @samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
+ − 1572 know the @sc{ascii} codes to understand which characters this means.
+ − 1573 For example, in the default global map, the characters @samp{@key{SPC}
+ − 1574 ..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32,
+ − 1575 @kbd{~} is @sc{ascii} 126, and the characters between them include all
+ − 1576 the normal printing characters, (e.g., letters, digits, punctuation,
+ − 1577 etc.@:); all these characters are bound to @code{self-insert-command}.
+ − 1578
444
+ − 1579 If the second optional argument @var{mouse-only-p} (prefix arg,
+ − 1580 interactively) is non-@code{nil} then only the mouse bindings are
+ − 1581 displayed.
428
+ − 1582 @end deffn
+ − 1583
+ − 1584 @node Other Keymap Functions
+ − 1585 @section Other Keymap Functions
+ − 1586
+ − 1587 @defun set-keymap-prompt keymap new-prompt
+ − 1588 This function sets the ``prompt'' of @var{keymap} to string
+ − 1589 @var{new-prompt}, or @code{nil} if no prompt is desired. The prompt is
+ − 1590 shown in the echo-area when reading a key-sequence to be looked-up in
+ − 1591 this keymap.
+ − 1592 @end defun
+ − 1593
+ − 1594 @defun keymap-prompt keymap &optional use-inherited
+ − 1595 This function returns the ``prompt'' of the given keymap.
+ − 1596 If @var{use-inherited} is non-@code{nil}, any parent keymaps
+ − 1597 will also be searched for a prompt.
+ − 1598 @end defun