comparison lispref/modes.texi @ 52628:74d358d76ea8

(Mode Line Data): Document the :propertize construct. (Mode Line Variables): Reorder the descriptions of the variables to match their order in the default mode-line-format. Describe the new variables mode-line-position and mode-line-modes. Update the default values of mode-line-frame-identification, minor-mode-alist, and default-mode-line-format. (Properties in Mode): Mention the :propertize construct.

52627:e3a0f4e62b53

settings.  A mode that does this is called a @dfn{derived mode}.  The
recommended way to define one is to use @code{define-derived-mode},
but this is not required.  Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
(Using @code{define-derived-mode} does this automatically.) 

@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).

        (hungry-electric-delete t))))
 :group 'hunger)
@end smallexample

@node Mode Line Format
@section Mode Line Format
@cindex mode line

  Each Emacs window (aside from minibuffer windows) typically has a mode
line at the bottom, which displays status information about the buffer
displayed in the window.  The mode line contains information about the

* Emulating Mode Line::   Formatting text as the mode line would.
@end menu

@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode line construct

  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 @dfn{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 (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).

@defvar 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 @code{nil} in a buffer, that buffer does not
have a mode line.  (This feature was added in Emacs 21.)
@end defvar

  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 @code{mode-line-format} incorporates the values
of variables such as @code{mode-name} and @code{minor-mode-alist}.
Because of this, very few modes need to alter @code{mode-line-format}
itself.  For most purposes, it is sufficient to alter some of the
variables that @code{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 @code{face} property.  @xref{Properties in Mode}.  In
addition, the face @code{mode-line} is used as a default for the whole
mode line (@pxref{Standard Faces}).

@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode line construct is displayed verbatim in the mode line
except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified).  @xref{%-Constructs}.

@item @var{symbol}
A symbol as a mode line construct stands for its value.  The value of
@var{symbol} is used as a mode line construct, in place of @var{symbol}.
However, the symbols @code{t} and @code{nil} are ignored, as is any
symbol whose value is void.

There is one exception: if the value of @var{symbol} is a string, it is
displayed verbatim: the @code{%}-constructs are not recognized.

@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
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.

@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.
(This feature is new as of Emacs 21.)

@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol that is not a keyword specifies a
conditional.  Its meaning depends on the value of @var{symbol}.  If the
value is non-@code{nil}, the second element, @var{then}, is processed
recursively as a mode line element.  But if the value of @var{symbol} is
@code{nil}, the third element, @var{else}, is processed recursively.
You may omit @var{else}; then the mode line element displays nothing if
the value of @var{symbol} is @code{nil}.

@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}.  The remaining elements
@var{rest} are processed recursively as mode line constructs and
concatenated together.  Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.

For example, the usual way to show what percentage of a buffer is above

   'mode-line-frame-identification
   "%b--"
@end group
@group
   ;; @r{Note that this is evaluated while making the list.}
   ;; @r{It makes a mode line construct which is just a string.}
   (getenv "HOST")
@end group
   ":"
   'default-directory
   "   "

Changing this variable does not force an update of the mode line.
@end defvar

@defvar mode-line-frame-identification
This variable identifies the current frame.  The default value is
@code{" "} if you are using a window system which can show multiple
frames, or @code{"-%F "} on an ordinary terminal which shows only one
frame at a time.
@end defvar

@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window.  Its
default value is @code{("%12b")}, which displays the buffer name, padded
with spaces to at least 12 columns.
@end defvar

@defvar global-mode-string
This variable holds a mode line spec that appears in the mode line by
default, just after the buffer name.  The command @code{display-time}
sets @code{global-mode-string} to refer to the variable
@code{display-time-string}, which holds a string containing the time and
load information.

The @samp{%M} construct substitutes the value of
@code{global-mode-string}, but that is obsolete, since the variable is
included in the mode line from @code{mode-line-format}.
@end defvar

@defvar mode-name
This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode.  Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar

@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active.  Each element of
the @code{minor-mode-alist} should be a two-element list:

@example
(@var{minor-mode-variable} @var{mode-line-string})
@end example

More generally, @var{mode-line-string} can be any mode line spec.  It
appears in the mode line when the value of @var{minor-mode-variable} is
non-@code{nil}, and not otherwise.  These strings should begin with
spaces so that they don't run together.  Conventionally, the
@var{minor-mode-variable} for a specific mode is set to a non-@code{nil}
value when that minor mode is activated.

The default value of @code{minor-mode-alist} is:

