procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rewrite buffer display related doc-strings and doc

Browse source 
* lisp/window.el (display-buffer-overriding-action)
(display-buffer-alist, display-buffer-base-action)
(display-buffer-fallback-action, display-buffer-assq-regexp)
(display-buffer): Rewrite doc-strings using suggestions by
Alan Mackenzie <acm@muc.de>.
(display-buffer-use-some-frame): Adjust doc-string and
reformat code.
* doc/lispref/windows.texi (Buffer Display Action Alists):
Make docs on 'window-height', 'window-width' and
'preserve-size' entries more accurate.
This commit is contained in:
Martin Rudalics 2018-11-08 20:20:13 +01:00
parent aa556596fa
commit fa605f242e
2 changed files with 187 additions and 141 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
doc/lispref/windows.texi
View file

@ -2747,8 +2747,8 @@ the buffer. This entry is used by
@vindex reusable-frames@r{, a buffer display action alist entry} @vindex reusable-frames@r{, a buffer display action alist entry}
@item reusable-frames @item reusable-frames
The value specifies the frame(s) to search for a window that can be The value specifies the set of frames to search for a window that can
reused because it already displays the buffer. It can be set as be reused because it already displays the buffer. It can be set as
follows: follows:
@itemize @bullet @itemize @bullet
@ -2792,17 +2792,20 @@ entry.
@vindex window-height@r{, a buffer display action alist entry} @vindex window-height@r{, a buffer display action alist entry}
@item window-height @item window-height
The value specifies whether and how to adjust the height of the chosen The value specifies whether and how to adjust the height of the chosen
window, and can have the following values: window and can be one of the following:
@itemize @bullet @itemize @bullet
@item @item
@code{nil} means to leave the height of the chosen window alone. @code{nil} means to leave the height of the chosen window alone.
@item @item
A number specifies the desired height of the chosen window. An An integer number specifies the desired total height of the chosen
integer specifies the number of lines of the window. A floating-point window in lines.
number gives the fraction of the window's height with respect to the
height of the frame's root window. @item
A floating-point number specifies the fraction of the chosen window's
desired total height with respect to the total height of its frame's
root window.
@item @item
If the value specifies a function, that function is called with one If the value specifies a function, that function is called with one
@ -2812,7 +2815,11 @@ are @code{shrink-window-if-larger-than-buffer} and
@code{fit-window-to-buffer}, see @ref{Resizing Windows}. @code{fit-window-to-buffer}, see @ref{Resizing Windows}.
@end itemize @end itemize
All action functions that choose a window should process this entry. By convention, the height of the chosen window is adjusted only if the
window is part of a vertical combination (@pxref{Windows and Frames})
to avoid changing the height of other, unrelated windows. Also, this
entry should be processed only under certain conditions which are
specified right below this list.
@vindex window-width@r{, a buffer display action alist entry} @vindex window-width@r{, a buffer display action alist entry}
@item window-width @item window-width
@ -2825,10 +2832,13 @@ value can be one of the following:
@code{nil} means to leave the width of the chosen window alone. @code{nil} means to leave the width of the chosen window alone.
@item @item
A number specifies the desired width of the chosen window. An integer An integer specifies the desired total width of the chosen window in
specifies the number of columns of the window. A floating-point columns.
number gives the fraction of the window's width with respect to the
width of the frame's root window. @item
A floating-point number specifies the fraction of the chosen window's
desired total width with respect to the total width of the frame's
root window.
@item @item
If the value specifies a function, that function is called with one If the value specifies a function, that function is called with one
@ -2836,16 +2846,21 @@ argument---the chosen window. The function is supposed to adjust the
width of the window; its return value is ignored. width of the window; its return value is ignored.
@end itemize @end itemize
All action functions that choose a window should process this entry. By convention, the width of the chosen window is adjusted only if the
window is part of a horizontal combination (@pxref{Windows and
Frames}) to avoid changing the width of other, unrelated windows.
Also, this entry should be processed under only certain conditions
which are specified right below this list.
@vindex preserve-size@r{, a buffer display action alist entry} @vindex preserve-size@r{, a buffer display action alist entry}
@item preserve-size @item preserve-size
If non-@code{nil} such an entry tells Emacs to preserve the size of If non-@code{nil} such an entry tells Emacs to preserve the size of
the window chosen (@pxref{Preserving Window Sizes}). The value should the window chosen (@pxref{Preserving Window Sizes}). The value should
be either @code{(t . nil)} to preserve the width of the window, be either @w{@code{(t . nil)}} to preserve the width of the window,
@code{(nil . t)} to preserve its height or @code{(t . t)} to preserve @w{@code{(nil . t)}} to preserve its height or @w{@code{(t . t)}} to
both its width and its height. All action functions that choose a preserve both, its width and its height. This entry should be
window should process this entry. processed only under certain conditions which are specified right
after this list.
@vindex pop-up-frame-parameters@r{, a buffer display action alist entry} @vindex pop-up-frame-parameters@r{, a buffer display action alist entry}
@item pop-up-frame-parameters @item pop-up-frame-parameters
@ -2900,6 +2915,15 @@ will display the buffer. @code{display-buffer-no-window} is the only
action function that cares about this entry. action function that cares about this entry.
@end table @end table
By convention, the entries @code{window-height}, @code{window-width}
and @code{preserve-size} are applied after the chosen window's buffer
has been set up and if and only if that window never showed another
buffer before. More precisely, the latter means that the window must
have been either created by the current @code{display-buffer} call or
the window was created earlier by @code{display-buffer} to show the
buffer and never was used to show another buffer until it was reused
by the current invocation of @code{display-buffer}.
@node Choosing Window Options @node Choosing Window Options
@subsection Additional Options for Displaying Buffers @subsection Additional Options for Displaying Buffers

