xemacs-beta: man/lispref/windows.texi comparison

comparison man/lispref/windows.texi @ 444:576fb035e263 r21-2-37

Import from CVS: tag r21-2-37

author	cvs
date	Mon, 13 Aug 2007 11:36:19 +0200
parents	abe6d1db359e
children	33f0f28b945c

comparison

equal deleted inserted replaced

-:a8296e22da4e
+:576fb035e263
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/windows.info
 @node Windows, Frames, Buffers, Top
 @chapter Windows
 * Displaying Buffers::     Higher-lever functions for displaying a buffer
 and choosing a window for it.
 * Choosing Window::	   How to choose a window for displaying a buffer.
 * Window Point::           Each window has its own location of point.
 * Window Start::           The display-start position controls which text
 is on-screen in the window.
 * Vertical Scrolling::     Moving text up and down in the window.
 * Horizontal Scrolling::   Moving text sideways on the window.
 * Size of Window::         Accessing the size of a window.
 * Position of Window::     Accessing the position of a window.
 * Resizing Windows::       Changing the size of a window.
 @itemize @bullet
 @item
 containing frame
 @item
 window height
 @item
 window width
 @item
 window edges with respect to the frame or screen
 @item
 the buffer it displays
 @item
 position within the buffer at the upper left of the window
 @item
 amount of horizontal scrolling, in columns
 @item
 point
 @item
 the mark
 @item
 how recently the window was selected
 @end itemize
 @cindex multiple windows
 Users create multiple windows so they can look at several buffers at
 The functions described here do not accept a buffer as an argument.
 The two ``halves'' of the split window initially display the same buffer
 previously visible in the window that was split.
-@defun one-window-p &optional no-mini all-frames
+@defun one-window-p &optional nomini which-frames which-devices
 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
+argument @var{nomini}, if non-@code{nil}, means don't count the
 minibuffer even if it is active; otherwise, the minibuffer window is
 included, if active, in the total number of windows which is compared
 against one.
-The argument @var{all-frame} controls which set of windows are
+The remaining arguments controls which set of windows are counted, as
-counted.
+with @code{next-window}.
-@itemize @bullet
-@item
-If it is @code{nil} or omitted, then count only the selected frame, plus
-the minibuffer it uses (which may be on another frame).
-@item
-If it is @code{t}, then windows on all frames that currently exist
-(including invisible and iconified frames) are counted.
-@item
-If it is the symbol @code{visible}, then windows on all visible frames
-are counted.
-@item
-If it is the number 0, then windows on all visible and iconified frames
-are counted.
-@item
-If it is any other value, then precisely the windows in @var{window}'s
-frame are counted, excluding the minibuffer in use if it lies in
-some other frame.
-@end itemize
 @end defun
 @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
 @result{} (0 0 80 50)     ;   @r{left--top--right--bottom}
 @end group
 @group
 ;; @r{Returns window created}
 (setq w2 (split-window w 15))
 @result{} #<window 28 on windows.texi>
 @end group
 @group
 (window-edges w2)
 @result{} (0 15 80 50)    ; @r{Bottom window;}
 The frame looks like this:
 @smallexample
 @group
 __________
 |          |  line 0
 |    w     |
 |__________|
 |          |  line 15
 |    w2    |
 |__________|
 Now, the screen looks like this:
 @smallexample
 @group
 column 35
 __________
 |   |      |  line 0
 | w |  w3  |
 |___|______|
 |          |  line 15
 |    w2    |
 |__________|
 @deffn Command split-window-vertically &optional size
 This function splits the selected window into two windows, one above
 the other, leaving the selected window with @var{size} lines.
