GNU Info

(elisp)Defining Minor Modes

---

Prev: Keymaps and Minor Modes Up: Minor Modes

---

Enter node , (file) or (file)node

Defining Minor Modes
--------------------

   The macro `define-minor-mode' offers a convenient way of
implementing a mode in one self-contained definition.  It supports only
buffer-local minor modes, not global ones.

 - Macro: define-minor-mode mode doc &optional init-value
          mode-indicator keymap 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.

     The command named MODE finishes by executing the BODY forms, if
     any, after it has performed the standard actions such as setting
     the variable named MODE.

     The string MODE-INDICATOR 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)

   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)
        ("\C-\M-\^?"
         . (lambda ()
             (interactive)
             (hungry-electric-delete t)))))

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 key bindings for `C-<DEL>'
and `C-M-<DEL>'.

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