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.
This commit is contained in:
Chong Yidong
parent
3f2b07f8b2
commit
0e406a72ed
8 changed files with 318 additions and 312 deletions
|
|
@ -1,3 +1,14 @@
|
|||
2011-09-24 Chong Yidong <cyd@stupidchicken.com>
|
||||
|
||||
* 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 <eliz@gnu.org>
|
||||
|
||||
* display.texi (Forcing Redisplay): Update the description of
|
||||
|
|
|
|||
|
|
@ -124,7 +124,7 @@ selected window. This is to prevent confusion: it ensures that the
|
|||
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 @@ been displayed in a window. Several functions, notably
|
|||
@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
|
||||
@code{bury-buffer}, 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 @@ as well as the fundamental buffer list; therefore, the buffer that you
|
|||
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
|
||||
@code{other-buffer}) 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
|
||||
@code{other-buffer}) 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
|
||||
@code{switch-to-buffer} (@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
|
||||
@code{switch-to-buffer} (@pxref{Switching Buffers}), to display the
|
||||
buffer returned by @code{last-buffer}, see above, in the selected
|
||||
window.
|
||||
@end deffn
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@
|
|||
@end ifset
|
||||
|
||||
@c per rms and peterb, use 10pt fonts for the main text, mostly to
|
||||
@c save on paper cost.
|
||||
@c save on paper cost.
|
||||
@c Do this inside @tex for now, so current makeinfo does not complain.
|
||||
@tex
|
||||
@ifset smallbook
|
||||
|
|
@ -935,9 +935,9 @@ Windows
|
|||
* 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.
|
||||
|
|
|
|||
|
|
@ -103,7 +103,7 @@ function is basically equivalent to:
|
|||
@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 non-@code{nil}, which is always true in an
|
||||
interactive call, then @code{find-file} expands wildcard characters in
|
||||
|
|
@ -187,8 +187,9 @@ various files.
|
|||
|
||||
@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}.
|
||||
|
|
|
|||
|
|
@ -953,11 +953,11 @@ Windows
|
|||
* 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.
|
||||
|
|
|
|||
|
|
@ -952,11 +952,11 @@ Windows
|
|||
* 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.
|
||||
|
|
|
|||
|
|
@ -22,9 +22,9 @@ is displayed in windows.
|
|||
* 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 @@ set of windows to investigate. See the description of
|
|||
@code{next-window} for details.
|
||||
@end defun
|
||||
|
||||
|
||||
@node Buffers and Windows
|
||||
@section Buffers and Windows
|
||||
@cindex examining windows
|
||||
|
|
@ -1982,10 +1981,11 @@ one. If @var{window} is an internal window, this function returns
|
|||
|
||||
The basic, low-level function to associate a window with a buffer is
|
||||
@code{set-window-buffer}. Higher-level functions like
|
||||
@code{display-buffer} 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}.
|
||||
@code{switch-to-buffer} 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 @@ The two remaining arguments work like the same-named arguments of
|
|||
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.
|
||||
@var{buffer-or-name} 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}.
|
||||
(@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}.
|
||||
@end 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
|
||||
@code{set-window-buffer} 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
|
||||
@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} described
|
||||
below.
|
||||
|
||||
The following functions directly operate on the lists of previous and
|
||||
next buffers.
|
||||
|
||||
@defun 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.
|
||||
@end defun
|
||||
|
||||
@defun set-window-prev-buffers window prev-buffers
|
||||
This function sets @var{window}'s previous buffers to the value of
|
||||
@var{prev-buffers}. The argument @var{window} must be a live window and
|
||||
defaults to the selected one. This function returns
|
||||
@var{prev-buffers}.
|
||||
|
||||
If non-@code{nil}, @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}.
|
||||
@end defun
|
||||
|
||||
@defun window-next-buffers &optional window
|
||||
This function returns the list of buffers recently re-shown in
|
||||
@var{window}. The argument @var{window} must be a live window and
|
||||
defaults to the selected one.
|
||||
@end defun
|
||||
|
||||
@defun set-window-next-buffers window next-buffers
|
||||
This function sets @var{window}'s next buffers to @var{next-buffers}.
|
||||
@var{window} must be a live window and defaults to the selected one.
|
||||
This fucntion returns @var{next-buffers}.
|
||||
|
||||
If non-@code{nil}, the argument @var{next-buffers} should specify a list
|
||||
of buffers that shall be preferably not shown by the command
|
||||
@code{switch-to-prev-buffer}, see below.
|
||||
@end defun
|
||||
|
||||
The following command is used by @code{replace-buffer-in-windows},
|
||||
@code{bury-buffer} 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.
|
||||
|
||||
@deffn 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 non-@code{nil},
|
||||
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
|
||||
@code{switch-to-prev-buffer} 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
|
||||
@code{last-buffer} (@pxref{The Buffer List}).
|
||||
@end deffn
|
||||
|
||||
The following command can be used to undo the effect of the last undone
|
||||
@code{switch-to-prev-buffer} command.
|
||||
|
||||
@deffn 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
|
||||
@var{window}. 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}).
|
||||
@end deffn
|
||||
|
||||
Together, @code{switch-to-prev-buffer} and
|
||||
@code{switch-to-next-buffer} 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.
|
||||
|
||||
|
||||
@node Displaying Buffers
|
||||
@section Displaying Buffers in Windows
|
||||
@node Switching Buffers
|
||||
@section 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.
|
||||
@iftex
|
||||
See the preceding section for
|
||||
@end iftex
|
||||
@ifnottex
|
||||
@xref{Buffers and Windows}, for
|
||||
@end ifnottex
|
||||
low-level primitives that give you more precise control. All of these
|
||||
functions work by calling @code{set-window-buffer}.
|
||||
This section describes high-level functions for switching to a
|
||||
specified buffer in some window.
|
||||
|
||||
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
|
||||
@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
|
||||
Buffer}), which designate buffers as current for programmed access
|
||||
without affecting the display of buffers in windows.
|
||||
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
|
||||
@code{with-current-buffer}, @code{save-current-buffer}, or
|
||||
@code{set-buffer} (@pxref{Current Buffer}).
|
||||
|
||||
@deffn 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}.
|
||||
@deffn 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}, @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}.
|
||||
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
|
||||
returned by @code{other-buffer} (@pxref{The Buffer List}). If
|
||||
@var{buffer-or-name} 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}).
|
||||
|
||||
When the selected window is the minibuffer window or is strongly
|
||||
dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
|
||||
@code{pop-to-buffer} (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 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 non-@code{nil}.
|
||||
|
||||
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
|
||||
@var{norecord} is non-@code{nil}, 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.
|
||||
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
|
||||
@code{pop-to-buffer} (see below). However, if the optional argument
|
||||
@var{force-same-window} is non-@code{nil}, 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}.
|
||||
@end deffn
|
||||
|
||||
@deffn 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 non-@code{nil}.
|
||||
The @var{buffer-or-name} and @var{norecord} arguments have the same
|
||||
meanings as in @code{switch-to-buffer}.
|
||||
@end deffn
|
||||
|
||||
@defun 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.
|
||||
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:
|
||||
|
||||
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}.
|
||||
@defun 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.
|
||||
|
||||
If either of the variables @code{display-buffer-reuse-frames} or
|
||||
@code{pop-up-frames} is non-@code{nil}, @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
|
||||
@code{pop-up-frames} is non-@code{nil}, 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.)
|
||||
This function uses @code{display-buffer} to display the buffer, so all
|
||||
the variables affecting @code{display-buffer} will affect it as well.
|
||||
@xref{Choosing Window}.
|
||||
|
||||
If the variable @code{pop-up-windows} is non-@code{nil}, windows may be
|
||||
split to create a new window that is different from the original window.
|
||||
For details, see @ref{Choosing Window}.
|
||||
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
|
||||
returned by @code{other-buffer} (@pxref{The Buffer List}). If
|
||||
@var{buffer-or-name} 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{other-window} is non-@code{nil}, @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
|
||||
@code{nil}, then the selected window is considered sufficient for
|
||||
displaying @var{buffer-or-name}, so that nothing needs to be done.
|
||||
If @var{action} is non-@code{nil}, it should be a display action to
|
||||
pass to @code{display-buffer} (@pxref{Choosing Window}).
|
||||
Alternatively, a non-@code{nil}, 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.
|
||||
|
||||
All the variables that affect @code{display-buffer} affect
|
||||
@code{pop-to-buffer} as well. @xref{Choosing Window}.
|
||||
|
||||
This function updates the buffer list just like @code{switch-to-buffer}
|
||||
Like @code{switch-to-buffer}, this function updates the buffer list
|
||||
unless @var{norecord} is non-@code{nil}.
|
||||
@end defun
|
||||
|
||||
@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{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
|
||||
@var{buffer-or-name} 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}.
|
||||
@end deffn
|
||||
|
||||
@node Choosing Window
|
||||
@section Choosing a Window for Display
|
||||
|
||||
This section describes the basic facility that chooses a window to
|
||||
display a buffer in---@code{display-buffer}. 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.
|
||||
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
|
||||
@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
|
||||
Buffers}).
|
||||
|
||||
@deffn 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
|
||||
@var{buffer-or-name} 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.
|
||||
@cindex 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
|
||||
@dfn{action alists}.
|
||||
|
||||
@var{not-this-window} non-@code{nil} 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.
|
||||
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} returns the window chosen to display
|
||||
@var{buffer-or-name}.
|
||||
@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}
|
||||
value.
|
||||
|
||||
If the optional argument @var{frame} is non-@code{nil}, 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}:
|
||||
@deffn 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
|
||||
@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.
|
||||
|
||||
The optional argument @var{action}, if non-@code{nil}, 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):
|
||||
|
||||
@itemize
|
||||
@item
|
||||
The variable @code{display-buffer-overriding-action}.
|
||||
|
||||
@item
|
||||
The user option @code{display-buffer-alist}.
|
||||
|
||||
@item
|
||||
The @var{action} argument.
|
||||
|
||||
@item
|
||||
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.
|
||||
@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 non-nil.
|
||||
|
||||
The argument @var{action} can also have a non-@code{nil}, 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 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}:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
|
|
@ -2652,6 +2550,100 @@ If all options described above fail to produce a suitable window,
|
|||
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.
|
||||
|
||||
@node Window History
|
||||
@section Window History
|
||||
@cindex 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:
|
||||
|
||||
@defun window-prev-buffers &optional window
|
||||
This function returns a list specifying the previous contents of
|
||||
@var{window}, which should be a live window and defaults to the
|
||||
selected window.
|
||||
|
||||
Each list element has the form @code{(@var{buffer} @var{window-start}
|
||||
@var{window-pos})}, 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.
|
||||
@end defun
|
||||
|
||||
@defun set-window-prev-buffers window prev-buffers
|
||||
This function sets @var{window}'s previous buffers to the value of
|
||||
@var{prev-buffers}. 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
|
||||
@code{window-prev-buffers}.
|
||||
@end 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
|
||||
@code{switch-to-next-buffer} for choosing buffers to switch to.
|
||||
|
||||
@defun window-next-buffers &optional window
|
||||
This function returns the list of buffers recently re-shown in
|
||||
@var{window} via @code{switch-to-prev-buffer}. @var{window} should be
|
||||
a live window or @code{nil} (meaning the selected window).
|
||||
@end defun
|
||||
|
||||
@defun set-window-next-buffers window next-buffers
|
||||
This function sets the next buffer list of @var{window} to
|
||||
@var{next-buffers}. The @var{window} argument should be a live window
|
||||
or @code{nil} (meaning the selected window). The argument
|
||||
@var{next-buffers} should be a list of buffers.
|
||||
@end 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
|
||||
@code{switch-to-prev-buffer} command, in particular, is used by
|
||||
@code{replace-buffer-in-windows}, @code{bury-buffer} and
|
||||
@code{quit-window} to find a replacement buffer for a window.
|
||||
|
||||
@deffn 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
|
||||
non-@code{nil}, 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
|
||||
@code{switch-to-prev-buffer} 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
|
||||
@code{last-buffer} (@pxref{The Buffer List}).
|
||||
@end deffn
|
||||
|
||||
@deffn 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
|
||||
@var{window}. 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}).
|
||||
@end deffn
|
||||
|
||||
@node Dedicated Windows
|
||||
@section Dedicated Windows
|
||||
@cindex dedicated window
|
||||
|
|
@ -2666,15 +2658,15 @@ non-@code{nil}. The behavior of @code{set-window-buffer}
|
|||
(@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.
|
||||
@code{replace-buffer-in-windows} (@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
|
||||
|
|
|
|||
1
etc/NEWS
1
etc/NEWS
|
|
@ -1070,6 +1070,7 @@ shown in that window with its previous window-start and window-point
|
|||
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue