Previous: Keymaps and Minor Modes, Up: Minor Modes

23.3.3 Defining Minor Modes

The macro define-minor-mode offers a convenient way of implementing a mode in one self-contained definition.

— Macro: define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args... body...

This macro defines a new minor mode whose name is mode (a symbol). It defines a command named mode to toggle the minor mode, with doc as its documentation string. It also defines a variable named mode, which is set to t or nil by enabling or disabling the mode. The variable is initialized to init-value. Except in unusual circumstances (see below), this value must be nil.

The string lighter says what to display in the mode line when the mode is enabled; if it is nil, the mode is not displayed in the mode line.

The optional argument keymap specifies the keymap for the minor mode. It can be a variable name, whose value is the keymap, or it can be an alist specifying bindings in this form: 

          (key-sequence . definition)

The above three arguments init-value, lighter, and keymap can be (partially) omitted when keyword-args are used. The keyword-args consist of keywords followed by corresponding values. A few keywords have special meanings:

:group group
Custom group name to use in all generated defcustom forms. Defaults to mode without the possible trailing “-mode”. Warning: don't use this default group name unless you have written a defgroup to define that group properly. See Group Definitions.
:global global
If non-nil specifies that the minor mode should be global. By default, minor modes defined with define-minor-mode are buffer-local.
:init-value init-value
This is equivalent to specifying init-value positionally.
:lighter lighter
This is equivalent to specifying lighter positionally.
:keymap keymap
This is equivalent to specifying keymap positionally.

Any other keyword arguments are passed directly to the defcustom generated for the variable mode.

The command named mode first performs the standard actions such as setting the variable named mode and then executes the body forms, if any. It finishes by running the mode hook variable mode-hook.

The initial value must be nil 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 nil.

The name easy-mmode-define-minor-mode is an alias for this macro.

Here is an example of using define-minor-mode: 

     (define-minor-mode hungry-mode
       "Toggle Hungry mode.
     With no argument, this command toggles the mode.
     Non-null prefix argument turns on the mode.
     Null prefix argument turns off the mode.
     
     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-\^?" . hungry-electric-delete))
      :group 'hunger)

This defines a minor mode named “Hungry mode,” a command named hungry-mode to toggle it, a variable named hungry-mode which indicates whether the mode is enabled, and a variable named hungry-mode-map which holds the keymap that is active when the mode is enabled. It initializes the keymap with a key binding for C-<DEL>. It puts the variable hungry-mode into custom group hunger. There are no body forms—many minor modes don't need any.

Here's an equivalent way to write it: 

     (define-minor-mode hungry-mode
       "Toggle Hungry mode.
     With no argument, this command toggles the mode.
     Non-null prefix argument turns on the mode.
     Null prefix argument turns off the mode.
     
     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.
      :init-value nil
      ;; The indicator for the mode line.
      :lighter " Hungry"
      ;; The minor mode bindings.
      :keymap
      '(("\C-\^?" . hungry-electric-delete)
        ("\C-\M-\^?"
         . (lambda ()
             (interactive)
             (hungry-electric-delete t))))
      :group 'hunger)
— Macro: define-global-minor-mode global-mode mode turn-on keyword-args...

This defines a global minor mode named global-mode whose meaning is to enable the buffer-local minor mode mode in every buffer. To turn on the minor mode in a buffer, it uses the function turn-on; to turn off the minor mode, it calls mode with −1 as argument.

Use :group group in keyword-args to specify the custom group for the mode variable of the global minor mode.

∑ Back to Emacs Lisp Tutorial.