comparison lispref/windows.texi @ 52846:2ff062ff0422

(Basic Windows): A window has fringe settings, display margins and scroll-bar settings. (Splitting Windows): Doc split-window return value. Clean up one-window-p. (Selecting Windows): Fix typo. (Cyclic Window Ordering): Explain frame as ALL-FRAMES in next-window. (Buffers and Windows): In set-window-buffer, explain effect on fringe settings and scroll bar settings. (Displaying Buffers): In pop-to-buffer, explain nil as buffer arg. (Choosing Window): Use defopt for pop-up-frame-function. For special-display-buffer-names, explain same-window and same-frame. Clarify window-dedicated-p return value. (Textual Scrolling): scroll-up and scroll-down can get an error. (Horizontal Scrolling): Clarify auto-hscroll-mode. Clarify set-window-hscroll. (Size of Window): Don't mention tool bar in window-height. (Coordinates and Windows): Explain what coordinates-in-window-p returns for fringes and display margins. (Window Configurations): Explain saving fringes, etc.

52845:1826a112381b

@item
the mark

@item
how recently the window was selected
@end itemize

@cindex multiple windows
  Users create multiple windows so they can look at several buffers at
once.  Lisp libraries use multiple windows for a variety of reasons, but

@deffn Command split-window &optional window size horizontal
This function splits @var{window} into two windows.  The original
window @var{window} remains the selected window, but occupies only
part of its former screen area.  The rest is occupied by a newly created
window which is returned as the value of this function.

If @var{horizontal} is non-@code{nil}, then @var{window} splits into
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

@defun one-window-p &optional no-mini all-frames
This function returns non-@code{nil} if there is only one window.  The
argument @var{no-mini}, if non-@code{nil}, means don't count the
minibuffer even if it is active; otherwise, the minibuffer window is
included, if active, in the total number of windows, which is compared
against one.

The argument @var{all-frames} specifies which frames to consider.  Here
are the possible values and their meanings:

@table @asis

@end group
@end example
@end defun

@defmac save-selected-window forms@dots{}
This macro records the selected window of eac frame, executes
@var{forms} in sequence, then restores the earlier selected windows.

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

Consider all windows in all visible frames.  (To get useful results, you
must ensure @var{window} is in a visible frame.)

@item 0
Consider all windows in all visible or iconified frames.

@item anything else
Consider precisely the windows in @var{window}'s frame, and no others.
@end table

     @result{} nil
@end group
@end example

Normally, displaying @var{buffer} in @var{window} resets the window's
fringe widths and position based on the local variables of @var{buffer}.
However, if @var{keep-margins} is non-@code{nil}, the fringe widths and
position of @var{window} remain unchanged.  @xref{Fringes}.
@end defun

@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

@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 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

@xref{Frames}, for more information.
@end defopt

@c Emacs 19 feature
@defvar pop-up-frame-function
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
@code{display-buffer} makes a new frame, it does so by calling that

@end example

@noindent
specifies to display a buffer named @samp{myfile} in a dedicated frame
with specified @code{minibuffer} and @code{menu-bar-lines} parameters.
@end defopt

@defopt special-display-regexps
A list of regular expressions that specify buffers that should be
displayed specially.  If the buffer's name matches any of the regular

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 @code{t} if @var{window} is marked as dedicated;
otherwise @code{nil}.
@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.

If @var{count} is @code{nil} (or omitted), then the length of scroll
is @code{next-screen-context-lines} lines less than the usable height of
the window (not counting its mode line).

@code{scroll-up} returns @code{nil}.
@end deffn

@deffn Command scroll-down &optional count
This function scrolls the text in the selected window downward
@var{count} lines.  If @var{count} is negative, scrolling is actually

If @var{count} is omitted or @code{nil}, then the length of the scroll
is @code{next-screen-context-lines} lines less than the usable height of
the window (not counting its mode line).

