mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-17 03:10:58 -08:00
Code Issues Projects Releases Wiki Activity

More documentation fixes in tab-bar.el

Browse source 
* lisp/tab-bar.el (tab-bar-detach-tab, tab-bar-move-window-to-tab)
(tab-bar-new-tab-to, tab-bar-new-tab, tab-bar-close-tab-select)
(tab-bar-close-last-tab-choice, tab-bar-tab-pre-close-functions)
(tab-bar-close-tab, tab-bar-close-tab-by-name)
(tab-bar-close-other-tabs, tab-bar-rename-tab)
(tab-bar-rename-tab-by-name, tab-bar-move-tab-to-group)
(tab-bar-change-tab-group, tab-bar-close-group-tabs)
(tab-switcher-next-line, tab-switcher-prev-line)
(tab-switcher-unmark, tab-switcher-delete, tab-switcher-select)
(tab-bar-get-buffer-tab, display-buffer-in-tab)
(display-buffer-in-new-tab, switch-to-buffer-other-tab)
(find-file-other-tab, find-file-read-only-other-tab): Doc fixes.
This commit is contained in:
Eli Zaretskii 2021-10-17 11:42:23 +03:00
parent 35920791df
commit 686a03ee22
1 changed files with 65 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

106
lisp/tab-bar.el
View file

