GNU Info

(elisp)Mode Line Data

---

Next: Mode Line Variables Up: Mode Line Format

---

Enter node , (file) or (file)node

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 buffer-local variables.  The data
structure is called a "mode line construct", and it is built in
recursive fashion out of simpler mode line constructs.  The same data
structure is used for constructing frame titles (Note: Frame Titles)
and header lines (Note: Header Lines).

 - 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.

     If you set this variable to `nil' in a buffer, that buffer does not
     have a mode line.  (This feature was added in Emacs 21.)

   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' itself.  For most
purposes, it is sufficient to alter some of the variables that
`mode-line-format' refers to.

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

   The mode line can display various faces, if the strings that control
it have the `face' property.  Note: Properties in Mode.  In addition,
the face `mode-line' is used as a default for the whole mode line
(Note: Standard Faces).

`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.

`SYMBOL'
     A symbol as a mode line construct stands for its value.  The value
     of SYMBOL is used as a mode line construct, in place of SYMBOL.
     However, the symbols `t' and `nil' are ignored, as is any symbol
     whose value is void.

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

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

`(:eval FORM)'
     A list whose first element is the symbol `:eval' says to evaluate
     FORM, and use the result as a string to display.  (This feature is
     new as of Emacs 21.)

`(SYMBOL THEN ELSE)'
     A list whose first element is a symbol that is not a keyword
     specifies a conditional.  Its meaning depends on the value of
     SYMBOL.  If the value is non-`nil', the second element, THEN, is
     processed recursively as a mode line element.  But if the value of
     SYMBOL is `nil', the third element, ELSE, is processed recursively.
     You may omit ELSE; then the mode line element displays nothing if
     the value of SYMBOL is `nil'.

`(WIDTH REST...)'
     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
     right.

     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
     "%p")'.

   If you do alter `mode-line-format' itself, the new value should use
the same variables that appear in the default value (Note: Mode Line
Variables), rather than duplicating their contents or displaying the
information in another fashion.  This way, customizations made by the
user or by Lisp programs (such as `display-time' and 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 host name and default directory.

     (setq mode-line-format
       (list "-"
        'mode-line-mule-info
        'mode-line-modified
        'mode-line-frame-identification
        "%b--"
        ;; Note that this is evaluated while making the list.
        ;; It makes a mode line construct which is just a string.
        (getenv "HOST")
        ":"
        'default-directory
        "   "
        'global-mode-string
        "   %[("
        '(:eval (mode-line-mode-name))
        'mode-line-process
        'minor-mode-alist
        "%n"
        ")%]--"
        '(which-func-mode ("" which-func-format "--"))
        '(line-number-mode "L%l--")
        '(column-number-mode "C%c--")
        '(-3 . "%p")
        "-%-"))

(The variables `line-number-mode', `column-number-mode' and
`which-func-mode' enable particular minor modes; as usual, these
variable names are also the minor mode command names.)


automatically generated by info2www version 1.2.2.9