bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

I wanted to find out how to customize the image used for tab bar
buttons, but could not find anything in the manual.

It seems that setting the display property of `tab-bar-close-button' and
`tab-bar-new-button' is the way to go.

Shouldn't such an important customization be documented somewhere in the
manual?

Thanks.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Eli Zaretskii]

> Date: Sun, 07 Nov 2021 11:07:07 +0800
> From:  Po Lu via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> 
> I wanted to find out how to customize the image used for tab bar
> buttons, but could not find anything in the manual.
> 
> It seems that setting the display property of `tab-bar-close-button' and
> `tab-bar-new-button' is the way to go.
> 
> Shouldn't such an important customization be documented somewhere in the
> manual?

No, not necessarily.  The manual is not supposed to document all the
customizations we have, only the important ones.

What should be possible is to find the customization by browsing the
tab-bar Custom group.  If that is not currently possible (I didn't
check), then we should probably do something to fix that.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> I wanted to find out how to customize the image used for tab bar
>> buttons, but could not find anything in the manual.
>> 
>> It seems that setting the display property of `tab-bar-close-button' and
>> `tab-bar-new-button' is the way to go.
>> 
>> Shouldn't such an important customization be documented somewhere in the
>> manual?
>
> No, not necessarily.  The manual is not supposed to document all the
> customizations we have, only the important ones.

Note that I said it was important.

FWIW, Two people asked me how to change the image used for those buttons
today.  (In one instance, right after introducing him to the tab bar --
it seems to be a customization people commonly wish to make.)

> What should be possible is to find the customization by browsing the
> tab-bar Custom group.  If that is not currently possible (I didn't
> check), then we should probably do something to fix that.

It isn't, FWIW.  Thanks.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Eli Zaretskii]

> From: Po Lu <luangruo@yahoo.com>
> Cc: 51648@debbugs.gnu.org
> Date: Sun, 07 Nov 2021 15:23:57 +0800
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> Shouldn't such an important customization be documented somewhere in the
> >> manual?
> >
> > No, not necessarily.  The manual is not supposed to document all the
> > customizations we have, only the important ones.
> 
> Note that I said it was important.

I don't necessarily agree that it is important enough to be in the
manual.

> FWIW, Two people asked me how to change the image used for those buttons
> today.  (In one instance, right after introducing him to the tab bar --
> it seems to be a customization people commonly wish to make.)

Two people asking doesn't mean it's a common customization, and it is
too early to make those decisions anyway, as the feature is barely out
there.  Decisions about additions to the manual should not be taken
too easily, because the manual is printed and sold by the FSF, and any
addition to it makes the production of the manual more expensive.

> > What should be possible is to find the customization by browsing the
> > tab-bar Custom group.  If that is not currently possible (I didn't
> > check), then we should probably do something to fix that.
> 
> It isn't, FWIW.  Thanks.

Juri, can we please fix this?  Thanks.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> Decisions about additions to the manual should not be taken too
> easily, because the manual is printed and sold by the FSF, and any
> addition to it makes the production of the manual more expensive.

This is a detail I didn't take into account when making my request,
thanks for pointing it out.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

>> > What should be possible is to find the customization by browsing the
>> > tab-bar Custom group.  If that is not currently possible (I didn't
>> > check), then we should probably do something to fix that.
>>
>> It isn't, FWIW.  Thanks.
>
> Juri, can we please fix this?  Thanks.

Please specify to what extent it should be customizable.

Currently configuration of these buttons is possible with e.g.

  (setq tab-bar-close-button
        (propertize " x"
                    'display
                    `(image :type svg
                            :file "checkbox-mixed.svg"
                            :margin ,tab-bar-button-margin
                            :ascent center)
                    'close-tab t
                    :help "Click to close tab"))

  (setq tab-bar-new-button
        (propertize " + "
                    'display
                    `(image :type svg
                            :file "checked.svg"
                            :margin ,tab-bar-button-margin
                            :ascent center)
                    :help "Click to add tab"))