@ -1227,7 +1227,7 @@ to which to move the tab; ARG defaults to 1."
(defun tab-bar-detach-tab (&optional from-number)
"Move tab number FROM-NUMBER to a new frame.
Interactively or without argument, move the current tab."
FROM-NUMBER defaults to the current tab (which happens interactively."
(interactive (list (1+ (tab-bar--current-tab-index))))
(let* ((tabs (funcall tab-bar-tabs-function))
(tab-index (1- (or from-number (1+ (tab-bar--current-tab-index tabs)))))
@ -1241,7 +1241,10 @@ Interactively or without argument, move the current tab."
(tab-bar-close-tab))))
(defun tab-bar-move-window-to-tab ()
"Detach the selected window to a new tab."
"Move the selected window to a new tab.
This command removes the selected window from the configuration stored
on the current tab, and makes a new tab with that window in its
configuration."
(interactive)
(let ((tab-bar-new-tab-choice 'window))
(tab-bar-new-tab))
@ -1251,17 +1254,17 @@ Interactively or without argument, move the current tab."
(defcustom tab-bar-new-tab-to 'right
"Defines where to create a new tab.
"Where to create a new tab.
If `leftmost', create as the first tab.
If `left', create to the left from the current tab.
If `right', create to the right from the current tab.
If `left', create to the left of the current tab.
If `right', create to the right of the current tab.
If `rightmost', create as the last tab.
If the value is a function, it should return a number as a position
on the tab bar specifying where to insert a new tab."
:type '(choice (const :tag "First tab" leftmost)
(const :tag "To the left" left)
(const :tag "To the right" right)
(const :tag "Last tab" rightmost)
:type '(choice (const :tag "Insert first" leftmost)
(const :tag "Insert left" left)
(const :tag "Insert right" right)
(const :tag "Insert last" rightmost)
(function :tag "Function"))
:group 'tab-bar
:version "27.1")
@ -1280,7 +1283,7 @@ TAB-NUMBER counts from 1. If no TAB-NUMBER is specified, then add
a new tab at the position specified by `tab-bar-new-tab-to'.
Negative TAB-NUMBER counts tabs from the end of the tab bar,
and -1 means the new tab will become the last one.
Argument addressing is absolute in contrast to `tab-bar-new-tab'
Argument addressing is absolute in contrast to `tab-bar-new-tab',
where argument addressing is relative.
After the tab is created, the hooks in
`tab-bar-tab-post-open-functions' are run."
@ -1353,7 +1356,7 @@ If a negative ARG, create a new tab ARG positions to the left.
If ARG is zero, create a new tab in place of the current tab.
If no ARG is specified, then add a new tab at the position
specified by `tab-bar-new-tab-to'.
Argument addressing is relative in contrast to `tab-bar-new-tab-to'
Argument addressing is relative in contrast to `tab-bar-new-tab-to',
where argument addressing is absolute.
If FROM-NUMBER is a tab number, a new tab is created from that tab."
(interactive "P")
@ -1380,7 +1383,7 @@ ARG and FROM-NUMBER have the same meaning as in `tab-bar-new-tab'."
"A list of closed tabs to be able to undo their closing.")
(defcustom tab-bar-close-tab-select 'recent
"Defines what tab to select after closing the specified tab.
"Which tab to make current after closing the specified tab.
If `left', select the adjacent left tab.
If `right', select the adjacent right tab.
If `recent', select the most recently visited tab."
@ -1391,7 +1394,7 @@ If `recent', select the most recently visited tab."
:version "27.1")
(defcustom tab-bar-close-last-tab-choice nil
"Defines what to do when the last tab is closed.
"What to do when the last tab is closed.
If nil, do nothing and show a message, like closing the last window or frame.
If `delete-frame', delete the containing frame, as a web browser would do.
If `tab-bar-mode-disable', disable `tab-bar-mode' so that tabs no longer show
@ -1416,9 +1419,8 @@ function returns a non-nil value, the tab will not be closed."
(defcustom tab-bar-tab-pre-close-functions nil
"List of functions to call before closing a tab.
The tab to be closed and a boolean indicating whether or not it
is the only tab in the frame are supplied as arguments,
respectively."
Each function is called with two arguments: the tab to be closed
and a boolean indicating whether or not it is the only tab on its frame."
:type '(repeat function)
:group 'tab-bar
:version "27.1")
@ -1427,6 +1429,7 @@ respectively."
"Close the tab specified by its absolute position TAB-NUMBER.
If no TAB-NUMBER is specified, then close the current tab and switch
to the tab specified by `tab-bar-close-tab-select'.
Interactively, TAB-NUMBER is the prefix numeric argument, and defaults to 1.
TAB-NUMBER counts from 1.
Optional TO-NUMBER could be specified to override the value of
`tab-bar-close-tab-select' programmatically with a position
@ -1500,7 +1503,8 @@ for the last tab on a frame is determined by
(message "Deleted tab and switched to %s" tab-bar-close-tab-select))))))
(defun tab-bar-close-tab-by-name (name)
"Close the tab by NAME."
"Close the tab given its NAME.
Interactively, prompt for NAME."
(interactive
(list (completing-read "Close tab by name: "
(mapcar (lambda (tab)
@ -1509,8 +1513,9 @@ for the last tab on a frame is determined by
(tab-bar-close-tab (1+ (tab-bar--tab-index-by-name name))))
(defun tab-bar-close-other-tabs (&optional tab-number)
"Close all tabs on the selected frame, except TAB-NUMBER.
TAB-NUMBER counts from 1 and defaults to the current tab."
"Close all tabs on the selected frame, except the tab TAB-NUMBER.
TAB-NUMBER counts from 1 and defaults to the current tab (which
happens interactively)."
(interactive)
(let* ((tabs (funcall tab-bar-tabs-function))
(current-index (tab-bar--current-tab-index tabs))
@ -1576,9 +1581,12 @@ TAB-NUMBER counts from 1 and defaults to the current tab."
(defun tab-bar-rename-tab (name &optional tab-number)
"Rename the tab specified by its absolute position TAB-NUMBER.
"Give the tab specified by its absolute position TAB-NUMBER a new NAME.
If no TAB-NUMBER is specified, then rename the current tab.
Interactively, TAB-NUMBER is the prefix numeric argument, and defaults
to the current tab.
TAB-NUMBER counts from 1.
Interactively, prompt for the new NAME.
If NAME is the empty string, then use the automatic name
function `tab-bar-tab-name-function'."
(interactive
@ -1606,7 +1614,8 @@ function `tab-bar-tab-name-function'."
(message "Renamed tab to '%s'" tab-new-name))))
(defun tab-bar-rename-tab-by-name (tab-name new-name)
"Rename the tab named TAB-NAME.
"Rename the tab named TAB-NAME to NEW-NAME.
Interactively, prompt for TAB-NAME and NEW-NAME.
If NEW-NAME is the empty string, then use the automatic name
function `tab-bar-tab-name-function'."
(interactive
@ -1623,7 +1632,7 @@ function `tab-bar-tab-name-function'."
;;; Tab groups
(defun tab-bar-move-tab-to-group (&optional tab)
"Relocate TAB (or the current tab) closer to its group."
"Relocate TAB (default: the current tab) closer to its group."
(interactive)
(let* ((tabs (funcall tab-bar-tabs-function))
(tab (or tab (tab-bar--current-tab-find tabs)))
@ -1661,6 +1670,8 @@ The current tab is supplied as an argument."
(defun tab-bar-change-tab-group (group-name &optional tab-number)
"Add the tab specified by its absolute position TAB-NUMBER to GROUP-NAME.
If no TAB-NUMBER is specified, then set the GROUP-NAME for the current tab.
Interactively, TAB-NUMBER is the prefix numeric argument, and the command
prompts for GROUP-NAME.
TAB-NUMBER counts from 1.
If GROUP-NAME is the empty string, then remove the tab from any group.
While using this command, you might also want to replace
@ -1698,7 +1709,8 @@ While using this command, you might also want to replace
(message "Set tab group to '%s'" group-new-name))))
(defun tab-bar-close-group-tabs (group-name)
"Close all tabs that belong to GROUP-NAME on the selected frame."
"Close all tabs that belong to GROUP-NAME on the selected frame.
Interactively, prompt for GROUP-NAME."
(interactive
(let ((group-name (funcall tab-bar-tab-group-function
(tab-bar--current-tab-find))))
@ -1745,7 +1757,7 @@ While using this command, you might also want to replace
(defun tab-bar--history-pre-change ()
(setq tab-bar-history-old-minibuffer-depth (minibuffer-depth))
;; Store wc before possibly entering the minibuffer
;; Store window-configuration before possibly entering the minibuffer.
(when (zerop tab-bar-history-old-minibuffer-depth)
(setq tab-bar-history-old
`((wc . ,(current-window-configuration))
@ -1754,7 +1766,8 @@ While using this command, you might also want to replace
(defun tab-bar--history-change ()
(when (and (not tab-bar-history-omit)
tab-bar-history-old
;; Store wc before possibly entering the minibuffer
;; Store window-configuration before possibly entering
;; the minibuffer.
(zerop tab-bar-history-old-minibuffer-depth))
(puthash (selected-frame)
(seq-take (cons tab-bar-history-old
@ -1946,12 +1959,16 @@ Letters do not insert themselves; instead, they are commands.
nil))))
(defun tab-switcher-next-line (&optional arg)
"Move to ARGth next line in the list of tabs.
Interactively, ARG is the prefix numeric argument and defaults to 1."
(interactive "p")
(forward-line arg)
(beginning-of-line)
(move-to-column tab-switcher-column))
(defun tab-switcher-prev-line (&optional arg)
"Move to ARGth previous line in the list of tabs.
Interactively, ARG is the prefix numeric argument and defaults to 1."
(interactive "p")
(forward-line (- arg))
(beginning-of-line)
@ -1959,7 +1976,7 @@ Letters do not insert themselves; instead, they are commands.
(defun tab-switcher-unmark (&optional backup)
"Cancel requested operations on window configuration on this line and move down.
Optional prefix arg means move up."
With prefix arg, move up instead."
(interactive "P")
(beginning-of-line)
(move-to-column tab-switcher-column)
@ -1979,7 +1996,7 @@ Optional prefix arg means move up."
(defun tab-switcher-delete (&optional arg)
"Mark window configuration on this line to be deleted by \\<tab-switcher-mode-map>\\[tab-switcher-execute] command.
Prefix arg is how many window configurations to delete.
Prefix arg says how many window configurations to delete.
Negative arg means delete backwards."
(interactive "p")
(let ((buffer-read-only nil))
@ -2032,8 +2049,8 @@ Then move up one line. Prefix arg means move that many lines."
(defun tab-switcher-select ()
"Select this line's window configuration.
This command deletes and replaces all the previously existing windows
in the selected frame."
This command replaces all the existing windows in the selected frame
with those specified by the selected window configuration."
(interactive)
(let* ((to-tab (tab-switcher-current-tab t)))
(kill-buffer (current-buffer))
@ -2059,8 +2076,8 @@ in the selected frame."
(t (list (selected-frame)))))
(defun tab-bar-get-buffer-tab (buffer-or-name &optional all-frames ignore-current-tab)
"Return a tab owning a window whose buffer is BUFFER-OR-NAME.
BUFFER-OR-NAME may be a buffer or a buffer name and defaults to
"Return the tab that owns the window whose buffer is BUFFER-OR-NAME.
BUFFER-OR-NAME may be a buffer or a buffer name, and defaults to
the current buffer.
The optional argument ALL-FRAMES specifies the frames to consider:
@ -2108,7 +2125,7 @@ Otherwise, prefer buffers of the current tab."
(tab-bar--reusable-frames all-frames)))))
(defun display-buffer-in-tab (buffer alist)
"Display BUFFER in a tab.
"Display BUFFER in a tab using display actions in ALIST.
ALIST is an association list of action symbols and values. See
Info node `(elisp) Buffer Display Action Alists' for details of
such alists.
@ -2116,8 +2133,8 @@ such alists.
If ALIST contains a `tab-name' entry, it creates a new tab with that name and
displays BUFFER in a new tab. If a tab with this name already exists, it
switches to that tab before displaying BUFFER. The `tab-name' entry can be
a function, then it is called with two arguments: BUFFER and ALIST, and
should return the tab name. When a `tab-name' entry is omitted, create
a function, in which case it is called with two arguments: BUFFER and ALIST,
and should return the tab name. When a `tab-name' entry is omitted, create
a new tab without an explicit name.
The ALIST entry `tab-group' (string or function) defines the tab group.
@ -2167,7 +2184,7 @@ indirectly called by the latter."
(display-buffer-in-new-tab buffer alist))))))
(defun display-buffer-in-new-tab (buffer alist)
"Display BUFFER in a new tab.
"Display BUFFER in a new tab using display actions in ALIST.
ALIST is an association list of action symbols and values. See
Info node `(elisp) Buffer Display Action Alists' for details of
such alists.
@ -2177,9 +2194,9 @@ without checking if a suitable tab already exists.
If ALIST contains a `tab-name' entry, it creates a new tab with that name
and displays BUFFER in a new tab. The `tab-name' entry can be a function,
then it is called with two arguments: BUFFER and ALIST, and should return
the tab name. When a `tab-name' entry is omitted, create a new tab without
an explicit name.
in which case it is called with two arguments: BUFFER and ALIST, and should
return the tab name. When a `tab-name' entry is omitted, create a new tab
without an explicit name.
The ALIST entry `tab-group' (string or function) defines the tab group.
@ -2203,7 +2220,8 @@ indirectly called by the latter."
(defun switch-to-buffer-other-tab (buffer-or-name &optional norecord)
"Switch to buffer BUFFER-OR-NAME in another tab.
Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab."
Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab.
Interactively, prompt for the buffer to switch to."
(interactive
(list (read-buffer-to-switch "Switch to buffer in other tab: ")))
(display-buffer (window-normalize-buffer-to-switch-to buffer-or-name)
@ -2213,7 +2231,10 @@ Like \\[switch-to-buffer-other-frame] (which see), but creates a new tab."
(defun find-file-other-tab (filename &optional wildcards)
"Edit file FILENAME, in another tab.
Like \\[find-file-other-frame] (which see), but creates a new tab."
Like \\[find-file-other-frame] (which see), but creates a new tab.
Interactively, prompt for FILENAME.
If WILDCARDS is non-nil, FILENAME can include widcards, and all matching
files will be visited."
(interactive
(find-file-read-args "Find file in other tab: "
(confirm-nonexistent-file-or-buffer)))
@ -2230,7 +2251,10 @@ Like \\[find-file-other-frame] (which see), but creates a new tab."
"Edit file FILENAME, in another tab, but don't allow changes.
Like \\[find-file-other-frame] (which see), but creates a new tab.
Like \\[find-file-other-tab], but marks buffer as read-only.
Use \\[read-only-mode] to permit editing."
Use \\[read-only-mode] to permit editing.
Interactively, prompt for FILENAME.
If WILDCARDS is non-nil, FILENAME can include widcards, and all matching
files will be visited."
(interactive
(find-file-read-args "Find file read-only in other tab: "
(confirm-nonexistent-file-or-buffer)))