path: root/devdocs/elisp/format-of-keymaps.html

 <h3 class="section">Format of Keymaps</h3>     <p>Each keymap is a list whose <small>CAR</small> is the symbol <code>keymap</code>. The remaining elements of the list define the key bindings of the keymap. A symbol whose function definition is a keymap is also a keymap. Use the function <code>keymapp</code> (see below) to test whether an object is a keymap. </p> <p>Several kinds of elements may appear in a keymap, after the symbol <code>keymap</code> that begins it: </p> <dl compact> <dt><code>(<var>type</var> . <var>binding</var>)</code></dt> <dd>
<p>This specifies one binding, for events of type <var>type</var>. Each ordinary binding applies to events of a particular <em>event type</em>, which is always a character or a symbol. See <a href="classifying-events">Classifying Events</a>. In this kind of binding, <var>binding</var> is a command. </p> </dd> <dt><code>(<var>type</var> <var>item-name</var> . <var>binding</var>)</code></dt> <dd>
<p>This specifies a binding which is also a simple menu item that displays as <var>item-name</var> in the menu. See <a href="simple-menu-items">Simple Menu Items</a>. </p> </dd> <dt><code>(<var>type</var> <var>item-name</var> <var>help-string</var> . <var>binding</var>)</code></dt> <dd>
<p>This is a simple menu item with help string <var>help-string</var>. </p> </dd> <dt><code>(<var>type</var> menu-item . <var>details</var>)</code></dt> <dd>
<p>This specifies a binding which is also an extended menu item. This allows use of other features. See <a href="extended-menu-items">Extended Menu Items</a>. </p> </dd> <dt><code>(t . <var>binding</var>)</code></dt> <dd>
 <p>This specifies a <em>default key binding</em>; any event not bound by other elements of the keymap is given <var>binding</var> as its binding. Default bindings allow a keymap to bind all possible event types without having to enumerate all of them. A keymap that has a default binding completely masks any lower-precedence keymap, except for events explicitly bound to <code>nil</code> (see below). </p> </dd> <dt><code><var>char-table</var></code></dt> <dd>
<p>If an element of a keymap is a char-table, it counts as holding bindings for all character events with no modifier bits (see <a href="other-char-bits#modifier-bits">modifier bits</a>): the element whose index is <var>c</var> is the binding for the character <var>c</var>. This is a compact way to record lots of bindings. A keymap with such a char-table is called a <em>full keymap</em>. Other keymaps are called <em>sparse keymaps</em>. </p> </dd> <dt><code><var>vector</var></code></dt> <dd>
<p>This kind of element is similar to a char-table: the element whose index is <var>c</var> is the binding for the character <var>c</var>. Since the range of characters that can be bound this way is limited by the vector size, and vector creation allocates space for all character codes from 0 up, this format should not be used except for creating menu keymaps (see <a href="menu-keymaps">Menu Keymaps</a>), where the bindings themselves don’t matter. </p> </dd> <dt><code><var>string</var></code></dt> <dd>
   <p>Aside from elements that specify bindings for keys, a keymap can also have a string as an element. This is called the <em>overall prompt string</em> and makes it possible to use the keymap as a menu. See <a href="defining-menus">Defining Menus</a>. </p> </dd> <dt><code>(keymap …)</code></dt> <dd><p>If an element of a keymap is itself a keymap, it counts as if this inner keymap were inlined in the outer keymap. This is used for multiple-inheritance, such as in <code>make-composed-keymap</code>. </p></dd> </dl> <p>When the binding is <code>nil</code>, it doesn’t constitute a definition but it does take precedence over a default binding or a binding in the parent keymap. On the other hand, a binding of <code>nil</code> does <em>not</em> override lower-precedence keymaps; thus, if the local map gives a binding of <code>nil</code>, Emacs uses the binding from the global map. </p>  <p>Keymaps do not directly record bindings for the meta characters. Instead, meta characters are regarded for purposes of key lookup as sequences of two characters, the first of which is <tt class="key">ESC</tt> (or whatever is currently the value of <code>meta-prefix-char</code>). Thus, the key <kbd>M-a</kbd> is internally represented as <kbd><span class="key">ESC</span> a</kbd>, and its global binding is found at the slot for <kbd>a</kbd> in <code>esc-map</code> (see <a href="prefix-keys">Prefix Keys</a>). </p> <p>This conversion applies only to characters, not to function keys or other input events; thus, <kbd>M-<span class="key">end</span></kbd> has nothing to do with <kbd><span class="key">ESC</span> <span class="key">end</span></kbd>. </p> <p>Here as an example is the local keymap for Lisp mode, a sparse keymap. It defines bindings for <tt class="key">DEL</tt>, <kbd>C-c C-z</kbd>, <kbd>C-M-q</kbd>, and <kbd>C-M-x</kbd> (the actual value also contains a menu binding, which is omitted here for the sake of brevity). </p> <div class="example"> <pre class="example">lisp-mode-map
⇒
</pre>
<pre class="example">(keymap
 (3 keymap
    ;; <kbd>C-c C-z</kbd>
    (26 . run-lisp))
</pre>
<pre class="example"> (27 keymap
     ;; <span class="roman"><kbd>C-M-x</kbd>, treated as <kbd><span class="key">ESC</span> C-x</kbd></span>
     (24 . lisp-send-defun))
</pre>
<pre class="example"> ;; <span class="roman">This part is inherited from <code>lisp-mode-shared-map</code>.</span>
 keymap
 ;; <span class="key">DEL</span>
 (127 . backward-delete-char-untabify)
</pre>
<pre class="example"> (27 keymap
     ;; <span class="roman"><kbd>C-M-q</kbd>, treated as <kbd><span class="key">ESC</span> C-q</kbd></span>
     (17 . indent-sexp)))
</pre>
</div> <dl> <dt id="keymapp">Function: <strong>keymapp</strong> <em>object</em>
</dt> <dd>
<p>This function returns <code>t</code> if <var>object</var> is a keymap, <code>nil</code> otherwise. More precisely, this function tests for a list whose <small>CAR</small> is <code>keymap</code>, or for a symbol whose function definition satisfies <code>keymapp</code>. </p> <div class="example"> <pre class="example">(keymapp '(keymap))
    ⇒ t
</pre>
<pre class="example">(fset 'foo '(keymap))
(keymapp 'foo)
    ⇒ t
</pre>
<pre class="example">(keymapp (current-global-map))
    ⇒ t
</pre>
</div> </dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 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/Format-of-Keymaps.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-of-Keymaps.html</a>
  </p>
</div>