@code{scroll-down} returns @code{nil}.
@end deffn

@deffn Command scroll-other-window &optional count
This function scrolls the text in another window upward @var{count}
lines.  Negative values of @var{count}, or @code{nil}, are handled

reduce the net horizontal scroll to zero.  There is no limit to how far
left you can scroll, but eventually all the text will disappear off the
left edge.

@vindex auto-hscroll-mode
  In Emacs 21, redisplay automatically alters the horizontal scrolling
of a window as necessary to ensure that point is always visible, if
@code{auto-hscroll-mode} is set.  However, you can still set the
horizontal scrolling value explicitly.  The value you specify serves as
a lower bound for automatic scrolling, i.e. automatic scrolling
will not scroll a window to a column less than the specified one.

@deffn Command scroll-left &optional count
This function scrolls the selected window @var{count} columns to the
left (or to the right if @var{count} is negative).  The default
for @var{count} is the window width, minus 2.

@end group
@end example
@end defun

@defun set-window-hscroll window columns
This function sets the number of columns from the left margin that
@var{window} is scrolled from the value of @var{columns}.  The argument
@var{columns} should be zero or positive; if not, it is taken as zero.
Fractional values of @var{columns} are not supported at present.

Note that @code{set-window-hscroll} may appear not to work if you test
it by evaluating a call with @kbd{M-:} in a simple way.  What happens
is that the function sets the horizontal scroll value and returns, but
then redisplay adjusts the horizontal scrolling to make point visible,

  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, and there is no tool bar, this
is typically one less than the value of @code{frame-height} on that
frame.

If @var{window} is @code{nil}, the function uses the selected window.

@example
@group

The coordinates are in the vertical line between @var{window} and its
neighbor to the right.  This value occurs only if the window doesn't
have a scroll bar; positions in a scroll bar are considered outside the
window for these purposes.

@item nil
The coordinates are not in any part of @var{window}.
@end table

The function @code{coordinates-in-window-p} does not require a frame as

@cindex saving window information

  A @dfn{window configuration} records the entire layout of one
frame---all windows, their sizes, which buffers they contain, what
part of each buffer is displayed, and the values of point and the
mark.  It also includes the values of @code{window-min-height},
@code{window-min-width} and @code{minibuffer-scroll-window}.  An
exception is made for point in the selected window for the current
buffer; its value is not saved in the window configuration.

  You can bring back an entire previous layout by restoring a window

52846:2ff062ff0422

@item
the mark

@item
how recently the window was selected

@item
fringe settings

@item
display margins

@item
scroll-bar settings
@end itemize

@cindex multiple windows
  Users create multiple windows so they can look at several buffers at
once.  Lisp libraries use multiple windows for a variety of reasons, but

@deffn Command split-window &optional window size horizontal
This function splits @var{window} into two windows.  The original
window @var{window} remains the selected window, but occupies only
part of its former screen area.  The rest is occupied by a newly created
window which is returned as the value of this function.
This function returns the newly created 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

@defun one-window-p &optional no-mini all-frames
This function returns non-@code{nil} if there is only one window.  The
argument @var{no-mini}, if non-@code{nil}, means don't count the
minibuffer even if it is active; otherwise, the minibuffer window is
counted when it is active.

The argument @var{all-frames} specifies which frames to consider.  Here
are the possible values and their meanings:

@table @asis

@end group
@end example
@end defun

@defmac save-selected-window forms@dots{}
This macro records the selected window of each frame, executes
@var{forms} in sequence, then restores the earlier selected windows.

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

Consider all windows in all visible frames.  (To get useful results, you
must ensure @var{window} is in a visible frame.)

@item 0
Consider all windows in all visible or iconified frames.

@item a frame
Consider all windows on that frame.

@item anything else
Consider precisely the windows in @var{window}'s frame, and no others.
@end table

     @result{} nil
@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}.
@end defun

@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

@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

