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