-This function is simply an interface to @code{split-windows}.
+This function is simply an interface to @code{split-window}.
 Here is the complete function definition for it:
 @smallexample
 @group
 (defun split-window-vertically (&optional arg)
 @deffn Command split-window-horizontally &optional size
 This function splits the selected window into two windows
 side-by-side, leaving the selected window with @var{size} columns.
-This function is simply an interface to @code{split-windows}.  Here is
+This function is simply an interface to @code{split-window}.  Here is
 the complete definition for @code{split-window-horizontally} (except for
 part of the documentation string):
 @smallexample
 @group
 (interactive "P")
 (split-window nil (and arg (prefix-numeric-value arg)) 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
-included, if active, in the total number of windows, which is compared
-against one.
-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
 @cindex deleting windows
 @strong{Warning:} Erroneous information or fatal errors may result from
 using a deleted window as if it were live.
 @end defun
-@deffn Command delete-window &optional window
+@deffn Command delete-window &optional window force
-This function removes @var{window} from the display.  If @var{window}
+This function removes @var{window} from the display.  If @var{window} is
-is omitted, then the selected window is deleted.  An error is signaled
+omitted, then the selected window is deleted. If window is the only one
-if there is only one window when @code{delete-window} is called.
+on its frame, the frame is deleted as well.
+Normally, you cannot delete the last non-minibuffer-only frame (you must
+use @code{save-buffers-kill-emacs} or @code{kill-emacs}); an error is
+signaled instead.  However, if optional second argument @var{force} is
+non-@code{nil}, you can delete the last frame. (This will automatically
+call @code{save-buffers-kill-emacs}.)
 This function returns @code{nil}.
-When @code{delete-window} is called interactively, @var{window}
+When @code{delete-window} is called interactively, the selected window
-defaults to the selected window.
+is deleted.
 @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.  If @var{window} is omitted or
 @code{nil}, then the selected window is used by default.
 The result is @code{nil}.
 @end deffn
-@deffn Command delete-windows-on buffer &optional frame
+@deffn Command delete-windows-on buffer &optional which-frames which-devices
 This function deletes all windows showing @var{buffer}.  If there are
 no windows showing @var{buffer}, it does nothing.
 @code{delete-windows-on} operates frame by frame.  If a frame has
 several windows showing different buffers, then those showing
 all windows in some frame are showing @var{buffer} (including the case
 where there is only one window), then the frame reverts to having a
 single window showing another buffer chosen with @code{other-buffer}.
 @xref{The Buffer List}.
-The argument @var{frame} controls which frames to operate on:
+The argument @var{which-frames} controls which frames to operate on:
-@itemize @bullet
+@table @asis
-@item
+@item @code{nil}
-If it is @code{nil}, operate on the selected frame.
+Delete all windows showing @var{buffer} in any frame.
-@item
-If it is @code{t}, operate on all frames.
+@item @code{t}
-@item
+Delete only windows showing @var{buffer} in the selected frame.
-If it is @code{visible}, operate on all visible frames.
-@item 0
+@item @code{visible}
-If it is 0, operate on all visible or iconified frames.
+Delete all windows showing @var{buffer} in any visible frame.
-@item
-If it is a frame, operate on that frame.
+@item @code{0}
-@end itemize
+Delete all windows showing @var{buffer} in any visible frame.
+@item @var{frame}
+If it is a frame, delete all windows showing @var{buffer} in that frame.
+@end table
+@strong{Warning:} This is similar to, but not identical to, the meaning
+of the @var{which-frames} argument to @code{next-window}; the meanings
+of @code{nil} and @code{t} are reversed.
+The optional argument @var{which-devices} further clarifies on which
+devices to search for frames as specified by @var{which-frames}.
+This value is only meaningful if @var{which-frames} is not @code{t}.
+@table @asis
+@item @code{nil}
+Consider all devices on the selected console.
+@item @var{device}
+Consider only the one device @var{device}.
+@item @var{console}
+Consider all devices on @var{console}.
+@item @var{device-type}
+Consider all devices with device type @var{device-type}.
+@item @code{window-system}
+Consider all devices on window system consoles.
+@item anything else
+Consider all devices without restriction.
+@end table
 This function always returns @code{nil}.
 @end deffn
 @node Selecting Windows
 appears in @var{window} (on redisplay).  The buffer being displayed in
 @var{window} is immediately designated the current buffer.
 If optional argument @var{norecord} is non-@code{nil} then the global
 and per-frame buffer orderings are not modified, as by the function
 @code{record-buffer}.
 The return value is @var{window}.
 @example
 @group
 @result{} #<window 65 on windows.texi>
 @end group
 @end example
 @end defun
-@defmac save-selected-window forms@dots{}
+@defspec save-selected-window forms@dots{}
-This macro records the selected window, executes @var{forms}
+This special form records the selected window, executes @var{forms} in
-in sequence, then restores the earlier selected window.
+sequence, then restores the earlier selected window.  It does not save
-It does not save or restore anything about the sizes, arrangement
+or restore anything about the sizes, arrangement or contents of windows;
-or contents of windows; therefore, if the @var{forms} change them,
+therefore, if the @var{forms} change them, the changes are permanent.
-the changes are permanent.
+@end defspec
-@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
+@defun get-lru-window &optional which-frames which-devices
 This function returns the window least recently ``used'' (that is,
 selected).  The selected window is always the most recently used window.
 The selected window can be the least recently used window if it is the
 only window.  A newly created window becomes the least recently used
 window until it is selected.  A minibuffer window is never a candidate.
-The argument @var{frame} controls which windows are considered.
+By default, only the windows in the selected frame are considered.
+The optional argument @var{which-frames} changes this behavior.
-@itemize @bullet
+Here are the possible values and their meanings:
-@item
-If it is @code{nil}, consider windows on the selected frame.
+@table @asis
-@item
+@item @code{nil}
-If it is @code{t}, consider windows on all frames.
+Consider all the windows in the selected windows's frame, plus the
-@item
+minibuffer used by that frame even if it lies in some other frame.
-If it is @code{visible}, consider windows on all visible frames.
-@item
+@item @code{t}
-If it is 0, consider windows on all visible or iconified frames.
+Consider all windows in all existing frames.
-@item
-If it is a frame, consider windows on that frame.
+@item @code{visible}
-@end itemize
+Consider all windows in all visible frames.  (To get useful results, you
-@end defun
+must ensure @var{window} is in a visible frame.)
-@defun get-largest-window &optional frame
+@item @code{0}
+Consider all windows in all visible or iconified frames.
+@item @var{frame}
+Consider all windows on frame @var{frame}.
+@item anything else
+Consider precisely the windows in the selected window's frame, and no others.
+@end table
+The optional argument @var{which-devices} further clarifies on which
+devices to search for frames as specified by @var{which-frames}.
+This value is only meaningful if @var{which-frames} is non-@code{nil}.
+@table @asis
+@item @code{nil}
+Consider all devices on the selected console.
+@item @var{device}
+Consider only the one device @var{device}.
+@item @var{console}
+Consider all devices on @var{console}.
+@item @var{device-type}
+Consider all devices with device type @var{device-type}.
+@item @code{window-system}
+Consider all devices on window system consoles.
+@item anything else
+Consider all devices without restriction.
+@end table
+@end defun
+@defun get-largest-window &optional which-frames which-devices
 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.
 If there are two windows of the same size, then the function returns
 the window that is first in the cyclic ordering of windows (see
 following section), starting from the selected window.
-The argument @var{frame} controls which set of windows are
+The remaining arguments control which set of windows are considered.
-considered.  See @code{get-lru-window}, above.
+See @code{next-window}, above.
 @end defun
 @node Cyclic Window Ordering
 @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
 the next window, it moves through all the windows on the screen in a
 specific cyclic order.  For any given configuration of windows, this
 order never varies.  It is called the @dfn{cyclic ordering of windows}.
 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,
 the order is left to right, or top to bottom.
-@defun next-window &optional window minibuf all-frames
+@defun next-window &optional window minibuf which-frames which-devices
 @cindex minibuffer 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
 window visible, then this function returns @var{window}.  If omitted,
 minibuffer window even if it is not active.
 If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer
 window is not included even if it is active.
-The argument @var{all-frames} specifies which frames to consider.  Here
+By default, only the windows in the selected frame are considered.
-are the possible values and their meanings:
+The optional argument @var{which-frames} changes this behavior.
+Here are the possible values and their meanings:
 @table @asis
 @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.
 @item @code{visible}
 Consider all windows in all visible frames.  (To get useful results, you
 must ensure @var{window} is in a visible frame.)
-@item 0
+@item @code{0}
 Consider all windows in all visible or iconified frames.
+@item @var{frame}
+Consider all windows on frame @var{frame}.
 @item anything else
 Consider precisely the windows in @var{window}'s frame, and no others.
 @end table
-This example assumes there are two windows, both displaying the
+The optional argument @var{which-devices} further clarifies on which
+devices to search for frames as specified by @var{which-frames}.
+This value is only meaningful if @var{which-frames} is non-@code{nil}.
+@table @asis
+@item @code{nil}
+Consider all devices on the selected console.
+@item @var{device}
+Consider only the one device @var{device}.
+@item @var{console}
+Consider all devices on @var{console}.
+@item @var{device-type}
+Consider all devices with device type @var{device-type}.
+@item @code{window-system}
+Consider all devices on window system consoles.
+@item anything else
+Consider all devices without restriction.
+@end table
+If you use consistent values for @var{minibuf}, @var{which-frames}, and
+@var{which-devices}, you can use @code{next-window} to iterate through the
+entire cycle of acceptable windows, eventually ending up back at the
+window you started with.  @code{previous-window} traverses the same
+cycle, in the reverse order.
+This example assumes there are two windows, both displaying the
 buffer @samp{windows.texi}:
 @example
 @group
 (selected-window)
 @result{} #<window 56 on windows.texi>
 @end group
 @end example
 @end defun
-@defun previous-window &optional window minibuf all-frames
+@defun previous-window &optional window minibuf which-frames which-devices
 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 defun
-@deffn Command other-window count &optional frame
+@deffn Command other-window count &optional which-frames which-devices
-This function selects the @var{count}th following window in the cyclic
+This function selects the @var{count}th following window in the cyclic order.
-order.  If count is negative, then it selects the @minus{}@var{count}th
+If @var{count} is negative, then it selects the @minus{}@var{count}th
 preceding window.  It returns @code{nil}.
 In an interactive call, @var{count} is the numeric prefix argument.
-The argument @var{frame} controls which set of windows are considered.
+The other arguments specify which windows to include in the cycle, as in
-@itemize @bullet
+@code{next-window}.
-@item
+@end deffn
-If it is @code{nil} or omitted, then windows on the selected frame are
-considered.
+@defun walk-windows function &optional minibuf which-frames which-devices
-@item
+This function cycles through all windows, calling @code{function}
-If it is a frame, then windows on that frame are considered.
-@item
-If it is @code{t}, then windows on all frames that currently exist
-(including invisible and iconified frames) are considered.
-@item
-If it is the symbol @code{visible}, then windows on all visible frames
-are considered.
-@item
-If it is the number 0, then windows on all visible and iconified frames
-are considered.
-@item
-If it is any other value, then the behavior is undefined.
-@end itemize
-@end deffn
-@c Emacs 19 feature
-@defun walk-windows proc &optional minibuf all-frames
-This function cycles through all windows, calling @code{proc}
 once for each window with the window as its sole argument.
-The optional arguments @var{minibuf} and @var{all-frames} specify the
+The other arguments specify which windows to cycle through, as in
-set of windows to include in the scan.  See @code{next-window}, above,
+@code{next-window}.
-for details.
 @end defun
 @node Buffers and Windows
 @section Buffers and Windows
 @cindex examining windows
 related functions that find a window to use and specify a buffer for it.
 The functions described there are easier to use than these, but they
 employ heuristics in choosing or creating a window; use these functions
 when you need complete control.
-@defun set-window-buffer window buffer-or-name
+@defun set-window-buffer window buffer-or-name &optional norecord
 This function makes @var{window} display @var{buffer-or-name} as its
-contents.  It returns @code{nil}.
+contents.  @var{buffer-or-name} can be a buffer or a buffer name.
+With non-@code{nil} optional argument @var{norecord}, do not modify the
+global or per-frame buffer ordering.
+This function returns @code{nil}.
 @example
 @group
 (set-window-buffer (selected-window) "foo")
 @result{} nil
 @result{} #<buffer windows.texi>
 @end group
 @end example
 @end defun
-@defun get-buffer-window buffer-or-name &optional frame
+@defun get-buffer-window buffer-or-name &optional which-frames which-devices
 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}.
-The argument @var{all-frames} controls which windows to consider.
+The remaining arguments control which windows to consider.  They have
+the same meaning as for @code{next-window}.
-@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
 @end defun
 @node Displaying Buffers
 @section Displaying Buffers in Windows
 @cindex switching to a buffer
 An example use of this function is found at the end of @ref{Filter
 Functions}.
 @end defun
-@deffn Command replace-buffer-in-windows buffer
+@deffn Command replace-buffer-in-windows buffer &optional which-frames which-devices
 This function replaces @var{buffer} with some other buffer in all
 windows displaying it.  The other buffer used is chosen with
 @code{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} is no longer displayed.
+The optional arguments @var{which-frames} and @var{which-devices} have
+the same meaning as with @code{delete-windows-on}.
 This function returns @code{nil}.
 @end deffn
 @node Choosing Window
 @section Choosing a Window for Display
 This section describes the basic facility that chooses a window to
 display a buffer in---@code{display-buffer}.  All the higher-level
 functions and commands 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
+@deffn Command display-buffer buffer-or-name &optional not-this-window override-frame
 This command makes @var{buffer-or-name} appear in some window, like
 @code{pop-to-buffer}, but it does not select that window and does not
 make the buffer current.  The identity of the selected window is
 unaltered by this function.
+@var{buffer-or-name} can be a buffer or the name of one.
 If @var{not-this-window} is non-@code{nil}, it means to display the
 specified buffer in a window other than the selected one, even if it is
 already on display 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
+If @var{override-frame} is non-@code{nil}, display on that frame instead
-@var{buffer-or-name}.
+of the current frame (or the dedicated frame).
+@code{display-buffer} returns the window chosen to display @var{buffer-or-name}.
 Precisely how @code{display-buffer} finds or creates a window depends on
 the variables described below.
 @end deffn
 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.
-@defun window-point window
+@defun window-point &optional window
 This function returns the current position of point in @var{window}.
 For a non-selected window, this is the value point would have (in that
 window's buffer) if that window were selected.
 When @var{window} is the selected window and its buffer is also the
-current buffer, the value returned is the same as point in that buffer.
+current buffer, the value returned is the same as the value of point in
+that buffer.
 Strictly speaking, it would be more correct to return the
 ``top-level'' value of point, outside of any @code{save-excursion}
 forms.  But that value is hard to find.
 @end defun
 @defun window-start &optional window
 @cindex window top line
 This function returns the display-start position of window
 @var{window}.  If @var{window} is @code{nil}, the selected window is
 used.  For example,
 @example
 @group
 (window-start)
 @result{} 7058
 For a realistic example, see the description of @code{count-lines} in
 @ref{Text Lines}.
 @end defun
-@defun window-end &optional window
+@defun window-end &optional window guarantee
 This function returns the position of the end of the display in window
 @var{window}.  If @var{window} is @code{nil}, the selected window is
 used.
-Simply changing the buffer text or moving point does not update the
+Simply changing the buffer text or setting @code{window-start} does not
-value that @code{window-end} returns.  The value is updated only when
+update the value that @code{window-end} returns.  The value is updated
-Emacs redisplays and redisplay actually finishes.
+only when Emacs redisplays and redisplay actually finishes.
 If the last redisplay of @var{window} was preempted, and did not finish,
 Emacs does not know the position of the end of display in that window.
 In that case, this function returns a value that is not correct.  In a
 future version, @code{window-end} will return @code{nil} in that case.
+If optional arg @var{guarantee} is non-@code{nil}, the return value is
+guaranteed to be the same as @code{window-end} would return at the end
+of the next full redisplay assuming nothing else changes in the
+meantime.  This function is potentially much slower with this flag set.
 @ignore
 in that case, this function returns @code{nil}.  You can compute where
 the end of the window @emph{would} have been, if redisplay had finished,
 like this:
 The 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}.
-@deffn Command scroll-up &optional count
+@deffn Command scroll-up &optional lines
 This function scrolls the text in the selected window upward
-@var{count} lines.  If @var{count} is negative, scrolling is actually
+@var{lines} lines.  If @var{lines} is negative, scrolling is actually
 downward.
-If @var{count} is @code{nil} (or omitted), then the length of scroll
+If @var{lines} 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 modeline).
 @code{scroll-up} returns @code{nil}.
 @end deffn
