diff options
author | Martin Rudalics <rudalics@gmx.at> | 2011-09-23 11:12:53 +0200 |
---|---|---|
committer | Martin Rudalics <rudalics@gmx.at> | 2011-09-23 11:12:53 +0200 |
commit | b33b68a32cc0d0b7f60a1de9a17e59e38e72a3d1 (patch) | |
tree | 73a407c9e44f76dd3a5b02f208e301daa475b119 | |
parent | 71146d7b6e7524c91b4eee124cfdaaf86aa21643 (diff) | |
download | emacs-b33b68a32cc0d0b7f60a1de9a17e59e38e72a3d1.tar.gz |
Document changes to windows code.
* frames.texi (Frames and Windows): Move section and rename to
Windows and Frames in windows.texi.
* windows.texi (Windows): Restructure.
(Basic Windows): Rewrite. Explain live and internal windows and
normalization functions.
(Windows and Frames): Move section here from frames.texi.
Describe subwindows, window combinations, window tree, and
corresponding functions including window-list here.
(Window Sizes): Rename section from Size of Window and move it
up in chapter. Describe total and body sizes and the
corresponding functions. Explain new semantics of
window-min-height/-width.
(Resizing Windows): Move section up in chapter. Describe new
resize functions.
(Splitting Windows): Describe new behavior of split-window,
split-window-above-each-other and split-window-side-by-side.
Provide examples. Describe window-nest and window-splits
options.
(Deleting Windows): Minor rewrite.
(Selecting Windows): Minor rewrite. Describe
frame-selected-window and set-frame-selected-window here.
(Cyclic Window Ordering): Minor rewrite. Describe
window-list-1.
(Buffers and Windows): Rewrite. Explain a window's previous and
next buffers and the corresponding functions.
* elisp.texi (Top): Update node listings for frames and windows
sections.
-rw-r--r-- | doc/lispref/ChangeLog | 30 | ||||
-rw-r--r-- | doc/lispref/elisp.texi | 10 | ||||
-rw-r--r-- | doc/lispref/frames.texi | 49 | ||||
-rw-r--r-- | doc/lispref/windows.texi | 2659 |
4 files changed, 1895 insertions, 853 deletions
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 70f6c9b7f22..90d346c0bf7 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,33 @@ +2011-09-23 Martin Rudalics <rudalics@gmx.at> + + * frames.texi (Frames and Windows): Move section and rename to + Windows and Frames in windows.texi. + * windows.texi (Windows): Restructure. + (Basic Windows): Rewrite. Explain live and internal windows and + normalization functions. + (Windows and Frames): Move section here from frames.texi. + Describe subwindows, window combinations, window tree, and + corresponding functions including window-list here. + (Window Sizes): Rename section from Size of Window and move it + up in chapter. Describe total and body sizes and the + corresponding functions. Explain new semantics of + window-min-height/-width. + (Resizing Windows): Move section up in chapter. Describe new + resize functions. + (Splitting Windows): Describe new behavior of split-window, + split-window-above-each-other and split-window-side-by-side. + Provide examples. Describe window-nest and window-splits + options. + (Deleting Windows): Minor rewrite. + (Selecting Windows): Minor rewrite. Describe + frame-selected-window and set-frame-selected-window here. + (Cyclic Window Ordering): Minor rewrite. Describe + window-list-1. + (Buffers and Windows): Rewrite. Explain a window's previous and + next buffers and the corresponding functions. + * elisp.texi (Top): Update node listings for frames and windows + sections. + 2011-09-21 Stefan Monnier <monnier@iro.umontreal.ca> * display.texi (Face Functions): `face-list' returns faces (bug#9564). diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index bcf6d3318ef..d3b96a0eb81 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -927,6 +927,9 @@ Buffers Windows * Basic Windows:: Basic information on using windows. +* Windows and Frames:: Relating windows to the frame they appear on. +* Window Sizes:: Accessing a window's size. +* Resizing Windows:: Changing the sizes of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Selecting Windows:: The selected window is the one that you edit in. @@ -936,17 +939,14 @@ Windows and choosing a window for it. * Choosing Window:: How to choose a window for displaying a buffer. * Dedicated Windows:: How to avoid displaying another buffer in - a specific window. + a specific window. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. * Textual Scrolling:: Moving text up and down through the window. * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. * Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. * Window Configurations:: Saving and restoring the state of the screen. * Window Parameters:: Associating additional information with windows. * Window Hooks:: Hooks for scrolling, window size changes, @@ -962,8 +962,6 @@ Frames * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index d619b92e4d3..d9399e98a69 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -86,8 +86,6 @@ is the same as for @code{framep} above. * Frame Titles:: Automatic updating of frame titles. * Deleting Frames:: Frames last until explicitly deleted. * Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * Input Focus:: Specifying the selected frame. * Visibility of Frames:: Frames may be visible or invisible, or icons. @@ -1309,53 +1307,6 @@ direction. See also @code{next-window} and @code{previous-window}, in @ref{Cyclic Window Ordering}. -@node Frames and Windows -@section Frames and Windows - - Each window is part of one and only one frame; you can get that frame -with @code{window-frame}. - -@defun window-frame window -This function returns the frame that @var{window} is on. -@end defun - - All the non-minibuffer windows in a frame are arranged in a cyclic -order. The order runs from the frame's top window, which is at the -upper left corner, down and to the right, until it reaches the window at -the lower right corner (always the minibuffer window, if the frame has -one), and then it moves back to the top. @xref{Cyclic Window Ordering}. - -@defun frame-first-window &optional frame -This returns the topmost, leftmost window of frame @var{frame}. -If omitted or @code{nil}, @var{frame} defaults to the selected frame. -@end defun - -At any time, exactly one window on any frame is @dfn{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 @code{select-window} also makes that window selected within -its frame. @xref{Selecting Windows}. - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to -the selected frame. -@end defun - -@defun set-frame-selected-window frame window &optional norecord -This sets the selected window of frame @var{frame} to @var{window}. -If @var{frame} is @code{nil}, it operates on the selected frame. If -@var{frame} is the selected frame, this makes @var{window} the -selected window. This function returns @var{window}. - -Optional argument @var{norecord} non-@code{nil} means to neither change -the order of recently selected windows nor the buffer list (@pxref{The -Buffer List}). -@end defun - - Another function that (usually) returns one of the windows in a given -frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}. - @node Minibuffers and Frames @section Minibuffers and Frames diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 2cf4a8152c7..b80fe02b0ff 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -7,13 +7,16 @@ @node Windows, Frames, Buffers, Top @chapter Windows - This chapter describes most of the functions and variables related to -Emacs windows. @xref{Frames and Windows}, for how windows relate to -frames. @xref{Display}, for information on how text is displayed in -windows. +This chapter describes the functions and variables related to Emacs +windows. @xref{Frames}, for how windows are assigned an area of screen +available for Emacs to use. @xref{Display}, for information on how text +is displayed in windows. @menu * Basic Windows:: Basic information on using windows. +* Windows and Frames:: Relating windows to the frame they appear on. +* Window Sizes:: Accessing a window's size. +* Resizing Windows:: Changing the sizes of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Selecting Windows:: The selected window is the one that you edit in. @@ -30,10 +33,7 @@ windows. * Textual Scrolling:: Moving text up and down through the window. * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. * Coordinates and Windows:: Converting coordinates to windows. -* Window Tree:: The layout and sizes of all windows in a frame. * Window Configurations:: Saving and restoring the state of the screen. * Window Parameters:: Associating additional information with windows. * Window Hooks:: Hooks for scrolling, window size changes, @@ -41,54 +41,35 @@ windows. or window configuration changes. @end menu + @node Basic Windows @section Basic Concepts of Emacs Windows @cindex window -@cindex selected window - - A @dfn{window} in Emacs is the physical area of the screen in which a -buffer is displayed. The term is also used to refer to a Lisp object that -represents that screen area in Emacs Lisp. It should be -clear from the context which is meant. - - Emacs groups windows into frames; see @ref{Frames}. A frame -represents an area of screen available for Emacs to use. Each frame -always contains at least one window, but you can subdivide it -vertically or horizontally into multiple, nonoverlapping Emacs -windows. - In each frame, at any time, one and only one window is designated as -@dfn{selected within the frame}. The frame's cursor appears in that -window, but the other windows have ``non-selected'' cursors, normally -less visible. (@xref{Cursor Parameters}, for customizing this.) At -any time, one frame is the selected frame; and the window selected -within that frame is @dfn{the selected window}. The selected window's -buffer is usually the current buffer (except when @code{set-buffer} has -been used); see @ref{Current Buffer}. - - For practical purposes, a window exists only while it is displayed in -a frame. Once removed from the frame, the window is effectively deleted -and should not be used, @emph{even though there may still be references -to it} from other Lisp objects; see @ref{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 @ref{Window Configurations}. +A @dfn{window} in Emacs is the physical area of the screen in which a +buffer is displayed, see @ref{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. @cindex multiple windows - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. + Emacs groups windows into frames; see @ref{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. +@cindex terminal screen +@cindex screen of terminal 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. +more X windows as frames, and subdivides them into Emacs windows. When +you use Emacs on a character-only terminal, Emacs treats the whole +terminal screen as one frame. -@cindex terminal screen -@cindex screen of terminal @cindex tiled windows Most window systems support arbitrarily located overlapping windows. In contrast, Emacs windows are @dfn{tiled}; they never overlap, and @@ -97,68 +78,937 @@ which Emacs creates new windows (@pxref{Splitting Windows}) and resizes them (@pxref{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 @ref{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 @ref{Window +Configurations}. + @defun windowp object -This function returns @code{t} if @var{object} is a window. +This function returns @code{t} if @var{object} is a window, @code{nil} +otherwise. It can return @code{t} if @var{object} denotes a window that +has been deleted. +@end defun + +@cindex live windows +@cindex internal windows + For historical reasons a window is considered @dfn{live} if and only +if it currently displays a buffer; see @ref{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 @ref{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. + +@defun window-live-p object +This function returns @code{t} if @var{object} is a live window and +@code{nil} otherwise. A live window is a window that displays a buffer. +@end defun + +@defun window-any-p object +This function returns @code{t} if @var{object} denotes a live or an +internal window and @code{nil} otherwise. In particular, this function +returns @code{nil} if @var{object} is a window that has been +deleted. +@end defun + +@cindex selected window +In each frame, at any time, one and only one window is designated as +@dfn{selected within the frame}. Also, at any time, one frame is the +selected frame (@pxref{Input Focus}). The window selected within the +selected frame is the @dfn{selected window}. + + The selected window is always a live window. Its buffer is usually +the current buffer (except when @code{set-buffer} has been used); see +@ref{Current Buffer}. + +@defun selected-window +This function returns the selected window. This is the window in which +the cursor for selected windows (@pxref{Cursor Parameters}) appears and +to which many commands apply. +@end defun + +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 +@code{nil} to specify the selected window. The two functions below can +be used to ``normalize'' arguments specifying windows in a uniform +manner. + +@defun window-normalize-any-window window +This function returns the normalized value for @var{window} which can be +any window that has not been deleted. More precisely, if @var{window} +is @code{nil}, it returns the selected window. If @var{window} denotes +a live or internal window, it returns that window. Otherwise, this +function signals an error. +@end defun + +@defun window-normalize-live-window window +This functions returns the normalized value for a live window +@var{window}. More precisely, if @var{window} is @code{nil}, it returns +the selected window. If @var{window} is a live window, it returns that +window. Otherwise, this function signals an error. +@end defun + + +@node Windows and Frames +@section Windows and Frames + +Each window is part of one and only one frame (@pxref{Frames}); you can +get that frame with the function described next. + +@defun window-frame window +This function returns the frame that @var{window} is on. The argument +@var{window} can be any window and defaults to the selected one. +@end defun + +The following function returns a list of all live windows on a specific +frame. + +@defun window-list &optional frame minibuf window +This function returns a list of @var{frame}'s live windows, starting +with @var{window}. The optional argument @var{frame} has to denote a +live frame and defaults to the selected frame. The optional argument +@var{window} has to denote a live window on the frame specified by +@var{frame} and defaults to the selected one. + +The argument @var{minibuf} specifies if the minibuffer window shall be +included in the return value. If @var{minibuf} is @code{t}, the result +always includes the minibuffer window. If @var{minibuf} is @code{nil} +or omitted, that includes the minibuffer window only if it is active. +If @var{minibuf} is neither @code{nil} nor @code{t}, the result never +includes the minibuffer window. +@end defun + +@cindex window tree +Windows within one and the same frame are organized in form of a tree +called @dfn{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 (@pxref{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 @code{window-tree} described at the end of this section. + + A window tree is rooted at the root window of its frame. + +@defun frame-root-window &optional frame-or-window +This function returns the root window of @var{frame-or-window}. The +argument @var{frame-or-window} has to denote either a window or a frame +and defaults to the selected frame. If @var{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 @var{frame-or-window} contains no other live windows and an +internal window otherwise. +@end defun + +@cindex subwindow +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 +@dfn{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. + +@cindex parent window +@defun window-parent &optional window +Return @var{window}'s parent in the window tree. The optional argument +@var{window} can denote an arbitrary window and defaults to the selected +one. The return value is @code{nil} if @var{window} is a minibuffer +window or the root window of its frame and an internal window otherwise. +@end defun + +@cindex child window + 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 @dfn{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. + +@cindex window combination +@cindex vertical combination +@cindex horizontal combination +The children of any parent window form either a vertical or a horizontal +combination of windows. A @dfn{vertical combination} is a set of +windows arranged one above each other. A @dfn{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): + +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ___________ ___________ ||| + || |||| || |||| + || |||| || |||| + || ||||_____W6____||_____W7____|||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| + +@end group +@end smallexample + +The root window of the frame is @code{W1}---a horizontal combination of +the live window @code{W2} and the internal window @code{W3}. Hence +@code{(window-parent W1)} is @code{nil} while @code{(window-parent W2)} +and @code{(window-parent W3)} are both @code{W1}. + + The internal window @code{W3} is a vertical combination of @code{W4} +and the live window @code{W5}. The internal window @code{W4} is a +horizontal combination of the live windows @code{W6} and @code{W7}. The +windows you can actually see on the screen are @code{W2}, @code{W5}, +@code{W6} and @code{W7}. + + For any parent window, the first child window can be retrieved by the +functions given next. + +@defun window-top-child &optional window +This function returns @var{window}'s first vertical child window. The +optional argument @var{window} can be an arbitrary window and defaults +to the selected one. The return value is @code{nil} if @var{window} is +a live window or its children form a horizontal combination. In the +example above @code{(window-top-child W3)} is @code{W4} while +@code{(window-top-child W4)} is @code{nil}. +@end defun + +@defun window-left-child &optional window +This function returns @var{window}'s first horizontal child window. The +optional argument @var{window} can be an arbitrary window and defaults +to the selected one. The return value is @code{nil} if @var{window} is +a live window or its children form a vertical combination. In the +example above @code{(window-left-child W4)} is @code{W6} while +@code{(window-top-child W3)} is @code{nil}. +@end defun + +@defun window-child window +This function return @var{window}'s first child window. The return +value is @code{nil} if @var{window} is a live window. In the example +above @code{(window-child W3)} is @code{W4} while @code{(window-child +W4)} is @code{W6}. +@end defun + +The following function is useful to determine whether a window is part +of a vertical or horizontal combination. + +@defun window-iso-combined-p &optional window horizontal +This function returns non-@code{nil} if and only if @var{window} is +vertically combined. The argument @var{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 @var{horizontal} is non-@code{nil}, this means +to return non-@code{nil} if and only if @var{window} is horizontally +combined. In this case, the return value is the first horizontal child +of window. +@end defun + +@cindex sibling window +For any window that is part of a combination, the other windows in that +combination are called the window's @dfn{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. + +@defun window-next-sibling &optional window +This function returns @var{window}'s next sibling. The optional +argument @var{window} can be an arbitrary window and defaults to the +selected window. It returns @code{nil} if @var{window} is the last +child of its parent. In our example @code{(window-next-sibling W2)} is +@code{W3} while @code{(window-next-sibling W3)} is @code{nil}. +@end defun + +@defun window-prev-sibling &optional window +This function returns @var{window}'s previous sibling. The optional +argument @var{window} can be an arbitrary window and defaults to the +selected window. It returns @code{nil} if @var{window} is the first +child of its parent. In our example @code{(window-prev-sibling W3)} is +@code{W2} and @code{(window-prev-sibling W2)} is @code{nil}. +@end defun + +The functions @code{window-next-sibling} and @code{window-prev-sibling} +should not be confused with the functions @code{next-window} and +@code{previous-window} which respectively return the next and previous +window in the cyclic ordering of windows, see @ref{Cyclic Window +Ordering}. + + In order to find the first live window on a frame, the following +function can be used. + +@defun frame-first-window &optional frame-or-window +This function returns the live window at the upper left corner of the +frame specified by @var{frame-or-window}. The argument +@var{frame-or-window} must denote a window or a live frame and defaults +to the selected frame. If @var{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 +@code{(frame-first-window)} returns @code{W2}. +@end defun + +You can get the window tree of a frame with the following function. + +@cindex window tree +@defun window-tree &optional frame +This function returns the window tree for frame @var{frame}. The +optional argument @var{frame} must be a live frame and defaults to the +selected one. + +The return value is a list of the form @code{(@var{root} @var{mini})}, +where @var{root} represents the window tree of the frame's +root window, and @var{mini} is the frame's minibuffer window. + +If the root window is live, @var{root} specifies the root window and +nothing else. Otherwise, @var{root} is a list @code{(@var{dir} +@var{edges} @var{w1} @var{w2} ...)} where @var{dir} is @code{nil} for a +horizontal combination, and @code{t} for a vertical combination, +@var{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 @var{edges} element is a list @code{(@var{left}@var{ top}@var{ +right}@var{ bottom})} similar to the value returned by +@code{window-edges}, see @ref{Coordinates and Windows}. +@end defun + + +@node Window Sizes +@section Window Sizes +@cindex window size +@cindex size of window + +Emacs windows are rectangular. The structure of a live window can be +roughly sketched as follows: + +@smallexample +@group + _________________________________________ + ^ |______________ 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 --------> + +@end group +@end smallexample + +@cindex window body +@cindex body of a window +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 (@pxref{Scroll Bars}) respectively. Only one of +them can be present at any time. LF and RF denote the left and right +fringe, see @ref{Fringes}. LM and RM, finally, stand for the left and +right display margin, see @ref{Display Margins}. The header line, if +present, is located above theses areas, the mode line below, see +@ref{Mode Line Format}. + +@cindex window height +@cindex total window height +@cindex height of a window +@cindex total height of a window +The @dfn{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. + +@cindex window width +@cindex total window width +@cindex width of a window +@cindex total width of a window +The @dfn{total width of a window} denotes the total number of columns of +the window. Any scroll bar and the column of @samp{|} 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. + +@cindex total size of a window +@cindex total window size +The following function is the standard interface for getting the total +size of any window: + +@defun window-total-size &optional window &optional horizontal +This function returns the total number of lines of @var{window}. The +argument @var{window} can denote any window and defaults to the selected +one. If @var{window} is live, the return value includes any header or +mode lines of @var{window}. If @var{window} is internal, the return +value is the sum of the total heights of @var{window}'s child windows +provided these are vertically combined and the height of @var{window}'s +first child if they are horizontally combined. + + If the optional argument @var{horizontal} is non-@code{nil}, this +function returns the total number of columns of @var{window}. If +@var{window} is live, the return value includes any vertical divider +column or scroll bars of @var{window}. On a window-system, the return +value includes the space occupied by any margins and fringes of +@var{window} too. If @var{window} is internal, the return value is the +sum of the total widths of @var{window}'s child windows provided these +are horizontally combined and the width of @var{window}'s first child +otherwise. +@end defun + +Alternatively, the following two functions can be used to retrieve +either the total height or the total width of a window: + +@defun window-total-height &optional window +This function returns the total number of lines of @var{window}. +@var{window} can be any window and defaults to the selected one. The +return value includes @var{window}'s mode line and header line, if any. +If @var{window} is internal the return value is the sum of heights of +@var{window}'s child windows for a vertical combination and the height +of @var{window}'s first child otherwise. +@end defun + +@defun window-total-width &optional window +This function returns the total number of columns of @var{window}. +@var{window} can be any window and defaults to the selected one. The +return value includes any vertical dividers or scrollbars of +@var{window}. On a window-system the return value also includes the +space occupied by any margins and fringes of @var{window}. If +@var{window} is internal, the return value is the sum of the widths of +@var{window}'s child windows for a horizontal combination and the width +of @var{window}'s first child otherwise. +@end defun + +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 (@pxref{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. + +@cindex full-height window +@defun window-full-height-p &optional window +This function returns non-@code{nil} if there is no other window above +or below @var{window} on the containing frame. More precisely, this +function returns @code{t} if and only if the total height of +@var{window} equals the total height of the root window (@pxref{Windows +and Frames}) of @var{window}'s frame. The @var{window} argument may +denote any window and defaults to the selected one. +@end defun + +@cindex full-width window +The following function can be used to determine whether there are no +other windows on the left or right of a specified window. + +@defun window-full-width-p &optional window +This function returns non-@code{nil} if there are no other windows on +the left or right of @var{window}; @code{nil} otherwise. More +precisely, this function returns @code{t} if and only if the total width +of @var{window} equals the total width of the root window +(@pxref{Windows and Frames}) of @var{window}'s frame. The @var{window} +argument may denote any window and defaults to the selected one. +@end defun + +@cindex top line of window +@cindex left column of window + The windows of a frame are unambiguously characterized by the +combination of their top line and left column within that frame. + +@defun window-top-line &optional window +This function returns the top line of @var{window}. The argument +@var{window} can denote any window and defaults to the selected one. +@end defun + +@defun window-left-column &optional window +This function returns the left column of @var{window}. The argument +@var{window} can denote any window and defaults to the selected one. +@end defun + +For a frame displaying one window only, that window's top line and left +column are both zero. When a frame displays a window @var{WB} below a +window @var{WA}, the top line of @var{WB} can be calculated by adding +the total height of @var{WA} to the top line of @var{WA}. When a frame +displays a window @var{WR} on the right of a window @var{WL}, the left +column of @var{WR} can be calculated by adding the total width of +@var{WL} to the left column of @var{WL}. + +@cindex window body height +@cindex body height of a window +The @dfn{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. + +@cindex window body width +@cindex body width of a window +The @dfn{body width of a window} denotes the total number of columns +occupied by the window's text area. Scroll bars or columns of @samp{|} +characters that separate side-by-side windows are not included in a +window's body width. + +@cindex body size of a window +@cindex window body size +The following functions retrieve height and width of the body of a live +window: + +@defun window-body-size &optional window horizontal +This function returns the number of lines of @var{window}'s text area. +@var{window} must be a live window and defaults to the selected one. +The return value does not count any mode or header line of @var{window}. + +Optional argument @var{horizontal} non-@code{nil} means to return the +number of columns of @var{window}'s text area. In this case the return +value does not include any vertical divider or scroll bar owned by +@var{window}. On a window-system the return value does not include the +number of columns used for @var{window}'s fringes or display margins +either. +@end defun + +@defun window-body-height &optional window +This function returns the number of lines of @var{window}'s body. +@var{window} must be a live window and defaults to the selected one. + +The return value does not include @var{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 @code{window-text-height} instead. +@end defun + +@defun window-body-width &optional window +This function returns the number of columns of @var{window}'s body. +@var{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 @var{window}. On a window-system the return value does not +include the number of columns used for @var{window}'s fringes or +display margins either. +@end defun + +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. + +@defun window-height &optional window +This function is an alias for `window-total-height', see above. +@end defun + +@defun window-width &optional window +This function is an alias for `window-body-width', see above. +@end defun + +@cindex minimum window size + The following two options constrain the sizes of windows to a minimum +height and width. Their values are honored when windows are split +(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). Any +request to make a window smaller than specified here will usually result +in an error. + +@defopt 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 @code{4}. Values less +than @code{1} are ignored. +@end defopt + +@defopt 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 @code{10}. A value less than @code{2} is ignored. +@end defopt + +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 @code{window-resize} (@pxref{Resizing Windows}) +with a non-@code{nil} @var{ignore} argument. The function +@code{split-window} (@pxref{Splitting Windows}) can make a window +smaller than specified here by calling it with a non-@code{nil} +@var{size} argument. Interactively, the values specified here cannot be +overridden. + + Earlier versions of Emacs could delete a window when its size dropped +below @code{window-min-height} or @code{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 @ref{Size and Position}. + + The size of a window can be fixed which means that it cannot be split +(@pxref{Splitting Windows}) or resized (@pxref{Resizing Windows}). + +@cindex fixed-size window +@defvar window-size-fixed +If this variable is non-@code{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 @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +This variable automatically becomes buffer-local when set. +@end defvar + +Commands supposed to explicitly change the size of windows such as +@code{enlarge-window} (@pxref{Resizing Windows}) get an error if they +had to change a window size which is fixed. Other functions like +@code{window-resize} (@pxref{Resizing Windows}) have an optional +@var{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. + +@defun window-size-fixed-p &optional window horizontal +This function returns non-@code{nil} if @var{window}'s height is fixed. +The argument @var{window} can be an arbitrary window and defaults to the +selected one. Optional argument @var{horizontal} non-@code{nil} means +return non-@code{nil} if @var{window}'s width is fixed. + +If this function returns @code{nil}, this does not necessarily mean that +@var{window} can be resized in the desired direction. The function +@code{window-resizable} (@pxref{Resizing Windows}) can tell that. +@end defun + + +@node Resizing Windows +@section Resizing Windows +@cindex window resizing +@cindex resize window +@cindex changing window size +@cindex window size, changing + +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 (@pxref{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 @ref{Window +Sizes}. In order to determine whether resizing a specific window is +possible in the first place, the following function can be used: + +@defun window-resizable window delta &optional horizontal ignore side noup nodown +This function returns @var{delta} if the size of @var{window} can be +changed vertically by @var{delta} lines. Optional argument +@var{horizontal} non-@code{nil} means to return @var{delta} if +@var{window} can be resized horizontally by @var{delta} columns. A +return value of zero means that @var{window} is not resizable. + +If @var{delta} is a positive number, this means that @var{window} shall +be enlarged by @var{delta} lines or columns. If @var{window} cannot be +enlarged by @var{delta} lines or columns, this function returns the +maximum value in the range from 0 to @var{delta} by which @var{window} +can be enlarged. + +If @var{delta} is a negative number, this means that @var{window} shall +be shrunk by -@var{delta} lines or columns. If @var{window} cannot be +shrunk by -@var{delta} lines or columns, this function returns the +minimum value in the range from @var{delta} to 0 that can be used for +shrinking @var{window}. + +Optional argument @var{ignore} non-@code{nil} means ignore any +restrictions imposed by the variables @code{window-min-height} or +@code{window-min-width} and @code{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 @var{ignore} denotes a window, this means to ignore restrictions for +that window only. If @var{ignore} equals the constant @code{safe}, this +means a live window may get as small as one line or two columns. + +Optional argument @var{noup} non-@code{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 @var{window}'s +combination. Optional argument @var{nodown} non-@code{nil} means don't +check whether @var{window} itself and its subwindows can be resized. +@end defun + +The function @code{window-resizable} does not change any window sizes. +The following function does: + +@defun window-resize window delta &optional horizontal ignore +This function resizes @var{window} vertically by @var{delta} lines. The +argument @var{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 @var{delta} a positive number means @var{window} shall +be enlarged by @var{delta} lines. If @var{delta} is negative, that +means @var{window} shall be shrunk by -@var{delta} lines. + +Optional argument @var{horizontal} non-@code{nil} means to resize +@var{window} horizontally by @var{delta} columns. In this case a +positive @var{delta} means enlarge @var{window} by @var{delta} columns. +A negative @var{delta} means @var{window} shall be shrunk by +-@var{delta} columns. + +Optional argument @var{ignore} has the same meaning as for the function +@code{window-resizable} above. + +This function can simultaneously move two edges of WINDOW. Exactly +which edges of @var{window} are moved and which other windows are +resized along with @var{window} is determined by the splits and nest +status of the involved windows (@pxref{Splitting Windows}). If only the +low (right) edge of @var{window} shall be moved, the function +@code{adjust-window-trailing-edge} described below should be used. +@end defun + +The next four commands are simple interfaces to @code{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 @code{window-min-height}, @code{window-min-width}, or +@code{window-size-fixed}. + +@deffn Command enlarge-window delta &optional horizontal +This function makes the selected window @var{delta} lines taller. +Interactively, if no argument is given, it makes the selected window one +line taller. If optional argument @var{horizontal} is non-@code{nil}, +it makes the selected window wider by @var{delta} columns. If +@var{delta} is negative, it shrinks the selected window by -@var{delta} +lines or columns. The return value is @code{nil}. +@end deffn + +@deffn Command enlarge-window-horizontally delta +This function makes the selected window @var{delta} columns wider. +Interactively, if no argument is given, it makes the selected window one +column wider. +@end deffn + +@deffn Command shrink-window delta &optional horizontal +This function makes the selected window @var{delta} lines smaller. +Interactively, if no argument is given, it makes the selected window one +line smaller. If optional argument @var{horizontal} is non-@code{nil}, +it makes the selected window narrower by @var{delta} columns. If +@var{delta} is negative, it enlarges the selected window by -@var{delta} +lines or columns. The return value is @code{nil}. +@end deffn + +@deffn Command shrink-window-horizontally delta +This function makes the selected window @var{delta} columns narrower. +Interactively, if no argument is given, it makes the selected window one +column narrower. +@end deffn + +The following function is useful for moving the line dividing two +windows. + +@defun adjust-window-trailing-edge window delta &optional horizontal +This function moves @var{window}'s bottom edge by @var{delta} lines. +Optional argument @var{horizontal} non-@code{nil} means to move +@var{window}'s right edge by @var{delta} columns. The argument +@var{window} defaults to the selected window. + +If @var{delta} is greater zero, this moves the edge downwards or to the +right. If @var{delta} is less than zero, this moves the edge upwards or +to the left. If the edge can't be moved by @var{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 +@var{window}, you should not use this function but call +@code{window-resize} (see above) instead. @end defun +@deffn Command fit-window-to-buffer &optional window max-height min-height override +This command makes @var{window} the right height to display its +contents exactly. The default for @var{window} is the selected window. + +The optional argument @var{max-height} specifies the maximum total +height the window is allowed to be; @code{nil} means use the maximum +permissible height of a window on @var{window}'s frame. The optional +argument @var{min-height} specifies the minimum toatl height for the +window; @code{nil} means use @code{window-min-height}. All these height +values include the mode line and/or header line. + +If the optional argument @var{override} is non-@code{nil}, this means to +ignore any restrictions imposed by @code{window-min-height} and +@code{window-min-width} on the size of @var{window}. + +This function returns non-@code{nil} if it orderly resized @var{window}, +and @code{nil} otherwise. +@end deffn + +@deffn Command shrink-window-if-larger-than-buffer &optional window +This command shrinks @var{window} vertically to be as small as possible +while still showing the full contents of its buffer---but not less than +@code{window-min-height} lines. The argument @var{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-@code{nil} if it actually shrank the window +and @code{nil} otherwise. +@end deffn + +@cindex balancing window sizes +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. + +@deffn 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 @var{window-or-frame} +specifies a frame, it balances all windows on that frame. If +@var{window-or-frame} specifies a window, it balances that window and +its siblings (@pxref{Windows and Frames}) only. +@end deffn + +@deffn 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. +@end deffn + +@cindex maximizing windows +The following function can be used to give a window the maximum possible +size without deleting other ones. + +@deffn Command maximize-window &optional window +This function maximizes @var{window}. More precisely, this makes +@var{window} as large as possible without resizing its frame or deleting +other windows. @var{window} can be any window and defaults to the +selected one. +@end deffn + +@cindex minimizing windows +To make a window as small as possible without deleting it the +following function can be used. + +@deffn Command minimize-window &optional window +This function minimizes @var{window}. More precisely, this makes +@var{window} as small as possible without deleting it or resizing its +frame. @var{window} can be any window and defaults to the selected one. +@end deffn + + @node Splitting Windows @section Splitting Windows @cindex splitting windows @cindex window splitting -The functions described below are the primitives used to split a window -into two windows. They do not accept a buffer as an argument. Rather, -the two ``halves'' of the split window initially display the same buffer +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. -@deffn Command split-window &optional window size horizontal -This function splits a new window out of @var{window}'s screen area. It -returns the new window. The default for @var{window} is the selected -window. When you split the selected window, it remains selected. - -If @var{horizontal} is non-@code{nil}, then @var{window} splits into two -side by side windows. The original window keeps the leftmost @var{size} -columns, and gives the rest of the columns to the new window. -Otherwise, @var{window} splits into windows one above the other, the -original window keeps the upper @var{size} lines and gives the rest of -the lines to the new window. The original window @var{window} is -therefore the left-hand or upper of the two, and the new window is the -right-hand or lower. - -If @var{size} is omitted or @code{nil}, then @var{window} is divided -evenly into two parts. (If there is an odd line, it is allocated to -the new window.) When @code{split-window} is called interactively, -all its arguments are @code{nil}. - -If splitting would result in making a window that is smaller than -@code{window-min-height} or @code{window-min-width} (@pxref{Resizing -Windows}), @code{split-window} signals an error and does not split the -window at all. +@deffn Command split-window &optional window size side +This function creates a new window adjacent to @var{window}. It returns +the new window which is always a live window. The argument @var{window} +can denote any window and defaults to the selected one. This function +does not change the selected window. + +Optional second argument @var{size} a positive number means make +@var{window} @var{size} lines (or columns) tall. If @var{size} is +negative, make the new window @minus{}@var{size} lines (or columns) +tall. If @var{size} is omitted or @code{nil}, then @var{window} is +divided evenly into two parts. (If there is an odd line, it is +allocated to the new window.) + +If splitting would result in making a window smaller than +@code{window-min-height} or @code{window-min-width} (@pxref{Window +Sizes}), this function usually signals an error. However, if @var{size} +is non-@code{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 @var{side} @code{nil} (or @code{below}) +specifies that the new window shall be located below @var{window}. The +value @code{above} means the new window will be located above +@var{window}. In both cases @var{size} specifies the new number of +lines for @var{window} (or the new window if @var{size} is negative) +including space reserved for the mode and/or header line. + +If @var{side} is @code{t} or @code{right} the new window will be +positioned on the right side of @var{window}. The value @code{left} +means the new window will be located on the left side of @var{window}. +In both cases @var{size} specifies the new number of columns for +@var{window} (or the new window provided @var{size} is negative) +including space reserved for margins, fringes and the scroll bar or a +divider column. + +Any other non-@code{nil} value for @var{side} is currently handled like +@code{t} (or @code{right}). Since this might change in the future, +application programs should refrain from using other values. + +If @var{window} is live, properties of the new window like margins and +scroll bars are inherited from @var{window}. If @var{window} is an +internal window, these properties, as well as the buffer shown in the +new window, are inherited from the window selected on @var{window}'s +frame. + +If @code{ignore-window-parameters} is non-@code{nil}, this function +ignores window parameters (@pxref{Window Parameters}). Otherwise, if +the @code{split-window} parameter of @var{window} is @code{t}, it splits +the window disregarding any other window parameters. If the +@code{split-window} parameter specifies a function, that function is +called with the arguments @var{window}, @var{size}, and @var{side} to +split @var{window}. If that function is @code{ignore}, nothing is done. +@end deffn The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then it splits the window. @smallexample @group -(setq w (selected-window)) +(setq W1 (selected-window)) @result{} #<window 8 on windows.texi> -(window-edges) ; @r{Edges in order:} - @result{} (0 0 80 50) ; @r{left--top--right--bottom} -@end group - -@group -;; @r{Returns window created} -(setq w2 (split-window w 15)) +(setq W2 (split-window W1 15)) @result{} #<window 28 on windows.texi> @end group @group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window;} - ; @r{top is line 15} -@end group -@group -(window-edges w) - @result{} (0 0 80 15) ; @r{Top window} +(window-top-line W1) + @result{} 0 +(window-total-size W1) + @result{} 15 +(window-top-line W2) + @result{} 15 @end group @end smallexample @@ -168,34 +1018,30 @@ The screen looks like this: @group __________ | | line 0 - | w | + | W1 | |__________| | | line 15 - | w2 | + | W2 | |__________| line 50 column 0 column 80 @end group @end smallexample -Next, split the top window horizontally: +Next, split the top window into two side-by-side windows: @smallexample @group -(setq w3 (split-window w 35 t)) +(setq W3 (split-window W1 35 t)) @result{} #<window 32 on windows.texi> @end group @group -(window-edges w3) - @result{} (35 0 80 15) ; @r{Left edge at column 35} -@end group -@group -(window-edges w) - @result{} (0 0 35 15) ; @r{Right edge at column 35} -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window unchanged} +(window-left-column W1) + @result{} 0 +(window-total-size W1 t) + @result{} 35 +(window-left-column W3) + @result{} 35 @end group @end smallexample @@ -206,11 +1052,11 @@ Now the screen looks like this: @group column 35 __________ - | | | line 0 - | w | w3 | - |___|______| + | | | line 0 + | W1 | W3 | + |____|_____| | | line 15 - | w2 | + | W2 | |__________| line 50 column 0 column 80 @@ -221,9 +1067,492 @@ Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The display table can specify alternative border characters; see @ref{Display Tables}. -@end deffn -@deffn Command split-window-vertically &optional size +Below we describe how @code{split-window} can be used to create the +window configuration from our earlier example (@pxref{Windows and +Frames}) and how internal windows are created for this purpose. We +start with a frame containing one live window @code{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 +@code{(split-window W2 8 t)} creates a new internal window @code{W1} +with two children---@code{W2} (the window we've split) and a new leaf +window @code{W6}: +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + ||__W2__||_____________W6_____________ | + |__________________W1__________________| + +@end group +@end smallexample + +Evaluating now @code{(split-window W6 -3)} creates another internal +window @code{W3} with two children---@code{W6} and a new live window +@code{W5}. This leaves us with a vertically combined window @code{W3} +embedded in the horizontally combined window @code{W1}: +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ||| + || ||| ||| + || ||| ||| + || ||| ||| + || ||| ||| + || |||____________W6____________||| + || || __________________________ || + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| + +@end group +@end smallexample + +Finally, evaluating @code{(split-window W6 nil t)} should get us the +desired configuration as depicted below. +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ___________ ___________ ||| + || |||| || |||| + || |||| || |||| + || ||||_____W6____||_____W7____|||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| + +@end group +@end smallexample + +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 +@code{W6} by evaluating @code{(split-window W6 -3)} to produce the +following vertical combination: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + || || + ||_________________W6_________________|| + | ____________________________________ | + || || + ||_________________W5_________________|| + |__________________W3__________________| + +@end group +@end smallexample + +Evaluating now @code{(split-window (window-parent W6) -8 'left)} or, +equivalently, @code{(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 inital window @code{W6} by +evaluating @code{(split-window W6 nil nil t)} with the following result: +@smallexample +@group + ______________________________________ + | _________________ _________________ | + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + || || || + ||________W6_______||________W7_______|| + |__________________W4__________________| + +@end group +@end smallexample + +Evaluating now @code{(split-window W4 -3)} or @code{(split-window +(window-parent W6) -3)} should get us a configuration as shown next. +@smallexample +@group + ______________________________________ + | ____________________________________ | + || ________________ ________________ || + ||| || ||| + ||| || ||| + ||| || ||| + ||| || ||| + ||| || ||| + |||_______W6_______||________W7______||| + ||_________________W4_________________|| + | ____________________________________ | + || || + ||_________________W5_________________|| + |__________________W3__________________| + +@end group +@end smallexample + +The desired configuration can be now obtained by evaluating +@code{(split-window W3 -8 'left)} or, equivalently, @code{(split-window +(window-parent W5) -8 'left)}. + + For a final approach let's start with the configuration of two live +windows @code{W6} and @code{W7} shown above. If we now evaluate +@code{(split-window W4 -8 'left)} or @code{(split-window (window-parent +W6) -8 'left)} we get the following configuration. +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || ____________ ____________ || + || ||| || ||| + || ||| || ||| + || ||| || ||| + || ||| || ||| + || ||| || ||| + || ||| || ||| + || ||| || ||| + || |||______W6____||______W7____||| + ||__W2__||_____________W4_____________|| + |__________________W1__________________| + +@end group +@end smallexample + +Evaluating now @code{(split-window W4 -3)} or, for example, +@code{(split-window (window-parent W6) -3)} should produce the desired +configuration. + + The two options described next can be used to tune the operation of +@code{split-window}. + +@defopt window-splits +If this variable is nil, the function @code{split-window} can split a +window if and only if that window's screen estate is sufficiently large +to accomodate both--itself and the new window. + +If this variable is non-@code{nil}, @code{split-window} tries to resize +all windows that are part of the same combination as the old window to +accomodate the new window. Hence, the new window can be also created if +the old window is of fixed size or too small to split (@pxref{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 @code{window-splits} and +altered by the function @code{set-window-splits} described next. + +If @code{window-nest} (see below) is non-@code{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. +@end defopt + +@defun window-splits &optional window +This function returns the splits status of @var{window}. The argument +@var{window} can be any window and defaults to the selected one. + +@cindex splits status +The @dfn{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 @var{window}'s splits status is +@code{nil} and @var{window} is resized, the corresponding space is +preferably taken from (or given to) @var{window}'s right sibling. When +@var{window} is deleted, its space is given to its left sibling. If +@var{window}'s splits status is non-@code{nil}, resizing and deleting +@var{window} may resize @emph{all} windows in @var{window}'s +combination. + +The splits status is initially set by @code{split-window} +from the current value of the variable @code{window-splits} (see above) +and can be reset by the function @code{set-window-splits} (see below). +@end defun + +@defun set-window-splits window &optional status +This function sets the splits status (see above) of @var{window} to +@var{status}. The argument @var{window} can be any window and defaults +to the selected one. The return value is @var{status}. +@end defun + +To illustrate the use of @code{window-splits} consider the following +window configuration: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Splitting window @code{W3} with @code{window-splits} @code{nil} +produces a configuration where the size of @code{W2} remains unchanged: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + ||_________________W4_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Splitting @code{W3} with @code{window-splits} non-@code{nil} instead +produces a configuration where all windows have approximately the same +height: + +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + || || + ||_________________W4_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +@defopt window-nest +If this variable is @code{nil}, @code{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-@code{nil}, @code{split-window} always creates a new parent +window. If this variable is always non-@code{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 @code{window-nest} and altered by the function +@code{set-window-nest}, see below. +@end defopt + +@defun window-nest &optional window +This function returns the nest status of @var{window}. The argument +@var{window} can be any window and defaults to the selected one. Note, +however, that the nest status is currently meaningful for internal +windows only. + +@cindex nest status +The @dfn{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 @code{split-window} from the current value of the variable +@code{window-nest} (see above) and can be reset by the function +@code{set-window-nest} (see below). + +If the return value is @code{nil}, subwindows of @var{window} may be +recombined with @var{window}'s siblings when a window gets deleted. A +return value of @code{nil} means that subwindows of @var{window} are +never (re-)combined with @var{window}'s siblings in such a case. +@end defun + +@defun set-window-nest window &optional status +This functions sets the nest status (see above) of @var{window} to +@var{status}. The argument @var{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 @var{status}. +@end defun + +To illustrate the use of @code{window-nest} consider the following +configuration (throughout the following examples we shall assume that +@code{window-splits} invariantly is @code{nil}). +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Splitting @code{W2} into two windows above each other with +@code{window-nest} equal @code{nil} will get you a configuration like: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +If you now enlarge window @code{W4}, Emacs steals the necessary space +from window @code{W3} resulting in a configuration like: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Deleting window @code{W4}, will return its space to @code{W2} as +follows: +@smallexample +@group + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Hence, with respect to the initial configuration, window @code{W2} has +grown at the expense of window @code{W3}. If, however, in the initial +configuration you had split @code{W2} with @code{window-nest} bound to +@code{t}, a new internal window @code{W5} would have been created as +depicted below. +@smallexample +@group + ______________________________________ + | ____________________________________ | + || __________________________________ || + ||| ||| + |||________________W2________________||| + || __________________________________ || + ||| ||| + |||________________W4________________||| + ||_________________W5_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +Enlarging @code{W4} would now have stolen the necessary space from +@code{W2} instead of @code{W3} as +@smallexample +@group + ______________________________________ + | ____________________________________ | + || __________________________________ || + |||________________W2________________||| + || __________________________________ || + ||| ||| + ||| ||| + |||________________W4________________||| + ||_________________W5_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + +@end group +@end smallexample + +and the subsequent deletion of @code{W4} would have restored the initial +configuration. + +For interactive use, Emacs provides two commands which always split the +selected window. + +@deffn 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 @var{size} lines. (If @var{size} is negative, then the lower of the two windows @@ -232,76 +1561,30 @@ the upper window is still the one selected.) However, if @code{split-window-keep-point} (see below) is @code{nil}, then either window can be selected. -In other respects, this function is similar to @code{split-window}. -In particular, the upper window is the original one and the return -value is the new, lower window. + In other respects, this function is similar to @code{split-window}. +In particular, the upper window is the original one and the return value +is the new, lower window. @end deffn @defopt split-window-keep-point If this variable is non-@code{nil} (the default), then -@code{split-window-vertically} behaves as described above. - -If it is @code{nil}, then @code{split-window-vertically} adjusts point -in each of the two windows to avoid scrolling. (This is useful on -slow terminals.) It selects whichever window contains the screen line -that point was previously on. +@code{split-window-above-each-other} behaves as described above. -This variable affects the behavior of @code{split-window-vertically} -only. It has no effect on the other functions described here. + If it is @code{nil}, then @code{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. @end defopt -@deffn Command split-window-horizontally &optional size +@deffn 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 @var{size} columns. If @var{size} is negative, the rightmost window gets @minus{}@var{size} columns, but the leftmost window still remains selected. - -This function is basically an interface to @code{split-window}. -You could define a simplified version of the function like this: - -@smallexample -@group -(defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") -@end group -@group - (let ((size (and arg (prefix-numeric-value arg)))) - (and size (< size 0) - (setq size (+ (window-width) size))) - (split-window nil size t))) -@end group -@end smallexample @end deffn -@defun one-window-p &optional no-mini all-frames -This function returns non-@code{nil} if there is only one window. The -argument @var{no-mini}, if non-@code{nil}, means don't count the -minibuffer even if it is active; otherwise, the minibuffer window is -counted when it is active. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Count the windows in the selected frame, plus the minibuffer used -by that frame even if it lies in some other frame. - -@item @code{t} -Count all windows in all existing frames. - -@item @code{visible} -Count all windows in all visible frames. - -@item 0 -Count all windows in all visible or iconified frames. - -@item anything else -Count precisely the windows in the selected frame, and no others. -@end table -@end defun @node Deleting Windows @section Deleting Windows @@ -313,105 +1596,110 @@ appear on the screen, but continues to exist as a Lisp object until there are no references to it. There is no way to cancel the deletion of a window aside from restoring a saved window configuration (@pxref{Window Configurations}). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one of -its sibling windows adjacent to it. - -@c Emacs 19 feature -@defun window-live-p window -This function returns @code{nil} if @var{window} is deleted, and -@code{t} otherwise. - -@strong{Warning:} Erroneous information or fatal errors may result from -using a deleted window as if it were live. -@end defun +deletes any windows that aren't part of that configuration. Erroneous +information may result from using a deleted window as if it were live. @deffn Command delete-window &optional window This function removes @var{window} from display and returns @code{nil}. -The default for @var{window} is the selected window. An error is -signaled if @var{window} is the only window on its frame. +The argument @var{window} can denote any window and defaults to the +selected one. An error is signaled if @var{window} is the only window +on its frame. Hence @var{window} must have at least one sibling window +(@pxref{Windows and Frames}) in order to get deleted. + +If the variable @code{ignore-window-parameters} (@pxref{Window +Parameters}) is non-@code{nil}, this function ignores all parameters of +@var{window}. Otherwise, if the @code{delete-window} parameter of +@var{window} is @code{t}, it deletes the window disregarding other +window parameters. If the @code{delete-window} parameter specifies a +function, that function is called with @var{window} as its sole +argument. + +If the splits status of @var{window} (@pxref{Splitting Windows}) is +@code{nil}, the space @var{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 @var{window} is non-@code{nil}, its space is +proportionally distributed among the remaining windows in the same +combination. @end deffn @deffn Command delete-other-windows &optional window -This function makes @var{window} the only window on its frame, by -deleting the other windows in that frame. The default for @var{window} -is the selected window. The return value is @code{nil}. +This function makes @var{window} fill its frame and returns @code{nil}. +The argument @var{window} can denote an arbitrary window and defaults to +the selected one. + +If the variable @code{ignore-window-parameters} (@pxref{Window +Parameters}) is non-@code{nil}, this function ignores all parameters of +@var{window}. Otherwise, if the @code{delete-other-windows} parameter +of @var{window} equals @code{t}, it deletes all other windows +disregarding any remaining window parameters. If the +@code{delete-other-windows} parameter of @var{window} specifies a +function, it calls that function with @var{window} as its sole argument. @end deffn @deffn Command delete-windows-on &optional buffer-or-name frame -This function deletes all windows showing @var{buffer-or-name}. If -there are no windows showing @var{buffer-or-name}, it does nothing. The -optional argument @var{buffer-or-name} may be a buffer or the name of an -existing buffer and defaults to the current buffer. - -@code{delete-windows-on} operates frame by frame. If a frame has -several windows showing different buffers, then those showing -@var{buffer-or-name} are removed, and the others expand to fill the -space. If all windows in some frame are showing @var{buffer-or-name} -(including the case where there is only one window), then the frame -winds up with a single window showing another buffer chosen with -@code{other-buffer} (@pxref{The Buffer List}). If, however, the window -showing @var{buffer-or-name} is dedicated to its buffer -(@pxref{Dedicated Windows}), and there are other frames left, that -window's frame is deleted. +This function deletes all windows showing @var{buffer-or-name} and +returns nil. If there are no windows showing @var{buffer-or-name}, it +does nothing. The optional argument @var{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 @code{delete-windows-on} operates by calling +@code{delete-window} for each window showing @var{buffer-or-name}. If a +frame has several windows showing different buffers, then those showing +@var{buffer-or-name} are removed, and the other windows expand to fill +the space. + +If all windows in some frame are showing @var{buffer-or-name} (including +the case where there is only one window), then that frame is deleted +provided there are other frames left. The optional argument @var{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 windows; specifically, the values @code{t} and -@code{nil} have the opposite of their meanings in other functions. Here -are the full details: +functions which scan all live windows (@pxref{Cyclic Window Ordering}); +specifically, the values @code{t} and @code{nil} have the opposite of +their meanings in the other functions. Here are the full details: @itemize @bullet -@item -If it is @code{nil}, operate on all frames. -@item -If it is @code{t}, operate on the selected frame. -@item -If it is @code{visible}, operate on all visible frames. -@item -If it is 0, operate on all visible or iconified frames. -@item -If it is a frame, operate on that frame. +@item @code{nil} +means operate on all frames. +@item @code{t} +means operate on the selected frame. +@item @code{visible} +means operate on all visible frames. +@item @code{0} +means operate on all visible or iconified frames. +@item A frame +means operate on that frame. @end itemize - -This function always returns @code{nil}. @end deffn + @node Selecting Windows @section Selecting Windows @cindex selecting a window - When a window is selected, the buffer in the window becomes the current -buffer, and the cursor will appear in it. - -@defun selected-window -This function returns the selected window. This is the window in -which the cursor appears and to which many commands apply. -@end defun - @defun select-window window &optional norecord -This function makes @var{window} the selected window. The cursor then -appears in @var{window} (after redisplay). Unless @var{window} was -already selected, @code{select-window} makes @var{window}'s buffer the -current buffer. The return value is @var{window}. +This function makes @var{window} the selected window, see @ref{Basic +Windows}. Unless @var{window} already is the selected window, this also +makes @var{window}'s buffer (@pxref{Buffers and Windows}) the current +buffer. Moreover, the cursor for selected windows will be displayed in +@var{window} after the next redisplay. This function returns +@var{window}. Normally, @var{window}'s selected buffer is moved to the front of the buffer list (@pxref{The Buffer List}) and @var{window} becomes the most -recently selected window. But if @var{norecord} is non-@code{nil}, the -buffer list remains unchanged and @var{window} does not become the most -recently selected one. - - -@example -@group -(setq w (next-window)) -(select-window w) - @result{} #<window 65 on windows.texi> -@end group -@end example +recently selected window. But if the optional argument @var{norecord} +is non-@code{nil}, the buffer list remains unchanged and @var{window} +does not become the most recently selected one. @end defun +@cindex most recently selected windows +The sequence of calls to @code{select-window} with a non-@code{nil} +@var{norecord} argument determines an ordering of windows by their +selection time. The function @code{get-lru-window} can be used to +retrieve the least recently selected live window in this ordering, see +@ref{Cyclic Window Ordering}. + @defmac save-selected-window forms@dots{} This macro records the selected frame, as well as the selected window of each frame, executes @var{forms} in sequence, then restores the @@ -437,138 +1725,105 @@ 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 @var{forms}, for example, by calling @code{select-window} with argument @var{norecord} @code{nil}. -@end defmac - -@cindex finding windows - The following functions choose one of the windows on the screen, -offering various criteria for the choice. - -@defun get-lru-window &optional frame dedicated -This function returns the window least recently ``used'' (that is, -selected) among a set of candidate windows. If any full-width windows -are present, it only considers these. - -The selected window is returned if it is the only candidate. A -minibuffer window is never a candidate. A dedicated window -(@pxref{Dedicated Windows}) is never a candidate unless the optional -argument @var{dedicated} is non-@code{nil}. -The optional argument @var{frame} specifies which windows are -considered. +The order of recently selected windows and the buffer list are not +changed by this macro. +@end defmac -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize +@cindex frame selected window +@cindex window selected within frame +Earlier (@pxref{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 +@code{select-window} also makes that window selected within its frame. + +@defun frame-selected-window &optional frame +This function returns the window on @var{frame} that is selected within +@var{frame}. The optional argument @var{frame} must denote a live frame +and defaults to the selected one. @end defun -@defun get-largest-window &optional frame dedicated -This function returns the window with the largest area (height times -width). If there are no side-by-side windows, then this is the window -with the most lines. A minibuffer window is never a candidate. A -dedicated window (@pxref{Dedicated Windows}) is never a candidate unless -the optional argument @var{dedicated} is non-@code{nil}. - -If there are two candidate windows of the same size, this function -prefers the one that comes first in the cyclic ordering of windows, -starting from the selected window (@pxref{Cyclic Window Ordering}). - -The optional argument @var{frame} specifies which set of windows to -consider, see @code{get-lru-window} above. +@defun set-frame-selected-window frame window &optional norecord +This function sets the selected window of frame @var{frame} to +@var{window}. The argument @var{frame} must denote a live frame and +defaults to the selected one. If @var{frame} is the selected frame, +this also makes @var{window} the selected window. The argument +@var{window} must denote a live window. This function returns +@var{window}. + +Optional argument @var{norecord} non-@code{nil} means to neither change +the list of most recently selected windows (@pxref{Selecting Windows}) +nor the buffer list (@pxref{The Buffer List}). @end defun -@cindex window that satisfies a predicate -@cindex conditional selection of windows -@defun get-window-with-predicate predicate &optional minibuf all-frames default -This function returns a window satisfying @var{predicate}. It cycles -through all visible windows using @code{walk-windows} (@pxref{Cyclic -Window Ordering}), calling @var{predicate} on each one of them with that -window as its argument. The function returns the first window for which -@var{predicate} returns a non-@code{nil} value; if that never happens, -it returns @var{default} (which defaults to @code{nil}). - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the scan. See the description of -@code{next-window} in @ref{Cyclic Window Ordering}, for details. -@end defun @node Cyclic Window Ordering -@comment node-name, next, previous, up @section Cyclic Ordering of Windows @cindex cyclic ordering of windows @cindex ordering of windows, cyclic @cindex window ordering, cyclic - When you use the command @kbd{C-x o} (@code{other-window}) to select -some other window, it moves through the windows on the screen in a -specific order. For any given configuration of windows, this order -never varies. It is called the @dfn{cyclic ordering of windows}. +When you use the command @kbd{C-x o} (@code{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 @dfn{cyclic ordering of windows}. - For a particular frame, this ordering generally goes from top to -bottom, and from left to right. But it may go down first or go right -first, depending on the order in which windows were split. + For a particular frame, this ordering is determined by the window +tree of that frame, see @ref{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 the first split was vertical (into windows one above each other), -and then the subwindows were split horizontally, then the ordering is -left to right in the top of the frame, and then left to right in the -next lower part of the frame, and so on. If the first split was -horizontal, the ordering is top to bottom in the left part, and so on. -In general, within each set of siblings at any level in the window tree -(@pxref{Window Tree}), the order is left to right, or top to bottom. + 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, @ref{Finding All Frames}. In any case, the ordering is made +``cyclic'' by having the last window precede the first window in the +ordering. @defun next-window &optional window minibuf all-frames @cindex minibuffer window, and @code{next-window} This function returns the window following @var{window} in the cyclic -ordering of windows. This is the window @kbd{C-x o} selects if typed -when @var{window} is selected. The default for @var{window} is the -selected window. +ordering of windows. The argument @var{window} must specify a live +window and defaults to the selected one. -The value of the optional argument @var{minibuf} specifies whether the -minibuffer is included in the window order. Normally, when -@var{minibuf} is @code{nil}, the minibuffer is included only if it is -currently ``active''; this matches the behavior of @kbd{C-x o}. (The -minibuffer window is active while the minibuffer is in use; see -@ref{Minibuffers}.) +The optional argument @var{minibuf} specifies whether minibuffer windows +shall be included in the cyclic ordering. Normally, when @var{minibuf} +is @code{nil}, a minibuffer window is included only if it is currently +``active''; this matches the behavior of @kbd{C-x o}. (Note that a +minibuffer window is active as long as its minibuffer is in use; see +@ref{Minibuffers}). -If @var{minibuf} is @code{t}, the cyclic ordering includes the -minibuffer window even if it is not active. If @var{minibuf} is neither -@code{t} nor @code{nil}, the minibuffer window is not included even if -it is active. +If @var{minibuf} is @code{t}, the cyclic ordering includes all +minibuffer windows. If @var{minibuf} is neither @code{t} nor +@code{nil}, minibuffer windows are not included even if they are active. The optional argument @var{all-frames} specifies which frames to consider. Here are the possible values and their meanings: -@table @asis +@itemize @bullet @item @code{nil} -Consider all the windows in @var{window}'s frame, plus the minibuffer -used by that frame even if it lies in some other frame. If the +means consider all windows on @var{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 @var{minibuf}), then all windows on all frames that share that minibuffer count too. @item @code{t} -Consider all windows in all existing frames. +means consider all windows on all existing frames. @item @code{visible} -Consider all windows in all visible frames. (To get useful results, you -must ensure @var{window} is in a visible frame.) +means consider all windows on all visible frames. (To get useful +results, ensure that @var{window} is on a visible frame.) @item 0 -Consider all windows in all visible or iconified frames. +means consider all windows on all visible or iconified frames. -@item a frame -Consider all windows on that frame. +@item A frame +means consider all windows on that frame. -@item anything else -Consider precisely the windows in @var{window}'s frame, and no others. -@end table +@item Anything else +means consider the windows on @var{window}'s frame, and no others. +@end itemize This example assumes there are two windows, both displaying the buffer @samp{windows.texi}: @@ -592,7 +1847,7 @@ buffer @samp{windows.texi}: @defun previous-window &optional window minibuf all-frames This function returns the window preceding @var{window} in the cyclic ordering of windows. The other arguments specify which windows to -include in the cycle, as in @code{next-window}. +consider as in @code{next-window}. @end defun @deffn Command other-window count &optional all-frames @@ -608,80 +1863,153 @@ prefix argument. The optional argument @var{all-frames} has the same meaning as in @code{next-window}, but the @var{minibuf} argument of @code{next-window} is always effectively @code{nil}. This function returns @code{nil}. + +This function does not select a window that has a non-@code{nil} +@code{no-other-window} window parameter (@pxref{Window Parameters}). @end deffn -@c Emacs 19 feature +The following function returns a copy of the list of windows in the +cyclic odering. + +@defun window-list-1 &optional window &optional minibuf &optional all_frames +This function returns a list of live windows. The optional arguments +@var{minibuf} and @var{all-frames} specify the set of windows to include +in the list. See the description of @code{next-window} for details. + +The optional argument @var{window} specifies the first window to list +and defaults to the selected window. If @var{window} is not on the list +of windows returned, some other window will be listed first but no error +is signalled. +@end defun + +The functions described below use @code{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 @emph{not} reflected in the list of windows investigated. + @defun walk-windows proc &optional minibuf all-frames -This function cycles through all windows. It calls the function -@code{proc} once for each window, with the window as its sole -argument. +This function cycles through live windows. It calls the function +@var{proc} once for each window, with the window as its sole argument. The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the walk. See @code{next-window}, above, -for details. +set of windows to include in the walk, see @code{next-window} above. If +@var{all-frames} specifies a frame, the first window walked is the first +window on that frame as returned by @code{frame-first-window} and not +necessarily the selected window. + +If @var{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. @end defun -@defun window-list &optional frame minibuf window -This function returns a list of all windows on @var{frame}, starting -with @var{window}. The default for @var{frame} is the selected frame; -the default for @var{window} is the selected window. +The following function allows to determine whether a specific window is +the only live window. -The value of @var{minibuf} specifies if the minibuffer window shall be -included in the result list. If @var{minibuf} is @code{t}, the result -always includes the minibuffer window. If @var{minibuf} is @code{nil} -or omitted, that includes the minibuffer window if it is active. If -@var{minibuf} is neither @code{nil} nor @code{t}, the result never -includes the minibuffer window. +@defun one-window-p &optional no-mini all-frames +This function returns non-@code{nil} if the selected window is the only +window. + +The optional argument @var{no-mini}, if non-@code{nil}, means don't +count the minibuffer even if it is active; otherwise, the minibuffer +window is counted when it is active. The optional argument +@var{all-frames} has the same meaning as for @code{next-window}, see +above. +@end defun + +@cindex finding windows + The following functions choose (but do not select) one of the windows +on the screen, offering various criteria for the choice. + +@cindex least recently used window +@defun 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 @var{all-frames} has the same meaning as +in @code{next-window}. + +The selected window is returned if it is the only candidate. A +minibuffer window is never a candidate. A dedicated window +(@pxref{Dedicated Windows}) is never a candidate unless the optional +argument @var{dedicated} is non-@code{nil}. +@end defun + +@cindex largest window +@defun 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 +(@pxref{Dedicated Windows}) is never a candidate unless the optional +argument @var{dedicated} is non-@code{nil}. + +If there are two candidate windows of the same size, this function +prefers the one that comes first in the cyclic ordering of windows, +starting from the selected window. + +The optional argument @var{all-frames} specifies which set of windows to +consider as with @code{next-window}, see above. +@end defun + +@cindex window that satisfies a predicate +@cindex conditional selection of windows +@defun get-window-with-predicate predicate &optional minibuf all-frames default +This function returns a window satisfying @var{predicate}. It cycles +through all visible windows calling @var{predicate} on each one of them +with that window as its argument. The function returns the first window +for which @var{predicate} returns a non-@code{nil} value; if that never +happens, it returns @var{default} (which defaults to @code{nil}). + +The optional arguments @var{minibuf} and @var{all-frames} specify the +set of windows to investigate. See the description of +@code{next-window} for details. @end defun + @node Buffers and Windows @section Buffers and Windows @cindex examining windows @cindex windows, controlling precisely @cindex buffers, controlled in windows - This section describes low-level functions to examine windows or to -display buffers in windows in a precisely controlled fashion. -@iftex -See the following section for -@end iftex -@ifnottex -@xref{Displaying Buffers}, for -@end ifnottex -related functions that find a window to use and specify a buffer for it. -The functions described there are easier to use, but they employ -heuristics in choosing or creating a window; use the functions described -here when you need complete control. +To find out which buffer is displayed in a given window the following +function is used. -@defun set-window-buffer window buffer-or-name &optional keep-margins -This function makes @var{window} display @var{buffer-or-name} as its -contents. It returns @code{nil}. The default for @var{window} is the -selected window. The argument @var{buffer-or-name} must specify a -buffer or the name of an existing buffer. +@defun window-buffer &optional window +This function returns the buffer that @var{window} is displaying. The +argument @var{window} can be any window and defaults to the selected +one. If @var{window} is an internal window, this function returns +@code{nil}. +@end defun -@code{set-window-buffer} is the fundamental primitive for changing which -buffer is displayed in a window, and all ways of doing that call this -function. +The basic, low-level function to associate a window with a buffer is +@code{set-window-buffer}. Higher-level functions like +@code{display-buffer} try to obey a number of user customizations +regulating which windows are supposed to display which buffers. When +writing an application, programmers should therefore carefully evaluate +whether they really need the power of @code{set-window-buffer}. -@example -@group -(set-window-buffer (selected-window) "foo") - @result{} nil -@end group -@end example +@defun set-window-buffer window buffer-or-name &optional keep-margins +This function makes @var{window} display @var{buffer-or-name} and +returns @code{nil}. The argument @var{window} has to denote a live +window and defaults to the selected one. The argument +@var{buffer-or-name} must specify a buffer or the name of an existing +buffer. An error is signalled when @var{window} is @dfn{strongly} +dedicated to its buffer (@pxref{Dedicated Windows}) and does not already +display @var{buffer-or-name}. Normally, displaying @var{buffer-or-name} in @var{window} resets the window's position, display margins, fringe widths, and scroll bar -settings based on the local variables of that buffer. -However, if @var{keep-margins} is non-@code{nil}, display margins and -fringe widths of @var{window} remain unchanged. @xref{Fringes}. - -@code{set-window-buffer} signals an error when @var{window} is -@dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and -does not already display @var{buffer-or-name}. +settings based on the local variables of the specified buffer. However, +if the optional argument @var{keep-margins} is non-@code{nil}, display +margins and fringe widths of @var{window} remain unchanged. +@xref{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. -Note that this function runs @code{window-scroll-functions} before -running @code{window-configuration-change-hook}. +This function runs @code{window-scroll-functions} before running +@code{window-configuration-change-hook}, see @ref{Window Hooks}. @end defun @defvar buffer-display-count @@ -690,26 +2018,22 @@ displayed in a window. It is incremented each time @code{set-window-buffer} is called for the buffer. @end defvar -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. The -default for @var{window} is the selected window. - -@example -@group -(window-buffer) - @result{} #<buffer windows.texi> -@end group -@end example -@end defun +@defvar buffer-display-time +This variable records the time at which a buffer was last made visible +in a window. It is always local in each buffer; each time +@code{set-window-buffer} is called, it sets this variable to +@code{(current-time)} in the specified buffer (@pxref{Time of Day}). +When a buffer is first created, @code{buffer-display-time} starts out +with the value @code{nil}. +@end defvar @defun get-buffer-window &optional buffer-or-name all-frames -This function returns a window currently displaying -@var{buffer-or-name}, or @code{nil} if there is none. If there are -several such windows, then the function returns the first one in the -cyclic ordering of windows, starting from the selected window. -@xref{Cyclic Window Ordering}. +This function returns a window displaying @var{buffer-or-name}, or +@code{nil} if there is none. If there are several such windows, then +the function returns the first one in the cyclic ordering of windows, +starting from the selected window, @xref{Cyclic Window Ordering}. -The argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and +The argument @var{buffer-or-name} may be a buffer or a buffer name and defaults to the current buffer. The optional argument @var{all-frames} specifies which windows to consider: @@ -739,18 +2063,146 @@ This function returns a list of all windows currently displaying or the name of an existing buffer and defaults to the current buffer. The two remaining arguments work like the same-named arguments of -@code{next-window}; they are @emph{not} like the optional arguments of -@code{get-buffer-window}. +@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} +like the optional arguments of @code{get-buffer-window}. @end defun -@defvar buffer-display-time -This variable records the time at which a buffer was last made visible -in a window. It is always local in each buffer; each time -@code{set-window-buffer} is called, it sets this variable to -@code{(current-time)} in the specified buffer (@pxref{Time of Day}). -When a buffer is first created, @code{buffer-display-time} starts out -with the value @code{nil}. -@end defvar +The following command removes a buffer from all windows showing it. + +@deffn Command replace-buffer-in-windows &optional buffer-or-name +This function replaces @var{buffer-or-name} in all windows displaying it +with some other buffer. It uses @code{switch-to-prev-buffer}, see +below, to choose that other buffer which is usually the last buffer +displayed before @var{buffer-or-name} in the respective window. + +The argument @var{buffer-or-name} may be a buffer or the name of an +existing buffer and defaults to the current buffer. + +If a window displaying @var{buffer-or-name} is dedicated +(@pxref{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 left, +the window's frame is deleted too. If there are no other frames left, +some other buffer is displayed in that window as explained above. You +can prevent the deletion of windows and/or frames by customizing the +option @var{window-auto-delete}. + +This function returns @code{nil}. +@end deffn + + When @code{replace-buffer-in-windows} has to show another buffer in a +window, it tries to pick the buffer shown there before. For this +purpose each window remembers the buffers it has displayed earlier and +the order in which these buffers have been removed from it. + +The list of @dfn{previous buffers} of a window is an association list +where each entry specifies a buffer, the last start position of that +buffer in the window (@pxref{Window Start and End}) and the last +position of that buffer's point in the window (@pxref{Window Point}). +This list is ordered by the times of the removal of the respective +buffers from the window. In particular, the first element of the list +references the buffer removed most recently. The function +@code{set-window-buffer} pushes an entry for the old buffer of its +window argument on that list before it shows its buffer argument in the +window. + +The list of @dfn{next buffers} of a window is a list of buffers that +have been recently re-shown by the function @code{switch-to-prev-buffer} +and is used to avoid that that function switches to such a buffer again +before showing other interesting buffers. + +The lists of previous and next buffers and the global buffer list +(@pxref{The Buffer List}) allow to effectively display all buffers in a +window while giving preference to the buffers previously shown in that +window. The commands used for this purpose are +@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} described +below. + +The following functions directly operate on the lists of previous and +next buffers. + +@defun window-prev-buffers &optional window +This function returns an alist specifying the buffers previously shown +in @var{window} together with their window start and point positions. +The argument @var{window} must be a live window and defaults to the +selected one. +@end defun + +@defun set-window-prev-buffers window prev-buffers +This function sets @var{window}'s previous buffers to the value of +@var{prev-buffers}. The argument @var{window} must be a live window and +defaults to the selected one. This function returns +@var{prev-buffers}. + +If non-@code{nil}, @var{prev-buffers} must specify an alist of triples +specifying a buffer and two markers for that buffer's start and point +position in @var{window}. +@end defun + +@defun window-next-buffers &optional window +This function returns the list of buffers recently re-shown in +@var{window}. The argument @var{window} must be a live window and +defaults to the selected one. +@end defun + +@defun set-window-next-buffers window next-buffers +This function sets @var{window}'s next buffers to @var{next-buffers}. +@var{window} must be a live window and defaults to the selected one. +This fucntion returns @var{next-buffers}. + +If non-@code{nil}, the argument @var{next-buffers} should specify a list +of buffers that shall be preferably not shown by the command +@code{switch-to-prev-buffer}, see below. +@end defun + +The following command is used by @code{replace-buffer-in-windows}, +@code{bury-buffer} and @code{quit-window} to show another buffer in a +window. It can be also used interactively to cycle through the list of +all buffers in a window, preferably showing the buffers recently shown +(but not buried or killed) in that window. + +@deffn Command switch-to-prev-buffer &optional window bury-or-kill +This function displays the previous buffer in @var{window}. The +argument @var{window} must be a live window and defaults to the selected +one. If the optional argument @var{bury-or-kill} is non-@code{nil}, +this means that the buffer currently shown in @var{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 @var{window}. However, a buffer that has been buried +or killed or has been already shown by a recent invocation of +@code{switch-to-prev-buffer} does not qualify as previous buffer. + +If repeated invocations of this command have already shown all buffers +previously shown in @var{window}, further invocations will show buffers +from the global buffer list starting with the buffer returned by +@code{last-buffer} (@pxref{The Buffer List}). +@end deffn + +The following command can be used to undo the effect of the last undone +@code{switch-to-prev-buffer} command. + +@deffn Command switch-to-next-buffer &optional window +This functions switches to the next buffer in @var{window} thus undoing +the effect of the last @code{switch-to-prev-buffer} command in +@var{window}. The argument @var{window} must be a live window and +defaults to the selected one. + +If there is no recent invocation of a @code{switch-to-prev-buffer} that +can be undone, @code{switch-to-next-buffer} will try to show the first +buffer from the global buffer list as returned by @code{other-buffer} +(@pxref{The Buffer List}). +@end deffn + + Together, @code{switch-to-prev-buffer} and +@code{switch-to-next-buffer} permit to navigate the global buffer list +much like @code{bury-buffer} and @code{unbury-buffer}. In contrast with +the latter, however, they may show a buffer even if it is already shown +in another window. Moreover, they try to restore the window specific +start and point positions of buffers which should handle viewing one and +the same buffer in multiple windows more easily. + @node Displaying Buffers @section Displaying Buffers in Windows @@ -1931,370 +3383,6 @@ is off the screen due to horizontal scrolling: @end group @end example -@node Size of Window -@section The Size of a Window -@cindex window size -@cindex size of window - - An Emacs window is rectangular, and its size information consists of -the height (the number of lines) and the width (the number of character -positions in each line). The mode line is included in the height. But -the width does not count the scroll bar or the column of @samp{|} -characters that separates side-by-side windows. - - The following three functions return size information about a window: - -@defun window-height &optional window -This function returns the number of lines in @var{window} (by default -the selected window), including any mode line and header line. -The result is almost always less than the value of @code{frame-height} -for the associated frame, because the latter also includes any echo -area. Depending on the toolkit in use, the frame height can also -include the menu bar and tool bar (@pxref{Size and Position}). -Therefore in general it is not straightforward to compare window and -frame heights (see @code{window-full-height-p} below). - -@example -@group -(window-height) - @result{} 23 -@end group -@group -(split-window-vertically) - @result{} #<window 4 on windows.texi> -@end group -@group -(window-height) - @result{} 11 -@end group -@end example -@end defun - -@defun window-body-height &optional window -Like @code{window-height} but the value does not include the -mode line (if any) or the header line (if any). -@end defun - -@defun window-full-height-p &optional window -This function returns non-@code{nil} if @var{window} is as tall as the -frame that contains it. The default for @var{window} is the selected -window. -@end defun - -@defun window-width &optional window -This function returns the number of columns in @var{window}. The -default for @var{window} is the selected window. - -The return value does not include the window's scroll bar or the column -of @samp{|} characters that separates side-by-side windows. Moreover, -the return value does not include the space used for displaying fringes -and margins. Hence you cannot, in general, compare the return values of -@code{window-width} and @code{frame-width} for equality to determine -whether a window is a wide as the containing frame. Use the function -@code{window-full-width-p}, see below, instead. - -@example -@group -(window-width) - @result{} 80 -@end group -@end example -@end defun - -@defun window-full-width-p &optional window -This function returns non-@code{nil} if @var{window} is as wide as the -frame that contains it; otherwise @code{nil}. The default for -@var{window} is the selected window. -@end defun - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -The default for @var{window} is the selected window. - -The order of the list is @code{(@var{left} @var{top} @var{right} -@var{bottom})}, all elements relative to 0, 0 at the top left corner of -the frame. The element @var{right} of the value is one more than the -rightmost column used by @var{window}, and @var{bottom} is one more than -the bottommost row used by @var{window} and its mode-line. - -The edges include the space used by the window's scroll bar, display -margins, fringes, header line, and mode line, if it has them. Also, -if the window has a neighbor on the right, its right edge value -includes the width of the separator line between the window and that -neighbor. Since the width of the window does not include this -separator, the width does not usually equal the difference between the -right and left edges. -@end defun - -@defun window-inside-edges &optional window -This is similar to @code{window-edges}, but the edge values -it returns include only the text area of the window. They -do not include the header line, mode line, scroll bar or -vertical separator, fringes, or display margins. -@end defun - -Here are the results obtained on a typical 24-line terminal with just -one window, with menu bar enabled: - -@example -@group -(window-edges (selected-window)) - @result{} (0 1 80 23) -@end group -@group -(window-inside-edges (selected-window)) - @result{} (0 1 80 22) -@end group -@end example - -@noindent -The bottom edge is at line 23 because the last line is the echo area. -The bottom inside edge is at line 22, which is the window's mode line. - -If @var{window} is at the upper left corner of its frame, and there is -no menu bar, then @var{bottom} returned by @code{window-edges} is the -same as the value of @code{(window-height)}, @var{right} is almost the -same as the value of @code{(window-width)}, and @var{top} and -@var{left} are zero. For example, the edges of the following window -are @w{@samp{0 0 8 5}}. Assuming that the frame has more than 8 -columns, the last column of the window (column 7) holds a border -rather than text. The last row (row 4) holds the mode line, shown -here with @samp{xxxxxxxxx}. - -@example -@group - 0 - _______ - 0 | | - | | - | | - | | - xxxxxxxxx 4 - - 7 -@end group -@end example - -In the following example, let's suppose that the frame is 7 -columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} -and the edges of the right window are @w{@samp{4 0 7 3}}. -The inside edges of the left window are @w{@samp{0 0 3 2}}, -and the inside edges of the right window are @w{@samp{4 0 7 2}}, - -@example -@group - ___ ___ - | | | - | | | - xxxxxxxxx - - 0 34 7 -@end group -@end example - -@defun window-pixel-edges &optional window -This function is like @code{window-edges} except that, on a graphical -display, the edge values are measured in pixels instead of in -character lines and columns. -@end defun - -@defun window-inside-pixel-edges &optional window -This function is like @code{window-inside-edges} except that, on a -graphical display, the edge values are measured in pixels instead of -in character lines and columns. -@end defun - -@node Resizing Windows -@section Changing the Size of a Window -@cindex window resizing -@cindex resize window -@cindex changing window size -@cindex window size, changing - - The window size functions fall into two classes: high-level commands -that change the size of windows and low-level functions that access -window size. Emacs does not permit overlapping windows or gaps between -windows, so resizing a window always affects at least one other window. - -@deffn Command enlarge-window size &optional horizontal -This function makes the selected window @var{size} lines taller by -stealing lines from windows above or below. In a first round, it takes -lines from one window at a time until that window is -@code{window-min-height} lines tall, then takes from another. If, at -the end of the first round, the selected window is still not tall -enough, @code{enlarge-window} starts a second round, where it deletes -windows above or below the selected one. - -If @var{horizontal} is non-@code{nil}, this function makes the window -@var{size} columns wider, stealing columns instead of lines. If a -window from which columns are stolen shrinks below -@code{window-min-width} columns, that window disappears. - -If the requested size would exceed that of the window's frame, then the -function makes the window occupy the entire height (or width) of the -frame. - -If there are various other windows from which lines or columns can be -stolen, and some of them specify fixed size (using -@code{window-size-fixed}, see below), they are left untouched while -other windows are ``robbed.'' If it would be necessary to alter the -size of a fixed-size window, @code{enlarge-window} gets an error -instead. - -If @var{size} is negative, this function shrinks the selected window by -@minus{}@var{size} lines or columns. If that makes the window smaller -than the minimum size (@code{window-min-height} and -@code{window-min-width}), then @code{enlarge-window} deletes the window. - -@code{enlarge-window} returns @code{nil}. -@end deffn - -@deffn Command enlarge-window-horizontally columns -This function makes the selected window @var{columns} wider. -It could be defined as follows: - -@example -@group -(defun enlarge-window-horizontally (columns) - (interactive "p") - (enlarge-window columns t)) -@end group -@end example -@end deffn - -@deffn Command shrink-window size &optional horizontal -This function is like @code{enlarge-window} but negates the argument -@var{size}, making the selected window smaller by giving lines (or -columns) to the other windows. If the window shrinks below -@code{window-min-height} or @code{window-min-width}, then it disappears. - -If @var{size} is negative, the window is enlarged by @minus{}@var{size} -lines or columns. -@end deffn - -@deffn Command shrink-window-horizontally columns -This function makes the selected window @var{columns} narrower. -It could be defined as follows: - -@example -@group -(defun shrink-window-horizontally (columns) - (interactive "p") - (shrink-window columns t)) -@end group -@end example -@end deffn - -@defun adjust-window-trailing-edge window delta horizontal -This function makes the selected window @var{delta} lines taller or -@var{delta} columns wider, by moving the bottom or right edge. This -function does not delete other windows; if it cannot make the -requested size adjustment, it signals an error. On success, this -function returns @code{nil}. -@end defun - -@deffn Command fit-window-to-buffer &optional window max-height min-height -This command makes @var{window} the right height to display its -contents exactly. The default for @var{window} is the selected window. - -The optional argument @var{max-height} specifies the maximum height the -window is allowed to be; @code{nil} means use the maximum permissible -height of a window on @var{window}'s frame. The optional argument -@var{min-height} specifies the minimum height for the window; @code{nil} -means use @code{window-min-height}. All these height values include the -mode line and/or header line. - -This function can delete windows when their height shrinks below -@var{min-height}. It returns non-@code{nil} if it orderly resized -@var{window}, and @code{nil} otherwise. -@end deffn - -@deffn Command shrink-window-if-larger-than-buffer &optional window -This command shrinks @var{window} vertically to be as small as possible -while still showing the full contents of its buffer---but not less than -@code{window-min-height} lines. The default for @var{window} is -the selected window. - -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-@code{nil} if it actually shrank the window -and @code{nil} otherwise. -@end deffn - -@cindex fixed-size window -@defvar window-size-fixed -If this variable is non-@code{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 @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -This variable automatically becomes buffer-local when set. - -Explicit size-change functions such as @code{enlarge-window} -get an error if they would have to change a window size which is fixed. -Therefore, when you want to change the size of such a window, -you should bind @code{window-size-fixed} to @code{nil}, like this: - -@example -(let ((window-size-fixed nil)) - (enlarge-window 10)) -@end example - -Deleting an adjacent window or changing the frame size may change the -size of a fixed-size window, if there is no other alternative. -@end defvar - -@cindex minimum window size - The following two variables constrain the window-structure-changing -functions to a minimum height and width. - -@defopt window-min-height -The value of this variable specifies how short a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-height} automatically deletes it, and no window may be -created shorter than this. The value is measured in line units. When -the window wants a mode line and/or a header line, they are counted as -one line each. The default value is @code{4}. A value less than -@code{1} is ignored. -@end defopt - -@defopt window-min-width -The value of this variable specifies how narrow a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-width} automatically deletes it, and no window may be -created narrower than this. The value is measured in characters and -includes any fringes or the scroll bar. The default value is @code{10}. -A value less than @code{2} is ignored. -@end defopt - -@cindex balancing window sizes -Emacs provides two functions to balance windows, that is, to even out -the sizes of windows on the same frame. The minibuffer window and -fixed-size windows are not resized by these functions. - -@deffn 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 @var{window-or-frame} -specifies a frame, it balances all windows on that frame. If -@var{window-or-frame} specifies a window, it balances this window and -its ``siblings'' only. Think of a sibling as the other (original or -new) window with respect to the present one, involved in the process of -splitting; see @ref{Splitting Windows}. Since a sibling may have been -split again, a window can have more than one sibling. -@end deffn - -@deffn 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. -@end deffn @node Coordinates and Windows @section Coordinates and Windows @@ -2357,31 +3445,6 @@ The function @code{coordinates-in-window-p} does not require a frame as argument because it always uses the frame that @var{window} is on. @end defun -@node Window Tree -@section The Window Tree -@cindex window tree - - A @dfn{window tree} specifies the layout, size, and relationship -between all windows in one frame. - -@defun window-tree &optional frame -This function returns the window tree for frame @var{frame}. -If @var{frame} is omitted, the selected frame is used. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's -root window, and @var{mini} is the frame's minibuffer window. - -If the root window is not split, @var{root} is the root window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, -and @code{t} for a vertical split, @var{edges} gives the combined size and -position of the subwindows in the split, and the rest of the elements -are the subwindows in the split. Each of the subwindows may again be -a window or a list representing a window split, and so on. The -@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} -similar to the value returned by @code{window-edges}. -@end defun @node Window Configurations @section Window Configurations |