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