path: root/devdocs/elisp/controlling-active-maps.html

 <h3 class="section">Controlling the Active Keymaps</h3>  <dl> <dt id="global-map">Variable: <strong>global-map</strong>
</dt> <dd>
<p>This variable contains the default global keymap that maps Emacs keyboard input to commands. The global keymap is normally this keymap. The default global keymap is a full keymap that binds <code>self-insert-command</code> to all of the printing characters. </p> <p>It is normal practice to change the bindings in the global keymap, but you should not assign this variable any value other than the keymap it starts out with. </p>
</dd>
</dl> <dl> <dt id="current-global-map">Function: <strong>current-global-map</strong>
</dt> <dd>
<p>This function returns the current global keymap. This is the same as the value of <code>global-map</code> unless you change one or the other. The return value is a reference, not a copy; if you use <code>define-key</code> or other functions on it you will alter global bindings. </p> <div class="example"> <pre class="example">(current-global-map)
⇒ (keymap [set-mark-command beginning-of-line …
            delete-backward-char])
</pre>
</div> </dd>
</dl> <dl> <dt id="current-local-map">Function: <strong>current-local-map</strong>
</dt> <dd>
<p>This function returns the current buffer’s local keymap, or <code>nil</code> if it has none. In the following example, the keymap for the <samp>*scratch*</samp> buffer (using Lisp Interaction mode) is a sparse keymap in which the entry for <tt class="key">ESC</tt>, <acronym>ASCII</acronym> code 27, is another sparse keymap. </p> <div class="example"> <pre class="example">(current-local-map)
⇒ (keymap
    (10 . eval-print-last-sexp)
    (9 . lisp-indent-line)
    (127 . backward-delete-char-untabify)
</pre>
<pre class="example">    (27 keymap
        (24 . eval-defun)
        (17 . indent-sexp)))
