diff options
Diffstat (limited to 'doc/lispref/windows.texi')
| -rw-r--r-- | doc/lispref/windows.texi | 134 |
1 files changed, 89 insertions, 45 deletions
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index f305d1a8ee8..26f85df160e 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1318,6 +1318,33 @@ lieu of the usual action of @code{delete-window}. @xref{Window Parameters}. @end deffn +When @code{delete-window} deletes the selected window of its frame, it +has to make another window the new selected window of that frame. The +following option allows configuring which window is chosen. + +@defopt delete-window-choose-selected +This option allows specifying which window should become a frame's +selected window after @code{delete-window} has deleted the previously +selected one. Possible choices are + +@itemize +@item @code{mru} +(the default) choose the most recently used window on that frame. + +@item @code{pos} +choose the window comprising the frame coordinates of point of the +previously selected window on that frame. + +@item @code{nil} +choose the first window (the window returned by +@code{frame-first-window}) on that frame. +@end itemize + +A window with a non-@code{nil} @code{no-other-window} parameter is +chosen only if all other windows on that frame have that parameter set +to a non-@code{nil} value too. +@end defopt + @deffn Command delete-other-windows &optional window This function makes @var{window} fill its frame, deleting other windows as necessary. If @var{window} is omitted or @code{nil}, it @@ -1838,6 +1865,14 @@ with @var{window} as the selected window without needlessly running @code{buffer-list-update-hook}. @end defmac +@defmac with-selected-frame frame forms@dots{} +This macro executes @var{forms} with @var{frame} as the selected +frame. The value returned is the value of the last form in +@var{forms}. This macro saves and restores the selected frame, and +changes the order of neither the recently selected windows nor the +buffers in the buffer list. +@end defmac + @defun frame-selected-window &optional frame This function returns the window on @var{frame} that is selected within that frame. @var{frame} should be a live frame; if omitted or @@ -1999,7 +2034,7 @@ meaning as for @code{next-window}. criterion, without selecting it: @cindex least recently used window -@defun get-lru-window &optional all-frames dedicated not-selected +@defun get-lru-window &optional all-frames dedicated not-selected no-other This function returns a live window which is heuristically the least recently used. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. @@ -2010,33 +2045,25 @@ window (@pxref{Dedicated Windows}) is never a candidate unless the optional argument @var{dedicated} is non-@code{nil}. The selected window is never returned, unless it is the only candidate. However, if the optional argument @var{not-selected} is non-@code{nil}, this -function returns @code{nil} in that case. +function returns @code{nil} in that case. The optional argument +@var{no-other}, if non-@code{nil}, means to never return a window whose +@code{no-other-window} parameter is non-@code{nil}. @end defun @cindex most recently used window -@defun get-mru-window &optional all-frames dedicated not-selected +@defun get-mru-window &optional all-frames dedicated not-selected no-other This function is like @code{get-lru-window}, but it returns the most recently used window instead. The meaning of the arguments is the -same as described for @code{get-lru-window}. +same as for @code{get-lru-window}. @end defun @cindex largest window -@defun get-largest-window &optional all-frames dedicated not-selected +@defun get-largest-window &optional all-frames dedicated not-selected no-other This function returns the window with the largest area (height times -width). The optional argument @var{all-frames} specifies the windows to -search, and has the same meaning as in @code{next-window}. - -A minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. The selected window is not -a candidate if the optional argument @var{not-selected} is -non-@code{nil}. If the optional argument @var{not-selected} is -non-@code{nil} and the selected window is the only candidate, this -function returns @code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window. +width). If there are two candidate windows of the same size, it prefers +the one that comes first in the cyclic ordering of windows, starting +from the selected window. The meaning of the arguments is the same as +for @code{get-lru-window}. @end defun @cindex window that satisfies a predicate @@ -2164,12 +2191,13 @@ the name of an existing buffer; if omitted or @code{nil}, it defaults to the current buffer. The replacement buffer in each window is chosen via -@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated -window displaying @var{buffer-or-name} is deleted if possible -(@pxref{Dedicated Windows}). If such a window is the only window on its -frame and there are other frames on the same terminal, the frame is -deleted as well. If the dedicated window is the only window on the only -frame on its terminal, the buffer is replaced anyway. +@code{switch-to-prev-buffer} (@pxref{Window History}). With the +exception of side windows (@pxref{Side Windows}), any dedicated window +displaying @var{buffer-or-name} is deleted if possible (@pxref{Dedicated +Windows}). If such a window is the only window on its frame and there +are other frames on the same terminal, the frame is deleted as well. +If the dedicated window is the only window on the only frame on its +terminal, the buffer is replaced anyway. @end deffn @@ -2557,7 +2585,7 @@ frame visible and, unless @var{alist} contains an This function tries to display @var{buffer} by finding a window that is displaying a buffer in a given mode. -If @var{alist} contains a @code{mode} entry, its value specifes a +If @var{alist} contains a @code{mode} entry, its value specifies a major mode (a symbol) or a list of major modes. If @var{alist} contains no @code{mode} entry, the current major mode of @var{buffer} is used instead. A window is a candidate if it displays a buffer @@ -2986,6 +3014,8 @@ If non-@code{nil}, such an entry tells @code{display-buffer} to mark any window it creates as dedicated to its buffer (@pxref{Dedicated Windows}). It does that by calling @code{set-window-dedicated-p} with the chosen window as first argument and the entry's value as second. +Side windows are by default dedicated with the value @code{side} +((@pxref{Side Window Options and Functions}). @vindex preserve-size@r{, a buffer display action alist entry} @item preserve-size @@ -4034,18 +4064,19 @@ slightly different, see below. Functions supposed to remove a buffer from a window or a window from a frame can behave specially when a window they operate on is dedicated. -We will distinguish three basic cases, namely where (1) the window is +We will distinguish four basic cases, namely where (1) the window is not the only window on its frame, (2) the window is the only window on -its frame but there are other frames on the same terminal left, and (3) -the window is the only window on the only frame on the same terminal. +its frame but there are other frames on the same terminal left, (3) +the window is the only window on the only frame on the same terminal, +and (4) the dedication's value is @code{side} +(@pxref{Displaying Buffers in Side Windows}). In particular, @code{delete-windows-on} (@pxref{Deleting Windows}) -handles case (2) by deleting the associated frame and case (3) by -showing another buffer in that frame's only window. The function +handles case (2) by deleting the associated frame and cases (3) and (4) +by showing another buffer in that frame's only window. The function @code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is called when a buffer gets killed, deletes the window in case (1) and behaves like @code{delete-windows-on} otherwise. -@c FIXME: Does replace-buffer-in-windows _delete_ a window in case (1)? When @code{bury-buffer} (@pxref{Buffer List}) operates on the selected window (which shows the buffer that shall be buried), it @@ -4308,6 +4339,25 @@ means to use a slot following (that is, below or on the right of) the middle slot. Hence, all windows on a specific side are ordered by their @code{slot} value. If unspecified, the window is located in the middle of the specified side. + +@item dedicated +The dedicated flag (@pxref{Dedicated Windows}) has a slightly different +meaning for side windows. When a side window is created, that flag is +set to the value @code{side} to prevent @code{display-buffer} to use the +window in other action functions. Its value persists across invocations +of @code{quit-window}, @code{kill-buffer}, @code{previous-buffer} and +@code{next-buffer}. + +In particular, these commands will refrain from showing, in a side +window, buffers that have not been displayed in that window before. +They will also refrain from having a normal, non-side window show a +buffer that has been already displayed in a side window. A notable +exception to the latter rule occurs when an application, after +displaying a buffer, resets that buffer’s local variables. To override +these rules and always delete a side window with @code{quit-window} or +@code{kill-buffer}, and eventually prevent the use of +@code{previous-buffer} and @code{next-buffer}, set this value to +@code{t} or specify a value via @code{display-buffer-mark-dedicated}. @end table If you specify the same slot on the same side for two or more different @@ -4328,16 +4378,6 @@ Functions}) unless it is explicitly specified as target of that action. Note also that @code{delete-other-windows} cannot make a side window the only window on its frame (@pxref{Deleting Windows}). - Once set up, side windows also change the behavior of the commands -@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} -(@pxref{Window History}). In particular, these commands will refrain -from showing, in a side window, buffers that have not been displayed in -that window before. They will also refrain from having a normal, -non-side window show a buffer that has been already displayed in a side -window. A notable exception to the latter rule occurs when an -application, after displaying a buffer, resets that buffer's local -variables. - @node Side Window Options and Functions @subsection Side Window Options and Functions @@ -5877,7 +5917,7 @@ which window parameters (if any) are saved by this function. @xref{Window Parameters}. @end defun -@defun set-window-configuration configuration &optional dont-set-frame +@defun set-window-configuration configuration &optional dont-set-frame dont-set-miniwindow This function restores the configuration of windows and buffers as specified by @var{configuration}, for the frame that @var{configuration} was created for, regardless of whether that frame @@ -5885,8 +5925,12 @@ is selected or not. The argument @var{configuration} must be a value that was previously returned by @code{current-window-configuration} for that frame. Normally the function also selects the frame which is recorded in the configuration, but if @var{dont-set-frame} is -non-@code{nil}, it leaves selected the frame which was current at the -start of the function. +non-@code{nil}, it leaves selected the frame which was already +selected at the start of the function. + +Normally the function restores the saved minibuffer (if any), but if +@var{dont-set-miniwindow} is non-@code{nil}, the minibuffer current +at the start of the function (if any) remains in the mini-window. If the frame from which @var{configuration} was saved is dead, all this function does is to restore the value of the variable |