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 the window is split.
+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,
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
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
@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
left you can scroll, but eventually all the text will disappear off the
left edge.
-@vindex automatic-hscrolling
+@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, if
-@code{automatic-hscrolling} is set. However, you can still set the
+@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.
@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
@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