[PATCH] Document tab opening/closing hooks and variables

[PATCH] Document tab opening/closing hooks and variables

[Robert Cochran]

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

Hi all,

As promised, I've written information on tab-bar-post-open-functions,
tab-bar-close-last-tab-choice, tab-bar-prevent-close-functions, and
tab-bar-post-close-functions in the manual.

Suggestions and comments welcome, as usual.

Thanks,
-- 
~Robert Cochran


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch to document new tab open/close custom variables --]
[-- Type: text/x-patch, Size: 2936 bytes --]

From 95f26f10030dca8954be16a540d6d699f4567131 Mon Sep 17 00:00:00 2001
From: Robert Cochran <robert-git@cochranmail.com>
Date: Tue, 10 Dec 2019 13:25:08 -0800
Subject: [PATCH] Document tab opening/closing hooks and variables

* doc/emacs/frame.texi (Tab Bats): Document
tab-bar-post-open-functions, tab-bar-close-last-tab-choice,
tab-bar-prevent-close-functions, and tab-bar-pre-close-functions.
---
 doc/emacs/frames.texi | 44 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index 3a98df7de9..1af06dd308 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1313,8 +1313,9 @@ Tab Bars
 @item C-x t 0
 @kindex C-x t 0
 @findex tab-close
-Close the selected tab (@code{tab-close}).  It has no effect if there
-is only one tab.
+Close the selected tab (@code{tab-close}).  Its effect when there is
+only one tab is determined by the variable
+@code{tab-bar-close-last-tab-choice}.
 
 @item C-x t o
 @kindex C-x t o
@@ -1329,6 +1330,45 @@ Tab Bars
 @kindex C-x t 1
 @findex tab-close-other
 Close all tabs on the selected frame, except the selected one.
+@end table
+
+  The following customizable variables provide more fine-grained
+control over tab opening and closing:
+
+@table @code
+@item tab-bar-post-open-functions
+@vindex tab-bar-post-open-functions
+A list of functions to be called to perform any final setup tasks just
+after the tab is opened.  Each function is called with the new tab as
+an argument, and this new tab will be the current tab.
+
+@item tab-bar-close-last-tab-choice
+@vindex tab-bar-close-last-tab-choice
+Determines what to do when the last tab on a frame is going to be
+closed.  The value @code{nil} means to do nothing and display a
+message in the minibuffer, as when attempting to close the only window
+in a frame.  The value @code{delete-frame} closes the entire
+containing frame, as it does in most modern web browsers.  The value
+@code{tab-bar-mode-disable} will disable tab-bar-mode.  If the value
+is a function, it will be called with the tab to be closed as an
+argument.
+
+@item tab-bar-prevent-close-functions
+@vindex tab-bar-prevent-close-functions
+A list of functions to be called to determine whether or not to close
+the tab.  Each function is called with the tab to be closed and a
+boolean argument indicating whether or not it is the last tab.  If any
+of the functions return non-@code{nil}, the tab is not closed and no
+cleanup is performed, including any actions determined by
+@code{tab-bar-close-last-tab-choice}.
+
+@item tab-bar-pre-close-functions
+@vindex tab-bar-pre-close-functions
+A list of functions to be called to perform any cleanup tasks just
+before the tab is closed.  Each function is called with the tab to be
+closed and a boolean argument indicating whether or not it is the last
+tab.
+
 @end table
 
 @node Dialog Boxes
-- 
2.23.0

Re: [PATCH] Document tab opening/closing hooks and variables

[Eli Zaretskii]

> From: Robert Cochran <robert-emacs@cochranmail.com>
> Date: Tue, 10 Dec 2019 13:33:27 -0800
> 
> As promised, I've written information on tab-bar-post-open-functions,
> tab-bar-close-last-tab-choice, tab-bar-prevent-close-functions, and
> tab-bar-post-close-functions in the manual.
> 
> Suggestions and comments welcome, as usual.

Thanks.

I wonder whether such facilities need to be described in the manual.
They sound pretty minor features, so perhaps we should let users
discover them via Custom, doc strings, and NEWS?

