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

[Jared Finder]

Thank you for all the feedback.  Updated patch attached.

On 2024-05-26 11:40, Eli Zaretskii wrote:
> > Date: Sun, 26 May 2024 09:20:56 -0700
> > From: Jared Finder <jared@finder.org>
> > Cc: juri@linkov.net, 68765@debbugs.gnu.org, philipk@posteo.net,
> >  monnier@iro.umontreal.ca
> >
> > >> +@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.
>
> But this means that the following text:
>
> > >                                                  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
>
> is at least inaccurate.  Specifically, if the frame's global tool bar
> changes as result of some command, the identity of the tool bars of
> windows to that of the frame is not re-examined.  So if some window
> decided that its tool bar is not to be displayed, it will remain
> undisplayed until that window shows a different buffer or its buffer
> changes its major mode.  Is that correct?  If not, why not?

Your understanding here is accurate.  I consider this behavior a bug 
that I'd like to fix (in normal use it rarely happens).  I suppose I 
could use add-variable-watcher to detect all changes to tool-bar-map and 
update tool bar visibility.  I'd like to make sure to do this correctly 
and not cause a significant performance hit.

Should such a temporary limitation be documented in the manual?  I added 
a section to describe this limitation to my patch, but I don't know if 
it is appropriate.

> Or maybe I don't understand well enough what you mean by "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."  You are using
> here terminology that is confusing: there's no "current window" in
> Emacs, only the "selected window", and it is unclear whether by
> "current buffer" you mean the global current buffer (the one returned
> by the function current-buffer) or the buffer shown in a window (since
> you also say "the window's current buffer", another term that we do
> not use).

Thanks for helping me here with terminology here.  Looking over the 
manual, it seems the proper terms are "current buffer", "selected 
window", and "buffer displayed in a window".  I have updated my patch to 
use these terms.

> > > 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))
>
> So a frame's tool bar can completely change its look due to :visible,
> and Emacs will still consider it "equal" to the tool bar of some
> window where those :visible conditions yield a completely different
> look?  Does that make sense?

From a functionality standpoint, I think it makes a lot of sense.  It's 
about if there's a major mode specific tool bar, not just if the list of 
buttons is different.  Major modes with custom tool bars are recommended 
to set tool-bar-map locally and that's what all customizations in core 
Emacs do.  An eq comparison properly catches this.

I have updated the patch to refer to the tool bar binding being 
different to try to communicate this.

> I'm beginning to think that the feature whereby we don't display the
> window's tool bar under some conditions "to conserve space" is more
> confusing and hard to document than is useful, and perhaps we should
> simply show the window's tool bar unconditionally?

I find it really useful to have this auto-show/hide behavior.  As I 
wrote in the docs, "you can think of the window tool bar as showing a 
major mode specific tool bar if it exists".  The most prominent other 
source of a custom tool bar is isearch.  Having no space taken up when 
editing a text file, then having the tool bar appear when I hit C-s 
lines up with what I see in many other programs.  I'd be sad to see this 
behavior removed.

> So what I would like us to say in the manual is that the value of
> window-tool-bar-format

Just to be clear -- there is no new line as you requested a while back. 
The mode just alters the value of tab-line-format.

> and of tab-line-format should produce what is
> expected from these lines: a row of tabs for tab-line and a row of
> icons for the tool bar.  The reader should understand that having a
> tab-line-format whose value is "%b %f", for example, makes no sense,
> although it will work.  (In general, most or all %-elements of mode
> line and header line make no sense in tab-line and tool bar.  It is
> hardly an accident that tab-line-format's value is just (:eval FUNC),
> in stark contrast to the value of mode-line-format and
> header-line-format in modes in which it is non-nil.)
>
> Did I succeed to explain my concerns?

Yes, I think I understand.  I have updated my patch.

  -- MJF

0001-Adding-documentation-for-window-tool-bar-bug-68765.patch
Description: Text Data