-@deffn Command scroll-down &optional count
+@deffn Command scroll-down &optional lines
 This function scrolls the text in the selected window downward
-@var{count} lines.  If @var{count} is negative, scrolling is actually
+@var{lines} lines.  If @var{lines} is negative, scrolling is actually
 upward.
-If @var{count} is omitted or @code{nil}, then the length of the scroll
+If @var{lines} 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).
 @code{scroll-down} returns @code{nil}.
 @end deffn
-@deffn Command scroll-other-window &optional count
+@deffn Command scroll-other-window &optional lines
-This function scrolls the text in another window upward @var{count}
+This function scrolls the text in another window upward @var{lines}
-lines.  Negative values of @var{count}, or @code{nil}, are handled
+lines.  Negative values of @var{lines}, or @code{nil}, are handled
 as in @code{scroll-up}.
 You can specify a buffer to scroll with the variable
 @code{other-window-scroll-buffer}.  When the selected window is the
 minibuffer, the next window is normally the one at the top left corner.
 with an argument of @code{nil} scrolls so that this many lines at the
 bottom of the window appear instead at the top.  The default value is
 @code{2}.
 @end defopt
-@deffn Command recenter &optional count
+@deffn Command recenter &optional location window
 @cindex centering point
-This function scrolls the selected window to put the text where point
+This function scrolls @var{window} (which defaults to the selected
-is located at a specified vertical position within the window.
+window) to put the text where point is located at a specified vertical
+position within the window.
-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}
+If @var{location} is a nonnegative number, it puts the line containing
+point @var{location} lines down from the top of the window.  If @var{location}
 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
