X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/2ab329f3b5d52a39f0a45c3d9c129f1c19560142..43bcfda6d863c6172eeba2d6aa22d22453849423:/doc/lispref/windows.texi diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index ea48a46359..2fbb59cd1d 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -76,30 +76,35 @@ within the area of the frame. When a window is created, resized, or deleted, the change in window space is taken from or given to the adjacent windows, so that the total area of the frame is unchanged. -@cindex live windows -@cindex internal windows - A @dfn{live window} is one that is actually displaying a buffer in a -frame. Such a window can be @dfn{deleted}, i.e. removed from the -frame (@pxref{Deleting Windows}); then it is no longer live, but the -Lisp object representing it might be still referenced from other Lisp -objects. A deleted window may be brought back to life by restoring a -saved window configuration (@pxref{Window Configurations}). - @defun windowp object This function returns @code{t} if @var{object} is a window (whether or -not it is live). Otherwise, it returns @code{nil}. +not it displays a buffer). Otherwise, it returns @code{nil}. @end defun +@cindex live windows +A @dfn{live window} is one that is actually displaying a buffer in a +frame. + @defun window-live-p object This function returns @code{t} if @var{object} is a live window and @code{nil} otherwise. A live window is one that displays a buffer. @end defun - The windows in each frame are organized into a @dfn{window tree}. -@xref{Windows and Frames}. The leaf nodes of each window tree are -live windows---the ones actually displaying buffers. The internal -nodes of the window tree are internal windows, which are not live. -You can distinguish internal windows from deleted windows with +@cindex internal windows +The windows in each frame are organized into a @dfn{window tree}. +@xref{Windows and Frames}. The leaf nodes of each window tree are live +windows---the ones actually displaying buffers. The internal nodes of +the window tree are @dfn{internal windows}, which are not live. + +@cindex valid windows + A @dfn{valid window} is one that is either live or internal. A valid +window can be @dfn{deleted}, i.e. removed from its frame +(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp +object representing it might be still referenced from other Lisp +objects. A deleted window may be made valid again by restoring a saved +window configuration (@pxref{Window Configurations}). + + You can distinguish valid windows from deleted windows with @code{window-valid-p}. @defun window-valid-p object @@ -1317,31 +1322,37 @@ meaning as for @code{next-window}. criterion, without selecting it: @cindex least recently used window -@defun get-lru-window &optional all-frames dedicated +@defun get-lru-window &optional all-frames dedicated not-selected This function returns a live window which is heuristically the ``least recently used'' window. The optional argument @var{all-frames} has the same meaning as in @code{next-window}. If any full-width windows are present, only those windows are -considered. The selected window is never returned, unless it is the -only candidate. 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}. +considered. 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 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. @end defun @cindex largest window -@defun get-largest-window &optional all-frames dedicated +@defun get-largest-window &optional all-frames dedicated not-selected This function returns the window with the largest area (height times -width). A minibuffer window is never a candidate. A dedicated window +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}. +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. - -The optional argument @var{all-frames} specifies the windows to -search, and has the same meaning as in @code{next-window}. @end defun @cindex window that satisfies a predicate @@ -1359,6 +1370,26 @@ windows to search, and have the same meanings as in @code{next-window}. @end defun +@cindex window in direction +@defun window-in-direction direction &optional window ignore +This function returns the nearest window in direction @var{direction} as +seen from the position of @code{window-point} in window @var{window}. +The argument @var{direction} must be one of @code{above}, @code{below}, +@code{left} or @code{right}. The optional argument @var{window} must +denote a live window and defaults to the selected one. + +This function does not return a window whose @code{no-other-window} +parameter is non-@code{nil}. If the nearest window's +@code{no-other-window} parameter is non-@code{nil}, this function tries +to find another window in the indicated direction whose +@code{no-other-window} parameter is @code{nil}. If the optional +argument @var{ignore} is non-@code{nil}, a window may be returned even +if its @code{no-other-window} parameter is non-@code{nil}. + +If it doesn't find a suitable window, this function returns @code{nil}. +@end defun + + @node Buffers and Windows @section Buffers and Windows @cindex examining windows @@ -1519,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. @@ -1631,11 +1682,6 @@ The variable @code{display-buffer-overriding-action}. @item The user option @code{display-buffer-alist}. -@item -A special action for handling @code{special-display-buffer-names} and -@code{special-display-regexps}, if either of those variables is -non-@code{nil}. @xref{Choosing Window Options}. - @item The @var{action} argument. @@ -1749,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 @@ -1760,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 @@ -1864,91 +1972,6 @@ Parameters}), which is used by the default function in @code{nil}. @end defopt -@defopt special-display-buffer-names -A list of buffer names identifying buffers that should be displayed -specially. If the name of @var{buffer-or-name} is in this list, -@code{display-buffer} handles the buffer specially. By default, special -display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of that -list is the buffer name, and the rest of that list says how to create -the frame. There are two possibilities for the rest of that list (its -@sc{cdr}): It can be an alist, specifying frame parameters, or it can -contain a function and arguments to give to it. (The function's first -argument is always the buffer to be displayed; the arguments from the -list come after that.) - -For example: - -@example -(("myfile" (minibuffer) (menu-bar-lines . 0))) -@end example - -@noindent -specifies to display a buffer named @samp{myfile} in a dedicated frame -with specified @code{minibuffer} and @code{menu-bar-lines} parameters. - -The list of frame parameters can also use the phony frame parameters -@code{same-frame} and @code{same-window}. If the specified frame -parameters include @code{(same-window . @var{value})} and @var{value} -is non-@code{nil}, that means to display the buffer in the current -selected window. Otherwise, if they include @code{(same-frame . -@var{value})} and @var{value} is non-@code{nil}, that means to display -the buffer in a new window in the currently selected frame. -@end defopt - -@defopt special-display-regexps -A list of regular expressions specifying buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. By default, special display means to give the buffer a -dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See @code{special-display-buffer-names} above. -@end defopt - -@defun special-display-p buffer-name -This function returns non-@code{nil} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -create a special frame. The value is @code{t} if it would -use the default frame parameters, or else the specified list -of frame parameters. -@end defun - -@defopt special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. The default value of this variable is -@code{special-display-popup-frame}, see below. -@end defopt - -@defun special-display-popup-frame buffer &optional args -This function tries to make @var{buffer} visible in a frame of its own. -If @var{buffer} is already displayed in some window, it makes that -window's frame visible and raises it. Otherwise, it creates a frame -that is dedicated to @var{buffer}. The return value is the window used -to display @var{buffer}. - -If @var{args} is an alist, it specifies frame parameters for the new -frame. If @var{args} is a list whose @sc{car} is a symbol, then -@code{(car @var{args})} is a function to actually create and -set up the frame; it is called with @var{buffer} as first argument, and -@code{(cdr @var{args})} as additional arguments. - -This function always uses an existing window displaying @var{buffer}, -whether or not it is in a frame of its own; but if you set up the above -variables in your init file, before @var{buffer} was created, then -presumably the window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -@anchor{Definition of special-display-frame-alist} -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - @defopt same-window-buffer-names A list of buffer names for buffers that should be displayed in the selected window. If a buffer's name is in this list, @@ -1969,19 +1992,6 @@ named @var{buffer-name} with @code{display-buffer} would put it in the selected window. @end defun -@c Emacs 19 feature -@defopt display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the first two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer in it, and then return the window. - -This variable takes precedence over all the other options described -above. -@end defopt - @node Window History @section Window History @cindex window history @@ -2158,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. @@ -2207,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} @@ -2218,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 @@ -3195,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 @@ -3339,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};