part of its former screen area. The rest is occupied by a newly created
window which is returned as the value of this function.
- If @var{horizontal} is non-@code{nil}, then @var{window} splits into
+If @var{horizontal} is non-@code{nil}, then @var{window} splits into
two side by side windows. The original window @var{window} keeps the
leftmost @var{size} columns, and gives the rest of the columns to the
new window. Otherwise, it splits into windows one above the other, and
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
+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}.
- The following example starts with one window on a screen that is 50
-lines high by 80 columns wide; then the window is split.
+If splitting would result in making a window that is smaller than
+@code{window-min-height} or @code{window-min-width}, the function
+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.
@smallexample
@group
@end group
@end smallexample
-Next, the top window is split horizontally:
+Next, split the top window horizontally:
@smallexample
@group
@end smallexample
@need 3000
-Now, the screen looks like this:
+Now the screen looks like this:
@smallexample
@group
@defmac save-selected-window forms@dots{}
This macro records the selected window, executes @var{forms}
-in sequence, then restores the earlier selected window.
+in sequence, then restores the earlier selected window (unless that
+window is no longer alive).
This macro does not save or restore anything about the sizes, arrangement
or contents of windows; therefore, if the @var{forms} change them,
consider. See @code{get-lru-window}, above.
@end defun
+@cindex window that satisfies a predicate
+@cindex conditional selection of windows
+@defun get-window-with-predicate predicate &optional minibuf all-frames default
+This function returns a window satisfying @var{predicate}. It cycles
+through all visible windows using @code{walk-windows} (@pxref{Cyclic
+Window Ordering}), calling @var{predicate} on each one 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}.
+
+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
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
-always returns @code{nil}.
+returns the buffer that it switched to.
@end deffn
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
This function 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 within
-its frame.
+its frame. The return value is the buffer that was switched to.
If the variable @code{pop-up-frames} is non-@code{nil},
@code{pop-to-buffer} looks for a window in any visible frame already
Emacs does not know the position of the end of display in that window.
In that case, this function returns @code{nil}.
-If @var{update} is non-@code{nil}, @code{window-end} always returns
-an up-to-date value for where the window ends. If the saved value is
-valid, @code{window-end} returns that; otherwise it computes the correct
+If @var{update} is non-@code{nil}, @code{window-end} always returns an
+up-to-date value for where the window ends, based on the current
+@code{window-start} value. If the saved value is valid,
+@code{window-end} returns that; otherwise it computes the correct
value by scanning the buffer text.
+
+Even if @var{update} is non-@code{nil}, @code{window-end} does not
+attempt to scroll the display if point has moved off the screen, the
+way real redisplay would do. It does not alter the
+@code{window-start} value. In effect, it reports where the displayed
+text will end if scrolling is not required.
@end defun
@defun set-window-start window position &optional noforce
This option specifies the size of the scroll margin---a minimum number
of lines between point and the top or bottom of a window. Whenever
point gets within this many lines of the top or bottom of the window,
-the window scrolls automatically (if possible) to move point out of the
-margin, closer to the center of the window.
+redisplay scrolls the text automatically (if possible) to move point
+out of the margin, closer to the center of the window.
@end defopt
@defopt scroll-conservatively
This variable controls how scrolling is done automatically when point
-moves off the screen (or into the scroll margin). If the value is zero,
-then redisplay scrolls the text to center point vertically in the
-window. If the value is a positive integer @var{n}, then redisplay
-scrolls the window up to @var{n} lines in either direction, if that will
-bring point back into view. Otherwise, it centers point. The default
-value is zero.
-
-A value of @code{nil} is equivalent to .5, since it centers point. This
-variable automatically becomes buffer-local when set in any fashion.
+moves off the screen (or into the scroll margin). If the value is a
+positive integer @var{n}, then redisplay scrolls the text up to
+@var{n} lines in either direction, if that will bring point back into
+proper view. This action is called @dfn{conservative scrolling}.
+Otherwise, scrolling happens in the usual way, under the control of
+other variables such as @code{scroll-up-aggressively} and
+@code{scroll-down-aggressively}.
+
+The default value is zero, which means that conservative scrolling
+never happens.
@end defopt
-@defopt scroll-up-aggressively
-@tindex scroll-up-aggressively
+@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 upward. More precisely, when a
-window scrolls up because point is above the window start, the new start
-position is chosen to put point @var{f} part of the window height from
-the top. The larger @var{f}, the more aggressive the scrolling.
+the screen to put point when scrolling down. More precisely, when a
+window scrolls down because point is above the window start, the new
+start position is chosen to put point @var{f} part of the window
+height from the top. The larger @var{f}, the more aggressive the
+scrolling.
A value of @code{nil} is equivalent to .5, since its effect is to center
point. This variable automatically becomes buffer-local when set in any
fashion.
@end defopt
-@defopt scroll-down-aggressively
-@tindex scroll-down-aggressively
-Likewise, for scrolling down. The value, @var{f}, specifies how far
+@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.
@end defopt
@deffn Command recenter &optional count
@cindex centering point
-This function scrolls the selected window to put the text where point
-is located at a specified vertical position within the window.
+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, it 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 line in the window.
-If @var{count} is a non-@code{nil} list, then it stands for the line in
-the middle of the window.
+If @var{count} is a nonnegative 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
+line in the window. If @var{count} is a non-@code{nil} list, then it
+stands for the line in the middle of the window.
If @var{count} is @code{nil}, @code{recenter} puts the line containing
point in the middle of the window, then clears and redisplays the entire
@var{lines}. The argument @var{lines} should be zero or positive; if
not, it is taken as zero.
+If @var{window} is @code{nil}, the selected window is used.
+
The actual vertical scroll position must always correspond
to an integral number of pixels, so the value you specify
is rounded accordingly.
@dfn{Horizontal scrolling} means shifting the image in the window left
or right by a specified multiple of the normal character width. Each
-window has a @dfn{vertical scroll position}, which is a number, never
+window has a @dfn{horizontal scroll position}, which is a number, never
less than zero. It specifies how far to shift the contents left.
Shifting the window contents left generally makes all or part of some
characters disappear off the left, and all or part of some other
The horizontal scroll position is measured in units of the normal
character width, which is the width of space in the default font. Thus,
if the value is 5, that means the window contents are scrolled left by 5
-times the the normal character width. How many characters actually
+times the normal character width. How many characters actually
disappear off to the left depends on their width, and could vary from
line to line.
left you can scroll, but eventually all the text will disappear off the
left edge.
+@vindex auto-hscroll-mode
In Emacs 21, redisplay automatically alters the horizontal scrolling
-of a window as necessary to ensure that point is always visible.
-However, you can still set the horizontal scrolling value explicitly.
-The value you specify will be used, provided it leaves point visible.
+of a window as necessary to ensure that point is always visible, if
+@code{auto-hscroll-mode} is set. However, you can still set the
+horizontal scrolling value explicitly. The value you specify serves as
+a lower bound for automatic scrolling, i.e. automatic scrolling
+will not scroll a window to a column less than the specified one.
@deffn Command scroll-left &optional count
This function scrolls the selected window @var{count} columns to the
@var{columns} should be zero or positive; if not, it is taken as zero.
Fractional values of @var{columns} are not supported at present.
+Note that @code{set-window-hscroll} may appear not to work if you test
+it by evaluating a call with @kbd{M-:} in a simple way. What happens
+is that the function sets the horizontal scroll value and returns, but
+then redisplay adjusts the horizontal scrolling to make point visible,
+and this overrides what the function did. You can observe the
+function's effect if you call it while point is sufficiently far from
+the left margin that it will remain visible.
+
The value returned is @var{columns}.
@example
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}, including its
-mode line. If @var{window} fills its entire frame, this is typically
-one less than the value of @code{frame-height} on that frame (since the
-last line is always reserved for the minibuffer).
+This function returns the number of lines in @var{window}, including
+its mode line and header line, if any. If @var{window} fills its
+entire frame except for the echo area, and there is no tool bar, this
+is typically one less than the value of @code{frame-height} on that
+frame.
If @var{window} is @code{nil}, the function uses the selected window.
@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 defun
+
@defun window-width &optional window
This function returns the number of columns in @var{window}. If
@var{window} fills its entire frame, this is the same as the value of
@end defvar
@cindex minimum window size
- The following two variables constrain the window-size-changing
+ 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 determines 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 absolute minimum height is two (allowing
-one line for the mode line, and one line for the buffer display).
-Actions that change window sizes reset this variable to two if it is
-less than two. The default value is 4.
+@code{window-min-height} automatically deletes it, and no window may
+be created shorter than this. The default value is 4.
+
+The absolute minimum window height is one; actions that change window
+sizes reset this variable to one if it is less than one.
@end defopt
@defopt window-min-width
The value of this variable determines 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 absolute minimum width is one; any
-value below that is ignored. The default value is 10.
+created narrower than this. The default value is 10.
+
+The absolute minimum window width is two; actions that change window
+sizes reset this variable to two if it is less than two.
@end defopt
@node Coordinates and Windows
@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. You
-can bring back an entire previous layout by restoring a window
-configuration previously saved.
-
- If you want to record all frames instead of just one, use a frame
-configuration instead of a window configuration. @xref{Frame
-Configurations}.
+frame---all windows, their sizes, which buffers they contain, what
+part of each buffer is displayed, and the values of point and the
+mark. 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.
+
+ You can bring back an entire previous layout by restoring a window
+configuration previously saved. If you want to record all frames
+instead of just one, use a frame configuration instead of a window
+configuration. @xref{Frame Configurations}.
@defun current-window-configuration &optional frame
-This function returns a new object representing @var{frame}'s
-current window configuration, including the number of windows, their
-sizes and current buffers, which window is the selected window, and for
-each window the displayed buffer, the display-start position, and the
-positions of point and the mark. 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
-current buffer, whose value is not saved.
-
-If @var{frame} is omitted, the selected frame is used.
+This function returns a new object representing @var{frame}'s current
+window configuration. If @var{frame} is omitted, the selected frame
+is used.
@end defun
@defun set-window-configuration configuration
HCoop / bpt / emacs.git / blobdiff