Commit 43bcfda6 authored by Martin Rudalics's avatar Martin Rudalics
Browse files

Doc changes related to displaying buffers and quitting windows.

* window.el (switch-to-visible-buffer)
(switch-to-buffer-preserve-window-point): Fix doc-strings.

* windows.texi (Switching Buffers): Document option
switch-to-buffer-preserve-window-point.
(Display Action Functions): Document window-height and
window-width alist entries.
(Display Action Functions): Document
display-buffer-below-selected and
display-buffer-in-previous-window.
(Quitting Windows): Document quit-restore-window.  Rewrite
section.
(Window Configurations): In window-state-get mention that
argument window must be valid.
(Window Parameters): Document quit-restore window parameter
(Bug#12158).
parent 67b50ba4
2012-11-03 Martin Rudalics <rudalics@gmx.at>
* windows.texi (Switching Buffers): Document option
switch-to-buffer-preserve-window-point.
(Display Action Functions): Document window-height and
window-width alist entries.
(Display Action Functions): Document
display-buffer-below-selected and
display-buffer-in-previous-window.
(Quitting Windows): Document quit-restore-window. Rewrite
section.
(Window Configurations): In window-state-get mention that
argument window must be valid.
(Window Parameters): Document quit-restore window parameter
(Bug#12158).
2012-10-31 Glenn Morris <rgm@gnu.org> 2012-10-31 Glenn Morris <rgm@gnu.org>
* control.texi (Catch and Throw): Add xref to cl.texi. * control.texi (Catch and Throw): Add xref to cl.texi.
......
...@@ -1550,6 +1550,26 @@ normally tries to display the buffer in some other window, by invoking ...@@ -1550,6 +1550,26 @@ normally tries to display the buffer in some other window, by invoking
instead. instead.
@end deffn @end deffn
By default, @code{switch-to-buffer} sets @code{window-point} of the
window used to the buffer's position of @code{point}. This behavior can
be tuned using the following option.
@defopt switch-to-buffer-preserve-window-point
If this variable is @code{nil}, @code{switch-to-buffer} displays the
buffer specified by @var{buffer-or-name} at the position of that
buffer's @code{point}. If this variable is @code{already-displayed}, it
tries to display the buffer at its previous position in the selected
window, provided the buffer is currently displayed in some other window
on any visible or iconified frame. If this variable is @code{t},
@code{switch-to-buffer} unconditionally tries to display the buffer at
its previous position in the selected window.
This variable is ignored if the buffer is already displayed in the
selected window or never appeared in it before, or if
@code{switch-to-buffer} calls @code{pop-to-buffer} to display the
buffer.
@end defopt
The next two functions are similar to @code{switch-to-buffer}, except The next two functions are similar to @code{switch-to-buffer}, except
for the described features. for the described features.
...@@ -1775,9 +1795,51 @@ It actually performs the split by calling the function specified in ...@@ -1775,9 +1795,51 @@ It actually performs the split by calling the function specified in
@code{split-window-preferred-function} (@pxref{Choosing Window @code{split-window-preferred-function} (@pxref{Choosing Window
Options}). Options}).
It can fail if no window splitting can be performed for some reason The size of the new window can be adjusted by supplying
(e.g. if there is just one frame and it has an @code{unsplittable} @code{window-height} and @code{window-width} entries in @var{alist}. To
frame parameter; @pxref{Buffer Parameters}). adjust the window's height, use an entry whose @sc{car} is
@code{window-height} and whose @sc{cdr} is one of:
@itemize @bullet
@item
@code{nil} means to leave the height of the new window alone.
@item
A number specifies the desired height of the new window. An integer
number specifies the number of lines of the window. A floating point
number gives the fraction of the window's height with respect to the
height of the frame's root window.
@item
If the @sc{cdr} specifies a function, that function is called with one
argument - the new window. The function is supposed to adjust the
height of the window; its return value is ignored. Suitable functions
are @code{shrink-window-if-larger-than-buffer} and
@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
@end itemize
To adjust the window's width, use an entry whose @sc{car} is
@code{window-width} and whose @sc{cdr} is one of:
@itemize @bullet
@item
@code{nil} means to leave the width of the new window alone.
@item
A number specifies the desired width of the new window. An integer
number specifies the number of columns of the window. A floating point
number gives the fraction of the window's width with respect to the
width of the frame's root window.
@item
If the @sc{cdr} specifies a function, that function is called with one
argument - the new window. The function is supposed to adjust the width
of the window; its return value is ignored.
@end itemize
This function can fail if no window splitting can be performed for some
reason (e.g. if there is just one frame and it has an
@code{unsplittable} frame parameter; @pxref{Buffer Parameters}).
@end defun @end defun
@defun display-buffer-use-some-window buffer alist @defun display-buffer-use-some-window buffer alist
...@@ -1786,6 +1848,26 @@ window and displaying the buffer in that window. It can fail if all ...@@ -1786,6 +1848,26 @@ window and displaying the buffer in that window. It can fail if all
windows are dedicated to another buffer (@pxref{Dedicated Windows}). windows are dedicated to another buffer (@pxref{Dedicated Windows}).
@end defun @end defun
@defun display-buffer-below-selected buffer alist
This function tries to display @var{buffer} in a window below the
selected window. This means to either split the selected window or
reuse the window below the selected one.
@end defun
@defun display-buffer-in-previous-window buffer alist
This function tries to display @var{buffer} in a window previously
showing it. If @var{alist} has a non-@code{nil}
@code{inhibit-same-window} entry, the selected window is not eligible
for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
value determines which frames to search for a suitable window as with
@code{display-buffer-reuse-window}.
If @var{alist} has a @code{previous-window} entry, the window
specified by that entry will override any other window found by the
methods above, even if that window never showed @var{buffer} before.
@end defun
@node Choosing Window Options @node Choosing Window Options
@section Additional Options for Displaying Buffers @section Additional Options for Displaying Buffers
...@@ -2086,45 +2168,77 @@ function @code{switch-to-prev-buffer} (@pxref{Window History}). ...@@ -2086,45 +2168,77 @@ function @code{switch-to-prev-buffer} (@pxref{Window History}).
Finally, you might want to either bury (@pxref{The Buffer List}) or kill Finally, you might want to either bury (@pxref{The Buffer List}) or kill
(@pxref{Killing Buffers}) the window's buffer. (@pxref{Killing Buffers}) the window's buffer.
The following function uses information on how the window for The following command uses information on how the window for
displaying the buffer was obtained in the first place, thus attempting to displaying the buffer was obtained in the first place, thus attempting
automate the above decisions for you. to automate the above decisions for you.
@deffn Command quit-window &optional kill window @deffn Command quit-window &optional kill window
This command quits @var{window} and buries its buffer. The argument This command quits @var{window} and buries its buffer. The argument
@var{window} must be a live window and defaults to the selected one. @var{window} must be a live window and defaults to the selected one.
With prefix argument @var{kill} non-@code{nil}, it kills the buffer With prefix argument @var{kill} non-@code{nil}, it kills the buffer
instead of burying it. instead of burying it. It calls the function @code{quit-restore-window}
described next to deal with the window and its buffer.
Quitting @var{window} means to proceed as follows: If @var{window} was
created specially for displaying its current buffer, delete @var{window}
provided its frame contains at least one other live window. If
@var{window} is the only window on its frame and there are other frames
on the frame's terminal, the value of @var{kill} determines how to
proceed with the window. If @var{kill} is @code{nil}, the fate of the
frame is determined by calling @code{frame-auto-hide-function} (see
below) with that frame as sole argument. If @var{kill} is
non-@code{nil}, the frame is deleted unconditionally.
If @var{window} was reused for displaying its buffer, this command tries
to display the buffer previously shown in it. It also tries to restore
the window start (@pxref{Window Start and End}) and point (@pxref{Window
Point}) positions of the previously shown buffer. If, in addition, the
current buffer was temporarily resized, this command will also try to
restore the original height of @var{window}.
The three cases described so far require that the buffer shown in
@var{window} is still the buffer displayed by the last buffer display
function for this window. If another buffer has been shown in the
meantime, or the buffer previously shown no longer exists, this command
calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some
other buffer instead.
@end deffn @end deffn
The function @code{quit-window} bases its decisions on information @defun quit-restore-window &optional window bury-or-kill
stored in @var{window}'s @code{quit-restore} window parameter This function tries to restore the state of @var{window} that existed
(@pxref{Window Parameters}), and resets that parameter to @code{nil} before its buffer was displayed in it. The optional argument
after it's done. @var{window} must be a live window and defaults to the selected one.
If @var{window} was created specially for displaying its buffer, this
function deletes @var{window} provided its frame contains at least one
other live window. If @var{window} is the only window on its frame and
there are other frames on the frame's terminal, the value of the
optional argument @var{bury-or-kill} determines how to proceed with the
window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
unconditionally. Otherwise, the fate of the frame is determined by
calling @code{frame-auto-hide-function} (see below) with that frame as
sole argument.
Otherwise, this function tries to redisplay the buffer previously shown
in @var{window}. It also tries to restore the window start
(@pxref{Window Start and End}) and point (@pxref{Window Point})
positions of the previously shown buffer. If, in addition,
@var{window}'s buffer was temporarily resized, this function will also
try to restore the original height of @var{window}.
The cases described so far require that the buffer shown in @var{window}
is still the buffer displayed by the last buffer display function for
this window. If another buffer has been shown in the meantime, or the
buffer previously shown no longer exists, this function calls
@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
buffer instead.
The optional argument @var{bury-or-kill} specifes how to deal with
@var{window}'s buffer. The following values are handled:
@table @code
@item nil
This means to not deal with the buffer in any particular way. As a
consequence, if @var{window} is not deleted, invoking
@code{switch-to-prev-buffer} will usually show the buffer again.
@item append
This means that if @var{window} is not deleted, its buffer is moved to
the end of @var{window}'s list of previous buffers, so it's less likely
that a future invocation of @code{switch-to-prev-buffer} will switch to
it. Also, it moves the buffer to the end of the frame's buffer list.
@item bury
This means that if @var{window} is not deleted, its buffer is removed
from @var{window}'s list of previous buffers. Also, it moves the buffer
to the end of the frame's buffer list. This value provides the most
reliable remedy to not have @code{switch-to-prev-buffer} switch to this
buffer again without killing the buffer.
@item kill
This means to kill @var{window}'s buffer.
@end table
@code{quit-restore-window} bases its decisions on information stored in
@var{window}'s @code{quit-restore} window parameter (@pxref{Window
Parameters}), and resets that parameter to @code{nil} after it's done.
@end defun
The following option specifies how to deal with a frame containing just The following option specifies how to deal with a frame containing just
one window that should be either quit, or whose buffer should be buried. one window that should be either quit, or whose buffer should be buried.
...@@ -2135,10 +2249,9 @@ frames. This function is called with one argument---a frame. ...@@ -2135,10 +2249,9 @@ frames. This function is called with one argument---a frame.
The function specified here is called by @code{bury-buffer} (@pxref{The The function specified here is called by @code{bury-buffer} (@pxref{The
Buffer List}) when the selected window is dedicated and shows the buffer Buffer List}) when the selected window is dedicated and shows the buffer
that should be buried. It is also called by @code{quit-window} (see to bury. It is also called by @code{quit-restore-window} (see above)
above) when the frame of the window that should be quit has been when the frame of the window to quit has been specially created for
specially created for displaying that window's buffer and the buffer displaying that window's buffer and the buffer is not killed.
should be buried.
The default is to call @code{iconify-frame} (@pxref{Visibility of The default is to call @code{iconify-frame} (@pxref{Visibility of
Frames}). Alternatively, you may specify either @code{delete-frame} Frames}). Alternatively, you may specify either @code{delete-frame}
...@@ -2146,9 +2259,9 @@ Frames}). Alternatively, you may specify either @code{delete-frame} ...@@ -2146,9 +2259,9 @@ Frames}). Alternatively, you may specify either @code{delete-frame}
@code{ignore} to leave the frame unchanged, or any other function that @code{ignore} to leave the frame unchanged, or any other function that
can take a frame as its sole argument. can take a frame as its sole argument.
Note that the function specified by this option is called if and only if Note that the function specified by this option is called only if the
there is at least one other frame on the terminal of the frame it's specified frame contains just one live window and there is at least one
supposed to handle, and that frame contains only one live window. other frame on the same terminal.
@end defopt @end defopt
...@@ -3123,8 +3236,8 @@ frame into the root window of that very frame only). ...@@ -3123,8 +3236,8 @@ frame into the root window of that very frame only).
@defun window-state-get &optional window writable @defun window-state-get &optional window writable
This function returns the state of @var{window} as a Lisp object. The This function returns the state of @var{window} as a Lisp object. The
argument @var{window} can be any window and defaults to the root window argument @var{window} must be a valid window and defaults to the root
of the selected frame. window of the selected frame.
If the optional argument @var{writable} is non-@code{nil}, this means to If the optional argument @var{writable} is non-@code{nil}, this means to
not use markers for sampling positions like @code{window-point} or not use markers for sampling positions like @code{window-point} or
...@@ -3267,10 +3380,28 @@ from. It is installed by @code{window-state-get} (@pxref{Window ...@@ -3267,10 +3380,28 @@ from. It is installed by @code{window-state-get} (@pxref{Window
Configurations}). Configurations}).
@item @code{quit-restore} @item @code{quit-restore}
This parameter specifies what to do with a window when the buffer it This parameter is installed by the buffer display functions
shows is not needed any more. It is installed by the buffer display (@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
functions (@pxref{Choosing Window}), and consulted by the function (@pxref{Quitting Windows}). It contains four elements:
@code{quit-window} (@pxref{Quitting Windows}).
The first element is one of the symbols @code{window} - meaning that the
window has been specially created by @code{display-buffer}, @code{frame}
- a separate frame has been created, @code{same} - the window has
displayed the same buffer before, or @code{other} - the window showed
another buffer before.
The second element is either one of the symbols @code{window} or
@code{frame}, or a list whose elements are the buffer shown in the
window before, that buffer's window start and window point positions,
and the window's height at that time.
The third element is the window selected at the time the parameter was
created. The function @code{quit-restore-window} tries to reselect that
window when it deletes the window passed to it as argument.
The fourth element is the buffer whose display caused the creation of
this parameter. @code{quit-restore-window} deletes the specified window
only if it still shows that buffer.
@end table @end table
There are additional parameters @code{window-atom} and @code{window-side}; There are additional parameters @code{window-atom} and @code{window-side};
......
...@@ -818,7 +818,7 @@ to work out which code is doing something. ...@@ -818,7 +818,7 @@ to work out which code is doing something.
recursive invocations. recursive invocations.
** Window changes ** Window changes
+++
*** The functions get-lru-window, get-mru-window and get-largest-window *** The functions get-lru-window, get-mru-window and get-largest-window
now accept a third argument to avoid choosing the selected window. now accept a third argument to avoid choosing the selected window.
...@@ -831,9 +831,12 @@ reused. ...@@ -831,9 +831,12 @@ reused.
*** New function `fit-frame-to-buffer' and new options *** New function `fit-frame-to-buffer' and new options
`fit-frame-to-buffer' and `fit-frame-to-buffer-bottom-margin'. `fit-frame-to-buffer' and `fit-frame-to-buffer-bottom-margin'.
+++
*** New option switch-to-buffer-preserve-window-point to restore a
window's point when switching buffers.
+++
*** New display action functions `display-buffer-below-selected', *** New display action functions `display-buffer-below-selected',
`display-buffer-at-bottom' and `display-buffer-in-previous-window'. and `display-buffer-in-previous-window'.
*** New display action alist entry `inhibit-switch-frame', if non-nil, *** New display action alist entry `inhibit-switch-frame', if non-nil,
tells display action functions to avoid changing which frame is tells display action functions to avoid changing which frame is
...@@ -841,10 +844,10 @@ selected. ...@@ -841,10 +844,10 @@ selected.
*** New display action alist entry `pop-up-frame-parameters', if *** New display action alist entry `pop-up-frame-parameters', if
non-nil, specifies frame parameters to give any newly-created frame. non-nil, specifies frame parameters to give any newly-created frame.
+++
*** New display action alist entry `previous-window', if non-nil, *** New display action alist entry `previous-window', if non-nil,
specifies window to reuse in `display-buffer-in-previous-window'. specifies window to reuse in `display-buffer-in-previous-window'.
+++
*** New display action alist entries `window-height' and `window-width' *** New display action alist entries `window-height' and `window-width'
to specify size of new window created by `display-buffer'. to specify size of new window created by `display-buffer'.
......
2012-11-03 Martin Rudalics <rudalics@gmx.at>
* window.el (switch-to-visible-buffer)
(switch-to-buffer-preserve-window-point): Fix doc-strings.
2012-11-01 Stephen Berman <stephen.berman@gmx.net> 2012-11-01 Stephen Berman <stephen.berman@gmx.net>
   
* play/gomoku.el (gomoku-display-statistics): Update mode line * play/gomoku.el (gomoku-display-statistics): Update mode line
......
...@@ -3091,10 +3091,11 @@ before was current this also makes BUFFER the current buffer." ...@@ -3091,10 +3091,11 @@ before was current this also makes BUFFER the current buffer."
"If non-nil, allow switching to an already visible buffer. "If non-nil, allow switching to an already visible buffer.
If this variable is non-nil, `switch-to-prev-buffer' and If this variable is non-nil, `switch-to-prev-buffer' and
`switch-to-next-buffer' may switch to an already visible buffer `switch-to-next-buffer' may switch to an already visible buffer
provided the buffer was shown in the argument window before. If provided the buffer was shown before in the window specified as
this variable is nil, `switch-to-prev-buffer' and argument to those functions. If this variable is nil,
`switch-to-next-buffer' always try to avoid switching to a buffer `switch-to-prev-buffer' and `switch-to-next-buffer' always try to
that is already visible in another window on the same frame." avoid switching to a buffer that is already visible in another
window on the same frame."
:type 'boolean :type 'boolean
:version "24.1" :version "24.1"
:group 'windows) :group 'windows)
...@@ -5855,8 +5856,8 @@ window on any visible or iconified frame. If this is t, it ...@@ -5855,8 +5856,8 @@ window on any visible or iconified frame. If this is t, it
unconditionally tries to display the buffer at its previous unconditionally tries to display the buffer at its previous
position in the selected window. position in the selected window.
This variable is ignored if the the buffer is already displayed This variable is ignored if the buffer is already displayed in
in the selected window or never appeared in it before, or if the selected window or never appeared in it before, or if
`switch-to-buffer' calls `pop-to-buffer' to display the buffer." `switch-to-buffer' calls `pop-to-buffer' to display the buffer."
:type '(choice :type '(choice
(const :tag "Never" nil) (const :tag "Never" nil)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment