procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add documentation for window-tool-bar package

Browse source 
Also change window-tool-mode to not pay attention to if
tool-bar-map has a buffer local value or not as that made the
documentation complicated.  Documentation added in Emacs manual,
Elisp manual, package commentary, and docstrings.  Also extend
window-tool-bar support to Emacs 27 and newer.  (bug#68765)

* doc/emacs/emacs.texi (Top):
* doc/emacs/frames.texi (Menu Bars):
* doc/emacs/glossary.texi (Glossary):
* doc/emacs/modes.texi (Minor Modes):
* doc/emacs/windows.texi (Windows, Tab Line): Mention Window
Tool Bar.
(Window Tool Bar): New documentation.
* doc/lispref/elisp.texi (Top):
* doc/lispref/modes.texi (Mode Line Format, Mode Line Basics)
(Mode Line Data): Mention Tab Lines.
(Tab Lines): New documentation.
* etc/NEWS: Mention newly added variable and package.
* lisp/window-tool-bar.el (window-tool-bar-mode): Don't display
tool bar when tool-bar-map is nil.
* lisp/window-tool-bar.el (tool-bar-always-show-default): Define
variable for older Emacs versions.
This commit is contained in:
Jared Finder 2024-06-08 17:23:58 -07:00 • committed by Eli Zaretskii
parent 7f8ded2a85
commit a5c0d682b1
9 changed files with 135 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/emacs/emacs.texi
View file

@ -529,6 +529,7 @@ Multiple Windows
* Temporary Displays:: Displaying non-editable buffers.
* Window Convenience:: Convenience functions for window handling.
* Tab Line:: Window tab line.
* Window Tool Bar:: A tool bar that is attached to windows.
Displaying a Buffer in a Window

14
doc/emacs/frames.texi
View file

@ -1295,16 +1295,22 @@ menus' visual appearance.
@node Tool Bars
@section Tool Bars
@cindex tool bar mode
@cindex tool bar, attached to frame
@cindex mode, Tool Bar
@cindex icons, toolbar
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 click on with the mouse to invoke various commands.
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 buttons with icons
which you can click on with the mouse to invoke various commands. Emacs
can also optionally display a tool bar at the top of each window
(@pxref{Window Tool Bar}).
@vindex tool-bar-always-show-default
The global (default) tool bar contains general commands. Some major
modes define their own tool bars; whenever a buffer with such a major
mode is current, the mode's tool bar replaces the global tool bar.
mode is current, the mode's tool bar replaces the global tool bar. To
prevent this replacement from happening, customize the variable
@code{tool-bar-always-show-default}.
@findex tool-bar-mode
@vindex tool-bar-mode

10
doc/emacs/glossary.texi
View file

@ -1436,10 +1436,12 @@ particular appearance or behavior. For example, you might use a theme
for your favorite set of faces (q.v.).
@item Tool Bar
The tool bar is a line (sometimes multiple lines) of icons at the top
of an Emacs frame. Clicking on one of these icons executes a command.
You can think of this as a graphical relative of the menu bar (q.v.).
@xref{Tool Bars}.
The tool bar is a line (sometimes multiple lines) of buttons with icons
at the top of an Emacs frame. Clicking on one of these buttons executes
a command. You can think of this as a graphical relative of the menu
bar (q.v.). @xref{Tool Bars}. There is also a window tool bar that
behaves similarly, but is at the top of an Emacs window. @xref{Window
Tool Bar}.
@anchor{Glossary---Tooltips}
@item Tooltips

3
doc/emacs/modes.texi
View file

@ -295,6 +295,9 @@ Tool Bar mode gives each frame a tool bar. It is enabled by default,
but the tool bar is only displayed on graphical terminals. @xref{Tool
Bars}.
@item
Window Tool Bar mode gives windows a tool bar. @xref{Window Tool Bar}.
@item
Tab Bar mode gives each frame a tab bar. @xref{Tab Bars}.

43
doc/emacs/windows.texi
View file

@ -22,6 +22,7 @@ one frame.
* Displaying Buffers:: How Emacs picks a window for displaying a buffer.
* Window Convenience:: Convenience functions for window handling.
* Tab Line:: Window tab line.
* Window Tool Bar:: A tool bar that is attached to windows.
@end menu
@node Basic Window
@ -689,3 +690,45 @@ Whereas tabs on the Tab Bar at the top of each frame are used to
switch between window configurations containing several windows with buffers,
tabs on the Tab Line at the top of each window are used to switch
between buffers in the window.
Also note that the tab line displays in the same space as the window
tool bar, so only one of these can be display at a time unless you
customize the value of @code{tab-line-format} in Lisp. In this case,
add @code{(:eval (tab-line-format))} to @code{tab-line-format}.
@xref{Mode Line Format,,, elisp, The Emacs Lisp Reference Manual}.
@node Window Tool Bar
@section Window Tool Bar
@cindex window tool bar
@cindex mode, window tool bar
@cindex tool bar, attached to window
@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 hidden if there are no buttons to show, i.e. if
@code{tool-bar-map} is @code{nil}.
@findex window-tool-bar-mode
If you want to toggle the display of a window tool bar for only some
buffers, run the command @code{window-tool-bar-mode} in those buffers.
This is useful to put in a mode hook. For example, if you want the window
tool bar to appear only for buffers that do not represent files and have
a custom tool bar, you could add the following code to your init file
(@pxref{Init File}):
@example
(add-hook 'special-mode-hook 'window-tool-bar-mode)
@end example
Emacs can also display a single tool bar at the top of frames
(@pxref{Tool Bars}).
Note that the window tool bar displays in the same space as the tab
line, so only one of these can be display at a time unless you customize
the value of @code{tab-line-format} in Lisp. In this case, add
@code{(:eval (window-tool-bar-string))} to @code{tab-line-format}.
@xref{Mode Line Format,,, elisp, The Emacs Lisp Reference Manual}.

1
doc/lispref/elisp.texi
View file

@ -925,6 +925,7 @@ Mode Line Format
* %-Constructs:: Putting information into a mode line.
* Properties in Mode:: Using text properties in the mode line.
* Header Lines:: Like a mode line, but at the top.
* Tab Lines:: A line that is above the header line.
* Emulating Mode Line:: Formatting text as the mode line would.
Font Lock Mode

56
doc/lispref/modes.texi
View file

@ -2074,14 +2074,14 @@ their previous values/states (using the companion function
line at the bottom, which displays status information about the buffer
displayed in the window. The mode line contains information about the
buffer, such as its name, associated file, depth of recursive editing,
and major and minor modes. A window can also have a @dfn{header
line}, which is much like the mode line but appears at the top of the
window.
and major and minor modes. A window can also have a @dfn{header line}
and a @dfn{tab line}, which are much like the mode line but they appear
at the top of the window.
This section describes how to control the contents of the mode line
and header line. We include it in this chapter because much of the
information displayed in the mode line relates to the enabled major and
minor modes.
This section describes how to control the contents of the mode line,
header line, and tab line. We include it in this chapter because much
of the information displayed in the mode line relates to the enabled
major and minor modes.
@menu
* Base: Mode Line Basics. Basic ideas of mode line control.
@ -2091,6 +2091,7 @@ minor modes.
* %-Constructs:: Putting information into a mode line.
* Properties in Mode:: Using text properties in the mode line.
* Header Lines:: Like a mode line, but at the top.
* Tab Lines:: A line that is above the header line.
* Emulating Mode Line:: Formatting text as the mode line would.
@end menu
@ -2101,11 +2102,13 @@ minor modes.
variable @code{mode-line-format} (@pxref{Mode Line Top}). This variable
holds a @dfn{mode line construct}: a template that controls what is
displayed on the buffer's mode line. The value of
@code{header-line-format} specifies the buffer's header line in the same
way. All windows for the same buffer use the same
@code{mode-line-format} and @code{header-line-format} unless a
@code{mode-line-format} or @code{header-line-format} parameter has been
specified for that window (@pxref{Window Parameters}).
@code{header-line-format} and @code{tab-line-format} specifies the
buffer's header line and tab line in the same way. All windows for the
same buffer use the same @code{mode-line-format},
@code{header-line-format}, and @code{tab-line-format} unless a
@code{mode-line-format}, @code{header-line-format}, or
@code{tab-line-format} parameter has been specified for that window
(@pxref{Window Parameters}).
For efficiency, Emacs does not continuously recompute each window's
mode line and header line. It does so when circumstances appear to call
@ -2167,8 +2170,8 @@ buffers.
@dfn{mode line construct}, made up of lists, strings, symbols, and
numbers kept in buffer-local variables. Each data type has a specific
meaning for the mode line appearance, as described below. The same data
structure is used for constructing frame titles (@pxref{Frame Titles})
and header lines (@pxref{Header Lines}).
structure is used for constructing frame titles (@pxref{Frame Titles}),
header lines (@pxref{Header Lines}), and tab lines (@pxref{Tab Lines}).
A mode line construct may be as simple as a fixed string of text,
but it usually specifies how to combine fixed strings with variables'
@ -2816,6 +2819,31 @@ window that is two lines tall cannot display both a mode line and a
header line at once; if it has a mode line, then it does not display a
header line.
@node Tab Lines
@subsection Window Tab Lines
@cindex tab line (of a window)
@cindex window tab line
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 is controlled like the mode line feature, except
that it's controlled by @code{tab-line-format}. Unlike the mode line,
the tab line is only expected to be used to display a list of tabs
(@pxref{Tab Line,,, emacs, The GNU Emacs Manual}) or the window
tool bar (@pxref{Window Tool Bar,,, emacs, The GNU Emacs Manual}):
@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
@defun window-tab-line-height &optional window
This function returns the height in pixels of @var{window}'s tab line.
@var{window} must be a live window, and defaults to the selected window.
@end defun
@node Emulating Mode Line
@subsection Emulating Mode Line Formatting

12
etc/NEWS
View file

@ -264,6 +264,11 @@ window systems other than Nextstep.
When this minor mode is enabled, buttons representing modifier keys
are displayed along the tool bar.
+++
** New user option 'tool-bar-always-show-default'.
When non-nil, the tool bar at the top of a frame does not show buffer
local customization of the tool bar. The default value is nil.
+++
** "d" in the mode line now indicates that the window is dedicated.
Windows have always been able to be dedicated to a specific buffer;
@ -2017,6 +2022,13 @@ To revert to the previous behavior, set the (also new) variable
'async-shell-command-mode' to 'shell-mode'. Any hooks or mode-specific
variables used should be adapted appropriately.
+++
** New package Window-Tool-Bar.
This provides a new minor mode, 'window-tool-bar-mode'. When this minor
mode is enabled, a tool bar is displayed at the top of a window. To
conserve space, no tool bar is shown if 'tool-bar-map' is nil. The
global minor mode 'global-window-tool-bar-mode' enables this minor mode
in all buffers.
* Incompatible Lisp Changes in Emacs 30.1

27
lisp/window-tool-bar.el
View file

@ -4,9 +4,9 @@
;; Author: Jared Finder <jared@finder.org>
;; Created: Nov 21, 2023
;; Version: 0.2
;; Version: 0.2.1
;; Keywords: mouse
;; Package-Requires: ((emacs "29.1"))
;; Package-Requires: ((emacs "27.1") (compat "29.1"))
;; This is a GNU ELPA :core package. Avoid adding functionality that
;; is not available in the version of Emacs recorded above or any of
@ -35,11 +35,11 @@
;; generally have sensible tool bars, for example: *info*, *help*, and
;; *eww* have them.
;;
;; It does this while being mindful of screen real estate. Most modes
;; do not provide a custom tool bar, and this package does not show the
;; default tool bar. This means that for most buffers there will be no
;; space taken up. Furthermore, you can put this tool bar in the mode
;; line or tab line if you want to share it with existing content.
;; It does this while being mindful of screen real estate. If
;; `tool-bar-map' is nil, then this package will not take up any space
;; for an empty tool bar. Most modes do not define a custom tool bar,
;; so calling (setq tool-bar-map nil) in your init file will make most
;; buffers not take up space for a tool bar.
;;
;; To get the default behavior, run (global-window-tool-bar-mode 1) or
;; enable via M-x customize-group RET window-tool-bar RET. This uses
@ -48,6 +48,9 @@
;; If you want to share space with an existing tab line, mode line, or
;; header line, add (:eval (window-tool-bar-string)) to
;; `tab-line-format', `mode-line-format', or `header-line-format'.
;;
;; For additional documentation, see info node `(emacs)Window Tool
;; Bar'
;;; Known issues:
;;
@ -92,6 +95,7 @@
;;; Code:
(require 'compat)
(require 'mwheel)
(require 'tab-line)
(require 'tool-bar)
@ -271,7 +275,7 @@ This is for when you want more customizations than
(defun window-tool-bar--keymap-entry-to-string (menu-item)
"Convert MENU-ITEM into a (propertized) string representation.
MENU-ITEM is a menu item to convert. See info node (elisp)Tool Bar."
MENU-ITEM is a menu item to convert. See info node `(elisp)Tool Bar'."
(pcase-exhaustive menu-item
;; Separators
((or `(,_ "--")
@ -394,8 +398,7 @@ enclosed in a `progn' form. ELSE-FORMS may be empty."
"Toggle display of the tool bar in the tab line of the current buffer."
:global nil
(let ((should-display (and window-tool-bar-mode
(not (eq tool-bar-map
(default-value 'tool-bar-map)))))
tool-bar-map))
(default-value '(:eval (window-tool-bar-string))))
;; Preserve existing tab-line set outside of this mode
@ -465,6 +468,10 @@ capabilities."
:group 'window-tool-bar)
;;; Workaround for https://debbugs.gnu.org/cgi/bugreport.cgi?bug=68334.
;; This special variable is added in Emacs 30.1.
(defvar tool-bar-always-show-default)
(defun window-tool-bar--get-keymap ()
"Return the tool bar keymap."
(let ((tool-bar-always-show-default nil))