From 9ec20d36df3a144ca383b8dd3574b13e479b51bb Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 24 Sep 2011 23:32:51 -0400 Subject: Document display-buffer-alist and related variables in Lisp manual. * doc/lispref/windows.texi (Display Action Functions) (Choosing Window Options): New nodes. --- doc/lispref/ChangeLog | 5 ++ doc/lispref/elisp.texi | 2 + doc/lispref/vol1.texi | 2 + doc/lispref/vol2.texi | 2 + doc/lispref/windows.texi | 129 ++++++++++++++++++++++++++++++++++++++--------- 5 files changed, 115 insertions(+), 25 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index a0d069ef922..c99d5658950 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2011-09-25 Chong Yidong + + * windows.texi (Display Action Functions) + (Choosing Window Options): New nodes. + 2011-09-24 Chong Yidong * windows.texi (Window History): New node. Move text here from diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 5934f452c52..45eaeb85ad8 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -937,6 +937,8 @@ 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. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 0abca1ec502..0fa23d6412c 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -955,6 +955,8 @@ 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. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index f9ec9200d21..2469a742900 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -954,6 +954,8 @@ 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. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f455a7d4e02..6565a014415 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -24,6 +24,8 @@ is displayed in 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. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. @@ -2094,11 +2096,12 @@ option @code{window-auto-delete}. specified buffer in some window. Do @emph{not} use these functions to make a buffer temporarily -current so that a Lisp program can access or modify it; they have -side-effects that may surprise the user, such as changing window -histories (@pxref{Window History}). Instead, use +current just so a Lisp program can access or modify it. They have +side-effects, such as changing window histories (@pxref{Window +History}), which will surprise the user if used that way. If you want +to make a buffer current to modify it in Lisp, use @code{with-current-buffer}, @code{save-current-buffer}, or -@code{set-buffer} (@pxref{Current Buffer}). +@code{set-buffer}. @xref{Current Buffer}. @deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window This function displays @var{buffer-or-name} in the selected window, @@ -2203,24 +2206,25 @@ used as a subroutine by many functions and commands, including Buffers}). @cindex display action +@cindex action function, for display-buffer +@cindex action alist, for display-buffer This command performs several complex steps to find a window to display in. These steps are described by means of @dfn{display actions}, which have the form @code{(@var{function} . @var{alist})}. Here, @var{function} is either a function or a list of functions, -while @var{alist} is an association list. In this section, we will -refer to such functions as @dfn{action functions}, and such alists as -@dfn{action alists}. - - An action function should accept two arguments: the buffer to -display and an action alist. It should attempt to display the buffer -in some window, picking or creating a window based on some internal -criteria (as well as, optionally, the action alist). If successful, -it should return the window; otherwise, it should return @code{nil}. +which we refer to as @dfn{action functions}; @var{alist} is an +association list, which we refer to as @dfn{action alists}. + + An action function accepts two arguments: the buffer to display and +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}. +@xref{Display Action Functions}, for a list of predefined action +functions. @code{display-buffer} works by combining display actions from -several sources (including some user-customizable options), and -calling the action functions in turn, until one of the action -functions manages to display the buffer and returns a non-@code{nil} +several sources, and calling the action functions in turn, until one +of them manages to display the buffer and returns a non-@code{nil} value. @deffn Command display-buffer buffer-or-name &optional action frame @@ -2248,9 +2252,7 @@ The @var{action} argument. The user option @code{display-buffer-base-action}. @item -The variable @code{display-buffer-fallback-action}. This is -non-@code{nil} by default, and specifies the fallback behavior if no -other display actions are given. +The constant @code{display-buffer-fallback-action}. @end itemize @noindent @@ -2266,9 +2268,59 @@ with a prefix argument, @var{action} is @code{t}. The optional argument @var{frame}, if non-@code{nil}, specifies which frames to check when deciding whether the buffer is already displayed. -If the buffer is already displayed in some window on one of these -frames, @code{display-buffer} simply returns that window. Here are -the possible values of @var{frame}: +It is equivalent to adding an element @code{(reusable-frames +. @var{frame})} to the action alist of @var{action}. @xref{Display +Action Functions}. +@end deffn + +@defvar display-buffer-overriding-action +The value of this variable should be a display action, which is +treated with the highest priority by @code{display-buffer}. The +default value is empty, i.e. @code{(nil . nil)}. +@end defvar + +@defopt display-buffer-alist +The value of this option is an alist mapping regular expressions to +display actions. If the name of the buffer passed to +@code{display-buffer} matches a regular expression in this alist, then +@code{display-buffer} uses the corresponding display action. +@end defopt + +@defopt display-buffer-base-action +The value of this option should be a display action. This option can +be used to define a ``standard'' display action for calls to +@code{display-buffer}. +@end defopt + +@defvr Constant display-buffer-fallback-action +This display action specifies the fallback behavior for +@code{display-buffer} if no other display actions are given. +@end defvr + +@node Display Action Functions +@section Action Functions for @code{display-buffer} + +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. + +@defun display-buffer-same-window buffer alist +This function tries to display @var{buffer} in the selected window. +It fails if the selected window is a minibuffer window or is dedicated +to another buffer (@pxref{Dedicated Windows}). It also fails if +@var{alist} has a non-nil @code{inhibit-same-window} entry. +@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. + +If @var{alist} has a non-@code{nil} @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: @itemize @bullet @item @@ -2284,9 +2336,36 @@ the possible values of @var{frame}: A frame means consider windows on that frame only. @end itemize -Precisely how @code{display-buffer} finds or creates a window depends on -the variables described below. -@end deffn +If @var{alist} contains no @code{reusable-frames} entry, this function +normally searches just the selected frame; however, if either the +variable @code{display-buffer-reuse-frames} or the variable +@code{pop-up-frames} is non-@code{nil}, it searches all frames on the +current terminal. @xref{Choosing Window Options}. +@end defun + +@defun display-buffer-pop-up-frame buffer alist +This function creates a new frame, and displays the buffer in that +frame's window. +@end defun + +@defun display-buffer-pop-up-window buffer alist +This function tries to display @var{buffer} by splitting the selected +window. It uses @code{split-window-sensibly} as a subroutine +(@pxref{Choosing Window Options}). +@end defun + +@defun display-buffer-use-some-window buffer alist +This function tries to display @var{buffer} by choosing an existing +buffer and displaying the buffer in that window. It can fail if all +windows are dedicated to another buffer (@pxref{Dedicated Windows}). +@end defun + +@node Choosing Window Options +@section 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 +options. @defopt display-buffer-reuse-frames If this variable is non-@code{nil}, @code{display-buffer} searches -- cgit v1.2.3