@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/windows
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.
+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 the first element.
@end defun
@cindex window tree
line (@pxref{Mode Line Format}).
Emacs provides several functions for finding the height and width of
-a window. Except where noted, these heights and widths are reported
+a window. Except where noted, Emacs reports window heights and widths
as integer numbers of lines and columns respectively. On a graphical
display, each ``line'' and ``column'' actually corresponds to the
height and width of a ``default'' character specified by the frame's
@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
@end defun
For compatibility with previous versions of Emacs,
-@code{window-height} is an alias for @code{window-body-height}, and
+@code{window-height} is an alias for @code{window-total-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.
function @code{window-resizable}. @xref{Resizing Windows}.
@end defun
- The following functions can be used to find a window's size and
-position in pixels. Though mostly useful on graphical displays, they
-can also be called on text-only terminals, where the screen area of
-each text character is taken to be ``one pixel''.
-
-@defun window-pixel-edges &optional window
-This function return a list of pixel coordinates for the edges of
-@var{window}. If @var{window} is omitted or @code{nil}, it defaults
-to the selected window.
-
-The return value has the form @code{(@var{left} @var{top} @var{right}
-@var{bottom})}. The list elements are, respectively, the X coordinate
-of the left window edge, the Y coordinate of the top edge, one more
-than the X coordinate of the right edge, and one more than the Y
-coordinate of the bottom edge. The origin coordinate @samp{(0,0)} is
-taken to be the top left corner of the frame's window area.
-
-These edge values include the space used by the window's scroll bar,
-margins, fringes, header line, and mode line, if any.
-@end defun
-
-@defun window-inside-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates for the window's text area, rather than
-the edge coordinates for the window itself. @var{window} must specify
-a live window.
-@end defun
-
-@defun window-absolute-pixel-edges &optional window
-This function is like @code{window-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen.
-@end defun
-
-@defun window-inside-absolute-pixel-edges &optional window
-This function is like @code{window-inside-pixel-edges}, except that it
-returns the edge coordinates relative to the top left corner of the
-display screen. @var{window} must specify a live window.
-@end defun
+ @xref{Coordinates and Windows}, for more functions that report the
+positions of various parts of a window relative to the frame, from
+which you can calculate its size. In particular, you can use the
+functions @code{window-pixel-edges} and
+@code{window-inside-pixel-edges} to find the size in pixels, for
+graphical displays.
@node Resizing Windows
@section Resizing Windows
This example demonstrates splitting a live window as well as splitting
an internal window. 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:
+@code{(split-window W4)} yields this window configuration:
@smallexample
@group
@defopt window-combination-resize
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. Furthermore,
-subsequently resizing or deleting @var{window} may resize all other
-windows in its combination.
-
-This variable has no effect if @code{window-combination-limit} is
-non-@code{nil} (see below).
+window (denoted by @var{window}) if @var{window}'s screen area is large
+enough to accommodate both itself and the new window.
+
+If this variable is @code{t}, @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. Furthermore, subsequently
+resizing or deleting @var{window} may resize all other windows in its
+combination.
+
+The default is @code{nil}. Other values are reserved for future use.
+The value of this variable is ignored when
+@code{window-combination-limit} is non-@code{nil} (see below).
@end defopt
To illustrate the effect of @code{window-combination-resize},
@end smallexample
@noindent
-If @code{window-combination-resize} is non-@code{nil}, splitting
-@code{W3} instead leaves all three live windows with approximately the
-same height:
+If @code{window-combination-resize} is @code{t}, splitting @code{W3}
+instead leaves all three live windows with approximately the same
+height:
@smallexample
@group
internal window is created anyway). The default is @code{nil}. Other
values are reserved for future use.
-Thus, if the value is always @code{t}, each window tree is a binary
-tree: each window except the root window has exactly one sibling.
+Thus, if the value of this variable is at all times @code{t}, then at
+all times every window tree is a binary tree (a tree where each window
+except the root window has exactly one sibling).
Furthermore, @code{split-window} calls
@code{set-window-combination-limit} on the newly-created internal
@end group
@end example
-
@node Coordinates and Windows
@section Coordinates and Windows
+@cindex frame-relative coordinate
+@cindex coordinate, relative to frame
+@cindex window position
-This section describes how to relate screen coordinates to windows.
+ This section describes functions that report the position of a
+window. Most of these functions report positions relative to the
+window's frame. In this case, the coordinate origin @samp{(0,0)} lies
+near the upper left corner of the frame. For technical reasons, on
+graphical displays the origin is not located at the exact corner of
+the graphical window as it appears on the screen. If Emacs is built
+with the GTK+ toolkit, the origin is at the upper left corner of the
+frame area used for displaying Emacs windows, below the title-bar,
+GTK+ menu bar, and tool bar (since these are drawn by the window
+manager and/or GTK+, not by Emacs). But if Emacs is not built with
+GTK+, the origin is at the upper left corner of the tool bar (since in
+this case Emacs itself draws the tool bar). In both cases, the X and
+Y coordinates increase rightward and downward respectively.
+
+ Except where noted, X and Y coordinates are reported in integer
+character units, i.e. numbers of lines and columns respectively. On a
+graphical display, each ``line'' and ``column'' corresponds to the
+height and width of a default character specified by the frame's
+default font.
+
+@defun window-edges &optional window
+This function returns a list of the edge coordinates of @var{window}.
+If @var{window} is omitted or @code{nil}, it defaults to the selected
+window.
-@defun window-at x y &optional frame
-This function returns the window containing the specified cursor
-position in the frame @var{frame}. The coordinates @var{x} and @var{y}
-are measured in characters and count from the top left corner of the
-frame. If they are out of range, @code{window-at} returns @code{nil}.
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}. These list elements are, respectively, the X
+coordinate of the leftmost column occupied by the window, the Y
+coordinate of the topmost row, the X coordinate one column to the
+right of the rightmost column, and the Y coordinate one row down from
+the bottommost row.
-If you omit @var{frame}, the selected frame is used.
+Note that these are the actual outer edges of the window, including
+any header line, mode line, scroll bar, fringes, and display margins.
+On a text-only terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
+neighbor.
@end defun
-@defun coordinates-in-window-p coordinates window
-This function checks whether a particular frame position falls within
-the window @var{window}.
+@defun window-inside-edges &optional window
+This function is similar to @code{window-edges}, but the returned edge
+values are for the text area of the window. They exclude any header
+line, mode line, scroll bar, fringes, display margins, and vertical
+separator.
+@end defun
+
+@defun window-top-line &optional window
+This function returns the Y coordinate of the topmost row of
+@var{window}, equivalent to the @var{top} entry in the list returned
+by @code{window-edges}.
+@end defun
-The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
-. @var{y})}. The coordinates @var{x} and @var{y} are measured in
-characters, and count from the top left corner of the screen or frame.
+@defun window-left-column &optional window
+This function returns the X coordinate of the leftmost column of
+@var{window}, equivalent to the @var{left} entry in the list returned
+by @code{window-edges}.
+@end defun
+
+ The following functions can be used to relate a set of
+frame-relative coordinates to a window:
-The value returned by @code{coordinates-in-window-p} is non-@code{nil}
-if the coordinates are inside @var{window}. The value also indicates
-what part of the window the position is in, as follows:
+@defun window-at x y &optional frame
+This function returns the live window at the frame-relative
+coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
+window at that position, the return value is @code{nil}. If
+@var{frame} is omitted or @code{nil}, it defaults to the selected
+frame.
+@end defun
+
+@defun coordinates-in-window-p coordinates window
+This function checks whether a window @var{window} occupies the
+frame-relative coordinates @var{coordinates}, and if so which part of
+the window that is. @var{window} should be a live window.
+@var{coordinates} should be a cons cell of the form @code{(@var{x}
+. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
+
+If there is no window at the specified position, the return value is
+@code{nil} . Otherwise, the return value is one of the following:
@table @code
@item (@var{relx} . @var{rely})
argument because it always uses the frame that @var{window} is on.
@end defun
+ The following functions return window positions in pixels, rather
+than character units. Though mostly useful on graphical displays,
+they can also be called on text-only terminals, where the screen area
+of each text character is taken to be ``one pixel''.
+
+@defun window-pixel-edges &optional window
+This function returns a list of pixel coordinates for the edges of
+@var{window}. If @var{window} is omitted or @code{nil}, it defaults
+to the selected window.
+
+The return value has the form @code{(@var{left} @var{top} @var{right}
+@var{bottom})}. The list elements are, respectively, the X pixel
+coordinate of the left window edge, the Y pixel coordinate of the top
+edge, one more than the X pixel coordinate of the right edge, and one
+more than the Y pixel coordinate of the bottom edge.
+@end defun
+
+@defun window-inside-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the pixel coordinates for the edges of the window's text area,
+rather than the pixel coordinates for the edges of the window itself.
+@var{window} must specify a live window.
+@end defun
+
+ The following functions return window positions in pixels, relative
+to the display screen rather than the frame:
+
+@defun window-absolute-pixel-edges &optional window
+This function is like @code{window-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen.
+@end defun
+
+@defun window-inside-absolute-pixel-edges &optional window
+This function is like @code{window-inside-pixel-edges}, except that it
+returns the edge pixel coordinates relative to the top left corner of
+the display screen. @var{window} must specify a live window.
+@end defun
@node Window Configurations
@section Window Configurations
@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
window configuration. The default for @var{frame} is the selected
-frame.
+frame. The variable @code{window-persistent-parameters} specifies
+whether and which window parameters are saved by this function, see
+@ref{Window Parameters} for details.
@end defun
@defun set-window-configuration configuration
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.
+configuration on disk and read it back in another Emacs session, the
+functions described next can be used. These functions are also useful
+to clone the state of a frame into an arbitrary live window
+(@code{set-window-configuration} effectively clones the windows of a
+frame into the root window of that very frame only).
-@defun window-state-get &optional window markers
+@defun window-state-get &optional window writable
This function returns the state of @var{window} as a Lisp object. The
argument @var{window} can be any window and defaults to the root window
of the selected frame.
-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.
+If the optional argument @var{writable} is non-@code{nil}, this means to
+not use markers for sampling positions like @code{window-point} or
+@code{window-start}. This argument should be non-@code{nil} when the
+state shall be written to disk and read back in another session.
+
+Together, the argument @var{writable} and the variable
+@code{window-persistent-parameters} specify which window parameters are
+saved by this function, see @ref{Window Parameters} for details.
@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.
+The value returned by @code{window-state-get} can be used in the same
+session to make a clone of a window in another window. It can be also
+written to disk and read back in another session. In either case, use
+the function described next to restore the state of the window.
@defun window-state-put state &optional window ignore
This function puts the window state @var{state} into @var{window}. The
is the selected window.
@end defun
+By default, functions saving and restoring window configurations or the
+states of windows (@pxref{Window Configurations}) do not care about
+window parameters. This means, that when you change the value of a
+parameter within the body of a @code{save-window-excursion}, the
+previous value is not restored upon exit of that macro. It also means
+that when you restore via @code{window-state-put} a window state saved
+earlier by @code{window-state-get}, all cloned windows have their
+parameters reset to @code{nil}. The following variable allows to
+override the standard behavior.
+
+@defvar window-persistent-parameters
+This variable is an alist specifying which parameters get saved by
+@code{current-window-configuration} and @code{window-state-get} and
+subsequently restored by @code{set-window-configuration} and
+@code{window-state-put}, see @ref{Window Configurations}.
+
+The @sc{car} of each entry of this alist is the symbol specifying the
+parameter. The @sc{cdr} should be one of the following:
+
+@table @asis
+@item @code{nil}
+This value means the parameter is neither saved by
+@code{window-state-get} nor by @code{current-window-configuration}.
+
+@item @code{t}
+This value specifies that the parameter is saved by
+@code{current-window-configuration} and, provided its @var{writable}
+argument is @code{nil}, by @code{window-state-get}.
+
+@item @code{writable}
+This means that the parameter is saved unconditionally by both
+@code{current-window-configuration} and @code{window-state-get}. This
+value should not be used for parameters whose values do not have a read
+syntax. Otherwise, invoking @code{window-state-put} in another session
+may fail with an @code{invalid-read-syntax} error.
+@end table
+@end defvar
+
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
@end defvar
The following parameters are currently used by the window management
-code.
+code:
@table @asis
@item @code{delete-window}
@item @code{no-other-window}
This parameter marks the window as not selectable by @code{other-window}
(@pxref{Cyclic Window Ordering}).
+
+@item @code{clone-of}
+This parameter specifies the window this one has been cloned from and is
+installed by @code{window-state-get}, see @ref{Window Configurations}.
+
+@item @code{quit-restore}
+This parameter tells how to proceed with a window when the buffer it
+shows is no more needed. It is installed by the buffer display
+functions (@pxref{Choosing Window}) and consulted by the function
+@code{quit-window} (@pxref{Quitting Windows}).
@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}).
+are reserved and should not be used by applications.
@node Window Hooks