that uses SVG images.  Also it's possible to use Unicode chars with

  (setq tab-bar-close-button (propertize " x" 'display (propertize "✕" 'face 'tab-bar-tab-inactive) 'close-tab t))
  (setq tab-bar-new-button (propertize " + " 'display (propertize "➕" 'face 'tab-bar-tab)))

So I'd simply add such examples to the docstrings of these variables
for emacs-28.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: Po Lu <luangruo@yahoo.com>,  51648@debbugs.gnu.org
> Date: Sun, 07 Nov 2021 19:37:22 +0200
> 
> >> > What should be possible is to find the customization by browsing the
> >> > tab-bar Custom group.  If that is not currently possible (I didn't
> >> > check), then we should probably do something to fix that.
> >>
> >> It isn't, FWIW.  Thanks.
> >
> > Juri, can we please fix this?  Thanks.
> 
> Please specify to what extent it should be customizable.
> 
> Currently configuration of these buttons is possible with e.g.
> 
>   (setq tab-bar-close-button
>         (propertize " x"
>                     'display
>                     `(image :type svg
>                             :file "checkbox-mixed.svg"
>                             :margin ,tab-bar-button-margin
>                             :ascent center)
>                     'close-tab t
>                     :help "Click to close tab"))
> 
>   (setq tab-bar-new-button
>         (propertize " + "
>                     'display
>                     `(image :type svg
>                             :file "checked.svg"
>                             :margin ,tab-bar-button-margin
>                             :ascent center)
>                     :help "Click to add tab"))
> 
> that uses SVG images.  Also it's possible to use Unicode chars with
> 
>   (setq tab-bar-close-button (propertize " x" 'display (propertize "✕" 'face 'tab-bar-tab-inactive) 'close-tab t))
>   (setq tab-bar-new-button (propertize " + " 'display (propertize "➕" 'face 'tab-bar-tab)))

I thought there were some defcustom's for that, but they weren't
easily discoverable by browsing the tab-bar customization group.  But
if you didn't intend to let users customize those, it's up to you.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

>>   (setq tab-bar-close-button (propertize " x" 'display (propertize "✕" 'face 'tab-bar-tab-inactive) 'close-tab t))
>>   (setq tab-bar-new-button (propertize " + " 'display (propertize "➕" 'face 'tab-bar-tab)))
>
> I thought there were some defcustom's for that, but they weren't
> easily discoverable by browsing the tab-bar customization group.  But
> if you didn't intend to let users customize those, it's up to you.

The problem is that I don't know how it's possible to customize
a string with text properties on it.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Eli Zaretskii]

> From: Juri Linkov <juri@linkov.net>
> Cc: luangruo@yahoo.com,  51648@debbugs.gnu.org
> Date: Sun, 07 Nov 2021 20:31:34 +0200
> 
> >>   (setq tab-bar-close-button (propertize " x" 'display (propertize "✕" 'face 'tab-bar-tab-inactive) 'close-tab t))
> >>   (setq tab-bar-new-button (propertize " + " 'display (propertize "➕" 'face 'tab-bar-tab)))
> >
> > I thought there were some defcustom's for that, but they weren't
> > easily discoverable by browsing the tab-bar customization group.  But
> > if you didn't intend to let users customize those, it's up to you.
> 
> The problem is that I don't know how it's possible to customize
> a string with text properties on it.

Well, the request was to allow customization of the image on the tabs,
so maybe have just the image(s) customizable?

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

>> >>   (setq tab-bar-close-button (propertize " x" 'display (propertize "✕" 'face 'tab-bar-tab-inactive) 'close-tab t))
>> >>   (setq tab-bar-new-button (propertize " + " 'display (propertize "➕" 'face 'tab-bar-tab)))
>> >
>> > I thought there were some defcustom's for that, but they weren't
>> > easily discoverable by browsing the tab-bar customization group.  But
>> > if you didn't intend to let users customize those, it's up to you.
>> 
>> The problem is that I don't know how it's possible to customize
>> a string with text properties on it.
>
> Well, the request was to allow customization of the image on the tabs,
> so maybe have just the image(s) customizable?

I don't know, let's wait for Po Lu to clarify what people want to customize.
Just a file name of an image file as a string?

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Po Lu via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Juri Linkov <juri@linkov.net> writes:

>> Well, the request was to allow customization of the image on the tabs,
>> so maybe have just the image(s) customizable?
>
> I don't know, let's wait for Po Lu to clarify what people want to customize.
> Just a file name of an image file as a string?

People generally want to customize the image, and perhaps the scale of
that image.

But I see no harm in letting people customize the whole string, if he
wants to.

Thanks!

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

> People generally want to customize the image, and perhaps the scale of
> that image.
>
> But I see no harm in letting people customize the whole string, if he
> wants to.

I can't imagine how Customization UI could support customization of
such strings with text properties and images on them.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 606 bytes --]

>> People generally want to customize the image, and perhaps the scale of
>> that image.
>>
>> But I see no harm in letting people customize the whole string, if he
>> wants to.
>
> I can't imagine how Customization UI could support customization of
> such strings with text properties and images on them.

Fortunately, now we have customizable icons.  So I tried to do this
with a patch like below, but compilation failed with this error
because tab-bar.el is pre-loaded:

  Loading tab-bar (native compiled elisp)...
  Error: void-function (icons--register)
  (require cl-print) while preparing to dump


[-- Attachment #2: tab-bar-new-icon.patch --]
[-- Type: text/x-diff, Size: 1238 bytes --]

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index 561365bb48..5d990ac184 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -33,7 +33,8 @@
 
 (eval-when-compile
   (require 'cl-lib)
-  (require 'seq))
+  (require 'seq)
+  (require 'icons))
 
 \f
 (defgroup tab-bar nil
@@ -521,6 +522,17 @@ tab-bar-new-button-show
 (defvar tab-bar-new-button " + "
   "Button for creating a new tab.")
 
+(define-icon tab-bar-new-icon nil
+  `((image "tabs/new.xpm"
+           :margin ,tab-bar-button-margin
+           :ascent center)
+    (emoji "➕")
+    (symbol "＋")
+    (text " + " :face tab-bar-tab))
+  "Icon for creating a new tab."
+  :version "29.1"
+  :help-echo "New tab")
+
 (defcustom tab-bar-close-button-show t
   "Defines where to show the close tab button.
 If t, show the close tab button on all tabs.
@@ -905,8 +925,8 @@ tab-bar-format-tabs-groups
 
 (defun tab-bar-format-add-tab ()
   "Button to add a new tab."
-  (when (and tab-bar-new-button-show tab-bar-new-button)
-    `((add-tab menu-item ,tab-bar-new-button tab-bar-new-tab
+  (when (and tab-bar-new-button-show)
+    `((add-tab menu-item ,(icon-string 'tab-bar-new-icon) tab-bar-new-tab
                :help "New tab"))))
 
 (defun tab-bar-format-align-right ()

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 360 bytes --]

> Fortunately, now we have customizable icons.  So I tried to do this
> with a patch like below, but compilation failed with this error
> because tab-bar.el is pre-loaded:
>
>   Loading tab-bar (native compiled elisp)...
>   Error: void-function (icons--register)
>   (require cl-print) while preparing to dump
>

OTOH, the following patch works pretty well:


[-- Attachment #2: tab-bar-icons.patch --]
[-- Type: text/x-diff, Size: 4631 bytes --]

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index abefd996a8a..777837f4db7 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -155,25 +155,34 @@ tab-bar--undefine-keys
 
 (defun tab-bar--load-buttons ()
   "Load the icons for the tab buttons."
-  (when (and tab-bar-new-button
-             (not (get-text-property 0 'display tab-bar-new-button)))
-    ;; This file is pre-loaded so only here we can use the right data-directory:
-    (add-text-properties 0 (length tab-bar-new-button)
-                         `(display (image :type xpm
-                                          :file "tabs/new.xpm"
-                                          :margin ,tab-bar-button-margin
-                                          :ascent center))
-                         tab-bar-new-button))
+  (require 'icons)
 
-  (when (and tab-bar-close-button
-             (not (get-text-property 0 'display tab-bar-close-button)))
-    ;; This file is pre-loaded so only here we can use the right data-directory:
-    (add-text-properties 0 (length tab-bar-close-button)
-                         `(display (image :type xpm
-                                          :file "tabs/close.xpm"
-                                          :margin ,tab-bar-button-margin
-                                          :ascent center))
-                         tab-bar-close-button)))
+  (unless (iconp 'tab-bar-new)
+    (define-icon tab-bar-new nil
+      `((image "tabs/new.xpm"
+               :margin ,tab-bar-button-margin
+               :ascent center)
+        ;; (emoji "➕")
+        ;; (symbol "＋")
+        (text " + "))
+      "Icon for creating a new tab."
+      :version "29.1"
+      :help-echo "New tab"))
+  (setq tab-bar-new-button (icon-string 'tab-bar-new))
+
+  (unless (iconp 'tab-bar-close)
+    (define-icon tab-bar-close nil
+      `((image "tabs/close.xpm"
+               :margin ,tab-bar-button-margin
+               :ascent center)
+        ;; (emoji " ❌")
+        ;; (symbol "ⓧ")
+        (text " x"))
+      "Icon for closing the clicked tab."
+      :version "29.1"
+      :help-echo "Click to close tab"))
+  (setq tab-bar-close-button (propertize (icon-string 'tab-bar-close)
+                                         'close-tab t)))
 
 (defun tab-bar--tab-bar-lines-for-frame (frame)
   "Determine and return the value of `tab-bar-lines' for FRAME.
@@ -1916,22 +1933,27 @@ tab-bar-history-mode
   :global t :group 'tab-bar
   (if tab-bar-history-mode
       (progn
-        (when (and tab-bar-mode (not (get-text-property 0 'display tab-bar-back-button)))
-          ;; This file is pre-loaded so only here we can use the right data-directory:
-          (add-text-properties 0 (length tab-bar-back-button)
-                               `(display (image :type xpm
-                                                :file "tabs/left-arrow.xpm"
-                                                :margin ,tab-bar-button-margin
-                                                :ascent center))
-                               tab-bar-back-button))
-        (when (and tab-bar-mode (not (get-text-property 0 'display tab-bar-forward-button)))
-          ;; This file is pre-loaded so only here we can use the right data-directory:
-          (add-text-properties 0 (length tab-bar-forward-button)
-                               `(display (image :type xpm
-                                                :file "tabs/right-arrow.xpm"
-                                                :margin ,tab-bar-button-margin
-                                                :ascent center))
-                               tab-bar-forward-button))
+        (require 'icons)
+
+        (unless (iconp 'tab-bar-back)
+          (define-icon tab-bar-back nil
+            `((image "tabs/left-arrow.xpm"
+                     :margin ,tab-bar-button-margin
+                     :ascent center)
+              (text " < "))
+            "Icon for going back in tab history."
+            :version "29.1"))
+        (setq tab-bar-back-button (icon-string 'tab-bar-back))
+
+        (unless (iconp 'tab-bar-forward)
+          (define-icon tab-bar-forward nil
+            `((image "tabs/right-arrow.xpm"
+                     :margin ,tab-bar-button-margin
+                     :ascent center)
+              (text " > "))
+            "Icon for going forward in tab history."
+            :version "29.1"))
+        (setq tab-bar-forward-button (icon-string 'tab-bar-forward))
 
         (add-hook 'pre-command-hook 'tab-bar--history-pre-change)
         (add-hook 'window-configuration-change-hook 'tab-bar--history-change))

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

forcemerge 51309 51648
thanks

> People generally want to customize the image, and perhaps the scale of
> that image.
>
> But I see no harm in letting people customize the whole string, if he
> wants to.

Please see also bug#51309.

bug#51648: 28.0.60; `tab-bar-close-button' and `tab-bar-new-button' should be documented in the manual

[Juri Linkov]

> Well, the request was to allow customization of the image on the tabs,
> so maybe have just the image(s) customizable?

I noticed that in addition that the button for tab-bar-format-menu-bar
is not customizable, it also has a bug:

  `((menu-bar menu-item (propertize "Menu" 'face 'tab-bar-tab-inactive)
     tab-bar-menu-bar :help "Menu Bar")))
 
i.e. the part with (propertize "Menu" 'face 'tab-bar-tab-inactive)
is inside the quoted list, but it should be unquoted with `,'.

If it's ok to leave this bug in the release branch,
then maybe this patch should be applied only to master?

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index d49fc2efea..4c95438bae 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -751,9 +751,13 @@ tab-bar-menu-bar
                 (menu-bar-keymap))
     (popup-menu menu event)))
 
+(defvar tab-bar-menu-bar-button
+  (propertize "Menu" 'face 'tab-bar-tab-inactive)
+  "Button for the menu bar.")
+
 (defun tab-bar-format-menu-bar ()
   "Produce the Menu button for the tab bar that shows the menu bar."
-  `((menu-bar menu-item (propertize "Menu" 'face 'tab-bar-tab-inactive)
+  `((menu-bar menu-item ,tab-bar-menu-bar-button
      tab-bar-menu-bar :help "Menu Bar")))
 
--