Function: display-buffer-in-tab

display-buffer-in-tab is a byte-compiled function defined in tab-bar.el.gz.

Signature

(display-buffer-in-tab BUFFER ALIST)

Documentation

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.

If ALIST contains a non-nil reusable-frames entry then the frames indicated by its value are searched for an existing tab which already displays BUFFER. The possible values of reusable-frames are:

  t -- all existing frames;
  visible -- all visible frames;
  0 -- all frames on the current terminal;
  A frame -- that frame only;
  Any other non-nil value -- the selected frame;
  nil -- do not search any frames (equivalent to omitting the entry).

(Note that the meaning of nil is different to the typical meaning of
nil for a reusable-frames entry in a buffer display action alist.)

If ALIST contains a non-nil ignore-current-tab entry then skip the current tab when searching for a reusable tab, otherwise prefer the current tab if it already displays BUFFER.

If a window displaying BUFFER is located in any reusable tab, select that tab and window.

If no such window is located, display BUFFER in a new or existing tab based on the ALIST entry tab-name (string or function). If a tab with this name already exists then select that tab, otherwise create a new tab with this name. If tab-name is a function it is called with two arguments (BUFFER and ALIST) and should return the tab name. If tab-name is omitted or nil, create a new tab without an explicit name.

If a new tab is created and ALIST contains a non-nil tab-group entry
(string or function), this defines the tab group, overriding user
option tab-bar-new-tab-group.

To create a new tab unconditionally, use display-buffer-in-new-tab instead.

This is an action function for buffer display, see Info node (elisp) Buffer Display Action Functions. It should be called only by display-buffer or a function directly or indirectly called by the latter.

View in manual

Source Code

;; Defined in /usr/src/emacs/lisp/tab-bar.el.gz
(defun display-buffer-in-tab (buffer alist)
  "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.

If ALIST contains a non-nil `reusable-frames' entry then the frames
indicated by its value are searched for an existing tab which already
displays BUFFER.  The possible values of `reusable-frames' are:

  t -- all existing frames;
  `visible' -- all visible frames;
  0 -- all frames on the current terminal;
  A frame -- that frame only;
  Any other non-nil value -- the selected frame;
  nil -- do not search any frames (equivalent to omitting the entry).

\(Note that the meaning of nil is different to the typical meaning of
nil for a `reusable-frames' entry in a buffer display action alist.)

If ALIST contains a non-nil `ignore-current-tab' entry then skip the
current tab when searching for a reusable tab, otherwise prefer the
current tab if it already displays BUFFER.

If a window displaying BUFFER is located in any reusable tab, select
that tab and window.

If no such window is located, display BUFFER in a new or existing tab
based on the ALIST entry `tab-name' (string or function).  If a tab with
this name already exists then select that tab, otherwise create a new
tab with this name.  If `tab-name' is a function it is called with two
arguments (BUFFER and ALIST) and should return the tab name.  If
`tab-name' is omitted or nil, create a new tab without an explicit name.

If a new tab is created and ALIST contains a non-nil `tab-group' entry
\(string or function), this defines the tab group, overriding user
option `tab-bar-new-tab-group'.

To create a new tab unconditionally, use `display-buffer-in-new-tab'
instead.

This is an action function for buffer display, see Info
node `(elisp) Buffer Display Action Functions'.  It should be
called only by `display-buffer' or a function directly or
indirectly called by the latter."
  (let* ((reusable-frames (alist-get 'reusable-frames alist))
         (ignore-current-tab (alist-get 'ignore-current-tab alist))
         (reusable-tab (when reusable-frames
                         (tab-bar-get-buffer-tab buffer reusable-frames
                                                 ignore-current-tab))))
    (if reusable-tab
        (let* ((frame (alist-get 'frame reusable-tab))
               (index (alist-get 'index reusable-tab)))
          (when frame
            (select-frame-set-input-focus frame))
          (when index
            (tab-bar-select-tab (1+ index)))
          (when (get-buffer-window buffer frame)
            (select-window (get-buffer-window buffer frame))))
      (let ((tab-name (alist-get 'tab-name alist)))
        (when (functionp tab-name)
          (setq tab-name (funcall tab-name buffer alist)))
        (if tab-name
            (let ((tab-index (tab-bar--tab-index-by-name tab-name)))
              (if tab-index
                  (progn
                    (tab-bar-select-tab (1+ tab-index))
                    (when (get-buffer-window buffer)
                      (select-window (get-buffer-window buffer))))
                (display-buffer-in-new-tab buffer alist)))
          (display-buffer-in-new-tab buffer alist))))))