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