Next: Modeline Variables, Previous: Modeline Format, Up: Modeline Format [Contents][Index]
The modeline contents are controlled by a data structure of lists,
strings, symbols, and numbers kept in the buffer-local variable
modeline-format
. The data structure is called a modeline
construct, and it is built in recursive fashion out of simpler modeline
constructs. The same data structure is used for constructing
frame titles (see Frame Titles).
The value of this variable is a modeline construct with overall responsibility for the modeline format. The value of this variable controls which other variables are used to form the modeline text, and where they appear.
A modeline 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 modeline constructs as their values.
The default value of modeline-format
incorporates the values
of variables such as mode-name
and minor-mode-alist
.
Because of this, very few modes need to alter modeline-format
.
For most purposes, it is sufficient to alter the variables referenced by
modeline-format
.
A modeline construct may be a string, symbol, glyph, generic specifier, list or cons cell.
string
A string as a modeline 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 %-Constructs.
symbol
A symbol as a modeline construct stands for its value. The value of
symbol is processed as a modeline construct, in place of
symbol. However, the symbols t
and nil
are ignored;
so 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.
glyph
A glyph is displayed as is.
generic-specifier
A generic-specifier (i.e. a specifier of type generic
)
stands for its instance. The instance of generic-specifier is
computed in the current window using the equivalent of
specifier-instance
and the value is processed.
(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.
(symbol then else)
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, then, is processed recursively as a modeline
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 modeline 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")
.
(extent rest…)
A list whose car is an extent means the cdr of the list is processed normally but the results are displayed using the face of the extent, and mouse clicks over this section are processed using the keymap of the extent. (In addition, if the extent has a help-echo property, that string will be echoed when the mouse moves over this section.) If extents are nested, all keymaps are properly consulted when processing mouse clicks, but multiple faces are not correctly merged (only the first face is used), and lists of faces are not correctly handled.
If you do alter modeline-format
itself, the new value should
use the same variables that appear in the default value (see Modeline 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 modeline-format
that might be
useful for shell-mode
, since it contains the hostname and default
directory.
(setq modeline-format (list "" 'modeline-modified "%b--"
(getenv "HOST") ; One element is not constant.
":"
'default-directory
" "
'global-mode-string
" %[("
'mode-name
'modeline-process
'minor-mode-alist
"%n"
")%]----"
'(line-number-mode "L%l--") '(-3 . "%p") "-%-"))
Next: Modeline Variables, Previous: Modeline Format, Up: Modeline Format [Contents][Index]