diff options
Diffstat (limited to 'devdocs/elisp/defining-minor-modes.html')
| -rw-r--r-- | devdocs/elisp/defining-minor-modes.html | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/devdocs/elisp/defining-minor-modes.html b/devdocs/elisp/defining-minor-modes.html new file mode 100644 index 00000000..4a4d3381 --- /dev/null +++ b/devdocs/elisp/defining-minor-modes.html @@ -0,0 +1,60 @@ + <h4 class="subsection">Defining Minor Modes</h4> <p>The macro <code>define-minor-mode</code> offers a convenient way of implementing a mode in one self-contained definition. </p> <dl> <dt id="define-minor-mode">Macro: <strong>define-minor-mode</strong> <em>mode doc keyword-args… body…</em> +</dt> <dd> +<p>This macro defines a new minor mode whose name is <var>mode</var> (a symbol). It defines a command named <var>mode</var> to toggle the minor mode, with <var>doc</var> as its documentation string. </p> <p>The toggle command takes one optional (prefix) argument. If called interactively with no argument it toggles the mode on or off. A positive prefix argument enables the mode, any other prefix argument disables it. From Lisp, an argument of <code>toggle</code> toggles the mode, whereas an omitted or <code>nil</code> argument enables the mode. This makes it easy to enable the minor mode in a major mode hook, for example. If <var>doc</var> is <code>nil</code>, the macro supplies a default documentation string explaining the above. </p> <p>By default, it also defines a variable named <var>mode</var>, which is set to <code>t</code> or <code>nil</code> by enabling or disabling the mode. </p> <p>The <var>keyword-args</var> consist of keywords followed by corresponding values. A few keywords have special meanings: </p> <dl compact> <dt><code>:global <var>global</var></code></dt> <dd> +<p>If non-<code>nil</code>, this specifies that the minor mode should be global rather than buffer-local. It defaults to <code>nil</code>. </p> <p>One of the effects of making a minor mode global is that the <var>mode</var> variable becomes a customization variable. Toggling it through the Customize interface turns the mode on and off, and its value can be saved for future Emacs sessions (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Customizations.html#Saving-Customizations">Saving Customizations</a> in <cite>The GNU Emacs Manual</cite>. For the saved variable to work, you should ensure that the minor mode function is available each time Emacs starts; usually this is done by marking the <code>define-minor-mode</code> form as autoloaded. </p> </dd> <dt><code>:init-value <var>init-value</var></code></dt> <dd> +<p>This is the value to which the <var>mode</var> variable is initialized. Except in unusual circumstances (see below), this value must be <code>nil</code>. </p> </dd> <dt><code>:lighter <var>lighter</var></code></dt> <dd> +<p>The string <var>lighter</var> says what to display in the mode line when the mode is enabled; if it is <code>nil</code>, the mode is not displayed in the mode line. </p> </dd> <dt><code>:keymap <var>keymap</var></code></dt> <dd> +<p>The optional argument <var>keymap</var> specifies the keymap for the minor mode. If non-<code>nil</code>, it should be a variable name (whose value is a keymap), a keymap, or an alist of the form </p> <div class="example"> <pre class="example">(<var>key-sequence</var> . <var>definition</var>) +</pre> +</div> <p>where each <var>key-sequence</var> and <var>definition</var> are arguments suitable for passing to <code>define-key</code> (see <a href="changing-key-bindings">Changing Key Bindings</a>). If <var>keymap</var> is a keymap or an alist, this also defines the variable <code><var>mode</var>-map</code>. </p> </dd> <dt><code>:variable <var>place</var></code></dt> <dd> +<p>This replaces the default variable <var>mode</var>, used to store the state of the mode. If you specify this, the <var>mode</var> variable is not defined, and any <var>init-value</var> argument is unused. <var>place</var> can be a different named variable (which you must define yourself), or anything that can be used with the <code>setf</code> function (see <a href="generalized-variables">Generalized Variables</a>). <var>place</var> can also be a cons <code>(<var>get</var> . <var>set</var>)</code>, where <var>get</var> is an expression that returns the current state, and <var>set</var> is a function of one argument (a state) which should be assigned to <var>place</var>. </p> </dd> <dt><code>:after-hook <var>after-hook</var></code></dt> <dd> +<p>This defines a single Lisp form which is evaluated after the mode hooks have run. It should not be quoted. </p> </dd> <dt><code>:interactive <var>value</var></code></dt> <dd><p>Minor modes are interactive commands by default. If <var>value</var> is <code>nil</code>, this is inhibited. If <var>value</var> is a list of symbols, it’s used to say which major modes this minor mode is useful in. </p></dd> </dl> <p>Any other keyword arguments are passed directly to the <code>defcustom</code> generated for the variable <var>mode</var>. </p> <p>The command named <var>mode</var> first performs the standard actions such as setting the variable named <var>mode</var> and then executes the <var>body</var> forms, if any. It then runs the mode hook variable <code><var>mode</var>-hook</code> and finishes by evaluating any form in <code>:after-hook</code>. (Note that all of this, including running the hook, is done both when the mode is enabled and disabled.) </p> +</dd> +</dl> <p>The initial value must be <code>nil</code> except in cases where (1) the mode is preloaded in Emacs, or (2) it is painless for loading to enable the mode even though the user did not request it. For instance, if the mode has no effect unless something else is enabled, and will always be loaded by that time, enabling it by default is harmless. But these are unusual circumstances. Normally, the initial value must be <code>nil</code>. </p> <p>The name <code>easy-mmode-define-minor-mode</code> is an alias for this macro. </p> <p>Here is an example of using <code>define-minor-mode</code>: </p> <div class="example"> <pre class="example">(define-minor-mode hungry-mode + "Toggle Hungry mode. +Interactively with no argument, this command toggles the mode. +A positive prefix argument enables the mode, any other prefix +argument disables it. From Lisp, argument omitted or nil enables +the mode, `toggle' toggles the state. + +When Hungry mode is enabled, the control delete key +gobbles all preceding whitespace except the last. +See the command \\[hungry-electric-delete]." + ;; The initial value. + nil + ;; The indicator for the mode line. + " Hungry" + ;; The minor mode bindings. + '(([C-backspace] . hungry-electric-delete))) +</pre> +</div> <p>This defines a minor mode named “Hungry mode”, a command named <code>hungry-mode</code> to toggle it, a variable named <code>hungry-mode</code> which indicates whether the mode is enabled, and a variable named <code>hungry-mode-map</code> which holds the keymap that is active when the mode is enabled. It initializes the keymap with a key binding for <kbd>C-<span class="key">DEL</span></kbd>. There are no <var>body</var> forms—many minor modes don’t need any. </p> <p>Here’s an equivalent way to write it: </p> <div class="example"> <pre class="example">(define-minor-mode hungry-mode + "Toggle Hungry mode. +...rest of documentation as before..." + ;; The initial value. + :init-value nil + ;; The indicator for the mode line. + :lighter " Hungry" + ;; The minor mode bindings. + :keymap + '(([C-backspace] . hungry-electric-delete) + ([C-M-backspace] + . (lambda () + (interactive) + (hungry-electric-delete t))))) +</pre> +</div> <dl> <dt id="define-globalized-minor-mode">Macro: <strong>define-globalized-minor-mode</strong> <em>global-mode mode turn-on keyword-args… body…</em> +</dt> <dd> +<p>This defines a global toggle named <var>global-mode</var> whose meaning is to enable or disable the buffer-local minor mode <var>mode</var> in all (or some; see below) buffers. It also executes the <var>body</var> forms. To turn on the minor mode in a buffer, it uses the function <var>turn-on</var>; to turn off the minor mode, it calls <var>mode</var> with -1 as argument. </p> <p>Globally enabling the mode also affects buffers subsequently created by visiting files, and buffers that use a major mode other than Fundamental mode; but it does not detect the creation of a new buffer in Fundamental mode. </p> <p>This defines the customization option <var>global-mode</var> (see <a href="customization">Customization</a>), which can be toggled in the Customize interface to turn the minor mode on and off. As with <code>define-minor-mode</code>, you should ensure that the <code>define-globalized-minor-mode</code> form is evaluated each time Emacs starts, for example by providing a <code>:require</code> keyword. </p> <p>Use <code>:group <var>group</var></code> in <var>keyword-args</var> to specify the custom group for the mode variable of the global minor mode. </p> <p>By default, the buffer-local minor mode variable that says whether the mode is switched on or off is the same as the name of the mode itself. Use <code>:variable <var>variable</var></code> if that’s not the case–some minor modes use a different variable to store this state information. </p> <p>Generally speaking, when you define a globalized minor mode, you should also define a non-globalized version, so that people can use (or disable) it in individual buffers. This also allows them to disable a globally enabled minor mode in a specific major mode, by using that mode’s hook. </p> <p>If given a <code>:predicate</code> keyword, a user option called the same as the global mode variable, but with <code>-modes</code> instead of <code>-mode</code> at the end will be created. The variable is used as a predicate that specifies which major modes the minor mode should be activated in. Valid values include <code>t</code> (use in all major modes, <code>nil</code> (use in no major modes), or a list of mode names (or <code>(not mode-name ...)</code>) elements (as well as <code>t</code> and <code>nil</code>). </p> <div class="example"> <pre class="example">(c-mode (not mail-mode message-mode) text-mode) +</pre> +</div> <p>This means “use in modes derived from <code>c-mode</code>, and not in modes derived from <code>message-mode</code> or <code>mail-mode</code>, but do use in modes derived from <code>text-mode</code>, and otherwise no other modes”. </p> <div class="example"> <pre class="example">((not c-mode) t) +</pre> +</div> <p>This means “don’t use modes derived from <code>c-mode</code>, but use everywhere else”. </p> <div class="example"> <pre class="example">(text-mode) +</pre> +</div> <p>This means “use in modes derived from <code>text-mode</code>, but nowhere else”. (There’s an implicit <code>nil</code> element at the end.) </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/Defining-Minor-Modes.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Minor-Modes.html</a> + </p> +</div> |