@example
@group
minor-mode-alist
@result{} ((vc-mode vc-mode)
    (abbrev-mode " Abbrev")
    (overwrite-mode overwrite-mode)
    (auto-fill-function " Fill")
    (defining-kbd-macro " Def")
    (isearch-mode isearch-mode))
@end group
@end example

@code{minor-mode-alist} itself is not buffer-local.  Each variable
mentioned in the alist should be buffer-local if its minor mode can be
enabled separately in each buffer.
@end defvar

@defvar mode-line-process
This buffer-local variable contains the mode line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:run)}.  Normally this variable
is @code{nil}.
@end defvar

  Some variables are used by @code{minor-mode-alist} to display
a string for various minor modes when enabled.  This is a typical
example:

@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
whether the buffer's visited file is maintained with version control,
and, if so, which kind.  Its value is a string that appears in the mode
line, or @code{nil} for no version control.
@end defvar

  The variable @code{default-mode-line-format} is where
@code{mode-line-format} usually gets its value:

@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it.  This is the same as @code{(default-value
'mode-line-format)}.

The default value of @code{default-mode-line-format} is this list:

@example
@group
("-"
 mode-line-mule-info
 mode-line-modified
 mode-line-frame-identification
 mode-line-buffer-identification
@end group
 "   "
 global-mode-string
@group
 "   %[("
 ;; @r{@code{mode-line-mode-name} is a function}
 ;; @r{that copies the mode name and adds text}
 ;; @r{properties to make it mouse-sensitive.}
 (:eval (mode-line-mode-name))
 mode-line-process
 minor-mode-alist
 "%n"
 ")%]--"
@end group
@group
 (which-func-mode ("" which-func-format "--"))
 (line-number-mode "L%l--")
 (column-number-mode "C%c--")
 (-3 . "%p")
 "-%-")
@end group
@end example
@end defvar

@code{display-time} modifies the value of @code{global-mode-string}.
@end table

@node Properties in Mode
@subsection Properties in the Mode Line

  Starting in Emacs 21, certain text properties are meaningful in the
mode line.  The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.

  There are three ways to specify text properties for text in the mode
line:

@enumerate
@item
Put a string with the @code{local-map} property directly into the
mode-line data structure.

@item
Put a @code{local-map} property on a mode-line %-construct
such as @samp{%12b}; then the expansion of the %-construct
will have that same text property.

@item
Use a list containing @code{:eval @var{form}} in the mode-line data
structure, and make @var{form} evaluate to a string that has a
@code{local-map} property.
@end enumerate

  You use the @code{local-map} property to specify a keymap.  Like any
keymap, it can bind character keys and function keys; but that has no
effect, since it is impossible to move point into the mode line.  This

@cindex header line (of a window)
@cindex window header line

  Starting in Emacs 21, a window can have a @dfn{header line} at the
top, just as it can have a mode line at the bottom.  The header line
feature works just like the mode line feature, except that it's
controlled by different variables.

@tindex header-line-format
@defvar header-line-format
This variable, local in every buffer, specifies how to display the

It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar

@node Emulating Mode Line
@subsection Emulating Mode Line Formatting

  You can use the function @code{format-mode-line} to compute
the text that would appear in a mode line or header line
based on certain mode line specification.

@defun format-mode-line &optional format window no-props
This function formats a line of text according to @var{format} as if
it were generating the mode line for @var{window}, but instead of
displaying the text in the mode line or the header line, it returns

In addition to using @code{font-lock-defaults} for search-based
fontification, you may use the special character property
@code{font-lock-face} (@pxref{Special Properties}).  This property
acts just like the explicit @code{face} property, but its activation
is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
@code{font-lock-face} is especially conveninent for special modes
which construct their text programmatically, such as
@code{list-buffers} and @code{occur}.

If your mode does not use any of the other machinery of Font Lock
(i.e. it only uses the @code{font-lock-face} property), you can tell

52628:74d358d76ea8

settings.  A mode that does this is called a @dfn{derived mode}.  The
recommended way to define one is to use @code{define-derived-mode},
but this is not required.  Such a mode should use
@code{delay-mode-hooks} around its entire body, including the call to
the parent mode command and the final call to @code{run-mode-hooks}.
(Using @code{define-derived-mode} does this automatically.)

@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).

        (hungry-electric-delete t))))
 :group 'hunger)
@end smallexample

@node Mode Line Format
@section Mode-Line Format
@cindex mode line

  Each Emacs window (aside from minibuffer windows) typically has a mode
line at the bottom, which displays status information about the buffer
displayed in the window.  The mode line contains information about the

* Emulating Mode Line::   Formatting text as the mode line would.
@end menu

