23.3.1 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 (see section 29.4 Frame Titles) and header lines (see section 23.3.5 Window 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. See section 23.3.4 Properties in the Mode Line. In addition, the face mode-line is used as a default for the whole mode line (see section 38.11.1 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). See section 23.3.3 %-Constructs in the Mode Line.

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 (see section 23.3.2 Variables Used in the Mode Line), 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.)