270
lisp/window.el
View file

@ -6705,7 +6705,11 @@ live."
((or (eq type 'frame) ((or (eq type 'frame)
(and (eq (car quit-restore) 'same) (and (eq (car quit-restore) 'same)
(eq (nth 1 quit-restore) 'frame))) (eq (nth 1 quit-restore) 'frame)))
;; Adjust size of frame if asked for. ;; A window that never showed another buffer but BUFFER ever
;; since it was created on a new frame.
;;
;; Adjust size of frame if asked for. We probably should do
;; that only for a single window frame.
(cond (cond
((not size)) ((not size))
((consp size) ((consp size)
@ -6724,7 +6728,10 @@ live."
((or (eq type 'window) ((or (eq type 'window)
(and (eq (car quit-restore) 'same) (and (eq (car quit-restore) 'same)
(eq (nth 1 quit-restore) 'window))) (eq (nth 1 quit-restore) 'window)))
;; Adjust height of window if asked for. ;; A window that never showed another buffer but BUFFER ever
;; since it was created on an existing frame.
;;
;; Adjust width and/or height of window if asked for.
(cond (cond
((not height)) ((not height))
((numberp height) ((numberp height)
@ -6820,31 +6827,41 @@ The actual non-nil value of this variable will be copied to the
"Custom type for `display-buffer' actions.") "Custom type for `display-buffer' actions.")
(defvar display-buffer-overriding-action '(nil . nil) (defvar display-buffer-overriding-action '(nil . nil)
"User-defined overriding action to perform to display a buffer. "Overriding action for buffer display.
This action overrides all the other actions in the action variables This action overrides all the other actions in the action
and arguments passed to `display-buffer'. variables and arguments passed to `display-buffer'. The value
Value should be a cons cell (FUNCTION . ALIST), where FUNCTION is should be a cons cell (FUNCTIONS . ALIST), where FUNCTIONS is a
a function or a list of functions. Each function should accept function or a list of functions. Each function should accept two
two arguments: a buffer to display and an alist similar to ALIST. arguments: a buffer to display and an alist similar to ALIST.
The default value is empty. See `display-buffer' for details.
See `display-buffer' for details.")
This variable is not intended for user customization. Lisp
programs should never set this variable permanently but may bind
it around calls of buffer display functions like `display-buffer'
or `pop-to-buffer'. Since such a binding will affect any nested
buffer display requests, this variable should be used with utmost
care.")
(put 'display-buffer-overriding-action 'risky-local-variable t) (put 'display-buffer-overriding-action 'risky-local-variable t)
(defcustom display-buffer-alist nil (defcustom display-buffer-alist nil
"Alist of user-defined conditional actions for `display-buffer'. "Alist of user-defined conditional actions for `display-buffer'.
Its value takes effect before `display-buffer-base-action' Its value takes effect before processing the ACTION argument of
and `display-buffer-fallback-action', but after `display-buffer' and before `display-buffer-base-action' and
`display-buffer-fallback-action', but after
`display-buffer-overriding-action', which see. `display-buffer-overriding-action', which see.
If non-nil, this is a list of elements (CONDITION . ACTION), where:
If non-nil, this is an alist of elements (CONDITION . ACTION),
where:
CONDITION is either a regexp matching buffer names, or a CONDITION is either a regexp matching buffer names, or a
function that takes two arguments - a buffer name and the function that takes two arguments - a buffer name and the
ACTION argument of `display-buffer' - and returns a boolean. ACTION argument of `display-buffer' - and returns a boolean.
ACTION is a cons cell (FUNCTION . ALIST), where FUNCTION is a ACTION is a cons cell (FUNCTIONS . ALIST), where FUNCTIONS is an
function or a list of functions. Each such function should action function or a list of action functions and ALIST is an
accept two arguments: a buffer to display and an alist of the action alist. Each such action function should accept two
same form as ALIST. See `display-buffer' for details. arguments: a buffer to display and an alist of the same form as
ALIST. See `display-buffer' for details.
`display-buffer' scans this alist until it either finds a `display-buffer' scans this alist until it either finds a
matching regular expression or the function specified by a matching regular expression or the function specified by a
@ -6864,11 +6881,12 @@ associated action to the list of actions it will try."
This is the default action used by `display-buffer' if no other This is the default action used by `display-buffer' if no other
actions are specified or all fail, before falling back on actions are specified or all fail, before falling back on
`display-buffer-fallback-action'. `display-buffer-fallback-action'.
It should be a cons cell (FUNCTION . ALIST), where FUNCTION is a
function or a list of functions. Each function should accept two It should be a cons cell (FUNCTIONS . ALIST), where FUNCTIONS is
arguments: a buffer to display and an alist similar to ALIST. an action function or a list of action functions and ALIST is an
The default value is empty. action alist. Each such action function should accept two
See `display-buffer' for details." arguments: a buffer to display and an alist of the same form as
ALIST. See `display-buffer' for details."
:type display-buffer--action-custom-type :type display-buffer--action-custom-type
:risky t :risky t
:version "24.1" :version "24.1"
@ -6884,17 +6902,20 @@ See `display-buffer' for details."
display-buffer-pop-up-frame)) display-buffer-pop-up-frame))
"Default fallback action for `display-buffer'. "Default fallback action for `display-buffer'.
This is the action used by `display-buffer' if no other actions This is the action used by `display-buffer' if no other actions
specified, e.g. by the user options `display-buffer-alist' or have been specified, for example, by the user options
`display-buffer-base-action', or they all fail. See `display-buffer'.") `display-buffer-alist' or `display-buffer-base-action', or they
all fail. It should never be set by programs or users. See
`display-buffer'.")
(put 'display-buffer-fallback-action 'risky-local-variable t) (put 'display-buffer-fallback-action 'risky-local-variable t)
(defun display-buffer-assq-regexp (buffer-name alist action) (defun display-buffer-assq-regexp (buffer-name alist action)
"Retrieve ALIST entry corresponding to BUFFER-NAME. "Retrieve ALIST entry corresponding to BUFFER-NAME.
This returns the cdr of the ALIST entry if either its key is a This returns the cdr of the alist entry ALIST if either its key
string that matches BUFFER-NAME, as reported by `string-match-p'; is a string that matches BUFFER-NAME, as reported by
or if the key is a function that returns a non-nil when called `string-match-p'; or if the key is a function that returns
with 3 arguments: the ALIST key, BUFFER-NAME, and ACTION. non-nil when called with three arguments: the ALIST key,
ACTION should have the form of the action argument passed to `display-buffer'." BUFFER-NAME and ACTION. ACTION should have the form of the
action argument passed to `display-buffer'."
(catch 'match (catch 'match
(dolist (entry alist) (dolist (entry alist)
(let ((key (car entry))) (let ((key (car entry)))
@ -6923,100 +6944,99 @@ fails, call `display-buffer-pop-up-frame'.")
(defun display-buffer (buffer-or-name &optional action frame) (defun display-buffer (buffer-or-name &optional action frame)
"Display BUFFER-OR-NAME in some window, without selecting it. "Display BUFFER-OR-NAME in some window, without selecting it.
BUFFER-OR-NAME must be a buffer or the name of an existing BUFFER-OR-NAME must be a buffer or a string naming a live buffer.
buffer. Return the window chosen for displaying BUFFER-OR-NAME, Return the window chosen for displaying that buffer, or nil if no
or nil if no such window is found. such window is found.
Optional argument ACTION, if non-nil, should specify a display Optional argument ACTION, if non-nil, should specify a buffer
action. Its form is described below. display action of the form (FUNCTIONS . ALIST). FUNCTIONS is
either an \"action function\" or a possibly empty list of action
functions. ALIST is a possibly empty \"action alist\".
Optional argument FRAME, if non-nil, acts like an additional An action function is a function that accepts two arguments: the
ALIST entry (reusable-frames . FRAME) to the action list of ACTION, buffer to display and an action alist. Based on those arguments,
specifying the frame(s) to search for a window that is already it should try to display the buffer in a window and return that
displaying the buffer. See `display-buffer-reuse-window'. window. An action alist is an association list mapping symbols
to values. Action functions use the action alist passed to them
to fine-tune their behaviors.
If ACTION is non-nil, it should have the form (FUNCTION . ALIST), `display-buffer' builds a list of action functions and an action
where FUNCTION is either a function or a list of functions, and alist by combining any action functions and alists specified by
ALIST is an arbitrary association list (alist).
Each such function should accept two arguments: the buffer to
display and an alist. Based on those arguments, it should
display the buffer and return the window. If the caller is
prepared to handle the case of not displaying the buffer
and returning nil from `display-buffer' it should pass
\(allow-no-window . t) as an element of the ALIST.
The `display-buffer' function builds a function list and an alist
by combining the functions and alists specified in
`display-buffer-overriding-action', `display-buffer-alist', the `display-buffer-overriding-action', `display-buffer-alist', the
ACTION argument, `display-buffer-base-action', and ACTION argument, `display-buffer-base-action', and
`display-buffer-fallback-action' (in order). Then it calls each `display-buffer-fallback-action' (in order). Then it calls each
function in the combined function list in turn, passing the function in the combined function list in turn, passing the
buffer as the first argument and the combined alist as the second buffer as the first argument and the combined action alist as the
argument, until one of the functions returns non-nil. second argument, until one of the functions returns non-nil.
If ACTION is nil, the function list and the alist are built using Action functions and the action they try to perform are:
only the other variables mentioned above. `display-buffer-same-window' -- Use the selected window.
`display-buffer-reuse-window' -- Use a window already showing
the buffer.
`display-buffer-in-previous-window' -- Use a window that did
show the buffer before.
`display-buffer-use-some-window' -- Use some existing window.
`display-buffer-pop-up-window' -- Pop up a new window.
`display-buffer-below-selected' -- Use or pop up a window below
the selected one.
`display-buffer-at-bottom' -- Use or pop up a window at the
bottom of the selected frame.
`display-buffer-pop-up-frame' -- Show the buffer on a new frame.
`display-buffer-in-child-frame' -- Show the buffer in a
child frame.
`display-buffer-no-window' -- Do not display the buffer and
have `display-buffer' return nil immediately.
Available action functions include: Action alist entries are:
`display-buffer-same-window' 'inhibit-same-window' -- A non-nil value prevents the same
`display-buffer-reuse-window' window from being used for display.
`display-buffer-pop-up-frame' 'inhibit-switch-frame' -- A non-nil value prevents any frame
`display-buffer-in-child-frame' used for showing the buffer from being raised or selected.
`display-buffer-pop-up-window' 'reusable-frames' -- The value specifies the set of frames to
`display-buffer-in-previous-window' search for a window that already displays the buffer.
`display-buffer-use-some-window' Possible values are nil (the selected frame), t (any live
`display-buffer-use-some-frame' frame), visible (any visible frame), 0 (any visible or
iconified frame) or an existing live frame.
'pop-up-frame-parameters' -- The value specifies an alist of
frame parameters to give a new frame, if one is created.
'window-height' -- The value specifies the desired height of the
window chosen and is either an integer (the total height of
the window), a floating point number (the fraction of its
total height with respect to the total height of the frame's
root window) or a function to be called with one argument -
the chosen window. The function is supposed to adjust the
height of the window; its return value is ignored. Suitable
functions are `shrink-window-if-larger-than-buffer' and
`fit-window-to-buffer'.
'window-width' -- The value specifies the desired width of the
window chosen and is either an integer (the total width of
the window), a floating point number (the fraction of its
total width with respect to the width of the frame's root
window) or a function to be called with one argument - the
chosen window. The function is supposed to adjust the width
of the window; its return value is ignored.
'preserve-size' -- The value should be either (t . nil) to
preserve the width of the chosen window, (nil . t) to
preserve its height or (t . t) to preserve its height and
width in future changes of the window configuration.
'window-parameters' -- The value specifies an alist of window
parameters to give the chosen window.
'allow-no-window' -- A non-nil value means that `display-buffer'
may not display the buffer and return nil immediately.
Recognized alist entries include: The entries 'window-height', 'window-width' and 'preserve-size'
are applied only when the window used for displaying the buffer
never showed another buffer before.
`inhibit-same-window' -- A non-nil value prevents the same The ACTION argument can also have a non-nil and non-list value.
window from being used for display. This means to display the buffer in a window other than the
selected one, even if it is already displayed in the selected
window. If called interactively with a prefix argument, ACTION
is t. Non-interactive calls should always supply a list or nil.
`inhibit-switch-frame' -- A non-nil value prevents any other The optional third argument FRAME, if non-nil, acts like a
frame from being raised or selected, \(reusable-frames . FRAME) entry appended to the action alist
even if the window is displayed there. specified by the ACTION argument."
`reusable-frames' -- Value specifies frame(s) to search for a
window that already displays the buffer.
See `display-buffer-reuse-window'.
`pop-up-frame-parameters' -- Value specifies an alist of frame
parameters to give a new frame, if
one is created.
`window-height' -- Value specifies either an integer (the number
of lines of a new window), a floating point number (the
fraction of a new window with respect to the height of the
frame's root window) or a function to be called with one
argument - a new window. The function is supposed to adjust
the height of the window; its return value is ignored.
Suitable functions are `shrink-window-if-larger-than-buffer'
and `fit-window-to-buffer'.
`window-width' -- Value specifies either an integer (the number
of columns of a new window), a floating point number (the
fraction of a new window with respect to the width of the
frame's root window) or a function to be called with one
argument - a new window. The function is supposed to adjust
the width of the window; its return value is ignored.
`allow-no-window' -- A non-nil value indicates readiness for the case
of not displaying the buffer and FUNCTION can safely return
a non-window value to suppress displaying.
`preserve-size' -- Value should be either (t . nil) to
preserve the width of the window, (nil . t) to preserve its
height or (t . t) to preserve both.
`window-parameters' -- Value specifies an alist of window
parameters to give the chosen window.
The ACTION argument to `display-buffer' can also have a non-nil
and non-list value. This means to display the buffer in a window
other than the selected one, even if it is already displayed in
the selected window. If called interactively with a prefix
argument, ACTION is t."
(interactive (list (read-buffer "Display buffer: " (other-buffer)) (interactive (list (read-buffer "Display buffer: " (other-buffer))
(if current-prefix-arg t))) (if current-prefix-arg t)))
(let ((buffer (if (bufferp buffer-or-name) (let ((buffer (if (bufferp buffer-or-name)
@ -7074,9 +7094,10 @@ its documentation for additional customization information."
;;; `display-buffer' action functions: ;;; `display-buffer' action functions:
(defun display-buffer-use-some-frame (buffer alist) (defun display-buffer-use-some-frame (buffer alist)
"Display BUFFER in an existing frame that meets a predicate "Display BUFFER in an existing frame that meets a predicate.
\(by default any frame other than the current frame). If The default predicate is to use any frame other than the selected
successful, return the window used; otherwise return nil. frame. If successful, return the window used; otherwise return
nil.
If ALIST has a non-nil `inhibit-switch-frame' entry, avoid If ALIST has a non-nil `inhibit-switch-frame' entry, avoid
raising the frame. raising the frame.
@ -7089,17 +7110,18 @@ predicate.
If ALIST has a non-nil `inhibit-same-window' entry, avoid using If ALIST has a non-nil `inhibit-same-window' entry, avoid using
the currently selected window (only useful with a frame-predicate the currently selected window (only useful with a frame-predicate
that allows the selected frame)." that allows the selected frame)."
(let* ((predicate (or (cdr (assq 'frame-predicate alist)) (let* ((predicate
(lambda (frame) (or (cdr (assq 'frame-predicate alist))
(and (lambda (frame)
(not (eq frame (selected-frame))) (and (not (eq frame (selected-frame)))
(not (window-dedicated-p (not (window-dedicated-p
(or (or (get-lru-window frame)
(get-lru-window frame) (frame-first-window frame))))))))
(frame-first-window frame)))))
)))
(frame (car (filtered-frame-list predicate))) (frame (car (filtered-frame-list predicate)))
(window (and frame (get-lru-window frame nil (cdr (assq 'inhibit-same-window alist)))))) (window
(and frame
(get-lru-window
frame nil (cdr (assq 'inhibit-same-window alist))))))
(when window (when window
(prog1 (prog1
(window--display-buffer (window--display-buffer