diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index ed2f0a0d3f0..a0d069ef922 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2011-09-24 Chong Yidong + + * 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 * display.texi (Forcing Redisplay): Update the description of diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 0f9de74c948..ce1a8b0fb4e 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -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 diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index d3b96a0eb81..5934f452c52 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -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. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index bd904bf49c0..71b612c527d 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -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}. diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 1275628cc94..0abca1ec502 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -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. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 3d849fa2dcf..f9ec9200d21 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -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. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index b80fe02b0ff..f455a7d4e02 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -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 diff --git a/etc/NEWS b/etc/NEWS index 75ff2081f00..3158295bbcb 100644 --- a/etc/NEWS +++ b/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