@node Mode Line Data
@subsection The Data Structure of the Mode Line
@cindex mode-line construct

  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 @dfn{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 (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).

@defvar 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 @code{nil} in a buffer, that buffer does not
have a mode line.  (This feature was added in Emacs 21.)
@end defvar

  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 @code{mode-line-format} incorporates the values
of variables such as @code{mode-line-position} and
@code{mode-line-modes} (which in turn incorporates the values of the
variables @code{mode-name} and @code{minor-mode-alist}).  Because of
this, very few modes need to alter @code{mode-line-format} itself.  For
most purposes, it is sufficient to alter some of the variables that
@code{mode-line-format} either directly or indirectly 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 @code{face} property.  @xref{Properties in Mode}.  In
addition, the face @code{mode-line} is used as a default for the whole
mode line (@pxref{Standard Faces}).

@table @code
@cindex percent symbol in mode line
@item @var{string}
A string as a mode-line construct is displayed verbatim in the mode line
except for @dfn{@code{%}-constructs}.  Decimal digits after the @samp{%}
specify the field width for space filling on the right (i.e., the data
is left justified).  @xref{%-Constructs}.

@item @var{symbol}
A symbol as a mode-line construct stands for its value.  The value of
@var{symbol} is used as a mode-line construct, in place of @var{symbol}.
However, the symbols @code{t} and @code{nil} are ignored, as is any
symbol whose value is void.

There is one exception: if the value of @var{symbol} is a string, it is
displayed verbatim: the @code{%}-constructs are not recognized.

@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{})
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.

@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.
(This feature is new as of Emacs 21.)

@item (:propertize @var{elt} @var{props}@dots{})
A list whose first element is the symbol @code{:propertize} says to
process the mode-line construct @var{elt} recursively and add the text
properties specified by @var{props} to the result.  The argument
@var{props} should consist of zero or more pairs @var{text-property}
@var{value}.  (This feature is new as of Emacs 21.4.)
@c FIXME: This might be Emacs 21.5.

@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol that is not a keyword specifies a
conditional.  Its meaning depends on the value of @var{symbol}.  If the
value is non-@code{nil}, the second element, @var{then}, is processed
recursively as a mode-line element.  But if the value of @var{symbol} is
@code{nil}, the third element, @var{else}, is processed recursively.
You may omit @var{else}; then the mode-line element displays nothing if
the value of @var{symbol} is @code{nil}.

@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
padding of the results of @var{rest}.  The remaining elements
@var{rest} are processed recursively as mode-line constructs and
concatenated together.  Then the result is space filled (if
@var{width} is positive) or truncated (to @minus{}@var{width} columns,
if @var{width} is negative) on the right.

For example, the usual way to show what percentage of a buffer is above

   'mode-line-frame-identification
   "%b--"
@end group
@group
   ;; @r{Note that this is evaluated while making the list.}
   ;; @r{It makes a mode-line construct which is just a string.}
   (getenv "HOST")
@end group
   ":"
   'default-directory
   "   "

Changing this variable does not force an update of the mode line.
@end defvar

@defvar mode-line-frame-identification
This variable identifies the current frame.  The default value is
@code{"  "} if you are using a window system which can show multiple
frames, or @code{"-%F  "} on an ordinary terminal which shows only one
frame at a time.
@end defvar

@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window.  Its
default value is @code{("%12b")}, which displays the buffer name, padded
with spaces to at least 12 columns.
@end defvar

@defvar mode-line-position
This variable indicates the position in the buffer.  Here is a
simplified version of its default value.  The actual default value
also specifies addition of the @code{help-echo} text property.

@example
@group
((-3 . "%p")
 (size-indication-mode (8 " of %I"))
@end group
@group
 (line-number-mode
  ((column-number-mode
    (10 " (%l,%c)")
    (6 " L%l")))
  ((column-number-mode
    (5 " C%c")))))
@end group
@end example

This means that @code{mode-line-position} displays at least the buffer
percentage and possibly the buffer size, the line number and the column
number.
@end defvar

@defvar vc-mode
The variable @code{vc-mode}, buffer-local in each buffer, records
whether the buffer's visited file is maintained with version control,
and, if so, which kind.  Its value is a string that appears in the mode
line, or @code{nil} for no version control.
@end defvar

@defvar mode-line-modes
This variable displays the buffer's major and minor modes.  Here is a
simplified version of its default value.  The real default value also
specifies addition of text properties.

@example
@group
("%[(" mode-name
 mode-line-process minor-mode-alist
 "%n" ")%]--")
@end group
@end example

So @code{mode-line-modes} normally also displays the recursive editing
level, information on the process status and whether narrowing is in
effect.
@end defvar

  The following three variables are used in @code{mode-line-modes}:

