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 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, 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.

If ALIST contains a reusable-frames entry, its value determines which frames to search for a reusable tab:
  nil -- do not reuse any frames;
  a frame -- just that frame;
  visible -- all visible frames;
  0 -- all frames on the current terminal;
  t -- all frames;
  other non-nil values -- use the selected frame.

If ALIST contains a non-nil ignore-current-tab entry, then the buffers of the current tab are skipped when searching for a reusable tab. Otherwise, prefer buffers of the current tab.

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.

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 `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, 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.

If ALIST contains a `reusable-frames' entry, its value determines
which frames to search for a reusable tab:
  nil -- do not reuse any frames;
  a frame  -- just that frame;
  `visible' -- all visible frames;
  0 -- all frames on the current terminal;
  t -- all frames;
  other non-nil values -- use the selected frame.

If ALIST contains a non-nil `ignore-current-tab' entry, then the buffers
of the current tab are skipped when searching for a reusable tab.
Otherwise, prefer buffers of the current tab.

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))))))