@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, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/windows
@node Windows, Frames, Buffers, Top
@chapter Windows
This chapter describes most of the functions and variables related to
-Emacs windows. See @ref{Display}, for information on how text is
-displayed in windows.
+Emacs windows. @xref{Frames and Windows}, for how windows relate to
+frames. @xref{Display}, for information on how text is displayed in
+windows.
@menu
* Basic Windows:: Basic information on using windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
* Displaying Buffers:: Higher-level functions for displaying a buffer
and choosing a window for it.
-* Choosing Window:: How to choose a window for displaying a buffer.
+* Choosing Window:: How to choose a window for displaying a buffer.
+* Dedicated Windows:: How to avoid displaying another buffer in
+ a specific window.
* 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.
+* Window Start and End:: Buffer positions indicating which text is
+ on-screen in a window.
* Textual Scrolling:: Moving text up and down through the window.
* Vertical Scrolling:: Moving the contents up and down on the window.
* Horizontal Scrolling:: Moving the contents sideways on the window.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Tree:: The layout and sizes of all windows in a frame.
* Window Configurations:: Saving and restoring the state of the screen.
+* Window Parameters:: Associating additional information with windows.
* Window Hooks:: Hooks for scrolling, window size changes,
redisplay going past a certain point,
or window configuration changes.
represents that screen area in Emacs Lisp. It should be
clear from the context which is meant.
- Emacs groups windows into frames. A frame represents an area of
-screen available for Emacs to use. Each frame always contains at least
-one window, but you can subdivide it vertically or horizontally into
-multiple nonoverlapping Emacs windows.
+ Emacs groups windows into frames; see @ref{Frames}. A frame
+represents an area of screen available for Emacs to use. Each frame
+always contains at least one window, but you can subdivide it
+vertically or horizontally into multiple, nonoverlapping Emacs
+windows.
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. (@pxref{Cursor Parameters}, for customization of this.)
-At any time, one frame is the selected frame; and the window selected
+less visible. (@xref{Cursor Parameters}, for customizing 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}.
+buffer is usually the current buffer (except when @code{set-buffer} has
+been used); see @ref{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
and should not be used, @emph{even though there may still be references
-to it} from other Lisp objects. Restoring a saved window configuration
-is the only way for a window no longer on the screen to come back to
-life. (@xref{Deleting Windows}.)
-
- Each window has the following attributes:
-
-@itemize @bullet
-@item
-containing frame
-
-@item
-window height
-
-@item
-window width
-
-@item
-window edges with respect to the screen or frame
-
-@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
-
-@item
-fringe settings
-
-@item
-display margins
-
-@item
-scroll-bar settings
-@end itemize
+to it} from other Lisp objects; see @ref{Deleting Windows}. Restoring a
+saved window configuration is the only way for a window no longer on the
+screen to come back to life; see @ref{Window Configurations}.
@cindex multiple windows
Users create multiple windows so they can look at several buffers at
Most window systems support arbitrarily located overlapping windows.
In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
together they fill the whole screen or frame. Because of the way in
-which Emacs creates new windows and resizes them, not all conceivable
-tilings of windows on an Emacs frame are actually possible.
-@xref{Splitting Windows}, and @ref{Size of Window}.
-
- @xref{Display}, for information on how the contents of the
-window's buffer are displayed in the window.
+which Emacs creates new windows (@pxref{Splitting Windows}) and resizes
+them (@pxref{Resizing Windows}), not all conceivable tilings of windows
+on an Emacs frame are actually possible.
@defun windowp object
This function returns @code{t} if @var{object} is a window.
@cindex splitting windows
@cindex window splitting
- The functions described here are the primitives used to split a window
-into two windows. Two higher level functions sometimes split a window,
-but not always: @code{pop-to-buffer} and @code{display-buffer}
-(@pxref{Displaying Buffers}).
-
- The functions described here do not accept a buffer as an argument.
-The two ``halves'' of the split window initially display the same buffer
+The functions described below are the primitives used to split a window
+into two windows. They do not accept a buffer as an argument. Rather,
+the two ``halves'' of the split window initially display the same buffer
previously visible in the window that was split.
@deffn Command split-window &optional window size horizontal
-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
-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
-@var{window} keeps the upper @var{size} lines and gives the rest of the
-lines to the new window. The original window is therefore 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}, that stands for the selected
+This function splits a new window out of @var{window}'s screen area. It
+returns the new window. The default for @var{window} is the selected
window. When you split the selected window, it remains selected.
+If @var{horizontal} is non-@code{nil}, then @var{window} splits into two
+side by side windows. The original window keeps the leftmost @var{size}
+columns, and gives the rest of the columns to the new window.
+Otherwise, @var{window} splits into windows one above the other, the
+original window keeps the upper @var{size} lines and gives the rest of
+the lines to the new window. The original window @var{window} is
+therefore the left-hand or upper of the two, and the new window is the
+right-hand or lower.
+
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
-signals an error and does not split the window at all.
+@code{window-min-height} or @code{window-min-width} (@pxref{Resizing
+Windows}), @code{split-window} 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.
@end smallexample
Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar (@pxref{Layout Parameters,Scroll Bars}) or @samp{|}
-characters. The display table can specify alternative border
-characters; see @ref{Display Tables}.
+with a scroll bar (@pxref{Scroll Bars}), or with @samp{|} characters. The
+display table can specify alternative border characters; see @ref{Display
+Tables}.
@end deffn
@deffn Command split-window-vertically &optional size
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
(@pxref{Window Configurations}). Restoring a window configuration also
deletes any windows that aren't part of that configuration.
- When you delete a window, the space it took up is given to one
-adjacent sibling.
+ When you delete a window, the space it took up is given to one of
+its sibling windows adjacent to it.
@c Emacs 19 feature
@defun window-live-p window
@end defun
@deffn Command delete-window &optional window
-This function removes @var{window} from display, and returns @code{nil}.
-If @var{window} is omitted, then the selected window is deleted. An
-error is signaled if there is only one window when @code{delete-window}
-is called.
+This function removes @var{window} from display and returns @code{nil}.
+The default for @var{window} is the selected window. An error is
+signaled if @var{window} is the only window on its frame.
@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 return value is @code{nil}.
+deleting the other windows in that frame. The default for @var{window}
+is the selected window. The return value is @code{nil}.
@end deffn
-@deffn Command delete-windows-on buffer-or-name &optional frame
+@deffn Command delete-windows-on &optional buffer-or-name frame
This function deletes all windows showing @var{buffer-or-name}. If
-there are no windows showing @var{buffer-or-name}, it does nothing.
-@var{buffer-or-name} must be a buffer or the name of an existing
-buffer.
+there are no windows showing @var{buffer-or-name}, it does nothing. The
+optional argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
@code{delete-windows-on} operates frame by frame. If a frame has
several windows showing different buffers, then those showing
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} (@pxref{The Buffer List}). If, however, the window
+showing @var{buffer-or-name} is dedicated to its buffer
+(@pxref{Dedicated Windows}), and there are other frames left, that
+window's frame is deleted.
-The argument @var{frame} controls 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
-full details:
+The optional 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 full details:
@itemize @bullet
@item
@defun select-window window &optional norecord
This function makes @var{window} the selected window. The cursor then
-appears in @var{window} (on redisplay). Unless @var{window} was
+appears in @var{window} (after redisplay). Unless @var{window} was
already selected, @code{select-window} makes @var{window}'s buffer the
-current buffer.
+current buffer. The return value is @var{window}.
-Normally @var{window}'s selected buffer is moved to the front of the
-buffer list, but if @var{norecord} is non-@code{nil}, the buffer list
-order is unchanged.
+Normally, @var{window}'s selected buffer is moved to the front of the
+buffer list (@pxref{The Buffer List}) and @var{window} becomes the most
+recently selected window. But if @var{norecord} is non-@code{nil}, the
+buffer list remains unchanged and @var{window} does not become the most
+recently selected one.
-The return value is @var{window}.
@example
@group
current buffer. It returns the value of the last form in @var{forms}.
This macro does not save or restore anything about the sizes,
-arrangement or contents of windows; therefore, if the @var{forms}
-change them, the change persists. If the previously selected window
-of some frame is no longer live at the time of exit from @var{forms},
-that frame's selected window is left alone. If the previously
-selected window is no longer live, then whatever window is selected at
-the end of @var{forms} remains selected.
+arrangement or contents of windows; therefore, if @var{forms} change
+them, the change persists. If the previously selected window of some
+frame is no longer live at the time of exit from @var{forms}, that
+frame's selected window is left alone. If the previously selected
+window is no longer live, then whatever window is selected at the end of
+@var{forms} remains selected. The current buffer is restored if and
+only if it is still live when exiting @var{forms}.
+
+This macro changes neither the ordering of recently selected windows nor
+the buffer list.
@end defmac
@defmac with-selected-window window forms@dots{}
-This macro selects @var{window} (without changing the buffer list),
-executes @var{forms} in sequence, then restores the previously
-selected window and current buffer. It is just like
-@code{save-selected-window}, except that it explicitly selects
-@var{window}, also without altering the buffer list sequence.
+This macro selects @var{window}, executes @var{forms} in sequence, then
+restores the previously selected window and current buffer. The ordering
+of recently selected windows and the buffer list remain unchanged unless
+you deliberately change them within @var{forms}, for example, by calling
+@code{select-window} with argument @var{norecord} @code{nil}.
@end defmac
@cindex finding windows
@defun get-lru-window &optional frame dedicated
This function returns the window least recently ``used'' (that is,
-selected). If any full-width windows are present, it only considers
-these. The selected window is always the most recently used window.
+selected) among a set of candidate windows. If any full-width windows
+are present, it only considers these.
-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. Dedicated windows are never candidates unless the
-@var{dedicated} argument is non-@code{nil}, so if all
-existing windows are dedicated, the value is @code{nil}.
+The selected window is returned if it is the only candidate. A
+minibuffer window is never a candidate. A dedicated window
+(@pxref{Dedicated Windows}) is never a candidate unless the optional
+argument @var{dedicated} is non-@code{nil}.
-The argument @var{frame} controls which windows are considered.
+The optional argument @var{frame} specifies which windows are
+considered.
@itemize @bullet
@item
@defun get-largest-window &optional frame dedicated
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.
-Dedicated windows are never candidates unless the
-@var{dedicated} argument is non-@code{nil}, so if all existing windows
-are dedicated, the value is @code{nil}.
+with the most lines. A minibuffer window is never a candidate. A
+dedicated window (@pxref{Dedicated Windows}) is never a candidate unless
+the optional argument @var{dedicated} is non-@code{nil}.
If there are two candidate windows of the same size, this function
-prefers the one that comes first in the cyclic ordering of windows
-(see following section), starting from the selected window.
+prefers the one that comes first in the cyclic ordering of windows,
+starting from the selected window (@pxref{Cyclic Window Ordering}).
-The argument @var{frame} controls which set of windows to
-consider. See @code{get-lru-window}, above.
+The optional argument @var{frame} specifies which set of windows to
+consider, see @code{get-lru-window} above.
@end defun
@cindex window that satisfies a predicate
@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 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}.
+Window Ordering}), calling @var{predicate} on each 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} (which defaults to @code{nil}).
The optional arguments @var{minibuf} and @var{all-frames} specify the
set of windows to include in the scan. See the description of
@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}.
+some other window, it moves through the windows on the screen in a
+specific order. For any given configuration of windows, this order
+never varies. It is called the @dfn{cyclic ordering of windows}.
- This ordering generally goes from top to bottom, and from left to
-right. But it may go down first or go right first, depending on the
-order in which the windows were split.
+ For a particular frame, this ordering generally goes from top to
+bottom, and from left to right. But it may go down first or go right
+first, depending on the order in which windows were split.
If the first split was vertical (into windows one above each other),
and then the subwindows were split horizontally, then the ordering is
left to right in the top of the frame, and then left to right in the
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.
+In general, within each set of siblings at any level in the window tree
+(@pxref{Window Tree}), the order is left to right, or top to bottom.
@defun next-window &optional window minibuf all-frames
@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
-window visible, then this function returns @var{window}. If omitted,
-@var{window} defaults to the selected window.
+ordering of windows. This is the window @kbd{C-x o} selects if typed
+when @var{window} is selected. The default for @var{window} is the
+selected window.
-The value of the argument @var{minibuf} determines whether the
+The value of the optional 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
-window is active while the minibuffer is in use. @xref{Minibuffers}.)
+@var{minibuf} is @code{nil}, the minibuffer is included only if it is
+currently ``active''; this matches the behavior of @kbd{C-x o}. (The
+minibuffer window is active while the minibuffer is in use; see
+@ref{Minibuffers}.)
-If @var{minibuf} is @code{t}, then the cyclic ordering includes the
-minibuffer window even if it is not active.
+If @var{minibuf} is @code{t}, the cyclic ordering includes the
+minibuffer window even if it is not active. If @var{minibuf} is neither
+@code{t} nor @code{nil}, the minibuffer window is not included even if
+it is 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
-are the possible values and their meanings:
+The optional argument @var{all-frames} specifies which frames to
+consider. Here are the possible values and their meanings:
@table @asis
@item @code{nil}
@end defun
@deffn Command other-window count &optional all-frames
-This function selects the @var{count}th following window in the cyclic
-order. If count is negative, then it moves back @minus{}@var{count}
-windows in the cycle, rather than forward. It returns @code{nil}.
-
-The argument @var{all-frames} has the same meaning as in
+This function selects another window in the cyclic ordering of windows.
+@var{count} specifies the number of windows to skip in the ordering,
+starting with the selected window, before making the selection. If
+@var{count} is a positive number, it skips @var{count} windows forwards.
+@var{count} negative means skip @minus{}@var{count} windows backwards.
+If @var{count} is zero, it does not skip any window, thus re-selecting
+the selected window. In an interactive call, @var{count} is the numeric
+prefix argument.
+
+The optional argument @var{all-frames} has the same meaning as in
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
-is always effectively @code{nil}.
-
-In an interactive call, @var{count} is the numeric prefix argument.
+is always effectively @code{nil}. This function returns @code{nil}.
@end deffn
@c Emacs 19 feature
argument.
The optional arguments @var{minibuf} and @var{all-frames} specify the
-set of windows to include in the scan. See @code{next-window}, above,
+set of windows to include in the walk. See @code{next-window}, above,
for details.
@end defun
@defun window-list &optional frame minibuf window
-This function returns a list of the windows on @var{frame}, starting
-with @var{window}. If @var{frame} is @code{nil} or omitted,
-@code{window-list} uses the selected frame instead; if @var{window} is
-@code{nil} or omitted, it uses the selected window.
+This function returns a list of all windows on @var{frame}, starting
+with @var{window}. The default for @var{frame} is the selected frame;
+the default for @var{window} is the selected window.
-The value of @var{minibuf} determines if the minibuffer window is
+The value of @var{minibuf} specifies if the minibuffer window shall be
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
@xref{Displaying Buffers}, for
@end ifnottex
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.
+The functions described there are easier to use, but they employ
+heuristics in choosing or creating a window; use the functions described
+here when you need complete control.
@defun set-window-buffer window buffer-or-name &optional keep-margins
This function makes @var{window} display @var{buffer-or-name} as its
-contents. It returns @code{nil}. @var{buffer-or-name} must be a
-buffer, or the name of an existing buffer. This is the fundamental
-primitive for changing which buffer is displayed in a window, and all
-ways of doing that call this function.
+contents. It returns @code{nil}. The default for @var{window} is the
+selected window. The argument @var{buffer-or-name} must specify a
+buffer or the name of an existing buffer.
+
+@code{set-window-buffer} is the fundamental primitive for changing which
+buffer is displayed in a window, and all ways of doing that call this
+function.
@example
@group
@end group
@end example
-Normally, displaying @var{buffer} in @var{window} resets the window's
-display margins, fringe widths, scroll bar settings, and position
-based on the local variables of @var{buffer}. However, if
-@var{keep-margins} is non-@code{nil}, the display margins and fringe
-widths of @var{window} remain unchanged. @xref{Fringes}.
+Normally, displaying @var{buffer-or-name} in @var{window} resets the
+window's position, display margins, fringe widths, and scroll bar
+settings based on the local variables of that buffer.
+However, if @var{keep-margins} is non-@code{nil}, display margins and
+fringe widths of @var{window} remain unchanged. @xref{Fringes}.
+
+@code{set-window-buffer} signals an error when @var{window} is
+@dfn{strongly} dedicated to its buffer (@pxref{Dedicated Windows}) and
+does not already display @var{buffer-or-name}.
+
+Note that this function runs @code{window-scroll-functions} before
+running @code{window-configuration-change-hook}.
@end defun
@defvar buffer-display-count
-This buffer-local variable records the number of times a buffer is
+This buffer-local variable records the number of times a buffer has been
displayed in a window. It is incremented each time
@code{set-window-buffer} is called for the buffer.
@end defvar
@defun window-buffer &optional window
-This function returns the buffer that @var{window} is displaying. If
-@var{window} is omitted, this function returns the buffer for the
-selected window.
+This function returns the buffer that @var{window} is displaying. The
+default for @var{window} is the selected window.
@example
@group
@end example
@end defun
-@defun get-buffer-window buffer-or-name &optional all-frames
+@defun get-buffer-window &optional buffer-or-name all-frames
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 argument @var{BUFFER-OR-NAME} may be a buffer or a buffer name and
+defaults to the current buffer. The optional argument @var{all-frames}
+specifies which windows to consider:
@itemize @bullet
@item
-If it is @code{nil}, consider windows on the selected frame.
+@code{nil} means consider windows on the selected frame.
@item
-If it is @code{t}, consider windows on all frames.
+@code{t} means consider windows on all existing frames.
@item
-If it is @code{visible}, consider windows on all visible frames.
+@code{visible} means consider windows on all visible frames.
@item
-If it is 0, consider windows on all visible or iconified frames.
+0 means consider windows on all visible or iconified frames.
@item
-If it is a frame, consider windows on that frame.
+A frame means consider windows on that frame only.
@end itemize
+
+Observe that the behavior of @code{get-buffer-window} may differ from
+that of @code{next-window} (@pxref{Cyclic Window Ordering}) when
+@var{all-frames} equals @code{nil} or any value not listed here.
+Perhaps we will change @code{get-buffer-window} in the future to make it
+compatible with the other functions.
@end defun
-@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames
-This function returns a list of all the windows currently displaying
-@var{buffer-or-name}.
+@defun get-buffer-window-list &optional buffer-or-name minibuf all-frames
+This function returns a list of all windows currently displaying
+@var{buffer-or-name}. The argument @var{buffer-or-name} may be a buffer
+or the name of an existing buffer and defaults to the current buffer.
-The two optional arguments work like the optional arguments of
-@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not}
-like the single optional argument of @code{get-buffer-window}. Perhaps
-we should change @code{get-buffer-window} in the future to make it
-compatible with the other functions.
+The two remaining arguments work like the same-named arguments of
+@code{next-window}; they are @emph{not} like the optional arguments of
+@code{get-buffer-window}.
@end defun
@defvar buffer-display-time
@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
displays the buffer in the selected window. This means that a human can
see the buffer and subsequent keyboard commands will apply to it.
Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
-the current buffer but does not display it in the selected window.
-@xref{Current Buffer}.
-
-If @var{buffer-or-name} does not identify an existing buffer, then a new
-buffer by that name is created. The major mode for the new buffer is
-set according to the variable @code{default-major-mode}. @xref{Auto
-Major Mode}. If @var{buffer-or-name} is @code{nil},
-@code{switch-to-buffer} chooses a buffer using @code{other-buffer}.
+the current buffer but does not display it in the selected window;
+see @ref{Current Buffer}.
+
+If @var{buffer-or-name} is @code{nil}, @code{switch-to-buffer} chooses a
+buffer using @code{other-buffer}. If @var{buffer-or-name} is a string
+that does not identify an existing buffer, then a new buffer by that
+name is created. The major mode for the new buffer is set according to
+the variable @code{major-mode}; see @ref{Auto Major Mode}.
+
+When the selected window is the minibuffer window or is strongly
+dedicated to its buffer (@pxref{Dedicated Windows}), this function calls
+@code{pop-to-buffer} (see below) to display the buffer in some other
+window.
Normally the specified buffer is put at the front of the buffer list
(both the selected frame's buffer list and the frame-independent buffer
for the described features.
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
-This function makes @var{buffer-or-name} the current buffer and
-displays it in a window not currently selected. It then selects that
-window. The handling of the buffer is the same as in
-@code{switch-to-buffer}.
+This function makes the buffer specified by @var{buffer-or-name} current
+and displays it in a window not currently selected, using the function
+@code{pop-to-buffer} (see below).
The currently selected window is absolutely never used to do the job.
-If it is the only window, then it is split to make a distinct window for
-this purpose. If the selected window is already displaying the buffer,
-then it continues to do so, but another window is nonetheless found to
-display it in as well.
+If the selected window already displays @var{buffer-or-name}, then it
+continues to do so, but another window is nonetheless found to display
+it in as well.
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
@end deffn
-@defun pop-to-buffer buffer-or-name &optional other-window 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. The return value is the buffer that was switched to.
-If @var{buffer-or-name} is @code{nil}, that means to choose some
-other buffer, but you don't specify which.
-
-If the variable @code{pop-up-frames} is non-@code{nil},
-@code{pop-to-buffer} looks for a window in any visible frame already
-displaying the buffer; if there is one, it returns that window and makes
-it be selected within its frame. If there is none, it creates a new
-frame and displays the buffer in it.
-
-If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer}
-operates entirely within the selected frame. (If the selected frame has
-just a minibuffer, @code{pop-to-buffer} operates within the most
-recently selected frame that was not just a minibuffer.)
-
-If the variable @code{pop-up-windows} is non-@code{nil}, windows may
-be split to create a new window that is different from the original
-window. For details, see @ref{Choosing Window}.
+@deffn Command pop-to-buffer buffer-or-name &optional other-window norecord
+This command 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. Its frame is
+given the X server's focus, if possible; see @ref{Input Focus}. The
+return value is the buffer that was switched to.
+
+If @var{buffer-or-name} is @code{nil}, that means to choose some other
+buffer, but you don't specify which. If @var{buffer-or-name} is a
+string that does not name an existing buffer, a buffer by that name is
+created. The major mode for the new buffer is set according to the
+variable @code{major-mode}. @xref{Auto Major Mode}.
+
+If either of the variables @code{display-buffer-reuse-frames} or
+@code{pop-up-frames} is non-@code{nil}, @code{pop-to-buffer} looks for a
+window in any visible frame already displaying the buffer; if there is
+one, it selects and returns that window. If no such window exists and
+@code{pop-up-frames} is non-@code{nil}, it creates a new frame and
+displays the buffer in it. Otherwise, @code{pop-to-buffer} operates
+entirely within the selected frame. (If the selected frame has just a
+minibuffer, @code{pop-to-buffer} operates within the most recently
+selected frame that was not just a minibuffer.)
+
+If the variable @code{pop-up-windows} is non-@code{nil}, windows may be
+split to create a new window that is different from the original window.
+For details, see @ref{Choosing Window}.
If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or
creates another window even if @var{buffer-or-name} is already visible
in the selected window. Thus @var{buffer-or-name} could end up
displayed in two windows. On the other hand, if @var{buffer-or-name} is
already displayed in the selected window and @var{other-window} is
-@code{nil}, then the selected window is considered sufficient display
-for @var{buffer-or-name}, so that nothing needs to be done.
+@code{nil}, then the selected window is considered sufficient for
+displaying @var{buffer-or-name}, so that nothing needs to be done.
All the variables that affect @code{display-buffer} affect
@code{pop-to-buffer} as well. @xref{Choosing Window}.
-If @var{buffer-or-name} is a string that does not name an existing
-buffer, a buffer by that name is created. The major mode for the new
-buffer is set according to the variable @code{default-major-mode}.
-@xref{Auto Major Mode}.
-
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
-@end defun
+@end deffn
-@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
+@deffn Command replace-buffer-in-windows &optional buffer-or-name
+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.
+The argument @var{buffer-or-name} may be a buffer or the name of an
+existing buffer and defaults to the current buffer.
+
+If a window displaying @var{buffer-or-name} is dedicated
+(@pxref{Dedicated Windows}), 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 too. If
+there are no other frames left, some other buffer is displayed in that
+window.
+
This function returns @code{nil}.
@end deffn
@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.
+display a buffer in---@code{display-buffer}. Higher-level functions and
+commands, like @code{switch-to-buffer} and @code{pop-to-buffer}, 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 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} must be a buffer, or
-the name of an existing buffer.
-
-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.
+This command makes @var{buffer-or-name} appear in some window, but it
+does not select that window and does not make the buffer specified by
+@var{buffer-or-name} current. The identity of the selected window is
+unaltered by this function. The argument @var{buffer-or-name} must be a
+buffer or the name of an existing buffer.
+
+@var{not-this-window} non-@code{nil} means to display the specified
+buffer in a window other than the selected one, even if it is already
+displayed 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
@var{buffer-or-name}.
-If the argument @var{frame} is non-@code{nil}, it specifies which frames
-to check when deciding whether the buffer is already displayed. If the
-buffer is already displayed in some window on one of these frames,
-@code{display-buffer} simply returns that window. Here are the possible
-values of @var{frame}:
+If the optional argument @var{frame} is non-@code{nil}, it specifies
+which frames to check when deciding whether the buffer is already
+displayed. If the buffer is already displayed in some window on one of
+these frames, @code{display-buffer} simply returns that window. Here
+are the possible values of @var{frame}:
@itemize @bullet
@item
-If it is @code{nil}, consider windows on the selected frame.
+@code{nil} means consider windows on the selected frame.
(Actually, the last non-minibuffer frame.)
@item
-If it is @code{t}, consider windows on all frames.
+@code{t} means consider windows on all frames.
@item
-If it is @code{visible}, consider windows on all visible frames.
+@code{visible} means consider windows on all visible frames.
@item
-If it is 0, consider windows on all visible or iconified frames.
+0 means consider windows on all visible or iconified frames.
@item
-If it is a frame, consider windows on that frame.
+A frame means consider windows on that frame only.
@end itemize
Precisely how @code{display-buffer} finds or creates a window depends on
@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
-already displayed in a window in some frame, @code{display-buffer} makes
-the frame visible and raises it, to use that window. If the buffer is
-not already displayed, or if @code{display-buffer-reuse-frames} is
-@code{nil}, @code{display-buffer}'s behavior is determined by other
-variables, described below.
+visible and iconified frames for a window displaying
+@var{buffer-or-name}. If there is such a window, @code{display-buffer}
+makes that window's frame visible and raises it if necessary, and
+returns the window. If there is no such window or
+@code{display-buffer-reuse-frames} is @code{nil}, the behavior of
+@code{display-buffer} is determined by the variables described next.
@end defopt
@defopt pop-up-windows
-This variable controls 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.
+This variable specifies whether @code{display-buffer} is allowed to
+split (@pxref{Splitting Windows}) an existing window. If this variable
+is non-@code{nil}, @code{display-buffer} tries to split the largest or
+least recently used window on the selected frame. (If the selected
+frame is a minibuffer-only frame, @code{display-buffer} tries to split a
+window on another frame instead.) If this variable is @code{nil} or the
+variable @code{pop-up-frames} (see below) is non-@code{nil},
+@code{display-buffer} does not split any window.
@end defopt
+@defopt split-window-preferred-function
+This variable must specify a function with one argument, which is a
+window. The @code{display-buffer} routines will call this function with
+one or more candidate windows when they look for a window to split. The
+function is expected to split that window and return the new window. If
+the function returns @code{nil}, this means that the argument window
+cannot (or shall not) be split.
+
+The default value of @code{split-window-preferred-function} is the
+function @code{split-window-sensibly} described below. If you
+customize this option, bear in mind that the @code{display-buffer}
+routines may call your function up to two times when trying to split a
+window. The argument of the first call is the largest window on the
+chosen frame (as returned by @code{get-largest-window}). If that call
+fails to return a live window, your function is called a second time
+with the least recently used window on that frame (as returned by
+@code{get-lru-window}).
+
+The function specified by this option may try to split any other window
+instead of the argument window. Note that the window selected at the
+time @code{display-buffer} was invoked is still selected when your
+function is called. Hence, you can split the selected window (instead
+of the largest or least recently used one) by simply ignoring the window
+argument in the body of your function. You can even choose to not split
+any window as long as the return value of your function specifies a live
+window or @code{nil}, but you are not encouraged to do so
+unconditionally. If you want @code{display-buffer} to never split any
+windows, set @code{pop-up-windows} to @code{nil}.
+@end defopt
+
+@defun split-window-sensibly window
+This function takes a window as argument and tries to split that window
+in a suitable way. The two variables described next are useful for
+tuning the behavior of this function.
+@end defun
+
@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 whether @code{split-window-sensibly} may split
+windows vertically. If it is an integer, @code{split-window-sensibly}
+tries to vertically split a window only if it has at least this many
+lines. If the window has less lines, splitting fails, or the value of
+this variable is @code{nil}, @code{split-window-sensibly} will try to
+split the window horizontally, subject to restrictions of
+@code{split-width-threshold} (see below). If splitting horizontally
+fails too and the window is the only window on its frame,
+@code{split-window-sensibly} will try to split the window vertically
+disregarding the value of @code{split-height-threshold}. If this fails
+as well, @code{split-window-sensibly} returns @code{nil}.
+
+@code{split-window-sensibly} does not split vertically a window whose
+height is fixed (@pxref{Resizing Windows}). Also, it vertically splits
+a window only if the space taken up by that window can accommodate two
+windows one above the other that are both at least
+@code{window-min-height} lines tall. Moreover, if the window that shall
+be split has a mode line, @code{split-window-sensibly} does not split
+the window unless the new window can accommodate a mode line too.
+@end defopt
+
+@defopt split-width-threshold
+This variable specifies whether @code{split-window-sensibly} may split
+windows horizontally. If it is an integer, @code{split-window-sensibly}
+tries to horizontally split a window only if it has at least this many
+columns. If it is @code{nil}, @code{split-window-sensibly} will not
+split the window horizontally. (It still might split the window
+vertically, though, see above.)
+
+@code{split-window-sensibly} does not split horizontally a window if
+that window's width is fixed (@pxref{Resizing Windows}). Also, it
+horizontally splits a window only if the space that window takes up can
+accommodate two windows side by side that are both at least
+@code{window-min-width} columns wide.
@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 window. If @code{even-window-heights} is
+non-@code{nil}, the default, window heights will be evened out. If
+either of the involved window has fixed height (@pxref{Resizing
+Windows}) or @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.
-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}.
-
-If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either
-splits a window or reuses one.
-
+This variable specifies whether @code{display-buffer} should make new
+frames. If it is non-@code{nil}, @code{display-buffer} looks for a
+window already displaying @var{buffer-or-name} on any visible or
+iconified frame. If it finds such a window, it makes that window's
+frame visible and raises it if necessary, and returns the 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.
@xref{Frames}, for more information.
+
+Note that the value of @code{pop-up-windows} does 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.
@end defopt
@c Emacs 19 feature
This variable specifies how to make a new frame if @code{pop-up-frames}
is non-@code{nil}.
-Its value should be a function of no arguments. When
+The value of this variable must be a function of no arguments. When
@code{display-buffer} makes a new frame, it does so by calling that
-function, which should return a frame. The default value of the
-variable is a function that creates a frame using parameters from
-@code{pop-up-frame-alist}.
+function, which should return a frame. The default value of this
+variable is a function that creates a frame using the parameters
+specified by @code{pop-up-frame-alist} described next.
@end defopt
@defopt pop-up-frame-alist
-This variable holds an alist specifying frame parameters used when
-@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
-more information about frame parameters.
+This variable holds an alist specifying frame parameters used by the
+default value of @code{pop-up-frame-function} for making new frames.
+@xref{Frame Parameters}, for more information about frame parameters.
@end defopt
@defopt special-display-buffer-names
-A list of buffer names for buffers that should be displayed specially.
-If the buffer's name is in this list, @code{display-buffer} handles the
-buffer specially.
-
-By default, special display means to give the buffer a dedicated frame.
-
-If an element is a list, instead of a string, then the @sc{car} of the
-list is the buffer name, and the rest of the list says how to create
-the frame. There are two possibilities for the rest of the list (its
-@sc{cdr}). It can be an alist, specifying frame parameters, or it can
+A list of buffer names identifying buffers that should be displayed
+specially. If the name of @var{buffer-or-name} is in this list,
+@code{display-buffer} handles the buffer specially. By default, special
+display means to give the buffer a dedicated frame.
+
+If an element is a list, instead of a string, then the @sc{car} of that
+list is the buffer name, and the rest of that list says how to create
+the frame. There are two possibilities for the rest of that list (its
+@sc{cdr}): It can be an alist, specifying frame parameters, or it can
contain a function and arguments to give to it. (The function's first
argument is always the buffer to be displayed; the arguments from the
list come after that.)
@end defopt
@defopt special-display-regexps
-A list of regular expressions that specify buffers that should be
+A list of regular expressions specifying buffers that should be
displayed specially. If the buffer's name matches any of the regular
expressions in this list, @code{display-buffer} handles the buffer
-specially.
-
-By default, special display means to give the buffer a dedicated frame.
+specially. By default, special display means to give the buffer a
+dedicated frame.
If an element is a list, instead of a string, then the @sc{car} of the
list is the regular expression, and the rest of the list says how to
-create the frame. See above, under @code{special-display-buffer-names}.
+create the frame. See @code{special-display-buffer-names} above.
@end defopt
@defun special-display-p buffer-name
of frame parameters.
@end defun
-@defvar special-display-function
+@defopt special-display-function
This variable holds the function to call to display a buffer specially.
It receives the buffer as an argument, and should return the window in
-which it is displayed.
-
-The default value of this variable is
-@code{special-display-popup-frame}.
-@end defvar
+which it is displayed. The default value of this variable is
+@code{special-display-popup-frame}, see below.
+@end defopt
@defun special-display-popup-frame buffer &optional args
-This function makes @var{buffer} visible in a frame of its own. If
-@var{buffer} is already displayed in a window in some frame, it makes
-the frame visible and raises it, to use that window. Otherwise, it
-creates a frame that will be dedicated to @var{buffer}. This
-function returns the window it used.
+This function tries to make @var{buffer} visible in a frame of its own.
+If @var{buffer} is already displayed in some window, it makes that
+window's frame visible and raises it. Otherwise, it creates a frame
+that is dedicated to @var{buffer}. The return value is the window used
+to display @var{buffer}.
If @var{args} is an alist, it specifies frame parameters for the new
-frame.
-
-If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
-@var{args})} is called as a function to actually create and set up the
-frame; it is called with @var{buffer} as first argument, and @code{(cdr
-@var{args})} as additional arguments.
+frame. If @var{args} is a list whose @sc{car} is a symbol, then
+@code{(car @var{args})} is called as a function to actually create and
+set up the frame; it is called with @var{buffer} as first argument, and
+@code{(cdr @var{args})} as additional arguments.
This function always uses an existing window displaying @var{buffer},
whether or not it is in a frame of its own; but if you set up the above
@end defun
@c Emacs 19 feature
-@defvar display-buffer-function
+@defopt display-buffer-function
This variable is the most flexible way to customize the behavior of
@code{display-buffer}. If it is non-@code{nil}, it should be a function
that @code{display-buffer} calls to do the work. The function should
received. It should choose or create a window, display the specified
buffer in it, and then return the window.
-This hook takes precedence over all the other options and hooks
-described above.
-@end defvar
+This variable takes precedence over all the other options described
+above.
+@end defopt
-@c Emacs 19 feature
+If all options described above fail to produce a suitable window,
+@code{display-buffer} tries to reuse an existing window. As a last
+resort, it will try to display @var{buffer-or-name} on a separate frame.
+In that case, the value of @code{pop-up-frames} is disregarded.
+
+@node Dedicated Windows
+@section Dedicated Windows
@cindex dedicated window
-A window can be marked as ``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
-This function returns non-@code{nil} if @var{window} is marked as
-dedicated; otherwise @code{nil}.
+Functions for displaying a buffer can be told to not use specific
+windows by marking these windows as @dfn{dedicated} to their buffers.
+@code{display-buffer} (@pxref{Choosing Window}) never uses a dedicated
+window for displaying another buffer in it. @code{get-lru-window} and
+@code{get-largest-window} (@pxref{Selecting Windows}) do not consider
+dedicated windows as candidates when their @var{dedicated} argument is
+non-@code{nil}. The behavior of @code{set-window-buffer}
+(@pxref{Buffers and Windows}) with respect to dedicated windows is
+slightly different, see below.
+
+When @code{delete-windows-on} (@pxref{Deleting Windows}) wants to delete
+a dedicated window and that window is the only window on its frame, it
+deletes the window's frame too, provided there are other frames left.
+@code{replace-buffer-in-windows} (@pxref{Displaying Buffers}) tries to
+delete all dedicated windows showing its buffer argument. When such a
+window is the only window on its frame, that frame is deleted, provided
+there are other frames left. If there are no more frames left, some
+other buffer is displayed in the window, and the window is marked as
+non-dedicated.
+
+When you kill a buffer (@pxref{Killing Buffers}) displayed in a
+dedicated window, any such window usually gets deleted too, since
+@code{kill-buffer} calls @code{replace-buffer-in-windows} for cleaning
+up windows. Burying a buffer (@pxref{The Buffer List}) deletes the
+selected window if it is dedicated to that buffer. If, however, that
+window is the only window on its frame, @code{bury-buffer} displays
+another buffer in it and iconifies the frame.
+
+@defun window-dedicated-p &optional window
+This function returns non-@code{nil} if @var{window} is dedicated to its
+buffer and @code{nil} otherwise. More precisely, the return value is
+the value assigned by the last call of @code{set-window-dedicated-p} for
+@var{window} or @code{nil} if that function was never called with
+@var{window} as its argument. The default for @var{window} is the
+selected window.
@end defun
@defun set-window-dedicated-p window flag
-This function marks @var{window} as dedicated if @var{flag} is
-non-@code{nil}, and nondedicated otherwise.
+This function marks @var{window} as dedicated to its buffer if
+@var{flag} is non-@code{nil}, and non-dedicated otherwise.
+
+As a special case, if @var{flag} is @code{t}, @var{window} becomes
+@dfn{strongly} dedicated to its buffer. @code{set-window-buffer}
+signals an error when the window it acts upon is strongly dedicated to
+its buffer and does not already display the buffer it is asked to
+display. Other functions do not treat @code{t} differently from any
+non-@code{nil} value.
@end defun
@node Window Point
@cindex position in window
@cindex point in window
- Each window has its own value of point, independent of the value of
-point in other windows displaying the same buffer. This makes it useful
-to have multiple windows showing one buffer.
+ Each window has its own value of point (@pxref{Point}), independent of
+the value of point in other windows displaying the same buffer. This
+makes it useful to have multiple windows showing one buffer.
@itemize @bullet
@item
point and the buffer's point always move together; they remain equal.
@end itemize
-@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
+ 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 &optional window
This function returns the current position of point in @var{window}.
For a nonselected window, this is the value point would have (in that
-window's buffer) if that window were selected. If @var{window} is
-@code{nil}, the selected window is used.
+window's buffer) if that window were selected. The default for
+@var{window} is the selected window.
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.
-
-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.
+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 set-window-point window position
this simply does @code{goto-char}.
@end defun
-@node Window Start
-@section The Window Start Position
+@defvar window-point-insertion-type
+This variable specifies the marker insertion type (@pxref{Marker
+Insertion Types}) of @code{window-point}. The default is @code{nil},
+so @code{window-point} will stay behind text inserted there.
+@end defvar
+
+@node Window Start and End
+@section The Window Start and End Positions
@cindex window start position
- Each window contains a marker used to keep track of a buffer position
+ Each window maintains a marker used to keep track of a buffer position
that specifies where in the buffer display should start. This position
is called the @dfn{display-start} position of the window (or just the
@dfn{start}). The character after this position is the one that appears
When you create a window, or display a different buffer in it, the
display-start position is set to a display-start position recently used
-for the same buffer, or 1 if the buffer doesn't have any.
+for the same buffer, or to @code{point-min} if the buffer doesn't have
+any.
Redisplay updates the window-start position (if you have not specified
-it explicitly since the previous redisplay)---for example, to make sure
-point appears on the screen. Nothing except redisplay automatically
-changes the window-start position; if you move point, do not expect the
-window-start position to change in response until after the next
-redisplay.
+it explicitly since the previous redisplay)---to make sure point appears
+on the screen. Nothing except redisplay automatically changes the
+window-start position; if you move point, do not expect the window-start
+position to change in response until after the next redisplay.
For a realistic example of using @code{window-start}, see the
description of @code{count-lines}. @xref{Definition of count-lines}.
@end defun
+@cindex window end position
@defun window-end &optional window update
-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.
+This function returns the position where display of its buffer ends in
+@var{window}. The default for @var{window} is the selected window.
Simply changing the buffer text or moving point does not update the
value that @code{window-end} returns. The value is updated only when
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, 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.
+up-to-date value for where display ends, based on the current
+@code{window-start} value. If a previously saved value of that position
+is still valid, @code{window-end} returns that value; 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
@defun pos-visible-in-window-p &optional position window partially
This function returns non-@code{nil} if @var{position} is within the
range of text currently visible on the screen in @var{window}. It
-returns @code{nil} if @var{position} is scrolled vertically out of
-view. Locations that are partially obscured are not considered
-visible unless @var{partially} is non-@code{nil}. The argument
-@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}.
+returns @code{nil} if @var{position} is scrolled vertically out of view.
+Locations that are partially obscured are not considered visible unless
+@var{partially} is non-@code{nil}. The argument @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}
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}, and the character after @var{position} is fully
+non-@code{nil}, and the character following @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.
+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 @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 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.
+This function returns the height of 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 default for @var{line} is the current line in
+@var{window}; the default for @var{window} is 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
If the window contains a row which is taller than the height of the
window (for example in the presence of a large image), the scroll
-functions will adjust the window vscroll to scroll the partially
-visible row. To disable this feature, Lisp code may bind the variable
-`auto-window-vscroll' to @code{nil} (@pxref{Vertical Scrolling}).
+functions will adjust the window's vertical scroll position to scroll
+the partially visible row. To disable this feature, Lisp code may bind
+the variable @code{auto-window-vscroll} to @code{nil} (@pxref{Vertical
+Scrolling}).
@deffn Command scroll-up &optional count
This function scrolls the text in the selected window upward
@c Emacs 19 feature
@defvar other-window-scroll-buffer
If this variable is non-@code{nil}, it tells @code{scroll-other-window}
-which buffer to scroll.
+which buffer's window to scroll.
@end defvar
@defopt scroll-margin
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}.
+proper view. This behavior 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}.
@end defopt
@defopt scroll-step
-This variable is an older variant of @code{scroll-conservatively}. The
-difference is that it if its value is @var{n}, that permits scrolling
+This variable is an older variant of @code{scroll-conservatively}.
+The difference is that if its value is @var{n}, that permits scrolling
only by precisely @var{n} lines, not a smaller number. This feature
does not work with @code{scroll-margin}. The default value is zero.
@end defopt
@node Vertical Scrolling
@section Vertical Fractional Scrolling
@cindex vertical fractional scrolling
+@cindex vertical scroll position
- @dfn{Vertical fractional scrolling} means shifting the image in the
-window up or down by a specified multiple or fraction of a line.
-Each window has a @dfn{vertical scroll position},
-which is a number, never less than zero. It specifies how far to raise
-the contents of the window. Raising the window contents generally makes
-all or part of some lines disappear off the top, and all or part of some
-other lines appear at the bottom. The usual value is zero.
+ @dfn{Vertical fractional scrolling} means shifting text in a window
+up or down by a specified multiple or fraction of a line. Each window
+has a @dfn{vertical scroll position}, which is a number, never less than
+zero. It specifies how far to raise the contents of the window.
+Raising the window contents generally makes all or part of some lines
+disappear off the top, and all or part of some other lines appear at the
+bottom. The usual value is zero.
- The vertical scroll position is measured in units of the normal line
+ The vertical scroll position is measured in units of the normal line
height, which is the height of the default font. Thus, if the value is
.5, that means the window contents are scrolled up half the normal line
height. If it is 3.3, that means the window contents are scrolled up
somewhat over three times the normal line height.
- What fraction of a line the vertical scrolling covers, or how many
+ What fraction of a line the vertical scrolling covers, or how many
lines, depends on what the lines contain. A value of .5 could scroll a
line whose height is very short off the screen, while a value of 3.3
could scroll just part of the way through a tall line or an image.
@defun window-vscroll &optional window pixels-p
This function returns the current vertical scroll position of
-@var{window}. If @var{window} is @code{nil}, the selected window is
-used. If @var{pixels-p} is non-@code{nil}, the return value is
-measured in pixels, rather than in units of the normal line height.
+@var{window}. The default for @var{window} is the selected window.
+If @var{pixels-p} is non-@code{nil}, the return value is measured in
+pixels, rather than in units of the normal line height.
@example
@group
@defun set-window-vscroll window lines &optional pixels-p
This function sets @var{window}'s vertical scroll position to
-@var{lines}. The argument @var{lines} should be zero or positive; if
-not, it is taken as zero.
+@var{lines}. If @var{window} is @code{nil}, the selected window is
+used. 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
@defvar auto-window-vscroll
If this variable is non-@code{nil}, the line-move, scroll-up, and
-scroll-down functions will automatically modify the window vscroll to
-scroll through display rows that are taller that the height of the
-window, for example in the presence of large images.
+scroll-down functions will automatically modify the vertical scroll
+position to scroll through display rows that are taller than the height
+of the window, for example in the presence of large images.
@end defvar
@node Horizontal Scrolling
@defun window-hscroll &optional window
This function returns the total leftward horizontal scrolling of
@var{window}---the number of columns by which the text in @var{window}
-is scrolled left past the left margin.
+is scrolled left past the left margin. The default for
+@var{window} is the selected window.
-The value is never negative. It is zero when no horizontal scrolling
-has been done in @var{window} (which is usually the case).
+The return value is never negative. It is zero when no horizontal
+scrolling has been done in @var{window} (which is usually the case).
-If @var{window} is @code{nil}, the selected window is used.
@example
@group
@end example
@end defun
- Here is how you can determine whether a given position @var{position}
+ Here is how you can determine whether a given position @var{position}
is off the screen due to horizontal scrolling:
@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 and header line, if any. If @var{window} fills its
-entire frame except for the echo area, 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.
+This function returns the number of lines in @var{window} (by default
+the selected window), including any mode line and header line.
+The result is almost always less than the value of @code{frame-height}
+for the associated frame, because the latter also includes any echo
+area. Depending on the toolkit in use, the frame height can also
+include the menu bar and tool bar (@pxref{Size and Position}).
+Therefore in general it is not straightforward to compare window and
+frame heights (see @code{window-full-height-p} below).
@example
@group
mode line (if any) or the header line (if any).
@end defun
+@defun window-full-height-p &optional window
+This function returns non-@code{nil} if @var{window} is as tall as the
+frame that contains it. The default for @var{window} is the selected
+window.
+@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
-@code{frame-width} on that frame. The width does not include the
-window's scroll bar or the column of @samp{|} characters that separates
-side-by-side windows.
+This function returns the number of columns in @var{window}. The
+default for @var{window} is the selected window.
-If @var{window} is @code{nil}, the function uses the selected window.
+The return value does not include the window's scroll bar or the column
+of @samp{|} characters that separates side-by-side windows. Moreover,
+the return value does not include the space used for displaying fringes
+and margins. Hence you cannot, in general, compare the return values of
+@code{window-width} and @code{frame-width} for equality to determine
+whether a window is a wide as the containing frame. Use the function
+@code{window-full-width-p}, see below, instead.
@example
@group
@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.
+This function returns non-@code{nil} if @var{window} is as wide as the
+frame that contains it; otherwise @code{nil}. The default for
+@var{window} is 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.
+The default for @var{window} is the selected window.
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
@cindex changing window size
@cindex window size, changing
- The window size functions fall into two classes: high-level commands
+ 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. Emacs does not permit overlapping windows or gaps between
-windows, so resizing one window affects other windows.
+windows, so resizing a window always affects at least one other window.
@deffn Command enlarge-window size &optional horizontal
-This function makes the selected window @var{size} 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
-lines. If a window from which columns are stolen shrinks below
+This function makes the selected window @var{size} lines taller by
+stealing lines from windows above or below. In a first round, it takes
+lines from one window at a time until that window is
+@code{window-min-height} lines tall, then takes from another. If, at
+the end of the first round, the selected window is still not tall
+enough, @code{enlarge-window} starts a second round, where it deletes
+windows above or below the selected one.
+
+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.
+@code{window-min-width}), then @code{enlarge-window} deletes the window.
@code{enlarge-window} returns @code{nil}.
@end deffn
function returns @code{nil}.
@end defun
-@defun fit-window-to-buffer &optional window max-height min-height
-This function makes @var{window} the right height to display its
-contents exactly. If @var{window} is omitted or @code{nil}, it uses
-the selected window.
+@deffn Command fit-window-to-buffer &optional window max-height min-height
+This command makes @var{window} the right height to display its
+contents exactly. The default for @var{window} is the selected window.
-The argument @var{max-height} specifies the maximum height the window
-is allowed to be; @code{nil} means use the frame height. The argument
-@var{min-height} specifies the minimum height for the window;
-@code{nil} means use @code{window-min-height}. All these height
-values include the mode-line and/or header-line.
-@end defun
+The optional argument @var{max-height} specifies the maximum height the
+window is allowed to be; @code{nil} means use the maximum permissible
+height of a window on @var{window}'s frame. The optional argument
+@var{min-height} specifies the minimum height for the window; @code{nil}
+means use @code{window-min-height}. All these height values include the
+mode line and/or header line.
+
+This function can delete windows when their height shrinks below
+@var{min-height}. It returns non-@code{nil} if it orderly resized
+@var{window}, and @code{nil} otherwise.
+@end deffn
@deffn Command shrink-window-if-larger-than-buffer &optional window
-This command shrinks @var{window} vertically to be as small as
-possible while still showing the full contents of its buffer---but not
-less than @code{window-min-height} lines. If @var{window} is not
-given, it defaults to the selected window.
+This command shrinks @var{window} vertically to be as small as possible
+while still showing the full contents of its buffer---but not less than
+@code{window-min-height} lines. The default for @var{window} is
+the selected window.
-However, the command does nothing if the window is already too small to
+However, this command does nothing if the window is already too small to
display the whole text of the buffer, or if part of the contents are
currently scrolled off screen, or if the window is not the full width of
its frame, or if the window is the only window in its frame.
and @code{nil} otherwise.
@end deffn
+@cindex fixed-size window
@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
-unless you explicitly change it or Emacs has no other choice.
+If this variable is non-@code{nil}, in a given buffer, then the size of
+any window displaying that buffer remains fixed unless you either
+explicitly change it or Emacs has no other choice.
If the value is @code{height}, then only the window's height is fixed;
if the value is @code{width}, then only the window's width is fixed.
(enlarge-window 10))
@end example
-Note that changing the frame size will change the size of a
-fixed-size window, if there is no other alternative.
+Deleting an adjacent window or changing the frame size may change the
+size of a fixed-size window, if there is no other alternative.
@end defvar
@cindex minimum window size
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 line and/or a header line, they are counted as
+one line each. The default value is @code{4}. A value less than
+@code{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 @code{10}.
+A value less than @code{2} is ignored.
@end defopt
+@cindex balancing window sizes
+Emacs provides two functions to balance windows, that is, to even out
+the sizes of windows on the same frame. The minibuffer window and
+fixed-size windows are not resized by these functions.
+
+@deffn Command balance-windows &optional window-or-frame
+This function balances windows in a way that gives more space to
+full-width and/or full-height windows. If @var{window-or-frame}
+specifies a frame, it balances all windows on that frame. If
+@var{window-or-frame} specifies a window, it balances this window and
+its ``siblings'' only. Think of a sibling as the other (original or
+new) window with respect to the present one, involved in the process of
+splitting; see @ref{Splitting Windows}. Since a sibling may have been
+split again, a window can have more than one sibling.
+@end deffn
+
+@deffn Command balance-windows-area
+This function attempts to give all windows on the selected frame
+approximately the same share of the screen area. This means that
+full-width or full-height windows are not given more space than other
+windows.
+@end deffn
+
@node Coordinates and Windows
@section 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, 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}. 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
-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, 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 value
+of @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. Also, the window configuration does not record
+the values of window parameters; see @ref{Window Parameters}.
+
+ You can bring back an entire frame layout by restoring a previously
+saved window configuration. If you want to record the layout of all
+frames instead of just one, use a frame configuration instead of a
+window configuration; see @ref{Frame Configurations}.
@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s current
-window configuration. If @var{frame} is omitted, the selected frame
-is used.
+window configuration. The default for @var{frame} is the selected
+frame.
@end defun
@defun set-window-configuration configuration
was created for.
The argument @var{configuration} must be a value that was previously
-returned by @code{current-window-configuration}. This configuration is
+returned by @code{current-window-configuration}. The configuration is
restored in the frame from which @var{configuration} was made, whether
that frame is selected or not. This always counts as a window size
change and triggers execution of the @code{window-size-change-functions}
Don't use this construct when @code{save-selected-window} is sufficient.
-Exit from @code{save-window-excursion} always triggers execution of the
+Exit from @code{save-window-excursion} always triggers execution of
@code{window-size-change-functions}. (It doesn't know how to tell
whether the restored configuration actually differs from the one in
effect at the end of the @var{forms}.)
file @file{winner.el} for some more operations on windows
configurations.
+@node Window Parameters
+@section Window Parameters
+@cindex window parameters
+
+This sections describes how window parameters can be used to associate
+additional information with windows.
+
+@defun window-parameter window parameter
+This function returns @var{window}'s value for @var{parameter}. The
+default for @var{window} is the selected window. If @var{window}
+has no setting for @var{parameter}, this function returns @code{nil}.
+@end defun
+
+@defun window-parameters &optional window
+This function returns all parameters of @var{window} and their values.
+The default for @var{window} is the selected window. The return value
+is an association list of elements of the form @code{(@var{parameter}
+. @var{value})}.
+@end defun
+
+@defun set-window-parameter window parameter value
+This function sets @var{window}'s value of @var{parameter} to
+@var{value} and returns @var{value}. The default for @var{window}
+is the selected window.
+@end defun
+
+Currently, window parameters are not saved in window configurations and
+consequently not restored by @code{set-window-configuration}. Hence,
+any change of a parameter introduced via @code{set-window-parameter} can
+be undone only by invoking @code{set-window-parameter} for the same
+parameter again. Since @code{save-window-excursion} relies on window
+configurations (@pxref{Window Configurations}), window parameters are
+not saved and restored by that special form, either.
+
@node Window Hooks
@section Hooks for Window Scrolling and Changes
@cindex hooks for window operations
@defvar window-scroll-functions
This variable holds a list of functions that Emacs should call before
-redisplaying a window with scrolling. It is not a normal hook, because
-each function is called with two arguments: the window, and its new
-display-start position.
+redisplaying a window with scrolling. Displaying a different buffer in
+the window also runs these functions.
-Displaying a different buffer in the window also runs these functions.
+This variable is not a normal hook, because each function is called with
+two arguments: the window, and its new display-start position.
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.
+(@pxref{Window Start and End}); 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
Windows}) is what you need here.
@end defvar
-@defvar redisplay-end-trigger-functions
-This abnormal hook is run whenever redisplay in a window uses text that
-extends past a specified end trigger position. You set the end trigger
-position with the function @code{set-window-redisplay-end-trigger}. The
-functions are called with two arguments: the window, and the end trigger
-position. Storing @code{nil} for the end trigger position turns off the
-feature, and the trigger value is automatically reset to @code{nil} just
-after the hook is run.
-@end defvar
-
-@defun set-window-redisplay-end-trigger window position
-This function sets @var{window}'s end trigger position at
-@var{position}.
-@end defun
-
-@defun window-redisplay-end-trigger &optional window
-This function returns @var{window}'s current end trigger position.
-If @var{window} is @code{nil} or omitted, it uses the selected window.
-@end defun
-
@defvar window-configuration-change-hook
A normal hook that is run every time you change the window configuration
of an existing frame. This includes splitting or deleting windows,
changing the sizes of windows, or displaying a different buffer in a
-window. The frame whose window configuration has changed is the
-selected frame when this hook runs.
+window.
+
+The buffer-local part of this hook is run once per each window on the
+affected frame, with the relevant window selected and its buffer
+current. The global part is run once for the modified frame, with that
+frame selected.
@end defvar
+ In addition, you can use @code{jit-lock-register} to register a Font
+Lock fontification function, which will be called whenever parts of a
+buffer are (re)fontified because a window was scrolled or its size
+changed. @xref{Other Font Lock Variables}.
+
@ignore
arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
@end ignore
HCoop / bpt / emacs.git / blobdiff