1 This is ../info/lispref.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps
58 Contrary to popular belief, the world is not ASCII. When running
59 under a window manager, XEmacs can tell the difference between, for
60 example, the keystrokes `control-h', `control-shift-h', and
61 `backspace'. You can, in fact, bind different commands to each of
64 A "key sequence" is a set of keystrokes. A "keystroke" is a keysym
65 and some set of modifiers (such as <CONTROL> and <META>). A "keysym"
66 is what is printed on the keys on your keyboard.
68 A keysym may be represented by a symbol, or (if and only if it is
69 equivalent to an ASCII character in the range 32 - 255) by a character
70 or its equivalent ASCII code. The `A' key may be represented by the
71 symbol `A', the character `?A', or by the number 65. The `break' key
72 may be represented only by the symbol `break'.
74 A keystroke may be represented by a list: the last element of the
75 list is the key (a symbol, character, or number, as above) and the
76 preceding elements are the symbolic names of modifier keys (<CONTROL>,
77 <META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>). Thus, the sequence
78 `control-b' is represented by the forms `(control b)', `(control ?b)',
79 and `(control 98)'. A keystroke may also be represented by an event
80 object, as returned by the `next-command-event' and `read-key-sequence'
83 Note that in this context, the keystroke `control-b' is _not_
84 represented by the number 2 (the ASCII code for `^B') or the character
87 The <SHIFT> modifier is somewhat of a special case. You should not
88 (and cannot) use `(meta shift a)' to mean `(meta A)', since for
89 characters that have ASCII equivalents, the state of the shift key is
90 implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)'
91 to mean `+', as that sort of thing varies from keyboard to keyboard.
92 The <SHIFT> modifier is for use only with characters that do not have a
93 second keysym on the same key, such as `backspace' and `tab'.
95 A key sequence is a vector of keystrokes. As a degenerate case,
96 elements of this vector may also be keysyms if they have no modifiers.
97 That is, the `A' keystroke is represented by all of these forms:
100 [A] [?A] [65] [(A)] [(?A)] [(65)]
102 the `control-a' keystroke is represented by these forms:
104 (control A) (control ?A) (control 65)
105 [(control A)] [(control ?A)] [(control 65)]
107 the key sequence `control-c control-a' is represented by these forms:
109 [(control c) (control a)] [(control ?c) (control ?a)]
110 [(control 99) (control 65)] etc.
112 Mouse button clicks work just like keypresses: `(control button1)'
113 means pressing the left mouse button while holding down the control
114 key. `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
117 Commands may be bound to the mouse-button up-stroke rather than the
118 down-stroke as well. `button1' means the down-stroke, and `button1up'
119 means the up-stroke. Different commands may be bound to the up and
120 down strokes, though that is probably not what you want, so be careful.
122 For backward compatibility, a key sequence may also be represented by
123 a string. In this case, it represents the key sequence(s) that would
124 produce that sequence of ASCII characters in a purely ASCII world. For
125 example, a string containing the ASCII backspace character, `"\^H"',
126 would represent two key sequences: `(control h)' and `backspace'.
127 Binding a command to this will actually bind both of those key
128 sequences. Likewise for the following pairs:
135 control @ control space
137 After binding a command to two key sequences with a form like
139 (define-key global-map "\^X\^I" 'command-1)
141 it is possible to redefine only one of those sequences like so:
143 (define-key global-map [(control x) (control i)] 'command-2)
144 (define-key global-map [(control x) tab] 'command-3)
146 Of course, all of this applies only when running under a window
147 system. If you're talking to XEmacs through a TTY connection, you
148 don't get any of these features.
150 - Function: event-matches-key-specifier-p event key-specifier
151 This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
152 which can be any valid form representing a key sequence. This can
153 be useful, e.g., to determine if the user pressed `help-char' or
157 File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps
162 A "prefix key" has an associated keymap that defines what to do with
163 key sequences that start with the prefix key. For example, `C-x' is a
164 prefix key, and it uses a keymap that is also stored in the variable
165 `ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and
168 * `help-map' is used for events that follow `C-h'.
170 * `mode-specific-map' is for events that follow `C-c'. This map is
171 not actually mode specific; its name was chosen to be informative
172 for the user in `C-h b' (`display-bindings'), where it describes
173 the main use of the `C-c' prefix key.
175 * `ctl-x-map' is the map used for events that follow `C-x'. This
176 map is also the function definition of `Control-X-prefix'.
178 * `ctl-x-4-map' is used for events that follow `C-x 4'.
180 * `ctl-x-5-map' is used for events that follow `C-x 5'.
182 * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
185 * `esc-map' is an evil hack that is present for compatibility
186 purposes with Emacs 18. Defining a key in `esc-map' is equivalent
187 to defining the same key in `global-map' but with the <META>
188 prefix added. You should _not_ use this in your code. (This map is
189 also the function definition of `ESC-prefix'.)
191 The binding of a prefix key is the keymap to use for looking up the
192 events that follow the prefix key. (It may instead be a symbol whose
193 function definition is a keymap. The effect is the same, but the symbol
194 serves as a name for the prefix key.) Thus, the binding of `C-x' is
195 the symbol `Control-X-prefix', whose function definition is the keymap
196 for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.)
198 Prefix key definitions can appear in any active keymap. The
199 definitions of `C-c', `C-x', `C-h' and <ESC> as prefix keys appear in
200 the global map, so these prefix keys are always available. Major and
201 minor modes can redefine a key as a prefix by putting a prefix key
202 definition for it in the local map or the minor mode's map. *Note
205 If a key is defined as a prefix in more than one active map, then its
206 various definitions are in effect merged: the commands defined in the
207 minor mode keymaps come first, followed by those in the local map's
208 prefix definition, and then by those from the global map.
210 In the following example, we make `C-p' a prefix key in the local
211 keymap, in such a way that `C-p' is identical to `C-x'. Then the
212 binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
213 The key sequence `C-p 6' is not found in any active keymap.
215 (use-local-map (make-sparse-keymap))
217 (local-set-key "\C-p" ctl-x-map)
219 (key-binding "\C-p\C-f")
222 (key-binding "\C-p6")
225 - Function: define-prefix-command symbol &optional mapvar
226 This function defines SYMBOL as a prefix command: it creates a
227 keymap and stores it as SYMBOL's function definition. Storing the
228 symbol as the binding of a key makes the key a prefix key that has
229 a name. If optional argument MAPVAR is not specified, it also
230 sets SYMBOL as a variable, to have the keymap as its value. (If
231 MAPVAR is given and is not `t', its value is stored as the value
232 of SYMBOL.) The function returns SYMBOL.
234 In Emacs version 18, only the function definition of SYMBOL was
235 set, not the value as a variable.
238 File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps
243 XEmacs normally contains many keymaps; at any given time, just a few
244 of them are "active" in that they participate in the interpretation of
245 user input. These are the global keymap, the current buffer's local
246 keymap, and the keymaps of any enabled minor modes.
248 The "global keymap" holds the bindings of keys that are defined
249 regardless of the current buffer, such as `C-f'. The variable
250 `global-map' holds this keymap, which is always active.
252 Each buffer may have another keymap, its "local keymap", which may
253 contain new or overriding definitions for keys. The current buffer's
254 local keymap is always active except when `overriding-local-map' or
255 `overriding-terminal-local-map' overrides it. Extents and text
256 properties can specify an alternative local map for certain parts of the
257 buffer; see *Note Extents and Events::.
259 Each minor mode may have a keymap; if it does, the keymap is active
260 when the minor mode is enabled.
262 The variable `overriding-local-map' and
263 `overriding-terminal-local-map', if non-`nil', specify other local
264 keymaps that override the buffer's local map and all the minor mode
267 All the active keymaps are used together to determine what command to
268 execute when a key is entered. XEmacs searches these maps one by one,
269 in order of decreasing precedence, until it finds a binding in one of
274 For key-presses, the order of keymaps searched is:
276 * the `keymap' property of any extent(s) or text properties at point;
278 * any applicable minor-mode maps;
280 * the current local map of the current buffer;
282 * the current global map.
284 For mouse-clicks, the order of keymaps searched is:
286 * the current local map of the `mouse-grabbed-buffer' if any;
288 * the `keymap' property of any extent(s) at the position of the click
289 (this includes modeline extents);
291 * the `modeline-map' of the buffer corresponding to the modeline
292 under the mouse (if the click happened over a modeline);
294 * the value of `toolbar-map' in the current buffer (if the click
295 happened over a toolbar);
297 * the current local map of the buffer under the mouse (does not
298 apply to toolbar clicks);
300 * any applicable minor-mode maps;
302 * the current global map.
304 Note that if `overriding-local-map' or
305 `overriding-terminal-local-map' is non-`nil', _only_ those two maps and
306 the current global map are searched.
308 The procedure for searching a single keymap is called "key lookup";
309 see *Note Key Lookup::.
311 Since every buffer that uses the same major mode normally uses the
312 same local keymap, you can think of the keymap as local to the mode. A
313 change to the local keymap of a buffer (using `local-set-key', for
314 example) is seen also in the other buffers that share that keymap.
316 The local keymaps that are used for Lisp mode, C mode, and several
317 other major modes exist even if they have not yet been used. These
318 local maps are the values of the variables `lisp-mode-map',
319 `c-mode-map', and so on. For most other modes, which are less
320 frequently used, the local keymap is constructed only when the mode is
321 used for the first time in a session.
323 The minibuffer has local keymaps, too; they contain various
324 completion and exit commands. *Note Intro to Minibuffers::.
326 *Note Standard Keymaps::, for a list of standard keymaps.
328 - Function: current-keymaps &optional event-or-keys
329 This function returns a list of the current keymaps that will be
330 searched for bindings. This lists keymaps such as the current
331 local map and the minor-mode maps, but does not list the parents
332 of those keymaps. EVENT-OR-KEYS controls which keymaps will be
333 listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last
334 element is a mouse event), the keymaps for that mouse event will
335 be listed. Otherwise, the keymaps for key presses will be listed.
337 - Variable: global-map
338 This variable contains the default global keymap that maps XEmacs
339 keyboard input to commands. The global keymap is normally this
340 keymap. The default global keymap is a full keymap that binds
341 `self-insert-command' to all of the printing characters.
343 It is normal practice to change the bindings in the global map,
344 but you should not assign this variable any value other than the
345 keymap it starts out with.
347 - Function: current-global-map
348 This function returns the current global keymap. This is the same
349 as the value of `global-map' unless you change one or the other.
352 => #<keymap global-map 639 entries 0x221>
354 - Function: current-local-map &optional buffer
355 This function returns BUFFER's local keymap, or `nil' if it has
356 none. BUFFER defaults to the current buffer.
358 In the following example, the keymap for the `*scratch*' buffer
359 (using Lisp Interaction mode) has a number of entries, including
360 one prefix key, `C-x'.
363 => #<keymap lisp-interaction-mode-map 5 entries 0x558>
364 (describe-bindings-internal (current-local-map))
365 => ; Inserted into the buffer:
366 backspace backward-delete-char-untabify
367 linefeed eval-print-last-sexp
369 C-j eval-print-last-sexp
370 C-x << Prefix Command >>
371 M-tab lisp-complete-symbol
372 M-; lisp-indent-for-comment
373 M-C-i lisp-complete-symbol
376 Alt-backspace backward-kill-sexp
381 - Function: current-minor-mode-maps
382 This function returns a list of the keymaps of currently enabled
385 - Function: use-global-map keymap
386 This function makes KEYMAP the new current global keymap. It
389 It is very unusual to change the global keymap.
391 - Function: use-local-map keymap &optional buffer
392 This function makes KEYMAP the new local keymap of BUFFER. BUFFER
393 defaults to the current buffer. If KEYMAP is `nil', then the
394 buffer has no local keymap. `use-local-map' returns `nil'. Most
395 major mode commands use this function.
397 - Variable: minor-mode-map-alist
398 This variable is an alist describing keymaps that may or may not be
399 active according to the values of certain variables. Its elements
404 The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
405 value. Typically VARIABLE is the variable that enables or
406 disables a minor mode. *Note Keymaps and Minor Modes::.
408 Note that elements of `minor-mode-map-alist' do not have the same
409 structure as elements of `minor-mode-alist'. The map must be the
410 CDR of the element; a list with the map as the second element will
413 What's more, the keymap itself must appear in the CDR. It does not
414 work to store a variable in the CDR and make the map the value of
417 When more than one minor mode keymap is active, their order of
418 priority is the order of `minor-mode-map-alist'. But you should
419 design minor modes so that they don't interfere with each other.
420 If you do this properly, the order will not matter.
422 See also `minor-mode-key-binding', above. See *Note Keymaps and
423 Minor Modes::, for more information about minor modes.
425 - Variable: modeline-map
426 This variable holds the keymap consulted for mouse-clicks on the
427 modeline of a window. This variable may be buffer-local; its
428 value will be looked up in the buffer of the window whose modeline
431 - Variable: toolbar-map
432 This variable holds the keymap consulted for mouse-clicks over a
435 - Variable: mouse-grabbed-buffer
436 If non-`nil', a buffer which should be consulted first for all
437 mouse activity. When a mouse-click is processed, it will first be
438 looked up in the local-map of this buffer, and then through the
439 normal mechanism if there is no binding for that click. This
440 buffer's value of `mode-motion-hook' will be consulted instead of
441 the `mode-motion-hook' of the buffer of the window under the mouse.
442 You should _bind_ this, not set it.
444 - Variable: overriding-local-map
445 If non-`nil', this variable holds a keymap to use instead of the
446 buffer's local keymap and instead of all the minor mode keymaps.
447 This keymap, if any, overrides all other maps that would have been
448 active, except for the current global map.
450 - Variable: overriding-terminal-local-map
451 If non-`nil', this variable holds a keymap to use instead of the
452 buffer's local keymap and instead of all the minor mode keymaps,
453 but for the selected console only. (In other words, this variable
454 is always console-local; putting a keymap here only applies to
455 keystrokes coming from the selected console. *Note Consoles and
456 Devices::.) This keymap, if any, overrides all other maps that
457 would have been active, except for the current global map.
460 File: lispref.info, Node: Key Lookup, Next: Functions for Key Lookup, Prev: Active Keymaps, Up: Keymaps
465 "Key lookup" is the process of finding the binding of a key sequence
466 from a given keymap. Actual execution of the binding is not part of
469 Key lookup uses just the event type of each event in the key
470 sequence; the rest of the event is ignored. In fact, a key sequence
471 used for key lookup may designate mouse events with just their types
472 (symbols) instead of with entire mouse events (lists). *Note Events::.
473 Such a pseudo-key-sequence is insufficient for `command-execute', but
474 it is sufficient for looking up or rebinding a key.
476 When the key sequence consists of multiple events, key lookup
477 processes the events sequentially: the binding of the first event is
478 found, and must be a keymap; then the second event's binding is found in
479 that keymap, and so on until all the events in the key sequence are used
480 up. (The binding thus found for the last event may or may not be a
481 keymap.) Thus, the process of key lookup is defined in terms of a
482 simpler process for looking up a single event in a keymap. How that is
483 done depends on the type of object associated with the event in that
486 Let's use the term "keymap entry" to describe the value found by
487 looking up an event type in a keymap. (This doesn't include the item
488 string and other extra elements in menu key bindings because
489 `lookup-key' and other key lookup functions don't include them in the
490 returned value.) While any Lisp object may be stored in a keymap as a
491 keymap entry, not all make sense for key lookup. Here is a list of the
492 meaningful kinds of keymap entries:
495 `nil' means that the events used so far in the lookup form an
496 undefined key. When a keymap fails to mention an event type at
497 all, and has no default binding, that is equivalent to a binding
498 of `nil' for that event type.
501 The events used so far in the lookup form a prefix key. The next
502 event of the key sequence is looked up in KEYMAP.
505 The events used so far in the lookup form a complete key, and
506 COMMAND is its binding. *Note What Is a Function::.
509 The array (either a string or a vector) is a keyboard macro. The
510 events used so far in the lookup form a complete key, and the
511 array is its binding. See *Note Keyboard Macros::, for more
512 information. (Note that you cannot use a shortened form of a key
513 sequence here, such as `(control y)'; you must use the full form
514 `[(control y)]'. *Note Key Sequences::.)
517 The meaning of a list depends on the types of the elements of the
520 * If the CAR of LIST is `lambda', then the list is a lambda
521 expression. This is presumed to be a command, and is treated
524 * If the CAR of LIST is a keymap and the CDR is an event type,
525 then this is an "indirect entry":
527 (OTHERMAP . OTHERTYPE)
529 When key lookup encounters an indirect entry, it looks up
530 instead the binding of OTHERTYPE in OTHERMAP and uses that.
532 This feature permits you to define one key as an alias for
533 another key. For example, an entry whose CAR is the keymap
534 called `esc-map' and whose CDR is 32 (the code for <SPC>)
535 means, "Use the global binding of `Meta-<SPC>', whatever that
539 The function definition of SYMBOL is used in place of SYMBOL. If
540 that too is a symbol, then this process is repeated, any number of
541 times. Ultimately this should lead to an object that is a keymap,
542 a command or a keyboard macro. A list is allowed if it is a
543 keymap or a command, but indirect entries are not understood when
546 Note that keymaps and keyboard macros (strings and vectors) are not
547 valid functions, so a symbol with a keymap, string, or vector as
548 its function definition is invalid as a function. It is, however,
549 valid as a key binding. If the definition is a keyboard macro,
550 then the symbol is also valid as an argument to `command-execute'
551 (*note Interactive Call::).
553 The symbol `undefined' is worth special mention: it means to treat
554 the key as undefined. Strictly speaking, the key is defined, and
555 its binding is the command `undefined'; but that command does the
556 same thing that is done automatically for an undefined key: it
557 rings the bell (by calling `ding') but does not signal an error.
559 `undefined' is used in local keymaps to override a global key
560 binding and make the key "undefined" locally. A local binding of
561 `nil' would fail to do this because it would not override the
565 If any other type of object is found, the events used so far in the
566 lookup form a complete key, and the object is its binding, but the
567 binding is not executable as a command.
569 In short, a keymap entry may be a keymap, a command, a keyboard
570 macro, a symbol that leads to one of them, or an indirection or `nil'.
573 File: lispref.info, Node: Functions for Key Lookup, Next: Changing Key Bindings, Prev: Key Lookup, Up: Keymaps
575 Functions for Key Lookup
576 ========================
578 Here are the functions and variables pertaining to key lookup.
580 - Function: lookup-key keymap key &optional accept-defaults
581 This function returns the definition of KEY in KEYMAP. If the
582 string or vector KEY is not a valid key sequence according to the
583 prefix keys specified in KEYMAP (which means it is "too long" and
584 has extra events at the end), then the value is a number, the
585 number of events at the front of KEY that compose a complete key.
587 If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
588 default bindings as well as bindings for the specific events in
589 KEY. Otherwise, `lookup-key' reports only bindings for the
590 specific sequence KEY, ignoring default bindings except when you
591 explicitly ask about them.
593 All the other functions described in this chapter that look up
594 keys use `lookup-key'.
596 (lookup-key (current-global-map) "\C-x\C-f")
598 (lookup-key (current-global-map) "\C-x\C-f12345")
601 If KEY begins with the character whose value is contained in
602 `meta-prefix-char', that character is implicitly removed and the
603 <META> modifier added to the key. Thus, the first example below is
604 handled by conversion into the second example.
606 (lookup-key (current-global-map) "\ef")
608 (lookup-key (current-global-map) "\M-f")
611 Unlike `read-key-sequence', this function does not modify the
612 specified events in ways that discard information (*note Key
613 Sequence Input::). In particular, it does not convert letters to
617 Used in keymaps to undefine keys. If a key sequence is defined to
618 this, invoking this key sequence causes a "key undefined" error,
619 just as if the key sequence had no binding.
621 - Function: key-binding key &optional accept-defaults
622 This function returns the binding for KEY in the current keymaps,
623 trying all the active keymaps. The result is `nil' if KEY is
624 undefined in the keymaps.
626 The argument ACCEPT-DEFAULTS controls checking for default
627 bindings, as in `lookup-key' (above).
629 (key-binding "\C-x\C-f")
631 (key-binding '(control home))
632 => beginning-of-buffer
633 (key-binding [escape escape escape])
634 => keyboard-escape-quit
636 - Function: local-key-binding keys &optional accept-defaults
637 This function returns the binding for KEYS in the current local
638 keymap, or `nil' if it is undefined there.
640 The argument ACCEPT-DEFAULTS controls checking for default
641 bindings, as in `lookup-key' (above).
643 - Function: global-key-binding keys &optional accept-defaults
644 This function returns the binding for command KEYS in the current
645 global keymap, or `nil' if it is undefined there.
647 The argument ACCEPT-DEFAULTS controls checking for default
648 bindings, as in `lookup-key' (above).
650 - Function: minor-mode-key-binding key &optional accept-defaults
651 This function returns a list of all the active minor mode bindings
652 of KEY. More precisely, it returns an alist of pairs `(MODENAME .
653 BINDING)', where MODENAME is the variable that enables the minor
654 mode, and BINDING is KEY's binding in that mode. If KEY has no
655 minor-mode bindings, the value is `nil'.
657 If the first binding is not a prefix command, all subsequent
658 bindings from other minor modes are omitted, since they would be
659 completely shadowed. Similarly, the list omits non-prefix
660 bindings that follow prefix bindings.
662 The argument ACCEPT-DEFAULTS controls checking for default
663 bindings, as in `lookup-key' (above).
665 - Variable: meta-prefix-char
666 This variable is the meta-prefix character code. It is used when
667 translating a two-character sequence to a meta character so it can
668 be looked up in a keymap. For useful results, the value should be
669 a prefix event (*note Prefix Keys::). The default value is `?\^['
670 (integer 27), which is the ASCII character usually produced by the
673 As long as the value of `meta-prefix-char' remains `?\^[', key
674 lookup translates `<ESC> b' into `M-b', which is normally defined
675 as the `backward-word' command. However, if you set
676 `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
677 equivalent ASCII code `24', then XEmacs will translate `C-x b'
678 (whose standard binding is the `switch-to-buffer' command) into
681 meta-prefix-char ; The default value.
682 => ?\^[ ; Under XEmacs 20.
683 => 27 ; Under XEmacs 19.
686 ?\C-x ; The print representation
688 => ?\^X ; Under XEmacs 20.
689 => 24 ; Under XEmacs 19.
690 (setq meta-prefix-char 24)
692 (key-binding "\C-xb")
693 => backward-word ; Now, typing `C-x b' is
696 (setq meta-prefix-char ?\e) ; Avoid confusion!
697 ; Restore the default value!
698 => ?\^[ ; Under XEmacs 20.
699 => 27 ; Under XEmacs 19.
702 File: lispref.info, Node: Changing Key Bindings, Next: Key Binding Commands, Prev: Functions for Key Lookup, Up: Keymaps
704 Changing Key Bindings
705 =====================
707 The way to rebind a key is to change its entry in a keymap. If you
708 change a binding in the global keymap, the change is effective in all
709 buffers (though it has no direct effect in buffers that shadow the
710 global binding with a local one). If you change the current buffer's
711 local map, that usually affects all buffers using the same major mode.
712 The `global-set-key' and `local-set-key' functions are convenient
713 interfaces for these operations (*note Key Binding Commands::). You
714 can also use `define-key', a more general function; then you must
715 specify explicitly the map to change.
717 The way to specify the key sequence that you want to rebind is
718 described above (*note Key Sequences::).
720 For the functions below, an error is signaled if KEYMAP is not a
721 keymap or if KEY is not a string or vector representing a key sequence.
722 You can use event types (symbols) as shorthand for events that are
725 - Function: define-key keymap key binding
726 This function sets the binding for KEY in KEYMAP. (If KEY is more
727 than one event long, the change is actually made in another keymap
728 reached from KEYMAP.) The argument BINDING can be any Lisp
729 object, but only certain types are meaningful. (For a list of
730 meaningful types, see *Note Key Lookup::.) The value returned by
731 `define-key' is BINDING.
733 Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
734 or undefined; otherwise an error is signaled.
736 If some prefix of KEY is undefined, then `define-key' defines it
737 as a prefix key so that the rest of KEY may be defined as
740 Here is an example that creates a sparse keymap and makes a number of
743 (setq map (make-sparse-keymap))
744 => #<keymap 0 entries 0xbee>
745 (define-key map "\C-f" 'forward-char)
748 => #<keymap 1 entry 0xbee>
749 (describe-bindings-internal map)
750 => ; (Inserted in buffer)
753 ;; Build sparse submap for `C-x' and bind `f' in that.
754 (define-key map "\C-xf" 'forward-word)
757 => #<keymap 2 entries 0xbee>
758 (describe-bindings-internal map)
759 => ; (Inserted in buffer)
761 C-x << Prefix Command >>
765 ;; Bind `C-p' to the `ctl-x-map'.
766 (define-key map "\C-p" ctl-x-map)
768 => #<keymap Control-X-prefix 77 entries 0x3bf>
770 ;; Bind `C-f' to `foo' in the `ctl-x-map'.
771 (define-key map "\C-p\C-f" 'foo)
774 => #<keymap 3 entries 0xbee>
775 (describe-bindings-internal map)
776 => ; (Inserted in buffer)
778 C-p << Prefix command Control-X-prefix >>
779 C-x << Prefix Command >>
781 C-p tab indent-rigidly
782 C-p $ set-selective-display
784 C-p ( start-kbd-macro
787 C-p C-x exchange-point-and-mark
788 C-p C-z suspend-or-iconify-emacs
789 C-p M-escape repeat-complex-command
790 C-p M-C-[ repeat-complex-command
794 C-p 4 . find-tag-other-window
796 C-p 4 C-o display-buffer
800 C-p 5 C-f find-file-other-frame
804 C-p a i g inverse-add-global-abbrev
805 C-p a i l inverse-add-mode-abbrev
807 Note that storing a new binding for `C-p C-f' actually works by
808 changing an entry in `ctl-x-map', and this has the effect of changing
809 the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
811 - Function: substitute-key-definition olddef newdef keymap &optional
813 This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
814 that were bound to OLDDEF. In other words, OLDDEF is replaced
815 with NEWDEF wherever it appears. Prefix keymaps are checked
818 The function returns `nil'.
820 For example, this redefines `C-x C-f', if you do it in an XEmacs
821 with standard bindings:
823 (substitute-key-definition
824 'find-file 'find-file-read-only (current-global-map))
826 If OLDMAP is non-`nil', then its bindings determine which keys to
827 rebind. The rebindings still happen in KEYMAP, not in OLDMAP.
828 Thus, you can change one map under the control of the bindings in
829 another. For example,
831 (substitute-key-definition
832 'delete-backward-char 'my-funny-delete
835 puts the special deletion command in `my-map' for whichever keys
836 are globally bound to the standard deletion command.
838 If argument PREFIX is non-`nil', then only those occurrences of
839 OLDDEF found in keymaps accessible through the keymap bound to
840 PREFIX in KEYMAP are redefined. See also `accessible-keymaps'.
843 - Function: suppress-keymap keymap &optional nodigits
844 This function changes the contents of the full keymap KEYMAP by
845 making all the printing characters undefined. More precisely, it
846 binds them to the command `undefined'. This makes ordinary
847 insertion of text impossible. `suppress-keymap' returns `nil'.
849 If NODIGITS is `nil', then `suppress-keymap' defines digits to run
850 `digit-argument', and `-' to run `negative-argument'. Otherwise
851 it makes them undefined like the rest of the printing characters.
853 The `suppress-keymap' function does not make it impossible to
854 modify a buffer, as it does not suppress commands such as `yank'
855 and `quoted-insert'. To prevent any modification of a buffer, make
856 it read-only (*note Read Only Buffers::).
858 Since this function modifies KEYMAP, you would normally use it on
859 a newly created keymap. Operating on an existing keymap that is
860 used for some other purpose is likely to cause trouble; for
861 example, suppressing `global-map' would make it impossible to use
864 Most often, `suppress-keymap' is used to initialize local keymaps
865 of modes such as Rmail and Dired where insertion of text is not
866 desirable and the buffer is read-only. Here is an example taken
867 from the file `emacs/lisp/dired.el', showing how the local keymap
868 for Dired mode is set up:
871 (setq dired-mode-map (make-keymap))
872 (suppress-keymap dired-mode-map)
873 (define-key dired-mode-map "r" 'dired-rename-file)
874 (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
875 (define-key dired-mode-map "d" 'dired-flag-file-deleted)
876 (define-key dired-mode-map "v" 'dired-view-file)
877 (define-key dired-mode-map "e" 'dired-find-file)
878 (define-key dired-mode-map "f" 'dired-find-file)
882 File: lispref.info, Node: Key Binding Commands, Next: Scanning Keymaps, Prev: Changing Key Bindings, Up: Keymaps
884 Commands for Binding Keys
885 =========================
887 This section describes some convenient interactive interfaces for
888 changing key bindings. They work by calling `define-key'.
890 People often use `global-set-key' in their `.emacs' file for simple
891 customization. For example,
893 (global-set-key "\C-x\C-\\" 'next-line)
897 (global-set-key [(control ?x) (control ?\\)] 'next-line)
901 (global-set-key [?\C-x ?\C-\\] 'next-line)
903 redefines `C-x C-\' to move down a line.
905 (global-set-key [(meta button1)] 'mouse-set-point)
907 redefines the first (leftmost) mouse button, typed with the Meta key, to
908 set point where you click.
910 - Command: global-set-key key definition
911 This function sets the binding of KEY in the current global map to
914 (global-set-key KEY DEFINITION)
916 (define-key (current-global-map) KEY DEFINITION)
918 - Command: global-unset-key key
919 This function removes the binding of KEY from the current global
922 One use of this function is in preparation for defining a longer
923 key that uses KEY as a prefix--which would not be allowed if KEY
924 has a non-prefix binding. For example:
926 (global-unset-key "\C-l")
928 (global-set-key "\C-l\C-l" 'redraw-display)
931 This function is implemented simply using `define-key':
933 (global-unset-key KEY)
935 (define-key (current-global-map) KEY nil)
937 - Command: local-set-key key definition
938 This function sets the binding of KEY in the current local keymap
941 (local-set-key KEY DEFINITION)
943 (define-key (current-local-map) KEY DEFINITION)
945 - Command: local-unset-key key
946 This function removes the binding of KEY from the current local
949 (local-unset-key KEY)
951 (define-key (current-local-map) KEY nil)
954 File: lispref.info, Node: Scanning Keymaps, Next: Other Keymap Functions, Prev: Key Binding Commands, Up: Keymaps
959 This section describes functions used to scan all the current
960 keymaps, or all keys within a keymap, for the sake of printing help
963 - Function: accessible-keymaps keymap &optional prefix
964 This function returns a list of all the keymaps that can be
965 accessed (via prefix keys) from KEYMAP. The value is an
966 association list with elements of the form `(KEY . MAP)', where
967 KEY is a prefix key whose definition in KEYMAP is MAP.
969 The elements of the alist are ordered so that the KEY increases in
970 length. The first element is always `([] . KEYMAP)', because the
971 specified keymap is accessible from itself with a prefix of no
974 If PREFIX is given, it should be a prefix key sequence; then
975 `accessible-keymaps' includes only the submaps whose prefixes start
976 with PREFIX. These elements look just as they do in the value of
977 `(accessible-keymaps)'; the only difference is that some elements
980 In the example below, the returned alist indicates that the key
981 `C-x', which is displayed as `[(control x)]', is a prefix key
982 whose definition is the keymap `#<keymap ((control x) #<keymap
983 emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
984 notation for the keymap's name indicates that this is an internal
985 submap of `emacs-lisp-mode-map'. This is because
986 `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
987 its parent, and `lisp-interaction-mode-map' defines no key
988 sequences beginning with `C-x'.)
991 => #<keymap lisp-interaction-mode-map 5 entries 0x558>
992 (accessible-keymaps (current-local-map))
993 =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
995 #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
998 The following example shows the results of calling
999 `accessible-keymaps' on a large, complex keymap. Notice how some
1000 keymaps were given explicit names using `set-keymap-name'; those
1001 submaps without explicit names are given descriptive names
1002 indicating their relationship to their enclosing keymap.
1004 (accessible-keymaps (current-global-map))
1005 => (([] . #<keymap global-map 639 entries 0x221>)
1006 ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
1007 ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
1008 ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
1010 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1012 ([(meta control \[)] .
1013 #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
1015 ([f1] . #<keymap help-map 33 entries 0x4ec>)
1016 ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
1017 ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
1018 ([(control x) \6] . #<keymap 13 entries 0x4d2>)
1020 #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1022 ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
1023 ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
1024 ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
1025 ([(control x) a i] .
1026 #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
1030 - Function: map-keymap function keymap &optional sort-first
1031 This function applies FUNCTION to each element of KEYMAP.
1032 FUNCTION will be called with two arguments: a key-description
1033 list, and the binding. The order in which the elements of the
1034 keymap are passed to the function is unspecified. If the function
1035 inserts new elements into the keymap, it may or may not be called
1036 with them later. No element of the keymap will ever be passed to
1037 the function more than once.
1039 The function will not be called on elements of this keymap's
1040 parents (*note Inheritance and Keymaps::) or upon keymaps which
1041 are contained within this keymap (multi-character definitions).
1042 It will be called on <META> characters since they are not really
1043 two-character sequences.
1045 If the optional third argument SORT-FIRST is non-`nil', then the
1046 elements of the keymap will be passed to the mapper function in a
1047 canonical order. Otherwise, they will be passed in hash (that is,
1048 random) order, which is faster.
1050 - Function: keymap-fullness keymap
1051 This function returns the number of bindings in the keymap.
1053 - Function: where-is-internal definition &optional keymaps firstonly
1054 noindirect event-or-keys
1055 This function returns a list of key sequences (of any length) that
1056 are bound to DEFINITION in a set of keymaps.
1058 The argument DEFINITION can be any object; it is compared with all
1059 keymap entries using `eq'.
1061 KEYMAPS can be either a keymap (meaning search in that keymap and
1062 the current global keymap) or a list of keymaps (meaning search in
1063 exactly those keymaps and no others). If KEYMAPS is nil, search
1064 in the currently applicable maps for EVENT-OR-KEYS.
1066 If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the
1067 global keymap. If KEYMAPS is a list of keymaps, then the maps
1068 searched are exactly those keymaps, and no others. If KEYMAPS is
1069 `nil', then the maps used are the current active keymaps for
1070 EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
1071 EVENT-OR-KEYS)' as the argument to KEYMAPS).
1073 If FIRSTONLY is non-`nil', then the value is a single vector
1074 representing the first key sequence found, rather than a list of
1075 all possible key sequences.
1077 If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
1078 indirect keymap bindings. This makes it possible to search for an
1079 indirect definition itself.
1081 This function is used by `where-is' (*note Help: (xemacs)Help.).
1083 (where-is-internal 'describe-function)
1084 => ([(control h) d] [(control h) f] [f1 d] [f1 f])
1086 - Function: describe-bindings-internal map &optional all shadow prefix
1088 This function inserts (into the current buffer) a list of all
1089 defined keys and their definitions in MAP. Optional second
1090 argument ALL says whether to include even "uninteresting"
1091 definitions, i.e. symbols with a non-`nil' `suppress-keymap'
1092 property. Third argument SHADOW is a list of keymaps whose
1093 bindings shadow those of map; if a binding is present in any
1094 shadowing map, it is not printed. Fourth argument PREFIX, if
1095 non-`nil', should be a key sequence; only bindings which start
1096 with that key sequence will be printed. Fifth argument
1097 MOUSE-ONLY-P says to only print bindings for mouse clicks.
1099 `describe-bindings-internal' is used to implement the help command
1100 `describe-bindings'.
1102 - Command: describe-bindings &optional prefix mouse-only-p
1103 This function creates a listing of all defined keys and their
1104 definitions. It writes the listing in a buffer named `*Help*' and
1105 displays it in a window.
1107 If optional argument PREFIX is non-`nil', it should be a prefix
1108 key; then the listing includes only keys that start with PREFIX.
1110 When several characters with consecutive ASCII codes have the same
1111 definition, they are shown together, as `FIRSTCHAR..LASTCHAR'. In
1112 this instance, you need to know the ASCII codes to understand
1113 which characters this means. For example, in the default global
1114 map, the characters `<SPC> .. ~' are described by a single line.
1115 <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
1116 them include all the normal printing characters, (e.g., letters,
1117 digits, punctuation, etc.); all these characters are bound to
1118 `self-insert-command'.
1120 If the second optional argument MOUSE-ONLY-P (prefix arg,
1121 interactively) is non-`nil' then only the mouse bindings are
1125 File: lispref.info, Node: Other Keymap Functions, Prev: Scanning Keymaps, Up: Keymaps
1127 Other Keymap Functions
1128 ======================
1130 - Function: set-keymap-prompt keymap new-prompt
1131 This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
1132 `nil' if no prompt is desired. The prompt is shown in the
1133 echo-area when reading a key-sequence to be looked-up in this
1136 - Function: keymap-prompt keymap &optional use-inherited
1137 This function returns the "prompt" of the given keymap. If
1138 USE-INHERITED is non-`nil', any parent keymaps will also be
1139 searched for a prompt.
1142 File: lispref.info, Node: Menus, Next: Dialog Boxes, Prev: Keymaps, Up: Top
1149 * Menu Format:: Format of a menu description.
1150 * Menubar Format:: How to specify a menubar.
1151 * Menubar:: Functions for controlling the menubar.
1152 * Modifying Menus:: Modifying a menu description.
1153 * Pop-Up Menus:: Functions for specifying pop-up menus.
1154 * Menu Filters:: Filter functions for the default menubar.
1155 * Menu Accelerators:: Using and controlling menu accelerator keys
1156 * Buffers Menu:: The menu that displays the list of buffers.
projects / chise / xemacs-chise.git- / blob