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>
* 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
instead.
@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
for the described features.
......@@ -1775,9 +1795,51 @@ It actually performs the split by calling the function specified in
@code{split-window-preferred-function} (@pxref{Choosing Window
Options}).
It 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}).
The size of the new window can be adjusted by supplying
@code{window-height} and @code{window-width} entries in @var{alist}. To
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
@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
windows are dedicated to another buffer (@pxref{Dedicated Windows}).
@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
@section Additional Options for Displaying Buffers
......@@ -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
(@pxref{Killing Buffers}) the window's buffer.
The following function uses information on how the window for
displaying the buffer was obtained in the first place, thus attempting to
automate the above decisions for you.
The following command uses information on how the window for
displaying the buffer was obtained in the first place, thus attempting
to automate the above decisions for you.
@deffn Command quit-window &optional kill window
This command quits @var{window} and buries its buffer. The argument
@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
instead of burying it.
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.
instead of burying it. It calls the function @code{quit-restore-window}
described next to deal with the window and its buffer.
@end deffn
The function @code{quit-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.
@defun quit-restore-window &optional window bury-or-kill
This function tries to restore the state of @var{window} that existed
before its buffer was displayed in it. The optional argument
@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
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.
The function specified here is called by @code{bury-buffer} (@pxref{The
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
above) when the frame of the window that should be quit has been
specially created for displaying that window's buffer and the buffer
should be buried.
to bury. It is also called by @code{quit-restore-window} (see above)
when the frame of the window to quit has been specially created for
displaying that window's buffer and the buffer is not killed.
The default is to call @code{iconify-frame} (@pxref{Visibility of
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
can take a frame as its sole argument.
Note that the function specified by this option is called if and only if
there is at least one other frame on the terminal of the frame it's
supposed to handle, and that frame contains only one live window.
Note that the function specified by this option is called only if the
specified frame contains just one live window and there is at least one
other frame on the same terminal.
@end defopt
......@@ -3123,8 +3236,8 @@ frame into the root window of that very frame only).
@defun window-state-get &optional window writable
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
of the selected frame.
argument @var{window} must be a valid window and defaults to the root
window of the selected frame.
If the optional argument @var{writable} is non-@code{nil}, this means to
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
Configurations}).
@item @code{quit-restore}
This parameter specifies what to do with a window when the buffer it
shows is not needed any more. It is installed by the buffer display
functions (@pxref{Choosing Window}), and consulted by the function
@code{quit-window} (@pxref{Quitting Windows}).
This parameter is installed by the buffer display functions
(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
(@pxref{Quitting Windows}). It contains four elements:
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
There are additional parameters @code{window-atom} and @code{window-side};
......
......@@ -818,7 +818,7 @@ to work out which code is doing something.
recursive invocations.
** Window changes
+++
*** The functions get-lru-window, get-mru-window and get-largest-window
now accept a third argument to avoid choosing the selected window.
......@@ -831,9 +831,12 @@ reused.
*** New function `fit-frame-to-buffer' and new options
`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',
`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,
tells display action functions to avoid changing which frame is
......@@ -841,10 +844,10 @@ selected.
*** New display action alist entry `pop-up-frame-parameters', if
non-nil, specifies frame parameters to give any newly-created frame.
+++
*** New display action alist entry `previous-window', if non-nil,
specifies window to reuse in `display-buffer-in-previous-window'.
+++
*** New display action alist entries `window-height' and `window-width'
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>
* play/gomoku.el (gomoku-display-statistics): Update mode line
......
......@@ -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 this variable is non-nil, `switch-to-prev-buffer' and
`switch-to-next-buffer' may switch to an already visible buffer
provided the buffer was shown in the argument window before. If
this variable is nil, `switch-to-prev-buffer' and
`switch-to-next-buffer' always try to avoid switching to a buffer
that is already visible in another window on the same frame."
provided the buffer was shown before in the window specified as
argument to those functions. If this variable is nil,
`switch-to-prev-buffer' and `switch-to-next-buffer' always try to
avoid switching to a buffer that is already visible in another
window on the same frame."
:type 'boolean
:version "24.1"
:group 'windows)
......@@ -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
position in the selected window.
This variable is ignored if the the buffer is already displayed
in the selected window or never appeared in it before, or if
This variable is ignored if the buffer is already displayed in
the selected window or never appeared in it before, or if
`switch-to-buffer' calls `pop-to-buffer' to display the buffer."
:type '(choice
(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