Windows
*******

This chapter describes the functions and variables related to Emacs windows.  See Frames, for how windows are assigned an area of screen available for Emacs to use.  See Display, for information on how text is displayed in windows.

Basic Concepts of Emacs Windows
===============================

A window in Emacs is the physical area of the screen in which a buffer is displayed, see Buffers.  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; see Frames.  Each frame always contains at least one window, but you can subdivide it into multiple, non-overlapping Emacs 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.

Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are tiled; they never overlap, and together they fill the whole screen or frame.  Because of the way in which Emacs creates new windows (see Splitting Windows) and resizes them (see Resizing Windows), not all conceivable tilings of windows on an Emacs frame are actually possible.

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, even though the Lisp object representing it might be still referenced from other Lisp objects; see Deleting Windows.  Restoring a saved window configuration is the only way for a window no longer on the screen to come back to life; see Window Configurations.

 -- Function: windowp object
     This function returns t if OBJECT is a window, nil otherwise.  It can return t if OBJECT denotes a window that has been deleted.

For historical reasons a window is considered live if and only if it currently displays a buffer; see Buffers and Windows.  In order to show multiple windows within one and the same frame, Emacs organizes them in form of a tree called window tree; see Windows and Frames.  The internal nodes of a window tree are called internal windows and are not considered live.  The leaf nodes of a window tree constitute the windows displaying buffers and only they will be called live here.

 -- Function: window-live-p object
     This function returns t if OBJECT is a live window and nil otherwise.  A live window is a window that displays a buffer.

 -- Function: window-any-p object
     This function returns t if OBJECT denotes a live or an internal window and nil otherwise.  In particular, this function returns nil if OBJECT is a window that has been deleted.

In each frame, at any time, one and only one window is designated as selected within the frame.  Also, at any time, one frame is the selected frame (see Input Focus).  The window selected within the selected frame is the selected window.

The selected window is always a live window.  Its buffer is usually the current buffer (except when set-buffer has been used); see Current Buffer.

 -- Function: selected-window
     This function returns the selected window.  This is the window in which the cursor for selected windows (see Cursor Parameters) appears and to which many commands apply.

The window handling functions can be roughly grouped into functions operating on live windows only and functions that accept any window as argument.  Many of these functions accept as argument the value nil to specify the selected window.  The two functions below can be used to ``normalize'' arguments specifying windows in a uniform manner.

 -- Function: window-normalize-any-window window
     This function returns the normalized value for WINDOW which can be any window that has not been deleted.  More precisely, if WINDOW is nil, it returns the selected window.  If WINDOW denotes a live or internal window, it returns that window.  Otherwise, this function signals an error.

 -- Function: window-normalize-live-window window
     This functions returns the normalized value for a live window WINDOW.  More precisely, if WINDOW is nil, it returns the selected window.  If WINDOW is a live window, it returns that window.  Otherwise, this function signals an error.

Windows and Frames
==================

Each window is part of one and only one frame (see Frames); you can get that frame with the function described next.

 -- Function: window-frame window
     This function returns the frame that WINDOW is on.  The argument WINDOW can be any window and defaults to the selected one.

The following function returns a list of all live windows on a specific frame.

 -- Function: window-list &optional frame minibuf window
     This function returns a list of FRAME's live windows, starting with WINDOW.  The optional argument FRAME has to denote a live frame and defaults to the selected frame.  The optional argument WINDOW has to denote a live window on the frame specified by FRAME and defaults to the selected one.

     The argument MINIBUF specifies if the minibuffer window shall be included in the return value.  If MINIBUF is t, the result always includes the minibuffer window.  If MINIBUF is nil or omitted, that includes the minibuffer window only if it is active. If MINIBUF is neither nil nor t, the result never includes the minibuffer window.

Windows within one and the same frame are organized in form of a tree called window tree.  The leaf nodes of a window tree constitute the windows visible to the user.  These are the windows associated with buffers and are usually called live windows.  The internal nodes of a window tree are needed for finding, traversing and displaying the live windows.

A minibuffer window (see Minibuffer Windows) is not considered part of its frame's window tree unless the frame is a minibuffer-only frame.  Most functions covered in this section accept, however, the minibuffer window as argument.  Also, the minibuffer window is listed by the function window-tree described at the end of this section.

A window tree is rooted at the root window of its frame.

 -- Function: frame-root-window &optional frame-or-window
     This function returns the root window of FRAME-OR-WINDOW.  The argument FRAME-OR-WINDOW has to denote either a window or a frame and defaults to the selected frame.  If FRAME-OR-WINDOW denotes a window, the return value is the root window of that window's frame. This function always returns a window; a live window if the frame specified by FRAME-OR-WINDOW contains no other live windows and an internal window otherwise.

All other windows of a frame with the exception of the minibuffer window are subwindows of the frame's root window.  A window is considered a subwindow of another window if it occupies a part of that other window's screen area.

The functions described next allow to access the members of a window tree and take an arbitrary window as argument.

 -- Function: window-parent &optional window
     Return WINDOW's parent in the window tree.  The optional argument WINDOW can denote an arbitrary window and defaults to the selected one.  The return value is nil if WINDOW is a minibuffer window or the root window of its frame and an internal window otherwise.

Parent windows do not appear on the screen.  The screen area of a parent window is the rectangular part of the window's frame occupied by the window's child windows, that is, the set of windows having that window as their parent.  Each parent window has at least two child windows, so there are no ``Matryoshka'' windows.  Minibuffer windows do not have child windows.

The children of any parent window form either a vertical or a horizontal combination of windows.  A vertical combination is a set of windows arranged one above each other.  A horizontal combination is a set of windows arranged side by side.  Consider the frame shown below (for simplicity we assume that the frame does not contain a minibuffer window):

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      ||| ___________  ___________ |||
         ||      ||||           ||           ||||
         ||      ||||           ||           ||||
         ||      ||||_____W6____||_____W7____||||
         ||      |||____________W4____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

The root window of the frame is W1---a horizontal combination of the live window W2 and the internal window W3.  Hence (window-parent W1) is nil while (window-parent W2) and (window-parent W3) are both W1.

The internal window W3 is a vertical combination of W4 and the live window W5.  The internal window W4 is a horizontal combination of the live windows W6 and W7.  The windows you can actually see on the screen are W2, W5, W6 and W7.

For any parent window, the first child window can be retrieved by the functions given next.

 -- Function: window-top-child &optional window
     This function returns WINDOW's first vertical child window.  The optional argument WINDOW can be an arbitrary window and defaults to the selected one.  The return value is nil if WINDOW is a live window or its children form a horizontal combination.  In the example above (window-top-child W3) is W4 while (window-top-child W4) is nil.

 -- Function: window-left-child &optional window
     This function returns WINDOW's first horizontal child window.  The optional argument WINDOW can be an arbitrary window and defaults to the selected one.  The return value is nil if WINDOW is a live window or its children form a vertical combination.  In the example above (window-left-child W4) is W6 while (window-left-child W3) is nil.

 -- Function: window-child window
     This function return WINDOW's first child window.  The return value is nil if WINDOW is a live window.  In the example above (window-child W3) is W4 while (window-child W4) is W6.

The following function is useful to determine whether a window is part of a vertical or horizontal combination.

 -- Function: window-iso-combined-p &optional window horizontal
     This function returns non-nil if and only if WINDOW is vertically combined.  The argument WINDOW can specify any window and defaults to the selected one.  The actual return value is the first vertical child of window.

     If the optional argument HORIZONTAL is non-nil, this means to return non-nil if and only if WINDOW is horizontally combined.  In this case, the return value is the first horizontal child of window.

For any window that is part of a combination, the other windows in that combination are called the window's siblings.  The only windows that do not have siblings are root windows of frames and minibuffer windows.  A window's siblings can be retrieved with the following two functions.

 -- Function: window-next-sibling &optional window
     This function returns WINDOW's next sibling.  The optional argument WINDOW can be an arbitrary window and defaults to the selected window.  It returns nil if WINDOW is the last child of its parent.  In our example (window-next-sibling W2) is W3 while (window-next-sibling W3) is nil.

 -- Function: window-prev-sibling &optional window
     This function returns WINDOW's previous sibling.  The optional argument WINDOW can be an arbitrary window and defaults to the selected window.  It returns nil if WINDOW is the first child of its parent. In our example (window-prev-sibling W3) is W2 and (window-prev-sibling W2) is nil.

The functions window-next-sibling and window-prev-sibling should not be confused with the functions next-window and previous-window which respectively return the next and previous window in the cyclic ordering of windows, see Cyclic Window Ordering.

In order to find the first live window on a frame, the following function can be used.

 -- Function: frame-first-window &optional frame-or-window
     This function returns the live window at the upper left corner of the frame specified by FRAME-OR-WINDOW.  The argument FRAME-OR-WINDOW must denote a window or a live frame and defaults to the selected frame.  If FRAME-OR-WINDOW specifies a window, this function returns the first window on that window's frame.  Under the assumption that the frame from our canonical example is selected (frame-first-window) returns W2.

You can get the window tree of a frame with the following function.

 -- Function: window-tree &optional frame
     This function returns the window tree for frame FRAME.  The optional argument FRAME must be a live frame and defaults to the selected one.

     The return value is a list of the form (ROOT MINI), where ROOT represents the window tree of the frame's root window, and MINI is the frame's minibuffer window.

     If the root window is live, ROOT specifies the root window and nothing else.  Otherwise, ROOT is a list (DIR EDGES W1 W2 ...) where DIR is nil for a horizontal combination, and t for a vertical combination, EDGES gives the size and position of the combination, and the remaining elements are the child windows.  Each child window may again be a live window or a list representing a window combination, and so on. The EDGES element is a list (LEFT TOP RIGHT BOTTOM) similar to the value returned by window-edges, see Coordinates and Windows.

Window Sizes
============

Emacs windows are rectangular.  The structure of a live window can be roughly sketched as follows:

              _________________________________________
           ^ |______________ Header Line_______________|
           | |LS|LF|LM|                       |RM|RF|RS| ^
           | |  |  |  |                       |  |  |  | |
      Window |  |  |  |       Text Area       |  |  |  | Window
      Total  |  |  |  |     (Window Body)     |  |  |  | Body
      Height |  |  |  |                       |  |  |  | Height
           | |  |  |  |<- Window Body Width ->|  |  |  | |
           | |__|__|__|_______________________|__|__|__| v
           v |_______________ Mode Line _______________|

              <----------- Window Total Width -------->

The text area constitutes the body of the window.  In its most simple form, a window consists of its body alone.  LS and RS stand for the left and right scroll bar (see Scroll Bars) respectively.  Only one of them can be present at any time.  LF and RF denote the left and right fringe, see Fringes.  LM and RM, finally, stand for the left and right display margin, see Display Margins.  The header line, if present, is located above theses areas, the mode line below, see Mode Line Format.

The total height of a window is specified as the total number of lines occupied by the window.  Any mode or header line is included in a window's total height.  For an internal window, the total height is calculated recursively from the total heights of its child windows.

The total width of a window denotes the total number of columns of the window.  Any scroll bar and the column of | characters that separate the window from its right sibling are included in a window's total width.  On a window-system, fringes and display margins are included in a window's total width too.  For an internal window, the total width is calculated recursively from the total widths of its child windows.

The following function is the standard interface for getting the total size of any window:

 -- Function: window-total-size &optional window &optional horizontal
     This function returns the total number of lines of WINDOW.  The argument WINDOW can denote any window and defaults to the selected one.  If WINDOW is live, the return value includes any header or mode lines of WINDOW.  If WINDOW is internal, the return value is the sum of the total heights of WINDOW's child windows provided these are vertically combined and the height of WINDOW's first child if they are horizontally combined.

     If the optional argument HORIZONTAL is non-nil, this function returns the total number of columns of WINDOW.  If WINDOW is live, the return value includes any vertical divider column or scroll bars of WINDOW.  On a window-system, the return value includes the space occupied by any margins and fringes of WINDOW too.  If WINDOW is internal, the return value is the sum of the total widths of WINDOW's child windows provided these are horizontally combined and the width of WINDOW's first child otherwise.

