Chapter 33: Customization
429
33.3.1 Keymaps As described in Section 2.3 [Commands], page 12, each Emacs command is a Lisp function whose definition provides for interactive use. Like every Lisp function, a command has a function name, which usually consists of lower-case letters and hyphens. A key sequence (key, for short) is a sequence of input events that have a meaning as a unit. Input events include characters, function keys and mouse buttons—all the inputs that you can send to the computer. A key sequence gets its meaning from its binding, which says what command it runs. The bindings between key sequences and command functions are recorded in data structures called keymaps. Emacs has many of these, each used on particular occasions. The global keymap is the most important keymap because it is always in effect. The global keymap defines keys for Fundamental mode (see Section 20.1 [Major Modes], page 198); most of these definitions are common to most or all major modes. Each major or minor mode can have its own keymap which overrides the global definitions of some keys. For example, a self-inserting character such as g is self-inserting because the global keymap binds it to the command self-insert-command. The standard Emacs editing characters such as C-a also get their standard meanings from the global keymap. Commands to rebind keys, such as M-x global-set-key, work by storing the new binding in the proper place in the global map (see Section 33.3.5 [Rebinding], page 431). Most modern keyboards have function keys as well as character keys. Function keys send input events just as character keys do, and keymaps can have bindings for them. Key sequences can mix function keys and characters. For example, if your keyboard has a Home function key, Emacs can recognize key sequences like C-x Home. You can even mix mouse events with keyboard events, such as S-down-mouse-1. On text terminals, typing a function key actually sends the computer a sequence of characters; the precise details of the sequence depends on the function key and on the terminal type. (Often the sequence starts with ESC [.) If Emacs understands your terminal type properly, it automatically handles such sequences as single input events.
33.3.2 Prefix Keymaps Internally, Emacs records only single events in each keymap. Interpreting a key sequence of multiple events involves a chain of keymaps: the first keymap gives a definition for the first event, which is another keymap, which is used to look up the second event in the sequence, and so on. Thus, a prefix key such as C-x or ESC has its own keymap, which holds the definition for the event that immediately follows that prefix. The definition of a prefix key is usually the keymap to use for looking up the following event. The definition can also be a Lisp symbol whose function definition is the following keymap; the effect is the same, but it provides a command name for the prefix key that can be used as a description of what the prefix key is for. Thus, the binding of C-x is the symbol Control-X-prefix, whose function definition is the keymap for C-x commands. 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. Aside from ordinary prefix keys, there is a fictitious “prefix key” which represents the menu bar; see Section “Menu Bar” in The Emacs Lisp Reference Manual , for special infor-
429
33.3.1 Keymaps As described in Section 2.3 [Commands], page 12, each Emacs command is a Lisp function whose definition provides for interactive use. Like every Lisp function, a command has a function name, which usually consists of lower-case letters and hyphens. A key sequence (key, for short) is a sequence of input events that have a meaning as a unit. Input events include characters, function keys and mouse buttons—all the inputs that you can send to the computer. A key sequence gets its meaning from its binding, which says what command it runs. The bindings between key sequences and command functions are recorded in data structures called keymaps. Emacs has many of these, each used on particular occasions. The global keymap is the most important keymap because it is always in effect. The global keymap defines keys for Fundamental mode (see Section 20.1 [Major Modes], page 198); most of these definitions are common to most or all major modes. Each major or minor mode can have its own keymap which overrides the global definitions of some keys. For example, a self-inserting character such as g is self-inserting because the global keymap binds it to the command self-insert-command. The standard Emacs editing characters such as C-a also get their standard meanings from the global keymap. Commands to rebind keys, such as M-x global-set-key, work by storing the new binding in the proper place in the global map (see Section 33.3.5 [Rebinding], page 431). Most modern keyboards have function keys as well as character keys. Function keys send input events just as character keys do, and keymaps can have bindings for them. Key sequences can mix function keys and characters. For example, if your keyboard has a Home function key, Emacs can recognize key sequences like C-x Home. You can even mix mouse events with keyboard events, such as S-down-mouse-1. On text terminals, typing a function key actually sends the computer a sequence of characters; the precise details of the sequence depends on the function key and on the terminal type. (Often the sequence starts with ESC [.) If Emacs understands your terminal type properly, it automatically handles such sequences as single input events.
33.3.2 Prefix Keymaps Internally, Emacs records only single events in each keymap. Interpreting a key sequence of multiple events involves a chain of keymaps: the first keymap gives a definition for the first event, which is another keymap, which is used to look up the second event in the sequence, and so on. Thus, a prefix key such as C-x or ESC has its own keymap, which holds the definition for the event that immediately follows that prefix. The definition of a prefix key is usually the keymap to use for looking up the following event. The definition can also be a Lisp symbol whose function definition is the following keymap; the effect is the same, but it provides a command name for the prefix key that can be used as a description of what the prefix key is for. Thus, the binding of C-x is the symbol Control-X-prefix, whose function definition is the keymap for C-x commands. 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. Aside from ordinary prefix keys, there is a fictitious “prefix key” which represents the menu bar; see Section “Menu Bar” in The Emacs Lisp Reference Manual , for special infor-
Chapter 33: Customization
430
mation about menu bar key bindings. Mouse button events that invoke pop-up menus are also prefix keys; see Section “Menu Keymaps” in The Emacs Lisp Reference Manual , for more details. Some prefix keymaps are stored in variables with names: • ctl-x-map is the variable name for the map used for characters that follow C-x. • help-map is for characters that follow C-h. • esc-map is for characters that follow ESC. Thus, 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.
33.3.3 Local Keymaps So far, we have explained the ins and outs of the global map. Major modes customize Emacs by providing their own key bindings in local keymaps. For example, C mode overrides TAB to make it indent the current line for C code. Minor modes can also have local keymaps; whenever a minor mode is in effect, the definitions in its keymap override both the major mode’s local keymap and the global keymap. In addition, portions of text in the buffer can specify their own keymaps, which override all other keymaps. A local keymap can redefine a key as a prefix key by defining it as a prefix keymap. If the key is also defined globally as a prefix, its local and global definitions (both keymaps) effectively combine: both definitions are used to look up the event that follows the prefix key. For example, if a local keymap defines C-c as a prefix keymap, and that keymap defines C-z as a command, this provides a local meaning for C-c C-z. This does not affect other sequences that start with C-c; if those sequences don’t have their own local bindings, their global bindings remain in effect. Another way to think of this is that Emacs handles a multi-event key sequence by looking in several keymaps, one by one, for a binding of the whole key sequence. First it checks the minor mode keymaps for minor modes that are enabled, then it checks the major mode’s keymap, and then it checks the global keymap. This is not precisely how key lookup works, but it’s good enough for understanding the results in ordinary circumstances.
33.3.4 Minibuffer Keymaps The minibuffer has its own set of local keymaps; 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. • minibuffer-local-completion-map is for permissive completion. • minibuffer-local-must-match-map is for strict completion and for cautious completion. • minibuffer-local-filename-completion-map and minibuffer-local-filenamemust-match-map are like the two previous ones, but they are specifically for file name completion. They do not bind SPC.
430
mation about menu bar key bindings. Mouse button events that invoke pop-up menus are also prefix keys; see Section “Menu Keymaps” in The Emacs Lisp Reference Manual , for more details. Some prefix keymaps are stored in variables with names: • ctl-x-map is the variable name for the map used for characters that follow C-x. • help-map is for characters that follow C-h. • esc-map is for characters that follow ESC. Thus, 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.
33.3.3 Local Keymaps So far, we have explained the ins and outs of the global map. Major modes customize Emacs by providing their own key bindings in local keymaps. For example, C mode overrides TAB to make it indent the current line for C code. Minor modes can also have local keymaps; whenever a minor mode is in effect, the definitions in its keymap override both the major mode’s local keymap and the global keymap. In addition, portions of text in the buffer can specify their own keymaps, which override all other keymaps. A local keymap can redefine a key as a prefix key by defining it as a prefix keymap. If the key is also defined globally as a prefix, its local and global definitions (both keymaps) effectively combine: both definitions are used to look up the event that follows the prefix key. For example, if a local keymap defines C-c as a prefix keymap, and that keymap defines C-z as a command, this provides a local meaning for C-c C-z. This does not affect other sequences that start with C-c; if those sequences don’t have their own local bindings, their global bindings remain in effect. Another way to think of this is that Emacs handles a multi-event key sequence by looking in several keymaps, one by one, for a binding of the whole key sequence. First it checks the minor mode keymaps for minor modes that are enabled, then it checks the major mode’s keymap, and then it checks the global keymap. This is not precisely how key lookup works, but it’s good enough for understanding the results in ordinary circumstances.
33.3.4 Minibuffer Keymaps The minibuffer has its own set of local keymaps; 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. • minibuffer-local-completion-map is for permissive completion. • minibuffer-local-must-match-map is for strict completion and for cautious completion. • minibuffer-local-filename-completion-map and minibuffer-local-filenamemust-match-map are like the two previous ones, but they are specifically for file name completion. They do not bind SPC.
Chapter 33: Customization
431
33.3.5 Changing Key Bindings Interactively The way to redefine an Emacs key is to change 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 bindings for the same key). Or you can change a local keymap, which affects all buffers using the same major mode. In this section, we describe how to rebind keys for the present Emacs session. See Section 33.3.6 [Init Rebinding], page 432, for a description of how to make key rebindings affect future Emacs sessions. M-x global-set-key RET key cmd RET Define key globally to run cmd. M-x local-set-key RET key cmd RET Define key locally (in the major mode now in effect) to run cmd. M-x global-unset-key RET key Make key undefined in the global map. M-x local-unset-key RET key Make key undefined locally (in the major mode now in effect). For example, the following binds C-z to the shell command (see Section 31.4.2 [Interactive Shell], page 383), replacing the normal global definition of C-z: M-x global-set-key RET C-z shell RET The global-set-key command reads the command name after the key. After you press the key, a message like this appears so that you can confirm that you are binding the key you want: Set key C-z to command: You can redefine function keys and mouse events in the same way; just type the function key or click the mouse when it’s time to specify the key to rebind. You can rebind a key that contains more than one event in the same way. Emacs keeps reading the key to rebind until it is a complete key (that is, not a prefix key). Thus, if you type C-f for key, that’s the end; it enters the minibuffer immediately to read cmd. But if you type C-x, since that’s a prefix, it reads another character; if that is 4, another prefix character, it reads one more character, 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. You can remove the global definition of a key with global-unset-key. This makes the key undefined ; if you type it, Emacs will just beep. Similarly, local-unset-key makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode. If you have redefined (or undefined) a key and you subsequently wish to retract the change, undefining the key will not do the job—you need to redefine the key with its standard definition. To find the name of the standard definition of a key, go to a Fundamental mode buffer in a fresh Emacs and use C-h c. The documentation of keys in this manual also lists their command names.
431
33.3.5 Changing Key Bindings Interactively The way to redefine an Emacs key is to change 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 bindings for the same key). Or you can change a local keymap, which affects all buffers using the same major mode. In this section, we describe how to rebind keys for the present Emacs session. See Section 33.3.6 [Init Rebinding], page 432, for a description of how to make key rebindings affect future Emacs sessions. M-x global-set-key RET key cmd RET Define key globally to run cmd. M-x local-set-key RET key cmd RET Define key locally (in the major mode now in effect) to run cmd. M-x global-unset-key RET key Make key undefined in the global map. M-x local-unset-key RET key Make key undefined locally (in the major mode now in effect). For example, the following binds C-z to the shell command (see Section 31.4.2 [Interactive Shell], page 383), replacing the normal global definition of C-z: M-x global-set-key RET C-z shell RET The global-set-key command reads the command name after the key. After you press the key, a message like this appears so that you can confirm that you are binding the key you want: Set key C-z to command: You can redefine function keys and mouse events in the same way; just type the function key or click the mouse when it’s time to specify the key to rebind. You can rebind a key that contains more than one event in the same way. Emacs keeps reading the key to rebind until it is a complete key (that is, not a prefix key). Thus, if you type C-f for key, that’s the end; it enters the minibuffer immediately to read cmd. But if you type C-x, since that’s a prefix, it reads another character; if that is 4, another prefix character, it reads one more character, 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. You can remove the global definition of a key with global-unset-key. This makes the key undefined ; if you type it, Emacs will just beep. Similarly, local-unset-key makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode. If you have redefined (or undefined) a key and you subsequently wish to retract the change, undefining the key will not do the job—you need to redefine the key with its standard definition. To find the name of the standard definition of a key, go to a Fundamental mode buffer in a fresh Emacs and use C-h c. The documentation of keys in this manual also lists their command names.
Chapter 33: Customization
432
If you want to prevent yourself from invoking a command by mistake, it is better to disable the command than to undefine the key. A disabled command is less work to invoke when you really want to. See Section 33.3.11 [Disabling], page 437.
33.3.6 Rebinding Keys in Your Init File If you have a set of key bindings that you like to use all the time, you can specify them in your initialization file by writing Lisp code. See Section 33.4 [Init File], page 437, for a description of the initialization file. There are several ways to write a key binding using Lisp. The simplest is to use the kbd function, which converts a textual representation of a key sequence—similar to how we have written key sequences in this manual—into a form that can be passed as an argument to global-set-key. For example, here’s how to bind C-z to the shell command (see Section 31.4.2 [Interactive Shell], page 383): (global-set-key (kbd "C-z") ’shell) The single-quote before the command name, shell, marks it as a constant symbol rather than a variable. If you omit the quote, Emacs would try to evaluate shell as a variable. This probably causes an error; it certainly isn’t what you want. Here are some additional examples, including binding function keys and mouse events: (global-set-key (global-set-key (global-set-key (global-set-key (global-set-key (global-set-key
(kbd (kbd (kbd (kbd (kbd (kbd
"C-c y") ’clipboard-yank) "C-M-q") ’query-replace) "<f5>") ’flyspell-mode) "C-<f5>") ’linum-mode) "C-<right>") ’forward-sentence) "<mouse-2>") ’mouse-save-then-kill)
Instead of using kbd, you can use a Lisp string or vector to specify the key sequence. Using a string is simpler, but only works for ASCII characters and Meta-modified ASCII characters. For example, here’s how to bind C-x M-l to make-symbolic-link (see Section 15.10 [Misc File Ops], page 139): (global-set-key "\C-x\M-l" ’make-symbolic-link) To put TAB, RET, ESC, or DEL in the string, use the Emacs Lisp escape sequences ‘\t’, ‘\r’, ‘\e’, and ‘\d’ respectively. Here is an example which binds C-x TAB to indent-rigidly (see Chapter 21 [Indentation], page 204): (global-set-key "\C-x\t" ’indent-rigidly) When the key sequence includes function keys or mouse button events, or non-ASCII characters such as C-= or H-a, you can use a vector to specify the key sequence. Each element in the vector stands for an input event; the elements are separated by spaces and surrounded by a pair of square brackets. If a vector element is a character, write it as a Lisp character constant: ‘?’ followed by the character as it would appear in a string. Function keys are represented by symbols (see Section 33.3.8 [Function Keys], page 433); simply write the symbol’s name, with no other delimiters or punctuation. Here are some examples: (global-set-key (global-set-key (global-set-key (global-set-key
[?\C-=] ’make-symbolic-link) [?\M-\C-=] ’make-symbolic-link) [?\H-a] ’make-symbolic-link) [f7] ’make-symbolic-link)
432
If you want to prevent yourself from invoking a command by mistake, it is better to disable the command than to undefine the key. A disabled command is less work to invoke when you really want to. See Section 33.3.11 [Disabling], page 437.
33.3.6 Rebinding Keys in Your Init File If you have a set of key bindings that you like to use all the time, you can specify them in your initialization file by writing Lisp code. See Section 33.4 [Init File], page 437, for a description of the initialization file. There are several ways to write a key binding using Lisp. The simplest is to use the kbd function, which converts a textual representation of a key sequence—similar to how we have written key sequences in this manual—into a form that can be passed as an argument to global-set-key. For example, here’s how to bind C-z to the shell command (see Section 31.4.2 [Interactive Shell], page 383): (global-set-key (kbd "C-z") ’shell) The single-quote before the command name, shell, marks it as a constant symbol rather than a variable. If you omit the quote, Emacs would try to evaluate shell as a variable. This probably causes an error; it certainly isn’t what you want. Here are some additional examples, including binding function keys and mouse events: (global-set-key (global-set-key (global-set-key (global-set-key (global-set-key (global-set-key
(kbd (kbd (kbd (kbd (kbd (kbd
"C-c y") ’clipboard-yank) "C-M-q") ’query-replace) "<f5>") ’flyspell-mode) "C-<f5>") ’linum-mode) "C-<right>") ’forward-sentence) "<mouse-2>") ’mouse-save-then-kill)
Instead of using kbd, you can use a Lisp string or vector to specify the key sequence. Using a string is simpler, but only works for ASCII characters and Meta-modified ASCII characters. For example, here’s how to bind C-x M-l to make-symbolic-link (see Section 15.10 [Misc File Ops], page 139): (global-set-key "\C-x\M-l" ’make-symbolic-link) To put TAB, RET, ESC, or DEL in the string, use the Emacs Lisp escape sequences ‘\t’, ‘\r’, ‘\e’, and ‘\d’ respectively. Here is an example which binds C-x TAB to indent-rigidly (see Chapter 21 [Indentation], page 204): (global-set-key "\C-x\t" ’indent-rigidly) When the key sequence includes function keys or mouse button events, or non-ASCII characters such as C-= or H-a, you can use a vector to specify the key sequence. Each element in the vector stands for an input event; the elements are separated by spaces and surrounded by a pair of square brackets. If a vector element is a character, write it as a Lisp character constant: ‘?’ followed by the character as it would appear in a string. Function keys are represented by symbols (see Section 33.3.8 [Function Keys], page 433); simply write the symbol’s name, with no other delimiters or punctuation. Here are some examples: (global-set-key (global-set-key (global-set-key (global-set-key
[?\C-=] ’make-symbolic-link) [?\M-\C-=] ’make-symbolic-link) [?\H-a] ’make-symbolic-link) [f7] ’make-symbolic-link)
Chapter 33: Customization
433
(global-set-key [C-mouse-1] ’make-symbolic-link) You can use a vector for the simple cases too: (global-set-key [?\C-z ?\M-l] ’make-symbolic-link) Language and coding systems may cause problems with key bindings for non-ASCII characters. See Section 33.4.5 [Init Non-ASCII], page 442. As described in Section 33.3.3 [Local Keymaps], page 430, major modes and minor modes can define local keymaps. These keymaps are constructed when the mode is used for the first time in a session. If you wish to change one of these keymaps, you must use the mode hook (see Section 33.2.2 [Hooks], page 422). For example, Texinfo mode runs the hook texinfo-mode-hook. Here’s how you can use the hook to add local bindings for C-c n and C-c p in Texinfo mode: (add-hook ’texinfo-mode-hook (lambda () (define-key texinfo-mode-map "\C-cp" ’backward-paragraph) (define-key texinfo-mode-map "\C-cn" ’forward-paragraph)))
33.3.7 Modifier Keys The default key bindings in Emacs are set up so that modified alphabetical characters are case-insensitive. In other words, C-A does the same thing as C-a, and M-A does the same thing as M-a. This concerns only alphabetical characters, and does not apply to “shifted” versions of other keys; for instance, C-@ is not the same as C-2. A Control-modified alphabetical character is always considered case-insensitive: Emacs always treats C-A as C-a, C-B as C-b, and so forth. The reason for this is historical. For all other modifiers, you can make the modified alphabetical characters case-sensitive when you customize Emacs. For instance, you could make M-a and M-A run different commands. Although only the Control and META modifier keys are commonly used, Emacs supports three other modifier keys. These are called Super, Hyper and Alt. Few terminals provide ways to use these modifiers; the key labeled Alt on most keyboards usually issues the META modifier, not Alt. The standard key bindings in Emacs do not include any characters with these modifiers. However, you can customize Emacs to assign meanings to them. The modifier bits are labeled as ‘s-’, ‘H-’ and ‘A-’ respectively. Even if your keyboard lacks these additional modifier keys, you can enter it using C-x @: C-x @ h adds the “hyper” flag to the next character, C-x @ s adds the “super” flag, and C-x @ a adds the “alt” flag. For instance, C-x @ h C-a is a way to enter Hyper-Control-a. (Unfortunately, there is no way to add two modifiers by using C-x @ twice for the same character, because the first one goes to work on the C-x.)
33.3.8 Rebinding Function Keys Key sequences can contain function keys as well as ordinary characters. Just as Lisp characters (actually integers) represent keyboard characters, Lisp symbols represent function keys. If the function key has a word as its label, then that word is also the name of the
433
(global-set-key [C-mouse-1] ’make-symbolic-link) You can use a vector for the simple cases too: (global-set-key [?\C-z ?\M-l] ’make-symbolic-link) Language and coding systems may cause problems with key bindings for non-ASCII characters. See Section 33.4.5 [Init Non-ASCII], page 442. As described in Section 33.3.3 [Local Keymaps], page 430, major modes and minor modes can define local keymaps. These keymaps are constructed when the mode is used for the first time in a session. If you wish to change one of these keymaps, you must use the mode hook (see Section 33.2.2 [Hooks], page 422). For example, Texinfo mode runs the hook texinfo-mode-hook. Here’s how you can use the hook to add local bindings for C-c n and C-c p in Texinfo mode: (add-hook ’texinfo-mode-hook (lambda () (define-key texinfo-mode-map "\C-cp" ’backward-paragraph) (define-key texinfo-mode-map "\C-cn" ’forward-paragraph)))
33.3.7 Modifier Keys The default key bindings in Emacs are set up so that modified alphabetical characters are case-insensitive. In other words, C-A does the same thing as C-a, and M-A does the same thing as M-a. This concerns only alphabetical characters, and does not apply to “shifted” versions of other keys; for instance, C-@ is not the same as C-2. A Control-modified alphabetical character is always considered case-insensitive: Emacs always treats C-A as C-a, C-B as C-b, and so forth. The reason for this is historical. For all other modifiers, you can make the modified alphabetical characters case-sensitive when you customize Emacs. For instance, you could make M-a and M-A run different commands. Although only the Control and META modifier keys are commonly used, Emacs supports three other modifier keys. These are called Super, Hyper and Alt. Few terminals provide ways to use these modifiers; the key labeled Alt on most keyboards usually issues the META modifier, not Alt. The standard key bindings in Emacs do not include any characters with these modifiers. However, you can customize Emacs to assign meanings to them. The modifier bits are labeled as ‘s-’, ‘H-’ and ‘A-’ respectively. Even if your keyboard lacks these additional modifier keys, you can enter it using C-x @: C-x @ h adds the “hyper” flag to the next character, C-x @ s adds the “super” flag, and C-x @ a adds the “alt” flag. For instance, C-x @ h C-a is a way to enter Hyper-Control-a. (Unfortunately, there is no way to add two modifiers by using C-x @ twice for the same character, because the first one goes to work on the C-x.)
33.3.8 Rebinding Function Keys Key sequences can contain function keys as well as ordinary characters. Just as Lisp characters (actually integers) represent keyboard characters, Lisp symbols represent function keys. If the function key has a word as its label, then that word is also the name of the