bug#68765: 30.0.50; Adding window-tool-bar package.

[Jared Finder via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

On 2024-05-26 02:44, Eli Zaretskii wrote:
>> Date: Sat, 25 May 2024 12:54:30 -0700
>> From: Jared Finder <jared@finder.org>
>> Cc: juri@linkov.net, 68765@debbugs.gnu.org, philipk@posteo.net,
>>  monnier@iro.umontreal.ca
>> 
>> Ok, I tried to fit into the existing convention but not use upper case
>> letters with "@cindex mode, window tool bar".  Let me know if that's 
>> not
>> appropriate.
> 
> LGTM, thanks.
> 
>> That's what I was concerned about.  Please let me know if this updated
>> text is clear enough.
>> 
>> > I will wait for the next version to see if my questions are now
>> > answered or we need to discuss them further.
>> 
>> New patch attached.  Feedback welcome.
> 
> Thanks, some comments below.

The questions around current behavior may be clarified by describing how 
the internals work.

There's a new function, window-tool-bar-string, which converts the 
binding of <tool-bar> to a propertized string containing clickable 
buttons for the tool bar.  This function depends on the current buffer 
but that doesn't result in flickering, see the next paragraph.

window-tool-bar-mode toggles the buffer local value of tab-line-format 
between nil, which shows no tab line, and (:eval 
(window-tool-bar-string)), which shows tool bar buttons in the tab line. 
  When "evaluating" tab-line-format for display Emacs already temporarily 
sets the current buffer, so this evaluation only shows that buffer's 
tool bar, ignoring whatever the user's current buffer is.

And finally, window-tool-bar-mode will keep tab-line-format as nil if 
the binding of <tool-bar> is the same as the global binding because 
setting tab-line-format to non-nil causes the tab line to take up a row, 
even if the result is just an empty string.


Answers also for the questions below follow.

>> +@findex global-window-tool-bar-mode
>> +  The command @code{global-window-tool-bar-mode} toggles the display 
>> of
>> +a tool bar at the top of each window.  When enabled, multiple windows
>> +can display their own tool bar simultaneously.  To conserve space, a
>> +window tool bar is only shown if the tool bar for that window's 
>> current
>> +buffer is different from the global (default) tool bar.  The most 
>> common
>> +way a buffer has a different tool bar is due to its major mode, so 
>> you
>> +can think of the window tool bar as showing a major mode's tool bar 
>> if
>> +it exists.
> 
> So, let me understand what happens under this global mode.  By
> default, the frame's tool bar changes according to the major mode of
> the buffer shown in the frame's selected window.  As a very frequent
> example, entering the minibuffer from a buffer whose mode is, say,
> Dired or Rmail or Info, changes the tool bar.  When that happens, some
> windows which previously didn't display their tool bar because it was
> identical to the frame's tool bar will now display their tool bars.
> Right?  And when you exit the minibuffer, those window-specific tool
> bars will again disappear, right?  Wouldn't that cause annoying
> flickering of the display?  (I know that setting
> tool-bar-always-show-default non-nil can prevent that, but I'm asking
> about the default behavior.)

No, this is not the behavior.  The window tool bar displays that 
buffer's binding of <tool-bar>.  The window tool bar is displayed in the 
tab line of each window and doesn't pay attention to what the current 
buffer or window is.

> Btw, what exactly is the meaning of "the tool bar of the window is
> different from the global tool bar"?  How are tool bars compared?  For
> example, a button on the tool bar can have the :visible attribute,
> which will cause the icon not to appear under some conditions -- will
> a tool bar with that icon on display be considered "different" from a
> tool bar where the icon is not shown due to :visible conditions?

It's specifically using the following test:

(eq tool-bar-map
     (default-value 'tool-bar-map))

This is because the binding for <tool-bar> is actually :filter 
tool-bar-make-keymap which generates a keymap based on tool-bar-map.


Other comments all addressed in an upcoming patch except this one:

>> +  A window can have a @dfn{tab line} at the top.  If both the tab 
>> line
>> +and header line are visible, the tab line appears above the header 
>> line.
>> +The tab line feature works just like the mode line feature, except 
>> that
>> +it's controlled by @code{tab-line-format}:
>> +
>> +@defvar tab-line-format
>> +This variable, local in every buffer, specifies how to display the 
>> tab
>> +line, for windows displaying the buffer.  The format of the value is 
>> the
>> +same as for @code{mode-line-format} (@pxref{Mode Line Data}).  It is
>> +normally @code{nil}, so that ordinary buffers have no tab line.
>> +@end defvar
> 
> I wonder whether it's a good idea to tell that tab line works "the
> same as mode line", since the purpose is very different, and the
> default value of tab-line-format is very different from the default of
> mode-line-format.  At the very least I think we should tell that
> tab-line-format should cause the tab line appear as a row of buttons,
> clicking on which should change the buffer shown in the window.

Perhaps there's some sort of convention we can describe that talks about 
the difference between header-line-format and tab-line-format?  I'd like 
to copy back any changes to header-line-format which I based this text 
off of.

It seems to me that really the only difference is conventional.  I'm 
thinking something along the lines of "header line is usually modified 
by major modes to add additional info (examples: EWW, Info) and the tab 
line is usually modified by minor modes to add IDE-styled buttons 
(examples: tab line mode, window tool bar mode)".

Does that sound right to you?  I'd make the text more specific in its 
description, I just want to confirm the general intent.

   -- MJF