[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r105910: Document display-buffer and
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r105910: Document display-buffer and other window changes in Lisp manual. |
|
Date: |
Sat, 24 Sep 2011 18:49:32 -0400 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 105910
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2011-09-24 18:49:32 -0400
message:
Document display-buffer and other window changes in Lisp manual.
* doc/lispref/windows.texi (Window History): New node. Move text here
from Buffers and Windows.
(Switching Buffers): Rename from Displaying Buffers, since we
don't document display-buffer here; callers changed. Document
FORCE-SAME-WINDOW arg to switch-to-buffer and
switch-to-buffer-other-frame. Delete duplicate
replace-buffer-in-windows doc.
(Choosing Window): Document display actions.
modified:
doc/lispref/ChangeLog
doc/lispref/buffers.texi
doc/lispref/elisp.texi
doc/lispref/files.texi
doc/lispref/vol1.texi
doc/lispref/vol2.texi
doc/lispref/windows.texi
etc/NEWS
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2011-09-24 14:38:16 +0000
+++ b/doc/lispref/ChangeLog 2011-09-24 22:49:32 +0000
@@ -1,3 +1,14 @@
+2011-09-24 Chong Yidong <address@hidden>
+
+ * windows.texi (Window History): New node. Move text here from
+ Buffers and Windows.
+ (Switching Buffers): Rename from Displaying Buffers, since we
+ don't document display-buffer here; callers changed. Document
+ FORCE-SAME-WINDOW arg to switch-to-buffer and
+ switch-to-buffer-other-frame. Delete duplicate
+ replace-buffer-in-windows doc.
+ (Choosing Window): Document display actions.
+
2011-09-24 Eli Zaretskii <address@hidden>
* display.texi (Forcing Redisplay): Update the description of
=== modified file 'doc/lispref/buffers.texi'
--- a/doc/lispref/buffers.texi 2011-04-08 18:53:26 +0000
+++ b/doc/lispref/buffers.texi 2011-09-24 22:49:32 +0000
@@ -124,7 +124,7 @@
buffer that the cursor is in, when Emacs reads a command, is the
buffer to which that command applies (@pxref{Command Loop}). Thus,
you should not use @code{set-buffer} to switch visibly to a different
-buffer; for that, use the functions described in @ref{Displaying
+buffer; for that, use the functions described in @ref{Switching
Buffers}.
When writing a Lisp function, do @emph{not} rely on this behavior of
@@ -775,13 +775,14 @@
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
- Creating a buffer adds it to the end of the buffer list, and killing a
-buffer removes it from that list. A buffer moves to the front of this
-list whenever it is chosen for display in a window (@pxref{Displaying
-Buffers}) or a window displaying it is selected (@pxref{Selecting
-Windows}). A buffer moves to the end of the list when it is buried (see
address@hidden, below). There are no functions available to the
-Lisp programmer which directly manipulate the buffer list.
+ Creating a buffer adds it to the end of the buffer list, and killing
+a buffer removes it from that list. A buffer moves to the front of
+this list whenever it is chosen for display in a window
+(@pxref{Switching Buffers}) or a window displaying it is selected
+(@pxref{Selecting Windows}). A buffer moves to the end of the list
+when it is buried (see @code{bury-buffer}, below). There are no
+functions available to the Lisp programmer which directly manipulate
+the buffer list.
In addition to the fundamental buffer list just described, Emacs
maintains a local buffer list for each frame, in which the buffers that
@@ -888,24 +889,24 @@
bury will come last in the value of @code{(buffer-list @var{frame})} and
in the value of @code{(buffer-list)}.
-If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
-current buffer. In addition, if the buffer is displayed in the selected
-window, this switches to some other buffer (obtained using
address@hidden) in the selected window. @xref{Displaying Buffers}.
-But if the selected window is dedicated to its buffer, it deletes that
-window if there are other windows left on its frame. Otherwise, if the
-selected window is the only window on its frame, it iconifies that
-frame. If @var{buffer-or-name} is displayed in some other window, it
-remains displayed there.
+If @var{buffer-or-name} is @code{nil} or omitted, this means to bury
+the current buffer. In addition, if the buffer is displayed in the
+selected window, this switches to some other buffer (obtained using
address@hidden) in the selected window. @xref{Switching
+Buffers}. But if the selected window is dedicated to its buffer, it
+deletes that window if there are other windows left on its frame.
+Otherwise, if the selected window is the only window on its frame, it
+iconifies that frame. If @var{buffer-or-name} is displayed in some
+other window, it remains displayed there.
To replace a buffer in all the windows that display it, use
@code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
@end deffn
@deffn Command unbury-buffer
-This command switches to the last buffer in the local buffer list of the
-selected frame. More precisely, it calls the function
address@hidden (@pxref{Displaying Buffers}), to display the
+This command switches to the last buffer in the local buffer list of
+the selected frame. More precisely, it calls the function
address@hidden (@pxref{Switching Buffers}), to display the
buffer returned by @code{last-buffer}, see above, in the selected
window.
@end deffn
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2011-09-23 09:12:53 +0000
+++ b/doc/lispref/elisp.texi 2011-09-24 22:49:32 +0000
@@ -21,7 +21,7 @@
@end ifset
@c per rms and peterb, use 10pt fonts for the main text, mostly to
address@hidden save on paper cost.
address@hidden save on paper cost.
@c Do this inside @tex for now, so current makeinfo does not complain.
@tex
@ifset smallbook
@@ -935,9 +935,9 @@
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-level functions for displaying a buffer
- and choosing a window for it.
+* Switching Buffers:: Higher-level functions for switching to a buffer.
* Choosing Window:: How to choose a window for displaying a buffer.
+* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
* Window Point:: Each window has its own location of point.
=== modified file 'doc/lispref/files.texi'
--- a/doc/lispref/files.texi 2011-08-28 21:15:20 +0000
+++ b/doc/lispref/files.texi 2011-09-24 22:49:32 +0000
@@ -103,7 +103,7 @@
@end smallexample
@noindent
-(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
+(See @code{switch-to-buffer} in @ref{Switching Buffers}.)
If @var{wildcards} is address@hidden, which is always true in an
interactive call, then @code{find-file} expands wildcard characters in
@@ -187,8 +187,9 @@
@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
-does so in a window other than the selected window. It may use another
-existing window or split a window; see @ref{Displaying Buffers}.
+does so in a window other than the selected window. It may use
+another existing window or split a window; see @ref{Switching
+Buffers}.
When this command is called interactively, it prompts for
@var{filename}.
=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi 2011-08-30 15:24:07 +0000
+++ b/doc/lispref/vol1.texi 2011-09-24 22:49:32 +0000
@@ -953,11 +953,11 @@
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-level functions for displaying a buffer
- and choosing a window for it.
+* Switching Buffers:: Higher-level functions for switching to a buffer.
* Choosing Window:: How to choose a window for displaying a buffer.
+* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
- a specific window.
+ a specific window.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi 2011-08-30 15:24:07 +0000
+++ b/doc/lispref/vol2.texi 2011-09-24 22:49:32 +0000
@@ -952,11 +952,11 @@
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-level functions for displaying a buffer
- and choosing a window for it.
+* Switching Buffers:: Higher-level functions for switching to a buffer.
* Choosing Window:: How to choose a window for displaying a buffer.
+* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
- a specific window.
+ a specific window.
* Window Point:: Each window has its own location of point.
* Window Start and End:: Buffer positions indicating which text is
on-screen in a window.
=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi 2011-09-23 09:12:53 +0000
+++ b/doc/lispref/windows.texi 2011-09-24 22:49:32 +0000
@@ -22,9 +22,9 @@
* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-level functions for displaying a buffer
- and choosing a window for it.
+* Switching Buffers:: Higher-level functions for switching to a buffer.
* Choosing Window:: How to choose a window for displaying a buffer.
+* Window History:: Each window remembers the buffers displayed in it.
* Dedicated Windows:: How to avoid displaying another buffer in
a specific window.
* Window Point:: Each window has its own location of point.
@@ -1963,7 +1963,6 @@
@code{next-window} for details.
@end defun
-
@node Buffers and Windows
@section Buffers and Windows
@cindex examining windows
@@ -1982,10 +1981,11 @@
The basic, low-level function to associate a window with a buffer is
@code{set-window-buffer}. Higher-level functions like
address@hidden try to obey a number of user customizations
-regulating which windows are supposed to display which buffers. When
-writing an application, programmers should therefore carefully evaluate
-whether they really need the power of @code{set-window-buffer}.
address@hidden and @code{display-buffer} try to obey a number
+of user customizations regulating which windows are supposed to
+display which buffers. @xref{Switching Buffers}. When writing an
+application, you should avoid using @code{set-window-buffer} unless
+you are sure you need it.
@defun set-window-buffer window buffer-or-name &optional keep-margins
This function makes @var{window} display @var{buffer-or-name} and
@@ -2067,310 +2067,208 @@
like the optional arguments of @code{get-buffer-window}.
@end defun
-The following command removes a buffer from all windows showing it.
-
@deffn Command replace-buffer-in-windows &optional buffer-or-name
-This function replaces @var{buffer-or-name} in all windows displaying it
-with some other buffer. It uses @code{switch-to-prev-buffer}, see
-below, to choose that other buffer which is usually the last buffer
-displayed before @var{buffer-or-name} in the respective window.
+This command replaces @var{buffer-or-name} with some other buffer, in
+all windows displaying it. For each such window, it choose another
+buffer using @code{switch-to-prev-buffer} (@pxref{Window History}).
-The argument @var{buffer-or-name} may be a buffer or the name of an
-existing buffer and defaults to the current buffer.
address@hidden may be a buffer, or the name of an existing
+buffer; it defaults to the current buffer.
If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}) has never displayed any other buffers and is
-not the only window on its frame, that window is deleted. If that
-window is the only window on its frame and there are other frames left,
-the window's frame is deleted too. If there are no other frames left,
-some other buffer is displayed in that window as explained above. You
-can prevent the deletion of windows and/or frames by customizing the
-option @var{window-auto-delete}.
-
-This function returns @code{nil}.
address@hidden deffn
-
- When @code{replace-buffer-in-windows} has to show another buffer in a
-window, it tries to pick the buffer shown there before. For this
-purpose each window remembers the buffers it has displayed earlier and
-the order in which these buffers have been removed from it.
-
-The list of @dfn{previous buffers} of a window is an association list
-where each entry specifies a buffer, the last start position of that
-buffer in the window (@pxref{Window Start and End}) and the last
-position of that buffer's point in the window (@pxref{Window Point}).
-This list is ordered by the times of the removal of the respective
-buffers from the window. In particular, the first element of the list
-references the buffer removed most recently. The function
address@hidden pushes an entry for the old buffer of its
-window argument on that list before it shows its buffer argument in the
-window.
-
-The list of @dfn{next buffers} of a window is a list of buffers that
-have been recently re-shown by the function @code{switch-to-prev-buffer}
-and is used to avoid that that function switches to such a buffer again
-before showing other interesting buffers.
-
-The lists of previous and next buffers and the global buffer list
-(@pxref{The Buffer List}) allow to effectively display all buffers in a
-window while giving preference to the buffers previously shown in that
-window. The commands used for this purpose are
address@hidden and @code{switch-to-next-buffer} described
-below.
-
-The following functions directly operate on the lists of previous and
-next buffers.
-
address@hidden window-prev-buffers &optional window
-This function returns an alist specifying the buffers previously shown
-in @var{window} together with their window start and point positions.
-The argument @var{window} must be a live window and defaults to the
-selected one.
address@hidden defun
-
address@hidden set-window-prev-buffers window prev-buffers
-This function sets @var{window}'s previous buffers to the value of
address@hidden The argument @var{window} must be a live window and
-defaults to the selected one. This function returns
address@hidden
-
-If address@hidden, @var{prev-buffers} must specify an alist of triples
-specifying a buffer and two markers for that buffer's start and point
-position in @var{window}.
address@hidden defun
-
address@hidden window-next-buffers &optional window
-This function returns the list of buffers recently re-shown in
address@hidden The argument @var{window} must be a live window and
-defaults to the selected one.
address@hidden defun
-
address@hidden set-window-next-buffers window next-buffers
-This function sets @var{window}'s next buffers to @var{next-buffers}.
address@hidden must be a live window and defaults to the selected one.
-This fucntion returns @var{next-buffers}.
-
-If address@hidden, the argument @var{next-buffers} should specify a list
-of buffers that shall be preferably not shown by the command
address@hidden, see below.
address@hidden defun
-
-The following command is used by @code{replace-buffer-in-windows},
address@hidden and @code{quit-window} to show another buffer in a
-window. It can be also used interactively to cycle through the list of
-all buffers in a window, preferably showing the buffers recently shown
-(but not buried or killed) in that window.
-
address@hidden Command switch-to-prev-buffer &optional window bury-or-kill
-This function displays the previous buffer in @var{window}. The
-argument @var{window} must be a live window and defaults to the selected
-one. If the optional argument @var{bury-or-kill} is address@hidden,
-this means that the buffer currently shown in @var{window} is about to
-be buried or killed and consequently shall not be switched to in future
-invocations of this command.
-
-The previous buffer is usually the buffer shown before the buffer
-currently shown in @var{window}. However, a buffer that has been buried
-or killed or has been already shown by a recent invocation of
address@hidden does not qualify as previous buffer.
-
-If repeated invocations of this command have already shown all buffers
-previously shown in @var{window}, further invocations will show buffers
-from the global buffer list starting with the buffer returned by
address@hidden (@pxref{The Buffer List}).
address@hidden deffn
-
-The following command can be used to undo the effect of the last undone
address@hidden command.
-
address@hidden Command switch-to-next-buffer &optional window
-This functions switches to the next buffer in @var{window} thus undoing
-the effect of the last @code{switch-to-prev-buffer} command in
address@hidden The argument @var{window} must be a live window and
-defaults to the selected one.
-
-If there is no recent invocation of a @code{switch-to-prev-buffer} that
-can be undone, @code{switch-to-next-buffer} will try to show the first
-buffer from the global buffer list as returned by @code{other-buffer}
-(@pxref{The Buffer List}).
address@hidden deffn
-
- Together, @code{switch-to-prev-buffer} and
address@hidden permit to navigate the global buffer list
-much like @code{bury-buffer} and @code{unbury-buffer}. In contrast with
-the latter, however, they may show a buffer even if it is already shown
-in another window. Moreover, they try to restore the window specific
-start and point positions of buffers which should handle viewing one and
-the same buffer in multiple windows more easily.
-
-
address@hidden Displaying Buffers
address@hidden Displaying Buffers in Windows
+(@pxref{Dedicated Windows}) has never displayed any other buffers and
+is not the only window on its frame, that window is deleted. If that
+window is the only window on its frame and there are other frames on
+the frame's terminal, that frame is deleted too; otherwise, some other
+buffer is displayed in that window, as explained above. A user can
+prevent the deletion of windows and/or frames by customizing the
+option @code{window-auto-delete}.
address@hidden deffn
+
address@hidden Switching Buffers
address@hidden Switching to a Buffer in a Window
@cindex switching to a buffer
@cindex displaying a buffer
- In this section we describe convenient functions that choose a window
-automatically and use it to display a specified buffer. These functions
-can also split an existing window in certain circumstances. We also
-describe variables that parameterize the heuristics used for choosing a
-window.
address@hidden
-See the preceding section for
address@hidden iftex
address@hidden
address@hidden and Windows}, for
address@hidden ifnottex
-low-level primitives that give you more precise control. All of these
-functions work by calling @code{set-window-buffer}.
-
- Do not use the functions in this section in order to make a buffer
-current so that a Lisp program can access or modify it; they are too
-drastic for that purpose, since they change the display of buffers in
-windows, which would be gratuitous and surprise the user. Instead, use
address@hidden and @code{save-current-buffer} (@pxref{Current
-Buffer}), which designate buffers as current for programmed access
-without affecting the display of buffers in windows.
-
address@hidden Command switch-to-buffer buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer, and also
-displays the buffer in the selected window. This means that a human can
-see the buffer and subsequent keyboard commands will apply to it.
-Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window;
-see @ref{Current Buffer}.
-
-If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
-buffer using @code{other-buffer}. If @var{buffer-or-name} is a string
-that does not identify an existing buffer, then a new buffer by that
-name is created. The major mode for the new buffer is set according to
-the variable @code{major-mode}; see @ref{Auto Major Mode}.
-
-When the selected window is the minibuffer window or is strongly
-dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
address@hidden (see below) to display the buffer in some other
-window.
-
-Normally the specified buffer is put at the front of the buffer list
-(both the selected frame's buffer list and the frame-independent buffer
-list). This affects the operation of @code{other-buffer}. However, if
address@hidden is address@hidden, this is not done. @xref{The Buffer
-List}.
-
-The @code{switch-to-buffer} function is often used interactively, as
-the binding of @kbd{C-x b}. It is also used frequently in programs. It
-returns the buffer that it switched to.
+ This section describes high-level functions for switching to a
+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
address@hidden, @code{save-current-buffer}, or
address@hidden (@pxref{Current Buffer}).
+
address@hidden Command switch-to-buffer buffer-or-name &optional norecord
force-same-window
+This function displays @var{buffer-or-name} in the selected window,
+and makes it the current buffer. (In contrast, @code{set-buffer}
+makes the buffer current but does not display it; @pxref{Current
+Buffer}). It is often used interactively (as the binding of @kbd{C-x
+b}), as well as in Lisp programs. The return value is the buffer
+switched to.
+
+If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
+returned by @code{other-buffer} (@pxref{The Buffer List}). If
address@hidden is a string that is not the name of any existing
+buffer, this function creates a new buffer with that name; the new
+buffer's major mode is determined by the variable @code{major-mode}
+(@pxref{Major Modes}).
+
+Normally the specified buffer is put at the front of the buffer
+list---both the global buffer list and the selected frame's buffer
+list (@pxref{The Buffer List}). However, this is not done if the
+optional argument @var{norecord} is address@hidden
+
+If this function is unable to display in the seleted window---usually
+because the selected window is a minibuffer window or is strongly
+dedicated to its buffer (@pxref{Dedicated Windows})---then it normally
+tries to display in some other window, in the manner of
address@hidden (see below). However, if the optional argument
address@hidden is address@hidden, it signals an error
+instead.
@end deffn
The next two functions are similar to @code{switch-to-buffer}, except
for the described features.
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes the buffer specified by @var{buffer-or-name} current
-and displays it in a window not currently selected, using the function
+This function makes the buffer specified by @var{buffer-or-name}
+current and displays it in some window other than the selected window.
+It uses the function @code{pop-to-buffer} internally (see below).
+
+If the selected window already displays the specified buffer, it
+continues to do so, but another window is nonetheless found to display
+it as well.
+
+The @var{buffer-or-name} and @var{norecord} arguments have the same
+meanings as in @code{switch-to-buffer}.
address@hidden deffn
+
address@hidden Command switch-to-buffer-other-frame buffer-or-name &optional
norecord
+This function makes the buffer specified by @var{buffer-or-name}
+current and displays it, usually in a new frame. It uses the function
@code{pop-to-buffer} (see below).
-The currently selected window is absolutely never used to do the job.
-If the selected window already displays @var{buffer-or-name}, then it
-continues to do so, but another window is nonetheless found to display
-it in as well.
+If the specified buffer is already displayed in another window, in any
+frame on the current terminal, this switches to that window instead of
+creating a new frame. However, the selected window is never used for
+this.
-This function updates the buffer list just like @code{switch-to-buffer}
-unless @var{norecord} is address@hidden
+The @var{buffer-or-name} and @var{norecord} arguments have the same
+meanings as in @code{switch-to-buffer}.
@end deffn
address@hidden pop-to-buffer buffer-or-name &optional other-window norecord
-This function makes @var{buffer-or-name} the current buffer and switches
-to it in some window, preferably not the window previously selected.
-The ``popped-to'' window becomes the selected window. Its frame is
-given the X server's focus, if possible; see @ref{Input Focus}. The
-return value is the buffer that was switched to.
-
-If @var{buffer-or-name} is @code{nil}, that means to choose some other
-buffer, but you don't specify which. If @var{buffer-or-name} is a
-string that does not name an existing buffer, a buffer by that name is
-created. The major mode for the new buffer is set according to the
-variable @code{major-mode}. @xref{Auto Major Mode}.
-
-If either of the variables @code{display-buffer-reuse-frames} or
address@hidden is address@hidden, @code{pop-to-buffer} looks for a
-window in any visible frame already displaying the buffer; if there is
-one, it selects and returns that window. If no such window exists and
address@hidden is address@hidden, it creates a new frame and
-displays the buffer in it. Otherwise, @code{pop-to-buffer} operates
-entirely within the selected frame. (If the selected frame has just a
-minibuffer, @code{pop-to-buffer} operates within the most recently
-selected frame that was not just a minibuffer.)
-
-If the variable @code{pop-up-windows} is address@hidden, windows may be
-split to create a new window that is different from the original window.
-For details, see @ref{Choosing Window}.
-
-If @var{other-window} is address@hidden, @code{pop-to-buffer} finds or
-creates another window even if @var{buffer-or-name} is already visible
-in the selected window. Thus @var{buffer-or-name} could end up
-displayed in two windows. On the other hand, if @var{buffer-or-name} is
-already displayed in the selected window and @var{other-window} is
address@hidden, then the selected window is considered sufficient for
-displaying @var{buffer-or-name}, so that nothing needs to be done.
-
-All the variables that affect @code{display-buffer} affect
address@hidden as well. @xref{Choosing Window}.
-
-This function updates the buffer list just like @code{switch-to-buffer}
+The above commands use @code{pop-to-buffer}, which is the function
+used by Lisp programs to flexibly display a buffer in some window and
+select that window for editing:
+
address@hidden pop-to-buffer buffer-or-name &optional action norecord
+This function makes @var{buffer-or-name} the current buffer and
+displays it in some window, preferably not the window previously
+selected. It then selects the displaying window. If that window is
+on a different graphical frame, that frame is given input focus if
+possible (@pxref{Input Focus}). The return value is the buffer that
+was switched to.
+
+This function uses @code{display-buffer} to display the buffer, so all
+the variables affecting @code{display-buffer} will affect it as well.
address@hidden Window}.
+
+If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
+returned by @code{other-buffer} (@pxref{The Buffer List}). If
address@hidden is a string that is not the name of any existing
+buffer, this function creates a new buffer with that name; the new
+buffer's major mode is determined by the variable @code{major-mode}
+(@pxref{Major Modes}).
+
+If @var{action} is address@hidden, it should be a display action to
+pass to @code{display-buffer} (@pxref{Choosing Window}).
+Alternatively, a address@hidden, non-list value means to pop to a
+window other than the selected one---even if the buffer is already
+displayed in the selected window.
+
+Like @code{switch-to-buffer}, this function updates the buffer list
unless @var{norecord} is address@hidden
@end defun
address@hidden Command replace-buffer-in-windows &optional buffer-or-name
-This function replaces @var{buffer-or-name} in all windows displaying
-it with some other buffer. It uses @code{other-buffer} to choose the
-other buffer. In the usual applications of this function, you
-don't care which other buffer is used; you just want to make sure that
address@hidden is no longer displayed.
-
-The argument @var{buffer-or-name} may be a buffer or the name of an
-existing buffer and defaults to the current buffer.
-
-If a window displaying @var{buffer-or-name} is dedicated
-(@pxref{Dedicated Windows}), and is not the only window on its frame,
-that window is deleted. If that window is the only window on its frame
-and there are other frames left, the window's frame is deleted too. If
-there are no other frames left, some other buffer is displayed in that
-window.
-
-This function returns @code{nil}.
address@hidden deffn
-
@node Choosing Window
@section Choosing a Window for Display
- This section describes the basic facility that chooses a window to
-display a buffer address@hidden Higher-level functions and
-commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this
-subroutine. Here we describe how to use @code{display-buffer} and how
-to customize it.
-
address@hidden Command display-buffer buffer-or-name &optional not-this-window
frame
-This command makes @var{buffer-or-name} appear in some window, but it
-does not select that window and does not make the buffer specified by
address@hidden current. The identity of the selected window is
-unaltered by this function. The argument @var{buffer-or-name} must be a
-buffer or the name of an existing buffer.
-
address@hidden address@hidden means to display the specified
-buffer in a window other than the selected one, even if it is already
-displayed in the selected window. This can cause the buffer to appear
-in two windows at once. Otherwise, if @var{buffer-or-name} is already
-being displayed in any window, that is good enough, so this function
-does nothing.
-
address@hidden returns the window chosen to display
address@hidden
-
-If the optional argument @var{frame} is address@hidden, it 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}:
+ 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 o}. It is also
+used as a subroutine by many functions and commands, including
address@hidden and @code{pop-to-buffer} (@pxref{Switching
+Buffers}).
+
address@hidden display action
+ 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}.
+
+ 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}.
+
+ @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
+value.
+
address@hidden Command display-buffer buffer-or-name &optional action frame
+This command makes @var{buffer-or-name} appear in some window, without
+selecting the window or making the buffer current. The argument
address@hidden must be a buffer or the name of an existing
+buffer. The return value is the window chosen to display the buffer.
+
+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):
+
address@hidden
address@hidden
+The variable @code{display-buffer-overriding-action}.
+
address@hidden
+The user option @code{display-buffer-alist}.
+
address@hidden
+The @var{action} argument.
+
address@hidden
+The user option @code{display-buffer-base-action}.
+
address@hidden
+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.
address@hidden itemize
+
address@hidden
+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 non-nil.
+
+The argument @var{action} can also have a address@hidden, non-list
+value. This has the special meaning that the buffer should be
+displayed in a window other than the selected one, even if the
+selected window is already displaying it. If called interactively
+with a prefix argument, @var{action} is @code{t}.
+
+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}:
@itemize @bullet
@item
@@ -2652,6 +2550,100 @@
resort, it will try to display @var{buffer-or-name} on a separate frame.
In that case, the value of @code{pop-up-frames} is disregarded.
address@hidden Window History
address@hidden Window History
address@hidden window history
+
+ Each window remembers the buffers it has displayed earlier and the
+order in which these buffers have been removed from it. This history
+is used, for example, by @code{replace-buffer-in-windows}
+(@pxref{Buffers and Windows}). This list is set automatically
+maintained by Emacs, but you can use the following functions to
+explicitly inspect or alter it:
+
address@hidden window-prev-buffers &optional window
+This function returns a list specifying the previous contents of
address@hidden, which should be a live window and defaults to the
+selected window.
+
+Each list element has the form @code{(@var{buffer} @var{window-start}
address@hidden)}, where @var{buffer} is a buffer previously shown in
+the window, @var{window-start} is the window start position when that
+buffer was last shown, and @var{window-pos} is the point position when
+that buffer was last shown.
+
+The list is ordered so that earlier elements correspond to more
+recently-shown buffers, and the first element corresponds to the
+buffer most recently removed from the window.
address@hidden defun
+
address@hidden set-window-prev-buffers window prev-buffers
+This function sets @var{window}'s previous buffers to the value of
address@hidden The argument @var{window} must be a live window
+and defaults to the selected one. The argument @var{prev-buffers}
+should be a list of the same form as that returned by
address@hidden
address@hidden defun
+
+In addition, each buffer maintains a list of @dfn{next buffers}, which
+is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
+below). This list is mainly used by @code{switch-to-prev-buffer} and
address@hidden for choosing buffers to switch to.
+
address@hidden window-next-buffers &optional window
+This function returns the list of buffers recently re-shown in
address@hidden via @code{switch-to-prev-buffer}. @var{window} should be
+a live window or @code{nil} (meaning the selected window).
address@hidden defun
+
address@hidden set-window-next-buffers window next-buffers
+This function sets the next buffer list of @var{window} to
address@hidden The @var{window} argument should be a live window
+or @code{nil} (meaning the selected window). The argument
address@hidden should be a list of buffers.
address@hidden defun
+
+The following commands can be used to cycle through the global buffer
+list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
+they cycle according to the specified window's history list, rather
+than the global buffer list. In addition, they restore
+window-specific window start and point positions, and may show a
+buffer even if it is already shown in another window. The
address@hidden command, in particular, is used by
address@hidden, @code{bury-buffer} and
address@hidden to find a replacement buffer for a window.
+
address@hidden Command switch-to-prev-buffer &optional window bury-or-kill
+This command displays the previous buffer in @var{window}. The
+argument @var{window} should be a live window or @code{nil} (meaning
+the selected window). If the optional argument @var{bury-or-kill} is
address@hidden, this means that the buffer currently shown in
address@hidden is about to be buried or killed and consequently shall
+not be switched to in future invocations of this command.
+
+The previous buffer is usually the buffer shown before the buffer
+currently shown in @var{window}. However, a buffer that has been buried
+or killed or has been already shown by a recent invocation of
address@hidden does not qualify as previous buffer.
+
+If repeated invocations of this command have already shown all buffers
+previously shown in @var{window}, further invocations will show buffers
+from the global buffer list starting with the buffer returned by
address@hidden (@pxref{The Buffer List}).
address@hidden deffn
+
address@hidden Command switch-to-next-buffer &optional window
+This command switches to the next buffer in @var{window} thus undoing
+the effect of the last @code{switch-to-prev-buffer} command in
address@hidden The argument @var{window} must be a live window and
+defaults to the selected one.
+
+If there is no recent invocation of a @code{switch-to-prev-buffer}
+that can be undone, this function tries to show the first buffer from
+the global buffer list as returned by @code{other-buffer} (@pxref{The
+Buffer List}).
address@hidden deffn
+
@node Dedicated Windows
@section Dedicated Windows
@cindex dedicated window
@@ -2666,15 +2658,15 @@
(@pxref{Buffers and Windows}) with respect to dedicated windows is
slightly different, see below.
-When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete
-a dedicated window and that window is the only window on its frame, it
-deletes the window's frame too, provided there are other frames left.
address@hidden (@pxref{Displaying Buffers}) tries to
-delete all dedicated windows showing its buffer argument. When such a
-window is the only window on its frame, that frame is deleted, provided
-there are other frames left. If there are no more frames left, some
-other buffer is displayed in the window, and the window is marked as
-non-dedicated.
+When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to
+delete a dedicated window and that window is the only window on its
+frame, it deletes the window's frame too, provided there are other
+frames left. @code{replace-buffer-in-windows} (@pxref{Switching
+Buffers}) tries to delete all dedicated windows showing its buffer
+argument. When such a window is the only window on its frame, that
+frame is deleted, provided there are other frames left. If there are
+no more frames left, some other buffer is displayed in the window, and
+the window is marked as non-dedicated.
When you kill a buffer (@pxref{Killing Buffers}) displayed in a
dedicated window, any such window usually gets deleted too, since
=== modified file 'etc/NEWS'
--- a/etc/NEWS 2011-09-24 18:19:20 +0000
+++ b/etc/NEWS 2011-09-24 22:49:32 +0000
@@ -1070,6 +1070,7 @@
positions. This also means that the same buffer may be automatically
shown twice even if it already appears in another window.
++++
*** `switch-to-buffer' has a new optional argument FORCE-SAME-WINDOW,
which if non-nil requires the buffer to be displayed in the currently
selected window, signaling an error otherwise. If nil, another window
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r105910: Document display-buffer and other window changes in Lisp manual.,
Chong Yidong <=