Mercurial > emacs
changeset 84112:7087f74a4f1d
Move here from ../../lispref
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:24:30 +0000 |
| parents | 36dfa0b3a8b7 |
| children | 74bca120d9f0 |
| files | doc/lispref/windows.texi |
| diffstat | 1 files changed, 2446 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/windows.texi Thu Sep 06 04:24:30 2007 +0000 @@ -0,0 +1,2446 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/windows +@node Windows, Frames, Buffers, Top +@chapter Windows + + This chapter describes most of the functions and variables related to +Emacs windows. See @ref{Display}, for information on how text is +displayed in windows. + +@menu +* Basic Windows:: Basic information on using windows. +* Splitting Windows:: Splitting one window into two windows. +* Deleting Windows:: Deleting a window gives its space to other windows. +* Selecting Windows:: The selected window is the one that you edit in. +* Cyclic Window Ordering:: Moving around the existing windows. +* Buffers and Windows:: Each window displays the contents of a buffer. +* Displaying Buffers:: Higher-level functions for displaying a buffer + and choosing a window for it. +* Choosing Window:: How to choose a window for displaying a buffer. +* Window Point:: Each window has its own location of point. +* Window Start:: The display-start position controls which text + is on-screen in the window. +* Textual Scrolling:: Moving text up and down through the window. +* Vertical Scrolling:: Moving the contents up and down on the window. +* Horizontal Scrolling:: Moving the contents sideways on the window. +* Size of Window:: Accessing the size of a window. +* Resizing Windows:: Changing the size of a window. +* Coordinates and Windows:: Converting coordinates to windows. +* Window Tree:: The layout and sizes of all windows in a frame. +* Window Configurations:: Saving and restoring the state of the screen. +* Window Hooks:: Hooks for scrolling, window size changes, + redisplay going past a certain point, + or window configuration changes. +@end menu + +@node Basic Windows +@section Basic Concepts of Emacs Windows +@cindex window +@cindex selected window + + A @dfn{window} in Emacs is the physical area of the screen in which a +buffer is displayed. The term is also used to refer to a Lisp object that +represents that screen area in Emacs Lisp. It should be +clear from the context which is meant. + + Emacs groups windows into frames. A frame represents an area of +screen available for Emacs to use. Each frame always contains at least +one window, but you can subdivide it vertically or horizontally into +multiple nonoverlapping Emacs windows. + + In each frame, at any time, one and only one window is designated as +@dfn{selected within the frame}. The frame's cursor appears in that +window, but the other windows have ``non-selected'' cursors, normally +less visible. At any time, one frame is the selected frame; and the +window selected within that frame is @dfn{the selected window}. The +selected window's buffer is usually the current buffer (except when +@code{set-buffer} has been used). @xref{Current Buffer}. + +@defvar cursor-in-non-selected-windows +If this variable is @code{nil}, Emacs displays only one cursor, +in the selected window. Other windows have no cursor at all. +@end defvar + + For practical purposes, a window exists only while it is displayed in +a frame. Once removed from the frame, the window is effectively deleted +and should not be used, @emph{even though there may still be references +to it} from other Lisp objects. Restoring a saved window configuration +is the only way for a window no longer on the screen to come back to +life. (@xref{Deleting Windows}.) + + Each window has the following attributes: + +@itemize @bullet +@item +containing frame + +@item +window height + +@item +window width + +@item +window edges with respect to the screen or frame + +@item +the buffer it displays + +@item +position within the buffer at the upper left of the window + +@item +amount of horizontal scrolling, in columns + +@item +point + +@item +the mark + +@item +how recently the window was selected + +@item +fringe settings + +@item +display margins + +@item +scroll-bar settings +@end itemize + +@cindex multiple windows + Users create multiple windows so they can look at several buffers at +once. Lisp libraries use multiple windows for a variety of reasons, but +most often to display related information. In Rmail, for example, you +can move through a summary buffer in one window while the other window +shows messages one at a time as they are reached. + + The meaning of ``window'' in Emacs is similar to what it means in the +context of general-purpose window systems such as X, but not identical. +The X Window System places X windows on the screen; Emacs uses one or +more X windows as frames, and subdivides them into +Emacs windows. When you use Emacs on a character-only terminal, Emacs +treats the whole terminal screen as one frame. + +@cindex terminal screen +@cindex screen of terminal +@cindex tiled windows + Most window systems support arbitrarily located overlapping windows. +In contrast, Emacs windows are @dfn{tiled}; they never overlap, and +together they fill the whole screen or frame. Because of the way in +which Emacs creates new windows and resizes them, not all conceivable +tilings of windows on an Emacs frame are actually possible. +@xref{Splitting Windows}, and @ref{Size of Window}. + + @xref{Display}, for information on how the contents of the +window's buffer are displayed in the window. + +@defun windowp object +This function returns @code{t} if @var{object} is a window. +@end defun + +@node Splitting Windows +@section Splitting Windows +@cindex splitting windows +@cindex window splitting + + The functions described here are the primitives used to split a window +into two windows. Two higher level functions sometimes split a window, +but not always: @code{pop-to-buffer} and @code{display-buffer} +(@pxref{Displaying Buffers}). + + The functions described here do not accept a buffer as an argument. +The two ``halves'' of the split window initially display the same buffer +previously visible in the window that was split. + +@deffn Command split-window &optional window size horizontal +This function splits a new window out of @var{window}'s screen area. +It returns the new window. + +If @var{horizontal} is non-@code{nil}, then @var{window} splits into +two side by side windows. The original window @var{window} keeps the +leftmost @var{size} columns, and gives the rest of the columns to the +new window. Otherwise, it splits into windows one above the other, and +@var{window} keeps the upper @var{size} lines and gives the rest of the +lines to the new window. The original window is therefore the +left-hand or upper of the two, and the new window is the right-hand or +lower. + +If @var{window} is omitted or @code{nil}, that stands for the selected +window. When you split the selected window, it remains selected. + +If @var{size} is omitted or @code{nil}, then @var{window} is divided +evenly into two parts. (If there is an odd line, it is allocated to +the new window.) When @code{split-window} is called interactively, +all its arguments are @code{nil}. + +If splitting would result in making a window that is smaller than +@code{window-min-height} or @code{window-min-width}, the function +signals an error and does not split the window at all. + +The following example starts with one window on a screen that is 50 +lines high by 80 columns wide; then it splits the window. + +@smallexample +@group +(setq w (selected-window)) + @result{} #<window 8 on windows.texi> +(window-edges) ; @r{Edges in order:} + @result{} (0 0 80 50) ; @r{left--top--right--bottom} +@end group + +@group +;; @r{Returns window created} +(setq w2 (split-window w 15)) + @result{} #<window 28 on windows.texi> +@end group +@group +(window-edges w2) + @result{} (0 15 80 50) ; @r{Bottom window;} + ; @r{top is line 15} +@end group +@group +(window-edges w) + @result{} (0 0 80 15) ; @r{Top window} +@end group +@end smallexample + +The screen looks like this: + +@smallexample +@group + __________ + | | line 0 + | w | + |__________| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 +@end group +@end smallexample + +Next, split the top window horizontally: + +@smallexample +@group +(setq w3 (split-window w 35 t)) + @result{} #<window 32 on windows.texi> +@end group +@group +(window-edges w3) + @result{} (35 0 80 15) ; @r{Left edge at column 35} +@end group +@group +(window-edges w) + @result{} (0 0 35 15) ; @r{Right edge at column 35} +@end group +@group +(window-edges w2) + @result{} (0 15 80 50) ; @r{Bottom window unchanged} +@end group +@end smallexample + +@need 3000 +Now the screen looks like this: + +@smallexample +@group + column 35 + __________ + | | | line 0 + | w | w3 | + |___|______| + | | line 15 + | w2 | + |__________| + line 50 + column 0 column 80 +@end group +@end smallexample + +Normally, Emacs indicates the border between two side-by-side windows +with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|} +characters. The display table can specify alternative border +characters; see @ref{Display Tables}. +@end deffn + +@deffn Command split-window-vertically &optional size +This function splits the selected window into two windows, one above the +other, leaving the upper of the two windows selected, with @var{size} +lines. (If @var{size} is negative, then the lower of the two windows +gets @minus{} @var{size} lines and the upper window gets the rest, but +the upper window is still the one selected.) However, if +@code{split-window-keep-point} (see below) is @code{nil}, then either +window can be selected. + +In other respects, this function is similar to @code{split-window}. +In particular, the upper window is the original one and the return +value is the new, lower window. +@end deffn + +@defopt split-window-keep-point +If this variable is non-@code{nil} (the default), then +@code{split-window-vertically} behaves as described above. + +If it is @code{nil}, then @code{split-window-vertically} adjusts point +in each of the two windows to avoid scrolling. (This is useful on +slow terminals.) It selects whichever window contains the screen line +that point was previously on. + +This variable only affects the behavior of @code{split-window-vertically}. +It has no effect on the other functions described here. +@end defopt + +@deffn Command split-window-horizontally &optional size +This function splits the selected window into two windows +side-by-side, leaving the selected window on the left with @var{size} +columns. If @var{size} is negative, the rightmost window gets +@minus{} @var{size} columns, but the leftmost window still remains +selected. + +This function is basically an interface to @code{split-window}. +You could define a simplified version of the function like this: + +@smallexample +@group +(defun split-window-horizontally (&optional arg) + "Split selected window into two windows, side by side..." + (interactive "P") +@end group +@group + (let ((size (and arg (prefix-numeric-value arg)))) + (and size (< size 0) + (setq size (+ (window-width) size))) + (split-window nil size t))) +@end group +@end smallexample +@end deffn + +@defun one-window-p &optional no-mini all-frames +This function returns non-@code{nil} if there is only one window. The +argument @var{no-mini}, if non-@code{nil}, means don't count the +minibuffer even if it is active; otherwise, the minibuffer window is +counted when it is active. + +The argument @var{all-frames} specifies which frames to consider. Here +are the possible values and their meanings: + +@table @asis +@item @code{nil} +Count the windows in the selected frame, plus the minibuffer used +by that frame even if it lies in some other frame. + +@item @code{t} +Count all windows in all existing frames. + +@item @code{visible} +Count all windows in all visible frames. + +@item 0 +Count all windows in all visible or iconified frames. + +@item anything else +Count precisely the windows in the selected frame, and no others. +@end table +@end defun + +@node Deleting Windows +@section Deleting Windows +@cindex deleting windows + +A window remains visible on its frame unless you @dfn{delete} it by +calling certain functions that delete windows. A deleted window cannot +appear on the screen, but continues to exist as a Lisp object until +there are no references to it. There is no way to cancel the deletion +of a window aside from restoring a saved window configuration +(@pxref{Window Configurations}). Restoring a window configuration also +deletes any windows that aren't part of that configuration. + + When you delete a window, the space it took up is given to one +adjacent sibling. + +@c Emacs 19 feature +@defun window-live-p window +This function returns @code{nil} if @var{window} is deleted, and +@code{t} otherwise. + +@strong{Warning:} Erroneous information or fatal errors may result from +using a deleted window as if it were live. +@end defun + +@deffn Command delete-window &optional window +This function removes @var{window} from display, and returns @code{nil}. +If @var{window} is omitted, then the selected window is deleted. An +error is signaled if there is only one window when @code{delete-window} +is called. +@end deffn + +@deffn Command delete-other-windows &optional window +This function makes @var{window} the only window on its frame, by +deleting the other windows in that frame. If @var{window} is omitted or +@code{nil}, then the selected window is used by default. + +The return value is @code{nil}. +@end deffn + +@deffn Command delete-windows-on buffer-or-name &optional frame +This function deletes all windows showing @var{buffer-or-name}. If +there are no windows showing @var{buffer-or-name}, it does nothing. +@var{buffer-or-name} must be a buffer or the name of an existing +buffer. + +@code{delete-windows-on} operates frame by frame. If a frame has +several windows showing different buffers, then those showing +@var{buffer-or-name} are removed, and the others expand to fill the +space. If all windows in some frame are showing @var{buffer-or-name} +(including the case where there is only one window), then the frame +winds up with a single window showing another buffer chosen with +@code{other-buffer}. @xref{The Buffer List}. + +The argument @var{frame} controls which frames to operate on. This +function does not use it in quite the same way as the other functions +which scan all windows; specifically, the values @code{t} and @code{nil} +have the opposite of their meanings in other functions. Here are the +full details: + +@itemize @bullet +@item +If it is @code{nil}, operate on all frames. +@item +If it is @code{t}, operate on the selected frame. +@item +If it is @code{visible}, operate on all visible frames. +@item +If it is 0, operate on all visible or iconified frames. +@item +If it is a frame, operate on that frame. +@end itemize + +This function always returns @code{nil}. +@end deffn + +@node Selecting Windows +@section Selecting Windows +@cindex selecting a window + + When a window is selected, the buffer in the window becomes the current +buffer, and the cursor will appear in it. + +@defun selected-window +This function returns the selected window. This is the window in +which the cursor appears and to which many commands apply. +@end defun + +@defun select-window window &optional norecord +This function makes @var{window} the selected window. The cursor then +appears in @var{window} (on redisplay). Unless @var{window} was +already selected, @code{select-window} makes @var{window}'s buffer the +current buffer. + +Normally @var{window}'s selected buffer is moved to the front of the +buffer list, but if @var{norecord} is non-@code{nil}, the buffer list +order is unchanged. + +The return value is @var{window}. + +@example +@group +(setq w (next-window)) +(select-window w) + @result{} #<window 65 on windows.texi> +@end group +@end example +@end defun + +@defmac save-selected-window forms@dots{} +This macro records the selected frame, as well as the selected window +of each frame, executes @var{forms} in sequence, then restores the +earlier selected frame and windows. It also saves and restores the +current buffer. It returns the value of the last form in @var{forms}. + +This macro does not save or restore anything about the sizes, +arrangement or contents of windows; therefore, if the @var{forms} +change them, the change persists. If the previously selected window +of some frame is no longer live at the time of exit from @var{forms}, +that frame's selected window is left alone. If the previously +selected window is no longer live, then whatever window is selected at +the end of @var{forms} remains selected. +@end defmac + +@defmac with-selected-window window forms@dots{} +This macro selects @var{window} (without changing the buffer list), +executes @var{forms} in sequence, then restores the previously +selected window and current buffer. It is just like +@code{save-selected-window}, except that it explicitly selects +@var{window}, also without altering the buffer list sequence. +@end defmac + +@cindex finding windows + The following functions choose one of the windows on the screen, +offering various criteria for the choice. + +@defun get-lru-window &optional frame dedicated +This function returns the window least recently ``used'' (that is, +selected). If any full-width windows are present, it only considers +these. The selected window is always the most recently used window. + +The selected window can be the least recently used window if it is the +only window. A newly created window becomes the least recently used +window until it is selected. A minibuffer window is never a +candidate. Dedicated windows are never candidates unless the +@var{dedicated} argument is non-@code{nil}, so if all +existing windows are dedicated, the value is @code{nil}. + +The argument @var{frame} controls which windows are considered. + +@itemize @bullet +@item +If it is @code{nil}, consider windows on the selected frame. +@item +If it is @code{t}, consider windows on all frames. +@item +If it is @code{visible}, consider windows on all visible frames. +@item +If it is 0, consider windows on all visible or iconified frames. +@item +If it is a frame, consider windows on that frame. +@end itemize +@end defun + +@defun get-largest-window &optional frame dedicated +This function returns the window with the largest area (height times +width). If there are no side-by-side windows, then this is the window +with the most lines. A minibuffer window is never a candidate. +Dedicated windows are never candidates unless the +@var{dedicated} argument is non-@code{nil}, so if all existing windows +are dedicated, the value is @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 +(see following section), starting from the selected window. + +The argument @var{frame} controls which set of windows to +consider. See @code{get-lru-window}, above. +@end defun + +@cindex window that satisfies a predicate +@cindex conditional selection of windows +@defun get-window-with-predicate predicate &optional minibuf all-frames default +This function returns a window satisfying @var{predicate}. It cycles +through all visible windows using @code{walk-windows} (@pxref{Cyclic +Window Ordering}), calling @var{predicate} on each one of them +with that window as its argument. The function returns the first +window for which @var{predicate} returns a non-@code{nil} value; if +that never happens, it returns @var{default}. + +The optional arguments @var{minibuf} and @var{all-frames} specify the +set of windows to include in the scan. See the description of +@code{next-window} in @ref{Cyclic Window Ordering}, for details. +@end defun + +@node Cyclic Window Ordering +@comment node-name, next, previous, up +@section Cyclic Ordering of Windows +@cindex cyclic ordering of windows +@cindex ordering of windows, cyclic +@cindex window ordering, cyclic + + When you use the command @kbd{C-x o} (@code{other-window}) to select +the next window, it moves through all the windows on the screen in a +specific cyclic order. For any given configuration of windows, this +order never varies. It is called the @dfn{cyclic ordering of windows}. + + This ordering generally goes from top to bottom, and from left to +right. But it may go down first or go right first, depending on the +order in which the windows were split. + + If the first split was vertical (into windows one above each other), +and then the subwindows were split horizontally, then the ordering is +left to right in the top of the frame, and then left to right in the +next lower part of the frame, and so on. If the first split was +horizontal, the ordering is top to bottom in the left part, and so on. +In general, within each set of siblings at any level in the window tree, +the order is left to right, or top to bottom. + +@defun next-window &optional window minibuf all-frames +@cindex minibuffer window, and @code{next-window} +This function returns the window following @var{window} in the cyclic +ordering of windows. This is the window that @kbd{C-x o} would select +if typed when @var{window} is selected. If @var{window} is the only +window visible, then this function returns @var{window}. If omitted, +@var{window} defaults to the selected window. + +The value of the argument @var{minibuf} determines whether the +minibuffer is included in the window order. Normally, when +@var{minibuf} is @code{nil}, the minibuffer is included if it is +currently active; this is the behavior of @kbd{C-x o}. (The minibuffer +window is active while the minibuffer is in use. @xref{Minibuffers}.) + +If @var{minibuf} is @code{t}, then the cyclic ordering includes the +minibuffer window even if it is not active. + +If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer +window is not included even if it is active. + +The argument @var{all-frames} specifies which frames to consider. Here +are the possible values and their meanings: + +@table @asis +@item @code{nil} +Consider all the windows in @var{window}'s frame, plus the minibuffer +used by that frame even if it lies in some other frame. If the +minibuffer counts (as determined by @var{minibuf}), then all windows on +all frames that share that minibuffer count too. + +@item @code{t} +Consider all windows in all existing frames. + +@item @code{visible} +Consider all windows in all visible frames. (To get useful results, you +must ensure @var{window} is in a visible frame.) + +@item 0 +Consider all windows in all visible or iconified frames. + +@item a frame +Consider all windows on that frame. + +@item anything else +Consider precisely the windows in @var{window}'s frame, and no others. +@end table + +This example assumes there are two windows, both displaying the +buffer @samp{windows.texi}: + +@example +@group +(selected-window) + @result{} #<window 56 on windows.texi> +@end group +@group +(next-window (selected-window)) + @result{} #<window 52 on windows.texi> +@end group +@group +(next-window (next-window (selected-window))) + @result{} #<window 56 on windows.texi> +@end group +@end example +@end defun + +@defun previous-window &optional window minibuf all-frames +This function returns the window preceding @var{window} in the cyclic +ordering of windows. The other arguments specify which windows to +include in the cycle, as in @code{next-window}. +@end defun + +@deffn Command other-window count &optional all-frames +This function selects the @var{count}th following window in the cyclic +order. If count is negative, then it moves back @minus{}@var{count} +windows in the cycle, rather than forward. It returns @code{nil}. + +The argument @var{all-frames} has the same meaning as in +@code{next-window}, but the @var{minibuf} argument of @code{next-window} +is always effectively @code{nil}. + +In an interactive call, @var{count} is the numeric prefix argument. +@end deffn + +@c Emacs 19 feature +@defun walk-windows proc &optional minibuf all-frames +This function cycles through all windows. It calls the function +@code{proc} once for each window, with the window as its sole +argument. + +The optional arguments @var{minibuf} and @var{all-frames} specify the +set of windows to include in the scan. See @code{next-window}, above, +for details. +@end defun + +@defun window-list &optional frame minibuf window +This function returns a list of the windows on @var{frame}, starting +with @var{window}. If @var{frame} is @code{nil} or omitted, +@code{window-list} uses the selected frame instead; if @var{window} is +@code{nil} or omitted, it uses the selected window. + +The value of @var{minibuf} determines if the minibuffer window is +included in the result list. If @var{minibuf} is @code{t}, the result +always includes the minibuffer window. If @var{minibuf} is @code{nil} +or omitted, that includes the minibuffer window if it is active. If +@var{minibuf} is neither @code{nil} nor @code{t}, the result never +includes the minibuffer window. +@end defun + +@node Buffers and Windows +@section Buffers and Windows +@cindex examining windows +@cindex windows, controlling precisely +@cindex buffers, controlled in windows + + This section describes low-level functions to examine windows or to +display buffers in windows in a precisely controlled fashion. +@iftex +See the following section for +@end iftex +@ifnottex +@xref{Displaying Buffers}, for +@end ifnottex +related functions that find a window to use and specify a buffer for it. +The functions described there are easier to use than these, but they +employ heuristics in choosing or creating a window; use these functions +when you need complete control. + +@defun set-window-buffer window buffer-or-name &optional keep-margins +This function makes @var{window} display @var{buffer-or-name} as its +contents. It returns @code{nil}. @var{buffer-or-name} must be a +buffer, or the name of an existing buffer. This is the fundamental +primitive for changing which buffer is displayed in a window, and all +ways of doing that call this function. + +@example +@group +(set-window-buffer (selected-window) "foo") + @result{} nil +@end group +@end example + +Normally, displaying @var{buffer} in @var{window} resets the window's +display margins, fringe widths, scroll bar settings, and position +based on the local variables of @var{buffer}. However, if +@var{keep-margins} is non-@code{nil}, the display margins and fringe +widths of @var{window} remain unchanged. @xref{Fringes}. +@end defun + +@defvar buffer-display-count +This buffer-local variable records the number of times a buffer is +displayed in a window. It is incremented each time +@code{set-window-buffer} is called for the buffer. +@end defvar + +@defun window-buffer &optional window +This function returns the buffer that @var{window} is displaying. If +@var{window} is omitted, this function returns the buffer for the +selected window. + +@example +@group +(window-buffer) + @result{} #<buffer windows.texi> +@end group +@end example +@end defun + +@defun get-buffer-window buffer-or-name &optional all-frames +This function returns a window currently displaying +@var{buffer-or-name}, or @code{nil} if there is none. If there are +several such windows, then the function returns the first one in the +cyclic ordering of windows, starting from the selected window. +@xref{Cyclic Window Ordering}. + +The argument @var{all-frames} controls which windows to consider. + +@itemize @bullet +@item +If it is @code{nil}, consider windows on the selected frame. +@item +If it is @code{t}, consider windows on all frames. +@item +If it is @code{visible}, consider windows on all visible frames. +@item +If it is 0, consider windows on all visible or iconified frames. +@item +If it is a frame, consider windows on that frame. +@end itemize +@end defun + +@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames +This function returns a list of all the windows currently displaying +@var{buffer-or-name}. + +The two optional arguments work like the optional arguments of +@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} +like the single optional argument of @code{get-buffer-window}. Perhaps +we should change @code{get-buffer-window} in the future to make it +compatible with the other functions. +@end defun + +@defvar buffer-display-time +This variable records the time at which a buffer was last made visible +in a window. It is always local in each buffer; each time +@code{set-window-buffer} is called, it sets this variable to +@code{(current-time)} in the specified buffer (@pxref{Time of Day}). +When a buffer is first created, @code{buffer-display-time} starts out +with the value @code{nil}. +@end defvar + +@node Displaying Buffers +@section Displaying Buffers in Windows +@cindex switching to a buffer +@cindex displaying a buffer + + In this section we describe convenient functions that choose a window +automatically and use it to display a specified buffer. These functions +can also split an existing window in certain circumstances. We also +describe variables that parameterize the heuristics used for choosing a +window. +@iftex +See the preceding section for +@end iftex +@ifnottex +@xref{Buffers and Windows}, for +@end ifnottex +low-level functions that give you more precise control. All of these +functions work by calling @code{set-window-buffer}. + + Do not use the functions in this section in order to make a buffer +current so that a Lisp program can access or modify it; they are too +drastic for that purpose, since they change the display of buffers in +windows, which would be gratuitous and surprise the user. Instead, use +@code{set-buffer} and @code{save-current-buffer} (@pxref{Current +Buffer}), which designate buffers as current for programmed access +without affecting the display of buffers in windows. + +@deffn Command switch-to-buffer buffer-or-name &optional norecord +This function makes @var{buffer-or-name} the current buffer, and also +displays the buffer in the selected window. This means that a human can +see the buffer and subsequent keyboard commands will apply to it. +Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} +the current buffer but does not display it in the selected window. +@xref{Current Buffer}. + +If @var{buffer-or-name} does not identify an existing buffer, then a new +buffer by that name is created. The major mode for the new buffer is +set according to the variable @code{default-major-mode}. @xref{Auto +Major Mode}. If @var{buffer-or-name} is @code{nil}, +@code{switch-to-buffer} chooses a buffer using @code{other-buffer}. + +Normally the specified buffer is put at the front of the buffer list +(both the selected frame's buffer list and the frame-independent buffer +list). This affects the operation of @code{other-buffer}. However, if +@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer +List}. + +The @code{switch-to-buffer} function is often used interactively, as +the binding of @kbd{C-x b}. It is also used frequently in programs. It +returns the buffer that it switched to. +@end deffn + +The next two functions are similar to @code{switch-to-buffer}, except +for the described features. + +@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord +This function makes @var{buffer-or-name} the current buffer and +displays it in a window not currently selected. It then selects that +window. The handling of the buffer is the same as in +@code{switch-to-buffer}. + +The currently selected window is absolutely never used to do the job. +If it is the only window, then it is split to make a distinct window for +this purpose. If the selected window is already displaying the buffer, +then it continues to do so, but another window is nonetheless found to +display it in as well. + +This function updates the buffer list just like @code{switch-to-buffer} +unless @var{norecord} is non-@code{nil}. +@end deffn + +@defun pop-to-buffer buffer-or-name &optional other-window norecord +This function makes @var{buffer-or-name} the current buffer and +switches to it in some window, preferably not the window previously +selected. The ``popped-to'' window becomes the selected window within +its frame. The return value is the buffer that was switched to. +If @var{buffer-or-name} is @code{nil}, that means to choose some +other buffer, but you don't specify which. + +If the variable @code{pop-up-frames} is non-@code{nil}, +@code{pop-to-buffer} looks for a window in any visible frame already +displaying the buffer; if there is one, it returns that window and makes +it be selected within its frame. If there is none, it creates a new +frame and displays the buffer in it. + +If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer} +operates entirely within the selected frame. (If the selected frame has +just a minibuffer, @code{pop-to-buffer} operates within the most +recently selected frame that was not just a minibuffer.) + +If the variable @code{pop-up-windows} is non-@code{nil}, windows may +be split to create a new window that is different from the original +window. For details, see @ref{Choosing Window}. + +If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or +creates another window even if @var{buffer-or-name} is already visible +in the selected window. Thus @var{buffer-or-name} could end up +displayed in two windows. On the other hand, if @var{buffer-or-name} is +already displayed in the selected window and @var{other-window} is +@code{nil}, then the selected window is considered sufficient display +for @var{buffer-or-name}, so that nothing needs to be done. + +All the variables that affect @code{display-buffer} affect +@code{pop-to-buffer} as well. @xref{Choosing Window}. + +If @var{buffer-or-name} is a string that does not name an existing +buffer, a buffer by that name is created. The major mode for the new +buffer is set according to the variable @code{default-major-mode}. +@xref{Auto Major Mode}. + +This function updates the buffer list just like @code{switch-to-buffer} +unless @var{norecord} is non-@code{nil}. +@end defun + +@deffn Command replace-buffer-in-windows buffer-or-name +This function replaces @var{buffer-or-name} with some other buffer in all +windows displaying it. It chooses the other buffer with +@code{other-buffer}. In the usual applications of this function, you +don't care which other buffer is used; you just want to make sure that +@var{buffer-or-name} is no longer displayed. + +This function returns @code{nil}. +@end deffn + +@node Choosing Window +@section Choosing a Window for Display + + This section describes the basic facility that chooses a window to +display a buffer in---@code{display-buffer}. All the higher-level +functions and commands use this subroutine. Here we describe how to use +@code{display-buffer} and how to customize it. + +@deffn Command display-buffer buffer-or-name &optional not-this-window frame +This command makes @var{buffer-or-name} appear in some window, like +@code{pop-to-buffer}, but it does not select that window and does not +make the buffer current. The identity of the selected window is +unaltered by this function. @var{buffer-or-name} must be a buffer, or +the name of an existing buffer. + +If @var{not-this-window} is non-@code{nil}, it means to display the +specified buffer in a window other than the selected one, even if it is +already on display in the selected window. This can cause the buffer to +appear in two windows at once. Otherwise, if @var{buffer-or-name} is +already being displayed in any window, that is good enough, so this +function does nothing. + +@code{display-buffer} returns the window chosen to display +@var{buffer-or-name}. + +If the argument @var{frame} is non-@code{nil}, it specifies which frames +to check when deciding whether the buffer is already displayed. If the +buffer is already displayed in some window on one of these frames, +@code{display-buffer} simply returns that window. Here are the possible +values of @var{frame}: + +@itemize @bullet +@item +If it is @code{nil}, consider windows on the selected frame. +(Actually, the last non-minibuffer frame.) +@item +If it is @code{t}, consider windows on all frames. +@item +If it is @code{visible}, consider windows on all visible frames. +@item +If it is 0, consider windows on all visible or iconified frames. +@item +If it is a frame, consider windows on that frame. +@end itemize + +Precisely how @code{display-buffer} finds or creates a window depends on +the variables described below. +@end deffn + +@defopt display-buffer-reuse-frames +If this variable is non-@code{nil}, @code{display-buffer} searches +existing frames for a window displaying the buffer. If the buffer is +already displayed in a window in some frame, @code{display-buffer} makes +the frame visible and raises it, to use that window. If the buffer is +not already displayed, or if @code{display-buffer-reuse-frames} is +@code{nil}, @code{display-buffer}'s behavior is determined by other +variables, described below. +@end defopt + +@defopt pop-up-windows +This variable controls whether @code{display-buffer} makes new windows. +If it is non-@code{nil} and there is only one window, then that window +is split. If it is @code{nil}, then @code{display-buffer} does not +split the single window, but uses it whole. +@end defopt + +@defopt split-height-threshold +This variable determines when @code{display-buffer} may split a window, +if there are multiple windows. @code{display-buffer} always splits the +largest window if it has at least this many lines. If the largest +window is not this tall, it is split only if it is the sole window and +@code{pop-up-windows} is non-@code{nil}. +@end defopt + +@defopt even-window-heights +This variable determines if @code{display-buffer} should even out window +heights if the buffer gets displayed in an existing window, above or +beneath another existing window. If @code{even-window-heights} is +@code{t}, the default, window heights will be evened out. If +@code{even-window-heights} is @code{nil}, the original window heights +will be left alone. +@end defopt + +@c Emacs 19 feature +@defopt pop-up-frames +This variable controls whether @code{display-buffer} makes new frames. +If it is non-@code{nil}, @code{display-buffer} looks for an existing +window already displaying the desired buffer, on any visible frame. If +it finds one, it returns that window. Otherwise it makes a new frame. +The variables @code{pop-up-windows} and @code{split-height-threshold} do +not matter if @code{pop-up-frames} is non-@code{nil}. + +If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either +splits a window or reuses one. + +@xref{Frames}, for more information. +@end defopt + +@c Emacs 19 feature +@defopt pop-up-frame-function +This variable specifies how to make a new frame if @code{pop-up-frames} +is non-@code{nil}. + +Its value should be a function of no arguments. When +@code{display-buffer} makes a new frame, it does so by calling that +function, which should return a frame. The default value of the +variable is a function that creates a frame using parameters from +@code{pop-up-frame-alist}. +@end defopt + +@defopt pop-up-frame-alist +This variable holds an alist specifying frame parameters used when +@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for +more information about frame parameters. +@end defopt + +@defopt special-display-buffer-names +A list of buffer names for buffers that should be displayed specially. +If the buffer's 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 the +list is the buffer name, and the rest of the list says how to create +the frame. There are two possibilities for the rest of the 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 that specify 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 above, under @code{special-display-buffer-names}. +@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 + +@defvar 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}. +@end defvar + +@defun special-display-popup-frame buffer &optional args +This function makes @var{buffer} visible in a frame of its own. If +@var{buffer} is already displayed in a window in some frame, it makes +the frame visible and raises it, to use that window. Otherwise, it +creates a frame that will be dedicated to @var{buffer}. This +function returns the window it used. + +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 called as 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 the buffer's name is in this list, +@code{display-buffer} handles the buffer by switching to it in the +selected window. +@end defopt + +@defopt same-window-regexps +A list of regular expressions that specify buffers that should be +displayed in the selected window. If the buffer's name matches any of +the regular expressions in this list, @code{display-buffer} handles the +buffer by switching to it in the selected window. +@end defopt + +@defun same-window-p buffer-name +This function returns @code{t} if displaying a buffer +named @var{buffer-name} with @code{display-buffer} would +put it in the selected window. +@end defun + +@c Emacs 19 feature +@defvar 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 hook takes precedence over all the other options and hooks +described above. +@end defvar + +@c Emacs 19 feature +@cindex dedicated window +A window can be marked as ``dedicated'' to its buffer. Then +@code{display-buffer} will not try to use that window to display any +other buffer. + +@defun window-dedicated-p window +This function returns non-@code{nil} if @var{window} is marked as +dedicated; otherwise @code{nil}. +@end defun + +@defun set-window-dedicated-p window flag +This function marks @var{window} as dedicated if @var{flag} is +non-@code{nil}, and nondedicated otherwise. +@end defun + +@node Window Point +@section Windows and Point +@cindex window position +@cindex window point +@cindex position in window +@cindex point in window + + Each window has its own value of point, independent of the value of +point in other windows displaying the same buffer. This makes it useful +to have multiple windows showing one buffer. + +@itemize @bullet +@item +The window point is established when a window is first created; it is +initialized from the buffer's point, or from the window point of another +window opened on the buffer if such a window exists. + +@item +Selecting a window sets the value of point in its buffer from the +window's value of point. Conversely, deselecting a window sets the +window's value of point from that of the buffer. Thus, when you switch +between windows that display a given buffer, the point value for the +selected window is in effect in the buffer, while the point values for +the other windows are stored in those windows. + +@item +As long as the selected window displays the current buffer, the window's +point and the buffer's point always move together; they remain equal. +@end itemize + +@noindent +@xref{Positions}, for more details on buffer positions. + +@cindex cursor + As far as the user is concerned, point is where the cursor is, and +when the user switches to another buffer, the cursor jumps to the +position of point in that buffer. + +@defun window-point &optional window +This function returns the current position of point in @var{window}. +For a nonselected window, this is the value point would have (in that +window's buffer) if that window were selected. If @var{window} is +@code{nil}, the selected window is used. + +When @var{window} is the selected window and its buffer is also the +current buffer, the value returned is the same as point in that buffer. + +Strictly speaking, it would be more correct to return the +``top-level'' value of point, outside of any @code{save-excursion} +forms. But that value is hard to find. +@end defun + +@defun set-window-point window position +This function positions point in @var{window} at position +@var{position} in @var{window}'s buffer. It returns @var{position}. + +If @var{window} is selected, and its buffer is current, +this simply does @code{goto-char}. +@end defun + +@node Window Start +@section The Window Start Position +@cindex window start position + + Each window contains a marker used to keep track of a buffer position +that specifies where in the buffer display should start. This position +is called the @dfn{display-start} position of the window (or just the +@dfn{start}). The character after this position is the one that appears +at the upper left corner of the window. It is usually, but not +inevitably, at the beginning of a text line. + +@defun window-start &optional window +@cindex window top line +This function returns the display-start position of window +@var{window}. If @var{window} is @code{nil}, the selected window is +used. For example, + +@example +@group +(window-start) + @result{} 7058 +@end group +@end example + +When you create a window, or display a different buffer in it, the +display-start position is set to a display-start position recently used +for the same buffer, or 1 if the buffer doesn't have any. + +Redisplay updates the window-start position (if you have not specified +it explicitly since the previous redisplay)---for example, to make sure +point appears on the screen. Nothing except redisplay automatically +changes the window-start position; if you move point, do not expect the +window-start position to change in response until after the next +redisplay. + +For a realistic example of using @code{window-start}, see the +description of @code{count-lines}. @xref{Definition of count-lines}. +@end defun + +@defun window-end &optional window update +This function returns the position of the end of the display in window +@var{window}. If @var{window} is @code{nil}, the selected window is +used. + +Simply changing the buffer text or moving point does not update the +value that @code{window-end} returns. The value is updated only when +Emacs redisplays and redisplay completes without being preempted. + +If the last redisplay of @var{window} was preempted, and did not finish, +Emacs does not know the position of the end of display in that window. +In that case, this function returns @code{nil}. + +If @var{update} is non-@code{nil}, @code{window-end} always returns an +up-to-date value for where the window ends, based on the current +@code{window-start} value. If the saved value is valid, +@code{window-end} returns that; otherwise it computes the correct +value by scanning the buffer text. + +Even if @var{update} is non-@code{nil}, @code{window-end} does not +attempt to scroll the display if point has moved off the screen, the +way real redisplay would do. It does not alter the +@code{window-start} value. In effect, it reports where the displayed +text will end if scrolling is not required. +@end defun + +@defun set-window-start window position &optional noforce +This function sets the display-start position of @var{window} to +@var{position} in @var{window}'s buffer. It returns @var{position}. + +The display routines insist that the position of point be visible when a +buffer is displayed. Normally, they change the display-start position +(that is, scroll the window) whenever necessary to make point visible. +However, if you specify the start position with this function using +@code{nil} for @var{noforce}, it means you want display to start at +@var{position} even if that would put the location of point off the +screen. If this does place point off screen, the display routines move +point to the left margin on the middle line in the window. + +For example, if point @w{is 1} and you set the start of the window @w{to +2}, then point would be ``above'' the top of the window. The display +routines will automatically move point if it is still 1 when redisplay +occurs. Here is an example: + +@example +@group +;; @r{Here is what @samp{foo} looks like before executing} +;; @r{the @code{set-window-start} expression.} +@end group + +@group +---------- Buffer: foo ---------- +@point{}This is the contents of buffer foo. +2 +3 +4 +5 +6 +---------- Buffer: foo ---------- +@end group + +@group +(set-window-start + (selected-window) + (1+ (window-start))) +@result{} 2 +@end group + +@group +;; @r{Here is what @samp{foo} looks like after executing} +;; @r{the @code{set-window-start} expression.} +---------- Buffer: foo ---------- +his is the contents of buffer foo. +2 +3 +@point{}4 +5 +6 +---------- Buffer: foo ---------- +@end group +@end example + +If @var{noforce} is non-@code{nil}, and @var{position} would place point +off screen at the next redisplay, then redisplay computes a new window-start +position that works well with point, and thus @var{position} is not used. +@end defun + +@defun pos-visible-in-window-p &optional position window partially +This function returns non-@code{nil} if @var{position} is within the +range of text currently visible on the screen in @var{window}. It +returns @code{nil} if @var{position} is scrolled vertically out of +view. Locations that are partially obscured are not considered +visible unless @var{partially} is non-@code{nil}. The argument +@var{position} defaults to the current position of point in +@var{window}; @var{window}, to the selected window. + +If @var{position} is @code{t}, that means to check the last visible +position in @var{window}. + +The @code{pos-visible-in-window-p} function considers only vertical +scrolling. If @var{position} is out of view only because @var{window} +has been scrolled horizontally, @code{pos-visible-in-window-p} returns +non-@code{nil} anyway. @xref{Horizontal Scrolling}. + +If @var{position} is visible, @code{pos-visible-in-window-p} returns +@code{t} if @var{partially} is @code{nil}; if @var{partially} is +non-@code{nil}, and the character after @var{position} is fully +visible, it returns a list of the form @code{(@var{x} @var{y})}, where +@var{x} and @var{y} are the pixel coordinates relative to the top left +corner of the window; otherwise it returns an extended list of the +form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh} +@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number +of off-window pixels at the top and bottom of the row at +@var{position}, @var{rowh} specifies the visible height of that row, +and @var{vpos} specifies the vertical position (zero-based row number) +of that row. + +Here is an example: + +@example +@group +;; @r{If point is off the screen now, recenter it now.} +(or (pos-visible-in-window-p + (point) (selected-window)) + (recenter 0)) +@end group +@end example +@end defun + +@defun window-line-height &optional line window +This function returns information about text line @var{line} in @var{window}. +If @var{line} is one of @code{header-line} or @code{mode-line}, +@code{window-line-height} returns information about the corresponding +line of the window. Otherwise, @var{line} is a text line number +starting from 0. A negative number counts from the end of the window. +The argument @var{line} defaults to the current line in @var{window}; +@var{window}, to the selected window. + +If the display is not up to date, @code{window-line-height} returns +@code{nil}. In that case, @code{pos-visible-in-window-p} may be used +to obtain related information. + +If there is no line corresponding to the specified @var{line}, +@code{window-line-height} returns @code{nil}. Otherwise, it returns +a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})}, +where @var{height} is the height in pixels of the visible part of the +line, @var{vpos} and @var{ypos} are the vertical position in lines and +pixels of the line relative to the top of the first text line, and +@var{offbot} is the number of off-window pixels at the bottom of the +text line. If there are off-window pixels at the top of the (first) +text line, @var{ypos} is negative. +@end defun + +@node Textual Scrolling +@section Textual Scrolling +@cindex textual scrolling +@cindex scrolling textually + + @dfn{Textual scrolling} means moving the text up or down through a +window. It works by changing the value of the window's display-start +location. It may also change the value of @code{window-point} to keep +point on the screen. + + Textual scrolling was formerly called ``vertical scrolling,'' but we +changed its name to distinguish it from the new vertical fractional +scrolling feature (@pxref{Vertical Scrolling}). + + In the commands @code{scroll-up} and @code{scroll-down}, the directions +``up'' and ``down'' refer to the motion of the text in the buffer at which +you are looking through the window. Imagine that the text is +written on a long roll of paper and that the scrolling commands move the +paper up and down. Thus, if you are looking at text in the middle of a +buffer and repeatedly call @code{scroll-down}, you will eventually see +the beginning of the buffer. + + Some people have urged that the opposite convention be used: they +imagine that the window moves over text that remains in place. Then +``down'' commands would take you to the end of the buffer. This view is +more consistent with the actual relationship between windows and the +text in the buffer, but it is less like what the user sees. The +position of a window on the terminal does not move, and short scrolling +commands clearly move the text up or down on the screen. We have chosen +names that fit the user's point of view. + + The textual scrolling functions (aside from +@code{scroll-other-window}) have unpredictable results if the current +buffer is different from the buffer that is displayed in the selected +window. @xref{Current Buffer}. + + If the window contains a row which is taller than the height of the +window (for example in the presence of a large image), the scroll +functions will adjust the window vscroll to scroll the partially +visible row. To disable this feature, Lisp code may bind the variable +`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}). + +@deffn Command scroll-up &optional count +This function scrolls the text in the selected window upward +@var{count} lines. If @var{count} is negative, scrolling is actually +downward. + +If @var{count} is @code{nil} (or omitted), then the length of scroll +is @code{next-screen-context-lines} lines less than the usable height of +the window (not counting its mode line). + +@code{scroll-up} returns @code{nil}, unless it gets an error +because it can't scroll any further. +@end deffn + +@deffn Command scroll-down &optional count +This function scrolls the text in the selected window downward +@var{count} lines. If @var{count} is negative, scrolling is actually +upward. + +If @var{count} is omitted or @code{nil}, then the length of the scroll +is @code{next-screen-context-lines} lines less than the usable height of +the window (not counting its mode line). + +@code{scroll-down} returns @code{nil}, unless it gets an error because +it can't scroll any further. +@end deffn + +@deffn Command scroll-other-window &optional count +This function scrolls the text in another window upward @var{count} +lines. Negative values of @var{count}, or @code{nil}, are handled +as in @code{scroll-up}. + +You can specify which buffer to scroll by setting the variable +@code{other-window-scroll-buffer} to a buffer. If that buffer isn't +already displayed, @code{scroll-other-window} displays it in some +window. + +When the selected window is the minibuffer, the next window is normally +the one at the top left corner. You can specify a different window to +scroll, when the minibuffer is selected, by setting the variable +@code{minibuffer-scroll-window}. This variable has no effect when any +other window is selected. When it is non-@code{nil} and the +minibuffer is selected, it takes precedence over +@code{other-window-scroll-buffer}. @xref{Definition of +minibuffer-scroll-window}. + +When the minibuffer is active, it is the next window if the selected +window is the one at the bottom right corner. In this case, +@code{scroll-other-window} attempts to scroll the minibuffer. If the +minibuffer contains just one line, it has nowhere to scroll to, so the +line reappears after the echo area momentarily displays the message +@samp{Beginning of buffer}. +@end deffn + +@c Emacs 19 feature +@defvar other-window-scroll-buffer +If this variable is non-@code{nil}, it tells @code{scroll-other-window} +which buffer to scroll. +@end defvar + +@defopt scroll-margin +This option specifies the size of the scroll margin---a minimum number +of lines between point and the top or bottom of a window. Whenever +point gets within this many lines of the top or bottom of the window, +redisplay scrolls the text automatically (if possible) to move point +out of the margin, closer to the center of the window. +@end defopt + +@defopt scroll-conservatively +This variable controls how scrolling is done automatically when point +moves off the screen (or into the scroll margin). If the value is a +positive integer @var{n}, then redisplay scrolls the text up to +@var{n} lines in either direction, if that will bring point back into +proper view. This action is called @dfn{conservative scrolling}. +Otherwise, scrolling happens in the usual way, under the control of +other variables such as @code{scroll-up-aggressively} and +@code{scroll-down-aggressively}. + +The default value is zero, which means that conservative scrolling +never happens. +@end defopt + +@defopt scroll-down-aggressively +The value of this variable should be either @code{nil} or a fraction +@var{f} between 0 and 1. If it is a fraction, that specifies where on +the screen to put point when scrolling down. More precisely, when a +window scrolls down because point is above the window start, the new +start position is chosen to put point @var{f} part of the window +height from the top. The larger @var{f}, the more aggressive the +scrolling. + +A value of @code{nil} is equivalent to .5, since its effect is to center +point. This variable automatically becomes buffer-local when set in any +fashion. +@end defopt + +@defopt scroll-up-aggressively +Likewise, for scrolling up. The value, @var{f}, specifies how far +point should be placed from the bottom of the window; thus, as with +@code{scroll-up-aggressively}, a larger value scrolls more aggressively. +@end defopt + +@defopt scroll-step +This variable is an older variant of @code{scroll-conservatively}. The +difference is that it if its value is @var{n}, that permits scrolling +only by precisely @var{n} lines, not a smaller number. This feature +does not work with @code{scroll-margin}. The default value is zero. +@end defopt + +@defopt scroll-preserve-screen-position +If this option is @code{t}, scrolling which would move the current +point position out of the window chooses the new position of point +so that the vertical position of the cursor is unchanged, if possible. + +If it is non-@code{nil} and not @code{t}, then the scrolling functions +always preserve the vertical position of point, if possible. +@end defopt + +@defopt next-screen-context-lines +The value of this variable is the number of lines of continuity to +retain when scrolling by full screens. For example, @code{scroll-up} +with an argument of @code{nil} scrolls so that this many lines at the +bottom of the window appear instead at the top. The default value is +@code{2}. +@end defopt + +@deffn Command recenter &optional count +@cindex centering point +This function scrolls the text in the selected window so that point is +displayed at a specified vertical position within the window. It does +not ``move point'' with respect to the text. + +If @var{count} is a nonnegative number, that puts the line containing +point @var{count} lines down from the top of the window. If +@var{count} is a negative number, then it counts upward from the +bottom of the window, so that @minus{}1 stands for the last usable +line in the window. If @var{count} is a non-@code{nil} list, then it +stands for the line in the middle of the window. + +If @var{count} is @code{nil}, @code{recenter} puts the line containing +point in the middle of the window, then clears and redisplays the entire +selected frame. + +When @code{recenter} is called interactively, @var{count} is the raw +prefix argument. Thus, typing @kbd{C-u} as the prefix sets the +@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets +@var{count} to 4, which positions the current line four lines from the +top. + +With an argument of zero, @code{recenter} positions the current line at +the top of the window. This action is so handy that some people make a +separate key binding to do this. For example, + +@example +@group +(defun line-to-top-of-window () + "Scroll current line to top of window. +Replaces three keystroke sequence C-u 0 C-l." + (interactive) + (recenter 0)) + +(global-set-key [kp-multiply] 'line-to-top-of-window) +@end group +@end example +@end deffn + +@node Vertical Scrolling +@section Vertical Fractional Scrolling +@cindex vertical fractional scrolling + + @dfn{Vertical fractional scrolling} means shifting the image in the +window up or down by a specified multiple or fraction of a line. +Each window has a @dfn{vertical scroll position}, +which is a number, never less than zero. It specifies how far to raise +the contents of the window. Raising the window contents generally makes +all or part of some lines disappear off the top, and all or part of some +other lines appear at the bottom. The usual value is zero. + + The vertical scroll position is measured in units of the normal line +height, which is the height of the default font. Thus, if the value is +.5, that means the window contents are scrolled up half the normal line +height. If it is 3.3, that means the window contents are scrolled up +somewhat over three times the normal line height. + + What fraction of a line the vertical scrolling covers, or how many +lines, depends on what the lines contain. A value of .5 could scroll a +line whose height is very short off the screen, while a value of 3.3 +could scroll just part of the way through a tall line or an image. + +@defun window-vscroll &optional window pixels-p +This function returns the current vertical scroll position of +@var{window}. If @var{window} is @code{nil}, the selected window is +used. If @var{pixels-p} is non-@code{nil}, the return value is +measured in pixels, rather than in units of the normal line height. + +@example +@group +(window-vscroll) + @result{} 0 +@end group +@end example +@end defun + +@defun set-window-vscroll window lines &optional pixels-p +This function sets @var{window}'s vertical scroll position to +@var{lines}. The argument @var{lines} should be zero or positive; if +not, it is taken as zero. + +If @var{window} is @code{nil}, the selected window is used. + +The actual vertical scroll position must always correspond +to an integral number of pixels, so the value you specify +is rounded accordingly. + +The return value is the result of this rounding. + +@example +@group +(set-window-vscroll (selected-window) 1.2) + @result{} 1.13 +@end group +@end example + +If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of +pixels. In this case, the return value is @var{lines}. +@end defun + +@defvar auto-window-vscroll +If this variable is non-@code{nil}, the line-move, scroll-up, and +scroll-down functions will automatically modify the window vscroll to +scroll through display rows that are taller that the height of the +window, for example in the presence of large images. +@end defvar + +@node Horizontal Scrolling +@section Horizontal Scrolling +@cindex horizontal scrolling + + @dfn{Horizontal scrolling} means shifting the image in the window left +or right by a specified multiple of the normal character width. Each +window has a @dfn{horizontal scroll position}, which is a number, never +less than zero. It specifies how far to shift the contents left. +Shifting the window contents left generally makes all or part of some +characters disappear off the left, and all or part of some other +characters appear at the right. The usual value is zero. + + The horizontal scroll position is measured in units of the normal +character width, which is the width of space in the default font. Thus, +if the value is 5, that means the window contents are scrolled left by 5 +times the normal character width. How many characters actually +disappear off to the left depends on their width, and could vary from +line to line. + + Because we read from side to side in the ``inner loop,'' and from top +to bottom in the ``outer loop,'' the effect of horizontal scrolling is +not like that of textual or vertical scrolling. Textual scrolling +involves selection of a portion of text to display, and vertical +scrolling moves the window contents contiguously; but horizontal +scrolling causes part of @emph{each line} to go off screen. + + Usually, no horizontal scrolling is in effect; then the leftmost +column is at the left edge of the window. In this state, scrolling to +the right is meaningless, since there is no data to the left of the edge +to be revealed by it; so this is not allowed. Scrolling to the left is +allowed; it scrolls the first columns of text off the edge of the window +and can reveal additional columns on the right that were truncated +before. Once a window has a nonzero amount of leftward horizontal +scrolling, you can scroll it back to the right, but only so far as to +reduce the net horizontal scroll to zero. There is no limit to how far +left you can scroll, but eventually all the text will disappear off the +left edge. + +@vindex auto-hscroll-mode + If @code{auto-hscroll-mode} is set, redisplay automatically alters +the horizontal scrolling of a window as necessary to ensure that point +is always visible. However, you can still set the horizontal +scrolling value explicitly. The value you specify serves as a lower +bound for automatic scrolling, i.e. automatic scrolling will not +scroll a window to a column less than the specified one. + +@deffn Command scroll-left &optional count set-minimum +This function scrolls the selected window @var{count} columns to the +left (or to the right if @var{count} is negative). The default +for @var{count} is the window width, minus 2. + +The return value is the total amount of leftward horizontal scrolling in +effect after the change---just like the value returned by +@code{window-hscroll} (below). + +Once you scroll a window as far right as it can go, back to its normal +position where the total leftward scrolling is zero, attempts to scroll +any farther right have no effect. + +If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes +the lower bound for automatic scrolling; that is, automatic scrolling +will not scroll a window to a column less than the value returned by +this function. Interactive calls pass non-@code{nil} for +@var{set-minimum}. +@end deffn + +@deffn Command scroll-right &optional count set-minimum +This function scrolls the selected window @var{count} columns to the +right (or to the left if @var{count} is negative). The default +for @var{count} is the window width, minus 2. Aside from the direction +of scrolling, this works just like @code{scroll-left}. +@end deffn + +@defun window-hscroll &optional window +This function returns the total leftward horizontal scrolling of +@var{window}---the number of columns by which the text in @var{window} +is scrolled left past the left margin. + +The value is never negative. It is zero when no horizontal scrolling +has been done in @var{window} (which is usually the case). + +If @var{window} is @code{nil}, the selected window is used. + +@example +@group +(window-hscroll) + @result{} 0 +@end group +@group +(scroll-left 5) + @result{} 5 +@end group +@group +(window-hscroll) + @result{} 5 +@end group +@end example +@end defun + +@defun set-window-hscroll window columns +This function sets horizontal scrolling of @var{window}. The value of +@var{columns} specifies the amount of scrolling, in terms of columns +from the left margin. The argument @var{columns} should be zero or +positive; if not, it is taken as zero. Fractional values of +@var{columns} are not supported at present. + +Note that @code{set-window-hscroll} may appear not to work if you test +it by evaluating a call with @kbd{M-:} in a simple way. What happens +is that the function sets the horizontal scroll value and returns, but +then redisplay adjusts the horizontal scrolling to make point visible, +and this overrides what the function did. You can observe the +function's effect if you call it while point is sufficiently far from +the left margin that it will remain visible. + +The value returned is @var{columns}. + +@example +@group +(set-window-hscroll (selected-window) 10) + @result{} 10 +@end group +@end example +@end defun + + Here is how you can determine whether a given position @var{position} +is off the screen due to horizontal scrolling: + +@example +@group +(defun hscroll-on-screen (window position) + (save-excursion + (goto-char position) + (and + (>= (- (current-column) (window-hscroll window)) 0) + (< (- (current-column) (window-hscroll window)) + (window-width window))))) +@end group +@end example + +@node Size of Window +@section The Size of a Window +@cindex window size +@cindex size of window + + An Emacs window is rectangular, and its size information consists of +the height (the number of lines) and the width (the number of character +positions in each line). The mode line is included in the height. But +the width does not count the scroll bar or the column of @samp{|} +characters that separates side-by-side windows. + + The following three functions return size information about a window: + +@defun window-height &optional window +This function returns the number of lines in @var{window}, including +its mode line and header line, if any. If @var{window} fills its +entire frame except for the echo area, this is typically one less than +the value of @code{frame-height} on that frame. + +If @var{window} is @code{nil}, the function uses the selected window. + +@example +@group +(window-height) + @result{} 23 +@end group +@group +(split-window-vertically) + @result{} #<window 4 on windows.texi> +@end group +@group +(window-height) + @result{} 11 +@end group +@end example +@end defun + +@defun window-body-height &optional window +Like @code{window-height} but the value does not include the +mode line (if any) or the header line (if any). +@end defun + +@defun window-width &optional window +This function returns the number of columns in @var{window}. If +@var{window} fills its entire frame, this is the same as the value of +@code{frame-width} on that frame. The width does not include the +window's scroll bar or the column of @samp{|} characters that separates +side-by-side windows. + +If @var{window} is @code{nil}, the function uses the selected window. + +@example +@group +(window-width) + @result{} 80 +@end group +@end example +@end defun + +@defun window-full-width-p &optional window +This function returns non-@code{nil} if @var{window} is as wide as +the frame that contains it; otherwise @code{nil}. +If @var{window} is @code{nil}, the function uses the selected window. +@end defun + +@defun window-edges &optional window +This function returns a list of the edge coordinates of @var{window}. +If @var{window} is @code{nil}, the selected window is used. + +The order of the list is @code{(@var{left} @var{top} @var{right} +@var{bottom})}, all elements relative to 0, 0 at the top left corner of +the frame. The element @var{right} of the value is one more than the +rightmost column used by @var{window}, and @var{bottom} is one more than +the bottommost row used by @var{window} and its mode-line. + +The edges include the space used by the window's scroll bar, display +margins, fringes, header line, and mode line, if it has them. Also, +if the window has a neighbor on the right, its right edge value +includes the width of the separator line between the window and that +neighbor. Since the width of the window does not include this +separator, the width does not usually equal the difference between the +right and left edges. +@end defun + +@defun window-inside-edges &optional window +This is similar to @code{window-edges}, but the edge values +it returns include only the text area of the window. They +do not include the header line, mode line, scroll bar or +vertical separator, fringes, or display margins. +@end defun + +Here are the results obtained on a typical 24-line terminal with just +one window, with menu bar enabled: + +@example +@group +(window-edges (selected-window)) + @result{} (0 1 80 23) +@end group +@group +(window-inside-edges (selected-window)) + @result{} (0 1 80 22) +@end group +@end example + +@noindent +The bottom edge is at line 23 because the last line is the echo area. +The bottom inside edge is at line 22, which is the window's mode line. + +If @var{window} is at the upper left corner of its frame, and there is +no menu bar, then @var{bottom} returned by @code{window-edges} is the +same as the value of @code{(window-height)}, @var{right} is almost the +same as the value of @code{(window-width)}, and @var{top} and +@var{left} are zero. For example, the edges of the following window +are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 +columns, the last column of the window (column 7) holds a border +rather than text. The last row (row 4) holds the mode line, shown +here with @samp{xxxxxxxxx}. + +@example +@group + 0 + _______ + 0 | | + | | + | | + | | + xxxxxxxxx 4 + + 7 +@end group +@end example + +In the following example, let's suppose that the frame is 7 +columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} +and the edges of the right window are @w{@samp{4 0 7 3}}. +The inside edges of the left window are @w{@samp{0 0 3 2}}, +and the inside edges of the right window are @w{@samp{4 0 7 2}}, + +@example +@group + ___ ___ + | | | + | | | + xxxxxxxxx + + 0 34 7 +@end group +@end example + +@defun window-pixel-edges &optional window +This function is like @code{window-edges} except that, on a graphical +display, the edge values are measured in pixels instead of in +character lines and columns. +@end defun + +@defun window-inside-pixel-edges &optional window +This function is like @code{window-inside-edges} except that, on a +graphical display, the edge values are measured in pixels instead of +in character lines and columns. +@end defun + +@node Resizing Windows +@section Changing the Size of a Window +@cindex window resizing +@cindex resize window +@cindex changing window size +@cindex window size, changing + + The window size functions fall into two classes: high-level commands +that change the size of windows and low-level functions that access +window size. Emacs does not permit overlapping windows or gaps between +windows, so resizing one window affects other windows. + +@deffn Command enlarge-window size &optional horizontal +This function makes the selected window @var{size} lines taller, +stealing lines from neighboring windows. It takes the lines from one +window at a time until that window is used up, then takes from another. +If a window from which lines are stolen shrinks below +@code{window-min-height} lines, that window disappears. + +If @var{horizontal} is non-@code{nil}, this function makes +@var{window} wider by @var{size} columns, stealing columns instead of +lines. If a window from which columns are stolen shrinks below +@code{window-min-width} columns, that window disappears. + +If the requested size would exceed that of the window's frame, then the +function makes the window occupy the entire height (or width) of the +frame. + +If there are various other windows from which lines or columns can be +stolen, and some of them specify fixed size (using +@code{window-size-fixed}, see below), they are left untouched while +other windows are ``robbed.'' If it would be necessary to alter the +size of a fixed-size window, @code{enlarge-window} gets an error +instead. + +If @var{size} is negative, this function shrinks the window by +@minus{}@var{size} lines or columns. If that makes the window smaller +than the minimum size (@code{window-min-height} and +@code{window-min-width}), @code{enlarge-window} deletes the window. + +@code{enlarge-window} returns @code{nil}. +@end deffn + +@deffn Command enlarge-window-horizontally columns +This function makes the selected window @var{columns} wider. +It could be defined as follows: + +@example +@group +(defun enlarge-window-horizontally (columns) + (interactive "p") + (enlarge-window columns t)) +@end group +@end example +@end deffn + +@deffn Command shrink-window size &optional horizontal +This function is like @code{enlarge-window} but negates the argument +@var{size}, making the selected window smaller by giving lines (or +columns) to the other windows. If the window shrinks below +@code{window-min-height} or @code{window-min-width}, then it disappears. + +If @var{size} is negative, the window is enlarged by @minus{}@var{size} +lines or columns. +@end deffn + +@deffn Command shrink-window-horizontally columns +This function makes the selected window @var{columns} narrower. +It could be defined as follows: + +@example +@group +(defun shrink-window-horizontally (columns) + (interactive "p") + (shrink-window columns t)) +@end group +@end example +@end deffn + +@defun adjust-window-trailing-edge window delta horizontal +This function makes the selected window @var{delta} lines taller or +@var{delta} columns wider, by moving the bottom or right edge. This +function does not delete other windows; if it cannot make the +requested size adjustment, it signals an error. On success, this +function returns @code{nil}. +@end defun + +@defun fit-window-to-buffer &optional window max-height min-height +This function makes @var{window} the right height to display its +contents exactly. If @var{window} is omitted or @code{nil}, it uses +the selected window. + +The argument @var{max-height} specifies the maximum height the window +is allowed to be; @code{nil} means use the frame height. The argument +@var{min-height} specifies the minimum height for the window; +@code{nil} means use @code{window-min-height}. All these height +values include the mode-line and/or header-line. +@end defun + +@deffn Command shrink-window-if-larger-than-buffer &optional window +This command shrinks @var{window} vertically to be as small as +possible while still showing the full contents of its buffer---but not +less than @code{window-min-height} lines. If @var{window} is not +given, it defaults to the selected window. + +However, the command does nothing if the window is already too small to +display the whole text of the buffer, or if part of the contents are +currently scrolled off screen, or if the window is not the full width of +its frame, or if the window is the only window in its frame. + +This command returns non-@code{nil} if it actually shrank the window +and @code{nil} otherwise. +@end deffn + +@defvar window-size-fixed +If this variable is non-@code{nil}, in any given buffer, +then the size of any window displaying the buffer remains fixed +unless you explicitly change it or Emacs has no other choice. + +If the value is @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +This variable automatically becomes buffer-local when set. + +Explicit size-change functions such as @code{enlarge-window} +get an error if they would have to change a window size which is fixed. +Therefore, when you want to change the size of such a window, +you should bind @code{window-size-fixed} to @code{nil}, like this: + +@example +(let ((window-size-fixed nil)) + (enlarge-window 10)) +@end example + +Note that changing the frame size will change the size of a +fixed-size window, if there is no other alternative. +@end defvar + +@cindex minimum window size + The following two variables constrain the window-structure-changing +functions to a minimum height and width. + +@defopt window-min-height +The value of this variable determines how short a window may become +before it is automatically deleted. Making a window smaller than +@code{window-min-height} automatically deletes it, and no window may +be created shorter than this. The default value is 4. + +The absolute minimum window height is one; actions that change window +sizes reset this variable to one if it is less than one. +@end defopt + +@defopt window-min-width +The value of this variable determines how narrow a window may become +before it is automatically deleted. Making a window smaller than +@code{window-min-width} automatically deletes it, and no window may be +created narrower than this. The default value is 10. + +The absolute minimum window width is two; actions that change window +sizes reset this variable to two if it is less than two. +@end defopt + +@node Coordinates and Windows +@section Coordinates and Windows + +This section describes how to relate screen coordinates to windows. + +@defun window-at x y &optional frame +This function returns the window containing the specified cursor +position in the frame @var{frame}. The coordinates @var{x} and @var{y} +are measured in characters and count from the top left corner of the +frame. If they are out of range, @code{window-at} returns @code{nil}. + +If you omit @var{frame}, the selected frame is used. +@end defun + +@defun coordinates-in-window-p coordinates window +This function checks whether a particular frame position falls within +the window @var{window}. + +The argument @var{coordinates} is a cons cell of the form @code{(@var{x} +. @var{y})}. The coordinates @var{x} and @var{y} are measured in +characters, and count from the top left corner of the screen or frame. + +The value returned by @code{coordinates-in-window-p} is non-@code{nil} +if the coordinates are inside @var{window}. The value also indicates +what part of the window the position is in, as follows: + +@table @code +@item (@var{relx} . @var{rely}) +The coordinates are inside @var{window}. The numbers @var{relx} and +@var{rely} are the equivalent window-relative coordinates for the +specified position, counting from 0 at the top left corner of the +window. + +@item mode-line +The coordinates are in the mode line of @var{window}. + +@item header-line +The coordinates are in the header line of @var{window}. + +@item vertical-line +The coordinates are in the vertical line between @var{window} and its +neighbor to the right. This value occurs only if the window doesn't +have a scroll bar; positions in a scroll bar are considered outside the +window for these purposes. + +@item left-fringe +@itemx right-fringe +The coordinates are in the left or right fringe of the window. + +@item left-margin +@itemx right-margin +The coordinates are in the left or right margin of the window. + +@item nil +The coordinates are not in any part of @var{window}. +@end table + +The function @code{coordinates-in-window-p} does not require a frame as +argument because it always uses the frame that @var{window} is on. +@end defun + +@node Window Tree +@section The Window Tree +@cindex window tree + + A @dfn{window tree} specifies the layout, size, and relationship +between all windows in one frame. + +@defun window-tree &optional frame +This function returns the window tree for frame @var{frame}. +If @var{frame} is omitted, the selected frame is used. + +The return value is a list of the form @code{(@var{root} @var{mini})}, +where @var{root} represents the window tree of the frame's +root window, and @var{mini} is the frame's minibuffer window. + +If the root window is not split, @var{root} is the root window itself. +Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} +@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, +and @code{t} for a vertical split, @var{edges} gives the combined size and +position of the subwindows in the split, and the rest of the elements +are the subwindows in the split. Each of the subwindows may again be +a window or a list representing a window split, and so on. The +@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} +similar to the value returned by @code{window-edges}. +@end defun + +@node Window Configurations +@section Window Configurations +@cindex window configurations +@cindex saving window information + + A @dfn{window configuration} records the entire layout of one +frame---all windows, their sizes, which buffers they contain, what +part of each buffer is displayed, and the values of point and the +mark; also their fringes, margins, and scroll bar settings. It also +includes the values of @code{window-min-height}, +@code{window-min-width} and @code{minibuffer-scroll-window}. An +exception is made for point in the selected window for the current +buffer; its value is not saved in the window configuration. + + You can bring back an entire previous layout by restoring a window +configuration previously saved. If you want to record all frames +instead of just one, use a frame configuration instead of a window +configuration. @xref{Frame Configurations}. + +@defun current-window-configuration &optional frame +This function returns a new object representing @var{frame}'s current +window configuration. If @var{frame} is omitted, the selected frame +is used. +@end defun + +@defun set-window-configuration configuration +This function restores the configuration of windows and buffers as +specified by @var{configuration}, for the frame that @var{configuration} +was created for. + +The argument @var{configuration} must be a value that was previously +returned by @code{current-window-configuration}. This configuration is +restored in the frame from which @var{configuration} was made, whether +that frame is selected or not. This always counts as a window size +change and triggers execution of the @code{window-size-change-functions} +(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't +know how to tell whether the new configuration actually differs from the +old one. + +If the frame which @var{configuration} was saved from is dead, all this +function does is restore the three variables @code{window-min-height}, +@code{window-min-width} and @code{minibuffer-scroll-window}. In this +case, the function returns @code{nil}. Otherwise, it returns @code{t}. + +Here is a way of using this function to get the same effect +as @code{save-window-excursion}: + +@example +@group +(let ((config (current-window-configuration))) + (unwind-protect + (progn (split-window-vertically nil) + @dots{}) + (set-window-configuration config))) +@end group +@end example +@end defun + +@defspec save-window-excursion forms@dots{} +This special form records the window configuration, executes @var{forms} +in sequence, then restores the earlier window configuration. The window +configuration includes, for each window, the value of point and the +portion of the buffer that is visible. It also includes the choice of +selected window. However, it does not include the value of point in +the current buffer; use @code{save-excursion} also, if you wish to +preserve that. + +Don't use this construct when @code{save-selected-window} is sufficient. + +Exit from @code{save-window-excursion} always triggers execution of the +@code{window-size-change-functions}. (It doesn't know how to tell +whether the restored configuration actually differs from the one in +effect at the end of the @var{forms}.) + +The return value is the value of the final form in @var{forms}. +For example: + +@example +@group +(split-window) + @result{} #<window 25 on control.texi> +@end group +@group +(setq w (selected-window)) + @result{} #<window 19 on control.texi> +@end group +@group +(save-window-excursion + (delete-other-windows w) + (switch-to-buffer "foo") + 'do-something) + @result{} do-something + ;; @r{The screen is now split again.} +@end group +@end example +@end defspec + +@defun window-configuration-p object +This function returns @code{t} if @var{object} is a window configuration. +@end defun + +@defun compare-window-configurations config1 config2 +This function compares two window configurations as regards the +structure of windows, but ignores the values of point and mark and the +saved scrolling positions---it can return @code{t} even if those +aspects differ. + +The function @code{equal} can also compare two window configurations; it +regards configurations as unequal if they differ in any respect, even a +saved point or mark. +@end defun + +@defun window-configuration-frame config +This function returns the frame for which the window configuration +@var{config} was made. +@end defun + + Other primitives to look inside of window configurations would make +sense, but are not implemented because we did not need them. See the +file @file{winner.el} for some more operations on windows +configurations. + +@node Window Hooks +@section Hooks for Window Scrolling and Changes +@cindex hooks for window operations + +This section describes how a Lisp program can take action whenever a +window displays a different part of its buffer or a different buffer. +There are three actions that can change this: scrolling the window, +switching buffers in the window, and changing the size of the window. +The first two actions run @code{window-scroll-functions}; the last runs +@code{window-size-change-functions}. + +@defvar window-scroll-functions +This variable holds a list of functions that Emacs should call before +redisplaying a window with scrolling. It is not a normal hook, because +each function is called with two arguments: the window, and its new +display-start position. + +Displaying a different buffer in the window also runs these functions. + +These functions must be careful in using @code{window-end} +(@pxref{Window Start}); if you need an up-to-date value, you must use +the @var{update} argument to ensure you get it. + +@strong{Warning:} don't use this feature to alter the way the window +is scrolled. It's not designed for that, and such use probably won't +work. +@end defvar + +@defvar window-size-change-functions +This variable holds a list of functions to be called if the size of any +window changes for any reason. The functions are called just once per +redisplay, and just once for each frame on which size changes have +occurred. + +Each function receives the frame as its sole argument. There is no +direct way to find out which windows on that frame have changed size, or +precisely how. However, if a size-change function records, at each +call, the existing windows and their sizes, it can also compare the +present sizes and the previous sizes. + +Creating or deleting windows counts as a size change, and therefore +causes these functions to be called. Changing the frame size also +counts, because it changes the sizes of the existing windows. + +It is not a good idea to use @code{save-window-excursion} (@pxref{Window +Configurations}) in these functions, because that always counts as a +size change, and it would cause these functions to be called over and +over. In most cases, @code{save-selected-window} (@pxref{Selecting +Windows}) is what you need here. +@end defvar + +@defvar redisplay-end-trigger-functions +This abnormal hook is run whenever redisplay in a window uses text that +extends past a specified end trigger position. You set the end trigger +position with the function @code{set-window-redisplay-end-trigger}. The +functions are called with two arguments: the window, and the end trigger +position. Storing @code{nil} for the end trigger position turns off the +feature, and the trigger value is automatically reset to @code{nil} just +after the hook is run. +@end defvar + +@defun set-window-redisplay-end-trigger window position +This function sets @var{window}'s end trigger position at +@var{position}. +@end defun + +@defun window-redisplay-end-trigger &optional window +This function returns @var{window}'s current end trigger position. +If @var{window} is @code{nil} or omitted, it uses the selected window. +@end defun + +@defvar window-configuration-change-hook +A normal hook that is run every time you change the window configuration +of an existing frame. This includes splitting or deleting windows, +changing the sizes of windows, or displaying a different buffer in a +window. The frame whose window configuration has changed is the +selected frame when this hook runs. +@end defvar + +@ignore + arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 +@end ignore