</pre>
</div> </dd>
</dl> <p><code>current-local-map</code> returns a reference to the local keymap, not a copy of it; if you use <code>define-key</code> or other functions on it you will alter local bindings. </p> <dl> <dt id="current-minor-mode-maps">Function: <strong>current-minor-mode-maps</strong>
</dt> <dd><p>This function returns a list of the keymaps of currently enabled minor modes. </p></dd>
</dl> <dl> <dt id="use-global-map">Function: <strong>use-global-map</strong> <em>keymap</em>
</dt> <dd>
<p>This function makes <var>keymap</var> the new current global keymap. It returns <code>nil</code>. </p> <p>It is very unusual to change the global keymap. </p>
</dd>
</dl> <dl> <dt id="use-local-map">Function: <strong>use-local-map</strong> <em>keymap</em>
</dt> <dd><p>This function makes <var>keymap</var> the new local keymap of the current buffer. If <var>keymap</var> is <code>nil</code>, then the buffer has no local keymap. <code>use-local-map</code> returns <code>nil</code>. Most major mode commands use this function. </p></dd>
</dl> <dl> <dt id="minor-mode-map-alist">Variable: <strong>minor-mode-map-alist</strong>
</dt> <dd>
<p>This variable is an alist describing keymaps that may or may not be active according to the values of certain variables. Its elements look like this: </p> <div class="example"> <pre class="example">(<var>variable</var> . <var>keymap</var>)
</pre>
</div> <p>The keymap <var>keymap</var> is active whenever <var>variable</var> has a non-<code>nil</code> value. Typically <var>variable</var> is the variable that enables or disables a minor mode. See <a href="keymaps-and-minor-modes">Keymaps and Minor Modes</a>. </p> <p>Note that elements of <code>minor-mode-map-alist</code> do not have the same structure as elements of <code>minor-mode-alist</code>. The map must be the <small>CDR</small> of the element; a list with the map as the second element will not do. The <small>CDR</small> can be either a keymap (a list) or a symbol whose function definition is a keymap. </p> <p>When more than one minor mode keymap is active, the earlier one in <code>minor-mode-map-alist</code> takes priority. But you should design minor modes so that they don’t interfere with each other. If you do this properly, the order will not matter. </p> <p>See <a href="keymaps-and-minor-modes">Keymaps and Minor Modes</a>, for more information about minor modes. See also <code>minor-mode-key-binding</code> (see <a href="functions-for-key-lookup">Functions for Key Lookup</a>). </p>
</dd>
</dl> <dl> <dt id="minor-mode-overriding-map-alist">Variable: <strong>minor-mode-overriding-map-alist</strong>
</dt> <dd>
<p>This variable allows major modes to override the key bindings for particular minor modes. The elements of this alist look like the elements of <code>minor-mode-map-alist</code>: <code>(<var>variable</var>
. <var>keymap</var>)</code>. </p> <p>If a variable appears as an element of <code>minor-mode-overriding-map-alist</code>, the map specified by that element totally replaces any map specified for the same variable in <code>minor-mode-map-alist</code>. </p> <p><code>minor-mode-overriding-map-alist</code> is automatically buffer-local in all buffers. </p>
</dd>
</dl> <dl> <dt id="overriding-local-map">Variable: <strong>overriding-local-map</strong>
</dt> <dd><p>If non-<code>nil</code>, this variable holds a keymap to use instead of the buffer’s local keymap, any text property or overlay keymaps, and any minor mode keymaps. This keymap, if specified, overrides all other maps that would have been active, except for the current global map. </p></dd>
</dl> <dl> <dt id="overriding-terminal-local-map">Variable: <strong>overriding-terminal-local-map</strong>
</dt> <dd>
<p>If non-<code>nil</code>, this variable holds a keymap to use instead of <code>overriding-local-map</code>, the buffer’s local keymap, text property or overlay keymaps, and all the minor mode keymaps. </p> <p>This variable is always local to the current terminal and cannot be buffer-local. See <a href="multiple-terminals">Multiple Terminals</a>. It is used to implement incremental search mode. </p>
</dd>
</dl> <dl> <dt id="overriding-local-map-menu-flag">Variable: <strong>overriding-local-map-menu-flag</strong>
</dt> <dd>
<p>If this variable is non-<code>nil</code>, the value of <code>overriding-local-map</code> or <code>overriding-terminal-local-map</code> can affect the display of the menu bar. The default value is <code>nil</code>, so those map variables have no effect on the menu bar. </p> <p>Note that these two map variables do affect the execution of key sequences entered using the menu bar, even if they do not affect the menu bar display. So if a menu bar key sequence comes in, you should clear the variables before looking up and executing that key sequence. Modes that use the variables would typically do this anyway; normally they respond to events that they do not handle by “unreading” them and exiting. </p>
</dd>
</dl> <dl> <dt id="special-event-map">Variable: <strong>special-event-map</strong>
</dt> <dd><p>This variable holds a keymap for special events. If an event type has a binding in this keymap, then it is special, and the binding for the event is run directly by <code>read-event</code>. See <a href="special-events">Special Events</a>. </p></dd>
</dl> <dl> <dt id="emulation-mode-map-alists">Variable: <strong>emulation-mode-map-alists</strong>
</dt> <dd><p>This variable holds a list of keymap alists to use for emulation modes. It is intended for modes or packages using multiple minor-mode keymaps. Each element is a keymap alist which has the same format and meaning as <code>minor-mode-map-alist</code>, or a symbol with a variable binding which is such an alist. The active keymaps in each alist are used before <code>minor-mode-map-alist</code> and <code>minor-mode-overriding-map-alist</code>. </p></dd>
</dl>  <dl> <dt id="set-transient-map">Function: <strong>set-transient-map</strong> <em>keymap &amp;optional keep-pred on-exit</em>
</dt> <dd>
<p>This function adds <var>keymap</var> as a <em>transient</em> keymap, which takes precedence over other keymaps for one (or more) subsequent keys. </p> <p>Normally, <var>keymap</var> is used just once, to look up the very next key. If the optional argument <var>keep-pred</var> is <code>t</code>, the map stays active as long as the user types keys defined in <var>keymap</var>; when the user types a key that is not in <var>keymap</var>, the transient keymap is deactivated and normal key lookup continues for that key. </p> <p>The <var>keep-pred</var> argument can also be a function. In that case, the function is called with no arguments, prior to running each command, while <var>keymap</var> is active; it should return non-<code>nil</code> if <var>keymap</var> should stay active. </p> <p>The optional argument <var>on-exit</var>, if non-<code>nil</code>, specifies a function that is called, with no arguments, after <var>keymap</var> is deactivated. </p> <p>This function works by adding and removing <var>keymap</var> from the variable <code>overriding-terminal-local-map</code>, which takes precedence over all other active keymaps (see <a href="searching-keymaps">Searching Keymaps</a>). </p>
</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/Controlling-Active-Maps.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Controlling-Active-Maps.html</a>
  </p>
</div>