Alternatively, the following two functions can be used to retrieve either the total height or the total width of a window:

 -- Function: window-total-height &optional window
     This function returns the total number of lines of WINDOW. WINDOW can be any window and defaults to the selected one.  The return value includes WINDOW's mode line and header line, if any. If WINDOW is internal the return value is the sum of heights of WINDOW's child windows for a vertical combination and the height of WINDOW's first child otherwise.

 -- Function: window-total-width &optional window
     This function returns the total number of columns of WINDOW. WINDOW can be any window and defaults to the selected one.  The return value includes any vertical dividers or scrollbars of WINDOW.  On a window-system the return value also includes the space occupied by any margins and fringes of WINDOW.  If WINDOW is internal, the return value is the sum of the widths of WINDOW's child windows for a horizontal combination and the width of WINDOW's first child otherwise.

The total height of any window is usually less than the height of the window's frame, because the latter may also include the minibuffer window.  Depending on the toolkit in use, the frame height can also include the menu bar and the tool bar (see Size and Position). Therefore, in general it is not straightforward to compare window and frame heights.  The following function is useful to determine whether there are no other windows above or below a specified window.

 -- Function: window-full-height-p &optional window
     This function returns non-nil if there is no other window above or below WINDOW on the containing frame.  More precisely, this function returns t if and only if the total height of WINDOW equals the total height of the root window (see Windows and Frames) of WINDOW's frame.  The WINDOW argument may denote any window and defaults to the selected one.

The following function can be used to determine whether there are no other windows on the left or right of a specified window.

 -- Function: window-full-width-p &optional window
     This function returns non-nil if there are no other windows on the left or right of WINDOW; nil otherwise.  More precisely, this function returns t if and only if the total width of WINDOW equals the total width of the root window (see Windows and Frames) of WINDOW's frame.  The WINDOW argument may denote any window and defaults to the selected one.

The windows of a frame are unambiguously characterized by the combination of their top line and left column within that frame.

 -- Function: window-top-line &optional window
     This function returns the top line of WINDOW.  The argument WINDOW can denote any window and defaults to the selected one.

 -- Function: window-left-column &optional window
     This function returns the left column of WINDOW.  The argument WINDOW can denote any window and defaults to the selected one.

For a frame displaying one window only, that window's top line and left column are both zero.  When a frame displays a window WB below a window WA, the top line of WB can be calculated by adding the total height of WA to the top line of WA.  When a frame displays a window WR on the right of a window WL, the left column of WR can be calculated by adding the total width of WL to the left column of WL.

The body height of a window is specified as the total number of lines occupied by the window's text area.  Mode or header lines are not included in a window's body height.

The body width of a window denotes the total number of columns occupied by the window's text area.  Scroll bars or columns of | characters that separate side-by-side windows are not included in a window's body width.

The following functions retrieve height and width of the body of a live window:

 -- Function: window-body-size &optional window horizontal
     This function returns the number of lines of WINDOW's text area. WINDOW must be a live window and defaults to the selected one. The return value does not count any mode or header line of WINDOW.

     Optional argument HORIZONTAL non-nil means to return the number of columns of WINDOW's text area.  In this case the return value does not include any vertical divider or scroll bar owned by WINDOW.  On a window-system the return value does not include the number of columns used for WINDOW's fringes or display margins either.

 -- Function: window-body-height &optional window
     This function returns the number of lines of WINDOW's body. WINDOW must be a live window and defaults to the selected one.

     The return value does not include WINDOW's mode line and header line, if any.  If a line at the bottom of the window is only partially visible, that line is included in the return value.  If you do not want to include a partially visible bottom line in the return value, use window-text-height instead.

 -- Function: window-body-width &optional window
     This function returns the number of columns of WINDOW's body. WINDOW must be a live window and defaults to the selected one.

     The return value does not include any vertical dividers or scroll bars owned by WINDOW.  On a window-system the return value does not include the number of columns used for WINDOW's fringes or display margins either.

The following functions have been used in earlier versions of Emacs. They are still supported but due to the confusing nomenclature they should not be used any more in future code.

 -- Function: window-height &optional window
     This function is an alias for `window-total-height', see above.

 -- Function: window-width &optional window
     This function is an alias for `window-body-width', see above.

The following two options constrain the sizes of windows to a minimum height and width.  Their values are honored when windows are split (see Splitting Windows) or resized (see Resizing Windows).  Any request to make a window smaller than specified here will usually result in an error.

 -- User Option: window-min-height
     The value of this variable specifies how short a window may be.  The value is measured in line units and has to account for any header or mode line.  The default value for this option is 4.  Values less than 1 are ignored.

 -- User Option: window-min-width
     The value of this variable specifies how narrow a window may be.  The value is measured in characters and includes any margins, fringes, scroll bar and vertical divider column.  The default value for this option is 10.  A value less than 2 is ignored.

Applications should not rebind these variables.  To shrink a specific window to a height or width less than the one specified here, they should rather invoke window-resize (see Resizing Windows) with a non-nil IGNORE argument.  The function split-window (see Splitting Windows) can make a window smaller than specified here by calling it with a non-nil SIZE argument.  Interactively, the values specified here cannot be overridden.

Earlier versions of Emacs could delete a window when its size dropped below window-min-height or window-min-width.  As a rule, the current version of Emacs does no more delete windows by side-effect. The only exception to this rule are requests to resize a frame which may implicitly delete windows when they do not fit on the frame any more, see Size and Position.

The size of a window can be fixed which means that it cannot be split (see Splitting Windows) or resized (see Resizing Windows).

 -- Variable: window-size-fixed
     If this variable is non-nil, in a given buffer, then the size of any window displaying that buffer remains fixed unless you either explicitly change it or Emacs has no other choice.

     If the value is height, then only the window's height is fixed; if the value is width, then only the window's width is fixed. Any other non-nil value fixes both the width and the height.

     This variable automatically becomes buffer-local when set.

Commands supposed to explicitly change the size of windows such as enlarge-window (see Resizing Windows) get an error if they had to change a window size which is fixed.  Other functions like window-resize (see Resizing Windows) have an optional IGNORE argument which allows to change the size of fixed-size windows.

Deleting a window or changing a frame's size may change the size of a fixed-size window, if there is no other alternative.

The height of a vertical combination of windows cannot be changed when the height of all these windows is fixed.  Its width cannot be changed if the width of at least one of these windows is fixed. Similarly, the width of a horizontal combination of windows cannot be changed when the width of all these windows is fixed.  Its height cannot be changed if the height of at least one of these windows is fixed.

The next function allows to check whether the size of an arbitrary window is fixed.

 -- Function: window-size-fixed-p &optional window horizontal
     This function returns non-nil if WINDOW's height is fixed. The argument WINDOW can be an arbitrary window and defaults to the selected one.  Optional argument HORIZONTAL non-nil means return non-nil if WINDOW's width is fixed.

     If this function returns nil, this does not necessarily mean that WINDOW can be resized in the desired direction.  The function window-resizable (see Resizing Windows) can tell that.

Resizing Windows
================

Emacs does not permit overlapping windows or gaps between windows, so changing the size of a window always affects at least one other window. When a frame contains just one window, that window can be resized only by resizing the window's frame.  The functions described below are therefore meaningful only in the context of a frame containing at least two windows.  The size of the corresponding frame never changes when invoking a function described in this section.

The routines changing window sizes always operate in one dimension at a time.  This means that windows can be resized only either vertically or horizontally.  If a window shall be resized in both dimensions, it must be resized in one dimension first and in the other dimension afterwards.  If the second resize operation fails, the frame might end up in an unsatisfactory state.  To avoid such states, it might be useful to save the current window configuration (see Window Configurations) before attempting the first resize operation and restore the saved configuration in case the second resize operation fails.

Functions that resize windows are supposed to obey restrictions imposed by window minimum sizes and fixed-size windows, see Window Sizes.  In order to determine whether resizing a specific window is possible in the first place, the following function can be used:

 -- Function: window-resizable window delta &optional horizontal ignore side noup nodown
     This function returns DELTA if the size of WINDOW can be changed vertically by DELTA lines.  Optional argument HORIZONTAL non-nil means to return DELTA if WINDOW can be resized horizontally by DELTA columns.  A return value of zero means that WINDOW is not resizable.

     If DELTA is a positive number, this means that WINDOW shall be enlarged by DELTA lines or columns.  If WINDOW cannot be enlarged by DELTA lines or columns, this function returns the maximum value in the range from 0 to DELTA by which WINDOW can be enlarged.

     If DELTA is a negative number, this means that WINDOW shall be shrunk by -DELTA lines or columns.  If WINDOW cannot be shrunk by -DELTA lines or columns, this function returns the minimum value in the range from DELTA to 0 that can be used for shrinking WINDOW.

     Optional argument IGNORE non-nil means ignore any restrictions imposed by the variables window-min-height or window-min-width and window-size-fixed.  In this case the minimum height of a window is specified as the minimum number of lines that allow viewing any header or mode line and at least one line of the text area of window.  The minimum width of a window includes any fringes, margins and the scroll bar as well as two text columns.

     If IGNORE denotes a window, this means to ignore restrictions for that window only.  If IGNORE equals the constant safe, this means a live window may get as small as one line or two columns.

     Optional argument NOUP non-nil means don't go up in the window tree but try to steal or distribute the space needed for the resize operation among the other windows within WINDOW's combination.  Optional argument NODOWN non-nil means don't check whether WINDOW itself and its subwindows can be resized.

The function window-resizable does not change any window sizes. The following function does:

 -- Function: window-resize window delta &optional horizontal ignore
     This function resizes WINDOW vertically by DELTA lines.  The argument WINDOW can denote an arbitrary window and defaults to the selected one.  An attempt to resize the root window of a frame will raise an error.

     Second argument DELTA a positive number means WINDOW shall be enlarged by DELTA lines.  If DELTA is negative, that means WINDOW shall be shrunk by -DELTA lines.

     Optional argument HORIZONTAL non-nil means to resize WINDOW horizontally by DELTA columns.  In this case a positive DELTA means enlarge WINDOW by DELTA columns. A negative DELTA means WINDOW shall be shrunk by -DELTA columns.

     Optional argument IGNORE has the same meaning as for the function window-resizable above.

     This function can simultaneously move two edges of WINDOW.  Exactly which edges of WINDOW are moved and which other windows are resized along with WINDOW is determined by the splits and nest status of the involved windows (see Splitting Windows).  If only the low (right) edge of WINDOW shall be moved, the function adjust-window-trailing-edge described below should be used.

The next four commands are simple interfaces to window-resize. They always operate on the selected window, never delete any window, and always raise an error when resizing would violate a restriction imposed by window-min-height, window-min-width, or window-size-fixed.

 -- Command: enlarge-window delta &optional horizontal
     This function makes the selected window DELTA lines taller. Interactively, if no argument is given, it makes the selected window one line taller.  If optional argument HORIZONTAL is non-nil, it makes the selected window wider by DELTA columns.  If DELTA is negative, it shrinks the selected window by -DELTA lines or columns.  The return value is nil.

 -- Command: enlarge-window-horizontally delta
     This function makes the selected window DELTA columns wider. Interactively, if no argument is given, it makes the selected window one column wider.

 -- Command: shrink-window delta &optional horizontal
     This function makes the selected window DELTA lines smaller. Interactively, if no argument is given, it makes the selected window one line smaller.  If optional argument HORIZONTAL is non-nil, it makes the selected window narrower by DELTA columns.  If DELTA is negative, it enlarges the selected window by -DELTA lines or columns.  The return value is nil.

 -- Command: shrink-window-horizontally delta
     This function makes the selected window DELTA columns narrower. Interactively, if no argument is given, it makes the selected window one column narrower.

