X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/0c5413c811be1341e4f8fd0d35d5e4b8b5e103dc..2cffd68198c4d574f073ab238dc12b1221005eab:/doc/lispref/windows.texi diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index b33748993b..52ac5a5390 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,40 +1,43 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, -@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/windows @node Windows, Frames, Buffers, Top @chapter Windows - This chapter describes most of the functions and variables related to -Emacs windows. @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. * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-level functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Dedicated Windows:: How to avoid displaying another buffer in +* Switching Buffers:: Higher-level functions for switching to a buffer. +* Choosing Window:: How to choose a window for displaying a buffer. +* Display Action Functions:: Subroutines for @code{display-buffer}. +* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Window History:: Each window remembers the buffers displayed in it. +* Dedicated Windows:: How to avoid displaying another buffer in a specific window. +* Quitting Windows:: How to restore the state prior to displaying a + buffer. * 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, @@ -42,189 +45,1087 @@ 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} is a area of the screen which is used to display a +buffer (@pxref{Buffers}). In Emacs Lisp, windows are represented by a +special Lisp object type. @cindex multiple windows - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. - - The meaning of ``window'' in Emacs is similar to what it means in the -context of general-purpose window systems such as X, but not identical. -The X Window System places X windows on the screen; Emacs uses one or -more X windows as frames, and subdivides them into -Emacs windows. When you use Emacs on a character-only terminal, Emacs -treats the whole terminal screen as one frame. + Windows are grouped into frames (@pxref{Frames}). Each frame +contains at least one window; the user can subdivide it into multiple, +non-overlapping windows to view several buffers at once. Lisp +programs can use multiple windows for a variety of purposes. In +Rmail, for example, you can view a summary of message titles in one +window, and the contents of the selected message in another window. @cindex terminal screen @cindex screen of terminal + Emacs uses the word ``window'' with a different meaning than in +graphical desktop environments and window systems, such as the X +Window System. When Emacs is run on X, each of its graphical X +windows is an Emacs frame (containing one or more Emacs windows). +When Emacs is run on a text-only terminal, the frame fills the entire +terminal screen. + @cindex tiled windows - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are @dfn{tiled}; they never overlap, and -together they fill the whole screen or frame. Because of the way in -which Emacs creates new windows (@pxref{Splitting Windows}) and resizes -them (@pxref{Resizing Windows}), not all conceivable tilings of windows -on an Emacs frame are actually possible. + Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap +within the area of the frame. When a window is created, resized, or +deleted, the change in window space is taken from or given to the +adjacent windows, so that the total area of the frame is unchanged. + +@cindex live windows +@cindex internal windows + A @dfn{live window} is one that is actually displaying a buffer in a +frame. Such a window can be @dfn{deleted}, i.e. removed from the +frame (@pxref{Deleting Windows}); then it is no longer live, but the +Lisp object representing it might be still referenced from other Lisp +objects. A deleted window may be brought back to life by restoring a +saved window configuration (@pxref{Window Configurations}). @defun windowp object -This function returns @code{t} if @var{object} is a window. +This function returns @code{t} if @var{object} is a window (whether or +not it is live). Otherwise, it returns @code{nil}. +@end defun + +@defun window-live-p object +This function returns @code{t} if @var{object} is a live window and +@code{nil} otherwise. A live window is one that displays a buffer. +@end defun + + The windows in each frame are organized into a @dfn{window tree}. +@xref{Windows and Frames}. The leaf nodes of each window tree are +live windows---the ones actually displaying buffers. The internal +nodes of the window tree are internal windows, which are not live. +You can distinguish internal windows from deleted windows with +@code{window-valid-p}. + +@defun window-valid-p object +This function returns @code{t} if @var{object} is a live window, or an +internal window in a window tree. Otherwise, it returns @code{nil}, +including for the case where @var{object} is a deleted window. +@end defun + +@cindex selected window + In each frame, at any time, exactly one Emacs window is designated +as @dfn{selected within the frame}. For the selected frame, that +window is called the @dfn{selected window}---the one in which most +editing takes place, and in which the cursor for selected windows +appears (@pxref{Cursor Parameters}). The selected window's buffer is +usually also the current buffer, except when @code{set-buffer} has +been used (@pxref{Current Buffer}). As for non-selected frames, the +window selected within the frame becomes the selected window if the +frame is ever selected. @xref{Selecting Windows}. + +@defun selected-window +This function returns the selected window (which is always a live +window). +@end defun + +@node Windows and Frames +@section Windows and Frames + +Each window belongs to exactly one frame (@pxref{Frames}). + +@defun window-frame window +This function returns the frame that the window @var{window} belongs +to. If @var{window} is @code{nil}, it defaults to the selected +window. +@end defun + +@defun window-list &optional frame minibuffer window +This function returns a list of live windows belonging to the frame +@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to +the selected frame. + +The optional argument @var{minibuffer} specifies whether to include +the minibuffer window in the returned list. If @var{minibuffer} is +@code{t}, the minibuffer window is included. If @var{minibuffer} is +@code{nil} or omitted, the minibuffer window is included only if it is +active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the +minibuffer window is never included. + +The optional argument @var{window}, if non-@code{nil}, should be a +live window on the specified frame; then @var{window} will be the +first element in the returned list. If @var{window} is omitted or +@code{nil}, the window selected within the frame is first element. +@end defun + +@cindex window tree +@cindex root window + Windows in the same frame are organized into a @dfn{window tree}, +whose leaf nodes are the live windows. The internal nodes of a window +tree are not live; they exist for the purpose of organizing the +relationships between live windows. The root node of a window tree is +called the @dfn{root window}. It can be either a live window (if the +frame has just one window), or an internal window. + + A minibuffer window (@pxref{Minibuffer Windows}) is not part of its +frame's window tree unless the frame is a minibuffer-only frame. +Nonetheless, most of the functions in this section accept the +minibuffer window as an argument. Also, the function +@code{window-tree} described at the end of this section lists the +minibuffer window alongside the actual window tree. + +@defun frame-root-window &optional frame-or-window +This function returns the root window for @var{frame-or-window}. The +argument @var{frame-or-window} should be either a window or a frame; +if omitted or @code{nil}, it defaults to the selected frame. If +@var{frame-or-window} is a window, the return value is the root window +of that window's frame. +@end defun + +@cindex parent window +@cindex child window +@cindex sibling window + When a window is split, there are two live windows where previously +there was one. One of these is represented by the same Lisp window +object as the original window, and the other is represented by a +newly-created Lisp window object. Both of these live windows become +leaf nodes of the window tree, as @dfn{child windows} of a single +internal window. If necessary, Emacs automatically creates this +internal window, which is also called the @dfn{parent window}, and +assigns it to the appropriate position in the window tree. A set of +windows that share the same parent are called @dfn{siblings}. + +@cindex parent window +@defun window-parent &optional window +This function returns the parent window of @var{window}. If +@var{window} is omitted or @code{nil}, it defaults to the selected +window. The return value is @code{nil} if @var{window} has no parent +(i.e. it is a minibuffer window or the root window of its frame). +@end defun + + Each internal window always has at least two child windows. If this +number falls to one as a result of window deletion, Emacs +automatically deletes the internal window, and its sole remaining +child window takes its place in the window tree. + + Each child window can be either a live window, or an internal window +(which in turn would have its own child windows). Therefore, each +internal window can be thought of as occupying a certain rectangular +@dfn{screen area}---the union of the areas occupied by the live +windows that are ultimately descended from it. + +@cindex window combination +@cindex vertical combination +@cindex horizontal combination + For each internal window, the screen areas of the immediate children +are arranged either vertically or horizontally (never both). If the +child windows are arranged one above the other, they are said to form +a @dfn{vertical combination}; if they are arranged side by side, they +are said to form a @dfn{horizontal combination}. Consider the +following example: + +@smallexample +@group + ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ||| + || ||| ||| + || ||| ||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| + +@end group +@end smallexample + +@noindent +The root window of this frame is an internal window, @code{W1}. Its +child windows form a horizontal combination, consisting of the live +window @code{W2} and the internal window @code{W3}. The child windows +of @code{W3} form a vertical combination, consisting of the live +windows @code{W4} and @code{W5}. Hence, the live windows in this +window tree are @code{W2} @code{W4}, and @code{W5}. + + The following functions can be used to retrieve a child window of an +internal window, and the siblings of a child window. + +@defun window-top-child window +This function returns the topmost child window of @var{window}, if +@var{window} is an internal window whose children form a vertical +combination. For any other type of window, the return value is +@code{nil}. +@end defun + +@defun window-left-child window +This function returns the leftmost child window of @var{window}, if +@var{window} is an internal window whose children form a horizontal +combination. For any other type of window, the return value is +@code{nil}. +@end defun + +@defun window-child window +This function returns the first child window of the internal window +@var{window}---the topmost child window for a vertical combination, or +the leftmost child window for a horizontal combination. If +@var{window} is a live window, the return value is @code{nil}. +@end defun + +@defun window-combined-p &optional window horizontal +This function returns a non-@code{nil} value if and only if +@var{window} is part of a vertical combination. If @var{window} is +omitted or @code{nil}, it defaults to the selected one. + +If the optional argument @var{horizontal} is non-@code{nil}, this +means to return non-@code{nil} if and only if @var{window} is part of +a horizontal combination. +@end defun + +@defun window-next-sibling &optional window +This function returns the next sibling of the window @var{window}. If +omitted or @code{nil}, @var{window} defaults to the selected window. +The return value is @code{nil} if @var{window} is the last child of +its parent. +@end defun + +@defun window-prev-sibling &optional window +This function returns the previous sibling of the window @var{window}. +If omitted or @code{nil}, @var{window} defaults to the selected +window. The return value is @code{nil} if @var{window} is the first +child of its parent. +@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 +(@pxref{Cyclic Window Ordering}). + + You can use the following functions to find the first live window on +a frame, and to retrieve the entire window tree of a frame: + +@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 + +@defun window-tree &optional frame +This function returns a list representing the window tree for frame +@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to +the selected frame. + +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} is that 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 +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 window object +(for a live window) or a list with the same format as above (for an +internal window). 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} (@pxref{Coordinates and Windows}). +@end defun + +@node Window Sizes +@section Window Sizes +@cindex window size +@cindex size of window + + The following schematic shows the structure of a live window: + +@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 text area of a window +@cindex body of a window + At the center of the window is the @dfn{text area}, or @dfn{body}, +where the buffer text is displayed. On each side of the text area is +a series of vertical areas; from innermost to outermost, these are the +left and right margins, denoted by LM and RM in the schematic +(@pxref{Display Margins}); the left and right fringes, denoted by LF +and RF (@pxref{Fringes}); and the left or right scroll bar, only one of +which is present at any time, denoted by LS and RS (@pxref{Scroll +Bars}). At the top of the window is an optional header line +(@pxref{Header Lines}), and at the bottom of the window is the mode +line (@pxref{Mode Line Format}). + + Emacs provides several functions for finding the height and width of +a window. Most of these functions report the values as integer +multiples of the default character height and width. On a graphical +display, the actual screen size of this default height and width are +those specified by the frame's default font. Hence, if the buffer +contains text that is displayed in a different size, the reported +height and width of the window may differ from the actual number of +text lines or columns displayed in it. + +@cindex window height +@cindex height of a window +@cindex total height of a window +@cindex window width +@cindex width of a window +@cindex total width of a window + The @dfn{total height} of a window is the distance between the top +and bottom of the window, including the header line (if one exists) +and the mode line. The @dfn{total width} of a window is the distance +between the left and right edges of the mode line. Note that the +height of a frame is not the same as the height of its windows, since +a frame may also contain an echo area, menu bar, and tool bar +(@pxref{Size and Position}). + +@defun window-total-height &optional window +This function returns the total height, in lines, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window. If @var{window} is an internal window, the +return value is the total height occupied by its descendant windows. +@end defun + +@defun window-total-width &optional window +This function returns the total width, in columns, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window. If @var{window} is internal, the return value +is the total width occupied by its descendant windows. +@end defun + +@defun window-total-size &optional window horizontal +This function returns either the total height or width of the window +@var{window}. If @var{horizontal} is omitted or @code{nil}, this is +equivalent to calling @code{window-total-height} for @var{window}; +otherwise it is equivalent to calling @code{window-total-width} for +@var{window}. +@end defun + +@cindex full-width window +@cindex full-height window + The following functions can be used to determine whether a given +window has any adjacent windows. + +@defun window-full-height-p &optional window +This function returns non-@code{nil} if @var{window} has no other +window above or below it in its frame, i.e. its total height equals +the total height of the root window on that frame. If @var{window} is +omitted or @code{nil}, it defaults to the selected window. +@end defun + +@defun window-full-width-p &optional window +This function returns non-@code{nil} if @var{window} has no other +window to the left or right in its frame, i.e. its total width equals +that of the root window on that frame. If @var{window} is omitted or +@code{nil}, it defaults to the selected window. +@end defun + +@cindex window position + The following functions can be used to determine the position of a +window relative to the window area of its frame: + +@defun window-top-line &optional window +This function returns the distance, in lines, between the top of +@var{window} and the top of the frame's window area. For instance, +the return value is 0 if there is no window above @var{window}. If +@var{window} is omitted or @code{nil}, it defaults to the selected +window. +@end defun + +@defun window-left-column &optional window +This function returns the distance, in columns, between the left edge +of @var{window} and the left edge of the frame's window area. For +instance, the return value is 0 if there is no window to the left of +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window. +@end defun + +@cindex window body height +@cindex body height of a window +@cindex window body width +@cindex body width of a window +@cindex body size of a window +@cindex window body size + The @dfn{body height} of a window is the height of its text area, +which does not include the mode or header line. Similarly, the +@dfn{body width} is the width of the text area, which does not include +the scroll bar, fringes, or margins. + +@defun window-body-height &optional window +This function returns the body height, in lines, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window; otherwise it must be a live window. + +If there is a partially-visible line at the bottom of the text area, +that counts as a whole line; to exclude such a partially-visible line, +use @code{window-text-height}, below. +@end defun + +@defun window-body-width &optional window +This function returns the body width, in columns, of the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window; otherwise it must be a live window. +@end defun + +@defun window-body-size &optional window horizontal +This function returns the body height or body width of @var{window}. +If @var{horizontal} is omitted or @code{nil}, it is equivalent to +calling @code{window-body-height} for @var{window}; otherwise it is +equivalent to calling @code{window-body-width}. +@end defun + +@defun window-text-height &optional window +This function is like @code{window-body-height}, except that any +partially-visible line at the bottom of the text area is not counted. +@end defun + + For compatibility with previous versions of Emacs, +@code{window-height} is an alias for @code{window-body-height}, and +@code{window-width} is an alias for @code{window-body-width}. These +aliases are considered obsolete and will be removed in the future. + +@cindex fixed-size window + Commands that change the size of windows (@pxref{Resizing Windows}), +or split them (@pxref{Splitting Windows}), obey the variables +@code{window-min-height} and @code{window-min-width}, which specify +the smallest allowable window height and width. @xref{Change +Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs +Manual}. They also obey the variable @code{window-size-fixed}, with +which a window can be @dfn{fixed} in size: + +@defvar window-size-fixed +If this buffer-local variable is non-@code{nil}, the size of any +window displaying the buffer cannot normally be changed. Deleting a +window or changing the frame's size may still change its size, if +there is no 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. +@end defvar + +@defun window-size-fixed-p &optional window horizontal +This function returns a non-@code{nil} value if @var{window}'s height +is fixed. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. If the optional argument @var{horizontal} is +non-@code{nil}, the return value is non-@code{nil} if @var{window}'s +width is fixed. + +A @code{nil} return value does not necessarily mean that @var{window} +can be resized in the desired direction. To determine that, use the +function @code{window-resizable}. @xref{Resizing Windows}. +@end defun + + +@node Resizing Windows +@section Resizing Windows +@cindex window resizing +@cindex resize window +@cindex changing window size +@cindex window size, changing + + This section describes functions for resizing a window without +changing the size of its frame. Because live windows do not overlap, +these functions are meaningful only on frames that contain two or more +windows: resizing a window also changes the size of a neighboring +window. If there is just one window on a frame, its size cannot be +changed except by resizing the frame (@pxref{Size and Position}). + + Except where noted, these functions also accept internal windows as +arguments. Resizing an internal window causes its child windows to be +resized to fit the same space. + +@defun window-resizable window delta &optional horizontal ignore +This function returns @var{delta} if the size of @var{window} can be +changed vertically by @var{delta} lines. If the optional argument +@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if +@var{window} can be resized horizontally by @var{delta} columns. It +does not actually change the window size. + +If @var{window} is @code{nil}, it defaults to the selected window. + +A positive value of @var{delta} means to check whether the window can be +enlarged by that number of lines or columns; a negative value of +@var{delta} means to check whether the window can be shrunk by that many +lines or columns. If @var{delta} is non-zero, a return value of 0 means +that the window cannot be resized. + +Normally, the variables @code{window-min-height} and +@code{window-min-width} specify the smallest allowable window size. +@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU +Emacs Manual}. However, if the optional argument @var{ignore} is +non-@code{nil}, this function ignores @code{window-min-height} and +@code{window-min-width}, as well as @code{window-size-fixed}. +Instead, it considers the minimum-height window to be one consisting +of a header (if any), a mode line, plus a text area one line tall; and +a minimum-width window as one consisting of fringes, margins, and +scroll bar (if any), plus a text area two columns wide. @end defun +@defun window-resize window delta &optional horizontal ignore +This function resizes @var{window} by @var{delta} increments. If +@var{horizontal} is @code{nil}, it changes the height by @var{delta} +lines; otherwise, it changes the width by @var{delta} columns. A +positive @var{delta} means to enlarge the window, and a negative +@var{delta} means to shrink it. + +If @var{window} is @code{nil}, it defaults to the selected window. If +the window cannot be resized as demanded, an error is signaled. + +The optional argument @var{ignore} has the same meaning as for the +function @code{window-resizable} above. + +The choice of which window edge this function alters depends on the +splitting and nesting status of the involved windows; in some cases, +it may alter both edges. @xref{Splitting Windows}. To resize by +moving only the bottom or right edge of a window, use the function +@code{adjust-window-trailing-edge}, below. +@end defun + +@c The commands enlarge-window, enlarge-window-horizontally, +@c shrink-window, and shrink-window-horizontally are documented in the +@c Emacs manual. They are not preferred for calling from Lisp. + + 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 +signaled. + +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 total 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 -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. - -The following example starts with one window on a screen that is 50 -lines high by 80 columns wide; then it splits the window. +This section describes functions for creating a new window by +@dfn{splitting} an existing one. + +@deffn Command split-window &optional window size side +This function creates a new live window next to the window +@var{window}. If @var{window} is omitted or @code{nil}, it defaults +to the selected window. That window is ``split'', and reduced in +size. The space is taken up by the new window, which is returned. + +The optional second argument @var{size} determines the sizes of the +@var{window} and/or the new window. If it is omitted or @code{nil}, +both windows are given equal sizes; if there is an odd line, it is +allocated to the new window. If @var{size} is a positive number, +@var{window} is given @var{size} lines (or columns, depending on the +value of @var{side}). If @var{size} is a negative number, the new +window is given @minus{}@var{size} lines (or columns). + +If @var{size} is @code{nil}, this function obeys the variables +@code{window-min-height} and @code{window-min-width}. @xref{Change +Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs +Manual}. Thus, it signals an error if splitting would result in +making a window smaller than those variables specify. However, a +non-@code{nil} value for @var{size} causes those variables to be +ignored; in that case, the smallest allowable window is considered to +be one that has space for a text area one line tall and/or two columns +wide. + +The optional third argument @var{side} determines the position of the +new window relative to @var{window}. If it is @code{nil} or +@code{below}, the new window is placed below @var{window}. If it is +@code{above}, the new window is placed above @var{window}. In both +these cases, @var{size} specifies a total window height, in lines. + +If @var{side} is @code{t} or @code{right}, the new window is placed on +the right of @var{window}. If @var{side} is @code{left}, the new +window is placed on the left of @var{window}. In both these cases, +@var{size} specifies a total window width, in columns. + +If @var{window} is a live window, the new window inherits various +properties from it, including margins and scroll bars. If +@var{window} is an internal window, the new window inherits the +properties of the window selected within @var{window}'s frame. + +If the variable @code{ignore-window-parameters} is non-@code{nil} +(@pxref{Window Parameters}), this function ignores window parameters. +Otherwise, it consults the @code{split-window} parameter of +@var{window}; if this 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}, in +lieu of the usual action of @code{split-window}. +@end deffn + + As an example, we show a combination of @code{split-window} calls +that yields the window configuration discussed in @ref{Windows and +Frames}. This example demonstrates splitting live windows as well as +splitting internal windows. We begin with a frame containing a single +window (a live root window), which we denote by @var{W4}. Calling +@code{(split-window W3)} yields this window configuration: @smallexample @group -(setq w (selected-window)) - @result{} # -(window-edges) ; @r{Edges in order:} - @result{} (0 0 80 50) ; @r{left--top--right--bottom} + ______________________________________ + | ____________________________________ | + || || + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + || || + || || + ||_________________W5_________________|| + |__________________W3__________________| + @end group +@end smallexample + +@noindent +The @code{split-window} call has created a new live window, denoted by +@var{W5}. It has also created a new internal window, denoted by +@var{W3}, which becomes the root window and the parent of both +@var{W4} and @var{W5}. + + Next, we call @code{(split-window W3 nil 'left)}, passing the +internal window @var{W3} as the argument. The result: +@smallexample @group -;; @r{Returns window created} -(setq w2 (split-window w 15)) - @result{} # + ______________________________________ + | ______ ____________________________ | + || || __________________________ || + || ||| ||| + || ||| ||| + || ||| ||| + || |||____________W4____________||| + || || __________________________ || + || ||| ||| + || ||| ||| + || |||____________W5____________||| + ||__W2__||_____________W3_____________ | + |__________________W1__________________| @end group +@end smallexample + +@noindent +A new live window, @var{W2}, is created to the left of @var{W3} (which +encompasses the vertical window combination of @var{W4} and @var{W5}). +A new internal window @var{W1} is also created, and becomes the new +root window. + + The following two options can be used to modify the operation of +@code{split-window}. + +@defopt window-splits +If this variable is @code{nil}, @code{split-window} can only split a +window (denoted by @var{window}) if @var{window}'s screen area is +large enough to accommodate both itself and the new window. This is +the default. + +If this variable is non-@code{nil}, @code{split-window} tries to +resize all windows that are part of the same combination as +@var{window}, in order to accommodate the new window. In particular, +this may allow @code{split-window} to succeed even if @var{window} is +a fixed-size window or too small to ordinarily split. + +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 -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window;} - ; @r{top is line 15} + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________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 -(window-edges w) - @result{} (0 0 80 15) ; @r{Top window} + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + ||_________________W4_________________|| + |__________________W1__________________| + @end group @end smallexample -The screen looks like this: +Splitting @code{W3} with @code{window-splits} non-@code{nil} instead +produces a configuration where all windows have approximately the same +height: @smallexample @group - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + | ____________________________________ | + || || + || || + ||_________________W4_________________|| + |__________________W1__________________| + @end group @end smallexample -Next, split the top window horizontally: +@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 child windows recombined with that window's siblings +when such a sibling's child window 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}, child windows of @var{window} may be +recombined with @var{window}'s siblings when a window gets deleted. A +return value of @code{nil} means that child windows 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 -(setq w3 (split-window w 35 t)) - @result{} # + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + ||_________________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 -(window-edges w3) - @result{} (35 0 80 15) ; @r{Left edge at column 35} + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________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 -(window-edges w) - @result{} (0 0 35 15) ; @r{Right edge at column 35} + ______________________________________ + | ____________________________________ | + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + || || + || || + ||_________________W4_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + |__________________W1__________________| + @end group +@end smallexample + +Deleting window @code{W4}, will return its space to @code{W2} as +follows: +@smallexample @group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window unchanged} + ______________________________________ + | ____________________________________ | + || || + || || + || || + || || + || || + || || + || || + ||_________________W2_________________|| + | ____________________________________ | + || || + ||_________________W3_________________|| + |__________________W1__________________| + @end group @end smallexample -@need 3000 -Now the screen looks like this: +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 - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 + ______________________________________ + | ____________________________________ | + || __________________________________ || + |||________________W2________________||| + || __________________________________ || + ||| ||| + ||| ||| + |||________________W4________________||| + ||_________________W5_________________|| + | ____________________________________ | + || || + || || + ||_________________W3_________________|| + |__________________W1__________________| + @end group @end smallexample -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 +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-vertically &optional size +@deffn Command split-window-below &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 @@ -233,76 +1134,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. +@code{split-window-below} behaves as described above. -If it is @code{nil}, then @code{split-window-vertically} adjusts point + If it is @code{nil}, then @code{split-window-below} adjusts point in each of the two windows to avoid scrolling. (This is useful on slow terminals.) It selects whichever window contains the screen line -that point was previously on. - -This variable affects the behavior of @code{split-window-vertically} -only. It has no effect on the other functions described here. +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-right &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 @@ -314,105 +1169,113 @@ 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 @var{window} +is the selected window on its frame, this function selects the most +recently selected live window on that frame instead. + +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. Upon exit, @var{window} will be the selected window +on its frame. + +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. +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{} # -@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 @@ -438,138 +1301,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. -@deffn next-window &optional window minibuf all-frames +@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}: @@ -588,13 +1418,13 @@ buffer @samp{windows.texi}: @result{} # @end group @end example -@end deffn +@end defun -@deffn previous-window &optional window minibuf all-frames +@defun previous-window &optional window minibuf all-frames This function returns the window preceding @var{window} in the cyclic ordering of windows. The other arguments specify which windows to -include in the cycle, as in @code{next-window}. -@end deffn +consider as in @code{next-window}. +@end defun @deffn Command other-window count &optional all-frames This function selects another window in the cyclic ordering of windows. @@ -609,30 +1439,104 @@ 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 ordering. + +@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 signaled. +@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 + +The following function allows to determine whether a specific window is +the only live 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 -@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. +@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 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. +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 @@ -641,48 +1545,47 @@ includes the minibuffer window. @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{switch-to-buffer} and @code{display-buffer} try to obey a number +of user customizations regulating which windows are supposed to +display which buffers. @xref{Switching Buffers}. When writing an +application, you should avoid using @code{set-window-buffer} unless +you are sure you need it. -@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 signaled 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 @@ -691,26 +1594,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{} # -@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: @@ -740,186 +1639,263 @@ 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 +@deffn Command replace-buffer-in-windows &optional buffer-or-name +This command replaces @var{buffer-or-name} with some other buffer, in +all windows displaying it. For each such window, it choose another +buffer using @code{switch-to-prev-buffer} (@pxref{Window History}). + +The argument @var{buffer-or-name} may be a buffer, or the name of an +existing buffer; it defaults to the current buffer. + +If a window displaying @var{buffer-or-name} is dedicated +(@pxref{Dedicated Windows}) and is not the only window on its frame, +that window is deleted. If that window is the only window on its frame +and there are other frames on the frame's terminal, that frame is dealt +with by the function specified by @code{frame-auto-hide-function} +(@pxref{Quitting Windows}). Otherwise, the buffer provided by the +function @code{switch-to-prev-buffer} (@pxref{Window History}) is +displayed in the window instead. +@end deffn + + +@node Switching Buffers +@section Switching to a Buffer in a Window +@cindex switching to a buffer +@cindex displaying a buffer + + This section describes high-level functions for switching to a +specified buffer in some window. + + Do @emph{not} use these functions to make a buffer temporarily +current just so a Lisp program can access or modify it. They have +side-effects, such as changing window histories (@pxref{Window +History}), which will surprise the user if used that way. If you want +to make a buffer current to modify it in Lisp, use +@code{with-current-buffer}, @code{save-current-buffer}, or +@code{set-buffer}. @xref{Current Buffer}. + +@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window +This function displays @var{buffer-or-name} in the selected window, +and makes it the current buffer. (In contrast, @code{set-buffer} +makes the buffer current but does not display it; @pxref{Current +Buffer}). It is often used interactively (as the binding of @kbd{C-x +b}), as well as in Lisp programs. The return value is the buffer +switched to. + +If @var{buffer-or-name} is @code{nil}, it defaults to the buffer +returned by @code{other-buffer} (@pxref{The Buffer List}). If +@var{buffer-or-name} is a string that is not the name of any existing +buffer, this function creates a new buffer with that name; the new +buffer's major mode is determined by the variable @code{major-mode} +(@pxref{Major Modes}). + +Normally the specified buffer is put at the front of the buffer +list---both the global buffer list and the selected frame's buffer +list (@pxref{The Buffer List}). However, this is not done if the +optional argument @var{norecord} is non-@code{nil}. + +If this function is unable to display the buffer in the selected +window---usually because the selected window is a minibuffer window or +is strongly dedicated to its buffer (@pxref{Dedicated Windows})---then +it normally tries to display the buffer in some other window, in the +manner of @code{pop-to-buffer} (see below). However, if the optional +argument @var{force-same-window} is non-@code{nil}, it signals an error +instead. +@end deffn + +The next two functions are similar to @code{switch-to-buffer}, except +for the described features. + +@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord +This function makes the buffer specified by @var{buffer-or-name} +current and displays it in some window other than the selected window. +It uses the function @code{pop-to-buffer} internally (see below). + +If the selected window already displays the specified buffer, it +continues to do so, but another window is nonetheless found to display +it as well. + +The @var{buffer-or-name} and @var{norecord} arguments have the same +meanings as in @code{switch-to-buffer}. +@end deffn + +@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord +This function makes the buffer specified by @var{buffer-or-name} +current and displays it, usually in a new frame. It uses the function +@code{pop-to-buffer} (see below). + +If the specified buffer is already displayed in another window, in any +frame on the current terminal, this switches to that window instead of +creating a new frame. However, the selected window is never used for +this. + +The @var{buffer-or-name} and @var{norecord} arguments have the same +meanings as in @code{switch-to-buffer}. +@end deffn + +The above commands use @code{pop-to-buffer}, which is the function +used by Lisp programs to flexibly display a buffer in some window and +select that window for editing: + +@defun pop-to-buffer buffer-or-name &optional action norecord +This function makes @var{buffer-or-name} the current buffer and +displays it in some window, preferably not the window previously +selected. It then selects the displaying window. If that window is +on a different graphical frame, that frame is given input focus if +possible (@pxref{Input Focus}). The return value is the buffer that +was switched to. + +This function uses @code{display-buffer} to display the buffer, so all +the variables affecting @code{display-buffer} will affect it as well. +@xref{Choosing Window}. + +If @var{buffer-or-name} is @code{nil}, it defaults to the buffer +returned by @code{other-buffer} (@pxref{The Buffer List}). If +@var{buffer-or-name} is a string that is not the name of any existing +buffer, this function creates a new buffer with that name; the new +buffer's major mode is determined by the variable @code{major-mode} +(@pxref{Major Modes}). + +If @var{action} is non-@code{nil}, it should be a display action to +pass to @code{display-buffer} (@pxref{Choosing Window}). +Alternatively, a non-@code{nil}, non-list value means to pop to a +window other than the selected one---even if the buffer is already +displayed in the selected window. + +Like @code{switch-to-buffer}, this function updates the buffer list +unless @var{norecord} is non-@code{nil}. +@end defun + +@node Choosing Window +@section Choosing a Window for Display + + The command @code{display-buffer} flexibly chooses a window for +display, and displays a specified buffer in that window. It can be +called interactively, via the key binding @kbd{C-x 4 C-o}. It is also +used as a subroutine by many functions and commands, including +@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching +Buffers}). + +@cindex display action +@cindex action function, for display-buffer +@cindex action alist, for display-buffer + This command performs several complex steps to find a window to +display in. These steps are described by means of @dfn{display +actions}, which have the form @code{(@var{function} . @var{alist})}. +Here, @var{function} is either a function or a list of functions, +which we refer to as @dfn{action functions}; @var{alist} is an +association list, which we refer to as @dfn{action alists}. + + An action function accepts two arguments: the buffer to display and +an action alist. It attempts to display the buffer in some window, +picking or creating a window according to its own criteria. If +successful, it returns the window; otherwise, it returns @code{nil}. +@xref{Display Action Functions}, for a list of predefined action +functions. + + @code{display-buffer} works by combining display actions from +several sources, and calling the action functions in turn, until one +of them manages to display the buffer and returns a non-@code{nil} +value. + +@deffn Command display-buffer buffer-or-name &optional action frame +This command makes @var{buffer-or-name} appear in some window, without +selecting the window or making the buffer current. The argument +@var{buffer-or-name} must be a buffer or the name of an existing +buffer. The return value is the window chosen to display the buffer. + +The optional argument @var{action}, if non-@code{nil}, should normally +be a display action (described above). @code{display-buffer} builds a +list of action functions and an action alist, by consolidating display +actions from the following sources (in order): + +@itemize +@item +The variable @code{display-buffer-overriding-action}. + +@item +The user option @code{display-buffer-alist}. -@node Displaying Buffers -@section Displaying Buffers in Windows -@cindex switching to a buffer -@cindex displaying a buffer +@item +The @var{action} argument. - In this section we describe convenient functions that choose a window -automatically and use it to display a specified buffer. These functions -can also split an existing window in certain circumstances. We also -describe variables that parameterize the heuristics used for choosing a -window. -@iftex -See the preceding section for -@end iftex -@ifnottex -@xref{Buffers and Windows}, for -@end ifnottex -low-level primitives that give you more precise control. All of these -functions work by calling @code{set-window-buffer}. - - Do not use the functions in this section in order to make a buffer -current so that a Lisp program can access or modify it; they are too -drastic for that purpose, since they change the display of buffers in -windows, which would be gratuitous and surprise the user. Instead, use -@code{set-buffer} and @code{save-current-buffer} (@pxref{Current -Buffer}), which designate buffers as current for programmed access -without affecting the display of buffers in windows. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord -This function makes @var{buffer-or-name} the current buffer, and also -displays the buffer in the selected window. This means that a human can -see the buffer and subsequent keyboard commands will apply to it. -Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} -the current buffer but does not display it in the selected window; -see @ref{Current Buffer}. - -If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a -buffer using @code{other-buffer}. If @var{buffer-or-name} is a string -that does not identify an existing buffer, then a new buffer by that -name is created. The major mode for the new buffer is set according to -the variable @code{major-mode}; see @ref{Auto Major Mode}. - -When the selected window is the minibuffer window or is strongly -dedicated to its buffer (@pxref{Dedicated Windows}), this function calls -@code{pop-to-buffer} (see below) to display the buffer in some other -window. +@item +The user option @code{display-buffer-base-action}. -Normally the specified buffer is put at the front of the buffer list -(both the selected frame's buffer list and the frame-independent buffer -list). This affects the operation of @code{other-buffer}. However, if -@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer -List}. +@item +The constant @code{display-buffer-fallback-action}. +@end itemize -The @code{switch-to-buffer} function is often used interactively, as -the binding of @kbd{C-x b}. It is also used frequently in programs. It -returns the buffer that it switched to. +@noindent +Each action function is called in turn, passing the buffer as the +first argument and the combined action alist as the second argument, +until one of the functions returns non-@code{nil}. + +The argument @var{action} can also have a non-@code{nil}, non-list +value. This has the special meaning that the buffer should be +displayed in a window other than the selected one, even if the +selected window is already displaying it. If called interactively +with a prefix argument, @var{action} is @code{t}. + +The optional argument @var{frame}, if non-@code{nil}, specifies which +frames to check when deciding whether the buffer is already displayed. +It is equivalent to adding an element @code{(reusable-frames +. @var{frame})} to the action alist of @var{action}. @xref{Display +Action Functions}. @end deffn -The next two functions are similar to @code{switch-to-buffer}, except -for the described features. - -@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord -This function makes the buffer specified by @var{buffer-or-name} current -and displays it in a window not currently selected, using the function -@code{pop-to-buffer} (see below). +@defvar display-buffer-overriding-action +The value of this variable should be a display action, which is +treated with the highest priority by @code{display-buffer}. The +default value is empty, i.e. @code{(nil . nil)}. +@end defvar -The currently selected window is absolutely never used to do the job. -If the selected window already displays @var{buffer-or-name}, then it -continues to do so, but another window is nonetheless found to display -it in as well. +@defopt display-buffer-alist +The value of this option is an alist mapping regular expressions to +display actions. If the name of the buffer passed to +@code{display-buffer} matches a regular expression in this alist, then +@code{display-buffer} uses the corresponding display action. +@end defopt -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end deffn +@defopt display-buffer-base-action +The value of this option should be a display action. This option can +be used to define a ``standard'' display action for calls to +@code{display-buffer}. +@end defopt -@deffn pop-to-buffer buffer-or-name &optional other-window norecord -This command makes @var{buffer-or-name} the current buffer and switches -to it in some window, preferably not the window previously selected. -The ``popped-to'' window becomes the selected window. Its frame is -given the X server's focus, if possible; see @ref{Input Focus}. The -return value is the buffer that was switched to. - -If @var{buffer-or-name} is @code{nil}, that means to choose some other -buffer, but you don't specify which. If @var{buffer-or-name} is a -string that does not name an existing buffer, a buffer by that name is -created. The major mode for the new buffer is set according to the -variable @code{major-mode}. @xref{Auto Major Mode}. - -If either of the variables @code{display-buffer-reuse-frames} or -@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a -window in any visible frame already displaying the buffer; if there is -one, it selects and returns that window. If no such window exists and -@code{pop-up-frames} is non-@code{nil}, it creates a new frame and -displays the buffer in it. Otherwise, @code{pop-to-buffer} operates -entirely within the selected frame. (If the selected frame has just a -minibuffer, @code{pop-to-buffer} operates within the most recently -selected frame that was not just a minibuffer.) - -If the variable @code{pop-up-windows} is non-@code{nil}, windows may be -split to create a new window that is different from the original window. -For details, see @ref{Choosing Window}. - -If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or -creates another window even if @var{buffer-or-name} is already visible -in the selected window. Thus @var{buffer-or-name} could end up -displayed in two windows. On the other hand, if @var{buffer-or-name} is -already displayed in the selected window and @var{other-window} is -@code{nil}, then the selected window is considered sufficient for -displaying @var{buffer-or-name}, so that nothing needs to be done. - -All the variables that affect @code{display-buffer} affect -@code{pop-to-buffer} as well. @xref{Choosing Window}. - -This function updates the buffer list just like @code{switch-to-buffer} -unless @var{norecord} is non-@code{nil}. -@end deffn +@defvr Constant display-buffer-fallback-action +This display action specifies the fallback behavior for +@code{display-buffer} if no other display actions are given. +@end defvr -@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{other-buffer} to choose the -other buffer. In the usual applications of this function, you -don't care which other buffer is used; you just want to make sure that -@var{buffer-or-name} is no longer displayed. +@node Display Action Functions +@section Action Functions for @code{display-buffer} -The argument @var{buffer-or-name} may be a buffer or the name of an -existing buffer and defaults to the current buffer. +The following basic action functions are defined in Emacs. Each of +these functions takes two arguments: @var{buffer}, the buffer to +display, and @var{alist}, an action alist. Each action function +returns the window if it succeeds, and @code{nil} if it fails. -If a window displaying @var{buffer-or-name} is dedicated -(@pxref{Dedicated Windows}), 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. +@defun display-buffer-same-window buffer alist +This function tries to display @var{buffer} in the selected window. +It fails if the selected window is a minibuffer window or is dedicated +to another buffer (@pxref{Dedicated Windows}). It also fails if +@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry. +@end defun -This function returns @code{nil}. -@end deffn +@defun display-buffer-reuse-window buffer alist +This function tries to ``display'' @var{buffer} by finding a window +that is already displaying it. -@node Choosing Window -@section Choosing a Window for Display +If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, +the selected window is not eligible for reuse. - This section describes the basic facility that chooses a window to -display a buffer in---@code{display-buffer}. Higher-level functions and -commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, use this -subroutine. Here we describe how to use @code{display-buffer} and how -to customize it. - -@deffn Command display-buffer buffer-or-name &optional not-this-window frame -This command makes @var{buffer-or-name} appear in some window, but it -does not select that window and does not make the buffer specified by -@var{buffer-or-name} current. The identity of the selected window is -unaltered by this function. The argument @var{buffer-or-name} must be a -buffer or the name of an existing buffer. - -@var{not-this-window} non-@code{nil} means to display the specified -buffer in a window other than the selected one, even if it is already -displayed in the selected window. This can cause the buffer to appear -in two windows at once. Otherwise, if @var{buffer-or-name} is already -being displayed in any window, that is good enough, so this function -does nothing. - -@code{display-buffer} returns the window chosen to display -@var{buffer-or-name}. - -If the optional argument @var{frame} is non-@code{nil}, it specifies -which frames to check when deciding whether the buffer is already -displayed. If the buffer is already displayed in some window on one of -these frames, @code{display-buffer} simply returns that window. Here -are the possible values of @var{frame}: +If @var{alist} contains a @code{reusable-frames} entry, its value +determines which frames to search for a reusable window: @itemize @bullet @item @@ -935,9 +1911,36 @@ are the possible values of @var{frame}: A frame means consider windows on that frame only. @end itemize -Precisely how @code{display-buffer} finds or creates a window depends on -the variables described below. -@end deffn +If @var{alist} contains no @code{reusable-frames} entry, this function +normally searches just the selected frame; however, if either the +variable @code{display-buffer-reuse-frames} or the variable +@code{pop-up-frames} is non-@code{nil}, it searches all frames on the +current terminal. @xref{Choosing Window Options}. +@end defun + +@defun display-buffer-pop-up-frame buffer alist +This function creates a new frame, and displays the buffer in that +frame's window. +@end defun + +@defun display-buffer-pop-up-window buffer alist +This function tries to display @var{buffer} by splitting the largest +or least recently-used window. It uses @code{split-window-sensibly} +as a subroutine (@pxref{Choosing Window Options}). +@end defun + +@defun display-buffer-use-some-window buffer alist +This function tries to display @var{buffer} by choosing an existing +window and displaying the buffer in that window. It can fail if all +windows are dedicated to another buffer (@pxref{Dedicated Windows}). +@end defun + +@node Choosing Window Options +@section Additional Options for Displaying Buffers + +The behavior of the standard display actions of @code{display-buffer} +(@pxref{Choosing Window}) can be modified by a variety of user +options. @defopt display-buffer-reuse-frames If this variable is non-@code{nil}, @code{display-buffer} searches @@ -1015,7 +2018,7 @@ a window only if the space taken up by that window can accommodate two windows one above the other that are both at least @code{window-min-height} lines tall. Moreover, if the window that shall be split has a mode line, @code{split-window-sensibly} does not split -the window unless the new window can accomodate a mode line too. +the window unless the new window can accommodate a mode line too. @end defopt @defopt split-width-threshold @@ -1201,6 +2204,101 @@ If all options described above fail to produce a suitable window, resort, it will try to display @var{buffer-or-name} on a separate frame. In that case, the value of @code{pop-up-frames} is disregarded. + +@node Window History +@section Window History +@cindex window history + +Each window remembers the buffers it has displayed earlier and the order +in which these buffers have been removed from it. This history is used, +for example, by @code{replace-buffer-in-windows} (@pxref{Buffers and +Windows}). This list is automatically maintained by Emacs, but you can +use the following functions to explicitly inspect or alter it: + +@defun window-prev-buffers &optional window +This function returns a list specifying the previous contents of +@var{window}, which should be a live window and defaults to the +selected window. + +Each list element has the form @code{(@var{buffer} @var{window-start} +@var{window-pos})}, where @var{buffer} is a buffer previously shown in +the window, @var{window-start} is the window start position when that +buffer was last shown, and @var{window-pos} is the point position when +that buffer was last shown. + +The list is ordered so that earlier elements correspond to more +recently-shown buffers, and the first element usually corresponds to the +buffer most recently removed from the window. +@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. The argument @var{prev-buffers} +should be a list of the same form as that returned by +@code{window-prev-buffers}. +@end defun + +In addition, each buffer maintains a list of @dfn{next buffers}, which +is a list of buffers re-shown by @code{switch-to-prev-buffer} (see +below). This list is mainly used by @code{switch-to-prev-buffer} and +@code{switch-to-next-buffer} for choosing buffers to switch to. + +@defun window-next-buffers &optional window +This function returns the list of buffers recently re-shown in +@var{window} via @code{switch-to-prev-buffer}. The @var{window} +argument must denote a live window or @code{nil} (meaning the selected +window). +@end defun + +@defun set-window-next-buffers window next-buffers +This function sets the next buffer list of @var{window} to +@var{next-buffers}. The @var{window} argument should be a live window +or @code{nil} (meaning the selected window). The argument +@var{next-buffers} should be a list of buffers. +@end defun + +The following commands can be used to cycle through the global buffer +list, much like @code{bury-buffer} and @code{unbury-buffer}. However, +they cycle according to the specified window's history list, rather +than the global buffer list. In addition, they restore +window-specific window start and point positions, and may show a +buffer even if it is already shown in another window. The +@code{switch-to-prev-buffer} command, in particular, is used by +@code{replace-buffer-in-windows}, @code{bury-buffer} and +@code{quit-window} to find a replacement buffer for a window. + +@deffn Command switch-to-prev-buffer &optional window bury-or-kill +This command displays the previous buffer in @var{window}. The +argument @var{window} should be a live window or @code{nil} (meaning +the selected window). 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 buffer list of the frame @var{window} appears on (@pxref{The +Buffer List}). +@end deffn + +@deffn Command switch-to-next-buffer &optional window +This command 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, this function tries to show a buffer from the buffer list +of the frame @var{window} appears on (@pxref{The Buffer List}). +@end deffn + + @node Dedicated Windows @section Dedicated Windows @cindex dedicated window @@ -1215,15 +2313,15 @@ non-@code{nil}. The behavior of @code{set-window-buffer} (@pxref{Buffers and Windows}) with respect to dedicated windows is slightly different, see below. -When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete -a dedicated window and that window is the only window on its frame, it -deletes the window's frame too, provided there are other frames left. -@code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to -delete all dedicated windows showing its buffer argument. When such a -window is the only window on its frame, that frame is deleted, provided -there are other frames left. If there are no more frames left, some -other buffer is displayed in the window, and the window is marked as -non-dedicated. +When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to +delete a dedicated window and that window is the only window on its +frame, it deletes the window's frame too, provided there are other +frames left. @code{replace-buffer-in-windows} (@pxref{Switching +Buffers}) tries to delete all dedicated windows showing its buffer +argument. When such a window is the only window on its frame, that +frame is deleted, provided there are other frames left. If there are +no more frames left, some other buffer is displayed in the window, and +the window is marked as non-dedicated. When you kill a buffer (@pxref{Killing Buffers}) displayed in a dedicated window, any such window usually gets deleted too, since @@ -1254,6 +2352,87 @@ display. Other functions do not treat @code{t} differently from any non-@code{nil} value. @end defun + +@node Quitting Windows +@section Quitting Windows + +When you want to get rid of a window used for displaying a buffer you +can call @code{delete-window} or @code{delete-windows-on} +(@pxref{Deleting Windows}) to remove that window from its frame. If the +buffer is shown on a separate frame, you might want to call +@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other +hand, a window has been reused for displaying the buffer, you might +prefer showing the buffer previously shown in that window by calling the +function @code{switch-to-prev-buffer} (@pxref{Window History}). +Finally, you might want to either bury (@pxref{The Buffer List}) or kill +(@pxref{Killing Buffers}) the window's buffer. + + The following function uses information on how the window for +displaying the buffer was obtained in the first place thus attempting to +automatize the above decisions for you. + +@deffn Command quit-window &optional kill window +This command quits @var{window} and buries its buffer. The argument +@var{window} must be a live window and defaults to the selected one. +With prefix argument @var{kill} non-@code{nil}, it kills the buffer +instead of burying it. + +Quitting @var{window} means to proceed as follows: If @var{window} was +created specially for displaying its current buffer, delete @var{window} +provided its frame contains at least one other live window. If +@var{window} is the only window on its frame and there are other frames +on the frame's terminal, the value of @var{kill} determines how to +proceed with the window. If @var{kill} is @code{nil}, the fate of the +frame is determined by calling @code{frame-auto-hide-function} (see +below) with that frame as sole argument. If @var{kill} is +non-@code{nil}, the frame is deleted unconditionally. + +If @var{window} was reused for displaying its buffer, this command tries +to display the buffer previously shown in it. It also tries to restore +the window start (@pxref{Window Start and End}) and point (@pxref{Window +Point}) positions of the previously shown buffer. If, in addition, the +current buffer was temporarily resized, this command will also try to +restore the original height of @var{window}. + +The three cases described so far require that the buffer shown in +@var{window} is still the buffer displayed by the last buffer display +function for this window. If another buffer has been shown in the +meantime or the buffer previously shown no longer exists, this command +calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show some +other buffer instead. +@end deffn + +The function @code{quit-window} bases its decisions on information +stored in @var{window}'s @code{quit-restore} window parameter +(@pxref{Window Parameters}) and resets that parameter to @code{nil} +after it's done. + +The following option specifies how to deal with a frame containing just +one window that shall be either quit or whose buffer shall be buried. + +@defopt frame-auto-hide-function +The function specified by this option is called to automatically hide +frames. This function is called with one argument - a frame. + +The function specified here is called by @code{bury-buffer} (@pxref{The +Buffer List}) when the selected window is dedicated and shows the buffer +that shall be buried. It is also called by @code{quit-window} (see +above) when the frame of the window that shall be quit has been +specially created for displaying that window's buffer and the buffer +shall be buried. + +The default is to call @code{iconify-frame} (@pxref{Visibility of +Frames}). Alternatively, you may either specify @code{delete-frame} +(@pxref{Deleting Frames}) to remove the frame from its display, +@code{ignore} to leave the frame unchanged, or any other function that +can take a frame as its sole argument. + +Note that the function specified by this option is called if and only if +there's at least one other frame on the terminal of the frame it's +supposed to handle and that frame contains only one live window. +@end defopt + + @node Window Point @section Windows and Point @cindex window position @@ -1463,10 +2642,10 @@ to the current position of point in @var{window}; @var{window}, to the selected window. If @var{position} is @code{t}, that means to check the last visible position in @var{window}. -The @code{pos-visible-in-window-p} function considers only vertical -scrolling. If @var{position} is out of view only because @var{window} -has been scrolled horizontally, @code{pos-visible-in-window-p} returns -non-@code{nil} anyway. @xref{Horizontal Scrolling}. +This function considers only vertical scrolling. If @var{position} is +out of view only because @var{window} has been scrolled horizontally, +@code{pos-visible-in-window-p} returns non-@code{nil} anyway. +@xref{Horizontal Scrolling}. If @var{position} is visible, @code{pos-visible-in-window-p} returns @code{t} if @var{partially} is @code{nil}; if @var{partially} is @@ -1522,67 +2701,77 @@ text line, @var{ypos} is negative. @cindex scrolling textually @dfn{Textual scrolling} means moving the text up or down through a -window. It works by changing the value of the window's display-start -location. It may also change the value of @code{window-point} to keep -point on the screen. - - Textual scrolling was formerly called ``vertical scrolling,'' but we -changed its name to distinguish it from the new vertical fractional -scrolling feature (@pxref{Vertical Scrolling}). - - In the commands @code{scroll-up} and @code{scroll-down}, the directions -``up'' and ``down'' refer to the motion of the text in the buffer at which -you are looking through the window. Imagine that the text is -written on a long roll of paper and that the scrolling commands move the -paper up and down. Thus, if you are looking at text in the middle of a -buffer and repeatedly call @code{scroll-down}, you will eventually see -the beginning of the buffer. +window. It works by changing the window's display-start location. It +may also change the value of @code{window-point} to keep point on the +screen (@pxref{Window Point}). + + The basic textual scrolling functions are @code{scroll-up} (which +scrolls forward) and @code{scroll-down} (which scrolls backward). In +these function names, ``up'' and ``down'' refer to the direction of +motion of the buffer text relative to the window. Imagine that the +text is written on a long roll of paper and that the scrolling +commands move the paper up and down. Thus, if you are looking at the +middle of a buffer and repeatedly call @code{scroll-down}, you will +eventually see the beginning of the buffer. Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -``down'' commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The textual scrolling functions (aside from -@code{scroll-other-window}) have unpredictable results if the current -buffer is different from the buffer that is displayed in the selected -window. @xref{Current Buffer}. - - If the window contains a row which is taller than the height of the -window (for example in the presence of a large image), the scroll -functions will adjust the window's vertical scroll position to scroll -the partially visible row. To disable this feature, Lisp code may bind -the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical -Scrolling}). +imagine the window moving over text that remains in place, so that +``down'' commands take you to the end of the buffer. This convention +is consistent with fact that such a command is bound to a key named +@key{PageDown} on modern keyboards. We have not switched to this +convention as that is likely to break existing Emacs Lisp code. + + Textual scrolling functions (aside from @code{scroll-other-window}) +have unpredictable results if the current buffer is not the one +displayed in the selected window. @xref{Current Buffer}. + + If the window contains a row taller than the height of the window +(for example in the presence of a large image), the scroll functions +will adjust the window's vertical scroll position to scroll the +partially visible row. Lisp callers can disable this feature by +binding the variable @code{auto-window-vscroll} to @code{nil} +(@pxref{Vertical Scrolling}). @deffn Command scroll-up &optional count -This function scrolls the text in the selected window upward -@var{count} lines. If @var{count} is negative, scrolling is actually -downward. +This function scrolls forward by @var{count} lines in the selected +window. -If @var{count} is @code{nil} (or omitted), then the length of scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). +If @var{count} is negative, it scrolls backward instead. If +@var{count} is @code{nil} (or omitted), the distance scrolled is +@code{next-screen-context-lines} lines less than the height of the +window's text area. -@code{scroll-up} returns @code{nil}, unless it gets an error -because it can't scroll any further. +If the selected window cannot be scrolled any further, this function +signals an error. Otherwise, it returns @code{nil}. @end deffn @deffn Command scroll-down &optional count -This function scrolls the text in the selected window downward -@var{count} lines. If @var{count} is negative, scrolling is actually -upward. +This function scrolls backward by @var{count} lines in the selected +window. + +If @var{count} is negative, it scrolls forward instead. If +@var{count} is omitted or @code{nil}, the distance scrolled is +@code{next-screen-context-lines} lines less than the height of the +window's text area. + +If the selected window cannot be scrolled any further, this function +signals an error. Otherwise, it returns @code{nil}. +@end deffn -If @var{count} is omitted or @code{nil}, then the length of the scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). +@deffn Command scroll-up-command &optional count +This behaves like @code{scroll-up}, except that if the selected window +cannot be scrolled any further and the value of the variable +@code{scroll-error-top-bottom} is @code{t}, it tries to move to the +end of the buffer instead. If point is already there, it signals an +error. +@end deffn -@code{scroll-down} returns @code{nil}, unless it gets an error because -it can't scroll any further. +@deffn Command scroll-down-command &optional count +This behaves like @code{scroll-down}, except that if the selected +window cannot be scrolled any further and the value of the variable +@code{scroll-error-top-bottom} is @code{t}, it tries to move to the +beginning of the buffer instead. If point is already there, it +signals an error. @end deffn @deffn Command scroll-other-window &optional count @@ -1612,7 +2801,6 @@ line reappears after the echo area momentarily displays the message @samp{Beginning of buffer}. @end deffn -@c Emacs 19 feature @defvar other-window-scroll-buffer If this variable is non-@code{nil}, it tells @code{scroll-other-window} which buffer's window to scroll. @@ -1661,19 +2849,24 @@ point should be placed from the bottom of the window; thus, as with @end defopt @defopt scroll-step -This variable is an older variant of @code{scroll-conservatively}. The -difference is that it if its value is @var{n}, that permits scrolling +This variable is an older variant of @code{scroll-conservatively}. +The difference is that if its value is @var{n}, that permits scrolling only by precisely @var{n} lines, not a smaller number. This feature does not work with @code{scroll-margin}. The default value is zero. @end defopt +@cindex @code{scroll-command} property @defopt scroll-preserve-screen-position -If this option is @code{t}, scrolling which would move the current -point position out of the window chooses the new position of point -so that the vertical position of the cursor is unchanged, if possible. +If this option is @code{t}, whenever a scrolling command moves point +off-window, Emacs tries to adjust point to keep the cursor at its old +vertical position in the window, rather than the window edge. -If it is non-@code{nil} and not @code{t}, then the scrolling functions -always preserve the vertical position of point, if possible. +If the value is non-@code{nil} and not @code{t}, Emacs adjusts point +to keep the cursor at the same vertical position, even if the +scrolling command didn't move point off-window. + +This option affects all scroll commands that have a non-@code{nil} +@code{scroll-command} symbol property. @end defopt @defopt next-screen-context-lines @@ -1684,13 +2877,23 @@ bottom of the window appear instead at the top. The default value is @code{2}. @end defopt +@defopt scroll-error-top-bottom +If this option is @code{nil} (the default), @code{scroll-up-command} +and @code{scroll-down-command} simply signal an error when no more +scrolling is possible. + +If the value is @code{t}, these commands instead move point to the +beginning or end of the buffer (depending on scrolling direction); +only if point is already on that position do they signal an error. +@end defopt + @deffn Command recenter &optional count @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does not ``move point'' with respect to the text. -If @var{count} is a nonnegative number, that puts the line containing +If @var{count} is a non-negative number, that puts the line containing point @var{count} lines down from the top of the window. If @var{count} is a negative number, then it counts upward from the bottom of the window, so that @minus{}1 stands for the last usable @@ -1932,370 +3135,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{} # -@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 @@ -2358,45 +3197,19 @@ The function @code{coordinates-in-window-p} does not require a frame as argument because it always uses the frame that @var{window} is on. @end defun -@node Window Tree -@section The Window Tree -@cindex window tree - - A @dfn{window tree} specifies the layout, size, and relationship -between all windows in one frame. - -@defun window-tree &optional frame -This function returns the window tree for frame @var{frame}. -If @var{frame} is omitted, the selected frame is used. - -The return value is a list of the form @code{(@var{root} @var{mini})}, -where @var{root} represents the window tree of the frame's -root window, and @var{mini} is the frame's minibuffer window. - -If the root window is not split, @var{root} is the root window itself. -Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1} -@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal split, -and @code{t} for a vertical split, @var{edges} gives the combined size and -position of the subwindows in the split, and the rest of the elements -are the subwindows in the split. Each of the subwindows may again be -a window or a list representing a window split, and so on. The -@var{edges} element is a list @code{(@var{left}@var{ top}@var{ right}@var{ bottom})} -similar to the value returned by @code{window-edges}. -@end defun @node Window Configurations @section Window Configurations @cindex window configurations @cindex saving window information - A @dfn{window configuration} records the entire layout of one +A @dfn{window configuration} records the entire layout of one frame---all windows, their sizes, which buffers they contain, how those buffers are scrolled, and their values of point and the mark; also their fringes, margins, and scroll bar settings. It also includes the value of @code{minibuffer-scroll-window}. As a special exception, the window configuration does not record the value of point in the selected window -for the current buffer. Also, the window configuration does not record -the values of window parameters; see @ref{Window Parameters}. +for the current buffer. You can bring back an entire frame layout by restoring a previously saved window configuration. If you want to record the layout of all @@ -2435,7 +3248,7 @@ as @code{save-window-excursion}: @group (let ((config (current-window-configuration))) (unwind-protect - (progn (split-window-vertically nil) + (progn (split-window-below nil) @dots{}) (set-window-configuration config))) @end group @@ -2506,24 +3319,62 @@ sense, but are not implemented because we did not need them. See the file @file{winner.el} for some more operations on windows configurations. + The objects returned by @code{current-window-configuration} die +together with the Emacs process. In order to store a window +configuration on disk and read it back in another Emacs session the +following two functions can be used. + +@defun window-state-get &optional window markers +This function returns the state of @var{window} as a Lisp object. The +argument @var{window} can be any window and defaults to the root window +of the selected frame. + +The optional argument @var{markers} non-@code{nil} means to use markers +for sampling positions like @code{window-point} or @code{window-start}. +This argument should be non-@code{nil} only if the value is used for +putting the state back in the same session since markers slow down +processing. +@end defun + +The value returned by @code{window-state-get} can be converted by using +one of the functions defined by Desktop Save Mode (@pxref{Desktop Save +Mode}) to an object that can be written to a file. Such objects can be +read back and converted to a Lisp object representing the state of the +window. That Lisp object can be used as argument for the following +function in order to restore the state window in another window. + +@defun window-state-put state &optional window ignore +This function puts the window state @var{state} into @var{window}. The +argument @var{state} should be the state of a window returned by an +earlier invocation of @code{window-state-get}, see above. The optional +argument @var{window} must specify a live window and defaults to the +selected one. + +The optional argument @var{ignore} non-@code{nil} means to ignore +minimum window sizes and fixed size restrictions. If @var{ignore} +equals @code{safe}, this means windows can get as small as one line +and/or two columns. +@end defun + + @node Window Parameters @section Window Parameters @cindex window parameters -This sections describes how window parameters can be used to associate +This section describes how window parameters can be used to associate additional information with windows. @defun window-parameter window parameter This function returns @var{window}'s value for @var{parameter}. The -default for @var{window} is the selected window. If @var{window} -has no setting for @var{parameter}, this function returns @code{nil}. +default for @var{window} is the selected window. If @var{window} has no +setting for @var{parameter}, this function returns @code{nil}. @end defun @defun window-parameters &optional window This function returns all parameters of @var{window} and their values. -The default for @var{window} is the selected window. The return value -is an association list of elements of the form @code{(@var{parameter} -. @var{value})}. +The default for @var{window} is the selected window. The return value, +if non-@code{nil} is an association list whose elements have the form +@code{(@var{parameter} . @var{value})}. @end defun @defun set-window-parameter window parameter value @@ -2532,13 +3383,56 @@ This function sets @var{window}'s value of @var{parameter} to is the selected window. @end defun -Currently, window parameters are not saved in window configurations and -consequently not restored by @code{set-window-configuration}. Hence, -any change of a parameter introduced via @code{set-window-parameter} can -be undone only by invoking @code{set-window-parameter} for the same -parameter again. Since @code{save-window-excursion} relies on window -configurations (@pxref{Window Configurations}), window parameters are -not saved and restored by that special form, either. +Some functions, notably @code{delete-window}, +@code{delete-other-windows} and @code{split-window} may behave specially +when their @var{window} argument has a parameter set. You can override +such special behavior by binding the following variable to a +non-@code{nil} value: + +@defvar ignore-window-parameters +If this variable is non-@code{nil}, some standard functions do not +process window parameters. The functions currently affected by this are +@code{split-window}, @code{delete-window}, @code{delete-other-windows} +and @code{other-window}. + +An application can bind this variable to a non-@code{nil} value around +calls to these functions. If it does so, the application is fully +responsible for correctly assigning the parameters of all involved +windows when exiting that function. +@end defvar + +The following parameters are currently used by the window management +code. + +@table @asis +@item @code{delete-window} +This parameter affects the execution of @code{delete-window} +(@pxref{Deleting Windows}). + +@item @code{delete-other-windows} +This parameter affects the execution of @code{delete-other-windows} +(@pxref{Deleting Windows}). + +@item @code{split-window} +This parameter affects the execution of @code{split-window} +(@pxref{Splitting Windows}). + +@item @code{other-window} +This parameter affects the execution of @code{other-window} +(@pxref{Cyclic Window Ordering}). + +@item @code{no-other-window} +This parameter marks the window as not selectable by @code{other-window} +(@pxref{Cyclic Window Ordering}). +@end table + +In addition, the parameters @code{window-atom} and @code{window-side} +are reserved and should not be used by applications. The +@code{quit-restore} parameter tells how to proceed with a window when +the buffer it shows is no more needed. This parameter is installed by +the buffer display functions (@pxref{Choosing Window}) and consulted by +the function @code{quit-window} (@pxref{Quitting Windows}). + @node Window Hooks @section Hooks for Window Scrolling and Changes @@ -2607,7 +3501,3 @@ frame selected. Lock fontification function, which will be called whenever parts of a buffer are (re)fontified because a window was scrolled or its size changed. @xref{Other Font Lock Variables}. - -@ignore - arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3 -@end ignore