diff options
Diffstat (limited to 'doc/lispref/windows.texi')
| -rw-r--r-- | doc/lispref/windows.texi | 136 |
1 files changed, 115 insertions, 21 deletions
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index d72da704f13..eef05d94fdb 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2851,8 +2851,8 @@ the left edge coordinate of the reference window. Its left edge coordinate would equal the left edge coordinate of the frame's new root window. -Four special values for @code{direction} entries allow to implicitly -specify the selected frame's main window as the reference window: +Four special values for @code{direction} entries allow implicitly +specifying the selected frame's main window as the reference window: @code{leftmost}, @code{top}, @code{rightmost} and @code{bottom}. This means that instead of, for example, @w{@code{(direction . left) (window . main)}} one can just specify @w{@code{(direction @@ -3272,6 +3272,15 @@ The value specifies an alist of frame parameters to give a new frame, if one is created. @code{display-buffer-pop-up-frame} is its one and only addressee. +@vindex pop-up-frames@r{, a buffer display action alist entry} +@item pop-up-frames +The value controls whether @code{display-buffer} may display buffers +by making new frames. It has the same meaning as the +@code{pop-up-frames} variable and takes precedence over it when present. +Its main intended purpose is to override a non-nil value of the +variable for particular buffers which the user prefers to keep +in the selected frame. + @vindex parent-frame@r{, a buffer display action alist entry} @item parent-frame The value specifies the parent frame to be used when the buffer is @@ -3335,6 +3344,16 @@ It is called @emph{after} the buffer is displayed, and @emph{before} the entries @code{window-height}, @code{window-width} and @code{preserve-size} are applied that could resize the window to fit it to the inserted contents. + +@vindex post-command-select-window@r{, a buffer display action alist entry} +@item post-command-select-window +If the value is non-@code{nil}, the buffer displayed by @code{display-buffer} +is selected after the current command is executed by running the hook +@code{post-command-hook} (@pxref{Command Overview}). +If the value is @code{nil}, the buffer selected by such functions as +@code{pop-to-buffer} is deselected, and the window that was selected +before calling this function will remain selected regardless of which +windows were selected afterwards within this command. @end table By convention, the entries @code{window-height}, @code{window-width} @@ -3445,6 +3464,9 @@ A non-@code{nil} value also means that when @code{display-buffer} is looking for a window already displaying @var{buffer-or-name}, it can search any visible or iconified frame, not just the selected frame. +An entry by the same name in @code{display-buffer}'s @var{alist} +takes precedence over the variable. + This variable is provided mainly for backward compatibility. It is obeyed by @code{display-buffer} via a special mechanism in @code{display-buffer-fallback-action}, which calls the action function @@ -3516,15 +3538,12 @@ functions it should try instead as, for example: @item pop-up-frames @vindex pop-up-frames@r{, replacement for} -Instead of customizing this variable to @code{t}, customize +Instead of customizing this variable to @code{t}, you can customize @code{display-buffer-base-action}, for example, as follows: @example @group -(setopt - display-buffer-base-action - '((display-buffer-reuse-window display-buffer-pop-up-frame) - (reusable-frames . 0))) +(setopt display-buffer-base-action '(nil (pop-up-frames . t))) @end group @end example @@ -3763,7 +3782,7 @@ preferred way regardless of whether the display is also guided by an @code{display-buffer-alist} differs from customizing @code{display-buffer-base-action} in two major aspects: it is stronger because it overrides the @var{action} argument of -@code{display-buffer}, and it allows to explicitly specify the +@code{display-buffer}, and it enables you to explicitly specify the affected buffers. In fact, displaying other buffers is not affected in any way by a customization for @file{*foo*}. For example, @@ -4600,7 +4619,7 @@ window and a number of side windows surrounding that main window. The main window is either a ``normal'' live window or specifies the area containing all the normal windows. - In their most simple form of use, side windows allow to display + In their most simple form of use, side windows allow displaying specific buffers always in the same area of a frame. Hence they can be regarded as a generalization of the concept provided by @code{display-buffer-at-bottom} (@pxref{Buffer Display Action @@ -6154,11 +6173,11 @@ up-to-date. @section Mouse Window Auto-selection @cindex window auto-selection @cindex auto-selection of window -The following option allows to automatically select the window under the -mouse pointer. This accomplishes a policy similar to that of window -managers that give focus to a frame (and thus trigger its subsequent -selection) whenever the mouse pointer enters its window-system window -(@pxref{Input Focus}). +The following option enables automatically selecting the window under +the mouse pointer. This accomplishes a policy similar to that of +window managers that give focus to a frame (and thus trigger its +subsequent selection) whenever the mouse pointer enters its +window-system window (@pxref{Input Focus}). @defopt mouse-autoselect-window If this variable is non-@code{nil}, Emacs will try to automatically @@ -6192,7 +6211,7 @@ and never deselects the active minibuffer window. Mouse auto-selection can be used to emulate a focus follows mouse policy for child frames (@pxref{Child Frames}) which usually are not tracked by -the window manager. This requires to set the value of +the window manager. This requires setting the value of @code{focus-follows-mouse} (@pxref{Input Focus}) to a non-@code{nil} value. If the value of @code{focus-follows-mouse} is @code{auto-raise}, entering a child frame with the mouse will raise it automatically above @@ -6245,11 +6264,10 @@ this function does is to restore the value of the variable @code{minibuffer-selected-window}. In this case, the function returns @code{nil}. Otherwise, it returns @code{t}. -If the buffer of a window of @var{configuration} has been killed since -@var{configuration} was made, that window is, as a rule, removed from -the restored configuration. However, if that window is the last -window remaining in the restored configuration, another live buffer is -shown in it. +This function consults the variable +@code{window-restore-killed-buffer-windows} (see below) when it tries to +restore a window whose buffer was killed after @var{configuration} was +recorded. Here is a way of using this function to get the same effect as @code{save-window-excursion}: @@ -6338,14 +6356,90 @@ a live window, it is replaced by a new live window created on the same frame before putting @var{state} into it. If @var{window} is @code{nil}, it puts the window state into a new window. +This function consults the variable +@code{window-restore-killed-buffer-windows} (see below) when it tries to +restore a window whose buffer was killed after @var{state} was recorded. + If the optional argument @var{ignore} is non-@code{nil}, it means to ignore minimum window sizes and fixed-size restrictions. If @var{ignore} is @code{safe}, this means windows can get as small as one line and/or two columns. @end defun +By default, @code{set-window-configuration} and @code{window-state-put} +may delete a window from the restored configuration when they find out +that its buffer was killed since the corresponding configuration or +state has been recorded. The variable described next can be used to +fine-tune that behavior. + +@cindex restoring windows whose buffers have been killed +@defvar window-restore-killed-buffer-windows +This variable specifies how @code{set-window-configuration} and +@code{window-state-put} shall handle a window whose buffer has been +killed since the corresponding configuration or state was recorded. Any +such window may be live---in which case it shows some other buffer---or +dead at the time one of these functions is called. Usually, +@code{set-window-configuration} leaves the window alone if it is live +while @code{window-state-put} deletes it. + +The following values can be used to override the default behavior for +dead windows in the case of @code{set-window-configuration} and for dead +and live windows in the case of @code{window-state-put}. + +@table @asis +@item @code{t} +This value means to unconditionally restore the window and show some +other buffer in it. + +@item @code{delete} +This means to unconditionally try to delete the window. + +@item @code{dedicated} +This means to try to delete the window if and only if it is dedicated to +its buffer. + +@item @code{nil} +This is the default, and it means that @code{set-window-configuration} +will try to delete the window if and only if it is dedicated to its +buffer, and @code{window-state-put} will unconditionally try to delete +it. + +@item a function +This means to restore the window and show some other buffer in it, like +if the value is @code{t}, and also add an entry for that window to a +list that will be later passed as the second argument to that function. +@end table + +If a window cannot be deleted (typically, because it is the last window +on its frame), @code{set-window-configuration} and +@code{window-state-put} will show another buffer in it. + +If the value of this variable is a function, that function should take +three arguments. The first argument specifies the frame whose windows +have been restored. The third argument is either the symbol +@code{configuration} if the windows are restored by +@code{set-window-configuration}, or the symbol @code{state} if the +windows are restored by @code{window-state-put}. + +The second argument specifies a list of entries for @emph{all} windows +whose previous buffers have been found dead at the time +@code{set-window-configuration} or @code{window-state-put} tried to +restore them (minibuffer windows are excluded). This means that the +function may also delete windows which were found live by +@code{set-window-configuration}. + +Each entry in the list that is passed as the second argument to the +function is itself a list of six values: the window whose buffer was +found dead, the dead buffer or its name, the positions of window-start +(@pxref{Window Start and End}) and window-point (@pxref{Window Point}) +of the buffer in that window, the dedicated state of the window as +previously reported by @code{window-dedicated-p} and a flag that is +@code{t} if the window has been found to be alive by +@code{set-window-configuration} and @code{nil} otherwise. +@end defvar + The functions @code{window-state-get} and @code{window-state-put} also -allow to exchange the contents of two live windows. The following +allow exchanging the contents of two live windows. The following function does precisely that: @deffn Command window-swap-states &optional window-1 window-2 size |