[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r105915: Document display-buffer-alis
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r105915: Document display-buffer-alist and related variables in Lisp manual. |
Date: |
Sat, 24 Sep 2011 23:32:51 -0400 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 105915
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-09-24 23:32:51 -0400
message:
Document display-buffer-alist and related variables in Lisp manual.
* doc/lispref/windows.texi (Display Action Functions)
(Choosing Window Options): New nodes.
modified:
doc/lispref/ChangeLog
doc/lispref/elisp.texi
doc/lispref/vol1.texi
doc/lispref/vol2.texi
doc/lispref/windows.texi
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2011-09-24 22:49:32 +0000
+++ b/doc/lispref/ChangeLog 2011-09-25 03:32:51 +0000
@@ -1,3 +1,8 @@
+2011-09-25 Chong Yidong <address@hidden>
+
+ * windows.texi (Display Action Functions)
+ (Choosing Window Options): New nodes.
+
2011-09-24 Chong Yidong <address@hidden>
* windows.texi (Window History): New node. Move text here from
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2011-09-24 22:49:32 +0000
+++ b/doc/lispref/elisp.texi 2011-09-25 03:32:51 +0000
@@ -937,6 +937,8 @@
* 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.
=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi 2011-09-24 22:49:32 +0000
+++ b/doc/lispref/vol1.texi 2011-09-25 03:32:51 +0000
@@ -955,6 +955,8 @@
* 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.
=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi 2011-09-24 22:49:32 +0000
+++ b/doc/lispref/vol2.texi 2011-09-25 03:32:51 +0000
@@ -954,6 +954,8 @@
* 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.
=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi 2011-09-24 22:49:32 +0000
+++ b/doc/lispref/windows.texi 2011-09-25 03:32:51 +0000
@@ -24,6 +24,8 @@
* 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 @@
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
address@hidden (@pxref{Current Buffer}).
address@hidden @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 @@
Buffers}).
@cindex display action
address@hidden action function, for display-buffer
address@hidden 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
address@hidden alists}.
+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 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}.
+ 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}.
address@hidden 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 address@hidden
+several sources, and calling the action functions in turn, until one
+of them manages to display the buffer and returns a address@hidden
value.
@deffn Command display-buffer buffer-or-name &optional action frame
@@ -2248,9 +2252,7 @@
The user option @code{display-buffer-base-action}.
@item
-The variable @code{display-buffer-fallback-action}. This is
address@hidden 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 @@
The optional argument @var{frame}, if address@hidden, 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}.
address@hidden deffn
+
address@hidden 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)}.
address@hidden defvar
+
address@hidden 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
address@hidden matches a regular expression in this alist, then
address@hidden uses the corresponding display action.
address@hidden defopt
+
address@hidden 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
address@hidden
address@hidden defopt
+
address@hidden Constant display-buffer-fallback-action
+This display action specifies the fallback behavior for
address@hidden if no other display actions are given.
address@hidden defvr
+
address@hidden Display Action Functions
address@hidden 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.
+
address@hidden 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
address@hidden has a non-nil @code{inhibit-same-window} entry.
address@hidden defun
+
address@hidden 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 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:
@itemize @bullet
@item
@@ -2284,9 +2336,36 @@
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.
address@hidden 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
address@hidden is address@hidden, it searches all frames on the
+current terminal. @xref{Choosing Window Options}.
address@hidden defun
+
address@hidden display-buffer-pop-up-frame buffer alist
+This function creates a new frame, and displays the buffer in that
+frame's window.
address@hidden defun
+
address@hidden 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}).
address@hidden defun
+
address@hidden 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}).
address@hidden defun
+
address@hidden Choosing Window Options
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
+options.
@defopt display-buffer-reuse-frames
If this variable is address@hidden, @code{display-buffer} searches
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r105915: Document display-buffer-alist and related variables in Lisp manual.,
Chong Yidong <=