From: Eli Zaretskii Date: Sat, 3 Aug 2019 09:15:03 +0000 (+0300) Subject: Improve documentation of 'display-buffer-*' functions X-Git-Tag: emacs-27.0.90~1740 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=49a5b573b25b70b3efd288efab0e27af1191d8c7;p=emacs.git Improve documentation of 'display-buffer-*' functions * lisp/window.el (display-buffer-in-atom-window) (display-buffer-in-side-window, display-buffer-same-window) (display-buffer--maybe-same-window) (display-buffer-reuse-window) (display-buffer-reuse-mode-window) (display-buffer-pop-up-frame, display-buffer-pop-up-window) (display-buffer--maybe-pop-up-frame-or-window) (display-buffer--maybe-pop-up-frame) (display-buffer-in-child-frame, display-buffer-in-direction) (display-buffer-below-selected, display-buffer-at-bottom) (display-buffer-in-previous-window) (display-buffer-use-some-window, display-buffer-no-window): More details about the ALIST argument in the doc string. (Bug#19461) --- diff --git a/lisp/window.el b/lisp/window.el index 8b12c4381f4..70e2bba7499 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -666,8 +666,9 @@ 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 symbols and values. The -following symbols can be used. +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 symbols can be used: `window' specifies the existing window the new window shall be combined with. Use `window-atom-root' to make the new window a @@ -1000,8 +1001,10 @@ and may be called only if no window on SIDE exists yet." (defun display-buffer-in-side-window (buffer alist) "Display BUFFER in a side window of the selected frame. -ALIST is an association list of symbols and values. The -following special symbols can be used 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. +The following special symbols can be used in ALIST: `side' denotes the side of the frame where the new window shall be located. Valid values are `bottom', `right', `top' and @@ -7285,6 +7288,10 @@ The default predicate is to use any frame other than the selected frame. If successful, return the window used; otherwise return nil. +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 has a non-nil `inhibit-switch-frame' entry, avoid raising the frame. @@ -7314,10 +7321,15 @@ that allows the selected frame)." (defun display-buffer-same-window (buffer alist) "Display BUFFER in the selected window. -This fails if ALIST has an `inhibit-same-window' element whose -value is non-nil, or if the selected window is a minibuffer -window or is dedicated to another buffer; in that case, return nil. -Otherwise, return the selected window." + +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists. + +This function fails if ALIST has an `inhibit-same-window' +element whose value is non-nil, or if the selected window is a +minibuffer window or is dedicated to another buffer; in that case, +return nil. Otherwise, return the selected window." (unless (or (cdr (assq 'inhibit-same-window alist)) (window-minibuffer-p) (window-dedicated-p)) @@ -7325,6 +7337,11 @@ Otherwise, return the selected window." (defun display-buffer--maybe-same-window (buffer alist) "Conditionally display BUFFER in the selected window. + +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists. + If `same-window-p' returns non-nil for BUFFER's name, call `display-buffer-same-window' and return its value. Otherwise, return nil." @@ -7336,6 +7353,10 @@ return nil." Preferably use a window on the selected frame if such a window exists. Return nil if no usable window is found. +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 has a non-nil 'inhibit-same-window' entry, the selected window is not eligible for reuse. @@ -7391,6 +7412,10 @@ that frame." Display BUFFER in the returned window. Return nil if no usable window is found. +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 `mode' entry, its value is a major mode (a symbol) or a list of modes. A window is a candidate if it displays a buffer that derives from one of the given modes. When @@ -7470,6 +7495,10 @@ See `display-buffer' for the format of display actions." This works by calling `pop-up-frame-function'. If successful, return the window used; otherwise return nil. +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 has a non-nil `inhibit-switch-frame' entry, avoid raising the new frame. @@ -7496,6 +7525,10 @@ The new window is created on the selected frame, or in `last-nonminibuffer-frame' if no windows can be created there. If successful, return the new window; otherwise return nil. +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 has a non-nil `inhibit-switch-frame' entry, then in the event that the new window is created on another frame, avoid raising the frame." @@ -7524,6 +7557,10 @@ raising the frame." If `pop-up-frames' is non-nil (and not `graphic-only' on a text-only terminal), try with `display-buffer-pop-up-frame'. +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists. + If that cannot be done, and `pop-up-windows' is non-nil, try again with `display-buffer-pop-up-window'." (or (display-buffer--maybe-pop-up-frame buffer alist) @@ -7532,7 +7569,11 @@ again with `display-buffer-pop-up-window'." (defun display-buffer--maybe-pop-up-frame (buffer alist) "Try displaying BUFFER based on `pop-up-frames'. If `pop-up-frames' is non-nil (and not `graphic-only' on a -text-only terminal), try with `display-buffer-pop-up-frame'." +text-only terminal), try with `display-buffer-pop-up-frame'. + +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists." (and (if (eq pop-up-frames 'graphic-only) (display-graphic-p) pop-up-frames) @@ -7550,6 +7591,10 @@ By default, this either reuses a child frame of the selected frame or makes a new child frame of the selected frame. If successful, return the window used; otherwise return nil. +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 has a non-nil 'child-frame-parameters' entry, the corresponding value is an alist of frame parameters to give the new frame. A 'parent-frame' parameter specifying the selected @@ -7653,6 +7698,11 @@ ALIST is a buffer display alist." (defun display-buffer-in-direction (buffer alist) "Try to display BUFFER in a direction specified by ALIST. + +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists. + ALIST has to contain a 'direction' entry whose value should be one of 'left', 'above' (or 'up'), 'right', and 'below' (or 'down'). Other values are usually interpreted as 'below'. @@ -7741,6 +7791,10 @@ create a new window below the selected one and show BUFFER there. If that attempt fails as well and there is a non-dedicated window below the selected one, use that window. +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 'window-min-height' entry, this function ensures that the window used is or can become at least as high as specified by that entry's value. Note that such an entry alone @@ -7795,7 +7849,11 @@ must also contain a 'window-height' entry with the same value." This either reuses such a window provided it shows BUFFER already, splits a window at the bottom of the frame or the frame's root window, or reuses some window at the bottom of the -selected frame." +selected frame. + +ALIST is an association list of action symbols and values. +See Info node `(elisp) Buffer Display Action Alists' for +details of such alists." (let (bottom-window bottom-window-shows-buffer window) (walk-window-tree (lambda (window) @@ -7819,6 +7877,11 @@ selected frame." (defun display-buffer-in-previous-window (buffer alist) "Display BUFFER in a window previously showing it. + +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 has a non-nil `inhibit-same-window' entry, the selected window is not usable. A dedicated window is usable only if it already shows BUFFER. If ALIST contains a `previous-window' @@ -7890,6 +7953,10 @@ apply the following order of preference: Search for a usable window, set that window to the buffer, and return the window. If no suitable window is found, return nil. +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 has a non-nil `inhibit-switch-frame' entry, then in the event that a window in another frame is chosen, avoid raising that frame." @@ -7930,6 +7997,11 @@ that frame." (defun display-buffer-no-window (_buffer alist) "Display BUFFER in no window. + +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 has a non-nil `allow-no-window' entry, then don't display a window at all. This makes possible to override the default action and avoid displaying the buffer. It is assumed that when the caller