* [PATCH] Document tab opening/closing hooks and variables
@ 2019-12-10 21:33 Robert Cochran
2019-12-11 17:25 ` Eli Zaretskii
0 siblings, 1 reply; 4+ messages in thread
From: Robert Cochran @ 2019-12-10 21:33 UTC (permalink / raw)
To: emacs-devel
[-- 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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Document tab opening/closing hooks and variables
2019-12-10 21:33 [PATCH] Document tab opening/closing hooks and variables Robert Cochran
@ 2019-12-11 17:25 ` Eli Zaretskii
2019-12-11 18:15 ` Robert Cochran
0 siblings, 1 reply; 4+ messages in thread
From: Eli Zaretskii @ 2019-12-11 17:25 UTC (permalink / raw)
To: Robert Cochran; +Cc: emacs-devel
> 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?
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] Document tab opening/closing hooks and variables
2019-12-11 17:25 ` Eli Zaretskii
@ 2019-12-11 18:15 ` Robert Cochran
2019-12-15 23:01 ` Juri Linkov
0 siblings, 1 reply; 4+ messages in thread
From: Robert Cochran @ 2019-12-11 18:15 UTC (permalink / raw)
To: Eli Zaretskii; +Cc: Robert Cochran, emacs-devel
[-- 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
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] Document tab opening/closing hooks and variables
2019-12-11 18:15 ` Robert Cochran
@ 2019-12-15 23:01 ` Juri Linkov
0 siblings, 0 replies; 4+ messages in thread
From: Juri Linkov @ 2019-12-15 23:01 UTC (permalink / raw)
To: Robert Cochran; +Cc: Eli Zaretskii, emacs-devel
> 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).
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-12-15 23:01 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2019-12-10 21:33 [PATCH] Document tab opening/closing hooks and variables Robert Cochran
2019-12-11 17:25 ` Eli Zaretskii
2019-12-11 18:15 ` Robert Cochran
2019-12-15 23:01 ` Juri Linkov
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.