procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Try to improve text on atomic windows in Elisp manual

Browse source 
* doc/lispref/windows.texi (Deleting Windows): Mention how
'delete-window' and 'delete-other-windows' handle atomic
windows.  Minor rewrite.
(Quitting Windows): Mention how 'quit-restore-window' handles
atomic windows and that it tries to avoid raising an error.
(Atomic Windows): Tell how to dissolve atomic windows.
This commit is contained in:
Martin Rudalics 2019-06-03 10:36:00 +02:00
parent fb314ba3ad
commit c153250adb
1 changed files with 48 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

81
doc/lispref/windows.texi
View file

@ -1307,8 +1307,10 @@ the selected window.
If deleting the window would leave no more windows in the window tree If deleting the window would leave no more windows in the window tree
(e.g., if it is the only live window in the frame) or all remaining (e.g., if it is the only live window in the frame) or all remaining
windows on @var{window}'s frame are side windows (@pxref{Side Windows}), windows on @var{window}'s frame are side windows (@pxref{Side
an error is signaled. Windows}), an error is signaled. If @var{window} is part of an atomic
window (@pxref{Atomic Windows}), this function tries to delete the
root of that atomic window instead.
By default, the space taken up by @var{window} is given to one of its By default, the space taken up by @var{window} is given to one of its
adjacent sibling windows, if any. However, if the variable adjacent sibling windows, if any. However, if the variable
@ -1327,10 +1329,13 @@ Parameters}.
@end deffn @end deffn
@deffn Command delete-other-windows &optional window @deffn Command delete-other-windows &optional window
This function makes @var{window} fill its frame, deleting other windows This function makes @var{window} fill its frame, deleting other
as necessary. If @var{window} is omitted or @code{nil}, it defaults to windows as necessary. If @var{window} is omitted or @code{nil}, it
the selected window. An error is signaled if @var{window} is a side defaults to the selected window. An error is signaled if @var{window}
window (@pxref{Side Windows}). The return value is @code{nil}. is a side window (@pxref{Side Windows}). If @var{window} is part of
an atomic window (@pxref{Atomic Windows}), this function tries to make
the root of that atomic window fill its frame. The return
value is @code{nil}.
The behavior of this function may be altered by the window parameters of The behavior of this function may be altered by the window parameters of
@var{window}, so long as the variable @code{ignore-window-parameters} is @var{window}, so long as the variable @code{ignore-window-parameters} is
@ -3909,9 +3914,8 @@ described next to deal with the window and its buffer.
This function handles @var{window} and its buffer after quitting. The This function handles @var{window} and its buffer after quitting. The
optional argument @var{window} must be a live window and defaults to optional argument @var{window} must be a live window and defaults to
the selected one. The function's behavior is determined by the four the selected one. The function's behavior is determined by the four
elements of the list specified by the @code{quit-restore} window elements of the list specified by @var{window}'s @code{quit-restore}
parameter (@pxref{Window Parameters}), which is set to @code{nil} parameter (@pxref{Window Parameters}).
afterwards.
The first element of the @code{quit-restore} parameter is one of the The first element of the @code{quit-restore} parameter is one of the
symbols @code{window}, meaning that the window has been specially symbols @code{window}, meaning that the window has been specially
@ -3920,35 +3924,40 @@ been created; @code{same}, the window has only ever displayed this
buffer; or @code{other}, the window showed another buffer before. buffer; or @code{other}, the window showed another buffer before.
@code{frame} and @code{window} affect how the window is quit, while @code{frame} and @code{window} affect how the window is quit, while
@code{same} and @code{other} affect the redisplay of buffers @code{same} and @code{other} affect the redisplay of buffers
previously shown in this window. previously shown in @var{window}.
The second element is either one of the symbols @code{window} or The parameter's second element is either one of the symbols
@code{frame}, or a list whose elements are the buffer shown in the @code{window} or @code{frame}, or a list whose elements are the buffer
window before, that buffer's window start and window point positions, shown in @var{window} before, that buffer's window start and window
and the window's height at that time. If that buffer is still live point positions, and @var{window}'s height at that time. If that
when the window is quit, then the function @code{quit-restore-window} buffer is still live when @var{window} is quit, then this function may
reuses the window to display the buffer. reuse @var{window} to display it.
The third element is the window selected at the time the parameter was The third element is the window selected at the time the parameter was
created. If @code{quit-restore-window} deletes the window passed to created. If this function deletes @var{window}, it subsequently tries
it as argument, it then tries to reselect this window. to reselect the window named by that element.
The fourth element is the buffer whose display caused the creation of The fourth element is the buffer whose display caused the creation of
this parameter. @code{quit-restore-window} deletes the specified window this parameter. This function may delete @var{window} if and only if
only if it still shows that buffer. it still shows that buffer.
The window is deleted entirely if: 1) the first element of the This function will try to delete @var{window} if and only if (1) the
@code{quit-restore} parameter is one of 'window or 'frame, 2) the first element of its @code{quit-restore} parameter is either
window has no history of previously-displayed buffers, and 3) the @code{window} or @code{frame}, (2) the window has no history of
displayed buffer matches the one in the fourth element of the previously-displayed buffers and (3) the fourth element of the
@code{quit-restore} parameter. If @var{window} is the @code{quit-restore} parameter specifies the buffer currently displayed
only window on its frame and there are other frames on the frame's in @var{window}. If @var{window} is part of an atomic window
terminal, the value of the optional argument @var{bury-or-kill} (@pxref{Atomic Windows}), it will try to delete the root of that
determines how to proceed with the window. If @var{bury-or-kill} atomic window instead. In either case, it tries to avoid signaling an
equals @code{kill}, the frame is deleted unconditionally. Otherwise, error when @var{window} cannot be deleted.
the fate of the frame is determined by calling
@code{frame-auto-hide-function} (see below) with that frame as sole If @var{window} shall be deleted, is the only window on its frame and
argument. there are other frames on that 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.
If the third element of the @code{quit-restore} parameter is a list of If the third element of the @code{quit-restore} parameter is a list of
buffer, window start (@pxref{Window Start and End}), and point buffer, window start (@pxref{Window Start and End}), and point
@ -3959,7 +3968,8 @@ try to restore the original height of @var{window}.
Otherwise, if @var{window} was previously used for displaying other Otherwise, if @var{window} was previously used for displaying other
buffers (@pxref{Window History}), the most recent buffer in that buffers (@pxref{Window History}), the most recent buffer in that
history will be displayed. history will be displayed. In either case, if @var{window} is not
deleted, its @code{quit-restore} parameter is reset to @code{nil}.
The optional argument @var{bury-or-kill} specifies how to deal with The optional argument @var{bury-or-kill} specifies how to deal with
@var{window}'s buffer. The following values are handled: @var{window}'s buffer. The following values are handled:
@ -4440,6 +4450,11 @@ parameter assigned by @code{display-buffer-in-atom-window}. Further
parameters have to be set by the application explicitly via a parameters have to be set by the application explicitly via a
@code{window-parameters} entry in @var{alist}. @code{window-parameters} entry in @var{alist}.
Atomic windows automatically cease to exist when one of their
constituents gets deleted. To dissolve an atomic window manually,
reset the @code{window-atom} parameter of its constituents---the root
of the atomic window and all its descendants.
The following code snippet, when applied to a single-window frame, The following code snippet, when applied to a single-window frame,
first splits the selected window and makes the selected and the new first splits the selected window and makes the selected and the new
window constituents of an atomic window with their parent as root. It window constituents of an atomic window with their parent as root. It