Commit 287e63bb authored by Eli Zaretskii's avatar Eli Zaretskii

Fallout from fixing bug #7587.

 doc/lispref/modes.texi (Emulating Mode Line): Update documentation of
 format-mode-line according to changes that fixed bug #7587.

 etc/NEWS: Mention the incompatible change in format-mode-line wrt its
 FACE argument.
parent 30d621a2
2010-12-18 Eli Zaretskii <eliz@gnu.org>
* modes.texi (Emulating Mode Line): Update documentation of
format-mode-line according to changes that fixed bug #7587.
2010-12-11 Eli Zaretskii <eliz@gnu.org>
* processes.texi (Shell Arguments):
......
......@@ -2111,29 +2111,43 @@ the text that would appear in a mode line or header line
based on a certain mode-line specification.
@defun format-mode-line format &optional face window buffer
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
the text as a string. The argument @var{window} defaults to the
selected window. If @var{buffer} is non-@code{nil}, all the
information used is taken from @var{buffer}; by default, it comes from
@var{window}'s buffer.
This function formats a line of text according to @var{format} as if it
were generating the mode line for @var{window}, but it also returns the
text as a string. The argument @var{window} defaults to the selected
window. If @var{buffer} is non-@code{nil}, all the information used is
taken from @var{buffer}; by default, it comes from @var{window}'s
buffer.
The value string normally has text properties that correspond to the
faces, keymaps, etc., that the mode line would have. And any character
for which no @code{face} property is specified gets a default
value which is usually @var{face}. (If @var{face} is @code{t},
that stands for either @code{mode-line} if @var{window} is selected,
otherwise @code{mode-line-inactive}. If @var{face} is @code{nil} or
omitted, that stands for no face property.)
for which no @code{face} property is specified gets a default value
determined by @var{face}. If @var{face} is @code{t}, that stands for
either @code{mode-line} if @var{window} is selected, otherwise
@code{mode-line-inactive}. If @var{face} is @code{nil} or omitted, that
stands for no face property.
However, if @var{face} is an integer, the value has no text properties.
You can also specify other valid faces as the value of @var{face}.
If the value is a @dfn{basic face}, one of @code{default}, @code{mode-line},
@code{mode-line-inactive}, @code{header-line}, or @code{tool-bar}, that
face provides the @code{face} property for characters whose face is not
specified by @var{format}. Any other face is treated as @code{default},
but you can remap one of the basic faces (@pxref{Face Remapping}) to get
the same effect as with non-basic faces.
Note that using @code{mode-line}, @code{mode-line-inactive}, or
@code{header-line} as @var{face} will actually redisplay the mode line
or the header line, respectively, using the current definitions of the
corresponding face, in addition to returning the formatted string.
(Other faces do not cause redisplay.)
For example, @code{(format-mode-line header-line-format)} returns the
text that would appear in the selected window's header line (@code{""}
if it has no header line). @code{(format-mode-line header-line-format
'header-line)} returns the same text, with each character
carrying the face that it will have in the header line itself.
carrying the face that it will have in the header line itself, and also
redraws the header line.
@end defun
@node Imenu
......
......@@ -1845,6 +1845,11 @@ checking/manipulating elements directly, use the new functions
** `mode-name' is no longer guaranteed to be a string.
Use `(format-mode-line mode-name)' to ensure a string value.
** `format-mode-line' now supports only a few basic faces as its FACE argument.
The FACE argument to `format-mode-line' should be one of `default',
`mode-line', `mode-line-inactive', `header-line', or `tool-bar'. Any
other face is treated as `default'.
** The function x-font-family-list has been removed.
Use the new function font-family-list (see Lisp Changes, below).
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment