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 (see Frame Titles) and header lines (see 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:
%-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
(see Standard Faces). The
keymap properties in string have
special meanings. See Properties in Mode.
nilare 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
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
:propertize forms in it. (The reason for this
is security: non-risky variables could be set automatically from file
variables without prompting the user.)
:evalsays 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.
:propertizesays 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. If elt is or produces a string with text properties, all the characters of that string should have the same properties, or else some of them might be removed by
(symbol then else
nilvalue, 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
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: