diff options
Diffstat (limited to 'devdocs/elisp/scanning-keymaps.html')
| -rw-r--r-- | devdocs/elisp/scanning-keymaps.html | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/devdocs/elisp/scanning-keymaps.html b/devdocs/elisp/scanning-keymaps.html new file mode 100644 index 00000000..afa77186 --- /dev/null +++ b/devdocs/elisp/scanning-keymaps.html @@ -0,0 +1,54 @@ + <h3 class="section">Scanning Keymaps</h3> <p>This section describes functions used to scan all the current keymaps for the sake of printing help information. To display the bindings in a particular keymap, you can use the <code>describe-keymap</code> command (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Misc-Help.html#Misc-Help">Other Help Commands</a> in <cite>The GNU Emacs Manual</cite>) </p> <dl> <dt id="accessible-keymaps">Function: <strong>accessible-keymaps</strong> <em>keymap &optional prefix</em> +</dt> <dd> +<p>This function returns a list of all the keymaps that can be reached (via zero or more prefix keys) from <var>keymap</var>. The value is an association list with elements of the form <code>(<var>key</var> . +<var>map</var>)</code>, where <var>key</var> is a prefix key whose definition in <var>keymap</var> is <var>map</var>. </p> <p>The elements of the alist are ordered so that the <var>key</var> increases in length. The first element is always <code>([] . <var>keymap</var>)</code>, because the specified keymap is accessible from itself with a prefix of no events. </p> <p>If <var>prefix</var> is given, it should be a prefix key sequence; then <code>accessible-keymaps</code> includes only the submaps whose prefixes start with <var>prefix</var>. These elements look just as they do in the value of <code>(accessible-keymaps)</code>; the only difference is that some elements are omitted. </p> <p>In the example below, the returned alist indicates that the key <tt class="key">ESC</tt>, which is displayed as ‘<samp>^[</samp>’, is a prefix key whose definition is the sparse keymap <code>(keymap (83 . center-paragraph) +(115 . foo))</code>. </p> <div class="example"> <pre class="example">(accessible-keymaps (current-local-map)) +⇒(([] keymap + (27 keymap ; <span class="roman">Note this keymap for <tt class="key">ESC</tt> is repeated below.</span> + (83 . center-paragraph) + (115 . center-line)) + (9 . tab-to-tab-stop)) +</pre> + +<pre class="example"> ("^[" keymap + (83 . center-paragraph) + (115 . foo))) +</pre> +</div> <p>In the following example, <kbd>C-h</kbd> is a prefix key that uses a sparse keymap starting with <code>(keymap (118 . describe-variable)…)</code>. Another prefix, <kbd>C-x 4</kbd>, uses a keymap which is also the value of the variable <code>ctl-x-4-map</code>. The event <code>mode-line</code> is one of several dummy events used as prefixes for mouse actions in special parts of a window. </p> <div class="example"> <pre class="example">(accessible-keymaps (current-global-map)) +⇒ (([] keymap [set-mark-command beginning-of-line … + delete-backward-char]) +</pre> +<pre class="example"> ("^H" keymap (118 . describe-variable) … + (8 . help-for-help)) +</pre> +<pre class="example"> ("^X" keymap [x-flush-mouse-queue … + backward-kill-sentence]) +</pre> +<pre class="example"> ("^[" keymap [mark-sexp backward-sexp … + backward-kill-word]) +</pre> +<pre class="example"> ("^X4" keymap (15 . display-buffer) …) +</pre> +<pre class="example"> ([mode-line] keymap + (S-mouse-2 . mouse-split-window-horizontally) …)) +</pre> +</div> <p>These are not all the keymaps you would see in actuality. </p> +</dd> +</dl> <dl> <dt id="map-keymap">Function: <strong>map-keymap</strong> <em>function keymap</em> +</dt> <dd> +<p>The function <code>map-keymap</code> calls <var>function</var> once for each binding in <var>keymap</var>. It passes two arguments, the event type and the value of the binding. If <var>keymap</var> has a parent, the parent’s bindings are included as well. This works recursively: if the parent has itself a parent, then the grandparent’s bindings are also included and so on. </p> <p>This function is the cleanest way to examine all the bindings in a keymap. </p> +</dd> +</dl> <dl> <dt id="where-is-internal">Function: <strong>where-is-internal</strong> <em>command &optional keymap firstonly noindirect no-remap</em> +</dt> <dd> +<p>This function is a subroutine used by the <code>where-is</code> command (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Help.html#Help">Help</a> in <cite>The GNU Emacs Manual</cite>). It returns a list of all key sequences (of any length) that are bound to <var>command</var> in a set of keymaps. </p> <p>The argument <var>command</var> can be any object; it is compared with all keymap entries using <code>eq</code>. </p> <p>If <var>keymap</var> is <code>nil</code>, then the maps used are the current active keymaps, disregarding <code>overriding-local-map</code> (that is, pretending its value is <code>nil</code>). If <var>keymap</var> is a keymap, then the maps searched are <var>keymap</var> and the global keymap. If <var>keymap</var> is a list of keymaps, only those keymaps are searched. </p> <p>Usually it’s best to use <code>overriding-local-map</code> as the expression for <var>keymap</var>. Then <code>where-is-internal</code> searches precisely the keymaps that are active. To search only the global map, pass the value <code>(keymap)</code> (an empty keymap) as <var>keymap</var>. </p> <p>If <var>firstonly</var> is <code>non-ascii</code>, then the value is a single vector representing the first key sequence found, rather than a list of all possible key sequences. If <var>firstonly</var> is <code>t</code>, then the value is the first key sequence, except that key sequences consisting entirely of <acronym>ASCII</acronym> characters (or meta variants of <acronym>ASCII</acronym> characters) are preferred to all other key sequences and that the return value can never be a menu binding. </p> <p>If <var>noindirect</var> is non-<code>nil</code>, <code>where-is-internal</code> doesn’t look inside menu-items to find their commands. This makes it possible to search for a menu-item itself. </p> <p>The fifth argument, <var>no-remap</var>, determines how this function treats command remappings (see <a href="remapping-commands">Remapping Commands</a>). There are two cases of interest: </p> <dl compact> <dt>If a command <var>other-command</var> is remapped to <var>command</var>:</dt> <dd> +<p>If <var>no-remap</var> is <code>nil</code>, find the bindings for <var>other-command</var> and treat them as though they are also bindings for <var>command</var>. If <var>no-remap</var> is non-<code>nil</code>, include the vector <code>[remap <var>other-command</var>]</code> in the list of possible key sequences, instead of finding those bindings. </p> </dd> <dt>If <var>command</var> is remapped to <var>other-command</var>:</dt> <dd><p>If <var>no-remap</var> is <code>nil</code>, return the bindings for <var>other-command</var> rather than <var>command</var>. If <var>no-remap</var> is non-<code>nil</code>, return the bindings for <var>command</var>, ignoring the fact that it is remapped. </p></dd> </dl> </dd> +</dl> <dl> <dt id="describe-bindings">Command: <strong>describe-bindings</strong> <em>&optional prefix buffer-or-name</em> +</dt> <dd> +<p>This function creates a listing of all current key bindings, and displays it in a buffer named <samp>*Help*</samp>. The text is grouped by modes—minor modes first, then the major mode, then global bindings. </p> <p>If <var>prefix</var> is non-<code>nil</code>, it should be a prefix key; then the listing includes only keys that start with <var>prefix</var>. </p> <p>When several characters with consecutive <acronym>ASCII</acronym> codes have the same definition, they are shown together, as ‘<samp><var>firstchar</var>..<var>lastchar</var></samp>’. In this instance, you need to know the <acronym>ASCII</acronym> codes to understand which characters this means. For example, in the default global map, the characters ‘<samp><span class="key">SPC</span> .. ~</samp>’ are described by a single line. <tt class="key">SPC</tt> is <acronym>ASCII</acronym> 32, <kbd>~</kbd> is <acronym>ASCII</acronym> 126, and the characters between them include all the normal printing characters, (e.g., letters, digits, punctuation, etc.); all these characters are bound to <code>self-insert-command</code>. </p> <p>If <var>buffer-or-name</var> is non-<code>nil</code>, it should be a buffer or a buffer name. Then <code>describe-bindings</code> lists that buffer’s bindings, instead of the current buffer’s. </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/Scanning-Keymaps.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Scanning-Keymaps.html</a> + </p> +</div> |