Function: display-buffer-in-atom-window

display-buffer-in-atom-window is a byte-compiled function defined in window.el.gz.

Signature

(display-buffer-in-atom-window BUFFER ALIST)

Documentation

Display BUFFER in an atomic window.

This function displays BUFFER in a new window that will be combined with an existing window to form an atomic window. If the existing window is already part of an atomic window, add the new window to that atomic window. Operations like split-window or delete-window, when applied to a constituent of an atomic window, are applied atomically to the root of that atomic window.

ALIST is an association list of action symbols and values. See Info node (elisp) Buffer Display Action Alists for details of such alists. The following two symbols have a special meaning:

window specifies the existing window the new window shall be
  combined with. Use window-atom-root to make the new window a
  sibling of an atomic window's root. If an internal window is
  specified here, all children of that window become part of the
  atomic window too. If no window is specified, the new window
  becomes a sibling of the selected window. By default, the
  window-atom parameter of the existing window is set to main
  provided the window is live and the parameter is not set yet.

side denotes the side of the existing window where the new
  window shall be located. Valid values are below, right,
  above and left. The default is below. By default, the
  window-atom parameter of the new window is set to this value.

The return value is the new window, nil when creating that window failed.

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/window.el.gz
(defun display-buffer-in-atom-window (buffer alist)
  "Display BUFFER in an atomic window.
This function displays BUFFER in a new window that will be
combined with an existing window to form an atomic window.  If
the existing window is already part of an atomic window, add the
new window to that atomic window.  Operations like `split-window'
or `delete-window', when applied to a constituent of an atomic
window, are applied atomically to the root of that atomic window.

ALIST is an association list of action symbols and values.  See
Info node `(elisp) Buffer Display Action Alists' for details of
such alists.  The following two symbols have a special meaning:

`window' specifies the existing window the new window shall be
  combined with.  Use `window-atom-root' to make the new window a
  sibling of an atomic window's root.  If an internal window is
  specified here, all children of that window become part of the
  atomic window too.  If no window is specified, the new window
  becomes a sibling of the selected window.  By default, the
  `window-atom' parameter of the existing window is set to `main'
  provided the window is live and the parameter is not set yet.

`side' denotes the side of the existing window where the new
  window shall be located.  Valid values are `below', `right',
  `above' and `left'.  The default is `below'.  By default, the
  `window-atom' parameter of the new window is set to this value.

The return value is the new window, nil when creating that window
failed.

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* ((ignore-window-parameters t)
	 (window-combination-limit t)
	 (window-combination-resize 'atom)
	 (window (cdr (assq 'window alist)))
	 (side (or (cdr (assq 'side alist)) 'below))
	 (atom (when window (window-parameter window 'window-atom)))
	 root new)
    (setq window (window-normalize-window window))
    (setq root (window-atom-root window))
    ;; Split off new window.
    (when (setq new (split-window-no-error window nil side))
      (window-make-atom
       (if (and root (not (eq root window)))
	   ;; When WINDOW was part of an atomic window and we did not
	   ;; split its root, root atomic window at old root.
	   root
	 ;; Otherwise, root atomic window at WINDOW's new parent.
	 (window-parent window)))
      ;; Assign `window-atom' parameters, if needed.
      (when (and (not atom) (window-live-p window))
	(set-window-parameter window 'window-atom 'main))
      (set-window-parameter new 'window-atom side)
      ;; Display BUFFER in NEW and return NEW.
      (window--display-buffer buffer new 'window alist))))