+If @var{location} 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
+If @var{location} is @code{nil}, @code{recenter} puts the line containing
 point in the middle of the window, then clears and redisplays the entire
 selected frame.
-When @code{recenter} is called interactively, @var{count} is the raw
+When @code{recenter} is called interactively, @var{location} is the raw
 prefix argument.  Thus, typing @kbd{C-u} as the prefix sets the
-@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
+@var{location} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
-@var{count} to 4, which positions the current line four lines from the
+@var{location} to 4, which positions the current line four lines from the
 top.
 With an argument of zero, @code{recenter} positions the current line at
 the top of the window.  This action is so handy that some people make a
 separate key binding to do this.  For example,
 @example
 @group
 (defun line-to-top-of-window ()
 "Scroll current line to top of window.
 Replaces three keystroke sequence C-u 0 C-l."
 (interactive)
 (recenter 0))
 (global-set-key [kp-multiply] 'line-to-top-of-window)
 @end group
 @end example
 @end deffn
 @node Horizontal Scrolling
 horizontal scrolling, you can scroll it back to the right, but only so
 far as to reduce the net horizontal scroll to zero.  There is no limit
 to how far left you can scroll, but eventually all the text will
 disappear off the left edge.
-@deffn Command scroll-left count
+@deffn Command scroll-left &optional count
 This function scrolls the selected window @var{count} columns to the
 left (or to the right if @var{count} is negative).  The return value is
 the total amount of leftward horizontal scrolling in effect after the
 change---just like the value returned by @code{window-hscroll} (below).
 @end deffn
-@deffn Command scroll-right count
+@deffn Command scroll-right &optional count
 This function scrolls the selected window @var{count} columns to the
 right (or to the left if @var{count} is negative).  The return value is
 the total amount of leftward horizontal scrolling in effect after the
 change---just like the value returned by @code{window-hscroll} (below).
 is off the screen due to horizontal scrolling:
 @example
 @group
 (defun hscroll-on-screen (window position)
 (save-excursion
 (goto-char position)
 (and
 (>= (- (current-column) (window-hscroll window)) 0)
 (< (- (current-column) (window-hscroll window))
 (window-width window)))))
 @end group
 @end example
 @defun window-displayed-text-pixel-height &optional window noclipped
 This function returns the height in pixels of the text displayed in
 @var{window}, which defaults to the selected window.  Unlike
 @code{window-text-area-pixel-height}, any blank space below the
 end of the buffer is not included.  If optional argument @var{noclipped}
 is non-@code{nil}, any space occupied by clipped lines will not be
 included.
 @end defun
 @node Position of Window
 @var{window}.  If @var{window} is @code{nil}, the selected window is
 used.
 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
+@var{window}'s frame.  The element @var{right} of the value is one more
-rightmost pixel used by @var{window} (including any left margin, right
+than the rightmost pixel used by @var{window} (including any left
-margin, or vertical scrollbar displayed alongside it), and
+margin, right margin, or vertical scrollbar displayed alongside it), and
 @var{bottom} is one more than the bottommost pixel used by @var{window}
-(including any modeline or horizontal scrollbar displayed above
+(including any modeline or horizontal scrollbar displayed above or below
-or below it).  The frame area does not include any frame menubars or
+it).  The frame area does not include any frame menubars, toolbars, or
-toolbars that may be displayed; thus, for example, if there is only
+gutters that may be displayed; thus, for example, if there is only one
-one window on the frame, the values for @var{left} and @var{top} will
+window on the frame, the values for @var{left} and @var{top} will always
-always be 0.
+be 0.
 If @var{window} is at the upper left corner of its frame, @var{right}
 and @var{bottom} are the same as the values returned by
 @code{(window-pixel-width)} and @code{(window-pixel-height)}
-respectively, and @var{top} and @var{bottom} are zero.
+respectively, and @var{left} and @var{top} are zero.
 @end defun
 There is no longer a function @code{window-edges} because it does not
 make sense in a world with variable-width and variable-height lines,
 as are allowed in XEmacs.
 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.  XEmacs does not permit overlapping windows or gaps between
 windows, so resizing one window affects other windows.
-@deffn Command enlarge-window size &optional horizontal window
+@deffn Command enlarge-window count &optional horizontal window
-This function makes the selected window @var{size} lines taller,
+This function makes the selected window @var{count} lines taller,
 stealing lines from neighboring windows.  It takes the lines from one
 window at a time until that window is used up, then takes from another.
 If a window from which lines are stolen shrinks below
 @code{window-min-height} lines, that window disappears.
 If @var{horizontal} is non-@code{nil}, this function makes
-@var{window} wider by @var{size} columns, stealing columns instead of
+@var{window} wider by @var{count} columns, 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 @var{size} is negative, this function shrinks the window by
+If @var{count} is negative, this function shrinks the window by
-@minus{}@var{size} lines or columns.  If that makes the window smaller
+@minus{}@var{count} lines or columns.  If that makes the window smaller
 than the minimum size (@code{window-min-height} and
 @code{window-min-width}), @code{enlarge-window} deletes the window.
 If @var{window} is non-@code{nil}, it specifies a window to change
 instead of the selected 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:
 @end group
 @end example
 @end deffn
 @deffn Command enlarge-window-pixels count &optional side window
-This function makes the selected window @var{count} pixels larger.  When
+This function makes the selected window @var{count} pixels larger.
-called from Lisp, optional second argument @var{side} non-@code{nil}
+When called from Lisp, optional second argument @var{side}
-means to grow sideways @var{count} pixels, and optional third argument
+non-@code{nil} means to grow sideways @var{count} pixels, and optional
-@var{window} specifies the window to change instead of the selected
+third argument @var{window} specifies the window to change instead of
-window.
+the selected window.
 @end deffn
-@deffn Command shrink-window size &optional horizontal window
+@deffn Command shrink-window count &optional horizontal window
 This function is like @code{enlarge-window} but negates the argument
-@var{size}, making the selected window smaller by giving lines (or
+@var{count}, 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}
+If @var{count} is negative, the window is enlarged by @minus{}@var{count}
 lines or columns.
 If @var{window} is non-@code{nil}, it specifies a window to change
 instead of the selected window.
 @end deffn
 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
+@defun current-window-configuration &optional frame
-This function returns a new object representing XEmacs's current window
+This function returns a new object representing the current current
-configuration, namely the number of windows, their sizes and current
+window configuration of @var{frame}, namely the number of windows, their
-buffers, which window is the selected window, and for each window the
+sizes and current buffers, which window is the selected window, and for
-displayed buffer, the display-start position, and the positions of point
+each window the displayed buffer, the display-start position, and the
-and the mark.  An exception is made for point in the current buffer,
+positions of point and the mark.  An exception is made for point in the
-whose value is not saved.
+current buffer, whose value is not saved.
+@var{frame} defaults to the selected frame.
 @end defun
 @defun set-window-configuration configuration
 This function restores the configuration of XEmacs's windows and
 buffers to the state specified by @var{configuration}.  The argument

Mercurial > hg > xemacs-beta

comparison man/lispref/windows.texi @ 444:576fb035e263 r21-2-37