@xref{Frames}, for more information.
@end defopt

@c Emacs 19 feature
@defopt pop-up-frame-function
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
@code{display-buffer} makes a new frame, it does so by calling that

@end example

@noindent
specifies to display a buffer named @samp{myfile} in a dedicated frame
with specified @code{minibuffer} and @code{menu-bar-lines} parameters.

The list of frame parameters can also use the phony frame parameters
@code{same-frame} and @code{same-window}.  If the specified frame
parameters include @code{(same-window . @var{value})} and @var{value}
is non-@code{nil}, that means to display the buffer in the current
selected window.  Otherwise, if they include @code{(same-frame .
@var{value})} and @var{value} is non-@code{nil}, that means to display
the buffer in a new window in the currently selected frame.
@end defopt

@defopt special-display-regexps
A list of regular expressions that specify buffers that should be
displayed specially.  If the buffer's name matches any of the regular

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}.
@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.

If @var{count} is @code{nil} (or omitted), then the length of scroll
is @code{next-screen-context-lines} lines less than the usable height of
the window (not counting its mode line).

@code{scroll-up} returns @code{nil}, unless it gets an error
because it can't scroll any further.
@end deffn

@deffn Command scroll-down &optional count
This function scrolls the text in the selected window downward
@var{count} lines.  If @var{count} is negative, scrolling is actually

If @var{count} is omitted or @code{nil}, then the length of the scroll
is @code{next-screen-context-lines} lines less than the usable height of
the window (not counting its mode line).

@code{scroll-down} returns @code{nil}, unless it gets an error because
it can't scroll any further.
@end deffn

@deffn Command scroll-other-window &optional count
This function scrolls the text in another window upward @var{count}
lines.  Negative values of @var{count}, or @code{nil}, are handled

reduce the net horizontal scroll to zero.  There is no limit to how far
left you can scroll, but eventually all the text will disappear off the
left edge.

@vindex auto-hscroll-mode
  If @code{auto-hscroll-mode} is set, redisplay automatically alters
the horizontal scrolling of a window as necessary to ensure that point
is always visible.  However, you can still set the horizontal
scrolling value explicitly.  The value you specify serves as a lower
bound for automatic scrolling, i.e. automatic scrolling will not
scroll a window to a column less than the specified one.

@deffn Command scroll-left &optional count
This function scrolls the selected window @var{count} columns to the
left (or to the right if @var{count} is negative).  The default
for @var{count} is the window width, minus 2.

@end group
@end example
@end defun

@defun set-window-hscroll window columns
This function sets horizontal scrolling of @var{window}.  The value of
@var{columns} specifies the amount of scrolling, in terms of columns
from the left margin.  The argument @var{columns} should be zero or
positive; if not, it is taken as zero.  Fractional values of
@var{columns} are not supported at present.

Note that @code{set-window-hscroll} may appear not to work if you test
it by evaluating a call with @kbd{M-:} in a simple way.  What happens
is that the function sets the horizontal scroll value and returns, but
then redisplay adjusts the horizontal scrolling to make point visible,

  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.

@example
@group

The coordinates are in the vertical line between @var{window} and its
neighbor to the right.  This value occurs only if the window doesn't
have a scroll bar; positions in a scroll bar are considered outside the
window for these purposes.

@item left-fringe
@itemx right-fringe
The coordinates are in the left or right fringe of the window.

@item left-margin
@itemx right-margin
The coordinates are in the left or right margin of the window.

@item nil
The coordinates are not in any part of @var{window}.
@end table

The function @code{coordinates-in-window-p} does not require a frame as

@cindex saving window information

  A @dfn{window configuration} records the entire layout of one
frame---all windows, their sizes, which buffers they contain, what
part of each buffer is displayed, and the values of point and the
mark; 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}.  An
exception is made for point in the selected window for the current
buffer; its value is not saved in the window configuration.

  You can bring back an entire previous layout by restoring a window