mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2025-01-01 11:14:55 +00:00
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).
This commit is contained in:
Martin Rudalics
parent
67b50ba47b
commit
43bcfda6d8
@ -1,3 +1,19 @@
|
||||
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};
|
||||
|
||||
13
etc/NEWS
13
etc/NEWS
@ -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'.
|
||||
|
||||
|
||||
@ -1,3 +1,8 @@
|
||||
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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user