elisp: Mode Line Data
22.4.2 The Data Structure of the Mode Line
------------------------------------------
The mode line contents are controlled by a data structure called a “mode
line construct”, made up of lists, strings, symbols, and numbers kept in
buffer-local variables. Each data type has a specific meaning for the
mode line appearance, as described below. The same data structure is
used for constructing frame titles (
Frame Titles) and header
lines (Header Lines).
A mode line construct may be as simple as a fixed string of text, but
it usually specifies how to combine fixed strings with variables’ values
to construct the text. Many of these variables are themselves defined
to have mode line constructs as their values.
Here are the meanings of various data types as mode line constructs:
‘STRING’
A string as a mode line construct appears verbatim except for
“‘%’-constructs” in it. These stand for substitution of other
data; see %-Constructs.
If parts of the string have ‘face’ properties, they control display
of the text just as they would text in the buffer. Any characters
which have no ‘face’ properties are displayed, by default, in the
face ‘mode-line’ or ‘mode-line-inactive’ ((emacs)Standard
Faces). The ‘help-echo’ and ‘keymap’ properties in STRING have
special meanings. Properties in Mode.
‘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.
Unless SYMBOL is marked as risky (i.e., it has a non-‘nil’
‘risky-local-variable’ property), all text properties specified in
SYMBOL’s value are ignored. This includes the text properties of
strings in SYMBOL’s value, as well as all ‘:eval’ and ‘:propertize’
forms in it. (The reason for this is security: non-risky variables
could be set automatically from file variables without prompting
the user.)
‘(STRING REST...)’
‘(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. Make sure this
evaluation cannot load any files, as doing so could cause infinite
recursion.
‘(:propertize ELT PROPS...)’
A list whose first element is the symbol ‘:propertize’ says to
process the mode line construct ELT recursively, then add the text
properties specified by PROPS to the result. The argument PROPS
should consist of zero or more pairs TEXT-PROPERTY VALUE.
‘(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 SYMBOL has a non-‘nil’ value, the second element, THEN,
is processed recursively as a mode line construct. Otherwise, the
third element, ELSE, is processed recursively. You may omit ELSE;
then the mode line construct displays nothing if the value of
SYMBOL is ‘nil’ or void.
‘(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. When WIDTH is positive, the result is space filled on
the right if its width is less than WIDTH. When WIDTH is negative,
the result is truncated on the right to −WIDTH columns if its width
exceeds −WIDTH.
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")’.
Info Catalog
elisp: Mode Line Basics
elisp: Mode Line Format
elisp: Mode Line Top