@defvar mode-name
This buffer-local variable holds the ``pretty'' name of the current
buffer's major mode.  Each major mode should set this variable so that the
mode name will appear in the mode line.
@end defvar

@defvar mode-line-process
This buffer-local variable contains the mode-line information on process
status in modes used for communicating with subprocesses.  It is
displayed immediately following the major mode name, with no intervening
space.  For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:run)}.  Normally this variable
is @code{nil}.
@end defvar

@defvar minor-mode-alist
This variable holds an association list whose elements specify how the
mode line should indicate that a minor mode is active.  Each element of
the @code{minor-mode-alist} should be a two-element list:

@example
(@var{minor-mode-variable} @var{mode-line-string})
@end example

More generally, @var{mode-line-string} can be any mode-line spec.  It
appears in the mode line when the value of @var{minor-mode-variable}
is non-@code{nil}, and not otherwise.  These strings should begin with
spaces so that they don't run together.  Conventionally, the
@var{minor-mode-variable} for a specific mode is set to a
non-@code{nil} value when that minor mode is activated.

@code{minor-mode-alist} itself is not buffer-local.  Each variable
mentioned in the alist should be buffer-local if its minor mode can be
enabled separately in each buffer.
@end defvar

@defvar global-mode-string
This variable holds a mode-line spec that appears in the mode line by
default, just after the buffer name.  The command @code{display-time}
sets @code{global-mode-string} to refer to the variable
@code{display-time-string}, which holds a string containing the time and
load information.

The @samp{%M} construct substitutes the value of
@code{global-mode-string}, but that is obsolete, since the variable is
included in the mode line from @code{mode-line-format}.
@end defvar

  The variable @code{default-mode-line-format} is where
@code{mode-line-format} usually gets its value:

@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it.  This is the same as @code{(default-value
'mode-line-format)}.

Here is a simplified version of the default value of
@code{default-mode-line-format}.  The real default value also
specifies addition of text properties.

@example
@group
("-"
 mode-line-mule-info
 mode-line-modified
 mode-line-frame-identification
 mode-line-buffer-identification
@end group
 "   "
 mode-line-position
 (vc-mode vc-mode)
 "   "
@group
 mode-line-modes
 (which-func-mode ("" which-func-format "--"))
 (global-mode-string ("--" global-mode-string))
 "-%-")
@end group
@end example
@end defvar

@code{display-time} modifies the value of @code{global-mode-string}.
@end table

@node Properties in Mode
@subsection Properties in the Mode Line
@cindex text properties in the mode line

  Starting in Emacs 21, certain text properties are meaningful in the
mode line.  The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.

  There are four ways to specify text properties for text in the mode
line:

@enumerate
@item
Put a string with a text property directly into the mode-line data
structure.

@item
Put a text property on a mode-line %-construct such as @samp{%12b}; then
the expansion of the %-construct will have that same text property.

@item
Use a @code{(:propertize @var{elt} @var{props}@dots{})} construct to
give @var{elt} a text property specified by @var{props}.

@item
Use a list containing @code{:eval @var{form}} in the mode-line data
structure, and make @var{form} evaluate to a string that has a text
property.
@end enumerate

  You use the @code{local-map} property to specify a keymap.  Like any
keymap, it can bind character keys and function keys; but that has no
effect, since it is impossible to move point into the mode line.  This

@cindex header line (of a window)
@cindex window header line

  Starting in Emacs 21, a window can have a @dfn{header line} at the
top, just as it can have a mode line at the bottom.  The header line
feature works just like the mode-line feature, except that it's
controlled by different variables.

@tindex header-line-format
@defvar header-line-format
This variable, local in every buffer, specifies how to display the

It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar

@node Emulating Mode Line
@subsection Emulating Mode-Line Formatting

  You can use the function @code{format-mode-line} to compute
the text that would appear in a mode line or header line
based on certain mode-line specification.

@defun format-mode-line &optional format window no-props
This function formats a line of text according to @var{format} as if
it were generating the mode line for @var{window}, but instead of
displaying the text in the mode line or the header line, it returns

In addition to using @code{font-lock-defaults} for search-based
fontification, you may use the special character property
@code{font-lock-face} (@pxref{Special Properties}).  This property
acts just like the explicit @code{face} property, but its activation
is toggled when the user calls @kbd{M-x font-lock-mode}.  Using
@code{font-lock-face} is especially convenient for special modes
which construct their text programmatically, such as
@code{list-buffers} and @code{occur}.

If your mode does not use any of the other machinery of Font Lock
(i.e. it only uses the @code{font-lock-face} property), you can tell