1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
|
<h3 class="section">Changing Key Bindings</h3> <p>The way to rebind a key is to change its entry in a keymap. If you change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer’s local map, that usually affects all buffers using the same major mode. The <code>global-set-key</code> and <code>local-set-key</code> functions are convenient interfaces for these operations (see <a href="key-binding-commands">Key Binding Commands</a>). You can also use <code>define-key</code>, a more general function; then you must explicitly specify the map to change. </p> <p>When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (see <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Key-Binding-Conventions.html">Key Binding Conventions</a>). </p> <p>In writing the key sequence to rebind, it is good to use the special escape sequences for control and meta characters (see <a href="string-type">String Type</a>). The syntax ‘<samp>\C-</samp>’ means that the following character is a control character and ‘<samp>\M-</samp>’ means that the following character is a meta character. Thus, the string <code>"\M-x"</code> is read as containing a single <kbd>M-x</kbd>, <code>"\C-f"</code> is read as containing a single <kbd>C-f</kbd>, and <code>"\M-\C-x"</code> and <code>"\C-\M-x"</code> are both read as containing a single <kbd>C-M-x</kbd>. You can also use this escape syntax in vectors, as well as others that aren’t allowed in strings; one example is ‘<samp>[?\C-\H-x home]</samp>’. See <a href="character-type">Character Type</a>. </p> <p>The key definition and lookup functions accept an alternate syntax for event types in a key sequence that is a vector: you can use a list containing modifier names plus one base event (a character or function key name). For example, <code>(control ?a)</code> is equivalent to <code>?\C-a</code> and <code>(hyper control left)</code> is equivalent to <code>C-H-left</code>. One advantage of such lists is that the precise numeric codes for the modifier bits don’t appear in compiled files. </p> <p>The functions below signal an error if <var>keymap</var> is not a keymap, or if <var>key</var> is not a string or vector representing a key sequence. You can use event types (symbols) as shorthand for events that are lists. The <code>kbd</code> function (see <a href="key-sequences">Key Sequences</a>) is a convenient way to specify the key sequence. </p> <dl> <dt id="define-key">Function: <strong>define-key</strong> <em>keymap key binding</em>
</dt> <dd>
<p>This function sets the binding for <var>key</var> in <var>keymap</var>. (If <var>key</var> is more than one event long, the change is actually made in another keymap reached from <var>keymap</var>.) The argument <var>binding</var> can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see <a href="key-lookup">Key Lookup</a>.) The value returned by <code>define-key</code> is <var>binding</var>. </p> <p>If <var>key</var> is <code>[t]</code>, this sets the default binding in <var>keymap</var>. When an event has no binding of its own, the Emacs command loop uses the keymap’s default binding, if there is one. </p> <p>Every prefix of <var>key</var> must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of <var>key</var> is undefined, then <code>define-key</code> defines it as a prefix key so that the rest of <var>key</var> can be defined as specified. </p> <p>If there was previously no binding for <var>key</var> in <var>keymap</var>, the new binding is added at the beginning of <var>keymap</var>. The order of bindings in a keymap makes no difference for keyboard input, but it does matter for menu keymaps (see <a href="menu-keymaps">Menu Keymaps</a>). </p>
</dd>
</dl> <p>This example creates a sparse keymap and makes a number of bindings in it: </p> <div class="example"> <pre class="example">(setq map (make-sparse-keymap))
⇒ (keymap)
</pre>
<pre class="example">(define-key map "\C-f" 'forward-char)
⇒ forward-char
</pre>
<pre class="example">map
⇒ (keymap (6 . forward-char))
</pre>
<pre class="example">;; <span class="roman">Build sparse submap for <kbd>C-x</kbd> and bind <kbd>f</kbd> in that.</span>
(define-key map (kbd "C-x f") 'forward-word)
⇒ forward-word
</pre>
<pre class="example">map
⇒ (keymap
(24 keymap ; <kbd>C-x</kbd>
(102 . forward-word)) ; <kbd>f</kbd>
(6 . forward-char)) ; <kbd>C-f</kbd>
</pre>
<pre class="example">;; <span class="roman">Bind <kbd>C-p</kbd> to the <code>ctl-x-map</code>.</span>
(define-key map (kbd "C-p") ctl-x-map)
;; <code>ctl-x-map</code>
⇒ [nil … find-file … backward-kill-sentence]
</pre>
<pre class="example">;; <span class="roman">Bind <kbd>C-f</kbd> to <code>foo</code> in the <code>ctl-x-map</code>.</span>
(define-key map (kbd "C-p C-f") 'foo)
⇒ 'foo
</pre>
<pre class="example">map
⇒ (keymap ; <span class="roman">Note <code>foo</code> in <code>ctl-x-map</code>.</span>
(16 keymap [nil … foo … backward-kill-sentence])
(24 keymap
(102 . forward-word))
(6 . forward-char))
</pre>
</div> <p>Note that storing a new binding for <kbd>C-p C-f</kbd> actually works by changing an entry in <code>ctl-x-map</code>, and this has the effect of changing the bindings of both <kbd>C-p C-f</kbd> and <kbd>C-x C-f</kbd> in the default global map. </p> <p>The function <code>substitute-key-definition</code> scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (see <a href="remapping-commands">Remapping Commands</a>). </p> <dl> <dt id="substitute-key-definition">Function: <strong>substitute-key-definition</strong> <em>olddef newdef keymap &optional oldmap</em>
</dt> <dd>
<p>This function replaces <var>olddef</var> with <var>newdef</var> for any keys in <var>keymap</var> that were bound to <var>olddef</var>. In other words, <var>olddef</var> is replaced with <var>newdef</var> wherever it appears. The function returns <code>nil</code>. </p> <p>For example, this redefines <kbd>C-x C-f</kbd>, if you do it in an Emacs with standard bindings: </p> <div class="example"> <pre class="example">(substitute-key-definition
'find-file 'find-file-read-only (current-global-map))
</pre>
</div> <p>If <var>oldmap</var> is non-<code>nil</code>, that changes the behavior of <code>substitute-key-definition</code>: the bindings in <var>oldmap</var> determine which keys to rebind. The rebindings still happen in <var>keymap</var>, not in <var>oldmap</var>. Thus, you can change one map under the control of the bindings in another. For example, </p> <div class="example"> <pre class="example">(substitute-key-definition
'delete-backward-char 'my-funny-delete
my-map global-map)
</pre>
</div> <p>puts the special deletion command in <code>my-map</code> for whichever keys are globally bound to the standard deletion command. </p> <p>Here is an example showing a keymap before and after substitution: </p> <div class="example"> <pre class="example">(setq map (list 'keymap
(cons ?1 olddef-1)
(cons ?2 olddef-2)
(cons ?3 olddef-1)))
⇒ (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
</pre>
<pre class="example">(substitute-key-definition 'olddef-1 'newdef map)
⇒ nil
</pre>
<pre class="example">map
⇒ (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))
</pre>
</div> </dd>
</dl> <dl> <dt id="suppress-keymap">Function: <strong>suppress-keymap</strong> <em>keymap &optional nodigits</em>
</dt> <dd>
<p>This function changes the contents of the full keymap <var>keymap</var> by remapping <code>self-insert-command</code> to the command <code>undefined</code> (see <a href="remapping-commands">Remapping Commands</a>). This has the effect of undefining all printing characters, thus making ordinary insertion of text impossible. <code>suppress-keymap</code> returns <code>nil</code>. </p> <p>If <var>nodigits</var> is <code>nil</code>, then <code>suppress-keymap</code> defines digits to run <code>digit-argument</code>, and <kbd>-</kbd> to run <code>negative-argument</code>. Otherwise it makes them undefined like the rest of the printing characters. </p> <p>The <code>suppress-keymap</code> function does not make it impossible to modify a buffer, as it does not suppress commands such as <code>yank</code> and <code>quoted-insert</code>. To prevent any modification of a buffer, make it read-only (see <a href="read-only-buffers">Read Only Buffers</a>). </p> <p>Since this function modifies <var>keymap</var>, you would normally use it on a newly created keymap. Operating on an existing keymap that is used for some other purpose is likely to cause trouble; for example, suppressing <code>global-map</code> would make it impossible to use most of Emacs. </p> <p>This function can be used to initialize the local keymap of a major mode for which insertion of text is not desirable. But usually such a mode should be derived from <code>special-mode</code> (see <a href="basic-major-modes">Basic Major Modes</a>); then its keymap will automatically inherit from <code>special-mode-map</code>, which is already suppressed. Here is how <code>special-mode-map</code> is defined: </p> <div class="example"> <pre class="example">(defvar special-mode-map
(let ((map (make-sparse-keymap)))
(suppress-keymap map)
(define-key map "q" 'quit-window)
…
map))
</pre>
</div> </dd>
</dl><div class="_attribution">
<p class="_attribution-p">
Copyright © 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
<a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Key-Bindings.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Changing-Key-Bindings.html</a>
</p>
</div>
|