Re: [PATCH] Document tab opening/closing hooks and variables

[Robert Cochran]

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

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Robert Cochran <robert-emacs@cochranmail.com>
>> Date: Tue, 10 Dec 2019 13:33:27 -0800
>> 
>> As promised, I've written information on tab-bar-post-open-functions,
>> tab-bar-close-last-tab-choice, tab-bar-prevent-close-functions, and
>> tab-bar-post-close-functions in the manual.
>> 
>> Suggestions and comments welcome, as usual.
>
> Thanks.
>
> I wonder whether such facilities need to be described in the manual.
> They sound pretty minor features, so perhaps we should let users
> discover them via Custom, doc strings, and NEWS?

I put them in the manual because I said that I would. I can't speak for
everyone, but sometimes stuff like that is nice to have in the manual. I
don't often discover variables via custom, but that might be because I
generally have a specific thing I have in mind I want to change when I
use it.

Such a thing definitely should be mentioned in the docstrings for the
functions, which I entirely forgot to write in both this patch and the
last patch. Oops. Here's a rough patch for that.

I think if anything else, that putting a couple of mentions in the
docstrings of some of the entry point functions is a reasonable
compromise.

Thanks,
-- 
~Robert Cochran


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Document tab-affecting variables in docstrings --]
[-- Type: text/x-patch, Size: 1961 bytes --]

From c6c4ae57b985bf9bd604613a173819fe725df761 Mon Sep 17 00:00:00 2001
From: Robert Cochran <robert-git@cochranmail.com>
Date: Wed, 11 Dec 2019 10:04:06 -0800
Subject: [PATCH] Document variables that affect tabs in function docstrings

* lisp/tab-bar.el (tab-bar-new-tab-to): Mention
tab-bar-post-open-functions in docstring.
(tab-bar-close-tab): Mention tab-bar-prevent-tab-functions,
tab-bar-tab-pre-close-functions, and tab-bar-close-last-tab-choice.
---
 lisp/tab-bar.el | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el
index ba4bc0afcd..7e8f56de2a 100644
--- a/lisp/tab-bar.el
+++ b/lisp/tab-bar.el
@@ -704,7 +704,10 @@ tab-bar-tab-post-open-functions
 (defun tab-bar-new-tab-to (&optional to-index)
   "Add a new tab at the absolute position TO-INDEX.
 TO-INDEX counts from 1.  If no TO-INDEX is specified, then add
-a new tab at the position specified by `tab-bar-new-tab-to'."
+a new tab at the position specified by `tab-bar-new-tab-to'.
+
+After the tab is created, the hooks in
+`tab-bar-tab-post-open-functions' are run."
   (interactive "P")
   (let* ((tabs (funcall tab-bar-tabs-function))
          (from-index (tab-bar--current-tab-index tabs))
@@ -819,7 +822,14 @@ tab-bar-close-tab
 Optional TO-INDEX could be specified to override the value of
 `tab-bar-close-tab-select' programmatically with a position
 of an existing tab to select after closing the current tab.
-TO-INDEX counts from 1."
+TO-INDEX counts from 1.
+
+The functions in `tab-bar-tab-prevent-close-functions' will be
+run to determine whether or not to close the tab.
+Just before the tab is closed, the functions in
+`tab-bar-tab-pre-close-functions' will be run.  The base behavior
+for the last tab on a frame is determined by
+`tab-bar-close-last-tab-choice'."
   (interactive "P")
   (let* ((tabs (funcall tab-bar-tabs-function))
          (current-index (tab-bar--current-tab-index tabs))
-- 
2.23.0

Re: [PATCH] Document tab opening/closing hooks and variables

[Juri Linkov]

> Such a thing definitely should be mentioned in the docstrings for the
> functions, which I entirely forgot to write in both this patch and the
> last patch. Oops. Here's a rough patch for that.
>
> I think if anything else, that putting a couple of mentions in the
> docstrings of some of the entry point functions is a reasonable
> compromise.

Thanks, your patches now pushed to master (tab-bar-close-other-tabs as well).