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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 02 Jun 2024 08:21:58 +0300

> Date: Sat, 01 Jun 2024 21:17:58 -0700
> From: Jared Finder <[email-masked]>
> Cc: [email-masked], [email-masked], [email-masked],
>  [email-masked]
> 
> >> > 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).

If this is a bug which we will fix, then it gets me back to my
question above: Wouldn't these changes in window tool bars cause
annoying flickering of the display that distract the user's attention?

> 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.

There should be no need to use watchers.  You can instead add a
function to pre-redisplay-function hook.  This hook is called each
time Emacs is about to update the menu bar and the tool bar of some
frames.

> 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.

No, if this is a bug, we don't describe them in the manual.

> > 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".

That's okay, I'm just saying that if the window's major mode has its
own tool bar, we should show that tool bar on a window regardless of
whether the frame's tool bar shows the same buttons.

> The most prominent other source of a custom tool bar is isearch.

Oh, there are many more modes that customize the tool bar in important
ways.  Help mode, Info mode, Customize, GUD modes, email modes, Grep,
and EWW, to name just a few popular ones.

> 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.

That's not what I'm talking about.  I'm talking about removing the
window's tool bar because the frame's tool bar became identical to it.
Here's a scenario:

  . you have a frame with Info mode and some other mode
  . the frame's tool bar is the default one, and the window under Info
    shows its own tool bar from info.el
  . now I type "C-h i" in the window that was previously in mode other
    than Info -- now the frame's tool bar is the one from Info mode,
    and suddenly the other window loses its window-specific tool bar!

IOW, what bothers me is that we _remove_ the window's tool bar because
the frame-global tool bar changed.  And you just confirmed above that,
while currently this is not the behavior, you'd like to fix the code
so it _is_ the behavior.

Am I missing something?

> +  On graphical displays, Emacs puts a @dfn{tool bar} at the top of each
> +frame, just below the menu bar.  This is a row of icons which you can
                                                     ^^^^^
"buttons with icons"

> +The tool bar is a line (sometimes multiple lines) of icons at the top of
                                                        ^^^^^
Likewise.

> +  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 the window's displayed
> +buffer has a different binding from the global (default) tool bar.  The

This should explain what does "global (default) tool bar" mean.  My
understanding is that this is the tool bar shown for the frame, which
will continue working as it does now, i.e. be determined by the major
mode of the frame's selected window.

> +Emacs can also display a single tool bar at the top of frames
> +(@pxref{Tool Bars}).  When showing a tool bar at the top of frames as
> +well as windows, you may want to have the frame tool bar not change
> +based on the current buffer's major mode.

There's a subtlety here: the frame's tool bar is determined by the
major mode of the buffer shown in the frame's selected window, not by
the current buffer (which is a single buffer, not per frame).