\f
(defcustom tab-line-tab-name-function #'tab-line-tab-name-buffer
"Function to get a tab name.
-Function gets two arguments: tab to get name for and a list of tabs
-to display. By default, use function `tab-line-tab-name'."
+The function is called with one or two arguments: the buffer or
+another object whose tab's name is requested, and, optionally,
+the list of all tabs."
:type '(choice (const :tag "Buffer name"
tab-line-tab-name-buffer)
(const :tag "Truncated buffer name"
(defvar tab-line-tab-name-ellipsis t)
(defun tab-line-tab-name-truncated-buffer (buffer &optional _buffers)
- "Generate tab name from BUFFER.
+ "Generate tab name from BUFFER, truncating it as needed.
Truncate it to the length specified by `tab-line-tab-name-truncated-max'.
-Append ellipsis `tab-line-tab-name-ellipsis' in this case."
+If truncated, append ellipsis per `tab-line-tab-name-ellipsis'."
(let ((tab-name (buffer-name buffer)))
(if (< (length tab-name) tab-line-tab-name-truncated-max)
tab-name
(buffer-list)))))
(defun tab-line-tabs-mode-buffers ()
- "Return a list of buffers with the same major mode with current buffer."
+ "Return a list of buffers with the same major mode as the current buffer."
(let ((mode major-mode))
(seq-sort-by #'buffer-name #'string<
(seq-filter (lambda (b) (with-current-buffer b
(funcall tab-line-tabs-buffer-list-function)))))
(defvar tab-line-tabs-buffer-group-function nil
- "Function to put a buffer to the group.
-Takes a buffer as arg and should return a group name as string.
-When the return value is nil, filter out the buffer.")
+ "Function to add a buffer to the appropriate group of tabs.
+Takes a buffer as arg and should return a group name as a string.
+If the return value is nil, the buffer should be filtered out.")
(defvar tab-line-tabs-buffer-group-sort-function nil
- "Function to sort buffers in group.")
+ "Function to sort buffers in a group.")
(defvar tab-line-tabs-buffer-groups-sort-function #'string<
"Function to sort group names.")
(defvar tab-line-tabs-buffer-groups mouse-buffer-menu-mode-groups
"How to group various major modes together in the tab line.
Each element has the form (REGEXP . GROUPNAME).
-If the major mode's name string matches REGEXP, use GROUPNAME instead.")
+If the major mode's name matches REGEXP, it belongs to GROUPNAME.
+The default is for each major mode to have a separate group
+named the same as the mode.")
(defun tab-line-tabs-buffer-group-name (&optional buffer)
(if (functionp tab-line-tabs-buffer-group-function)
\f
(defcustom tab-line-tab-name-format-function #'tab-line-tab-name-format-default
"Function to format a tab name.
-Function gets two arguments: the tab and a list of all tabs, and
-should return the formatted tab name to display in the tab line."
+The function will be called two arguments: the tab whose name to format,
+and the list of all the tabs; it should return the formatted tab name
+to display in the tab line.
+The first argument could also be a different object, for example the buffer
+which the tab will represent."
:type 'function
:initialize 'custom-initialize-default
:set (lambda (sym val)
:version "28.1")
(defun tab-line-tab-name-format-default (tab tabs)
+ "Default function to use as `tab-line-tab-name-format-function', which see."
(let* ((buffer-p (bufferp tab))
(selected-p (if buffer-p
(eq tab (window-buffer))
mouse-face tab-line-highlight))))
(defun tab-line-format-template (tabs)
- "Template for displaying tab line for selected window."
+ "Template of the format for displaying tab line for selected window.
+This is used by `tab-line-format'."
(let* ((separator (or tab-line-separator (if window-system " " "|")))
(hscroll (window-parameter nil 'tab-line-hscroll))
(strings
(defun tab-line-tab-face-inactive-alternating (tab tabs face _buffer-p selected-p)
"Return FACE for TAB in TABS with alternation.
-When TAB is an inactive buffer and is even-numbered, make FACE
+SELECTED-P non-nil means TAB is not the selected tab.
+When TAB is not selected and is even-numbered, make FACE
inherit from `tab-line-tab-inactive-alternate'. For use in
`tab-line-tab-face-functions'."
(when (and (not selected-p) (cl-evenp (cl-position tab tabs)))
face)
(defun tab-line-tab-face-special (tab _tabs face buffer-p _selected-p)
- "Return FACE for TAB according to whether it's special.
-When TAB is a non-file-backed buffer, make FACE inherit from
+ "Return FACE for TAB according to whether its buffer is special.
+When TAB is a non-file-visiting buffer, make FACE inherit from
`tab-line-tab-special'. For use in
`tab-line-tab-face-functions'."
(when (and buffer-p (not (buffer-file-name tab)))
face)
(defun tab-line-tab-face-modified (tab _tabs face buffer-p _selected-p)
- "Return FACE for TAB according to whether it's modified.
+ "Return FACE for TAB according to whether its buffer is modified.
When TAB is a modified, file-backed buffer, make FACE inherit
from `tab-line-tab-modified'. For use in
`tab-line-tab-face-functions'."
(defvar tab-line-auto-hscroll)
(defun tab-line-format ()
- "Template for displaying tab line for selected window."
+ "Format for displaying the tab line of the selected window."
(let* ((tabs (funcall tab-line-tabs-function))
(cache-key (list tabs
;; handle buffer renames
\f
(defcustom tab-line-auto-hscroll t
"Allow or disallow automatic horizontal scrolling of the tab line.
-Non-nil means the tab line are automatically scrolled horizontally to make
+Non-nil means the tab lines are automatically scrolled horizontally to make
the selected tab visible."
:type 'boolean
:group 'tab-line
(force-mode-line-update t))))
(defun tab-line-hscroll-right (&optional arg event)
+ "Scroll the tab line ARG positions to the right.
+Interactively, ARG is the prefix numeric argument and defaults to 1."
(interactive (list current-prefix-arg last-nonmenu-event))
(let ((window (and (listp event) (posn-window (event-start event)))))
(tab-line-hscroll arg window)
(force-mode-line-update window)))
(defun tab-line-hscroll-left (&optional arg event)
+ "Scroll the tab line ARG positions to the left.
+Interactively, ARG is the prefix numeric argument and defaults to 1."
(interactive (list current-prefix-arg last-nonmenu-event))
(let ((window (and (listp event) (posn-window (event-start event)))))
(tab-line-hscroll (- (or arg 1)) window)
\f
(defun tab-line-new-tab (&optional event)
- "Add a new tab to the tab line.
-Usually is invoked by clicking on the plus-shaped button.
-But any switching to other buffer also adds a new tab
-corresponding to the switched buffer."
+ "Add a new tab to the selected-window's tab line.
+This command is usually invoked by clicking on the plus-shaped button
+on the tab line. Switching to another buffer also adds a new tab
+corresponding to the new buffer shown in the window."
(interactive (list last-nonmenu-event))
(if (functionp tab-line-new-tab-choice)
(funcall tab-line-new-tab-choice)
(tmm-prompt (mouse-buffer-menu-keymap))))))
(defun tab-line-select-tab (&optional event)
- "Switch to the selected tab.
+ "Switch to the buffer specified by the tab on which you click.
This command maintains the original order of prev/next buffers.
-So for example, switching to a previous tab is equivalent to
+So, for example, switching to a previous tab is equivalent to
using the `previous-buffer' command."
(interactive "e")
(let* ((posnp (event-start event))
:version "28.1")
(defun tab-line-switch-to-prev-tab (&optional event)
- "Switch to the previous tab.
+ "Switch to the previous tab's buffer.
Its effect is the same as using the `previous-buffer' command
(\\[previous-buffer])."
(interactive (list last-nonmenu-event))
(switch-to-buffer buffer)))))))
(defun tab-line-switch-to-next-tab (&optional event)
- "Switch to the next tab.
+ "Switch to the next tab's buffer.
Its effect is the same as using the `next-buffer' command
(\\[next-buffer])."
(interactive (list last-nonmenu-event))
\f
(defcustom tab-line-close-tab-function 'bury-buffer
- "Defines what to do on closing the tab.
+ "What to do upon closing a tab on the tab line.
If `bury-buffer', put the tab's buffer at the end of the list of all
-buffers that effectively hides the buffer's tab from the tab line.
+buffers, which effectively hides the buffer's tab from the tab line.
If `kill-buffer', kills the tab's buffer.
When a function, it is called with the tab as its argument.
This option is useful when `tab-line-tabs-function' has the value
(defun tab-line-close-tab (&optional event)
"Close the selected tab.
-Usually is invoked by clicking on the close button on the right side
-of the tab. This command buries the buffer, so it goes out of sight
-from the tab line."
+This command is usually invoked by clicking on the close button on the
+right side of the tab. This command buries the buffer, so it goes out of
+sight of the tab line."
(interactive (list last-nonmenu-event))
(let* ((posnp (and (listp event) (event-start event)))
(window (and posnp (posn-window posnp)))
(force-mode-line-update))))
(defun tab-line-tab-context-menu (&optional event)
- "Pop up context menu for the tab."
+ "Pop up the context menu for a tab-line tab."
(interactive "e")
(let ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t))))
(define-key-after menu [close]
(popup-menu menu event)))
(defun tab-line-context-menu (&optional event)
- "Pop up context menu for the tab line."
+ "Pop up the context menu for the tab line."
(interactive "e")
(let ((menu (make-sparse-keymap (propertize "Context Menu" 'hide t))))
(define-key-after menu [close]
\f
;;;###autoload
(define-minor-mode tab-line-mode
- "Toggle display of window tab line in the buffer."
+ "Toggle display of tab line in the windows displaying the current buffer."
:lighter nil
(setq tab-line-format (when tab-line-mode '(:eval (tab-line-format)))))
(defcustom tab-line-exclude-modes
'(completion-list-mode)
- "List of major modes in which the tab line is not enabled."
+ "List of major modes for which the tab-line display is not enabled.
+Buffers under any of these major modes will not show the tab line in
+their windows, even if `global-tab-line-mode' is enabled."
:type '(repeat symbol)
:group 'tab-line
:version "27.1")
(defvar-local tab-line-exclude nil)
(defun tab-line-mode--turn-on ()
- "Turn on `tab-line-mode'."
+ "Turn on `tab-line-mode' in all pertinent buffers.
+Temporary buffers, buffers whose names begin with a space, buffers
+under major modes that are either mentioned in `tab-line-exclude-mode'
+or have a non-nil `tab-line-exclude' property on their symbol,
+and buffers that have a non-nil buffer-local value
+of `tab-line-exclude', are exempt from `tab-line-mode'."
(unless (or (minibufferp)
(string-match-p "\\` " (buffer-name))
(memq major-mode tab-line-exclude-modes)
projects / emacs.git / commitdiff