diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 7dbd680..7ad9a77 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -48,8 +48,8 @@ Basic Window @kbd{C-x 4 b} that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} -(@code{list-buffers}), work by switching buffers in a nonselected -window without affecting the selected window. +(@code{list-buffers}), usually work by displaying buffers in a +nonselected window without affecting the selected window. When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, @@ -340,11 +340,9 @@ Displaying Buffers in response to a user command. There are several different ways in which commands do this. - Many commands, like @kbd{C-x C-f} (@code{find-file}), display the -buffer by ``taking over'' the selected window, expecting that the -user's attention will be diverted to that buffer. These commands -usually work by calling @code{switch-to-buffer} internally -(@pxref{Select Buffer}). + Many commands, like @kbd{C-x C-f} (@code{find-file}), by default +display the buffer by ``taking over'' the selected window, expecting +that the user's attention will be diverted to that buffer. Some commands try to display intelligently, trying not to take over the selected window, e.g., by splitting off a new window and @@ -367,10 +365,9 @@ Displaying Buffers Commands with names ending in @code{-other-frame} behave like @code{display-buffer}, except that they (i) never display in the -selected window and (ii) prefer to create a new frame to display the -desired buffer instead of splitting a window---as though the variable address@hidden is set to @code{t} (@pxref{Window Choice}). -Several of these commands are bound in the @kbd{C-x 5} prefix key. +selected window and (ii) prefer to either create a new frame or use a +window on some other frame to display the desired buffer. Several of +these commands are bound in the @kbd{C-x 5} prefix key. @menu * Window Choice:: How @code{display-buffer} works. @@ -388,28 +385,56 @@ Window Choice sequence of steps. @itemize address@hidden same-window-buffer-names address@hidden same-window-regexps @item First, check if the buffer should be displayed in the selected window regardless of other considerations. You can tell Emacs to do this by -adding the desired buffer's name to the list address@hidden, or adding a matching regular -expression to the list @code{same-window-regexps}. By default, these -variables are @code{nil}, so this step is skipped. +adding a regular expression matching the buffer's name together with a +reference to the @code{display-buffer-same-window} action function +(@pxref{Action Functions,,Action Functions for Buffer Display, elisp, +The Emacs Lisp Reference Manual}) to the option address@hidden (@pxref{Choosing Window,,Choosing a Window +for Display, elisp, The Emacs Lisp Reference Manual}). For example, +to display the buffer @file{*scratch*} preferably in the selected +window write: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '("\\*scratch\\*" (display-buffer-same-window))) address@hidden group address@hidden example + +By default, @code{display-buffer-alist} is @code{nil}, so this step is +skipped. @item Otherwise, if the buffer is already displayed in an existing window, -reuse that window. Normally, only windows on the selected frame -are considered, but windows on other frames are also reusable if you -change @code{pop-up-frames} (see below) to @code{t}. +reuse that window. Normally, only windows on the selected frame are +considered, but windows on other frames are also reusable if a +corresponding @code{reusable-frames} action alist entry (@pxref{Action +Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp +Reference Manual}) is used (see the next step for an example of how to +do that). address@hidden pop-up-frames @item Otherwise, optionally create a new frame and display the buffer there. -By default, this step is skipped. To enable it, change the variable address@hidden to a address@hidden value. The special value address@hidden means to do this only on graphical displays. +By default, this step is skipped. To enable it, change the value of +the option @code{display-buffer-base-action} (@pxref{Choosing +Window,,Choosing a Window for Display, elisp, The Emacs Lisp Reference +Manual}) as follows: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) address@hidden group address@hidden example + +This customization will also try to make the preceding step search for +a reusable window on all visible of iconified frames @item Otherwise, try to create a new window by splitting a window on the @@ -429,9 +454,9 @@ Window Choice @item Otherwise, display the buffer in a window previously showing it. -Normally, only windows on the selected frame are considered, but if address@hidden is address@hidden the window may be also on another -frame. +Normally, only windows on the selected frame are considered, but with +a suitable @code{reusable-frames} action alist entry (see above) the +window may be also on another frame. @item Otherwise, display the buffer in an existing window on the selected @@ -442,14 +467,9 @@ Window Choice and display the buffer there. @end itemize -A more advanced and flexible way to customize the behavior of address@hidden is by using the option @code{display-buffer-alist} -mentioned in the next section. - @node Temporary Displays @subsection Displaying non-editable buffers. address@hidden pop-up windows @cindex temporary windows Some buffers are shown in windows for perusal rather than for editing. @@ -459,24 +479,23 @@ Temporary Displays displayed only for a short period of time. Normally, Emacs chooses the window for such temporary displays via address@hidden as described above. The @file{*Completions*} -buffer, on the other hand, is normally displayed in a window at the -bottom of the selected frame, regardless of the number of windows -already shown on that frame. address@hidden as described in the previous subsection. The address@hidden buffer, on the other hand, is normally displayed +in a window at the bottom of the selected frame, regardless of the +number of windows already shown on that frame. If you prefer Emacs to display a temporary buffer in a different fashion, we recommend customizing the variable @code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window for Display, elisp, The Emacs Lisp Reference Manual}). For example, -to display @file{*Completions*} by splitting a window as described in -the previous section, use the following form in your initialization -file (@pxref{Init File}): +to display @file{*Completions*} always below the selected window, use +the following form in your initialization file (@pxref{Init File}): @example @group (customize-set-variable 'display-buffer-alist - '(("\\*Completions\\*" display-buffer-pop-up-window))) + '(("\\*Completions\\*" display-buffer-below-selected))) @end group @end example diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 6c3182b..e0939e5 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1043,9 +1043,7 @@ Top * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Displaying Buffers:: Displaying a buffer in a suitable window. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. @@ -1067,6 +1065,18 @@ Top redisplay going past a certain point, or window configuration changes. +Displaying Buffers + +* Choosing Window:: How to choose a window for displaying a buffer. +* Action Functions:: Support functions for buffer display. +* Action Alists:: Alists for fine-tuning buffer display + action functions. +* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Precedence of Action Functions:: A tutorial explaining the precedence of + buffer display action functions. +* The Zen of Buffer Display:: How to avoid that buffers get lost in between + windows. + Side Windows * Displaying Buffers in Side Windows:: An action function for displaying diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 1e008da..31fb7ce 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -3198,11 +3198,10 @@ Child Frames @code{drag-with-mode-line} parameter. When a child frame is used for displaying a buffer via address@hidden (@pxref{Display Action Functions}), -the frame's @code{auto-hide-function} parameter (@pxref{Frame -Interaction Parameters}) can be set to a function, in order to -appropriately deal with the frame when the window displaying the buffer -shall be quit. address@hidden (@pxref{Action Functions}), the +frame's @code{auto-hide-function} parameter (@pxref{Frame Interaction +Parameters}) can be set to a function, in order to appropriately deal +with the frame when the window displaying the buffer shall be quit. When a child frame is used during minibuffer interaction, for example, to display completions in a separate window, the @code{minibuffer-exit} diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 2650671..c14c441 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -25,9 +25,7 @@ Windows * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Displaying Buffers:: Displaying a buffer in a suitable window. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. @@ -162,6 +160,7 @@ Basic Windows in the group). @end defun + @node Windows and Frames @section Windows and Frames @@ -1542,11 +1541,11 @@ Recombining Windows window is created anyway). @item window-size -This means that @code{display-buffer} makes a new parent window when it -splits a window and is passed a @code{window-height} or address@hidden entry in the @var{alist} argument (@pxref{Display -Action Functions}). Otherwise, window splitting behaves as for a value -of @code{nil}. +This means that @code{display-buffer} makes a new parent window when +it splits a window and is passed a @code{window-height} or address@hidden entry in the @var{alist} argument (@pxref{Action +Functions}). Otherwise, window splitting behaves as for a value of address@hidden @item temp-buffer-resize In this case @code{with-temp-buffer-window} makes a new parent window @@ -1879,7 +1878,7 @@ Cyclic Window Ordering @cindex ordering of windows, cyclic @cindex window ordering, cyclic - When you use the command @kbd{C-x o} (@code{other-window}) to select + When you use the command @address@hidden o}} (@code{other-window}) to select some other window, it moves through live windows in a specific order. For any given configuration of windows, this order never varies. It is called the @dfn{cyclic ordering of windows}. @@ -1899,7 +1898,7 @@ Cyclic Window Ordering The optional argument @var{minibuf} specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when @var{minibuf} is @code{nil}, a minibuffer window is included only if it is currently -active; this matches the behavior of @kbd{C-x o}. (Note that a +active; this matches the behavior of @address@hidden o}}. (Note that a minibuffer window is active as long as its minibuffer is in use; see @ref{Minibuffers}). @@ -2327,10 +2326,39 @@ Switching Buffers @end deffn address@hidden Displaying Buffers address@hidden Displaying a Buffer in a Suitable Window + +In this section we describe how Emacs finds or creates a window +suitable for displaying a buffer. We first introduce the function address@hidden workhorse for choosing such a window. +Next, action functions---auxiliary functions called by address@hidden to find or create a suitable window---are +presented. Then we describe action alists---special association lists +used to fine-tune the behavior of action functions. + + We continue with the description of additional options to customize +the behavior of @code{display-buffer}. Then a series of examples will +try to explain the precedence among action functions in a single call +of @code{display-buffer}. We conclude this section with some +guidelines for managing the complexity of buffer display. + address@hidden +* Choosing Window:: How to choose a window for displaying a buffer. +* Action Functions:: Support functions for buffer display. +* Action Alists:: Alists for fine-tuning buffer display. +* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Precedence of Action Functions:: Examples to explain the precedence of + action functions. +* The Zen of Buffer Display:: How to avoid that buffers get lost in between + windows. address@hidden menu + + @node Choosing Window address@hidden Choosing a Window for Display address@hidden Choosing a Window for Displaying a Buffer - The command @code{display-buffer} flexibly chooses a window for +The command @code{display-buffer} flexibly chooses a window for display, and displays a specified buffer in that window. It can be called interactively, via the key binding @kbd{C-x 4 C-o}. It is also used as a subroutine by many functions and commands, including @@ -2351,8 +2379,9 @@ Choosing Window an action alist. It attempts to display the buffer in some window, picking or creating a window according to its own criteria. If successful, it returns the window; otherwise, it returns @code{nil}. address@hidden Action Functions}, for a list of predefined action -functions. address@hidden Functions}, for a list of predefined action functions. address@hidden Alists}, for a list of action alist entries recognized by +these functions. @code{display-buffer} works by combining display actions from several sources, and calling the action functions in turn, until one @@ -2364,11 +2393,13 @@ Choosing Window selecting the window or making the buffer current. The argument @var{buffer-or-name} must be a buffer or the name of an existing buffer. The return value is the window chosen to display the buffer. +It is @code{nil} if no suitable window was found. The optional argument @var{action}, if address@hidden, should normally be a display action (described above). @code{display-buffer} builds a list of action functions and an action alist, by consolidating display -actions from the following sources (in order): +actions from the following sources (in order of their precedence, +highest ranking first): @itemize @item @@ -2388,12 +2419,35 @@ Choosing Window @end itemize @noindent -Each action function is called in turn, passing the buffer as the -first argument and the combined action alist as the second argument, -until one of the functions returns address@hidden The caller can -pass @code{(allow-no-window . t)} as an element of the action alist to -indicate its readiness to handle the case of not displaying the -buffer in a window. +In practice this means that @code{display-buffer} builds a list of all +action functions specified by these display actions. The first +element of this list is the first action function specified by address@hidden, if any. The last element of +this list is @code{display-buffer-pop-up-frame}---the last action +function specified by @code{display-buffer-fallback-action}. +Duplicates are not removed from this list---hence the same action +function may be called multiple times during one call of address@hidden + address@hidden calls the action functions specified by this +list in turn, passing the buffer as the first argument and the +combined action alist as the second argument, until one of the +functions returns address@hidden + +Note that the second argument is always the list of @emph{all} action +alist entries specified by the sources named above. Hence, the first +element of this list is the first action alist entry specified by address@hidden, if any. The last element of +this list is the last alist entry specified by address@hidden, if any (the action alist specified +by @code{display-buffer-fallback-action} is empty). + +Note also, that the combined action alist may contain duplicate +entries and entries for the same key with different values. As a +rule, action functions always use the first association for each key +so users may not expect that the association found by the action +function is the one provided by the same display action, +see @ref{Precedence of Action Functions} for an example. The argument @var{action} can also have a address@hidden, non-list value. This has the special meaning that the buffer should be @@ -2404,8 +2458,8 @@ Choosing Window The optional argument @var{frame}, if address@hidden, specifies which frames to check when deciding whether the buffer is already displayed. It is equivalent to adding an element @code{(reusable-frames -. @var{frame})} to the action alist of @var{action}. @xref{Display -Action Functions}. +. @var{frame})} to the action alist of @var{action} (@pxref{Action +Alists}). @end deffn @defvar display-buffer-overriding-action @@ -2437,13 +2491,16 @@ Choosing Window @end defvr address@hidden Display Action Functions address@hidden Action Functions for @code{display-buffer} address@hidden Action Functions address@hidden Action Functions for Buffer Display The following basic action functions are defined in Emacs. Each of these functions takes two arguments: @var{buffer}, the buffer to -display, and @var{alist}, an action alist. Each action function -returns the window if it succeeds, and @code{nil} if it fails. +display, and @var{alist}, an action alist. As a rule, each action +function is supposed to return a window displaying @var{buffer} if it +succeeds and @code{nil} if it fails (for the sole exception to this +rule see the last function listed address@hidden). @defun display-buffer-same-window buffer alist This function tries to display @var{buffer} in the selected window. @@ -2453,57 +2510,103 @@ Display Action Functions @end defun @defun display-buffer-reuse-window buffer alist -This function tries to display @var{buffer} by finding a window -that is already displaying it. +This function tries to display @var{buffer} by finding a window that +is already displaying it. If @var{alist} has a address@hidden @code{inhibit-same-window} entry, -the selected window is not eligible for reuse. If @var{alist} -contains a @code{reusable-frames} entry, its value determines which -frames to search for a reusable window: - address@hidden @bullet address@hidden address@hidden means consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) address@hidden address@hidden means consider windows on all frames. address@hidden address@hidden means consider windows on all visible frames. address@hidden -0 means consider windows on all visible or iconified frames. address@hidden -A frame means consider windows on that frame only. address@hidden itemize - -Note that these meanings differ slightly from those of the address@hidden argument to @code{next-window} (@pxref{Cyclic Window -Ordering}). - -If @var{alist} contains no @code{reusable-frames} entry, this function -normally searches just the selected frame; however, if the variable address@hidden is address@hidden, it searches all frames on the -current terminal. @xref{Choosing Window Options}. +the selected window is not eligible for reuse. The set of frames to +search for a window already displaying @var{buffer} can be specified +with the help of a @code{reusable-frames} action alist entry +(@pxref{Action Alists}). If @var{alist} contains no address@hidden entry, this function searches just the selected +frame. -If this function chooses a window on another frame, it makes that frame -visible and, unless @var{alist} contains an @code{inhibit-switch-frame} -entry (@pxref{Choosing Window Options}), raises that frame if necessary. +If this function chooses a window on another frame, it makes that +frame visible and, unless @var{alist} contains an address@hidden entry (@pxref{Action Alists}), raises that +frame if necessary. @end defun @defun display-buffer-reuse-mode-window buffer alist This function tries to display @var{buffer} by finding a window that is displaying a buffer in a given mode. -If @var{alist} contains a @code{mode} entry, its value is a major mode -(a symbol) or a list of major modes. If @var{alist} contains no address@hidden entry, the current major mode of @var{buffer} is used. A -window is a candidate if it displays a buffer that derives from one of -the given modes. +If @var{alist} contains a @code{mode} entry, its value specifes a +major mode (a symbol) or a list of major modes. If @var{alist} +contains no @code{mode} entry, the current major mode of @var{buffer} +is used instead. A window is a candidate if it displays a buffer +whose mode derives from one of the modes specified thusly. -The behavior is also controlled by entries for +The behavior is also controlled by alist entries for @code{inhibit-same-window}, @code{reusable-frames} and address@hidden as is done in the function address@hidden address@hidden (@pxref{Action Alists}) as is done in the +function @code{display-buffer-reuse-window}. address@hidden defun address@hidden display-buffer-pop-up-window buffer alist +This function tries to display @var{buffer} by splitting the largest +or least recently-used window (typically one on the selected frame). +It actually performs the split by calling the function specified by address@hidden (@pxref{Choosing Window +Options}). + +The size of the new window can be adjusted by supplying address@hidden and @code{window-width} entries in @var{alist} +(@pxref{Action Alists}). If @var{alist} contains a address@hidden entry (@pxref{Action Alists}), Emacs will try to +preserve the size of the new window during future resize operations +(@pxref{Preserving Window Sizes}). + +This function fails if no window can be split. More often than not +this happens because no window is large enough to allow splitting. +Setting @code{split-height-threshold} or @code{split-width-threshold} +(@pxref{Choosing Window Options}) to a lower value may help in this +regard. It also happens when the selected frame has an address@hidden frame parameter; @pxref{Buffer Parameters}. address@hidden defun + address@hidden display-buffer-in-previous-window buffer alist +This function tries to display @var{buffer} in a window previously +showing it. If @var{alist} has a address@hidden address@hidden entry, the selected window is not eligible +for reuse. If @var{alist} contains a @code{reusable-frames} entry, +its value determines which frames to search for a suitable window +(@pxref{Action Alists}). + +If @var{alist} has a @code{previous-window} entry and the window +specified by that entry is live and not dedicated to another buffer, +that window will be preferred, even if it never showed @var{buffer} +before. address@hidden defun + address@hidden display-buffer-use-some-window buffer alist +This function tries to display @var{buffer} by choosing an existing +window and displaying the buffer in that window. It can fail if all +windows are dedicated to another buffer (@pxref{Dedicated Windows}). address@hidden defun + address@hidden display-buffer-below-selected buffer alist +This function tries to display @var{buffer} in a window below the +selected window. If there is a window below the selected one and that +window already displays @var{buffer}, it reuses that window. + +If there is no such window, this function tries to create a new window +by splitting the selected one and display @var{buffer} there. It will +also adjust that window's size provided @var{alist} contains a suitable address@hidden or @code{window-width} entry, see above. + +If splitting the selected window fails and there is a non-dedicated +window below the selected one showing some other buffer, it uses that +window for showing @var{buffer}. address@hidden defun + address@hidden display-buffer-at-bottom buffer alist +This function tries to display @var{buffer} in a window at the bottom +of the selected frame. + +This either splits the window at the bottom of the frame or the +frame's root window, or reuses an existing window at the bottom of the +selected frame. @end defun @defun display-buffer-pop-up-frame buffer alist @@ -2537,11 +2640,12 @@ Display Action Functions @defun display-buffer-use-some-frame buffer alist This function tries to display @var{buffer} by trying to find a frame that meets a predicate (by default any frame other than the -current frame). +selected frame). -If this function chooses a window on another frame, it makes that frame -visible and, unless @var{alist} contains an @code{inhibit-switch-frame} -entry (@pxref{Choosing Window Options}), raises that frame if necessary. +If this function chooses a window on another frame, it makes that +frame visible and, unless @var{alist} contains an address@hidden entry (@pxref{Action Alists}), raises that +frame if necessary. If @var{alist} has a address@hidden @code{frame-predicate} entry, its value is a function taking one argument (a frame), returning @@ -2549,207 +2653,220 @@ Display Action Functions default predicate. If @var{alist} has a address@hidden @code{inhibit-same-window} entry, -the selected window is used; thus if the selected frame has a single -window, it is not used. +the selected window is not used; thus if the selected frame has a +single window, it is not used. @end defun address@hidden display-buffer-pop-up-window buffer alist -This function tries to display @var{buffer} by splitting the largest -or least recently-used window (typically one on the selected frame). -It actually performs the split by calling the function specified in address@hidden (@pxref{Choosing Window -Options}). address@hidden display-buffer-no-window buffer alist +If @var{alist} has a address@hidden @code{allow-no-window} entry, then +this function does not display @code{buffer} and returns the symbol address@hidden This will skip the excution of any further display +actions and cause @code{display-buffer} to return @code{nil}. -The size of the new window can be adjusted by supplying address@hidden and @code{window-width} entries in @var{alist}. To -adjust the window's height, use an entry whose @sc{car} is address@hidden and whose @sc{cdr} is one of: + It is assumed that when a call of @code{display-buffer} specifies a address@hidden @code{allow-no-window} entry, the caller can handle a address@hidden return value. address@hidden defun + +If the @var{alist} argument of any of these functions contains a address@hidden entry, @code{display-buffer} assigns the +elements of the associated value as window parameters of the chosen +window. + + address@hidden Action Alists address@hidden Action Alists for Buffer Display + +An action alist (@pxref{Choosing Window}) is an association list +mapping predefined symbols recognized by action functions to values +these functions are supposed to interpret accordingly. In each call, address@hidden builds a new, possibly empty, action alist and +passes that entire list on to the action functions it calls. + + By design, action functions are free in their interpretation of +action alist entries. In fact, some entries like address@hidden or @code{previous-window} have a meaning only +for one or a few action functions and are ignored by the rest. Other +entries, like @code{inhibit-same-window} or @code{window-parameters}, +are supposed to be respected by most action functions including those +provided by application programs and external packages. + + In the previous subsection we have described in detail how +individual action functions interpret the action alist entries they +care about. Here we give a reference list of all known action alist +entries according to their symbols, together with their values and +action functions that recognize them. Throughout this list, the terms +``buffer'' will refer to the buffer @code{display-buffer} is supposed +to display and ``value'' to the entry's value. + address@hidden @code address@hidden allow-no-window +If the value is address@hidden, @code{display-buffer} does not +necessarily have to display the buffer and the caller is prepared to +accept that. This entry is not intended for user customizations since +there is no guarantee that an arbitrary caller of address@hidden will be able to handle the case that no window +will display the buffer. @code{display-buffer-no-window} is the only +action function that cares about this entry. + address@hidden inhibit-same-window +If the value is address@hidden, this signals that the selected window +must not be used for displaying the buffer. All action functions that +(re-)use an existing window respect this entry. + address@hidden previous-window +The value must specify a window that may have displayed the buffer +previously. @code{display-buffer-in-previous-window} will give +preference to such a window provided it is still live and not +dedicated to another buffer. + address@hidden mode +The value is either a major mode or a list of major modes. address@hidden may reuse a window whenever +the value specified by this entry matches the major mode of that +window's buffer. Other action functions ignore such entries. + address@hidden frame-predicate +The value must be a function taking one argument (a frame), supposed +to return address@hidden if that frame is a candidate for displaying +the buffer. This entry is used by address@hidden + address@hidden pop-up-frame-parameters +The value specifies an alist of frame parameters to give a new frame, +if one is created. @code{display-buffer-pop-up-frame} is its one and +only one addressee. + address@hidden reusable-frames +The value specifies the frame(s) to search for a window that can be +reused because it already displays the buffer. It can be set as +follows: + address@hidden @bullet address@hidden address@hidden means consider only windows on the selected frame. +(Actually, the last frame used that is not a minibuffer-only frame.) address@hidden address@hidden means consider windows on all frames. address@hidden address@hidden means consider windows on all visible frames. address@hidden +0 means consider windows on all visible or iconified frames. address@hidden +A frame means consider windows on that frame only. address@hidden itemize + +Note that the meaning of @code{nil} differs slightly from that of the address@hidden argument to @code{next-window} (@pxref{Cyclic Window +Ordering}). + +A major client of this is @code{display-buffer-reuse-window} but all +other action functions that try to reuse a window are affected as +well. + address@hidden inhibit-switch-frame +A address@hidden value prevents another frame from being raised or +selected, if the window chosen by @code{display-buffer} is displayed +there. Primarily affected by this are address@hidden and address@hidden address@hidden should be affected as well but +there is no guarantee that the window manager will not override it. + address@hidden window-parameters +The value specifies an alist of window parameters to give the chosen +window. All action functions that choose a window should process this +entry. + address@hidden window-height +The value specifies whether and how to adjust the height of the chosen +window and can be provided as follows: @itemize @bullet @item address@hidden means to leave the height of the new window alone. address@hidden means to leave the height of the chosen window alone. @item -A number specifies the desired height of the new window. An integer -specifies the number of lines of the window. A floating-point +A number specifies the desired height of the chosen window. An +integer specifies the number of lines of the window. A floating-point number gives the fraction of the window's height with respect to the height of the frame's root window. @item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the +If the value specifies a function, that function is 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 @code{shrink-window-if-larger-than-buffer} and @code{fit-window-to-buffer}, see @ref{Resizing Windows}. @end itemize -To adjust the window's width, use an entry whose @sc{car} is address@hidden and whose @sc{cdr} is one of: +All action functions that choose a window should process this entry. + address@hidden window-width +This entry is similar to the @code{window-height} entry described +before but can be used to adjust the chosen window's width instead. +The value can be one of the following: @itemize @bullet @item address@hidden means to leave the width of the new window alone. address@hidden means to leave the width of the chosen window alone. @item -A number specifies the desired width of the new window. An integer +A number specifies the desired width of the chosen window. An integer specifies the number of columns of the window. A floating-point number gives the fraction of the window's width with respect to the width of the frame's root window. @item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the width -of the window; its return value is ignored. +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +width of the window; its return value is ignored. @end itemize -If @var{alist} contains a @code{preserve-size} entry, Emacs will try to -preserve the size of the new window during future resize operations -(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a -cons cell whose @sc{car}, if address@hidden, means to preserve the width -of the window and whose @sc{cdr}, if address@hidden, means to preserve -the height of the window. - -This function can fail if no window splitting can be performed for some -reason (e.g., if the selected frame has an @code{unsplittable} frame -parameter; @pxref{Buffer Parameters}). address@hidden defun - address@hidden display-buffer-below-selected buffer alist -This function tries to display @var{buffer} in a window below the -selected window. If there is a window below the selected one and that -window already displays @var{buffer}, it reuses that window. - -If there is no such window, this function tries to create a new window -by splitting the selected one and display @var{buffer} there. It will -also adjust that window's size provided @var{alist} contains a suitable address@hidden or @code{window-width} entry, see above. - -If splitting the selected window fails and there is a non-dedicated -window below the selected one showing some other buffer, it uses that -window for showing @var{buffer}. address@hidden defun +All action functions that choose a window should process this entry. address@hidden display-buffer-in-previous-window buffer alist -This function tries to display @var{buffer} in a window previously -showing it. If @var{alist} has a address@hidden address@hidden entry, the selected window is not eligible -for reuse. If @var{alist} contains a @code{reusable-frames} entry, its -value determines which frames to search for a suitable window as with address@hidden address@hidden preserve-size +If address@hidden such an entry tells Emacs to preserve the size of +the window chosen (@pxref{Preserving Window Sizes}). The value should +be either @code{(t . nil)} to preserve the width of the window, address@hidden(nil . t)} to preserve its height or @code{(t . t)} to preserve +both, its width and its height. All action functions that choose a +window should process this entry. -If @var{alist} has a @code{previous-window} entry, the window -specified by that entry will override any other window found by the -methods above, even if that window never showed @var{buffer} before. address@hidden defun address@hidden child-frame-parameters +The value specifies an alist of frame parameters used when the buffer +is displayed on a child frame. This entry is used by address@hidden only. address@hidden display-buffer-at-bottom buffer alist -This function tries to display @var{buffer} in a window at the bottom -of the selected frame. - -This either splits the window at the bottom of the frame or the -frame's root window, or reuses an existing window at the bottom of the -selected frame. address@hidden defun - address@hidden display-buffer-use-some-window buffer alist -This function tries to display @var{buffer} by choosing an existing -window and displaying the buffer in that window. It can fail if all -windows are dedicated to another buffer (@pxref{Dedicated Windows}). address@hidden defun - address@hidden display-buffer-no-window buffer alist -If @var{alist} has a address@hidden @code{allow-no-window} entry, then -this function does not display @code{buffer}. This allows you to -override the default action and avoid displaying the buffer. It is -assumed that when the caller specifies a address@hidden address@hidden value it can handle a @code{nil} value returned -from @code{display-buffer} in this case. address@hidden defun - -If the @var{alist} argument of any of these functions contains a address@hidden entry, @code{display-buffer} assigns the -elements of the associated value as window parameters of the chosen -window. - - To illustrate the use of action functions, consider the following -example. - address@hidden address@hidden -(display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40))) address@hidden group address@hidden example - address@hidden -Evaluating the form above will cause @code{display-buffer} to proceed as -follows: If a buffer called *foo* already appears on a visible or -iconified frame, it will reuse its window. Otherwise, it will try to -pop up a new window or, if that is impossible, a new frame and show the -buffer there. If all these steps fail, it will proceed using whatever address@hidden and address@hidden prescribe. - - Furthermore, @code{display-buffer} will try to adjust a reused window -(provided *foo* was put by @code{display-buffer} there before) or a -popped-up window as follows: If the window is part of a vertical -combination, it will set its height to ten lines. Note that if, instead -of the number 10, we specified the function address@hidden, @code{display-buffer} would come up with a -one-line window to fit the empty buffer. If the window is part of a -horizontal combination, it sets its width to 40 columns. Whether a new -window is vertically or horizontally combined depends on the shape of -the window split and the values of address@hidden, @code{split-height-threshold} -and @code{split-width-threshold} (@pxref{Choosing Window Options}). - - Now suppose we combine this call with a preexisting setup for address@hidden as follows. - address@hidden address@hidden -(let ((display-buffer-alist - (cons - '("\\*foo\\*" - (display-buffer-reuse-window display-buffer-below-selected) - (reusable-frames) - (window-height . 5)) - display-buffer-alist))) - (display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40)))) address@hidden group address@hidden example address@hidden side +The value denotes the side of the frame or window where a new window +displaying the buffer shall be created. This entry is used by address@hidden to indicate the side of the frame +where a new side window shall be placed (@pxref{Displaying Buffers in +Side Windows}). It is also used by address@hidden to indicate the side of an +existing window where the new window shall be located (@pxref{Atomic +Windows}). address@hidden -This form will have @code{display-buffer} first try reusing a window -that shows *foo* on the selected frame. If there's no such window, it -will try to split the selected window or, if that is impossible, use the -window below the selected window. address@hidden slot +If address@hidden, the value specifies the slot of the side window +supposed to display the buffer. This entry is used by address@hidden only (@pxref{Displaying Buffers +in Side Windows}). - If there's no window below the selected one, or the window below the -selected one is dedicated to its buffer, @code{display-buffer} will -proceed as described in the previous example. Note, however, that when -it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to 5 since that value -overrides the corresponding specification in the @var{action} argument -of @code{display-buffer}. address@hidden window +The value specifies a window that is in some way related to the window +chosen by @code{display-buffer}. This entry is currently used by address@hidden to indicate the window on whose +side the new window shall be created (@pxref{Atomic Windows}). address@hidden table @node Choosing Window Options address@hidden Additional Options for Displaying Buffers address@hidden Additional Options for Displaying Buffers -The behavior of the standard display actions of @code{display-buffer} -(@pxref{Choosing Window}) can be modified by a variety of user +The behavior of the display actions of @code{display-buffer} +(@pxref{Choosing Window}) can be modified by the following user options. @defopt pop-up-windows @@ -2757,10 +2874,10 @@ Choosing Window Options is allowed to split an existing window to make a new window for displaying in. This is the default. -This variable is provided mainly for backward compatibility. It is +This variable is provided for backward compatibility only. It is obeyed by @code{display-buffer} via a special mechanism in @code{display-buffer-fallback-action}, which only calls the action -function @code{display-buffer-pop-up-window} (@pxref{Display Action +function @code{display-buffer-pop-up-window} (@pxref{Action Functions}) when the value is @code{nil}. It is not consulted by @code{display-buffer-pop-up-window} itself, which the user may specify directly in @code{display-buffer-alist} etc. @@ -2770,7 +2887,7 @@ Choosing Window Options This variable specifies a function for splitting a window, in order to make a new window for displaying a buffer. It is used by the @code{display-buffer-pop-up-window} action function to actually split -the window (@pxref{Display Action Functions}). +the window (@pxref{Action Functions}). The default value is @code{split-window-sensibly}, which is documented below. The value must be a function that takes one argument, a window, @@ -2797,19 +2914,19 @@ Choosing Window Options @end defun @defopt split-height-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window below. If it is an +This variable specifies whether @code{split-window-sensibly} is +allowed to split the window placing the new window below. If it is an integer, that means to split only if the original window has at least that many lines. If it is @code{nil}, that means not to split this way. @end defopt @defopt split-width-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window to the right. If the value -is an integer, that means to split only if the original window has at -least that many columns. If the value is @code{nil}, that means not -to split this way. +This variable specifies whether @code{split-window-sensibly} is +allowed to split the window placing the new window to the right. If +the value is an integer, that means to split only if the original +window has at least that many columns. If the value is @code{nil}, +that means not to split this way. @end defopt @defopt even-window-sizes @@ -2827,30 +2944,11 @@ Choosing Window Options of their combination. @end defopt address@hidden pop-up-frames -If the value of this variable is address@hidden, that means address@hidden may display buffers by making new frames. The -default is @code{nil}. - -A address@hidden value also means that when @code{display-buffer} is -looking for a window already displaying @var{buffer-or-name}, it can -search any visible or iconified frame, not just the selected frame. - -This variable is provided mainly for backward compatibility. It is -obeyed by @code{display-buffer} via a special mechanism in address@hidden, which calls the action function address@hidden (@pxref{Display Action Functions}) -if the value is address@hidden (This is done before attempting to -split a window.) This variable is not consulted by address@hidden itself, which the user may specify -directly in @code{display-buffer-alist} etc. address@hidden defopt - @defopt pop-up-frame-function This variable specifies a function for creating a new frame, in order to make a new window for displaying a buffer. It is used by the address@hidden action function (@pxref{Display -Action Functions}). address@hidden action function (@pxref{Action +Functions}). The value should be a function that takes no arguments and returns a frame, or @code{nil} if no frame could be created. The default value @@ -2860,30 +2958,632 @@ Choosing Window Options @defopt pop-up-frame-alist This variable holds an alist of frame parameters (@pxref{Frame -Parameters}), which is used by the default function in +Parameters}), which is used by the function specified by @code{pop-up-frame-function} to make a new frame. The default is @code{nil}. address@hidden defopt address@hidden same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If a buffer's name is in this list, address@hidden handles the buffer by showing it in the selected -window. +This option is provided for backward compatibility only. Note, +however that when @code{display-buffer-pop-up-frame} calls the +function specified by @code{pop-up-frame-function}, it prepends the +value of all @code{pop-up-frame-parameters} action alist entries to address@hidden so that the values specified by the action +alist entry effectively override the corresponding values of address@hidden + +Hence, users should set up a @code{pop-up-frame-parameters} action +alist entry in @code{display-buffer-alist} instead of customizing address@hidden Only this will guarantee that the value of +a parameter specified by the user overrides the value of that +parameter specified by the caller of @code{display-buffer}. @end defopt address@hidden same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by showing it in the selected window. address@hidden defopt + Many efforts in the design of @code{display-buffer} have been given +to maintain compatibility with code that uses older options like address@hidden, @code{pop-up-frames}, address@hidden, @code{same-window-buffer-names} and address@hidden Applications and users should refrain +from using these options in future code. Above we already warned +against customizing @code{pop-up-frame-alist}. Here we describe how +to convert the remaining options to use display actions instead. + address@hidden @code address@hidden pop-up-windows +This variable is @code{nil} by default. Instead of customizing it to address@hidden and thus telling @code{display-buffer} what not to do, it's +much better to list in @code{display-buffer-base-action} the actions address@hidden should do instead as, for example: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame + display-buffer-in-previous-window display-buffer-use-some-window))) address@hidden group address@hidden example + address@hidden pop-up-frames +Instead of customizing this variable to @code{t}, customize address@hidden, for example, as follows: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) address@hidden group address@hidden example + address@hidden same-window-buffer-names address@hidden same-window-regexps +Instead of adding a buffer name or a regular expression to one of +these options use a @code{display-buffer-alist} entry for that buffer +specifying the action function @code{display-buffer-same-window}. address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + (cons '("\\*foo\\*" (display-buffer-same-window)) display-buffer-alist)) address@hidden group address@hidden example address@hidden table + + address@hidden Precedence of Action Functions address@hidden Precedence of Action Functions + +From the past subsections we already know that @code{display-buffer} +must be supplied with a number of display actions (@pxref{Choosing +Window}) in order to display a buffer. In a completely uncustomized +Emacs, these actions are specified by address@hidden in the following order of +precedence: Reuse a window, pop up a new window on the same frame, use +a window previously showing the buffer, use some window and pop up a +new frame. (The remaining actions in the default value of address@hidden are void in an uncustomized +Emacs). + +Let's now consider the following form: + address@hidden +(display-buffer (get-buffer-create "*foo*")) address@hidden example + address@hidden +Put this form into the buffer @file{*scratch*} of an uncustomized +Emacs session you just started and evaluate it: @code{display-buffer} +will fail to reuse a window showing @file{*foo*} but succeed in +popping up a new window. If you evaluate the form again, nothing will address@hidden reused the window already showing address@hidden because that action was applicable and had the highest +precedence among all applicable actions. + + Popping up a new window will fail if there is not enough space on +the selected frame. In an uncustomized Emacs it typically fails when +there are already two windows on a frame. For example, if you now +type @address@hidden 1}} followed by @address@hidden 2}} and evaluate the form +once more, @file{*foo*} should show up in the lower address@hidden just used ``some'' window. If, before +typing @address@hidden 2}} you had typed @address@hidden o}}, @file{*foo*} +would have been shown in the upper window because ``some'' window +stands for the ``least recently used'' window and the selected window +has been least recently used if and only if it is alone on its frame. + + Let's assume you did not type @address@hidden o}} and @file{*foo*} is +shown in the lower window. Type @address@hidden o}} to get there followed +by @address@hidden left}} and evaluate the form again. This should +display @file{*foo*} in the same, lower window because that window had +already shown @file{*foo*} previously and was therefore chosen instead +of some other window (remember the precedence order prescribed by address@hidden we sketched above). + + So far we have only observed default behaviors in an uncustomized +Emacs session. Next let's see how these behaviors can be customized. +The first option we consider is @code{display-buffer-base-action}. It +provides a very coarse customization which conceptually affects the +display of @emph{any} buffer. It can be used to supplement the +actions supplied by @code{display-buffer-fallback-action} by +reordering them or by adding actions that are not present there but +fit more closely the user's editing practice. It can be, however, +also used to change the default behavior in a more profound way. + + Let's consider a user who, as a rule, prefers to display buffers on +another frame. Such a user might provide the following customization: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) address@hidden group address@hidden example + address@hidden +This setting will address@hidden to first try to find a +window showing the buffer on a visible or iconified frame and, if no +such frame exists, pop up a new frame. You can observe this behavior +on a graphical system by typing @address@hidden 1}} in the window showing address@hidden and evaluating the canonical @code{display-buffer} +form. This will usually create (and give focus to) a new frame whose +root window shows @file{*foo*}. Iconify that frame and evaluate the +canonical form again: @code{display-buffer} will reuse the window on +the new frame (usually raising the frame and giving it focus too). + + Only if creating a new frame fails, @code{display-buffer} will +apply the actions supplied by @code{display-buffer-fallback-action} +which means to again try to reuse a window, pop up a new window and so +on. A trivial way to make frame creation fail is supplied by the +following form: + address@hidden address@hidden +(let ((pop-up-frame-function 'ignore)) + (display-buffer (get-buffer-create "*foo*"))) address@hidden group address@hidden example + address@hidden +We will forget about that form immediately after observing that it +fails to create a new frame and uses a fallback action instead. + + Note that @code{display-buffer-reuse-window} appears redundant in +the customization of @code{display-buffer-base-action} because it is +already part of @code{display-buffer-fallback-action} and should be +tried there anyway. However, that would fail because due to the +precedence of @code{display-buffer-base-action} over address@hidden, at that time address@hidden would have already won the race. +In fact + address@hidden address@hidden +(customize-set-variable + 'display-buffer-base-action + '(display-buffer-pop-up-frame (reusable-frames . 0))) address@hidden group address@hidden example + address@hidden +would cause @code{display-buffer} to @emph{always} pop up a new frame +which is probably not what our user wants. + + So far, we have only shown how @emph{users} can customize the +default behavior of @code{display-buffer}. Let us now see how address@hidden can change the course of @code{display-buffer}. +The canonical way to do that is to use the @var{action} argument of address@hidden or the function that eventually ends up calling +it. + + Suppose an application wants to display @file{*foo*} preferably +below the selected window (to immediately attract the attention of the +user to the new window) or, if that fails, in a window at the bottom +of the frame. It could do that with a call like + address@hidden address@hidden +(display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom))) address@hidden group address@hidden example + address@hidden +In order to see how this new, modified form works, delete any frame +showing @file{*foo*}, type @address@hidden 1}} followed by @address@hidden 2}} in the +window showing @file{*scratch*} and subsequently evaluate that form. address@hidden should split the upper window and show address@hidden in the new window. Alternatively, if after @address@hidden 2}} +you had typed @address@hidden o}}, @code{display-buffer} would have split the +window at the bottom instead. + + Suppose now that, before evaluating the new form, you have made the +selected window as small as possible, for example, by evaluating the +form @code{(fit-window-to-buffer)} in that window. In that case, address@hidden would have failed to split the selected window +and would have split the frame's root window instead, effectively +displaying @file{*foo*} at the bottom of the frame. + + In either case, evaluating the new form a second time now should +reuse the window already showing @file{*foo*} since both functions +supplied by the @var{action} argument try to reuse such a window +first. + + By setting the @var{action} argument, an application effectively +overrules any customization of @code{display-buffer-base-action}. Our +user can now either accept the choice of the application or redouble +by customizing the option @code{display-buffer-alist} as follows: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame)))) address@hidden group address@hidden example + address@hidden +Trying this with the new, modified form above in a configuration that +does not show @file{*foo*} anywhere, will display @file{*foo*} on a +separate frame, completely ignoring the @var{action} argument of address@hidden + + Note that we didn't care to specify a @code{reusable-frames} action +alist entry in our specification of @code{display-buffer-alist}. address@hidden always takes the first one it finds---in our +case the one specified by @code{display-buffer-base-action}. If we +wanted to use a different specification, for example, to exclude +iconified frames showing @file{*foo*} from the list of reusable ones, +we would have to specify that separately, however: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . visible)))) address@hidden group address@hidden example + address@hidden +If you try this, you will notice that repeated attempts to display address@hidden will succeed to reuse a frame only if that frame is +visible. + + The above example would allow the conclusion that users customize address@hidden for the sole purpose to overrule the address@hidden argument chosen by applications. Such a conclusion would +be incorrect. @code{display-buffer-alist} is the standard option for +users to direct the course of display of specific buffers in a +preferred way regardless of whether the display is also guided by an address@hidden argument. + + We can, however, reasonably conclude that customizing address@hidden differs from customizing address@hidden in two major aspects: It is stronger +because it overrides the @var{action} argument of address@hidden And it allows to explicitly specify all +affected buffers. In fact displaying other buffers is not affected in +any way by a customization for @file{*foo*}. For example, + address@hidden +(display-buffer (get-buffer-create "*bar*")) address@hidden example + address@hidden +continues being governed by the settings of address@hidden and address@hidden only. + + We could stop with our examples here but applications still have an +ace up their sleeves which they can use to overrule any customization +of @code{display-buffer-alist}. It's the variable address@hidden which they can bind around address@hidden calls as follows: + address@hidden address@hidden +(let ((display-buffer-overriding-action '((display-buffer-same-window)))) + (display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom)))) address@hidden group address@hidden example + address@hidden +Evaluating this form will usually display @file{*foo*} in the selected +window regardless of the @var{action} argument and any user +customizations. It might be illustrative to look at the list of +action functions @code{display-buffer} would have tried to display address@hidden with the customizations we provided earlier. The list +(including comments explaining who added this and the subsequent +elements) is: + address@hidden address@hidden +(display-buffer-same-window ;; `display-buffer-overriding-action' + display-buffer-reuse-window ;; `display-buffer-alist' + display-buffer-pop-up-frame + display-buffer-below-selected ;; ACTION argument + display-buffer-at-bottom + display-buffer-reuse-window ;; `display-buffer-base-action' + display-buffer-pop-up-frame + display-buffer--maybe-same-window ;; `display-buffer-fallback-action' + display-buffer-reuse-window + display-buffer--maybe-pop-up-frame-or-window + display-buffer-in-previous-window + display-buffer-use-some-window + display-buffer-pop-up-frame) address@hidden group address@hidden example + address@hidden +Among the internal functions listed here address@hidden is effectively ignored while address@hidden actually runs address@hidden + +The action alist passed in each function call is: + address@hidden address@hidden +((reusable-frames . visible) + (reusable-frames . 0)) address@hidden group address@hidden example + address@hidden +which shows that we have used the second specification of address@hidden above. Suppose our user had written that +as + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (inhibit-same-window . t) + (reusable-frames . visible)))) address@hidden group address@hidden example + address@hidden +In this case the @code{inhibit-same-window} alist entry will +successfully invalidate the @code{display-buffer-same-window} +specification from @code{display-buffer-overriding-action} and address@hidden will show @file{*foo*} on another frame. + + This last example shows that while the precedence order of action +functions is fixed as described in @ref{Choosing Window}, an action +alist entry specified by a display action ranked lower in that order +can affect the execution of an higher ranked display action. + + address@hidden The Zen of Buffer Display address@hidden The Zen of Buffer Display + +In its most simplistic form, a frame accommodates always one single +window that can be used for displaying a buffer. As a consequence, it +is always the latest call of @code{display-buffer} that will have +succeeded in placing its buffer there. + + Since working with such a frame is not very practical, Emacs by +default allows for more complex frame layouts controlled by the +default values of the frame size and the @code{split-height-threshold} +and @code{split-width-threshold} options. Displaying a buffer not yet +shown on a frame then either splits the single window on that frame or +(re-)uses one of its two windows. + + The default behavior is abandoned as soon as the user customizes +one of these thresholds or manually changes the frame's layout. The +default behavior is also abandoned when calling @code{display-buffer} +with a address@hidden @var{action} argument or the user customizes one +of the options mentioned in the previous subsections. Mastering address@hidden soon may become a frustrating experience due to +the plethora of applicable display actions and the resulting frame +layouts. + + However, refraining from using buffer display functions and falling +back on a split & delete windows metaphor is not a good idea either. +Buffer display functions give applications and users a framework to +reconcile their different needs; no comparable framework exists for +splitting and deleting windows. They also allow to at least partially +restore the layout of a frame when removing a buffer from it later +(@pxref{Quitting Windows}). + + Below we will give a number of guidelines to redeem the frustration +mentioned above and thus to avoid that buffers literally get lost in +between the windows of a frame. + address@hidden @asis address@hidden Write display actions without stress +Writing display actions can be a pain because one has to lump together +action functions and action alists in one huge list. (Historical +reasons prevented us from having @code{display-buffer} support +separate arguments for these.) It might help to memorize some basic +forms like the ones listed below: + address@hidden +'(nil (inhibit-same-window . t)) address@hidden example + address@hidden +specifies an action alist entry only and no action function. Its sole +purpose is to inhibit a @code{display-buffer-same-window} function +specified elsewhere from showing the buffer in the same window, see +also the last example of the preceding subsection. + address@hidden +'(display-buffer-below-selected) address@hidden example + +on the other hand specifies one action function and an empty action +alist. To combine the effects of the above two specifications one +would write the form + address@hidden +'(display-buffer-below-selected (inhibit-same-window . t)) address@hidden example + +to add another action function one would write + address@hidden address@hidden +'((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t)) address@hidden group address@hidden example + +and to add another alist entry one would write + address@hidden address@hidden +'((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) (window-height . fit-window-to-buffer)) address@hidden group address@hidden example + +That last form can be used as @var{action} argument of address@hidden in the following way: + address@hidden address@hidden +(display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) (window-height . fit-window-to-buffer))) address@hidden group address@hidden example + +In a customization of @code{display-buffer-alist} it would be used as +follows: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) (window-height . fit-window-to-buffer)))) address@hidden group address@hidden example + +To add a customization for a second buffer one would then write: + address@hidden address@hidden +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) (window-height . fit-window-to-buffer)) + ("\\*bar\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . visible)))) address@hidden group address@hidden example + address@hidden Treat each other with respect address@hidden and @code{display-buffer-base-action} are +user options---applications must never set or rebind them. address@hidden, on the other hand, is +reserved for applications---who seldom use that option and if they use +it, then with utmost care. + + Older implementations of @code{display-buffer} frequently caused +users and applications to fight over the settings of user options like address@hidden and @code{pop-up-windows} (@pxref{Choosing Window +Options}). This was one major reason for redesigning address@hidden provide a clear rule dividing what users +and applications should be allowed to do. + + Applications must be prepared that a user's customizations may +cause buffers to get displayed in an unexpected way. They should +never assume in their subsequent behavior, that the buffer has been +shown precisely the way they asked for in the @var{action} argument of address@hidden + + Users should not pose too many and too severe restrictions on how +arbitrary buffers gets displayed. Otherwise, they will risk to lose +the characteristics of showing a buffer for a certain purpose. +Suppose an application has been written to compare different versions +of a buffer in two windows side-by-side. If the customization of address@hidden prescribes that any such buffer should be +always shown in or below the selected window, the application will +have a hard time to set up the desired window configuration via address@hidden + + To specify a preference for showing an arbitrary buffer, users +should customize @code{display-buffer-base-action}. An example of how +users who prefer working with multiple frames would do that was given +in the previous subsection. @code{display-buffer-alist} should be +reserved for displaying specific buffers in a specific way. + address@hidden Consider reusing a window that already shows the buffer +Generally, it's always a good idea for users and application +programmers to be prepared for the case that a window already shows +the buffer in question and to reuse that window. In the preceding +subsection we have shown that failing to do so properly may cause address@hidden to continuously pop up a new frame although a +frame showing that buffer existed already. Only sometimes, it might +be undesirable to reuse a window, for example, when a different +portion of the buffer should be shown in that window. + + Hence, @code{display-buffer-reuse-window} is one action function +that should be used as often as possible, both in @var{action} +arguments and customizations. An @code{inhibit-same-window} entry in +the @var{action} argument usually takes care of the most common case +where reusing a window showing the buffer should be avoided---that +where the window in question is the selected one. + address@hidden Attract focus to the window chosen +This is a no-brainer for people working with multiple frames---the +frame showing the buffer will automatically raise and get focus unless +an @code{inhibit-switch-frame} entry forbids it. For single frame +users this task can be considerably more difficult. In particular, address@hidden and address@hidden can become obtrusive in this +regard. They split or use a seemingly arbitrary (often the largest or +least recently used) window, distracting the user's attention. + +Some applications therefore try to choose a window at the bottom of +the frame, for example, in order to display the buffer in vicinity of +the minibuffer window where the user is expected to answer a question +related to the new window. For non-input related actions address@hidden might be preferable because the +selected window usually already has the user's attention. + address@hidden Handle subsequent invocations of @code{display-buffer} address@hidden is not overly well suited for displaying several +buffers in sequence and making sure that all these buffers are shown +orderly in the resulting window configuration. Again, the standard +action functions @code{display-buffer-pop-up-window} and address@hidden are not very suited for this +purpose due to their somewhat chaotic nature in more complex +configurations. + + To produce a window configuration displaying multiple buffers (or +different views of one and the same buffer) in one and the same +display cycle, application programmers will unavoidably have to write +their own action functions. A few tricks listed below might help in +this regard. + address@hidden @bullet address@hidden +Making windows atomic (@pxref{Atomic Windows}) avoids that an +existing window composition gets broken when popping up a new window. +The new window will pop up outside the composition instead. + address@hidden +Temporarily dedicating windows to their buffers (@pxref{Dedicated +Windows}) avoids that a window gets used for displaying a different +buffer. A non-dedicated window will be used instead. + address@hidden +Calling @code{window-preserve-size} (@pxref{Preserving Window Sizes}) +will try to keep the size of the argument window unchanged when +popping up a new window. You have to make sure that another window in +the same combination can be shrunk instead, though. + address@hidden +Side windows (@pxref{Side Windows}) can be used for displaying +specific buffers always in a window at the same position of a frame. +This permits to group buffers that do not compete for being shown at +the same time on a frame and show any such buffer in the same window +without disrupting the display of other buffers. + address@hidden +Child frames (@pxref{Child Frames}) can be used to display a buffer +within the screen estate of the selected frame without disrupting that +frame's window configuration and without the overhead associated with +full-fledged frames as inflicted by @code{display-buffer-pop-up-frame}. address@hidden itemize address@hidden table address@hidden same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. address@hidden defun @node Window History @section Window History @@ -3204,7 +3904,7 @@ Side Windows In their most simple form of use, side windows allow to display specific buffers always in the same area of a frame. Hence they can be regarded as a generalization of the concept provided by address@hidden (@pxref{Display Action Functions}) to address@hidden (@pxref{Action Functions}) to the remaining sides of a frame. With suitable customizations, however, side windows can be also used to provide frame layouts similar to those found in so-called integrated development environments (IDEs). @@ -3221,8 +3921,8 @@ Side Windows @node Displaying Buffers in Side Windows @subsection Displaying Buffers in Side Windows -The following action function for @code{display-buffer} (@pxref{Display -Action Functions}) creates or reuses a side window for displaying the +The following action function for @code{display-buffer} (@pxref{Action +Functions}) creates or reuses a side window for displaying the specified buffer. @defun display-buffer-in-side-window buffer alist @@ -3264,7 +3964,7 @@ Displaying Buffers in Side Windows By default, side windows cannot be split via @code{split-window} (@pxref{Splitting Windows}). Also, a side window is not reused or split -by any buffer display action (@pxref{Display Action Functions}) unless +by any buffer display action (@pxref{Action Functions}) unless it is explicitly specified as target of that action. Note also that @code{delete-other-windows} cannot make a side window the only window on its frame (@pxref{Deleting Windows}). @@ -3453,9 +4153,9 @@ Frame Layouts with Side Windows @xref{Resizing Windows}. The last form also makes sure that none of the created side windows -are accessible via @kbd{C-x o} by installing the @code{no-other-window} +are accessible via @address@hidden o}} by installing the @code{no-other-window} parameter for each of these windows. In addition, it makes sure that -side windows are not deleted via @kbd{C-x 1} by installing the +side windows are not deleted via @address@hidden 1}} by installing the @code{no-delete-other-windows} parameter for each of these windows. Since @code{dired} buffers have no fixed names, we use a special @@ -3547,7 +4247,7 @@ Atomic Windows To create a new atomic window from an existing live window or to add a new window to an existing atomic window, the following buffer display -action function (@pxref{Display Action Functions}) can be used: +action function (@pxref{Action Functions}) can be used: @defun display-buffer-in-atom-window buffer alist This function tries to display @var{buffer} in a new window that will be @@ -3679,6 +4379,7 @@ Window Point so @code{window-point} will stay behind text inserted there. @end defvar + @node Window Start and End @section The Window Start and End Positions @cindex window start position @@ -3925,6 +4626,7 @@ Window Start and End text line, @var{ypos} is negative. @end defun + @node Textual Scrolling @section Textual Scrolling @cindex textual scrolling @@ -4264,6 +4966,7 @@ Vertical Scrolling presence of large images. @end defvar + @node Horizontal Scrolling @section Horizontal Scrolling @cindex horizontal scrolling @@ -5145,6 +5848,7 @@ Window Parameters versions of Emacs. @end table + @node Window Hooks @section Hooks for Window Scrolling and Changes @cindex hooks for window operations