The following function is useful for moving the line dividing two windows.

 -- Function: adjust-window-trailing-edge window delta &optional horizontal
     This function moves WINDOW's bottom edge by DELTA lines. Optional argument HORIZONTAL non-nil means to move WINDOW's right edge by DELTA columns.  The argument WINDOW defaults to the selected window.

     If DELTA is greater zero, this moves the edge downwards or to the right.  If DELTA is less than zero, this moves the edge upwards or to the left. If the edge can't be moved by DELTA lines or columns, it is moved as far as possible in the desired direction but no error is signalled.

     This function tries to resize windows adjacent to the edge that is moved.  Only if this is insufficient, it will also resize windows not adjacent to that edge.  As a consequence, if you move an edge in one direction and back in the other direction by the same amount, the resulting window configuration will not be necessarily identical to the one before the first move.  So if your intend to just resize WINDOW, you should not use this function but call window-resize (see above) instead.

 -- Command: fit-window-to-buffer &optional window max-height min-height override
     This command makes WINDOW the right height to display its contents exactly.  The default for WINDOW is the selected window.

     The optional argument MAX-HEIGHT specifies the maximum total height the window is allowed to be; nil means use the maximum permissible height of a window on WINDOW's frame.  The optional argument MIN-HEIGHT specifies the minimum toatl height for the window; nil means use window-min-height.  All these height values include the mode line and/or header line.

     If the optional argument OVERRIDE is non-nil, this means to ignore any restrictions imposed by window-min-height and window-min-width on the size of WINDOW.

     This function returns non-nil if it orderly resized WINDOW, and nil otherwise.

 -- Command: shrink-window-if-larger-than-buffer &optional window
     This command shrinks WINDOW vertically to be as small as possible while still showing the full contents of its buffer---but not less than window-min-height lines.  The argument WINDOW must denote a live window and defaults to the selected one.

     However, this 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-nil if it actually shrank the window and nil otherwise.

Emacs provides two functions to balance windows, that is, to even out the sizes of all windows on the same frame.  The minibuffer window and fixed-size windows are not resized by these functions.

 -- Command: balance-windows &optional window-or-frame
     This function balances windows in a way that gives more space to full-width and/or full-height windows.  If WINDOW-OR-FRAME specifies a frame, it balances all windows on that frame.  If WINDOW-OR-FRAME specifies a window, it balances that window and its siblings (see Windows and Frames) only.

 -- Command: balance-windows-area
     This function attempts to give all windows on the selected frame approximately the same share of the screen area.  This means that full-width or full-height windows are not given more space than other windows.

The following function can be used to give a window the maximum possible size without deleting other ones.

 -- Command: maximize-window &optional window
     This function maximizes WINDOW.  More precisely, this makes WINDOW as large as possible without resizing its frame or deleting other windows.  WINDOW can be any window and defaults to the selected one.

To make a window as small as possible without deleting it the following function can be used.

 -- Command: minimize-window &optional window
     This function minimizes WINDOW.  More precisely, this makes WINDOW as small as possible without deleting it or resizing its frame.  WINDOW can be any window and defaults to the selected one.

Splitting Windows
=================

The functions described below are the primitives needed for creating a new window.  They do not accept a buffer as an argument.  Rather, they ``split'' an existing window into two halves, both displaying the buffer previously visible in the window that was split.

 -- Command: split-window &optional window size side
     This function creates a new window adjacent to WINDOW.  It returns the new window which is always a live window.  The argument WINDOW can denote any window and defaults to the selected one.  This function does not change the selected window.

     Optional second argument SIZE a positive number means make WINDOW SIZE lines (or columns) tall.  If SIZE is negative, make the new window -SIZE lines (or columns) tall.  If SIZE is omitted or nil, then WINDOW is divided evenly into two parts.  (If there is an odd line, it is allocated to the new window.)

     If splitting would result in making a window smaller than window-min-height or window-min-width (see Window Sizes), this function usually signals an error.  However, if SIZE is non-nil and valid, a new window of the requested size is created.  (A size value would be invalid if it assigned less than one line or less than two columns to the new window.)

     Optional third argument SIDE nil (or below) specifies that the new window shall be located below WINDOW.  The value above means the new window will be located above WINDOW.  In both cases SIZE specifies the new number of lines for WINDOW (or the new window if SIZE is negative) including space reserved for the mode and/or header line.

     If SIDE is t or right the new window will be positioned on the right side of WINDOW.  The value left means the new window will be located on the left side of WINDOW. In both cases SIZE specifies the new number of columns for WINDOW (or the new window provided SIZE is negative) including space reserved for margins, fringes and the scroll bar or a divider column.

     Any other non-nil value for SIDE is currently handled like t (or right).  Since this might change in the future, application programs should refrain from using other values.

     If WINDOW is live, properties of the new window like margins and scroll bars are inherited from WINDOW.  If WINDOW is an internal window, these properties, as well as the buffer shown in the new window, are inherited from the window selected on WINDOW's frame.

     If ignore-window-parameters is non-nil, this function ignores window parameters (see Window Parameters).  Otherwise, if the split-window parameter of WINDOW is t, it splits the window disregarding any other window parameters.  If the split-window parameter specifies a function, that function is called with the arguments WINDOW, SIZE, and SIDE to split WINDOW.  If that function is ignore, nothing is done.

The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then it splits the window.

     (setq W1 (selected-window))
          => #<window 8 on windows.texi>
     (setq W2 (split-window W1 15))
          => #<window 28 on windows.texi>

     (window-top-line W1)
          => 0
     (window-total-size W1)
          => 15
     (window-top-line W2)
          => 15

The screen looks like this:

              __________
             |          |  line 0
             |    W1    |
             |__________|
             |          |  line 15
             |    W2    |
             |__________|
                           line 50
      column 0   column 80

Next, split the top window into two side-by-side windows:

     (setq W3 (split-window W1 35 t))
          => #<window 32 on windows.texi>

     (window-left-column W1)
          => 0
     (window-total-size W1 t)
          => 35
     (window-left-column W3)
          => 35

Now the screen looks like this:

          column 35
              __________
             |    |     |  line 0
             | W1 |  W3 |
             |____|_____|
             |          |  line 15
             |    W2    |
             |__________|
                           line 50
      column 0   column 80

Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (see Scroll Bars), or with | characters.  The display table can specify alternative border characters; see Display Tables.

