-\1f
-File: xemacs.info, Node: Keymaps, Next: Rebinding, Up: Key Bindings
-
-Keymaps
--------
-
- The bindings between characters and command functions are recorded in
-data structures called "keymaps". Emacs has many of these. One, the
-"global" keymap, defines the meanings of the single-character keys that
-are defined regardless of major mode. It is the value of the variable
-`global-map'.
-
- Each major mode has another keymap, its "local keymap", which
-contains overriding definitions for the single-character keys that are
-redefined in that mode. Each buffer records which local keymap is
-installed for it at any time, and the current buffer's local keymap is
-the only one that directly affects command execution. The local keymaps
-for Lisp mode, C mode, and many other major modes always exist even when
-not in use. They are the values of the variables `lisp-mode-map',
-`c-mode-map', and so on. For less frequently used major modes, the
-local keymap is sometimes constructed only when the mode is used for the
-first time in a session, to save space.
-
- There are local keymaps for the minibuffer, too; they contain various
-completion and exit commands.
-
- * `minibuffer-local-map' is used for ordinary input (no completion).
-
- * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
- like <RET>. This is used mainly for Mocklisp compatibility.
-
- * `minibuffer-local-completion-map' is for permissive completion.
-
- * `minibuffer-local-must-match-map' is for strict completion and for
- cautious completion.
-
- * `repeat-complex-command-map' is for use in `C-x <ESC>'.
-
- * `isearch-mode-map' contains the bindings of the special keys which
- are bound in the pseudo-mode entered with `C-s' and `C-r'.
-
- Finally, each prefix key has a keymap which defines the key sequences
-that start with it. For example, `ctl-x-map' is the keymap used for
-characters following a `C-x'.
-
- * `ctl-x-map' is the variable name for the map used for characters
- that follow `C-x'.
-
- * `help-map' is used for characters that follow `C-h'.
-
- * `esc-map' is for characters that follow <ESC>. All Meta characters
- are actually defined by this map.
-
- * `ctl-x-4-map' is for characters that follow `C-x 4'.
-
- * `mode-specific-map' is for characters that follow `C-c'.
-
- The definition of a prefix key is the keymap to use for looking up
-the following character. Sometimes the definition is actually a Lisp
-symbol whose function definition is the following character keymap. The
-effect is the same, but it provides a command name for the prefix key
-that you can use as a description of what the prefix key is for. Thus
-the binding of `C-x' is the symbol `Ctl-X-Prefix', whose function
-definition is the keymap for `C-x' commands, the value of `ctl-x-map'.
-
- Prefix key definitions can appear in either the global map or a
-local map. 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 modes can locally redefine a key as a prefix by
-putting a prefix key definition for it in the local map.
-
- A mode can also put a prefix definition of a global prefix character
-such as `C-x' into its local map. This is how major modes override the
-definitions of certain keys that start with `C-x'. This case is
-special, because the local definition does not entirely replace the
-global one. When both the global and local definitions of a key are
-other keymaps, the next character is looked up in both keymaps, with
-the local definition overriding the global one. The character after the
-`C-x' is looked up in both the major mode's own keymap for redefined
-`C-x' commands and in `ctl-x-map'. If the major mode's own keymap for
-`C-x' commands contains `nil', the definition from the global keymap
-for `C-x' commands is used.
-
-\1f
-File: xemacs.info, Node: Rebinding, Next: Disabling, Prev: Keymaps, Up: Key Bindings
-
-Changing Key Bindings
----------------------
-
- You can redefine an Emacs key by changing its entry in a keymap.
-You can change the global keymap, in which case the change is effective
-in all major modes except those that have their own overriding local
-definitions for the same key. Or you can change the current buffer's
-local map, which affects all buffers using the same major mode.
-
-* Menu:
-
-* Interactive Rebinding:: Changing Key Bindings Interactively
-* Programmatic Rebinding:: Changing Key Bindings Programmatically
-* Key Bindings Using Strings:: Using Strings for Changing Key Bindings
-
-\1f
-File: xemacs.info, Node: Interactive Rebinding, Next: Programmatic Rebinding, Up: Rebinding
-
-Changing Key Bindings Interactively
-...................................
-
-`M-x global-set-key <RET> KEY CMD <RET>'
- Defines KEY globally to run CMD.
-
-`M-x local-set-key <RET> KEYS CMD <RET>'
- Defines KEY locally (in the major mode now in effect) to run CMD.
-
-`M-x local-unset-key <RET> KEYS <RET>'
- Removes the local binding of KEY.
-
- CMD is a symbol naming an interactively-callable function.
-
- When called interactively, KEY is the next complete key sequence
-that you type. When called as a function, KEY is a string, a vector of
-events, or a vector of key-description lists as described in the
-`define-key' function description. The binding goes in the current
-buffer's local map, which is shared with other buffers in the same
-major mode.
-
- The following example:
-
- M-x global-set-key <RET> C-f next-line <RET>
-
-redefines `C-f' to move down a line. The fact that CMD is read second
-makes it serve as a kind of confirmation for KEY.
-
- These functions offer no way to specify a particular prefix keymap as
-the one to redefine in, but that is not necessary, as you can include
-prefixes in KEY. KEY is read by reading characters one by one until
-they amount to a complete key (that is, not a prefix key). Thus, if
-you type `C-f' for KEY, Emacs enters the minibuffer immediately to read
-CMD. But if you type `C-x', another character is read; if that
-character is `4', another character is read, and so on. For example,
-
- M-x global-set-key <RET> C-x 4 $ spell-other-window <RET>
-
-redefines `C-x 4 $' to run the (fictitious) command
-`spell-other-window'.
-
- The most general way to modify a keymap is the function
-`define-key', used in Lisp code (such as your init file). `define-key'
-takes three arguments: the keymap, the key to modify in it, and the new
-definition. *Note Init File::, for an example.
-`substitute-key-definition' is used similarly; it takes three
-arguments, an old definition, a new definition, and a keymap, and
-redefines in that keymap all keys that were previously defined with the
-old definition to have the new definition instead.
-
-\1f
-File: xemacs.info, Node: Programmatic Rebinding, Next: Key Bindings Using Strings, Prev: Interactive Rebinding, Up: Rebinding
-
-Changing Key Bindings Programmatically
-......................................
-
- You can use the functions `global-set-key' and `define-key' to
-rebind keys under program control.
-
-``(global-set-key KEYS CMD)''
- Defines KEYS globally to run CMD.
-
-``(define-key KEYMAP KEYS DEF)''
- Defines KEYS to run DEF in the keymap KEYMAP.
-
- KEYMAP is a keymap object.
-
- KEYS is the sequence of keystrokes to bind.
-
- DEF is anything that can be a key's definition:
-
- * `nil', meaning key is undefined in this keymap
-
- * A command, that is, a Lisp function suitable for interactive
- calling
-
- * A string or key sequence vector, which is treated as a keyboard
- macro
-
- * A keymap to define a prefix key
-
- * A symbol so that when the key is looked up, the symbol stands for
- its function definition, which should at that time be one of the
- above, or another symbol whose function definition is used, and so
- on
-
- * A cons, `(string . defn)', meaning that DEFN is the definition
- (DEFN should be a valid definition in its own right)
-
- * A cons, `(keymap . char)', meaning use the definition of CHAR in
- map KEYMAP
-
- For backward compatibility, XEmacs allows you to specify key
-sequences as strings. However, the preferred method is to use the
-representations of key sequences as vectors of keystrokes. *Note
-Keystrokes::, for more information about the rules for constructing key
-sequences.
-
- Emacs allows you to abbreviate representations for key sequences in
-most places where there is no ambiguity. Here are some rules for
-abbreviation:
-
- * The keysym by itself is equivalent to a list of just that keysym,
- i.e., `f1' is equivalent to `(f1)'.
-
- * A keystroke by itself is equivalent to a vector containing just
- that keystroke, i.e., `(control a)' is equivalent to `[(control
- a)]'.
-
- * You can use ASCII codes for keysyms that have them. i.e., `65' is
- equivalent to `A'. (This is not so much an abbreviation as an
- alternate representation.)
-
- Here are some examples of programmatically binding keys:
-
-
- ;;; Bind `my-command' to <f1>
- (global-set-key 'f1 'my-command)
-
- ;;; Bind `my-command' to Shift-f1
- (global-set-key '(shift f1) 'my-command)
-
- ;;; Bind `my-command' to C-c Shift-f1
- (global-set-key '[(control c) (shift f1)] 'my-command)
-
- ;;; Bind `my-command' to the middle mouse button.
- (global-set-key 'button2 'my-command)
-
- ;;; Bind `my-command' to <META> <CTL> <Right Mouse Button>
- ;;; in the keymap that is in force when you are running `dired'.
- (define-key dired-mode-map '(meta control button3) 'my-command)
-
-\1f
-File: xemacs.info, Node: Key Bindings Using Strings, Prev: Programmatic Rebinding, Up: Rebinding
-
-Using Strings for Changing Key Bindings
-.......................................
-
- For backward compatibility, you can still use strings to represent
-key sequences. Thus you can use commands like the following:
-
- ;;; Bind `end-of-line' to C-f
- (global-set-key "\C-f" 'end-of-line)
-
- Note, however, that in some cases you may be binding more than one
-key sequence by using a single command. This situation can arise
-because in ASCII, `C-i' and <TAB> have the same representation.
-Therefore, when Emacs sees:
-
- (global-set-key "\C-i" 'end-of-line)
-
- it is unclear whether the user intended to bind `C-i' or <TAB>. The
-solution XEmacs adopts is to bind both of these key sequences.
-
- 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)
-
- This applies only when running under a window system. If you are
-talking to Emacs through an ASCII-only channel, you do not get any of
-these features.
-
- Here is a table of pairs of key sequences that behave in a similar
-fashion:
-
- control h backspace
- control l clear
- control i tab
- control m return
- control j linefeed
- control [ escape
- control @ control space
-