format-mode-line

format-mode-line

[Nick Roberts]

The documentation says:

> format-mode-line is a built-in function in `C source code'.
> (format-mode-line &optional FORMAT WINDOW NO-PROPS BUFFER)

> Return the mode-line of selected window as a string.
> First optional arg FORMAT specifies a different format string (see
> `mode-line-format' for details) to use.  If format is t, return
> the buffer's header-line.

AFAIK FORMAT need not be a string.

The manual also says:

> If FORMAT is `nil', that means to use `mode-line-format'

This does not seem to make sense because if header-line-format is nil
then (format-mode-line header-line-format) will presumably return the
mode-line of selected window as a string.

In any case, (format-mode-line) does not seem to give the right thing,
although (format-mode-line mode-line-format) does.

I suggest changing format-mode-line so that FORMAT is not optional and not
give a special meaning to nil and t. I think format-mode-line is currently
always used with a value for FORMAT. If this is a good idea, I offer to do
it and post my patch here.


Nick

Re: format-mode-line

[Richard Stallman]

    > If FORMAT is `nil', that means to use `mode-line-format'

    This does not seem to make sense because if header-line-format is nil
    then (format-mode-line header-line-format) will presumably return the
    mode-line of selected window as a string.

    ...

    I suggest changing format-mode-line so that FORMAT is not optional and not
    give a special meaning to nil and t. I think format-mode-line is currently
    always used with a value for FORMAT. If this is a good idea, I offer to do
    it and post my patch here.

The argument above seems convincing, so please do.

Re: format-mode-line

[Nick Roberts]

 >     I suggest changing format-mode-line so that FORMAT is not optional and not
 >     give a special meaning to nil and t. I think format-mode-line is currently
 >     always used with a value for FORMAT. If this is a good idea, I offer to do
 >     it and post my patch here.
 > 
 > The argument above seems convincing, so please do.

Here's the patch.

Nick