Below we describe how split-window can be used to create the window configuration from our earlier example (see Windows and Frames) and how internal windows are created for this purpose.  We start with a frame containing one live window W2 (in the following scenarios window names are assigned in an arbitrary manner in order to match the names of the example).  Evaluating the form (split-window W2 8 t) creates a new internal window W1 with two children---W2 (the window we've split) and a new leaf window W6:

          ______________________________________
         | ______  ____________________________ |
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||      ||                            ||
         ||__W2__||_____________W6_____________ |
         |__________________W1__________________|

Evaluating now (split-window W6 -3) creates another internal window W3 with two children---W6 and a new live window W5.  This leaves us with a vertically combined window W3 embedded in the horizontally combined window W1:

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||                          |||
         ||      |||____________W6____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

Finally, evaluating (split-window W6 nil t) should get us the desired configuration as depicted below.

          ______________________________________
         | ______  ____________________________ |
         ||      || __________________________ ||
         ||      ||| ___________  ___________ |||
         ||      ||||           ||           ||||
         ||      ||||           ||           ||||
         ||      ||||_____W6____||_____W7____||||
         ||      |||____________W4____________|||
         ||      || __________________________ ||
         ||      |||                          |||
         ||      |||____________W5____________|||
         ||__W2__||_____________W3_____________ |
         |__________________W1__________________|

The scenario sketched above is the standard way to obtain the desired configuration.  In Emacs 23 it was also the only way to do that since Emacs 23 did't allow splitting internal windows.

With Emacs 24 you can also proceed as follows: Split an initial window W6 by evaluating (split-window W6 -3) to produce the following vertical combination:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W6_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W5_________________||
         |__________________W3__________________|

Evaluating now (split-window (window-parent W6) -8 'left) or, equivalently, (split-window W3 -8 'left) should now produce the penultimate configuration from the previous scenario from where we can continue as described before.

Another strategy starts with splitting an initial window W6 by evaluating (split-window W6 nil nil t) with the following result:

          ______________________________________
         | _________________  _________________ |
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||                 ||                 ||
         ||________W6_______||________W7_______||
         |__________________W4__________________|

Evaluating now (split-window W4 -3) or (split-window (window-parent W6) -3) should get us a configuration as shown next.

          ______________________________________
         | ____________________________________ |
         || ________________  ________________ ||
         |||                ||                |||
         |||                ||                |||
         |||                ||                |||
         |||                ||                |||
         |||                ||                |||
         |||_______W6_______||________W7______|||
         ||_________________W4_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W5_________________||
         |__________________W3__________________|

The desired configuration can be now obtained by evaluating (split-window W3 -8 'left) or, equivalently, (split-window (window-parent W5) -8 'left).

For a final approach let's start with the configuration of two live windows W6 and W7 shown above.  If we now evaluate (split-window W4 -8 'left) or (split-window (window-parent W6) -8 'left) we get the following configuration.

          ______________________________________
         | ______  ____________________________ |
         ||      || ____________  ____________ ||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||            ||            |||
         ||      |||______W6____||______W7____|||
         ||__W2__||_____________W4_____________||
         |__________________W1__________________|

Evaluating now (split-window W4 -3) or, for example, (split-window (window-parent W6) -3) should produce the desired configuration.

The two options described next can be used to tune the operation of split-window.

 -- User Option: window-splits
     If this variable is nil, the function split-window can split a window if and only if that window's screen estate is sufficiently large to accommodate both--itself and the new window.

     If this variable is non-nil, split-window tries to resize all windows that are part of the same combination as the old window to accommodate the new window.  Hence, the new window can be also created if the old window is of fixed size or too small to split (see Window Sizes).

     In any case, the value of this variable is assigned to the splits status of the new window and, provided old and new window form a new combination, of the old window as well.  The splits status of a window can be retrieved by invoking the function window-splits and altered by the function set-window-splits described next.

     If window-nest (see below) is non-nil, the space for the new window is exclusively taken from the old window, but the splits status of the involved windows is nevertheless set as described here.

 -- Function: window-splits &optional window
     This function returns the splits status of WINDOW.  The argument WINDOW can be any window and defaults to the selected one.

     The splits status of a window specifies how resizing and deleting that window may affect the size of other windows in the same window combination.  More precisely, if WINDOW's splits status is nil and WINDOW is resized, the corresponding space is preferably taken from (or given to) WINDOW's right sibling.  When WINDOW is deleted, its space is given to its left sibling.  If WINDOW's splits status is non-nil, resizing and deleting WINDOW may resize all windows in WINDOW's combination.

     The splits status is initially set by split-window from the current value of the variable window-splits (see above) and can be reset by the function set-window-splits (see below).

 -- Function: set-window-splits window &optional status
     This function sets the splits status (see above) of WINDOW to STATUS.  The argument WINDOW can be any window and defaults to the selected one.  The return value is STATUS.

To illustrate the use of window-splits consider the following window configuration:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

Splitting window W3 with window-splits nil produces a configuration where the size of W2 remains unchanged:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W3_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W4_________________||
         |__________________W1__________________|

Splitting W3 with window-splits non-nil instead produces a configuration where all windows have approximately the same height:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         |__________________W1__________________|

 -- User Option: window-nest
     If this variable is nil, split-window creates a new parent window if and only if the old window has no parent window or shall be split orthogonally to the combination it is part of.  If this variable is non-nil, split-window always creates a new parent window.  If this variable is always non-nil, a frame's window tree is a binary tree so every window but the frame's root window has exactly one sibling.

     The value of this variable is also assigned to the nest status of the new parent window.  The nest status of any window can be retrieved via the function window-nest and altered by the function set-window-nest, see below.

 -- Function: window-nest &optional window
     This function returns the nest status of WINDOW.  The argument WINDOW can be any window and defaults to the selected one.  Note, however, that the nest status is currently meaningful for internal windows only.

     The nest status of a window specifies whether that window may be removed and its subwindows recombined with that window's siblings when such a sibling's subwindow is deleted.  The nest status is initially assigned by split-window from the current value of the variable window-nest (see above) and can be reset by the function set-window-nest (see below).

     If the return value is nil, subwindows of WINDOW may be recombined with WINDOW's siblings when a window gets deleted.  A return value of nil means that subwindows of WINDOW are never (re-)combined with WINDOW's siblings in such a case.

 -- Function: set-window-nest window &optional status
     This functions sets the nest status (see above) of WINDOW to STATUS.  The argument WINDOW can be any window and defaults to the selected one.  Note that setting the nest status is meaningful for internal windows only.  The return value is STATUS.

To illustrate the use of window-nest consider the following configuration (throughout the following examples we shall assume that window-splits invariantly is nil).

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

Splitting W2 into two windows above each other with window-nest equal nil will get you a configuration like:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

If you now enlarge window W4, Emacs steals the necessary space from window W3 resulting in a configuration like:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W4_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

Deleting window W4, will return its space to W2 as follows:

          ______________________________________
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||                                    ||
         ||_________________W2_________________||
         | ____________________________________ |
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

Hence, with respect to the initial configuration, window W2 has grown at the expense of window W3.  If, however, in the initial configuration you had split W2 with window-nest bound to t, a new internal window W5 would have been created as depicted below.

          ______________________________________
         | ____________________________________ |
         || __________________________________ ||
         |||                                  |||
         |||________________W2________________|||
         || __________________________________ ||
         |||                                  |||
         |||________________W4________________|||
         ||_________________W5_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

Enlarging W4 would now have stolen the necessary space from W2 instead of W3 as

          ______________________________________
         | ____________________________________ |
         || __________________________________ ||
         |||________________W2________________|||
         || __________________________________ ||
         |||                                  |||
         |||                                  |||
         |||________________W4________________|||
         ||_________________W5_________________||
         | ____________________________________ |
         ||                                    ||
         ||                                    ||
         ||_________________W3_________________||
         |__________________W1__________________|

and the subsequent deletion of W4 would have restored the initial configuration.

For interactive use, Emacs provides two commands which always split the selected window.

 -- Command: split-window-above-each-other &optional size
     This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with SIZE lines.  (If SIZE is negative, then the lower of the two windows gets -SIZE lines and the upper window gets the rest, but the upper window is still the one selected.)  However, if split-window-keep-point (see below) is nil, then either window can be selected.

     In other respects, this function is similar to split-window. In particular, the upper window is the original one and the return value is the new, lower window.

 -- User Option: split-window-keep-point
     If this variable is non-nil (the default), then split-window-above-each-other behaves as described above.

     If it is nil, then split-window-above-each-other 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.  Other functions are not affected by this variable.

 -- Command: split-window-side-by-side &optional size
     This function splits the selected window into two windows side-by-side, leaving the selected window on the left with SIZE columns.  If SIZE is negative, the rightmost window gets -SIZE columns, but the leftmost window still remains selected.

Deleting Windows
================

A window remains visible on its frame unless you 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 (see Window Configurations).  Restoring a window configuration also deletes any windows that aren't part of that configuration.  Erroneous information may result from using a deleted window as if it were live.

 -- Command: delete-window &optional window
     This function removes WINDOW from display and returns nil. The argument WINDOW can denote any window and defaults to the selected one.  An error is signaled if WINDOW is the only window on its frame.  Hence WINDOW must have at least one sibling window (see Windows and Frames) in order to get deleted.

     If the variable ignore-window-parameters (see Window Parameters) is non-nil, this function ignores all parameters of WINDOW.  Otherwise, if the delete-window parameter of WINDOW is t, it deletes the window disregarding other window parameters.  If the delete-window parameter specifies a function, that function is called with WINDOW as its sole argument.

     If the splits status of WINDOW (see Splitting Windows) is nil, the space WINDOW took up is given to its left sibling if such a window exists and to its right sibling otherwise.  If the splits status of WINDOW is non-nil, its space is proportionally distributed among the remaining windows in the same combination.

 -- Command: delete-other-windows &optional window
     This function makes WINDOW fill its frame and returns nil. The argument WINDOW can denote an arbitrary window and defaults to the selected one.

     If the variable ignore-window-parameters (see Window Parameters) is non-nil, this function ignores all parameters of WINDOW.  Otherwise, if the delete-other-windows parameter of WINDOW equals t, it deletes all other windows disregarding any remaining window parameters.  If the delete-other-windows parameter of WINDOW specifies a function, it calls that function with WINDOW as its sole argument.

 -- Command: delete-windows-on &optional buffer-or-name frame
     This function deletes all windows showing BUFFER-OR-NAME and returns nil.  If there are no windows showing BUFFER-OR-NAME, it does nothing.  The optional argument BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer.  Invoking this command on a minibuffer signals an error.

     The function delete-windows-on operates by calling delete-window for each window showing BUFFER-OR-NAME.  If a frame has several windows showing different buffers, then those showing BUFFER-OR-NAME are removed, and the other windows expand to fill the space.

     If all windows in some frame are showing BUFFER-OR-NAME (including the case where there is only one window), then that frame is deleted provided there are other frames left.

     The optional argument FRAME specifies which frames to operate on. This function does not use it in quite the same way as the other functions which scan all live windows (see Cyclic Window Ordering); specifically, the values t and nil have the opposite of their meanings in the other functions.  Here are the full details:

       * nil means operate on all frames.

       * t means operate on the selected frame.

       * visible means operate on all visible frames.

       * 0 means operate on all visible or iconified frames.

       * A frame means operate on that frame.

Selecting Windows
=================

 -- Function: select-window window &optional norecord
     This function makes WINDOW the selected window, see Basic Windows.  Unless WINDOW already is the selected window, this also makes WINDOW's buffer (see Buffers and Windows) the current buffer.  Moreover, the cursor for selected windows will be displayed in WINDOW after the next redisplay.  This function returns WINDOW.

     Normally, WINDOW's selected buffer is moved to the front of the buffer list (see The Buffer List) and WINDOW becomes the most recently selected window.  But if the optional argument NORECORD is non-nil, the buffer list remains unchanged and WINDOW does not become the most recently selected one.

The sequence of calls to select-window with a non-nil NORECORD argument determines an ordering of windows by their selection time.  The function get-lru-window can be used to retrieve the least recently selected live window in this ordering, see Cyclic Window Ordering.

 -- Macro: save-selected-window forms...
     This macro records the selected frame, as well as the selected window of each frame, executes 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 FORMS.

     This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if FORMS change them, the change persists.  If the previously selected window of some frame is no longer live at the time of exit from 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 FORMS remains selected.  The current buffer is restored if and only if it is still live when exiting FORMS.

     This macro changes neither the ordering of recently selected windows nor the buffer list.

 -- Macro: with-selected-window window forms...
     This macro selects WINDOW, executes FORMS in sequence, then restores the previously selected window and current buffer.  The ordering of recently selected windows and the buffer list remain unchanged unless you deliberately change them within FORMS, for example, by calling select-window with argument NORECORD nil.

     The order of recently selected windows and the buffer list are not changed by this macro.

Earlier (see Basic Windows) we mentioned that at any time, exactly one window on any frame is selected within the frame.  The significance of this designation is that selecting the frame also selects this window.  Conversely, selecting a window for Emacs with select-window also makes that window selected within its frame.

 -- Function: frame-selected-window &optional frame
     This function returns the window on FRAME that is selected within FRAME.  The optional argument FRAME must denote a live frame and defaults to the selected one.

 -- Function: set-frame-selected-window frame window &optional norecord
     This function sets the selected window of frame FRAME to WINDOW.  The argument FRAME must denote a live frame and defaults to the selected one.  If FRAME is the selected frame, this also makes WINDOW the selected window.  The argument WINDOW must denote a live window.  This function returns WINDOW.

     Optional argument NORECORD non-nil means to neither change the list of most recently selected windows (see Selecting Windows) nor the buffer list (see The Buffer List).

Cyclic Ordering of Windows
==========================

When you use the command C-x o (other-window) to select some other window, it moves through live windows in a specific order. For any given configuration of windows, this order never varies.  It is called the cyclic ordering of windows.

For a particular frame, this ordering is determined by the window tree of that frame, see Windows and Frames.  More precisely, the ordering is obtained by a depth-first traversal of the frame's window tree supplemented, if requested, by the frame's minibuffer window.

If there's just one live frame, the cyclic ordering is the ordering for that frame.  Otherwise, the cyclic ordering is obtained by appending the orderings for individual frames in order of the list of all live frames, Finding All Frames.  In any case, the ordering is made ``cyclic'' by having the last window precede the first window in the ordering.

 -- Function: next-window &optional window minibuf all-frames
     This function returns the window following WINDOW in the cyclic ordering of windows.  The argument WINDOW must specify a live window and defaults to the selected one.

     The optional argument MINIBUF specifies whether minibuffer windows shall be included in the cyclic ordering.  Normally, when MINIBUF is nil, a minibuffer window is included only if it is currently ``active''; this matches the behavior of C-x o.  (Note that a minibuffer window is active as long as its minibuffer is in use; see Minibuffers).

     If MINIBUF is t, the cyclic ordering includes all minibuffer windows.  If MINIBUF is neither t nor nil, minibuffer windows are not included even if they are active.

     The optional argument ALL-FRAMES specifies which frames to consider.  Here are the possible values and their meanings:

       * nil means consider all windows on WINDOW's frame, plus the minibuffer window used by that frame even if it lies in some other frame.  If the minibuffer counts (as determined by MINIBUF), then all windows on all frames that share that minibuffer count too.

       * t means consider all windows on all existing frames.

       * visible means consider all windows on all visible frames.  (To get useful results, ensure that WINDOW is on a visible frame.)

       * 0 means consider all windows on all visible or iconified frames.

       * A frame means consider all windows on that frame.

       * Anything else means consider the windows on WINDOW's frame, and no others.

     This example assumes there are two windows, both displaying the buffer windows.texi:

          (selected-window)
               => #<window 56 on windows.texi>

          (next-window (selected-window))
               => #<window 52 on windows.texi>

          (next-window (next-window (selected-window)))
               => #<window 56 on windows.texi>

 -- Function: previous-window &optional window minibuf all-frames
     This function returns the window preceding WINDOW in the cyclic ordering of windows.  The other arguments specify which windows to consider as in next-window.

 -- Command: other-window count &optional all-frames
     This function selects another window in the cyclic ordering of windows. COUNT specifies the number of windows to skip in the ordering, starting with the selected window, before making the selection.  If COUNT is a positive number, it skips COUNT windows forwards. COUNT negative means skip -COUNT windows backwards. If COUNT is zero, it does not skip any window, thus re-selecting the selected window.  In an interactive call, COUNT is the numeric prefix argument.

     The optional argument ALL-FRAMES has the same meaning as in next-window, but the MINIBUF argument of next-window is always effectively nil.  This function returns nil.

     This function does not select a window that has a non-nil no-other-window window parameter (see Window Parameters).

The following function returns a copy of the list of windows in the cyclic odering.

 -- Function: window-list-1 &optional window &optional minibuf &optional all_frames
     This function returns a list of live windows.  The optional arguments MINIBUF and ALL-FRAMES specify the set of windows to include in the list.  See the description of next-window for details.

     The optional argument WINDOW specifies the first window to list and defaults to the selected window.  If WINDOW is not on the list of windows returned, some other window will be listed first but no error is signalled.

The functions described below use window-list-1 for generating a copy of the list of all relevant windows.  Hence, any change of the window configuration that occurs while one of these functions is executed is not reflected in the list of windows investigated.

 -- Function: walk-windows proc &optional minibuf all-frames
     This function cycles through live windows.  It calls the function PROC once for each window, with the window as its sole argument.

     The optional arguments MINIBUF and ALL-FRAMES specify the set of windows to include in the walk, see next-window above.  If ALL-FRAMES specifies a frame, the first window walked is the first window on that frame as returned by frame-first-window and not necessarily the selected window.

     If PROC changes the window configuration by splitting or deleting windows, that change is not reflected in the set of windows walked. That set is determined entirely by the set of live windows at the time this function was invoked.

The following function allows to determine whether a specific window is the only live window.

 -- Function: one-window-p &optional no-mini all-frames
     This function returns non-nil if the selected window is the only window.

     The optional argument NO-MINI, if non-nil, means don't count the minibuffer even if it is active; otherwise, the minibuffer window is counted when it is active.  The optional argument ALL-FRAMES has the same meaning as for next-window, see above.

The following functions choose (but do not select) one of the windows on the screen, offering various criteria for the choice.

 -- Function: get-lru-window &optional all-frames dedicated
     This function returns the window least recently ``used'' (that is, selected).  If any full-width windows are present, it only considers these.  The optional argument ALL-FRAMES has the same meaning as in next-window.

     The selected window is returned if it is the only candidate.  A minibuffer window is never a candidate.  A dedicated window (see Dedicated Windows) is never a candidate unless the optional argument DEDICATED is non-nil.

 -- Function: get-largest-window &optional all-frames dedicated
     This function returns the window with the largest area (height times width).  A minibuffer window is never a candidate.  A dedicated window (see Dedicated Windows) is never a candidate unless the optional argument DEDICATED is non-nil.

     If there are two candidate windows of the same size, this function prefers the one that comes first in the cyclic ordering of windows, starting from the selected window.

     The optional argument ALL-FRAMES specifies which set of windows to consider as with next-window, see above.

 -- Function: get-window-with-predicate predicate &optional minibuf all-frames default
     This function returns a window satisfying PREDICATE.  It cycles through all visible windows calling PREDICATE on each one of them with that window as its argument.  The function returns the first window for which PREDICATE returns a non-nil value; if that never happens, it returns DEFAULT (which defaults to nil).

     The optional arguments MINIBUF and ALL-FRAMES specify the set of windows to investigate.  See the description of next-window for details.

Buffers and Windows
===================

To find out which buffer is displayed in a given window the following function is used.

 -- Function: window-buffer &optional window
     This function returns the buffer that WINDOW is displaying.  The argument WINDOW can be any window and defaults to the selected one.  If WINDOW is an internal window, this function returns nil.

The basic, low-level function to associate a window with a buffer is set-window-buffer.  Higher-level functions like switch-to-buffer and display-buffer try to obey a number of user customizations regulating which windows are supposed to display which buffers.  See Switching Buffers.  When writing an application, you should avoid using set-window-buffer unless you are sure you need it.

 -- Function: set-window-buffer window buffer-or-name &optional keep-margins
     This function makes WINDOW display BUFFER-OR-NAME and returns nil.  The argument WINDOW has to denote a live window and defaults to the selected one.  The argument BUFFER-OR-NAME must specify a buffer or the name of an existing buffer.  An error is signalled when WINDOW is strongly dedicated to its buffer (see Dedicated Windows) and does not already display BUFFER-OR-NAME.

     Normally, displaying BUFFER-OR-NAME in WINDOW resets the window's position, display margins, fringe widths, and scroll bar settings based on the local variables of the specified buffer.  However, if the optional argument KEEP-MARGINS is non-nil, display margins and fringe widths of WINDOW remain unchanged. See Fringes.

     This function is the fundamental primitive for changing which buffer is displayed in a window, and all ways of doing that call this function. Neither the selected window nor the current buffer are changed by this function.

     This function runs window-scroll-functions before running window-configuration-change-hook, see Window Hooks.

 -- Variable: buffer-display-count
     This buffer-local variable records the number of times a buffer has been displayed in a window.  It is incremented each time set-window-buffer is called for the buffer.

 -- Variable: 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 set-window-buffer is called, it sets this variable to (current-time) in the specified buffer (see Time of Day). When a buffer is first created, buffer-display-time starts out with the value nil.

 -- Function: get-buffer-window &optional buffer-or-name all-frames
     This function returns a window displaying BUFFER-OR-NAME, or 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, see Cyclic Window Ordering.

     The argument BUFFER-OR-NAME may be a buffer or a buffer name and defaults to the current buffer.  The optional argument ALL-FRAMES specifies which windows to consider:

       * nil means consider windows on the selected frame.

       * t means consider windows on all existing frames.

       * visible means consider windows on all visible frames.

       * 0 means consider windows on all visible or iconified frames.

       * A frame means consider windows on that frame only.

     Observe that the behavior of get-buffer-window may differ from that of next-window (see Cyclic Window Ordering) when ALL-FRAMES equals nil or any value not listed here. Perhaps we will change get-buffer-window in the future to make it compatible with the other functions.

 -- Function: get-buffer-window-list &optional buffer-or-name minibuf all-frames
     This function returns a list of all windows currently displaying BUFFER-OR-NAME.  The argument BUFFER-OR-NAME may be a buffer or the name of an existing buffer and defaults to the current buffer.

     The two remaining arguments work like the same-named arguments of next-window (see Cyclic Window Ordering); they are not like the optional arguments of get-buffer-window.

 -- Command: replace-buffer-in-windows &optional buffer-or-name
     This command replaces BUFFER-OR-NAME with some other buffer, in all windows displaying it.  For each such window, it choose another buffer using switch-to-prev-buffer (see Window History).

     BUFFER-OR-NAME may be a buffer, or the name of an existing buffer; it defaults to the current buffer.

     If a window displaying BUFFER-OR-NAME is dedicated (see Dedicated Windows), has never displayed any other buffers and is not the only window on its frame, that window is deleted.  If that window is the only window on its frame and there are other frames on the frame's terminal, that frame is deleted too; otherwise, the buffer provided by the function switch-to-prev-buffer (see Window History) is displayed instead.

Switching to a Buffer in a Window
=================================

This section describes high-level functions for switching to a specified buffer in some window.

Do not use these functions to make a buffer temporarily current just so a Lisp program can access or modify it.  They have side-effects, such as changing window histories (see Window History), which will surprise the user if used that way.  If you want to make a buffer current to modify it in Lisp, use with-current-buffer, save-current-buffer, or set-buffer.  See Current Buffer.

 -- Command: switch-to-buffer buffer-or-name &optional norecord force-same-window
     This function displays BUFFER-OR-NAME in the selected window, and makes it the current buffer.  (In contrast, set-buffer makes the buffer current but does not display it; see Current Buffer).  It is often used interactively (as the binding of C-x b), as well as in Lisp programs.  The return value is the buffer switched to.

     If BUFFER-OR-NAME is nil, it defaults to the buffer returned by other-buffer (see The Buffer List).  If BUFFER-OR-NAME is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable major-mode (see Major Modes).

     Normally the specified buffer is put at the front of the buffer list---both the global buffer list and the selected frame's buffer list (see The Buffer List).  However, this is not done if the optional argument NORECORD is non-nil.

     If this function is unable to display the buffer in the selected window---usually because the selected window is a minibuffer window or is strongly dedicated to its buffer (see Dedicated Windows)---then it normally tries to display the buffer in some other window, in the manner of pop-to-buffer (see below).  However, if the optional argument FORCE-SAME-WINDOW is non-nil, it signals an error instead.

The next two functions are similar to switch-to-buffer, except for the described features.

 -- Command: switch-to-buffer-other-window buffer-or-name &optional norecord
     This function makes the buffer specified by BUFFER-OR-NAME current and displays it in some window other than the selected window. It uses the function pop-to-buffer internally (see below).

     If the selected window already displays the specified buffer, it continues to do so, but another window is nonetheless found to display it as well.

     The BUFFER-OR-NAME and NORECORD arguments have the same meanings as in switch-to-buffer.

 -- Command: switch-to-buffer-other-frame buffer-or-name &optional norecord
     This function makes the buffer specified by BUFFER-OR-NAME current and displays it, usually in a new frame.  It uses the function pop-to-buffer (see below).

     If the specified buffer is already displayed in another window, in any frame on the current terminal, this switches to that window instead of creating a new frame.  However, the selected window is never used for this.

     The BUFFER-OR-NAME and NORECORD arguments have the same meanings as in switch-to-buffer.

The above commands use pop-to-buffer, which is the function used by Lisp programs to flexibly display a buffer in some window and select that window for editing:

 -- Function: pop-to-buffer buffer-or-name &optional action norecord
     This function makes BUFFER-OR-NAME the current buffer and displays it in some window, preferably not the window previously selected.  It then selects the displaying window.  If that window is on a different graphical frame, that frame is given input focus if possible (see Input Focus).  The return value is the buffer that was switched to.

     This function uses display-buffer to display the buffer, so all the variables affecting display-buffer will affect it as well. See Choosing Window.

     If BUFFER-OR-NAME is nil, it defaults to the buffer returned by other-buffer (see The Buffer List).  If BUFFER-OR-NAME is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable major-mode (see Major Modes).

     If ACTION is non-nil, it should be a display action to pass to display-buffer (see Choosing Window). Alternatively, a non-nil, non-list value means to pop to a window other than the selected one---even if the buffer is already displayed in the selected window.

     Like switch-to-buffer, this function updates the buffer list unless NORECORD is non-nil.

Choosing a Window for Display
=============================

The command display-buffer flexibly chooses a window for display, and displays a specified buffer in that window.  It can be called interactively, via the key binding C-x 4 o.  It is also used as a subroutine by many functions and commands, including switch-to-buffer and pop-to-buffer (see Switching Buffers).

This command performs several complex steps to find a window to display in.  These steps are described by means of display actions, which have the form (FUNCTION . ALIST). Here, FUNCTION is either a function or a list of functions, which we refer to as action functions; ALIST is an association list, which we refer to as action alists.

An action function accepts two arguments: the buffer to display and an action alist.  It attempts to display the buffer in some window, picking or creating a window according to its own criteria.  If successful, it returns the window; otherwise, it returns nil. See Display Action Functions, for a list of predefined action functions.

display-buffer works by combining display actions from several sources, and calling the action functions in turn, until one of them manages to display the buffer and returns a non-nil value.

 -- Command: display-buffer buffer-or-name &optional action frame
     This command makes BUFFER-OR-NAME appear in some window, without selecting the window or making the buffer current.  The argument BUFFER-OR-NAME must be a buffer or the name of an existing buffer.  The return value is the window chosen to display the buffer.

     The optional argument ACTION, if non-nil, should normally be a display action (described above).  display-buffer builds a list of action functions and an action alist, by consolidating display actions from the following sources (in order):

       * The variable display-buffer-overriding-action.

       * The user option display-buffer-alist.

       * The ACTION argument.

       * The user option display-buffer-base-action.

       * The constant display-buffer-fallback-action.

     Each action function is called in turn, passing the buffer as the first argument and the combined action alist as the second argument, until one of the functions returns non-nil.

     The argument ACTION can also have a non-nil, non-list value.  This has the special meaning that the buffer should be displayed in a window other than the selected one, even if the selected window is already displaying it.  If called interactively with a prefix argument, ACTION is t.

     The optional argument FRAME, if non-nil, specifies which frames to check when deciding whether the buffer is already displayed. It is equivalent to adding an element (reusable-frames . FRAME) to the action alist of ACTION.  See Display Action Functions.

 -- Variable: display-buffer-overriding-action
     The value of this variable should be a display action, which is treated with the highest priority by display-buffer.  The default value is empty, i.e. (nil . nil).

 -- User Option: display-buffer-alist
     The value of this option is an alist mapping regular expressions to display actions.  If the name of the buffer passed to display-buffer matches a regular expression in this alist, then display-buffer uses the corresponding display action.

 -- User Option: display-buffer-base-action
     The value of this option should be a display action.  This option can be used to define a ``standard'' display action for calls to display-buffer.

 -- Constant: display-buffer-fallback-action
     This display action specifies the fallback behavior for display-buffer if no other display actions are given.

Action Functions for display-buffer
===================================

The following basic action functions are defined in Emacs.  Each of these functions takes two arguments: BUFFER, the buffer to display, and ALIST, an action alist.  Each action function returns the window if it succeeds, and nil if it fails.

 -- Function: display-buffer-same-window buffer alist
     This function tries to display BUFFER in the selected window. It fails if the selected window is a minibuffer window or is dedicated to another buffer (see Dedicated Windows).  It also fails if ALIST has a non-nil inhibit-same-window entry.

 -- Function: display-buffer-reuse-window buffer alist
     This function tries to ``display'' BUFFER by finding a window that is already displaying it.

     If ALIST has a non-nil inhibit-same-window entry, the selected window is not eligible for reuse.

     If ALIST contains a reusable-frames entry, its value determines which frames to search for a reusable window:

       * nil means consider windows on the selected frame. (Actually, the last non-minibuffer frame.)

       * t means consider windows on all frames.

       * visible means consider windows on all visible frames.

       * 0 means consider windows on all visible or iconified frames.

       * A frame means consider windows on that frame only.

     If ALIST contains no reusable-frames entry, this function normally searches just the selected frame; however, if either the variable display-buffer-reuse-frames or the variable pop-up-frames is non-nil, it searches all frames on the current terminal.  See Choosing Window Options.

 -- Function: display-buffer-pop-up-frame buffer alist
     This function creates a new frame, and displays the buffer in that frame's window.

 -- Function: display-buffer-pop-up-window buffer alist
     This function tries to display BUFFER by splitting the largest or least recently-used window.  It uses split-window-sensibly as a subroutine (see Choosing Window Options).

 -- Function: display-buffer-use-some-window buffer alist
     This function tries to display BUFFER by choosing an existing window and displaying the buffer in that window.  It can fail if all windows are dedicated to another buffer (see Dedicated Windows).

Additional Options for Displaying Buffers
=========================================

The behavior of the standard display actions of display-buffer (see Choosing Window) can be modified by a variety of user options.

 -- User Option: display-buffer-reuse-frames
     If this variable is non-nil, display-buffer searches visible and iconified frames for a window displaying BUFFER-OR-NAME.  If there is such a window, display-buffer makes that window's frame visible and raises it if necessary, and returns the window.  If there is no such window or display-buffer-reuse-frames is nil, the behavior of display-buffer is determined by the variables described next.

 -- User Option: pop-up-windows
     This variable specifies whether display-buffer is allowed to split (see Splitting Windows) an existing window.  If this variable is non-nil, display-buffer tries to split the largest or least recently used window on the selected frame.  (If the selected frame is a minibuffer-only frame, display-buffer tries to split a window on another frame instead.)  If this variable is nil or the variable pop-up-frames (see below) is non-nil, display-buffer does not split any window.

 -- User Option: split-window-preferred-function
     This variable must specify a function with one argument, which is a window.  The display-buffer routines will call this function with one or more candidate windows when they look for a window to split.  The function is expected to split that window and return the new window.  If the function returns nil, this means that the argument window cannot (or shall not) be split.

     The default value of split-window-preferred-function is the function split-window-sensibly described below.  If you customize this option, bear in mind that the display-buffer routines may call your function up to two times when trying to split a window.  The argument of the first call is the largest window on the chosen frame (as returned by get-largest-window).  If that call fails to return a live window, your function is called a second time with the least recently used window on that frame (as returned by get-lru-window).

     The function specified by this option may try to split any other window instead of the argument window.  Note that the window selected at the time display-buffer was invoked is still selected when your function is called.  Hence, you can split the selected window (instead of the largest or least recently used one) by simply ignoring the window argument in the body of your function.  You can even choose to not split any window as long as the return value of your function specifies a live window or nil, but you are not encouraged to do so unconditionally.  If you want display-buffer to never split any windows, set pop-up-windows to nil.

 -- Function: split-window-sensibly window
     This function takes a window as argument and tries to split that window in a suitable way.  The two variables described next are useful for tuning the behavior of this function.

 -- User Option: split-height-threshold
     This variable specifies whether split-window-sensibly may split windows vertically.  If it is an integer, split-window-sensibly tries to vertically split a window only if it has at least this many lines.  If the window has less lines, splitting fails, or the value of this variable is nil, split-window-sensibly will try to split the window horizontally, subject to restrictions of split-width-threshold (see below).  If splitting horizontally fails too and the window is the only window on its frame, split-window-sensibly will try to split the window vertically disregarding the value of split-height-threshold.  If this fails as well, split-window-sensibly returns nil.

     split-window-sensibly does not split vertically a window whose height is fixed (see Resizing Windows).  Also, it vertically splits a window only if the space taken up by that window can accommodate two windows one above the other that are both at least window-min-height lines tall.  Moreover, if the window that shall be split has a mode line, split-window-sensibly does not split the window unless the new window can accommodate a mode line too.

 -- User Option: split-width-threshold
     This variable specifies whether split-window-sensibly may split windows horizontally.  If it is an integer, split-window-sensibly tries to horizontally split a window only if it has at least this many columns.  If it is nil, split-window-sensibly will not split the window horizontally.  (It still might split the window vertically, though, see above.)

     split-window-sensibly does not split horizontally a window if that window's width is fixed (see Resizing Windows).  Also, it horizontally splits a window only if the space that window takes up can accommodate two windows side by side that are both at least window-min-width columns wide.

 -- User Option: even-window-heights
     This variable specifies whether display-buffer should even out window heights if the buffer gets displayed in an existing window, above or beneath another window.  If even-window-heights is non-nil, the default, window heights will be evened out.  If either of the involved window has fixed height (see Resizing Windows) or even-window-heights is nil, the original window heights will be left alone.

 -- User Option: pop-up-frames
     This variable specifies whether display-buffer should make new frames.  If it is non-nil, display-buffer looks for a window already displaying BUFFER-OR-NAME on any visible or iconified frame.  If it finds such a window, it makes that window's frame visible and raises it if necessary, and returns the window. Otherwise it makes a new frame, unless the variable's value is graphic-only and the selected frame is not on a graphic display. See Frames, for more information.

     Note that the value of pop-up-windows does not matter if pop-up-frames is non-nil.  If pop-up-frames is nil, then display-buffer either splits a window or reuses one.

 -- User Option: pop-up-frame-function
     This variable specifies how to make a new frame if pop-up-frames is non-nil.

     The value of this variable must be a function of no arguments.  When display-buffer makes a new frame, it does so by calling that function, which should return a frame.  The default value of this variable is a function that creates a frame using the parameters specified by pop-up-frame-alist described next.

 -- User Option: pop-up-frame-alist
     This variable holds an alist specifying frame parameters used by the default value of pop-up-frame-function for making new frames. See Frame Parameters, for more information about frame parameters.

 -- User Option: special-display-buffer-names
     A list of buffer names identifying buffers that should be displayed specially.  If the name of BUFFER-OR-NAME is in this list, 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 CAR of that list is the buffer name, and the rest of that list says how to create the frame.  There are two possibilities for the rest of that list (its 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:

          (("myfile" (minibuffer) (menu-bar-lines . 0)))

     specifies to display a buffer named myfile in a dedicated frame with specified minibuffer and menu-bar-lines parameters.

     The list of frame parameters can also use the phony frame parameters same-frame and same-window.  If the specified frame parameters include (same-window . VALUE) and VALUE is non-nil, that means to display the buffer in the current selected window.  Otherwise, if they include (same-frame . VALUE) and VALUE is non-nil, that means to display the buffer in a new window in the currently selected frame.

 -- User Option: special-display-regexps
     A list of regular expressions specifying buffers that should be displayed specially.  If the buffer's name matches any of the regular expressions in this list, 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 CAR of the list is the regular expression, and the rest of the list says how to create the frame.  See special-display-buffer-names above.

 -- Function: special-display-p buffer-name
     This function returns non-nil if displaying a buffer named BUFFER-NAME with display-buffer would create a special frame.  The value is t if it would use the default frame parameters, or else the specified list of frame parameters.

 -- User Option: 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 special-display-popup-frame, see below.

 -- Function: special-display-popup-frame buffer &optional args
     This function tries to make BUFFER visible in a frame of its own. If BUFFER is already displayed in some window, it makes that window's frame visible and raises it.  Otherwise, it creates a frame that is dedicated to BUFFER.  The return value is the window used to display BUFFER.

     If ARGS is an alist, it specifies frame parameters for the new frame.  If ARGS is a list whose CAR is a symbol, then (car ARGS) is called as a function to actually create and set up the frame; it is called with BUFFER as first argument, and (cdr ARGS) as additional arguments.

     This function always uses an existing window displaying 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 BUFFER was created, then presumably the window was previously made by this function.

 -- User Option: special-display-frame-alist
     This variable holds frame parameters for special-display-popup-frame to use when it creates a frame.

 -- User Option: 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, display-buffer handles the buffer by switching to it in the selected window.

 -- User Option: 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, display-buffer handles the buffer by switching to it in the selected window.

 -- Function: same-window-p buffer-name
     This function returns t if displaying a buffer named BUFFER-NAME with display-buffer would put it in the selected window.

 -- User Option: display-buffer-function
     This variable is the most flexible way to customize the behavior of display-buffer.  If it is non-nil, it should be a function that display-buffer calls to do the work.  The function should accept two arguments, the first two arguments that display-buffer received.  It should choose or create a window, display the specified buffer in it, and then return the window.

     This variable takes precedence over all the other options described above.

If all options described above fail to produce a suitable window, display-buffer tries to reuse an existing window.  As a last resort, it will try to display BUFFER-OR-NAME on a separate frame. In that case, the value of pop-up-frames is disregarded.

Window History
==============

Each window remembers the buffers it has displayed earlier and the order in which these buffers have been removed from it.  This history is used, for example, by replace-buffer-in-windows (see Buffers and Windows).  This list is automatically maintained by Emacs, but you can use the following functions to explicitly inspect or alter it:

 -- Function: window-prev-buffers &optional window
     This function returns a list specifying the previous contents of WINDOW, which should be a live window and defaults to the selected window.

     Each list element has the form (BUFFER WINDOW-START WINDOW-POS), where BUFFER is a buffer previously shown in the window, WINDOW-START is the window start position when that buffer was last shown, and WINDOW-POS is the point position when that buffer was last shown.

     The list is ordered so that earlier elements correspond to more recently-shown buffers, and the first element usually corresponds to the buffer most recently removed from the window.

 -- Function: set-window-prev-buffers window prev-buffers
     This function sets WINDOW's previous buffers to the value of PREV-BUFFERS.  The argument WINDOW must be a live window and defaults to the selected one.  The argument PREV-BUFFERS should be a list of the same form as that returned by window-prev-buffers.

In addition, each buffer maintains a list of next buffers, which is a list of buffers re-shown by switch-to-prev-buffer (see below).  This list is mainly used by switch-to-prev-buffer and switch-to-next-buffer for choosing buffers to switch to.

 -- Function: window-next-buffers &optional window
     This function returns the list of buffers recently re-shown in WINDOW via switch-to-prev-buffer.  The WINDOW argument must denote a live window or nil (meaning the selected window).

 -- Function: set-window-next-buffers window next-buffers
     This function sets the next buffer list of WINDOW to NEXT-BUFFERS.  The WINDOW argument should be a live window or nil (meaning the selected window).  The argument NEXT-BUFFERS should be a list of buffers.

The following commands can be used to cycle through the global buffer list, much like bury-buffer and unbury-buffer.  However, they cycle according to the specified window's history list, rather than the global buffer list.  In addition, they restore window-specific window start and point positions, and may show a buffer even if it is already shown in another window.  The switch-to-prev-buffer command, in particular, is used by replace-buffer-in-windows, bury-buffer and quit-window to find a replacement buffer for a window.

 -- Command: switch-to-prev-buffer &optional window bury-or-kill
     This command displays the previous buffer in WINDOW.  The argument WINDOW should be a live window or nil (meaning the selected window).  If the optional argument BURY-OR-KILL is non-nil, this means that the buffer currently shown in WINDOW is about to be buried or killed and consequently shall not be switched to in future invocations of this command.

     The previous buffer is usually the buffer shown before the buffer currently shown in WINDOW.  However, a buffer that has been buried or killed or has been already shown by a recent invocation of switch-to-prev-buffer does not qualify as previous buffer.

     If repeated invocations of this command have already shown all buffers previously shown in WINDOW, further invocations will show buffers from the buffer list of the frame WINDOW appears on (see The Buffer List).

 -- Command: switch-to-next-buffer &optional window
     This command switches to the next buffer in WINDOW thus undoing the effect of the last switch-to-prev-buffer command in WINDOW.  The argument WINDOW must be a live window and defaults to the selected one.

     If there is no recent invocation of a switch-to-prev-buffer that can be undone, this function tries to show a buffer from the buffer list of the frame WINDOW appears on (see The Buffer List).

Dedicated Windows
=================

Functions for displaying a buffer can be told to not use specific windows by marking these windows as dedicated to their buffers. display-buffer (see Choosing Window) never uses a dedicated window for displaying another buffer in it.  get-lru-window and get-largest-window (see Selecting Windows) do not consider dedicated windows as candidates when their DEDICATED argument is non-nil.  The behavior of set-window-buffer (see Buffers and Windows) with respect to dedicated windows is slightly different, see below.

When delete-windows-on (see Deleting Windows) wants to delete a dedicated window and that window is the only window on its frame, it deletes the window's frame too, provided there are other frames left.  replace-buffer-in-windows (see Switching Buffers) tries to delete all dedicated windows showing its buffer argument.  When such a window is the only window on its frame, that frame is deleted, provided there are other frames left.  If there are no more frames left, some other buffer is displayed in the window, and the window is marked as non-dedicated.

When you kill a buffer (see Killing Buffers) displayed in a dedicated window, any such window usually gets deleted too, since kill-buffer calls replace-buffer-in-windows for cleaning up windows.  Burying a buffer (see The Buffer List) deletes the selected window if it is dedicated to that buffer.  If, however, that window is the only window on its frame, bury-buffer displays another buffer in it and iconifies the frame.

 -- Function: window-dedicated-p &optional window
     This function returns non-nil if WINDOW is dedicated to its buffer and nil otherwise.  More precisely, the return value is the value assigned by the last call of set-window-dedicated-p for WINDOW or nil if that function was never called with WINDOW as its argument.  The default for WINDOW is the selected window.

 -- Function: set-window-dedicated-p window flag
     This function marks WINDOW as dedicated to its buffer if FLAG is non-nil, and non-dedicated otherwise.

     As a special case, if FLAG is t, WINDOW becomes strongly dedicated to its buffer.  set-window-buffer signals an error when the window it acts upon is strongly dedicated to its buffer and does not already display the buffer it is asked to display.  Other functions do not treat t differently from any non-nil value.

Quitting Windows
================

When you want to get rid of a window used for displaying a buffer you can use the function delete-window (see Deleting Windows) to remove that window from its frame.  If the buffer has been shown on a separate frame, you might want to call delete-frame (see Deleting Frames) instead.  If, on the other hand, a window has been reused for displaying the buffer, you might prefer showing the buffer previously shown in that window by calling the function switch-to-prev-buffer (see Window History).  Finally, you might want to either bury (see The Buffer List) or kill (see Killing Buffers) the window's buffer.

The following function uses information on how the window for displaying the buffer was obtained in the first place thus attempting to automatize the above decisions for you.

 -- Command: quit-window &optional kill window
     This command quits WINDOW and buries its buffer.  The argument WINDOW must be a live window and defaults to the selected one. With prefix argument KILL non-nil, it kills the buffer instead of burying it.

     Quitting WINDOW means to proceed as follows: If WINDOW was created specially for displaying its current buffer, delete WINDOW provided its frame contains at least one other live window.  If WINDOW is the only window on its frame and other frames still exist, delete the frame together with WINDOW.  If, however, there are no other frames left, display some other buffer in WINDOW.

     If WINDOW was reused for displaying its buffer, this command tries to display the buffer previously shown in it.  It also tries to restore the window start (see Window Start and End) and point (see Window Point) positions of the previously shown buffer.  If, in addition, the current buffer was temporarily resized, this command will also try to restore the original height of WINDOW.

     The three cases described so far require that the buffer shown in WINDOW is still the buffer displayed by the last buffer display function for this window.  If another buffer has been shown in the meantime or the buffer previously shown no longer exists, this command calls switch-to-prev-buffer (see Window History) to show some other buffer instead.

The function quit-window bases its decisions on information stored in WINDOW's quit-restore window parameter (see Window Parameters) and resets that parameter to nil after it's done.

Windows and Point
=================

Each window has its own value of point (see 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.

  * 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.

  * 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.

  * 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.

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.

 -- Function: window-point &optional window
     This function returns the current position of point in WINDOW. For a nonselected window, this is the value point would have (in that window's buffer) if that window were selected.  The default for WINDOW is the selected window.

     When 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 save-excursion forms.  But that value is hard to find.

 -- Function: set-window-point window position
     This function positions point in WINDOW at position POSITION in WINDOW's buffer.  It returns POSITION.

     If WINDOW is selected, and its buffer is current, this simply does goto-char.

 -- Variable: window-point-insertion-type
     This variable specifies the marker insertion type (see Marker Insertion Types) of window-point.  The default is nil, so window-point will stay behind text inserted there.

The Window Start and End Positions
==================================

Each window maintains a marker used to keep track of a buffer position that specifies where in the buffer display should start.  This position is called the display-start position of the window (or just the 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.

After switching windows or buffers, and in some other cases, if the window start is in the middle of a line, Emacs adjusts the window start to the start of a line.  This prevents certain operations from leaving the window start at a meaningless point within a line.  This feature may interfere with testing some Lisp code by executing it using the commands of Lisp mode, because they trigger this readjustment.  To test such code, put it into a command and bind the command to a key.

 -- Function: window-start &optional window
     This function returns the display-start position of window WINDOW.  If WINDOW is nil, the selected window is used.  For example,

          (window-start)
               => 7058

     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 to point-min if the buffer doesn't have any.

     Redisplay updates the window-start position (if you have not specified it explicitly since the previous redisplay)---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 window-start, see the description of count-lines.  See Definition of count-lines.

 -- Function: window-end &optional window update
     This function returns the position where display of its buffer ends in WINDOW.  The default for WINDOW is the selected window.

     Simply changing the buffer text or moving point does not update the value that window-end returns.  The value is updated only when Emacs redisplays and redisplay completes without being preempted.

     If the last redisplay of 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 nil.

     If UPDATE is non-nil, window-end always returns an up-to-date value for where display ends, based on the current window-start value.  If a previously saved value of that position is still valid, window-end returns that value; otherwise it computes the correct value by scanning the buffer text.

     Even if UPDATE is non-nil, 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 window-start value.  In effect, it reports where the displayed text will end if scrolling is not required.

 -- Function: set-window-start window position &optional noforce
     This function sets the display-start position of WINDOW to POSITION in WINDOW's buffer.  It returns 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 nil for NOFORCE, it means you want display to start at 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 is 1 and you set the start of the window to 37, the start of the next line, point will 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:

          ;; Here is what foo looks like before executing
          ;;   the set-window-start expression.

          ---------- Buffer: foo ----------
          -!-This is the contents of buffer foo.
          2
          3
          4
          5
          6
          ---------- Buffer: foo ----------

          (set-window-start
           (selected-window)
           (save-excursion
             (goto-char 1)
             (forward-line 1)
             (point)))
          => 37

          ;; Here is what foo looks like after executing
          ;;   the set-window-start expression.
          ---------- Buffer: foo ----------
          2
          3
          -!-4
          5
          6
          ---------- Buffer: foo ----------

     If NOFORCE is non-nil, and 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 POSITION is not used.

 -- Function: pos-visible-in-window-p &optional position window partially
     This function returns non-nil if POSITION is within the range of text currently visible on the screen in WINDOW.  It returns nil if POSITION is scrolled vertically out of view. Locations that are partially obscured are not considered visible unless PARTIALLY is non-nil.  The argument POSITION defaults to the current position of point in WINDOW; WINDOW, to the selected window.  If POSITION is t, that means to check the last visible position in WINDOW.

     This function considers only vertical scrolling.  If POSITION is out of view only because WINDOW has been scrolled horizontally, pos-visible-in-window-p returns non-nil anyway. See Horizontal Scrolling.

     If POSITION is visible, pos-visible-in-window-p returns t if PARTIALLY is nil; if PARTIALLY is non-nil, and the character following POSITION is fully visible, it returns a list of the form (X Y), where X and Y are the pixel coordinates relative to the top left corner of the window; otherwise it returns an extended list of the form (X Y RTOP RBOT ROWH VPOS), where RTOP and RBOT specify the number of off-window pixels at the top and bottom of the row at POSITION, ROWH specifies the visible height of that row, and VPOS specifies the vertical position (zero-based row number) of that row.

     Here is an example:

          ;; If point is off the screen now, recenter it now.
          (or (pos-visible-in-window-p
               (point) (selected-window))
              (recenter 0))

 -- Function: window-line-height &optional line window
     This function returns the height of text line LINE in WINDOW.  If LINE is one of header-line or mode-line, window-line-height returns information about the corresponding line of the window.  Otherwise, LINE is a text line number starting from 0.  A negative number counts from the end of the window.  The default for LINE is the current line in WINDOW; the default for WINDOW is the selected window.

     If the display is not up to date, window-line-height returns nil.  In that case, pos-visible-in-window-p may be used to obtain related information.

     If there is no line corresponding to the specified LINE, window-line-height returns nil.  Otherwise, it returns a list (HEIGHT VPOS YPOS OFFBOT), where HEIGHT is the height in pixels of the visible part of the line, VPOS and YPOS are the vertical position in lines and pixels of the line relative to the top of the first text line, and 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, YPOS is negative.

Textual Scrolling
=================

Textual scrolling means moving the text up or down through a window.  It works by changing the window's display-start location.  It may also change the value of window-point to keep point on the screen (see Window Point).

The basic textual scrolling functions are scroll-up (which scrolls forward) and scroll-down (which scrolls backward).  In these function names, ``up'' and ``down'' refer to the direction of motion of the buffer text relative to 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 the middle of a buffer and repeatedly call scroll-down, you will eventually see the beginning of the buffer.

Some people have urged that the opposite convention be used: they imagine the window moving over text that remains in place, so that ``down'' commands take you to the end of the buffer.  This convention is consistent with fact that such a command is bound to a key named PageDown on modern keyboards.  We have not switched to this convention as that is likely to break existing Emacs Lisp code.

Textual scrolling functions (aside from scroll-other-window) have unpredictable results if the current buffer is not the one displayed in the selected window.  See Current Buffer.

If the window contains a row taller than the height of the window (for example in the presence of a large image), the scroll functions will adjust the window's vertical scroll position to scroll the partially visible row.  Lisp callers can disable this feature by binding the variable auto-window-vscroll to nil (see Vertical Scrolling).

 -- Command: scroll-up &optional count
     This function scrolls forward by COUNT lines in the selected window.

     If COUNT is negative, it scrolls backward instead.  If COUNT is nil (or omitted), the distance scrolled is next-screen-context-lines lines less than the height of the window's text area.

     If the selected window cannot be scrolled any further, this function signals an error.  Otherwise, it returns nil.

 -- Command: scroll-down &optional count
     This function scrolls backward by COUNT lines in the selected window.

     If COUNT is negative, it scrolls forward instead.  If COUNT is omitted or nil, the distance scrolled is next-screen-context-lines lines less than the height of the window's text area.

     If the selected window cannot be scrolled any further, this function signals an error.  Otherwise, it returns nil.

 -- Command: scroll-up-command &optional count
     This behaves like scroll-up, except that if the selected window cannot be scrolled any further and the value of the variable scroll-error-top-bottom is t, it tries to move to the end of the buffer instead.  If point is already there, it signals an error.

 -- Command: scroll-down-command &optional count
     This behaves like scroll-down, except that if the selected window cannot be scrolled any further and the value of the variable scroll-error-top-bottom is t, it tries to move to the beginning of the buffer instead.  If point is already there, it signals an error.

 -- Command: scroll-other-window &optional count
     This function scrolls the text in another window upward COUNT lines.  Negative values of COUNT, or nil, are handled as in scroll-up.

     You can specify which buffer to scroll by setting the variable other-window-scroll-buffer to a buffer.  If that buffer isn't already displayed, 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 minibuffer-scroll-window.  This variable has no effect when any other window is selected.  When it is non-nil and the minibuffer is selected, it takes precedence over other-window-scroll-buffer.  See 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, 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 Beginning of buffer.

 -- Variable: other-window-scroll-buffer
     If this variable is non-nil, it tells scroll-other-window which buffer's window to scroll.

 -- User Option: 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.

 -- User Option: 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 N, then redisplay scrolls the text up to N lines in either direction, if that will bring point back into proper view.  This behavior is called conservative scrolling. Otherwise, scrolling happens in the usual way, under the control of other variables such as scroll-up-aggressively and scroll-down-aggressively.

     The default value is zero, which means that conservative scrolling never happens.

 -- User Option: scroll-down-aggressively
     The value of this variable should be either nil or a fraction 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 F part of the window height from the top.  The larger F, the more aggressive the scrolling.

     A value of nil is equivalent to .5, since its effect is to center point.  This variable automatically becomes buffer-local when set in any fashion.

 -- User Option: scroll-up-aggressively
     Likewise, for scrolling up.  The value, F, specifies how far point should be placed from the bottom of the window; thus, as with scroll-up-aggressively, a larger value scrolls more aggressively.

 -- User Option: scroll-step
     This variable is an older variant of scroll-conservatively. The difference is that if its value is N, that permits scrolling only by precisely N lines, not a smaller number.  This feature does not work with scroll-margin.  The default value is zero.

 -- User Option: scroll-preserve-screen-position
     If this option is t, whenever a scrolling command moves point off-window, Emacs tries to adjust point to keep the cursor at its old vertical position in the window, rather than the window edge.

     If the value is non-nil and not t, Emacs adjusts point to keep the cursor at the same vertical position, even if the scrolling command didn't move point off-window.

     This option affects all scroll commands that have a non-nil scroll-command symbol property.

 -- User Option: 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, scroll-up with an argument of nil scrolls so that this many lines at the bottom of the window appear instead at the top.  The default value is 2.

 -- User Option: scroll-error-top-bottom
     If this option is nil (the default), scroll-up-command and scroll-down-command simply signal an error when no more scrolling is possible.

     If the value is t, these commands instead move point to the beginning or end of the buffer (depending on scrolling direction); only if point is already on that position do they signal an error.

 -- Command: recenter &optional count
     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 COUNT is a nonnegative number, that puts the line containing point COUNT lines down from the top of the window.  If COUNT is a negative number, then it counts upward from the bottom of the window, so that -1 stands for the last usable line in the window.  If COUNT is a non-nil list, then it stands for the line in the middle of the window.

     If COUNT is nil, recenter puts the line containing point in the middle of the window, then clears and redisplays the entire selected frame.

     When recenter is called interactively, COUNT is the raw prefix argument.  Thus, typing C-u as the prefix sets the COUNT to a non-nil list, while typing C-u 4 sets COUNT to 4, which positions the current line four lines from the top.

     With an argument of zero, 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,

          (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)

Vertical Fractional Scrolling
=============================

Vertical fractional scrolling means shifting text in a window up or down by a specified multiple or fraction of a line.  Each window has a 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.

 -- Function: window-vscroll &optional window pixels-p
     This function returns the current vertical scroll position of WINDOW.  The default for WINDOW is the selected window. If PIXELS-P is non-nil, the return value is measured in pixels, rather than in units of the normal line height.

          (window-vscroll)
               => 0

 -- Function: set-window-vscroll window lines &optional pixels-p
     This function sets WINDOW's vertical scroll position to LINES.  If WINDOW is nil, the selected window is used.  The argument LINES should be zero or positive; if not, it is taken as zero.

     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.

          (set-window-vscroll (selected-window) 1.2)
               => 1.13

     If PIXELS-P is non-nil, LINES specifies a number of pixels.  In this case, the return value is LINES.

 -- Variable: auto-window-vscroll
     If this variable is non-nil, the line-move, scroll-up, and scroll-down functions will automatically modify the vertical scroll position to scroll through display rows that are taller than the height of the window, for example in the presence of large images.

Horizontal Scrolling
====================

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 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 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.

If 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.

 -- Command: scroll-left &optional count set-minimum
     This function scrolls the selected window COUNT columns to the left (or to the right if COUNT is negative).  The default for 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 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 SET-MINIMUM is non-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-nil for SET-MINIMUM.

 -- Command: scroll-right &optional count set-minimum
     This function scrolls the selected window COUNT columns to the right (or to the left if COUNT is negative).  The default for COUNT is the window width, minus 2.  Aside from the direction of scrolling, this works just like scroll-left.

 -- Function: window-hscroll &optional window
     This function returns the total leftward horizontal scrolling of WINDOW---the number of columns by which the text in WINDOW is scrolled left past the left margin.  The default for WINDOW is the selected window.

     The return value is never negative.  It is zero when no horizontal scrolling has been done in WINDOW (which is usually the case).

          (window-hscroll)
               => 0

          (scroll-left 5)
               => 5

          (window-hscroll)
               => 5

 -- Function: set-window-hscroll window columns
     This function sets horizontal scrolling of WINDOW.  The value of COLUMNS specifies the amount of scrolling, in terms of columns from the left margin.  The argument COLUMNS should be zero or positive; if not, it is taken as zero.  Fractional values of COLUMNS are not supported at present.

     Note that set-window-hscroll may appear not to work if you test it by evaluating a call with 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 COLUMNS.

          (set-window-hscroll (selected-window) 10)
               => 10

Here is how you can determine whether a given position POSITION is off the screen due to horizontal scrolling:

     (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)))))

Coordinates and Windows
=======================

This section describes how to relate screen coordinates to windows.

 -- Function: window-at x y &optional frame
     This function returns the window containing the specified cursor position in the frame FRAME.  The coordinates X and Y are measured in characters and count from the top left corner of the frame.  If they are out of range, window-at returns nil.

     If you omit FRAME, the selected frame is used.

 -- Function: coordinates-in-window-p coordinates window
     This function checks whether a particular frame position falls within the window WINDOW.

     The argument COORDINATES is a cons cell of the form (X . Y).  The coordinates X and Y are measured in characters, and count from the top left corner of the screen or frame.

     The value returned by coordinates-in-window-p is non-nil if the coordinates are inside WINDOW.  The value also indicates what part of the window the position is in, as follows:

     (RELX . RELY)
          The coordinates are inside WINDOW.  The numbers RELX and RELY are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window.

     mode-line
          The coordinates are in the mode line of WINDOW.

     header-line
          The coordinates are in the header line of WINDOW.

     vertical-line
          The coordinates are in the vertical line between 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.

     left-fringe
     right-fringe
          The coordinates are in the left or right fringe of the window.

     left-margin
     right-margin
          The coordinates are in the left or right margin of the window.

     nil
          The coordinates are not in any part of WINDOW.

     The function coordinates-in-window-p does not require a frame as argument because it always uses the frame that WINDOW is on.

Window Configurations
=====================

A window configuration records the entire layout of one frame---all windows, their sizes, which buffers they contain, how those buffers are scrolled, and their values of point and the mark; also their fringes, margins, and scroll bar settings.  It also includes the value of minibuffer-scroll-window.  As a special exception, the window configuration does not record the value of point in the selected window for the current buffer.

You can bring back an entire frame layout by restoring a previously saved window configuration.  If you want to record the layout of all frames instead of just one, use a frame configuration instead of a window configuration; see Frame Configurations.

 -- Function: current-window-configuration &optional frame
     This function returns a new object representing FRAME's current window configuration.  The default for FRAME is the selected frame.

 -- Function: set-window-configuration configuration
     This function restores the configuration of windows and buffers as specified by CONFIGURATION, for the frame that CONFIGURATION was created for.

     The argument CONFIGURATION must be a value that was previously returned by current-window-configuration.  The configuration is restored in the frame from which CONFIGURATION was made, whether that frame is selected or not.  This always counts as a window size change and triggers execution of the window-size-change-functions (see Window Hooks), because set-window-configuration doesn't know how to tell whether the new configuration actually differs from the old one.

     If the frame which CONFIGURATION was saved from is dead, all this function does is restore the three variables window-min-height, window-min-width and minibuffer-scroll-window. In this case, the function returns nil.  Otherwise, it returns t.

     Here is a way of using this function to get the same effect as save-window-excursion:

          (let ((config (current-window-configuration)))
            (unwind-protect
                (progn (split-window-vertically nil)
                       ...)
              (set-window-configuration config)))

 -- Special Form: save-window-excursion forms...
     This special form records the window configuration, executes 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 save-excursion also, if you wish to preserve that.

     Don't use this construct when save-selected-window is sufficient.

     Exit from save-window-excursion always triggers execution of 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 FORMS.)

     The return value is the value of the final form in FORMS. For example:

          (split-window)
               => #<window 25 on control.texi>

          (setq w (selected-window))
               => #<window 19 on control.texi>

          (save-window-excursion
            (delete-other-windows w)
            (switch-to-buffer "foo")
            'do-something)
               => do-something
               ;; The screen is now split again.

 -- Function: window-configuration-p object
     This function returns t if OBJECT is a window configuration.

 -- Function: 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 t even if those aspects differ.

     The function equal can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point or mark.

 -- Function: window-configuration-frame config
     This function returns the frame for which the window configuration CONFIG was made.

Other primitives to look inside of window configurations would make sense, but are not implemented because we did not need them.  See the file winner.el for some more operations on windows configurations.

The objects returned by current-window-configuration die together with the Emacs process.  In order to store a window configuration on disk and read it back in another Emacs session the following two functions can be used.

 -- Function: window-state-get &optional window markers
     This function returns the state of WINDOW as a Lisp object.  The argument WINDOW can be any window and defaults to the root window of the selected frame.

     The optional argument MARKERS non-nil means to use markers for sampling positions like window-point or window-start. This argument should be non-nil only if the value is used for putting the state back in the same session since markers slow down processing.

The value returned by window-state-get can be converted by using one of the functions defined by Desktop Save Mode (see Desktop Save Mode) to an object that can be written to a file.  Such objects can be read back and converted to a Lisp object representing the state of the window.  That Lisp object can be used as argument for the following function in order to restore the state window in another window.

 -- Function: window-state-put state &optional window ignore
     This function puts the window state STATE into WINDOW.  The argument STATE should be the state of a window returned by an earlier invocation of window-state-get, see above.  The optional argument WINDOW must specify a live window and defaults to the selected one.

     The optional argument IGNORE non-nil means to ignore minimum window sizes and fixed size restrictions.  If IGNORE equals safe, this means subwindows can get as small as one line and/or two columns.

Window Parameters
=================

This section describes how window parameters can be used to associate additional information with windows.

 -- Function: window-parameter window parameter
     This function returns WINDOW's value for PARAMETER.  The default for WINDOW is the selected window.  If WINDOW has no setting for PARAMETER, this function returns nil.

 -- Function: window-parameters &optional window
     This function returns all parameters of WINDOW and their values. The default for WINDOW is the selected window.  The return value, if non-nil is an association list whose elements have the form (PARAMETER . VALUE).

 -- Function: set-window-parameter window parameter value
     This function sets WINDOW's value of PARAMETER to VALUE and returns VALUE.  The default for WINDOW is the selected window.

Some functions, notably delete-window, delete-other-windows and split-window may behave specially when their WINDOW argument has a parameter set.  You can override such special behavior by binding the following variable to a non-nil value:

 -- Variable: ignore-window-parameters
     If this variable is non-nil, some standard functions do not process window parameters.  The functions currently affected by this are split-window, delete-window, delete-other-windows and other-window.

     An application can bind this variable to a non-nil value around calls to these functions.  If it does so, the application is fully responsible for correctly assigning the parameters of all involved windows when exiting that function.

The following parameters are currently used by the window management code.

delete-window
     This parameter affects the execution of delete-window (see Deleting Windows).

delete-other-windows
     This parameter affects the execution of delete-other-windows (see Deleting Windows).

split-window
     This parameter affects the execution of split-window (see Splitting Windows).

other-window
     This parameter affects the execution of other-window (see Cyclic Window Ordering).

no-other-window
     This parameter marks the window as not selectable by other-window (see Cyclic Window Ordering).

In addition, the parameters window-atom and window-side are reserved and should not be used by applications.  The quit-restore parameter tells how to proceed with a window when the buffer it shows is no more needed.  This parameter is installed by the buffer display functions (see Choosing Window) and consulted by the function quit-window (see Quitting Windows).

Hooks for Window Scrolling and Changes
======================================

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 window-scroll-functions; the last runs window-size-change-functions.

 -- Variable: window-scroll-functions
     This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling.  Displaying a different buffer in the window also runs these functions.

     This variable is not a normal hook, because each function is called with two arguments: the window, and its new display-start position.

     These functions must be careful in using window-end (see Window Start and End); if you need an up-to-date value, you must use the UPDATE argument to ensure you get it.

     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.

 -- Variable: 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 save-window-excursion (see 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, save-selected-window (see Selecting Windows) is what you need here.

 -- Variable: 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 buffer-local part of this hook is run once per each window on the affected frame, with the relevant window selected and its buffer current.  The global part is run once for the modified frame, with that frame selected.

In addition, you can use jit-lock-register to register a Font Lock fontification function, which will be called whenever parts of a buffer are (re)fontified because a window was scrolled or its size changed.  See Other Font Lock Variables.