@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@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
the buffer it displays
@item
-position within the buffer at the upper left of the window
+buffer position at the upper left corner of the window
@item
amount of horizontal scrolling, in columns
This function splits the selected window into two windows, one above the
other, leaving the upper of the two windows selected, with @var{size}
lines. (If @var{size} is negative, then the lower of the two windows
-gets @minus{} @var{size} lines and the upper window gets the rest, but
+gets @minus{}@var{size} lines and the upper window gets the rest, but
the upper window is still the one selected.) However, if
@code{split-window-keep-point} (see below) is @code{nil}, then either
window can be selected.
slow terminals.) It selects whichever window contains the screen line
that point was previously on.
-This variable only affects the behavior of @code{split-window-vertically}.
-It has no effect on the other functions described here.
+This variable affects the behavior of @code{split-window-vertically}
+only. It has no effect on the other functions described here.
@end defopt
@deffn Command split-window-horizontally &optional size
This function splits the selected window into two windows
side-by-side, leaving the selected window on the left with @var{size}
columns. If @var{size} is negative, the rightmost window gets
-@minus{} @var{size} columns, but the leftmost window still remains
+@minus{}@var{size} columns, but the leftmost window still remains
selected.
This function is basically an interface to @code{split-window}.
@group
(let ((size (and arg (prefix-numeric-value arg))))
(and size (< size 0)
- (setq size (+ (window-width) size)))
+ (setq size (+ (window-width) size)))
(split-window nil size t)))
@end group
@end smallexample
space. If all windows in some frame are showing @var{buffer-or-name}
(including the case where there is only one window), then the frame
winds up with a single window showing another buffer chosen with
-@code{other-buffer}. @xref{The Buffer List}.
+@code{other-buffer}. @xref{The Buffer List}. If, however, that window
+is dedicated and there are other frames left, the window's frame is
+deleted.
-The argument @var{frame} controls which frames to operate on. This
+The argument @var{frame} specifies which frames to operate on. This
function does not use it in quite the same way as the other functions
which scan all windows; specifically, the values @code{t} and @code{nil}
have the opposite of their meanings in other functions. Here are the
@var{dedicated} argument is non-@code{nil}, so if all
existing windows are dedicated, the value is @code{nil}.
-The argument @var{frame} controls which windows are considered.
+The argument @var{frame} specifies which windows are considered.
@itemize @bullet
@item
prefers the one that comes first in the cyclic ordering of windows
(see following section), starting from the selected window.
-The argument @var{frame} controls which set of windows to
+The argument @var{frame} specifies which set of windows to
consider. See @code{get-lru-window}, above.
@end defun
window visible, then this function returns @var{window}. If omitted,
@var{window} defaults to the selected window.
-The value of the argument @var{minibuf} determines whether the
+The value of the argument @var{minibuf} specifies whether the
minibuffer is included in the window order. Normally, when
@var{minibuf} is @code{nil}, the minibuffer is included if it is
currently active; this is the behavior of @kbd{C-x o}. (The minibuffer
@code{window-list} uses the selected frame instead; if @var{window} is
@code{nil} or omitted, it uses the selected window.
-The value of @var{minibuf} determines if the minibuffer window is
+The value of @var{minibuf} specifies if the minibuffer window is
included in the result list. If @var{minibuf} is @code{t}, the result
always includes the minibuffer window. If @var{minibuf} is @code{nil}
or omitted, that includes the minibuffer window if it is active. If
cyclic ordering of windows, starting from the selected window.
@xref{Cyclic Window Ordering}.
-The argument @var{all-frames} controls which windows to consider.
+The argument @var{all-frames} specifies which windows to consider.
@itemize @bullet
@item
@ifnottex
@xref{Buffers and Windows}, for
@end ifnottex
-low-level functions that give you more precise control. All of these
+low-level primitives that give you more precise control. All of these
functions work by calling @code{set-window-buffer}.
Do not use the functions in this section in order to make a buffer
@end defun
@deffn Command replace-buffer-in-windows buffer-or-name
-This function replaces @var{buffer-or-name} with some other buffer in all
-windows displaying it. It chooses the other buffer with
-@code{other-buffer}. In the usual applications of this function, you
+This function replaces @var{buffer-or-name} in all windows displaying
+it with some other buffer. It uses @code{other-buffer} to choose the
+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-or-name} is no longer displayed.
+If the window displaying @var{buffer-or-name} is dedicated, and
+is not the only window on its frame, that window is deleted. If that
+window is the only window on its frame and there are other frames left,
+the window's frame is deleted as well. If there are no other frames left,
+some other buffer is displayed in that window.
+
This function returns @code{nil}.
@end deffn
the variables described below.
@end deffn
+@defvar split-window-preferred-function
+This variable specifies how to split a window. Its value, if
+non-@code{nil}, should be a function of one argument, which is a
+window. If this variable specifies a function, @code{display-buffer}
+will call it with one or more candidate windows when it looks for a
+window to split. If the argument window fits, the function is
+expected to split it and return a new window. If the function returns
+@code{nil}, then this window will not be split.
+
+If the value of this variable is @code{nil}, @code{display-buffer}
+uses the other variables described below to decide whether and which
+window to split.
+@end defvar
+
@defopt display-buffer-reuse-frames
If this variable is non-@code{nil}, @code{display-buffer} searches
existing frames for a window displaying the buffer. If the buffer is
@end defopt
@defopt pop-up-windows
-This variable controls whether @code{display-buffer} makes new windows.
+This variable specifies whether @code{display-buffer} makes new windows.
If it is non-@code{nil} and there is only one window, then that window
-is split. If it is @code{nil}, then @code{display-buffer} does not
-split the single window, but uses it whole.
+is split vertically. If it is @code{nil}, then @code{display-buffer}
+does not split the single window, but uses it whole.
@end defopt
@defopt split-height-threshold
-This variable determines when @code{display-buffer} may split a window,
-if there are multiple windows. @code{display-buffer} always splits the
-largest window if it has at least this many lines. If the largest
-window is not this tall, it is split only if it is the sole window and
-@code{pop-up-windows} is non-@code{nil}.
+This variable specifies when @code{display-buffer} may split a window
+vertically, if there are multiple windows. If the value is a number,
+@code{display-buffer} splits the largest window if it has at least
+this many lines. If the largest window is not this tall, or if the
+value of this variable is @code{nil}, @code{display-buffer} tries to
+split some window horizontally, subject to restrictions of
+@code{split-width-threshold} (see below). If splitting horizontally
+is impossible, @code{display-buffer} splits a window vertically
+only if it's the only window on its frame and not the minibuffer
+window, and only if @code{pop-up-windows} is non-@code{nil}.
+Otherwise, @code{display-buffer} uses one of the existing windows.
+@end defopt
+
+@defopt split-width-threshold
+This variable specifies when @code{display-buffer} may split a window
+horizontally. If the value is a number, @code{display-buffer} may
+split a window if it has at least this many columns. If the value of
+this variable is @code{nil}, @code{display-buffer} will not split any
+windows horizontally. (It still might split some window vertically,
+though, see above.)
@end defopt
@defopt even-window-heights
-This variable determines if @code{display-buffer} should even out window
-heights if the buffer gets displayed in an existing window, above or
-beneath another existing window. If @code{even-window-heights} is
-@code{t}, the default, window heights will be evened out. If
-@code{even-window-heights} is @code{nil}, the original window heights
-will be left alone.
+This variable specifies whether @code{display-buffer} should even out
+window heights if the buffer gets displayed in an existing window,
+above or beneath another existing window. If
+@code{even-window-heights} is @code{t}, the default, window heights
+will be evened out. If @code{even-window-heights} is @code{nil}, the
+original window heights will be left alone.
@end defopt
@c Emacs 19 feature
@defopt pop-up-frames
-This variable controls whether @code{display-buffer} makes new frames.
+This variable specifies whether @code{display-buffer} makes new frames.
If it is non-@code{nil}, @code{display-buffer} looks for an existing
-window already displaying the desired buffer, on any visible frame. If
-it finds one, it returns that window. Otherwise it makes a new frame.
-The variables @code{pop-up-windows} and @code{split-height-threshold} do
-not matter if @code{pop-up-frames} is non-@code{nil}.
+window already displaying the desired buffer, on any visible frame.
+If it finds one, it returns that window. Otherwise it makes a new
+frame, unless the variable's value is @code{graphic-only} and the
+selected frame is not on a graphic display. The variables
+@code{pop-up-windows}, @code{split-height-threshold}, and
+@code{split-width-threshold} do not matter if @code{pop-up-frames} is
+non-@code{nil}.
If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
splits a window or reuses one.
@c Emacs 19 feature
@cindex dedicated window
-A window can be marked as ``dedicated'' to its buffer. Then
+A window can be marked as @dfn{dedicated} to its buffer. Then
@code{display-buffer} will not try to use that window to display any
-other buffer.
-
-@defun window-dedicated-p window
+other buffer. @code{set-window-buffer} will signal an error when asked
+to display another buffer in it. Both @code{get-lru-window} and
+@code{get-largest-window} do not consider dedicated windows as
+candidates when their @var{dedicated} argument is non-@code{nil}.
+
+When @code{delete-windows-on} deletes a dedicated window and that window
+is the only window on its frame, it will delete that frame as well if
+there are other frames left. @code{replace-buffer-in-windows} deletes
+any dedicated window showing its buffer argument. When such a window is
+the only window on its frame, that frame is deleted if there are other
+frames left.
+
+@defun window-dedicated-p &optional window
This function returns non-@code{nil} if @var{window} is marked as
dedicated; otherwise @code{nil}.
@end defun
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
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
-lines. If a window from which columns are stolen shrinks below
+If @var{horizontal} is non-@code{nil}, this function makes the window
+@var{size} columns wider, 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
size of a fixed-size window, @code{enlarge-window} gets an error
instead.
-If @var{size} is negative, this function shrinks the window by
+If @var{size} is negative, this function shrinks the selected window by
@minus{}@var{size} 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.
functions to a minimum height and width.
@defopt window-min-height
-The value of this variable determines how short a window may become
+The value of this variable specifies 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 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.
+@code{window-min-height} automatically deletes it, and no window may be
+created shorter than this. The value is measured in line units. When
+the window wants a mode- and/or header-line, they are counted as one
+line each. The default value of this variable is 4. A value less than
+1 is ignored.
@end defopt
@defopt window-min-width
-The value of this variable determines how narrow a window may become
+The value of this variable specifies 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 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.
+created narrower than this. The value is measured in characters and
+includes any fringes or the scroll bar. The default value is 10. A
+value less than 2 is ignored.
@end defopt
@node Coordinates and Windows
HCoop / bpt / emacs.git / blobdiff