*** /home/nick/emacs/src/xdisp.c.~1.954.~	2005-01-06 12:32:47.000000000 +1300
--- /home/nick/emacs/src/xdisp.c	2005-01-06 12:44:01.000000000 +1300
***************
*** 15969,15982 ****
  
  
  DEFUN ("format-mode-line", Fformat_mode_line, Sformat_mode_line,
!        0, 4, 0,
         doc: /* Return the mode-line of selected window as a string.
! First optional arg FORMAT specifies the mode line format (see
! `mode-line-format' for details) to use.  If FORMAT is t, return
! the buffer's header-line.  Second optional arg WINDOW specifies a
! different window to use as the context for the formatting.
! If third optional arg NO-PROPS is non-nil, string is not propertized.
! Fourth optional arg BUFFER specifies which buffer to use.  */)
    (format, window, no_props, buffer)
       Lisp_Object format, window, no_props, buffer;
  {
--- 15969,15981 ----
  
  
  DEFUN ("format-mode-line", Fformat_mode_line, Sformat_mode_line,
!        1, 4, 0,
         doc: /* Return the mode-line of selected window as a string.
! First arg FORMAT specifies the mode line format (see `mode-line-format' for
! details) to use.  Second optional arg WINDOW specifies a different window to
! use as the context for the formatting.  If third optional arg NO-PROPS is
! non-nil, string is not propertized.  Fourth optional arg BUFFER specifies
! which buffer to use.  */)
    (format, window, no_props, buffer)
       Lisp_Object format, window, no_props, buffer;
  {
***************
*** 16002,16017 ****
        set_buffer_internal_1 (XBUFFER (buffer));
      }
  
-   if (NILP (format) || EQ (format, Qt))
-     {
-       face_id = (NILP (format)
- 		 ? CURRENT_MODE_LINE_FACE_ID (w)
- 		 : HEADER_LINE_FACE_ID);
-       format = (NILP (format)
- 		? current_buffer->mode_line_format
- 		: current_buffer->header_line_format);
-     }
- 
    init_iterator (&it, w, -1, -1, NULL, face_id);
  
    if (NILP (no_props))
--- 16001,16006 ----

*** /home/nick/emacs/lispref/modes.texi.~1.82.~	2005-01-01 19:31:23.000000000 +1300
--- /home/nick/emacs/lispref/modes.texi	2005-01-06 12:53:46.000000000 +1300
***************
*** 1736,1753 ****
  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 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.
  
! If @var{format} is @code{nil}, that means to use
! @code{mode-line-format} and return the text that would appear in the
! mode line.  If @var{format} is @code{t}, that means to use
! @code{header-line-format} so as to return the text that would appear
! in the header line (@code{""} if the window has no header line).
! The argument @var{window} defaults to the selected window.
  
  The value string normally has text properties that correspond to the
  faces, keymaps, etc., that the mode line would have.  If
--- 1736,1751 ----
  the text that would appear in a mode line or header line
  based on certain mode-line specification.
  
! @defun format-mode-line format &optional window no-props 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.
  
! For example, if @var{format} is @code{header-line-format} it returns the
! text that would appear in the header line (@code{""} if the window has
! no header line).  The argument @var{window} defaults to the selected
! window.
  
  The value string normally has text properties that correspond to the
  faces, keymaps, etc., that the mode line would have.  If

Re: format-mode-line

[Kim F. Storm]

Nick Roberts <nickrob@snap.net.nz> writes:

>  >     I suggest changing format-mode-line so that FORMAT is not optional and not
>  >     give a special meaning to nil and t. I think format-mode-line is currently
>  >     always used with a value for FORMAT. If this is a good idea, I offer to do
>  >     it and post my patch here.
>  > 
>  > The argument above seems convincing, so please do.
>

I see that the following patch has already been installed, but I have problem with it.

Specifically, it removes a useful feature of the old code:

When format is nil (for mode-line-format) or t (for header-line-format),
the resulting string is propertized with the proper mode-line and header-line
face as the base face.

This differs from specifying mode-line-format and header-line-format
as this does not put a base face on the formatted string.

With the patch, this distinction is no longer present.

IMHO, the fine thing with the old code was that (format-mode-line
nil) would give you an exact replica (except for the trailing dashes)
of the mode line, whereas (format-mode-line mode-line-format) only
gives an approximation.


The rationale for making FORMAT optional was that (format-mode-line)
should simply do the right thing [IMHO], i.e. return the current mode
line as specified by mode-line-format in the proper mode-line face.

In your original mail you said:

> The manual also says:
>
> > If FORMAT is `nil', that means to use `mode-line-format'
>  
> This does not seem to make sense because if header-line-format is nil
> then (format-mode-line header-line-format) will presumably return the
> mode-line of selected window as a string.

That is a problem indeed that I didn't think about.

> In any case, (format-mode-line) does not seem to give the right thing,
> although (format-mode-line mode-line-format) does.

I seems to work fine for me -- what is wrong with the return value?


I don't object to the patch as such, but I think it should be possible
somehow to specify the face to use for the string, e.g. we could change
the definition as follows with the following doc string:

(format-mode-line FORMAT &optional FACE WINDOW BUFFER)

Return a mode line format specification as a string.
First arg FORMAT specifies the mode line format (see `mode-line-format'
for details) to use.  Optional second arg FACE is the basic face to
use on the formatted string.  If FACE is nil, the returned string is
not propertized.  Optional third arg WINDOW specifies a different
window to use as the context for the formatting. Fourth optional arg
BUFFER specifies which buffer to use.

If FORMAT is t or the symbol `mode-line', this corresponds to
specifying `mode-line-format' for FORMAT and `mode-line' for FACE.  If
FORMAT is the symbol `header-line', format the `header-line-format' in
the `header-line' face.

Re: format-mode-line

[Nick Roberts]

 > >  >     I suggest changing format-mode-line so that FORMAT is not optional
 > >  >     and not give a special meaning to nil and t. I think
 > >  >     format-mode-line is currently always used with a value for
 > >  >     FORMAT. If this is a good idea, I offer to do it and post my patch
 > >  >     here.
 > >  > 
 > >  > The argument above seems convincing, so please do.
 > >
 > 
 > I see that the following patch has already been installed, but I have
 > problem with it.
 > 
 > Specifically, it removes a useful feature of the old code:
 > 
 > When format is nil (for mode-line-format) or t (for header-line-format),
 > the resulting string is propertized with the proper mode-line and header-line
 > face as the base face.

I'll show my ignorance: I don't know what a base face is and I can't
find a definition in the manual.

 > This differs from specifying mode-line-format and header-line-format
 > as this does not put a base face on the formatted string.
 > With the patch, this distinction is no longer present.
 > 
 > IMHO, the fine thing with the old code was that (format-mode-line
 > nil) would give you an exact replica (except for the trailing dashes)
 > of the mode line, whereas (format-mode-line mode-line-format) only
 > gives an approximation.

Perhaps this should have been mentioned in the manual too.

 > The rationale for making FORMAT optional was that (format-mode-line)
 > should simply do the right thing [IMHO], i.e. return the current mode
 > line as specified by mode-line-format in the proper mode-line face.
 > 
 > In your original mail you said:
 > 
 > > The manual also says:
 > >
 > > > If FORMAT is `nil', that means to use `mode-line-format'
 > >  
 > > This does not seem to make sense because if header-line-format is nil
 > > then (format-mode-line header-line-format) will presumably return the
 > > mode-line of selected window as a string.
 > 
 > That is a problem indeed that I didn't think about.
 > 
 > > In any case, (format-mode-line) does not seem to give the right thing,
 > > although (format-mode-line mode-line-format) does.
 > 
 > I seems to work fine for me -- what is wrong with the return value?

I use format-mode-line in the version of t-mouse.el that I posted here
recently to make clicking on the mode-line position dependent. It seems to
work with (format-mode-line mode-line-format) but not (format-mode-line). This
relates to an earlier post (format-mode-line and mode-line mouse events - 18
Dec 2004) where I gave an example output. My analysis might be feeble - the
output seems wrong to me but I don't understand what is happening enough to
correct it.

 > I don't object to the patch as such, but I think it should be possible
 > somehow to specify the face to use for the string, e.g. we could change
 > the definition as follows with the following doc string:
 > 
 > (format-mode-line FORMAT &optional FACE WINDOW BUFFER)
 > 
 > Return a mode line format specification as a string.
 > First arg FORMAT specifies the mode line format (see `mode-line-format'
 > for details) to use.  Optional second arg FACE is the basic face to
 > use on the formatted string.  If FACE is nil, the returned string is
 > not propertized.  Optional third arg WINDOW specifies a different
 > window to use as the context for the formatting. Fourth optional arg
 > BUFFER specifies which buffer to use.
 > 
 > If FORMAT is t or the symbol `mode-line', this corresponds to
 > specifying `mode-line-format' for FORMAT and `mode-line' for FACE.  If
 > FORMAT is the symbol `header-line', format the `header-line-format' in
 > the `header-line' face.

Sure. I don't understand where it would be used but it won't interfere with
my use of format-mode-line.


Nick

Re: format-mode-line

[Richard Stallman]

     > When format is nil (for mode-line-format) or t (for header-line-format),
     > the resulting string is propertized with the proper mode-line and header-line
     > face as the base face.

    I'll show my ignorance: I don't know what a base face is and I can't
    find a definition in the manual.

There is no term "base face".  What he means is a face to apply
by default to any characters that don't specify some other face.
So that you would get the same face actually used in the mode line.

I think adding an argument specifying a default face for format-mode-line
is a good way to do it.

Re: format-mode-line

[Stefan]

> There is no term "base face".  What he means is a face to apply
> by default to any characters that don't specify some other face.
> So that you would get the same face actually used in the mode line.

Is it added as a `face' text-property only at those spots where the `face'
property would otherwise be nil?  Or is it appended to the `face' property
of every character?

> I think adding an argument specifying a default face for format-mode-line
> is a good way to do it.

That's assuming that there is a need for such a feature.
I haven't seen no evidence of it.


        Stefan