From 287e63bb58cf30457222598c64b4bf551cdeb381 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 18 Dec 2010 10:53:28 +0200 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/modes.texi | 40 +++++++++++++++++++++++++++------------- etc/NEWS | 5 +++++ 3 files changed, 37 insertions(+), 13 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 970da3f5ff2..30e77ab38af 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2010-12-18 Eli Zaretskii + + * modes.texi (Emulating Mode Line): Update documentation of + format-mode-line according to changes that fixed bug #7587. + 2010-12-11 Eli Zaretskii * processes.texi (Shell Arguments): diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 0b6547177e0..5c5e6cd3fbb 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -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 diff --git a/etc/NEWS b/etc/NEWS index 6e152777aee..ebc1f0afc9e 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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). -- 2.11.4.GIT