(lispref.info)Mode Line Data

Next: Mode Line Variables Prev: Mode Line Format Up: Mode Line Format

The Data Structure of the Mode Line

   The mode line contents are controlled by a data structure of lists,
strings, symbols and numbers kept in the buffer-local variable
`mode-line-format'.  The data structure is called a "mode line
construct", and it is built in recursive fashion out of simpler mode
line constructs.

 - Variable: mode-line-format
     The value of this variable is a mode line construct with overall
     responsibility for the mode line format.  The value of this
     variable controls which other variables are used to form the mode
     line text, and where they appear.

   A mode line construct may be as simple as a fixed string of text, but
it usually specifies how to use other variables to construct the text.
Many of these variables are themselves defined to have mode line
constructs as their values.

   The default value of `mode-line-format' incorporates the values of
variables such as `mode-name' and `minor-mode-alist'.  Because of this,
very few modes need to alter `mode-line-format'.  For most purposes, it
is sufficient to alter the variables referenced by `mode-line-format'.

   A mode line construct may be a list, cons cell, symbol, or string.
If the value is a list, each element may be a list, a cons cell, a
symbol, or a string.

     A string as a mode line construct is displayed verbatim in the
     mode line except for "`%'-constructs".  Decimal digits after the
     `%' specify the field width for space filling on the right (i.e.,
     the data is left justified).  Note: %-Constructs.

     A symbol as a mode line construct stands for its value.  The value
     of SYMBOL is used in place of SYMBOL unless SYMBOL is `t' or
     `nil', or is void, in which case SYMBOL is ignored.

     There is one exception: if the value of SYMBOL is a string, it is
     processed verbatim in that the `%'-constructs are not recognized.

`(STRING REST...) or (LIST REST...)'
     A list whose first element is a string or list, means to
     concatenate all the elements.  This is the most common form of
     mode line construct.

     A list whose first element is a symbol is a conditional.  Its
     meaning depends on the value of SYMBOL.  If the value is non-`nil',
     the second element of the list (THEN) is processed recursively as
     a mode line element.  But if the value of SYMBOL is `nil', the
     third element of the list (if there is one) is processed

     A list whose first element is an integer specifies truncation or
     padding of the results of REST.  The remaining elements REST are
     processed recursively as mode line constructs and concatenated
     together.  Then the result is space filled (if WIDTH is positive)
     or truncated (to -WIDTH columns, if WIDTH is negative) on the

     For example, the usual way to show what percentage of a buffer is
     above the top of the window is to use a list like this: `(-3 .

   If you do alter `mode-line-format' itself, the new value should use
all the same variables that are used by the default value, rather than
duplicating their contents or displaying the information in another
fashion.  This permits customizations made by the user, by libraries
(such as `display-time') or by major modes via changes to those
variables remain effective.

   Here is an example of a `mode-line-format' that might be useful for
`shell-mode' since it contains the hostname and default directory.

     (setq mode-line-format
       (list ""
        (getenv "HOST")      ; One element is not constant.
        "   "
        "   %[(" 'mode-name
        '(-3 . "%p")

automatically generated by info2www