* Selecting Windows:: The selected window is the one that you edit in.
* Cyclic Window Ordering:: Moving around the existing windows.
* Buffers and Windows:: Each window displays the contents of a buffer.
-* Displaying Buffers:: Higher-lever functions for displaying 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.
* Window Point:: Each window has its own location of point.
@item
how recently the window was selected
+
+@item
+fringe settings
+
+@item
+display margins
+
+@item
+scroll-bar settings
@end itemize
@cindex multiple windows
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
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.
+counted when it is active.
The argument @var{all-frames} specifies which frames to consider. Here
are the possible values and their meanings:
@end defun
@defmac save-selected-window forms@dots{}
-This macro records the selected window, executes @var{forms}
-in sequence, then restores the earlier selected window (unless that
-window is no longer alive).
-
-This macro does not save or restore anything about the sizes, arrangement
-or contents of windows; therefore, if the @var{forms} change them,
-the change persists.
-
-Each frame, at any time, has a window selected within the frame. This
-macro saves only @emph{the} selected window; it does not save anything
-about other frames. If the @var{forms} select some other frame and
-alter the window selected within it, the change persists.
+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
+of some frame is no longer live at the time of exit from this form,
+that frame's selected window is left alone.
@end defmac
@defmac with-selected-window window forms@dots{}
@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
employ heuristics in choosing or creating a window; use these functions
when you need complete control.
-@defun set-window-buffer window buffer-or-name
+@defun set-window-buffer window buffer-or-name &optional keep-margins
This function makes @var{window} display @var{buffer-or-name} as its
contents. It returns @code{nil}. This is the fundamental primitive
for changing which buffer is displayed in a window, and all ways
@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
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 argument @var{all-frames} controls which windows to consider.
-
-@itemize @bullet
-@item
-If it is @code{nil}, consider windows on the selected frame.
-@item
-If it is @code{t}, consider windows on all frames.
-@item
-If it is @code{visible}, consider windows on all visible frames.
-@item
-If it is 0, consider windows on all visible or iconified frames.
-@item
-If it is a frame, consider windows on that frame.
-@end itemize
@end defun
@defvar buffer-display-time
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
@end defopt
@c Emacs 19 feature
-@defvar pop-up-frame-function
+@defopt pop-up-frame-function
This variable specifies how to make a new frame if @code{pop-up-frames}
is non-@code{nil}.
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}.
-@end defvar
+@end defopt
@defopt pop-up-frame-alist
This variable holds an alist specifying frame parameters used when
@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
create the frame. See above, under @code{special-display-buffer-names}.
@end defopt
+@defun special-display-p buffer-name
+This function returns non-@code{nil} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+create a special frame. The value is @code{t} if it would
+use the default frame paramaters, or else the specified list
+of frame parameters.
+@end defun
+
@defvar 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
buffer by switching to it in the selected window.
@end defopt
+@defun same-window-p buffer-name
+This function returns @code{t} if displaying a buffer
+named @var{buffer-name} with @code{display-buffer} would
+put it in the selected window.
+@end defun
+
@c Emacs 19 feature
@defvar display-buffer-function
This variable is the most flexible way to customize the behavior of
other buffer.
@defun window-dedicated-p window
-This function returns @code{t} if @var{window} is marked as dedicated;
-otherwise @code{nil}.
+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
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}.
+@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
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}.
+@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
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.
+ 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
@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.
+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
@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.
+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.
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
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},
+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.
However, it does not include the value of point in the current buffer;
use @code{save-excursion} also, if you wish to preserve that.
-Don't use this construct when @code{save-selected-window} is all you need.
+Don't use this construct when @code{save-selected-window} is sufficient.
Exit from @code{save-window-excursion} always triggers execution of the
@code{window-size-change-functions}. (It doesn't know how to tell
saved point or mark.
@end defun
- Primitives to look inside of window configurations would make sense,
-but none are implemented. It is not clear they are useful enough to
-be worth implementing. See the file @file{winner.el} for some more
-operations on windows configurations.
+@defun window-configuration-frame config
+This function returns the frame for which the window configuration
+@var{config} was made.
+@end defun
+
+ Other primitives to look inside of window configurations would make
+sense, but are not implemented because we did not need them. See the
+file @file{winner.el} for some more operations on windows
+configurations.
@node Window Hooks
@section Hooks for Window Scrolling and Changes
window. The frame whose window configuration has changed is the
selected frame when this hook runs.
@end defvar
+
+@ignore
+ arch-tag: 3f6c36e8-df49-4986-b757-417feed88be3
+@end ignore