@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/windows
@node Windows, Frames, Buffers, Top
In each frame, at any time, one and only one window is designated as
@dfn{selected within the frame}. The frame's cursor appears in that
window, but the other windows have ``non-selected'' cursors, normally
-less visible. At any time, one frame is the selected frame; and the
-window selected within that frame is @dfn{the selected window}. The
-selected window's buffer is usually the current buffer (except when
-@code{set-buffer} has been used). @xref{Current Buffer}.
-
-@defvar cursor-in-non-selected-windows
-If this variable is @code{nil}, Emacs displays only one cursor,
-in the selected window. Other windows have no cursor at all.
-@end defvar
+less visible. (@pxref{Cursor Parameters}, for customization of 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). @xref{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
previously visible in the window that was split.
@deffn Command split-window &optional window size horizontal
-This function splits @var{window} into two windows. The original
-window @var{window} remains the selected window, but occupies only
-part of its former screen area. The rest is occupied by a newly created
-window which is returned as the value of this function.
+This function splits a new window out of @var{window}'s screen area.
+It returns the new window.
If @var{horizontal} is non-@code{nil}, then @var{window} splits into
two side by side windows. The original window @var{window} keeps the
left-hand or upper of the two, and the new window is the right-hand or
lower.
-If @var{window} is omitted or @code{nil}, then the selected window is
-split. 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 @var{window} is omitted or @code{nil}, that stands for the selected
+window. When you split the selected window, it remains selected.
+
+If @var{size} is omitted or @code{nil}, then @var{window} is divided
+evenly into two parts. (If there is an odd line, it is allocated to
+the new window.) When @code{split-window} is called interactively,
+all its arguments are @code{nil}.
If splitting would result in making a window that is smaller than
@code{window-min-height} or @code{window-min-width}, the function
@node Selecting Windows
@section Selecting Windows
-@cindex 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.
the order is left to right, or top to bottom.
@defun next-window &optional window minibuf all-frames
-@cindex minibuffer window
+@cindex minibuffer window, and @code{next-window}
This function returns the window following @var{window} in the cyclic
ordering of windows. This is the window that @kbd{C-x o} would select
if typed when @var{window} is selected. If @var{window} is the only
@noindent
@xref{Positions}, for more details on buffer positions.
+@cindex cursor
As far as the user is concerned, point is where the cursor is, and
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.
@node Window Start
@section The Window Start Position
+@cindex window start position
Each window contains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
at the upper left corner of the window. It is usually, but not
inevitably, at the beginning of a text line.
+ After switching windows or buffers, and in some other cases, if the
+window start is in the middle of a line, Emacs adjusts the window
+start to the start of a line. This prevents certain operations from
+leaving the window start at a meaningless point within a line. This
+feature may interfere with testing some Lisp code by executing it
+using the commands of Lisp mode, because they trigger this
+readjustment. To test such code, put it into a command and bind the
+command to a key.
+
@defun window-start &optional window
@cindex window top line
This function returns the display-start position of window
screen. If this does place point off screen, the display routines move
point to the left margin on the middle line in the window.
-For example, if point @w{is 1} and you set the start of the window @w{to
-2}, then point would be ``above'' the top of the window. The display
-routines will automatically move point if it is still 1 when redisplay
-occurs. Here is an example:
+For example, if point @w{is 1} and you set the start of the window
+@w{to 37}, the start of the next line, point will be ``above'' the top
+of the window. The display routines will automatically move point if
+it is still 1 when redisplay occurs. Here is an example:
@example
@group
@group
(set-window-start
(selected-window)
- (1+ (window-start)))
-@result{} 2
+ (save-excursion
+ (goto-char 1)
+ (forward-line 1)
+ (point)))
+@result{} 37
@end group
@group
;; @r{Here is what @samp{foo} looks like after executing}
;; @r{the @code{set-window-start} expression.}
---------- Buffer: foo ----------
-his is the contents of buffer foo.
2
3
@point{}4
@var{position} defaults to the current position of point in
@var{window}; @var{window}, to the selected window.
+If @var{position} is @code{t}, that means to check the last visible
+position in @var{window}.
+
The @code{pos-visible-in-window-p} function considers only vertical
scrolling. If @var{position} is out of view only because @var{window}
has been scrolled horizontally, @code{pos-visible-in-window-p} returns
If @var{position} is visible, @code{pos-visible-in-window-p} returns
@code{t} if @var{partially} is @code{nil}; if @var{partially} is
-non-@code{nil}, it returns a list of the form @code{(@var{x} @var{y}
-@var{partial})}, where @var{x} and @var{y} are the pixel coordinates
-relative to the top left corner of the window, and @var{partial} is
-@code{nil} if the character after @var{position} is fully visible;
-otherwise it is a cons @code{(@var{rtop} . @var{rbot})} where the
-@var{rtop} and @var{rbot} specify the number of invisible pixels at
-the top and bottom of the row at @var{position}.
+non-@code{nil}, and the character after @var{position} is fully
+visible, it returns a list of the form @code{(@var{x} @var{y})}, where
+@var{x} and @var{y} are the pixel coordinates relative to the top left
+corner of the window; otherwise it returns an extended list of the
+form @code{(@var{x} @var{y} @var{rtop} @var{rbot} @var{rowh}
+@var{vpos})}, where the @var{rtop} and @var{rbot} specify the number
+of off-window pixels at the top and bottom of the row at
+@var{position}, @var{rowh} specifies the visible height of that row,
+and @var{vpos} specifies the vertical position (zero-based row number)
+of that row.
Here is an example:
@end example
@end defun
+@defun window-line-height &optional line window
+This function returns information about text line @var{line} in @var{window}.
+If @var{line} is one of @code{header-line} or @code{mode-line},
+@code{window-line-height} returns information about the corresponding
+line of the window. Otherwise, @var{line} is a text line number
+starting from 0. A negative number counts from the end of the window.
+The argument @var{line} defaults to the current line in @var{window};
+@var{window}, to the selected window.
+
+If the display is not up to date, @code{window-line-height} returns
+@code{nil}. In that case, @code{pos-visible-in-window-p} may be used
+to obtain related information.
+
+If there is no line corresponding to the specified @var{line},
+@code{window-line-height} returns @code{nil}. Otherwise, it returns
+a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
+where @var{height} is the height in pixels of the visible part of the
+line, @var{vpos} and @var{ypos} are the vertical position in lines and
+pixels of the line relative to the top of the first text line, and
+@var{offbot} is the number of off-window pixels at the bottom of the
+text line. If there are off-window pixels at the top of the (first)
+text line, @var{ypos} is negative.
+@end defun
+
@node Textual Scrolling
@section Textual Scrolling
@cindex textual scrolling
@code{scroll-other-window} attempts to scroll the minibuffer. If the
minibuffer contains just one line, it has nowhere to scroll to, so the
line reappears after the echo area momentarily displays the message
-``Beginning of buffer''.
+@samp{Beginning of buffer}.
@end deffn
@c Emacs 19 feature
@end defopt
@defopt scroll-down-aggressively
-@tindex scroll-down-aggressively
The value of this variable should be either @code{nil} or a fraction
@var{f} between 0 and 1. If it is a fraction, that specifies where on
the screen to put point when scrolling down. More precisely, when a
@end defopt
@defopt scroll-up-aggressively
-@tindex scroll-up-aggressively
Likewise, for scrolling up. The value, @var{f}, specifies how far
point should be placed from the bottom of the window; thus, as with
@code{scroll-up-aggressively}, a larger value scrolls more aggressively.
@node Vertical Scrolling
@section Vertical Fractional Scrolling
-@cindex Vertical Fractional Scrolling
+@cindex vertical fractional scrolling
@dfn{Vertical fractional scrolling} means shifting the image in the
window up or down by a specified multiple or fraction of a line.
disappear off to the left depends on their width, and could vary from
line to line.
- Because we read from side to side in the ``inner loop'', and from top
-to bottom in the ``outer loop'', the effect of horizontal scrolling is
+ Because we read from side to side in the ``inner loop,'' and from top
+to bottom in the ``outer loop,'' the effect of horizontal scrolling is
not like that of textual or vertical scrolling. Textual scrolling
involves selection of a portion of text to display, and vertical
scrolling moves the window contents contiguously; but horizontal
@end example
@end defun
-@tindex window-body-height
@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 example
@end defun
+@defun window-full-width-p &optional window
+This function returns non-@code{nil} if @var{window} is as wide as
+the frame that contains it; otherwise @code{nil}.
+If @var{window} is @code{nil}, the function uses the selected window.
+@end defun
+
@defun window-edges &optional window
This function returns a list of the edge coordinates of @var{window}.
If @var{window} is @code{nil}, the selected window is used.
@node Resizing Windows
@section Changing the Size of a Window
@cindex window resizing
+@cindex resize window
@cindex changing window size
@cindex window size, changing
and @code{nil} otherwise.
@end deffn
-@tindex window-size-fixed
@defvar window-size-fixed
If this variable is non-@code{nil}, in any given buffer,
then the size of any window displaying the buffer remains fixed
@cindex saving window information
A @dfn{window configuration} records the entire layout of one
-frame---all windows, their sizes, which buffers they contain, what
-part of each buffer is displayed, and the values of point and the
-mark; also their fringes, margins, and scroll bar settings. It also
+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 values of @code{window-min-height},
-@code{window-min-width} and @code{minibuffer-scroll-window}. An
-exception is made for point in the selected window for the current
-buffer; its value is not saved in the window configuration.
+@code{window-min-width} and @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.
You can bring back an entire previous layout by restoring a window
configuration previously saved. If you want to record all frames
@node Window Hooks
@section Hooks for Window Scrolling and Changes
+@cindex hooks for window operations
This section describes how a Lisp program can take action whenever a
window displays a different part of its buffer or a different buffer.
These functions must be careful in using @code{window-end}
(@pxref{Window Start}); if you need an up-to-date value, you must use
the @var{update} argument to ensure you get it.
+
+@strong{Warning:} don't use this feature to alter the way the window
+is scrolled. It's not designed for that, and such use probably won't
+work.
@end defvar
@defvar window-size-change-functions