GNU Info

(elisp)Minor Mode Conventions

---

Next: Keymaps and Minor Modes Up: Minor Modes

---

Enter node , (file) or (file)node

Conventions for Writing Minor Modes
-----------------------------------

   There are conventions for writing minor modes just as there are for
major modes.  Several of the major mode conventions apply to minor
modes as well: those regarding the name of the mode initialization
function, the names of global symbols, and the use of keymaps and other
tables.

   In addition, there are several conventions that are specific to
minor modes.

   * Make a variable whose name ends in `-mode' to control the minor
     mode.  We call this the "mode variable".  The minor mode command
     should set this variable (`nil' to disable; anything else to
     enable).

     If possible, implement the mode so that setting the variable
     automatically enables or disables the mode.  Then the minor mode
     command does not need to do anything except set the variable.

     This variable is used in conjunction with the `minor-mode-alist' to
     display the minor mode name in the mode line.  It can also enable
     or disable a minor mode keymap.  Individual commands or hooks can
     also check the variable's value.

     If you want the minor mode to be enabled separately in each buffer,
     make the variable buffer-local.

   * Define a command whose name is the same as the mode variable.  Its
     job is to enable and disable the mode by setting the variable.

     The command should accept one optional argument.  If the argument
     is `nil', it should toggle the mode (turn it on if it is off, and
     off if it is on).  Otherwise, it should turn the mode on if the
     argument is a positive integer, a symbol other than `nil' or `-',
     or a list whose CAR is such an integer or symbol; it should turn
     the mode off otherwise.

     Here is an example taken from the definition of
     `transient-mark-mode'.  It shows the use of `transient-mark-mode'
     as a variable that enables or disables the mode's behavior, and
     also shows the proper way to toggle, enable or disable the minor
     mode based on the raw prefix argument value.

          (setq transient-mark-mode
                (if (null arg) (not transient-mark-mode)
                  (> (prefix-numeric-value arg) 0)))

   * Add an element to `minor-mode-alist' for each minor mode (Note:
     Mode Line Variables), if you want to indicate the minor mode in
     the mode line.  This element should be a list of the following
     form:

          (MODE-VARIABLE STRING)

     Here MODE-VARIABLE is the variable that controls enabling of the
     minor mode, and STRING is a short string, starting with a space,
     to represent the mode in the mode line.  These strings must be
     short so that there is room for several of them at once.

     When you add an element to `minor-mode-alist', use `assq' to check
     for an existing element, to avoid duplication.  For example:

          (unless (assq 'leif-mode minor-mode-alist)
            (setq minor-mode-alist
                  (cons '(leif-mode " Leif") minor-mode-alist)))

     or like this, using `add-to-list' (Note: Setting Variables):

          (add-to-list 'minor-mode-alist '(leif-mode " Leif"))

   Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (Note: Customization).  To do this,
the first step is to define the mode variable with `defcustom', and
specify `:type boolean'.

   If just setting the variable is not sufficient to enable the mode,
you should also specify a `:set' method which enables the mode by
invoke the mode command.  Note in the variable's documentation string
that setting the variable other than via Custom may not take effect.

   Also mark the definition with an autoload cookie (Note: Autoload),
and specify a `:require' so that customizing the variable will load the
library that defines the mode.  This will copy suitable definitions
into `loaddefs.el' so that users can use `customize-option' to enable
the mode.  For example:


     ;;;###autoload
     (defcustom msb-mode nil
       "Toggle msb-mode.
     Setting this variable directly does not take effect;
     use either \\[customize] or the function `msb-mode'."
       :set (lambda (symbol value)
     	 (msb-mode (or value 0)))
       :initialize 'custom-initialize-default
       :version "20.4"
       :type    'boolean
       :group   'msb
       :require 'msb)