diff options
Diffstat (limited to 'devdocs/elisp/functions-for-key-lookup.html')
| -rw-r--r-- | devdocs/elisp/functions-for-key-lookup.html | 62 |
1 files changed, 62 insertions, 0 deletions
diff --git a/devdocs/elisp/functions-for-key-lookup.html b/devdocs/elisp/functions-for-key-lookup.html new file mode 100644 index 00000000..906ea301 --- /dev/null +++ b/devdocs/elisp/functions-for-key-lookup.html @@ -0,0 +1,62 @@ + <h3 class="section">Functions for Key Lookup</h3> <p>Here are the functions and variables pertaining to key lookup. </p> <dl> <dt id="lookup-key">Function: <strong>lookup-key</strong> <em>keymap key &optional accept-defaults</em> +</dt> <dd> +<p>This function returns the definition of <var>key</var> in <var>keymap</var>. All the other functions described in this chapter that look up keys use <code>lookup-key</code>. Here are examples: </p> <div class="example"> <pre class="example">(lookup-key (current-global-map) "\C-x\C-f") + ⇒ find-file +</pre> +<pre class="example">(lookup-key (current-global-map) (kbd "C-x C-f")) + ⇒ find-file +</pre> +<pre class="example">(lookup-key (current-global-map) "\C-x\C-f12345") + ⇒ 2 +</pre> +</div> <p>If the string or vector <var>key</var> is not a valid key sequence according to the prefix keys specified in <var>keymap</var>, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of <var>key</var> that compose a complete key. </p> <p>If <var>accept-defaults</var> is non-<code>nil</code>, then <code>lookup-key</code> considers default bindings as well as bindings for the specific events in <var>key</var>. Otherwise, <code>lookup-key</code> reports only bindings for the specific sequence <var>key</var>, ignoring default bindings except when you explicitly ask about them. (To do this, supply <code>t</code> as an element of <var>key</var>; see <a href="format-of-keymaps">Format of Keymaps</a>.) </p> <p>If <var>key</var> contains a meta character (not a function key), that character is implicitly replaced by a two-character sequence: the value of <code>meta-prefix-char</code>, followed by the corresponding non-meta character. Thus, the first example below is handled by conversion into the second example. </p> <div class="example"> <pre class="example">(lookup-key (current-global-map) "\M-f") + ⇒ forward-word +</pre> +<pre class="example">(lookup-key (current-global-map) "\ef") + ⇒ forward-word +</pre> +</div> <p>The <var>keymap</var> argument can also be a list of keymaps. </p> <p>Unlike <code>read-key-sequence</code>, this function does not modify the specified events in ways that discard information (see <a href="key-sequence-input">Key Sequence Input</a>). In particular, it does not convert letters to lower case and it does not change drag events to clicks. </p> +</dd> +</dl> <dl> <dt id="undefined">Command: <strong>undefined</strong> +</dt> <dd><p>Used in keymaps to undefine keys. It calls <code>ding</code>, but does not cause an error. </p></dd> +</dl> <dl> <dt id="local-key-binding">Function: <strong>local-key-binding</strong> <em>key &optional accept-defaults</em> +</dt> <dd> +<p>This function returns the binding for <var>key</var> in the current local keymap, or <code>nil</code> if it is undefined there. </p> <p>The argument <var>accept-defaults</var> controls checking for default bindings, as in <code>lookup-key</code> (above). </p> +</dd> +</dl> <dl> <dt id="global-key-binding">Function: <strong>global-key-binding</strong> <em>key &optional accept-defaults</em> +</dt> <dd> +<p>This function returns the binding for command <var>key</var> in the current global keymap, or <code>nil</code> if it is undefined there. </p> <p>The argument <var>accept-defaults</var> controls checking for default bindings, as in <code>lookup-key</code> (above). </p> +</dd> +</dl> <dl> <dt id="minor-mode-key-binding">Function: <strong>minor-mode-key-binding</strong> <em>key &optional accept-defaults</em> +</dt> <dd> +<p>This function returns a list of all the active minor mode bindings of <var>key</var>. More precisely, it returns an alist of pairs <code>(<var>modename</var> . <var>binding</var>)</code>, where <var>modename</var> is the variable that enables the minor mode, and <var>binding</var> is <var>key</var>’s binding in that mode. If <var>key</var> has no minor-mode bindings, the value is <code>nil</code>. </p> <p>If the first binding found is not a prefix definition (a keymap or a symbol defined as a keymap), all subsequent bindings from other minor modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings. </p> <p>The argument <var>accept-defaults</var> controls checking for default bindings, as in <code>lookup-key</code> (above). </p> +</dd> +</dl> <dl> <dt id="meta-prefix-char">User Option: <strong>meta-prefix-char</strong> +</dt> <dd> + <p>This variable is the meta-prefix character code. It is used for translating a meta character to a two-character sequence so it can be looked up in a keymap. For useful results, the value should be a prefix event (see <a href="prefix-keys">Prefix Keys</a>). The default value is 27, which is the <acronym>ASCII</acronym> code for <tt class="key">ESC</tt>. </p> <p>As long as the value of <code>meta-prefix-char</code> remains 27, key lookup translates <kbd>M-b</kbd> into <kbd><span class="key">ESC</span> b</kbd>, which is normally defined as the <code>backward-word</code> command. However, if you were to set <code>meta-prefix-char</code> to 24, the code for <kbd>C-x</kbd>, then Emacs will translate <kbd>M-b</kbd> into <kbd>C-x b</kbd>, whose standard binding is the <code>switch-to-buffer</code> command. (Don’t actually do this!) Here is an illustration of what would happen: </p> <div class="example"> <pre class="example">meta-prefix-char ; <span class="roman">The default value.</span> + ⇒ 27 +</pre> +<pre class="example">(key-binding "\M-b") + ⇒ backward-word +</pre> +<pre class="example">?\C-x ; <span class="roman">The print representation</span> + ⇒ 24 ; <span class="roman">of a character.</span> +</pre> +<pre class="example">(setq meta-prefix-char 24) + ⇒ 24 +</pre> +<pre class="example">(key-binding "\M-b") + ⇒ switch-to-buffer ; <span class="roman">Now, typing <kbd>M-b</kbd> is</span> + ; <span class="roman">like typing <kbd>C-x b</kbd>.</span> + +(setq meta-prefix-char 27) ; <span class="roman">Avoid confusion!</span> + ⇒ 27 ; <span class="roman">Restore the default value!</span> +</pre> +</div> <p>This translation of one event into two happens only for characters, not for other kinds of input events. Thus, <kbd>M-<span class="key">F1</span></kbd>, a function key, is not converted into <kbd><span class="key">ESC</span> <span class="key">F1</span></kbd>. </p> +</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/Functions-for-Key-Lookup.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Functions-for-Key-Lookup.html</a> + </p> +</div> |