-\1f
-File: lispref.info, Node: Key Sequences, Next: Prefix Keys, Prev: Inheritance and Keymaps, Up: Keymaps
-
-Key Sequences
-=============
-
- Contrary to popular belief, the world is not ASCII. When running
-under a window manager, XEmacs can tell the difference between, for
-example, the keystrokes `control-h', `control-shift-h', and
-`backspace'. You can, in fact, bind different commands to each of
-these.
-
- A "key sequence" is a set of keystrokes. A "keystroke" is a keysym
-and some set of modifiers (such as <CONTROL> and <META>). A "keysym"
-is what is printed on the keys on your keyboard.
-
- A keysym may be represented by a symbol, or (if and only if it is
-equivalent to an ASCII character in the range 32 - 255) by a character
-or its equivalent ASCII code. The `A' key may be represented by the
-symbol `A', the character `?A', or by the number 65. The `break' key
-may be represented only by the symbol `break'.
-
- A keystroke may be represented by a list: the last element of the
-list is the key (a symbol, character, or number, as above) and the
-preceding elements are the symbolic names of modifier keys (<CONTROL>,
-<META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>). Thus, the sequence
-`control-b' is represented by the forms `(control b)', `(control ?b)',
-and `(control 98)'. A keystroke may also be represented by an event
-object, as returned by the `next-command-event' and `read-key-sequence'
-functions.
-
- Note that in this context, the keystroke `control-b' is *not*
-represented by the number 2 (the ASCII code for `^B') or the character
-`?\^B'. See below.
-
- The <SHIFT> modifier is somewhat of a special case. You should not
-(and cannot) use `(meta shift a)' to mean `(meta A)', since for
-characters that have ASCII equivalents, the state of the shift key is
-implicit in the keysym (`a' vs. `A'). You also cannot say `(shift =)'
-to mean `+', as that sort of thing varies from keyboard to keyboard.
-The <SHIFT> modifier is for use only with characters that do not have a
-second keysym on the same key, such as `backspace' and `tab'.
-
- A key sequence is a vector of keystrokes. As a degenerate case,
-elements of this vector may also be keysyms if they have no modifiers.
-That is, the `A' keystroke is represented by all of these forms:
-
- A ?A 65 (A) (?A) (65)
- [A] [?A] [65] [(A)] [(?A)] [(65)]
-
- the `control-a' keystroke is represented by these forms:
-
- (control A) (control ?A) (control 65)
- [(control A)] [(control ?A)] [(control 65)]
-
- the key sequence `control-c control-a' is represented by these forms:
-
- [(control c) (control a)] [(control ?c) (control ?a)]
- [(control 99) (control 65)] etc.
-
- Mouse button clicks work just like keypresses: `(control button1)'
-means pressing the left mouse button while holding down the control
-key. `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
-click right.
-
- Commands may be bound to the mouse-button up-stroke rather than the
-down-stroke as well. `button1' means the down-stroke, and `button1up'
-means the up-stroke. Different commands may be bound to the up and
-down strokes, though that is probably not what you want, so be careful.
-
- For backward compatibility, a key sequence may also be represented by
-a string. In this case, it represents the key sequence(s) that would
-produce that sequence of ASCII characters in a purely ASCII world. For
-example, a string containing the ASCII backspace character, `"\^H"',
-would represent two key sequences: `(control h)' and `backspace'.
-Binding a command to this will actually bind both of those key
-sequences. Likewise for the following pairs:
-
- control h backspace
- control i tab
- control m return
- control j linefeed
- control [ escape
- control @ control space
-
- After binding a command to two key sequences with a form like
-
- (define-key global-map "\^X\^I" 'command-1)
-
-it is possible to redefine only one of those sequences like so:
-
- (define-key global-map [(control x) (control i)] 'command-2)
- (define-key global-map [(control x) tab] 'command-3)
-
- Of course, all of this applies only when running under a window
-system. If you're talking to XEmacs through a TTY connection, you
-don't get any of these features.
-
- - Function: event-matches-key-specifier-p EVENT KEY-SPECIFIER
- This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
- which can be any valid form representing a key sequence. This can
- be useful, e.g., to determine if the user pressed `help-char' or
- `quit-char'.
-
-\1f
-File: lispref.info, Node: Prefix Keys, Next: Active Keymaps, Prev: Key Sequences, Up: Keymaps
-
-Prefix Keys
-===========
-
- A "prefix key" has an associated keymap that defines what to do with
-key sequences that start with the prefix key. For example, `C-x' is a
-prefix key, and it uses a keymap that is also stored in the variable
-`ctl-x-map'. Here is a list of the standard prefix keys of XEmacs and
-their keymaps:
-
- * `help-map' is used for events that follow `C-h'.
-
- * `mode-specific-map' is for events that follow `C-c'. This map is
- not actually mode specific; its name was chosen to be informative
- for the user in `C-h b' (`display-bindings'), where it describes
- the main use of the `C-c' prefix key.
-
- * `ctl-x-map' is the map used for events that follow `C-x'. This
- map is also the function definition of `Control-X-prefix'.
-
- * `ctl-x-4-map' is used for events that follow `C-x 4'.
-
- * `ctl-x-5-map' is used for events that follow `C-x 5'.
-
- * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
- no special name.
-
- * `esc-map' is an evil hack that is present for compatibility
- purposes with Emacs 18. Defining a key in `esc-map' is equivalent
- to defining the same key in `global-map' but with the <META>
- prefix added. You should *not* use this in your code. (This map is
- also the function definition of `ESC-prefix'.)
-
- The binding of a prefix key is the keymap to use for looking up the
-events that follow the prefix key. (It may instead be a symbol whose
-function definition is a keymap. The effect is the same, but the symbol
-serves as a name for the prefix key.) Thus, the binding of `C-x' is
-the symbol `Control-X-prefix', whose function definition is the keymap
-for `C-x' commands. (The same keymap is also the value of `ctl-x-map'.)
-
- Prefix key definitions can appear in any active keymap. The
-definitions of `C-c', `C-x', `C-h' and <ESC> as prefix keys appear in
-the global map, so these prefix keys are always available. Major and
-minor modes can redefine a key as a prefix by putting a prefix key
-definition for it in the local map or the minor mode's map. *Note
-Active Keymaps::.
-
- If a key is defined as a prefix in more than one active map, then its
-various definitions are in effect merged: the commands defined in the
-minor mode keymaps come first, followed by those in the local map's
-prefix definition, and then by those from the global map.
-
- In the following example, we make `C-p' a prefix key in the local
-keymap, in such a way that `C-p' is identical to `C-x'. Then the
-binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
-The key sequence `C-p 6' is not found in any active keymap.
-
- (use-local-map (make-sparse-keymap))
- => nil
- (local-set-key "\C-p" ctl-x-map)
- => nil
- (key-binding "\C-p\C-f")
- => find-file
-
- (key-binding "\C-p6")
- => nil
-
- - Function: define-prefix-command SYMBOL &optional MAPVAR
- This function defines SYMBOL as a prefix command: it creates a
- keymap and stores it as SYMBOL's function definition. Storing the
- symbol as the binding of a key makes the key a prefix key that has
- a name. If optional argument MAPVAR is not specified, it also
- sets SYMBOL as a variable, to have the keymap as its value. (If
- MAPVAR is given and is not `t', its value is stored as the value
- of SYMBOL.) The function returns SYMBOL.
-
- In Emacs version 18, only the function definition of SYMBOL was
- set, not the value as a variable.
-
-\1f
-File: lispref.info, Node: Active Keymaps, Next: Key Lookup, Prev: Prefix Keys, Up: Keymaps
-
-Active Keymaps
-==============
-
- XEmacs normally contains many keymaps; at any given time, just a few
-of them are "active" in that they participate in the interpretation of
-user input. These are the global keymap, the current buffer's local
-keymap, and the keymaps of any enabled minor modes.
-
- The "global keymap" holds the bindings of keys that are defined
-regardless of the current buffer, such as `C-f'. The variable
-`global-map' holds this keymap, which is always active.
-
- Each buffer may have another keymap, its "local keymap", which may
-contain new or overriding definitions for keys. The current buffer's
-local keymap is always active except when `overriding-local-map' or
-`overriding-terminal-local-map' overrides it. Extents and text
-properties can specify an alternative local map for certain parts of the
-buffer; see *Note Extents and Events::.
-
- Each minor mode may have a keymap; if it does, the keymap is active
-when the minor mode is enabled.
-
- The variable `overriding-local-map' and
-`overriding-terminal-local-map', if non-`nil', specify other local
-keymaps that override the buffer's local map and all the minor mode
-keymaps.
-
- All the active keymaps are used together to determine what command to
-execute when a key is entered. XEmacs searches these maps one by one,
-in order of decreasing precedence, until it finds a binding in one of
-the maps.
-
- More specifically:
-
- For key-presses, the order of keymaps searched is:
-
- * the `keymap' property of any extent(s) or text properties at point;
-
- * any applicable minor-mode maps;
-
- * the current local map of the current buffer;
-
- * the current global map.
-
- For mouse-clicks, the order of keymaps searched is:
-
- * the current local map of the `mouse-grabbed-buffer' if any;
-
- * the `keymap' property of any extent(s) at the position of the click
- (this includes modeline extents);
-
- * the `modeline-map' of the buffer corresponding to the modeline
- under the mouse (if the click happened over a modeline);
-
- * the value of `toolbar-map' in the current buffer (if the click
- happened over a toolbar);
-
- * the current local map of the buffer under the mouse (does not
- apply to toolbar clicks);
-
- * any applicable minor-mode maps;
-
- * the current global map.
-
- Note that if `overriding-local-map' or
-`overriding-terminal-local-map' is non-`nil', *only* those two maps and
-the current global map are searched.
-
- The procedure for searching a single keymap is called "key lookup";
-see *Note Key Lookup::.
-
- Since every buffer that uses the same major mode normally uses the
-same local keymap, you can think of the keymap as local to the mode. A
-change to the local keymap of a buffer (using `local-set-key', for
-example) is seen also in the other buffers that share that keymap.
-
- The local keymaps that are used for Lisp mode, C mode, and several
-other major modes exist even if they have not yet been used. These
-local maps are the values of the variables `lisp-mode-map',
-`c-mode-map', and so on. For most other modes, which are less
-frequently used, the local keymap is constructed only when the mode is
-used for the first time in a session.
-
- The minibuffer has local keymaps, too; they contain various
-completion and exit commands. *Note Intro to Minibuffers::.
-
- *Note Standard Keymaps::, for a list of standard keymaps.
-
- - Function: current-keymaps &optional EVENT-OR-KEYS
- This function returns a list of the current keymaps that will be
- searched for bindings. This lists keymaps such as the current
- local map and the minor-mode maps, but does not list the parents
- of those keymaps. EVENT-OR-KEYS controls which keymaps will be
- listed. If EVENT-OR-KEYS is a mouse event (or a vector whose last
- element is a mouse event), the keymaps for that mouse event will
- be listed. Otherwise, the keymaps for key presses will be listed.
-
- - Variable: global-map
- This variable contains the default global keymap that maps XEmacs
- keyboard input to commands. The global keymap is normally this
- keymap. The default global keymap is a full keymap that binds
- `self-insert-command' to all of the printing characters.
-
- It is normal practice to change the bindings in the global map,
- but you should not assign this variable any value other than the
- keymap it starts out with.
-
- - Function: current-global-map
- This function returns the current global keymap. This is the same
- as the value of `global-map' unless you change one or the other.
-
- (current-global-map)
- => #<keymap global-map 639 entries 0x221>
-
- - Function: current-local-map
- This function returns the current buffer's local keymap, or `nil'
- if it has none. In the following example, the keymap for the
- `*scratch*' buffer (using Lisp Interaction mode) has a number of
- entries, including one prefix key, `C-x'.
-
- (current-local-map)
- => #<keymap lisp-interaction-mode-map 5 entries 0x558>
- (describe-bindings-internal (current-local-map))
- => ; Inserted into the buffer:
- backspace backward-delete-char-untabify
- linefeed eval-print-last-sexp
- delete delete-char
- C-j eval-print-last-sexp
- C-x << Prefix Command >>
- M-tab lisp-complete-symbol
- M-; lisp-indent-for-comment
- M-C-i lisp-complete-symbol
- M-C-q indent-sexp
- M-C-x eval-defun
- Alt-backspace backward-kill-sexp
- Alt-delete kill-sexp
-
- C-x x edebug-defun
-
- - Function: current-minor-mode-maps
- This function returns a list of the keymaps of currently enabled
- minor modes.
-
- - Function: use-global-map KEYMAP
- This function makes KEYMAP the new current global keymap. It
- returns `nil'.
-
- It is very unusual to change the global keymap.
-
- - Function: use-local-map KEYMAP &optional BUFFER
- This function makes KEYMAP the new local keymap of BUFFER. BUFFER
- defaults to the current buffer. If KEYMAP is `nil', then the
- buffer has no local keymap. `use-local-map' returns `nil'. Most
- major mode commands use this function.
-
- - Variable: minor-mode-map-alist
- This variable is an alist describing keymaps that may or may not be
- active according to the values of certain variables. Its elements
- look like this:
-
- (VARIABLE . KEYMAP)
-
- The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
- value. Typically VARIABLE is the variable that enables or
- disables a minor mode. *Note Keymaps and Minor Modes::.
-
- Note that elements of `minor-mode-map-alist' do not have the same
- structure as elements of `minor-mode-alist'. The map must be the
- CDR of the element; a list with the map as the second element will
- not do.
-
- What's more, the keymap itself must appear in the CDR. It does not
- work to store a variable in the CDR and make the map the value of
- that variable.
-
- When more than one minor mode keymap is active, their order of
- priority is the order of `minor-mode-map-alist'. But you should
- design minor modes so that they don't interfere with each other.
- If you do this properly, the order will not matter.
-
- See also `minor-mode-key-binding', above. See *Note Keymaps and
- Minor Modes::, for more information about minor modes.
-
- - Variable: modeline-map
- This variable holds the keymap consulted for mouse-clicks on the
- modeline of a window. This variable may be buffer-local; its
- value will be looked up in the buffer of the window whose modeline
- was clicked upon.
-
- - Variable: toolbar-map
- This variable holds the keymap consulted for mouse-clicks over a
- toolbar.
-
- - Variable: mouse-grabbed-buffer
- If non-`nil', a buffer which should be consulted first for all
- mouse activity. When a mouse-click is processed, it will first be
- looked up in the local-map of this buffer, and then through the
- normal mechanism if there is no binding for that click. This
- buffer's value of `mode-motion-hook' will be consulted instead of
- the `mode-motion-hook' of the buffer of the window under the mouse.
- You should *bind* this, not set it.
-
- - Variable: overriding-local-map
- If non-`nil', this variable holds a keymap to use instead of the
- buffer's local keymap and instead of all the minor mode keymaps.
- This keymap, if any, overrides all other maps that would have been
- active, except for the current global map.
-
- - Variable: overriding-terminal-local-map
- If non-`nil', this variable holds a keymap to use instead of the
- buffer's local keymap and instead of all the minor mode keymaps,
- but for the selected console only. (In other words, this variable
- is always console-local; putting a keymap here only applies to
- keystrokes coming from the selected console. *Note Consoles and
- Devices::.) This keymap, if any, overrides all other maps that
- would have been active, except for the current global map.
-
projects / chise / xemacs-chise.git / blobdiff