mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-16 09:50:25 +00:00
39e8fb76d6
* doc/lispref/windows.texi (Window History): Mention the default value of switch-to-visible-buffer.
3717 lines
155 KiB
Plaintext
3717 lines
155 KiB
Plaintext
@c -*-texinfo-*-
|
|
@c This is part of the GNU Emacs Lisp Reference Manual.
|
|
@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
|
|
@c Foundation, Inc.
|
|
@c See the file elisp.texi for copying conditions.
|
|
@node Windows
|
|
@chapter Windows
|
|
|
|
This chapter describes the functions and variables related to Emacs
|
|
windows. @xref{Frames}, for how windows are assigned an area of screen
|
|
available for Emacs to use. @xref{Display}, for information on how text
|
|
is displayed in windows.
|
|
|
|
@menu
|
|
* Basic Windows:: Basic information on using windows.
|
|
* Windows and Frames:: Relating windows to the frame they appear on.
|
|
* Window Sizes:: Accessing a window's size.
|
|
* Resizing Windows:: Changing the sizes of windows.
|
|
* Splitting Windows:: Creating a new window.
|
|
* Deleting Windows:: Removing a window from its frame.
|
|
* Recombining Windows:: Preserving the frame layout when splitting and
|
|
deleting windows.
|
|
* 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.
|
|
* Switching Buffers:: Higher-level functions for switching to a buffer.
|
|
* Choosing Window:: How to choose a window for displaying a buffer.
|
|
* Display Action Functions:: Subroutines for @code{display-buffer}.
|
|
* Choosing Window Options:: Extra options affecting how buffers are displayed.
|
|
* Window History:: Each window remembers the buffers displayed in it.
|
|
* Dedicated Windows:: How to avoid displaying another buffer in
|
|
a specific window.
|
|
* Quitting Windows:: How to restore the state prior to displaying a
|
|
buffer.
|
|
* Window Point:: Each window has its own location of point.
|
|
* 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 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.
|
|
@end menu
|
|
|
|
|
|
@node Basic Windows
|
|
@section Basic Concepts of Emacs Windows
|
|
@cindex window
|
|
|
|
A @dfn{window} is an area of the screen that is used to display a buffer
|
|
(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special
|
|
Lisp object type.
|
|
|
|
@cindex multiple windows
|
|
Windows are grouped into frames (@pxref{Frames}). Each frame
|
|
contains at least one window; the user can subdivide it into multiple,
|
|
non-overlapping windows to view several buffers at once. Lisp
|
|
programs can use multiple windows for a variety of purposes. In
|
|
Rmail, for example, you can view a summary of message titles in one
|
|
window, and the contents of the selected message in another window.
|
|
|
|
@cindex terminal screen
|
|
@cindex screen of terminal
|
|
Emacs uses the word ``window'' with a different meaning than in
|
|
graphical desktop environments and window systems, such as the X
|
|
Window System. When Emacs is run on X, each of its graphical X
|
|
windows is an Emacs frame (containing one or more Emacs windows).
|
|
When Emacs is run on a text terminal, the frame fills the entire
|
|
terminal screen.
|
|
|
|
@cindex tiled windows
|
|
Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap
|
|
within the area of the frame. When a window is created, resized, or
|
|
deleted, the change in window space is taken from or given to the
|
|
adjacent windows, so that the total area of the frame is unchanged.
|
|
|
|
@defun windowp object
|
|
This function returns @code{t} if @var{object} is a window (whether or
|
|
not it displays a buffer). Otherwise, it returns @code{nil}.
|
|
@end defun
|
|
|
|
@cindex live windows
|
|
A @dfn{live window} is one that is actually displaying a buffer in a
|
|
frame.
|
|
|
|
@defun window-live-p object
|
|
This function returns @code{t} if @var{object} is a live window and
|
|
@code{nil} otherwise. A live window is one that displays a buffer.
|
|
@end defun
|
|
|
|
@cindex internal windows
|
|
The windows in each frame are organized into a @dfn{window tree}.
|
|
@xref{Windows and Frames}. The leaf nodes of each window tree are live
|
|
windows---the ones actually displaying buffers. The internal nodes of
|
|
the window tree are @dfn{internal windows}, which are not live.
|
|
|
|
@cindex valid windows
|
|
A @dfn{valid window} is one that is either live or internal. A valid
|
|
window can be @dfn{deleted}, i.e., removed from its frame
|
|
(@pxref{Deleting Windows}); then it is no longer valid, but the Lisp
|
|
object representing it might be still referenced from other Lisp
|
|
objects. A deleted window may be made valid again by restoring a saved
|
|
window configuration (@pxref{Window Configurations}).
|
|
|
|
You can distinguish valid windows from deleted windows with
|
|
@code{window-valid-p}.
|
|
|
|
@defun window-valid-p object
|
|
This function returns @code{t} if @var{object} is a live window, or an
|
|
internal window in a window tree. Otherwise, it returns @code{nil},
|
|
including for the case where @var{object} is a deleted window.
|
|
@end defun
|
|
|
|
@cindex selected window
|
|
@cindex window selected within a frame
|
|
In each frame, at any time, exactly one Emacs window is designated
|
|
as @dfn{selected within the frame}. For the selected frame, that
|
|
window is called the @dfn{selected window}---the one in which most
|
|
editing takes place, and in which the cursor for selected windows
|
|
appears (@pxref{Cursor Parameters}). The selected window's buffer is
|
|
usually also the current buffer, except when @code{set-buffer} has
|
|
been used (@pxref{Current Buffer}). As for non-selected frames, the
|
|
window selected within the frame becomes the selected window if the
|
|
frame is ever selected. @xref{Selecting Windows}.
|
|
|
|
@defun selected-window
|
|
This function returns the selected window (which is always a live
|
|
window).
|
|
@end defun
|
|
|
|
@node Windows and Frames
|
|
@section Windows and Frames
|
|
|
|
Each window belongs to exactly one frame (@pxref{Frames}).
|
|
|
|
@defun window-frame window
|
|
This function returns the frame that the window @var{window} belongs
|
|
to. If @var{window} is @code{nil}, it defaults to the selected
|
|
window.
|
|
@end defun
|
|
|
|
@defun window-list &optional frame minibuffer window
|
|
This function returns a list of live windows belonging to the frame
|
|
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
|
|
the selected frame.
|
|
|
|
The optional argument @var{minibuffer} specifies whether to include
|
|
the minibuffer window in the returned list. If @var{minibuffer} is
|
|
@code{t}, the minibuffer window is included. If @var{minibuffer} is
|
|
@code{nil} or omitted, the minibuffer window is included only if it is
|
|
active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the
|
|
minibuffer window is never included.
|
|
|
|
The optional argument @var{window}, if non-@code{nil}, should be a live
|
|
window on the specified frame; then @var{window} will be the first
|
|
element in the returned list. If @var{window} is omitted or @code{nil},
|
|
the window selected within the frame is the first element.
|
|
@end defun
|
|
|
|
@cindex window tree
|
|
@cindex root window
|
|
Windows in the same frame are organized into a @dfn{window tree},
|
|
whose leaf nodes are the live windows. The internal nodes of a window
|
|
tree are not live; they exist for the purpose of organizing the
|
|
relationships between live windows. The root node of a window tree is
|
|
called the @dfn{root window}. It can be either a live window (if the
|
|
frame has just one window), or an internal window.
|
|
|
|
A minibuffer window (@pxref{Minibuffer Windows}) is not part of its
|
|
frame's window tree unless the frame is a minibuffer-only frame.
|
|
Nonetheless, most of the functions in this section accept the
|
|
minibuffer window as an argument. Also, the function
|
|
@code{window-tree} described at the end of this section lists the
|
|
minibuffer window alongside the actual window tree.
|
|
|
|
@defun frame-root-window &optional frame-or-window
|
|
This function returns the root window for @var{frame-or-window}. The
|
|
argument @var{frame-or-window} should be either a window or a frame;
|
|
if omitted or @code{nil}, it defaults to the selected frame. If
|
|
@var{frame-or-window} is a window, the return value is the root window
|
|
of that window's frame.
|
|
@end defun
|
|
|
|
@cindex parent window
|
|
@cindex child window
|
|
@cindex sibling window
|
|
When a window is split, there are two live windows where previously
|
|
there was one. One of these is represented by the same Lisp window
|
|
object as the original window, and the other is represented by a
|
|
newly-created Lisp window object. Both of these live windows become
|
|
leaf nodes of the window tree, as @dfn{child windows} of a single
|
|
internal window. If necessary, Emacs automatically creates this
|
|
internal window, which is also called the @dfn{parent window}, and
|
|
assigns it to the appropriate position in the window tree. A set of
|
|
windows that share the same parent are called @dfn{siblings}.
|
|
|
|
@cindex parent window
|
|
@defun window-parent &optional window
|
|
This function returns the parent window of @var{window}. If
|
|
@var{window} is omitted or @code{nil}, it defaults to the selected
|
|
window. The return value is @code{nil} if @var{window} has no parent
|
|
(i.e., it is a minibuffer window or the root window of its frame).
|
|
@end defun
|
|
|
|
Each internal window always has at least two child windows. If this
|
|
number falls to one as a result of window deletion, Emacs
|
|
automatically deletes the internal window, and its sole remaining
|
|
child window takes its place in the window tree.
|
|
|
|
Each child window can be either a live window, or an internal window
|
|
(which in turn would have its own child windows). Therefore, each
|
|
internal window can be thought of as occupying a certain rectangular
|
|
@dfn{screen area}---the union of the areas occupied by the live
|
|
windows that are ultimately descended from it.
|
|
|
|
@cindex window combination
|
|
@cindex vertical combination
|
|
@cindex horizontal combination
|
|
For each internal window, the screen areas of the immediate children
|
|
are arranged either vertically or horizontally (never both). If the
|
|
child windows are arranged one above the other, they are said to form
|
|
a @dfn{vertical combination}; if they are arranged side by side, they
|
|
are said to form a @dfn{horizontal combination}. Consider the
|
|
following example:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ______ ____________________________ |
|
|
|| || __________________________ ||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| |||____________W4____________|||
|
|
|| || __________________________ ||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| |||____________W5____________|||
|
|
||__W2__||_____________W3_____________ |
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The root window of this frame is an internal window, @var{W1}. Its
|
|
child windows form a horizontal combination, consisting of the live
|
|
window @var{W2} and the internal window @var{W3}. The child windows
|
|
of @var{W3} form a vertical combination, consisting of the live
|
|
windows @var{W4} and @var{W5}. Hence, the live windows in this
|
|
window tree are @var{W2} @var{W4}, and @var{W5}.
|
|
|
|
The following functions can be used to retrieve a child window of an
|
|
internal window, and the siblings of a child window.
|
|
|
|
@defun window-top-child window
|
|
This function returns the topmost child window of @var{window}, if
|
|
@var{window} is an internal window whose children form a vertical
|
|
combination. For any other type of window, the return value is
|
|
@code{nil}.
|
|
@end defun
|
|
|
|
@defun window-left-child window
|
|
This function returns the leftmost child window of @var{window}, if
|
|
@var{window} is an internal window whose children form a horizontal
|
|
combination. For any other type of window, the return value is
|
|
@code{nil}.
|
|
@end defun
|
|
|
|
@defun window-child window
|
|
This function returns the first child window of the internal window
|
|
@var{window}---the topmost child window for a vertical combination, or
|
|
the leftmost child window for a horizontal combination. If
|
|
@var{window} is a live window, the return value is @code{nil}.
|
|
@end defun
|
|
|
|
@defun window-combined-p &optional window horizontal
|
|
This function returns a non-@code{nil} value if and only if
|
|
@var{window} is part of a vertical combination. If @var{window} is
|
|
omitted or @code{nil}, it defaults to the selected one.
|
|
|
|
If the optional argument @var{horizontal} is non-@code{nil}, this
|
|
means to return non-@code{nil} if and only if @var{window} is part of
|
|
a horizontal combination.
|
|
@end defun
|
|
|
|
@defun window-next-sibling &optional window
|
|
This function returns the next sibling of the window @var{window}. If
|
|
omitted or @code{nil}, @var{window} defaults to the selected window.
|
|
The return value is @code{nil} if @var{window} is the last child of
|
|
its parent.
|
|
@end defun
|
|
|
|
@defun window-prev-sibling &optional window
|
|
This function returns the previous sibling of the window @var{window}.
|
|
If omitted or @code{nil}, @var{window} defaults to the selected
|
|
window. The return value is @code{nil} if @var{window} is the first
|
|
child of its parent.
|
|
@end defun
|
|
|
|
The functions @code{window-next-sibling} and
|
|
@code{window-prev-sibling} should not be confused with the functions
|
|
@code{next-window} and @code{previous-window}, which return the next
|
|
and previous window, respectively, in the cyclic ordering of windows
|
|
(@pxref{Cyclic Window Ordering}).
|
|
|
|
You can use the following functions to find the first live window on a
|
|
frame and the window nearest to a given window.
|
|
|
|
@defun frame-first-window &optional frame-or-window
|
|
This function returns the live window at the upper left corner of the
|
|
frame specified by @var{frame-or-window}. The argument
|
|
@var{frame-or-window} must denote a window or a live frame and defaults
|
|
to the selected frame. If @var{frame-or-window} specifies a window,
|
|
this function returns the first window on that window's frame. Under
|
|
the assumption that the frame from our canonical example is selected
|
|
@code{(frame-first-window)} returns @var{W2}.
|
|
@end defun
|
|
|
|
@cindex window in direction
|
|
@defun window-in-direction direction &optional window ignore
|
|
This function returns the nearest live window in direction
|
|
@var{direction} as seen from the position of @code{window-point} in
|
|
window @var{window}. The argument @var{direction} must be one of
|
|
@code{above}, @code{below}, @code{left} or @code{right}. The optional
|
|
argument @var{window} must denote a live window and defaults to the
|
|
selected one.
|
|
|
|
This function does not return a window whose @code{no-other-window}
|
|
parameter is non-@code{nil} (@pxref{Window Parameters}). If the nearest
|
|
window's @code{no-other-window} parameter is non-@code{nil}, this
|
|
function tries to find another window in the indicated direction whose
|
|
@code{no-other-window} parameter is @code{nil}. If the optional
|
|
argument @var{ignore} is non-@code{nil}, a window may be returned even
|
|
if its @code{no-other-window} parameter is non-@code{nil}.
|
|
|
|
If it doesn't find a suitable window, this function returns @code{nil}.
|
|
@end defun
|
|
|
|
The following function allows to retrieve the entire window tree of a
|
|
frame:
|
|
|
|
@defun window-tree &optional frame
|
|
This function returns a list representing the window tree for frame
|
|
@var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to
|
|
the selected frame.
|
|
|
|
The return value is a list of the form @code{(@var{root} @var{mini})},
|
|
where @var{root} represents the window tree of the frame's root
|
|
window, and @var{mini} is the frame's minibuffer window.
|
|
|
|
If the root window is live, @var{root} is that window itself.
|
|
Otherwise, @var{root} is a list @code{(@var{dir} @var{edges} @var{w1}
|
|
@var{w2} ...)} where @var{dir} is @code{nil} for a horizontal
|
|
combination and @code{t} for a vertical combination, @var{edges} gives
|
|
the size and position of the combination, and the remaining elements
|
|
are the child windows. Each child window may again be a window object
|
|
(for a live window) or a list with the same format as above (for an
|
|
internal window). The @var{edges} element is a list @code{(@var{left}
|
|
@var{top} @var{right} @var{bottom})}, similar to the value returned by
|
|
@code{window-edges} (@pxref{Coordinates and Windows}).
|
|
@end defun
|
|
|
|
@node Window Sizes
|
|
@section Window Sizes
|
|
@cindex window size
|
|
@cindex size of window
|
|
|
|
The following schematic shows the structure of a live window:
|
|
|
|
@smallexample
|
|
@group
|
|
_________________________________________
|
|
^ |______________ Header Line_______________|
|
|
| |LS|LF|LM| |RM|RF|RS| ^
|
|
| | | | | | | | | |
|
|
Window | | | | Text Area | | | | Window
|
|
Total | | | | (Window Body) | | | | Body
|
|
Height | | | | | | | | Height
|
|
| | | | |<- Window Body Width ->| | | | |
|
|
| |__|__|__|_______________________|__|__|__| v
|
|
v |_______________ Mode Line _______________|
|
|
|
|
<----------- Window Total Width -------->
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@cindex window body
|
|
@cindex text area of a window
|
|
@cindex body of a window
|
|
At the center of the window is the @dfn{text area}, or @dfn{body},
|
|
where the buffer text is displayed. On each side of the text area is
|
|
a series of vertical areas; from innermost to outermost, these are the
|
|
left and right margins, denoted by LM and RM in the schematic
|
|
(@pxref{Display Margins}); the left and right fringes, denoted by LF
|
|
and RF (@pxref{Fringes}); and the left or right scroll bar, only one of
|
|
which is present at any time, denoted by LS and RS (@pxref{Scroll
|
|
Bars}). At the top of the window is an optional header line
|
|
(@pxref{Header Lines}), and at the bottom of the window is the mode
|
|
line (@pxref{Mode Line Format}).
|
|
|
|
Emacs provides several functions for finding the height and width of
|
|
a window. Except where noted, Emacs reports window heights and widths
|
|
as integer numbers of lines and columns, respectively. On a graphical
|
|
display, each ``line'' and ``column'' actually corresponds to the
|
|
height and width of a ``default'' character specified by the frame's
|
|
default font. Thus, if a window is displaying text with a different
|
|
font or size, the reported height and width for that window may differ
|
|
from the actual number of text lines or columns displayed within it.
|
|
|
|
@cindex window height
|
|
@cindex height of a window
|
|
@cindex total height of a window
|
|
@cindex window width
|
|
@cindex width of a window
|
|
@cindex total width of a window
|
|
The @dfn{total height} of a window is the distance between the top
|
|
and bottom of the window, including the header line (if one exists)
|
|
and the mode line. The @dfn{total width} of a window is the distance
|
|
between the left and right edges of the mode line. Note that the
|
|
height of a frame is not the same as the height of its windows, since
|
|
a frame may also contain an echo area, menu bar, and tool bar
|
|
(@pxref{Size and Position}).
|
|
|
|
@defun window-total-height &optional window
|
|
This function returns the total height, in lines, of the window
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window. If @var{window} is an internal window, the
|
|
return value is the total height occupied by its descendant windows.
|
|
@end defun
|
|
|
|
@defun window-total-width &optional window
|
|
This function returns the total width, in columns, of the window
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window. If @var{window} is internal, the return value
|
|
is the total width occupied by its descendant windows.
|
|
@end defun
|
|
|
|
@defun window-total-size &optional window horizontal
|
|
This function returns either the total height or width of the window
|
|
@var{window}. If @var{horizontal} is omitted or @code{nil}, this is
|
|
equivalent to calling @code{window-total-height} for @var{window};
|
|
otherwise it is equivalent to calling @code{window-total-width} for
|
|
@var{window}.
|
|
@end defun
|
|
|
|
@cindex full-width window
|
|
@cindex full-height window
|
|
The following functions can be used to determine whether a given
|
|
window has any adjacent windows.
|
|
|
|
@defun window-full-height-p &optional window
|
|
This function returns non-@code{nil} if @var{window} has no other
|
|
window above or below it in its frame, i.e., its total height equals
|
|
the total height of the root window on that frame. If @var{window} is
|
|
omitted or @code{nil}, it defaults to the selected window.
|
|
@end defun
|
|
|
|
@defun window-full-width-p &optional window
|
|
This function returns non-@code{nil} if @var{window} has no other
|
|
window to the left or right in its frame, i.e., its total width equals
|
|
that of the root window on that frame. If @var{window} is omitted or
|
|
@code{nil}, it defaults to the selected window.
|
|
@end defun
|
|
|
|
@cindex window body height
|
|
@cindex body height of a window
|
|
@cindex window body width
|
|
@cindex body width of a window
|
|
@cindex body size of a window
|
|
@cindex window body size
|
|
The @dfn{body height} of a window is the height of its text area,
|
|
which does not include the mode or header line. Similarly, the
|
|
@dfn{body width} is the width of the text area, which does not include
|
|
the scroll bar, fringes, or margins.
|
|
|
|
@defun window-body-height &optional window
|
|
This function returns the body height, in lines, of the window
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window; otherwise it must be a live window.
|
|
|
|
If there is a partially-visible line at the bottom of the text area,
|
|
that counts as a whole line; to exclude such a partially-visible line,
|
|
use @code{window-text-height}, below.
|
|
@end defun
|
|
|
|
@defun window-body-width &optional window
|
|
This function returns the body width, in columns, of the window
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window; otherwise it must be a live window.
|
|
@end defun
|
|
|
|
@defun window-body-size &optional window horizontal
|
|
This function returns the body height or body width of @var{window}.
|
|
If @var{horizontal} is omitted or @code{nil}, it is equivalent to
|
|
calling @code{window-body-height} for @var{window}; otherwise it is
|
|
equivalent to calling @code{window-body-width}.
|
|
@end defun
|
|
|
|
@defun window-text-height &optional window
|
|
This function is like @code{window-body-height}, except that any
|
|
partially-visible line at the bottom of the text area is not counted.
|
|
@end defun
|
|
|
|
For compatibility with previous versions of Emacs,
|
|
@code{window-height} is an alias for @code{window-total-height}, and
|
|
@code{window-width} is an alias for @code{window-body-width}. These
|
|
aliases are considered obsolete and will be removed in the future.
|
|
|
|
@cindex fixed-size window
|
|
@vindex window-min-height
|
|
@vindex window-min-width
|
|
Commands that change the size of windows (@pxref{Resizing Windows}),
|
|
or split them (@pxref{Splitting Windows}), obey the variables
|
|
@code{window-min-height} and @code{window-min-width}, which specify
|
|
the smallest allowable window height and width. @xref{Change
|
|
Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
|
|
Manual}. They also obey the variable @code{window-size-fixed}, with
|
|
which a window can be @dfn{fixed} in size:
|
|
|
|
@defvar window-size-fixed
|
|
If this buffer-local variable is non-@code{nil}, the size of any
|
|
window displaying the buffer cannot normally be changed. Deleting a
|
|
window or changing the frame's size may still change its size, if
|
|
there is no 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.
|
|
Any other non-@code{nil} value fixes both the width and the height.
|
|
@end defvar
|
|
|
|
@defun window-size-fixed-p &optional window horizontal
|
|
This function returns a non-@code{nil} value if @var{window}'s height
|
|
is fixed. If @var{window} is omitted or @code{nil}, it defaults to
|
|
the selected window. If the optional argument @var{horizontal} is
|
|
non-@code{nil}, the return value is non-@code{nil} if @var{window}'s
|
|
width is fixed.
|
|
|
|
A @code{nil} return value does not necessarily mean that @var{window}
|
|
can be resized in the desired direction. To determine that, use the
|
|
function @code{window-resizable}. @xref{Resizing Windows}.
|
|
@end defun
|
|
|
|
@xref{Coordinates and Windows}, for more functions that report the
|
|
positions of various parts of a window relative to the frame, from
|
|
which you can calculate its size. In particular, you can use the
|
|
functions @code{window-pixel-edges} and
|
|
@code{window-inside-pixel-edges} to find the size in pixels, for
|
|
graphical displays.
|
|
|
|
@node Resizing Windows
|
|
@section Resizing Windows
|
|
@cindex window resizing
|
|
@cindex resize window
|
|
@cindex changing window size
|
|
@cindex window size, changing
|
|
|
|
This section describes functions for resizing a window without
|
|
changing the size of its frame. Because live windows do not overlap,
|
|
these functions are meaningful only on frames that contain two or more
|
|
windows: resizing a window also changes the size of a neighboring
|
|
window. If there is just one window on a frame, its size cannot be
|
|
changed except by resizing the frame (@pxref{Size and Position}).
|
|
|
|
Except where noted, these functions also accept internal windows as
|
|
arguments. Resizing an internal window causes its child windows to be
|
|
resized to fit the same space.
|
|
|
|
@defun window-resizable window delta &optional horizontal ignore
|
|
This function returns @var{delta} if the size of @var{window} can be
|
|
changed vertically by @var{delta} lines. If the optional argument
|
|
@var{horizontal} is non-@code{nil}, it instead returns @var{delta} if
|
|
@var{window} can be resized horizontally by @var{delta} columns. It
|
|
does not actually change the window size.
|
|
|
|
If @var{window} is @code{nil}, it defaults to the selected window.
|
|
|
|
A positive value of @var{delta} means to check whether the window can be
|
|
enlarged by that number of lines or columns; a negative value of
|
|
@var{delta} means to check whether the window can be shrunk by that many
|
|
lines or columns. If @var{delta} is non-zero, a return value of 0 means
|
|
that the window cannot be resized.
|
|
|
|
Normally, the variables @code{window-min-height} and
|
|
@code{window-min-width} specify the smallest allowable window size.
|
|
@xref{Change Window,, Deleting and Rearranging Windows, emacs, The GNU
|
|
Emacs Manual}. However, if the optional argument @var{ignore} is
|
|
non-@code{nil}, this function ignores @code{window-min-height} and
|
|
@code{window-min-width}, as well as @code{window-size-fixed}.
|
|
Instead, it considers the minimum-height window to be one consisting
|
|
of a header (if any), a mode line, plus a text area one line tall; and
|
|
a minimum-width window as one consisting of fringes, margins, and
|
|
scroll bar (if any), plus a text area two columns wide.
|
|
@end defun
|
|
|
|
@defun window-resize window delta &optional horizontal ignore
|
|
This function resizes @var{window} by @var{delta} increments. If
|
|
@var{horizontal} is @code{nil}, it changes the height by @var{delta}
|
|
lines; otherwise, it changes the width by @var{delta} columns. A
|
|
positive @var{delta} means to enlarge the window, and a negative
|
|
@var{delta} means to shrink it.
|
|
|
|
If @var{window} is @code{nil}, it defaults to the selected window. If
|
|
the window cannot be resized as demanded, an error is signaled.
|
|
|
|
The optional argument @var{ignore} has the same meaning as for the
|
|
function @code{window-resizable} above.
|
|
|
|
The choice of which window edges this function alters depends on the
|
|
values of the option @code{window-combination-resize} and the
|
|
combination limits of the involved windows; in some cases, it may alter
|
|
both edges. @xref{Recombining Windows}. To resize by moving only the
|
|
bottom or right edge of a window, use the function
|
|
@code{adjust-window-trailing-edge}, below.
|
|
@end defun
|
|
|
|
@c The commands enlarge-window, enlarge-window-horizontally,
|
|
@c shrink-window, and shrink-window-horizontally are documented in the
|
|
@c Emacs manual. They are not preferred for calling from Lisp.
|
|
|
|
@defun adjust-window-trailing-edge window delta &optional horizontal
|
|
This function moves @var{window}'s bottom edge by @var{delta} lines.
|
|
If optional argument @var{horizontal} is non-@code{nil}, it instead
|
|
moves the right edge by @var{delta} columns. If @var{window} is
|
|
@code{nil}, it defaults to the selected window.
|
|
|
|
A positive @var{delta} moves the edge downwards or to the right; a
|
|
negative @var{delta} moves it upwards or to the left. If the edge
|
|
cannot be moved as far as specified by @var{delta}, this function
|
|
moves it as far as possible but does not signal a error.
|
|
|
|
This function tries to resize windows adjacent to the edge that is
|
|
moved. If this is not possible for some reason (e.g., if that adjacent
|
|
window is fixed-size), it may resize other windows.
|
|
@end defun
|
|
|
|
The following commands resize windows in more specific ways. When
|
|
called interactively, they act on the selected window.
|
|
|
|
@deffn Command fit-window-to-buffer &optional window max-height min-height override
|
|
This command adjusts the height of @var{window} to fit the text in it.
|
|
It returns non-@code{nil} if it was able to resize @var{window}, and
|
|
@code{nil} otherwise. If @var{window} is omitted or @code{nil}, it
|
|
defaults to the selected window. Otherwise, it should be a live
|
|
window.
|
|
|
|
The optional argument @var{max-height}, if non-@code{nil}, specifies
|
|
the maximum total height that this function can give @var{window}.
|
|
The optional argument @var{min-height}, if non-@code{nil}, specifies
|
|
the minimum total height that it can give, which overrides the
|
|
variable @code{window-min-height}.
|
|
|
|
If the optional argument @var{override} is non-@code{nil}, this
|
|
function ignores any size restrictions imposed by
|
|
@code{window-min-height} and @code{window-min-width}.
|
|
|
|
@vindex fit-frame-to-buffer
|
|
If the option @code{fit-frame-to-buffer} is non-@code{nil}, this
|
|
command may resize the frame to fit its contents.
|
|
@end deffn
|
|
|
|
@deffn Command shrink-window-if-larger-than-buffer &optional window
|
|
This command attempts to reduce @var{window}'s height as much as
|
|
possible while still showing its full buffer, but no less than
|
|
@code{window-min-height} lines. The return value is non-@code{nil} if
|
|
the window was resized, and @code{nil} otherwise. If @var{window} is
|
|
omitted or @code{nil}, it defaults to the selected window. Otherwise,
|
|
it should be a live window.
|
|
|
|
This command does nothing if the window is already too short to
|
|
display all of its buffer, or if any of the buffer is scrolled
|
|
off-screen, or if the window is the only live window in its frame.
|
|
@end deffn
|
|
|
|
@cindex balancing window sizes
|
|
@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 only that window
|
|
and its siblings (@pxref{Windows and Frames}).
|
|
@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. Full-width or
|
|
full-height windows are not given more space than other windows.
|
|
@end deffn
|
|
|
|
@cindex maximizing windows
|
|
@deffn Command maximize-window &optional window
|
|
This function attempts to make @var{window} as large as possible, in
|
|
both dimensions, without resizing its frame or deleting other windows.
|
|
If @var{window} is omitted or @code{nil}, it defaults to the selected
|
|
window.
|
|
@end deffn
|
|
|
|
@cindex minimizing windows
|
|
@deffn Command minimize-window &optional window
|
|
This function attempts to make @var{window} as small as possible, in
|
|
both dimensions, without deleting it or resizing its frame. If
|
|
@var{window} is omitted or @code{nil}, it defaults to the selected
|
|
window.
|
|
@end deffn
|
|
|
|
|
|
@node Splitting Windows
|
|
@section Splitting Windows
|
|
@cindex splitting windows
|
|
@cindex window splitting
|
|
|
|
This section describes functions for creating a new window by
|
|
@dfn{splitting} an existing one.
|
|
|
|
@defun split-window &optional window size side
|
|
This function creates a new live window next to the window
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window. That window is ``split'', and reduced in
|
|
size. The space is taken up by the new window, which is returned.
|
|
|
|
The optional second argument @var{size} determines the sizes of
|
|
@var{window} and/or the new window. If it is omitted or @code{nil},
|
|
both windows are given equal sizes; if there is an odd line, it is
|
|
allocated to the new window. If @var{size} is a positive number,
|
|
@var{window} is given @var{size} lines (or columns, depending on the
|
|
value of @var{side}). If @var{size} is a negative number, the new
|
|
window is given @minus{}@var{size} lines (or columns).
|
|
|
|
If @var{size} is @code{nil}, this function obeys the variables
|
|
@code{window-min-height} and @code{window-min-width}. @xref{Change
|
|
Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs
|
|
Manual}. Thus, it signals an error if splitting would result in
|
|
making a window smaller than those variables specify. However, a
|
|
non-@code{nil} value for @var{size} causes those variables to be
|
|
ignored; in that case, the smallest allowable window is considered to
|
|
be one that has space for a text area one line tall and/or two columns
|
|
wide.
|
|
|
|
The optional third argument @var{side} determines the position of the
|
|
new window relative to @var{window}. If it is @code{nil} or
|
|
@code{below}, the new window is placed below @var{window}. If it is
|
|
@code{above}, the new window is placed above @var{window}. In both
|
|
these cases, @var{size} specifies a total window height, in lines.
|
|
|
|
If @var{side} is @code{t} or @code{right}, the new window is placed on
|
|
the right of @var{window}. If @var{side} is @code{left}, the new
|
|
window is placed on the left of @var{window}. In both these cases,
|
|
@var{size} specifies a total window width, in columns.
|
|
|
|
If @var{window} is a live window, the new window inherits various
|
|
properties from it, including margins and scroll bars. If
|
|
@var{window} is an internal window, the new window inherits the
|
|
properties of the window selected within @var{window}'s frame.
|
|
|
|
The behavior of this function may be altered by the window parameters
|
|
of @var{window}, so long as the variable
|
|
@code{ignore-window-parameters} is @code{nil}. If the value of
|
|
the @code{split-window} window parameter is @code{t}, this function
|
|
ignores all other window parameters. Otherwise, if the value of the
|
|
@code{split-window} window parameter is a function, that function is
|
|
called with the arguments @var{window}, @var{size}, and @var{side}, in
|
|
lieu of the usual action of @code{split-window}. Otherwise, this
|
|
function obeys the @code{window-atom} or @code{window-side} window
|
|
parameter, if any. @xref{Window Parameters}.
|
|
@end defun
|
|
|
|
As an example, here is a sequence of @code{split-window} calls that
|
|
yields the window configuration discussed in @ref{Windows and Frames}.
|
|
This example demonstrates splitting a live window as well as splitting
|
|
an internal window. We begin with a frame containing a single window
|
|
(a live root window), which we denote by @var{W4}. Calling
|
|
@code{(split-window W4)} yields this window configuration:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W4_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W5_________________||
|
|
|__________________W3__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The @code{split-window} call has created a new live window, denoted by
|
|
@var{W5}. It has also created a new internal window, denoted by
|
|
@var{W3}, which becomes the root window and the parent of both
|
|
@var{W4} and @var{W5}.
|
|
|
|
Next, we call @code{(split-window W3 nil 'left)}, passing the
|
|
internal window @var{W3} as the argument. The result:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ______ ____________________________ |
|
|
|| || __________________________ ||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| |||____________W4____________|||
|
|
|| || __________________________ ||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| |||____________W5____________|||
|
|
||__W2__||_____________W3_____________ |
|
|
|__________________W1__________________|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A new live window @var{W2} is created, to the left of the internal
|
|
window @var{W3}. A new internal window @var{W1} is created, becoming
|
|
the new root window.
|
|
|
|
For interactive use, Emacs provides two commands which always split
|
|
the selected window. These call @code{split-window} internally.
|
|
|
|
@deffn Command split-window-right &optional size
|
|
This function splits the selected window into two side-by-side
|
|
windows, putting the selected window on the left. If @var{size} is
|
|
positive, the left window gets @var{size} columns; if @var{size} is
|
|
negative, the right window gets @minus{}@var{size} columns.
|
|
@end deffn
|
|
|
|
@deffn Command split-window-below &optional size
|
|
This function splits the selected window into two windows, one above
|
|
the other, leaving the upper window selected. If @var{size} is
|
|
positive, the upper window gets @var{size} lines; if @var{size} is
|
|
negative, the lower window gets @minus{}@var{size} lines.
|
|
@end deffn
|
|
|
|
@defopt split-window-keep-point
|
|
If the value of this variable is non-@code{nil} (the default),
|
|
@code{split-window-below} behaves as described above.
|
|
|
|
If it is @code{nil}, @code{split-window-below} adjusts point in each
|
|
of the two windows to minimize redisplay. (This is useful on slow
|
|
terminals.) It selects whichever window contains the screen line that
|
|
point was previously on. Note that this only affects
|
|
@code{split-window-below}, not the lower-level @code{split-window}
|
|
function.
|
|
@end defopt
|
|
|
|
@node Deleting Windows
|
|
@section Deleting Windows
|
|
@cindex deleting windows
|
|
|
|
@dfn{Deleting} a window removes it from the frame's window tree. If
|
|
the window is a live window, it disappears from the screen. If the
|
|
window is an internal window, its child windows are deleted too.
|
|
|
|
Even after a window is deleted, it continues to exist as a Lisp
|
|
object, until there are no more references to it. Window deletion can
|
|
be reversed, by restoring a saved window configuration (@pxref{Window
|
|
Configurations}).
|
|
|
|
@deffn Command delete-window &optional window
|
|
This function removes @var{window} from display and returns
|
|
@code{nil}. If @var{window} is omitted or @code{nil}, it defaults to
|
|
the selected window. If deleting the window would leave no more
|
|
windows in the window tree (e.g., if it is the only live window in the
|
|
frame), an error is signaled.
|
|
|
|
By default, the space taken up by @var{window} is given to one of its
|
|
adjacent sibling windows, if any. However, if the variable
|
|
@code{window-combination-resize} is non-@code{nil}, the space is
|
|
proportionally distributed among any remaining windows in the window
|
|
combination. @xref{Recombining Windows}.
|
|
|
|
The behavior of this function may be altered by the window parameters
|
|
of @var{window}, so long as the variable
|
|
@code{ignore-window-parameters} is @code{nil}. If the value of
|
|
the @code{delete-window} window parameter is @code{t}, this function
|
|
ignores all other window parameters. Otherwise, if the value of the
|
|
@code{delete-window} window parameter is a function, that function is
|
|
called with the argument @var{window}, in lieu of the usual action of
|
|
@code{delete-window}. Otherwise, this function obeys the
|
|
@code{window-atom} or @code{window-side} window parameter, if any.
|
|
@xref{Window Parameters}.
|
|
@end deffn
|
|
|
|
@deffn Command delete-other-windows &optional window
|
|
This function makes @var{window} fill its frame, by deleting other
|
|
windows as necessary. If @var{window} is omitted or @code{nil}, it
|
|
defaults to the selected window. The return value is @code{nil}.
|
|
|
|
The behavior of this function may be altered by the window parameters
|
|
of @var{window}, so long as the variable
|
|
@code{ignore-window-parameters} is @code{nil}. If the value of
|
|
the @code{delete-other-windows} window parameter is @code{t}, this
|
|
function ignores all other window parameters. Otherwise, if the value
|
|
of the @code{delete-other-windows} window parameter is a function,
|
|
that function is called with the argument @var{window}, in lieu of the
|
|
usual action of @code{delete-other-windows}. Otherwise, this function
|
|
obeys the @code{window-atom} or @code{window-side} window parameter,
|
|
if any. @xref{Window Parameters}.
|
|
@end deffn
|
|
|
|
@deffn Command delete-windows-on &optional buffer-or-name frame
|
|
This function deletes all windows showing @var{buffer-or-name}, by
|
|
calling @code{delete-window} on those windows. @var{buffer-or-name}
|
|
should be a buffer, or the name of a buffer; if omitted or @code{nil},
|
|
it defaults to the current buffer. If there are no windows showing
|
|
the specified buffer, this function does nothing. If the specified
|
|
buffer is a minibuffer, an error is signaled.
|
|
|
|
If there is a dedicated window showing the buffer, and that window is
|
|
the only one on its frame, this function also deletes that frame if it
|
|
is not the only frame on the terminal.
|
|
|
|
The optional argument @var{frame} specifies which frames to operate
|
|
on:
|
|
|
|
@itemize @bullet
|
|
@item @code{nil}
|
|
means operate on all frames.
|
|
@item @code{t}
|
|
means operate on the selected frame.
|
|
@item @code{visible}
|
|
means operate on all visible frames.
|
|
@item @code{0}
|
|
means operate on all visible or iconified frames.
|
|
@item A frame
|
|
means operate on that frame.
|
|
@end itemize
|
|
|
|
Note that this argument does not have the same meaning as in other
|
|
functions which scan all live windows (@pxref{Cyclic Window
|
|
Ordering}). Specifically, the meanings of @code{t} and @code{nil} here
|
|
are the opposite of what they are in those other functions.
|
|
@end deffn
|
|
|
|
|
|
@node Recombining Windows
|
|
@section Recombining Windows
|
|
|
|
When deleting the last sibling of a window @var{W}, its parent window
|
|
is deleted too, with @var{W} replacing it in the window tree. This
|
|
means that @var{W} must be recombined with its parent's siblings to
|
|
form a new window combination (@pxref{Windows and Frames}). In some
|
|
occasions, deleting a live window may even entail the deletion of two
|
|
internal windows.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ______ ____________________________ |
|
|
|| || __________________________ ||
|
|
|| ||| ___________ ___________ |||
|
|
|| |||| || ||||
|
|
|| ||||____W6_____||_____W7____||||
|
|
|| |||____________W4____________|||
|
|
|| || __________________________ ||
|
|
|| ||| |||
|
|
|| ||| |||
|
|
|| |||____________W5____________|||
|
|
||__W2__||_____________W3_____________ |
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Deleting @var{W5} in this configuration normally causes the deletion of
|
|
@var{W3} and @var{W4}. The remaining live windows @var{W2},
|
|
@var{W6} and @var{W7} are recombined to form a new horizontal
|
|
combination with parent @var{W1}.
|
|
|
|
Sometimes, however, it makes sense to not delete a parent window like
|
|
@var{W4}. In particular, a parent window should not be removed when it
|
|
was used to preserve a combination embedded in a combination of the same
|
|
type. Such embeddings make sense to assure that when you split a window
|
|
and subsequently delete the new window, Emacs reestablishes the layout
|
|
of the associated frame as it existed before the splitting.
|
|
|
|
Consider a scenario starting with two live windows @var{W2} and
|
|
@var{W3} and their parent @var{W1}.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Split @var{W2} to make a new window @var{W4} as follows.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W4_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Now, when enlarging a window vertically, Emacs tries to obtain the
|
|
corresponding space from its lower sibling, provided such a window
|
|
exists. In our scenario, enlarging @var{W4} will steal space from
|
|
@var{W3}.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W4_________________||
|
|
| ____________________________________ |
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Deleting @var{W4} will now give its entire space to @var{W2},
|
|
including the space earlier stolen from @var{W3}.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This can be counterintuitive, in particular if @var{W4} were used for
|
|
displaying a buffer only temporarily (@pxref{Temporary Displays}), and
|
|
you want to continue working with the initial layout.
|
|
|
|
The behavior can be fixed by making a new parent window when splitting
|
|
@var{W2}. The variable described next allows to do that.
|
|
|
|
@defopt window-combination-limit
|
|
This variable controls whether splitting a window shall make a new
|
|
parent window. The following values are recognized:
|
|
|
|
@table @code
|
|
@item nil
|
|
This means that the new live window is allowed to share the existing
|
|
parent window, if one exists, provided the split occurs in the same
|
|
direction as the existing window combination (otherwise, a new internal
|
|
window is created anyway).
|
|
|
|
@item window-size
|
|
In this case @code{display-buffer} makes a new parent window if it is
|
|
passed a @code{window-height} or @code{window-width} entry in the
|
|
@var{alist} argument (@pxref{Display Action Functions}).
|
|
|
|
@item temp-buffer
|
|
This value causes the creation of a new parent window when a window is
|
|
split for showing a temporary buffer (@pxref{Temporary Displays}) only.
|
|
|
|
@item display-buffer
|
|
This means that when @code{display-buffer} (@pxref{Choosing Window})
|
|
splits a window it always makes a new parent window.
|
|
|
|
@item t
|
|
In this case a new parent window is always created when splitting a
|
|
window. Thus, if the value of this variable is at all times @code{t},
|
|
then at all times every window tree is a binary tree (a tree where each
|
|
window except the root window has exactly one sibling).
|
|
@end table
|
|
|
|
The default is @code{nil}. Other values are reserved for future use.
|
|
|
|
If, as a consequence of this variable's setting, @code{split-window}
|
|
makes a new parent window, it also calls
|
|
@code{set-window-combination-limit} (see below) on the newly-created
|
|
internal window. This affects how the window tree is rearranged when
|
|
the child windows are deleted (see below).
|
|
@end defopt
|
|
|
|
If @code{window-combination-limit} is @code{t}, splitting @var{W2} in
|
|
the initial configuration of our scenario would have produced this:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| __________________________________ ||
|
|
||| |||
|
|
|||________________W2________________|||
|
|
|| __________________________________ ||
|
|
||| |||
|
|
|||________________W4________________|||
|
|
||_________________W5_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
A new internal window @var{W5} has been created; its children are
|
|
@var{W2} and the new live window @var{W4}. Now, @var{W2} is the only
|
|
sibling of @var{W4}, so enlarging @var{W4} will try to shrink
|
|
@var{W2}, leaving @var{W3} unaffected. Observe that @var{W5}
|
|
represents a vertical combination of two windows embedded in the
|
|
vertical combination @var{W1}.
|
|
|
|
@cindex window combination limit
|
|
@defun set-window-combination-limit window limit
|
|
This functions sets the @dfn{combination limit} of the window
|
|
@var{window} to @var{limit}. This value can be retrieved via the
|
|
function @code{window-combination-limit}. See below for its effects;
|
|
note that it is only meaningful for internal windows. The
|
|
@code{split-window} function automatically calls this function, passing
|
|
it @code{t} as @var{limit}, provided the value of the variable
|
|
@code{window-combination-limit} is @code{t} when it is called.
|
|
@end defun
|
|
|
|
@defun window-combination-limit window
|
|
This function returns the combination limit for @var{window}.
|
|
|
|
The combination limit is meaningful only for an internal window. If it
|
|
is @code{nil}, then Emacs is allowed to automatically delete
|
|
@var{window}, in response to a window deletion, in order to group the
|
|
child windows of @var{window} with its sibling windows to form a new
|
|
window combination. If the combination limit is @code{t}, the child
|
|
windows of @var{window} are never automatically recombined with its
|
|
siblings.
|
|
|
|
If, in the configuration shown at the beginning of this section, the
|
|
combination limit of @var{W4} (the parent window of @var{W6} and
|
|
@var{W7}) is @code{t}, deleting @var{W5} will not implicitly delete
|
|
@var{W4} too.
|
|
@end defun
|
|
|
|
Alternatively, the problems sketched above can be avoided by always
|
|
resizing all windows in the same combination whenever one of its windows
|
|
is split or deleted. This also permits to split windows that would be
|
|
otherwise too small for such an operation.
|
|
|
|
@defopt window-combination-resize
|
|
If this variable is @code{nil}, @code{split-window} can only split a
|
|
window (denoted by @var{window}) if @var{window}'s screen area is large
|
|
enough to accommodate both itself and the new window.
|
|
|
|
If this variable is @code{t}, @code{split-window} tries to resize all
|
|
windows that are part of the same combination as @var{window}, in order
|
|
to accommodate the new window. In particular, this may allow
|
|
@code{split-window} to succeed even if @var{window} is a fixed-size
|
|
window or too small to ordinarily split. Furthermore, subsequently
|
|
resizing or deleting @var{window} may resize all other windows in its
|
|
combination.
|
|
|
|
The default is @code{nil}. Other values are reserved for future use.
|
|
The value of this variable is ignored when
|
|
@code{window-combination-limit} is non-@code{nil}.
|
|
@end defopt
|
|
|
|
To illustrate the effect of @code{window-combination-resize}, consider
|
|
the following frame layout.
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W3_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If @code{window-combination-resize} is @code{nil}, splitting window
|
|
@var{W3} leaves the size of @var{W2} unchanged:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
||_________________W3_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
||_________________W4_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
If @code{window-combination-resize} is @code{t}, splitting @var{W3}
|
|
instead leaves all three live windows with approximately the same
|
|
height:
|
|
|
|
@smallexample
|
|
@group
|
|
______________________________________
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W2_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W3_________________||
|
|
| ____________________________________ |
|
|
|| ||
|
|
|| ||
|
|
||_________________W4_________________||
|
|
|__________________W1__________________|
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Deleting any of the live windows @var{W2}, @var{W3} or @var{W4} will
|
|
distribute its space proportionally among the two remaining live
|
|
windows.
|
|
|
|
|
|
@node Selecting Windows
|
|
@section Selecting Windows
|
|
@cindex selecting a window
|
|
|
|
@defun select-window window &optional norecord
|
|
This function makes @var{window} the selected window and the window
|
|
selected within its frame (@pxref{Basic Windows}) and selects that
|
|
frame. @var{window} must be a live window. This function also makes
|
|
@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets
|
|
that buffer's value of @code{point} to the value of @code{window-point}
|
|
(@pxref{Window Point}) in @var{window}. The return value is
|
|
@var{window}.
|
|
|
|
By default, this function also moves @var{window}'s buffer to the front
|
|
of the buffer list (@pxref{The Buffer List}), and makes @var{window} the
|
|
most recently selected window. However, if the optional argument
|
|
@var{norecord} is non-@code{nil}, these additional actions are omitted.
|
|
@end defun
|
|
|
|
@cindex most recently selected windows
|
|
The sequence of calls to @code{select-window} with a non-@code{nil}
|
|
@var{norecord} argument determines an ordering of windows by their
|
|
selection time. The function @code{get-lru-window} can be used to
|
|
retrieve the least recently selected live window (@pxref{Cyclic Window
|
|
Ordering}).
|
|
|
|
@defmac save-selected-window forms@dots{}
|
|
This macro records the selected frame, as well as the selected window
|
|
of each frame, executes @var{forms} in sequence, then restores the
|
|
earlier selected frame and windows. It also saves and restores the
|
|
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 @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}, 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}.
|
|
|
|
This macro does not change the order of recently selected windows or
|
|
the buffer list.
|
|
@end defmac
|
|
|
|
@defun frame-selected-window &optional frame
|
|
This function returns the window on @var{frame} that is selected
|
|
within that frame. @var{frame} should be a live frame; if omitted or
|
|
@code{nil}, it defaults to the selected frame.
|
|
@end defun
|
|
|
|
@defun set-frame-selected-window frame window &optional norecord
|
|
This function makes @var{window} the window selected within the frame
|
|
@var{frame}. @var{frame} should be a live frame; if @code{nil}, it
|
|
defaults to the selected frame. @var{window} should be a live window;
|
|
if @code{nil}, it defaults to the selected window.
|
|
|
|
If @var{frame} is the selected frame, this makes @var{window} the
|
|
selected window.
|
|
|
|
If the optional argument @var{norecord} is non-@code{nil}, this
|
|
function does not alter the list of most recently selected windows,
|
|
nor the buffer list.
|
|
@end defun
|
|
|
|
@node Cyclic Window Ordering
|
|
@section Cyclic Ordering of Windows
|
|
@cindex cyclic ordering of windows
|
|
@cindex ordering of windows, cyclic
|
|
@cindex window ordering, cyclic
|
|
|
|
When you use the command @kbd{C-x o} (@code{other-window}) to select
|
|
some other window, it moves through live windows in a specific order.
|
|
For any given configuration of windows, this order never varies. It
|
|
is called the @dfn{cyclic ordering of windows}.
|
|
|
|
The ordering is determined by a depth-first traversal of the frame's
|
|
window tree, retrieving the live windows which are the leaf nodes of
|
|
the tree (@pxref{Windows and Frames}). If the minibuffer is active,
|
|
the minibuffer window is included too. The ordering is cyclic, so the
|
|
last window in the sequence is followed by the first one.
|
|
|
|
@defun next-window &optional window minibuf all-frames
|
|
@cindex minibuffer window, and @code{next-window}
|
|
This function returns a live window, the one following @var{window} in
|
|
the cyclic ordering of windows. @var{window} should be a live window;
|
|
if omitted or @code{nil}, it defaults to the selected window.
|
|
|
|
The optional argument @var{minibuf} specifies whether minibuffer windows
|
|
should be included in the cyclic ordering. Normally, when @var{minibuf}
|
|
is @code{nil}, a minibuffer window is included only if it is currently
|
|
``active''; this matches the behavior of @kbd{C-x o}. (Note that a
|
|
minibuffer window is active as long as its minibuffer is in use; see
|
|
@ref{Minibuffers}).
|
|
|
|
If @var{minibuf} is @code{t}, the cyclic ordering includes all
|
|
minibuffer windows. If @var{minibuf} is neither @code{t} nor
|
|
@code{nil}, minibuffer windows are not included even if they are active.
|
|
|
|
The optional argument @var{all-frames} specifies which frames to
|
|
consider:
|
|
|
|
@itemize @bullet
|
|
@item @code{nil}
|
|
means to consider windows on @var{window}'s frame. If the minibuffer
|
|
window is considered (as specified by the @var{minibuf} argument),
|
|
then frames that share the minibuffer window are considered too.
|
|
|
|
@item @code{t}
|
|
means to consider windows on all existing frames.
|
|
|
|
@item @code{visible}
|
|
means to consider windows on all visible frames.
|
|
|
|
@item 0
|
|
means to consider windows on all visible or iconified frames.
|
|
|
|
@item A frame
|
|
means to consider windows on that specific frame.
|
|
|
|
@item Anything else
|
|
means to consider windows on @var{window}'s frame, and no others.
|
|
@end itemize
|
|
|
|
If more than one frame is considered, the cyclic ordering is obtained
|
|
by appending the orderings for those frames, in the same order as the
|
|
list of all live frames (@pxref{Finding All Frames}).
|
|
@end defun
|
|
|
|
@defun previous-window &optional window minibuf all-frames
|
|
This function returns a live window, the one preceding @var{window} in
|
|
the cyclic ordering of windows. The other arguments are handled like
|
|
in @code{next-window}.
|
|
@end defun
|
|
|
|
@deffn Command other-window count &optional all-frames
|
|
This function selects a live window, one @var{count} places from the
|
|
selected window in the cyclic ordering of windows. If @var{count} is
|
|
a positive number, it skips @var{count} windows forwards; if
|
|
@var{count} is negative, it skips @minus{}@var{count} windows
|
|
backwards; if @var{count} is zero, that simply re-selects the selected
|
|
window. When called interactively, @var{count} is the numeric prefix
|
|
argument.
|
|
|
|
The optional argument @var{all-frames} has the same meaning as in
|
|
@code{next-window}, like a @code{nil} @var{minibuf} argument to
|
|
@code{next-window}.
|
|
|
|
This function does not select a window that has a non-@code{nil}
|
|
@code{no-other-window} window parameter (@pxref{Window Parameters}).
|
|
@end deffn
|
|
|
|
@defun walk-windows fun &optional minibuf all-frames
|
|
This function calls the function @var{fun} once for each live window,
|
|
with the window as the argument.
|
|
|
|
It follows the cyclic ordering of windows. The optional arguments
|
|
@var{minibuf} and @var{all-frames} specify the set of windows
|
|
included; these have the same arguments as in @code{next-window}. If
|
|
@var{all-frames} specifies a frame, the first window walked is the
|
|
first window on that frame (the one returned by
|
|
@code{frame-first-window}), not necessarily the selected window.
|
|
|
|
If @var{fun} changes the window configuration by splitting or deleting
|
|
windows, that does not alter the set of windows walked, which is
|
|
determined prior to calling @var{fun} for the first time.
|
|
@end defun
|
|
|
|
@defun one-window-p &optional no-mini all-frames
|
|
This function returns @code{t} if the selected window is the only live
|
|
window, and @code{nil} otherwise.
|
|
|
|
If the minibuffer window is active, it is normally considered (so that
|
|
this function returns @code{nil}). However, if the optional argument
|
|
@var{no-mini} is non-@code{nil}, the minibuffer window is ignored even
|
|
if active. The optional argument @var{all-frames} has the same
|
|
meaning as for @code{next-window}.
|
|
@end defun
|
|
|
|
@cindex finding windows
|
|
The following functions return a window which satisfies some
|
|
criterion, without selecting it:
|
|
|
|
@cindex least recently used window
|
|
@defun get-lru-window &optional all-frames dedicated not-selected
|
|
This function returns a live window which is heuristically the ``least
|
|
recently used'' window. The optional argument @var{all-frames} has
|
|
the same meaning as in @code{next-window}.
|
|
|
|
If any full-width windows are present, only those windows are
|
|
considered. 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 selected
|
|
window is never returned, unless it is the only candidate. However, if
|
|
the optional argument @var{not-selected} is non-@code{nil}, this
|
|
function returns @code{nil} in that case.
|
|
@end defun
|
|
|
|
@cindex largest window
|
|
@defun get-largest-window &optional all-frames dedicated not-selected
|
|
This function returns the window with the largest area (height times
|
|
width). The optional argument @var{all-frames} specifies the windows to
|
|
search, and has the same meaning as in @code{next-window}.
|
|
|
|
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 selected window is not
|
|
a candidate if the optional argument @var{not-selected} is
|
|
non-@code{nil}. If the optional argument @var{not-selected} is
|
|
non-@code{nil} and the selected window is the only candidate, this
|
|
function returns @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,
|
|
starting from the selected window.
|
|
@end defun
|
|
|
|
@cindex window that satisfies a predicate
|
|
@cindex conditional selection of windows
|
|
@defun get-window-with-predicate predicate &optional minibuf all-frames default
|
|
This function calls the function @var{predicate} for each of the
|
|
windows in the cyclic order of windows in turn, passing it the window
|
|
as an argument. If the predicate returns non-@code{nil} for any
|
|
window, this function stops and returns that window. If no such
|
|
window is found, the return value is @var{default} (which defaults to
|
|
@code{nil}).
|
|
|
|
The optional arguments @var{minibuf} and @var{all-frames} specify the
|
|
windows to search, and have the same meanings as in
|
|
@code{next-window}.
|
|
@end defun
|
|
|
|
|
|
@node Buffers and Windows
|
|
@section Buffers and Windows
|
|
@cindex examining windows
|
|
@cindex windows, controlling precisely
|
|
@cindex buffers, controlled in windows
|
|
|
|
This section describes low-level functions for examining and setting
|
|
the contents of windows. @xref{Switching Buffers}, for higher-level
|
|
functions for displaying a specific buffer in a window.
|
|
|
|
@defun window-buffer &optional window
|
|
This function returns the buffer that @var{window} is displaying. If
|
|
@var{window} is omitted or @code{nil} it defaults to the selected
|
|
window. If @var{window} is an internal window, this function returns
|
|
@code{nil}.
|
|
@end defun
|
|
|
|
@defun set-window-buffer window buffer-or-name &optional keep-margins
|
|
This function makes @var{window} display @var{buffer-or-name}.
|
|
@var{window} should be a live window; if @code{nil}, it defaults to
|
|
the selected window. @var{buffer-or-name} should be a buffer, or the
|
|
name of an existing buffer. This function does not change which
|
|
window is selected, nor does it directly change which buffer is
|
|
current (@pxref{Current Buffer}). Its return value is @code{nil}.
|
|
|
|
If @var{window} is @dfn{strongly dedicated} to a buffer and
|
|
@var{buffer-or-name} does not specify that buffer, this function
|
|
signals an error. @xref{Dedicated Windows}.
|
|
|
|
By default, this function resets @var{window}'s position, display
|
|
margins, fringe widths, and scroll bar settings, based on the local
|
|
variables in the specified buffer. However, if the optional argument
|
|
@var{keep-margins} is non-@code{nil}, it leaves the display margins
|
|
and fringe widths unchanged.
|
|
|
|
When writing an application, you should normally use the higher-level
|
|
functions described in @ref{Switching Buffers}, instead of calling
|
|
@code{set-window-buffer} directly.
|
|
|
|
This runs @code{window-scroll-functions}, followed by
|
|
@code{window-configuration-change-hook}. @xref{Window Hooks}.
|
|
@end defun
|
|
|
|
@defvar buffer-display-count
|
|
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
|
|
|
|
@defvar buffer-display-time
|
|
This buffer-local variable records the time at which a buffer was last
|
|
displayed in a window. The value is @code{nil} if the buffer has
|
|
never been displayed. It is updated each time
|
|
@code{set-window-buffer} is called for the buffer, with the value
|
|
returned by @code{current-time} (@pxref{Time of Day}).
|
|
@end defvar
|
|
|
|
@defun get-buffer-window &optional buffer-or-name all-frames
|
|
This function returns the first window displaying @var{buffer-or-name}
|
|
in the cyclic ordering of windows, starting from the selected window
|
|
(@pxref{Cyclic Window Ordering}). If no such window exists, the
|
|
return value is @code{nil}.
|
|
|
|
@var{buffer-or-name} should be a buffer or the name of a buffer; if
|
|
omitted or @code{nil}, it defaults to the current buffer. The
|
|
optional argument @var{all-frames} specifies which windows to
|
|
consider:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{t} means consider windows on all existing frames.
|
|
@item
|
|
@code{visible} means consider windows on all visible frames.
|
|
@item
|
|
0 means consider windows on all visible or iconified frames.
|
|
@item
|
|
A frame means consider windows on that frame only.
|
|
@item
|
|
Any other value means consider windows on the selected frame.
|
|
@end itemize
|
|
|
|
Note that these meanings differ slightly from those of the
|
|
@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
|
|
Ordering}). This function may be changed in a future version of Emacs
|
|
to eliminate this discrepancy.
|
|
@end defun
|
|
|
|
@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}. @var{buffer-or-name} should be a buffer or the
|
|
name of an existing buffer. If omitted or @code{nil}, it defaults to
|
|
the current buffer.
|
|
|
|
The arguments @var{minibuf} and @var{all-frames} have the same
|
|
meanings as in the function @code{next-window} (@pxref{Cyclic Window
|
|
Ordering}). Note that the @var{all-frames} argument does @emph{not}
|
|
behave exactly like in @code{get-buffer-window}.
|
|
@end defun
|
|
|
|
@deffn Command replace-buffer-in-windows &optional buffer-or-name
|
|
This command replaces @var{buffer-or-name} with some other buffer, in
|
|
all windows displaying it. @var{buffer-or-name} should be a buffer, or
|
|
the name of an existing buffer; if omitted or @code{nil}, it defaults to
|
|
the current buffer.
|
|
|
|
The replacement buffer in each window is chosen via
|
|
@code{switch-to-prev-buffer} (@pxref{Window History}). Any dedicated
|
|
window displaying @var{buffer-or-name} is deleted if possible
|
|
(@pxref{Dedicated Windows}). If such a window is the only window on its
|
|
frame and there are other frames on the same terminal, the frame is
|
|
deleted as well. If the dedicated window is the only window on the only
|
|
frame on its terminal, the buffer is replaced anyway.
|
|
@end deffn
|
|
|
|
|
|
@node Switching Buffers
|
|
@section Switching to a Buffer in a Window
|
|
@cindex switching to a buffer
|
|
@cindex displaying a buffer
|
|
|
|
This section describes high-level functions for switching to a specified
|
|
buffer in some window. In general, ``switching to a buffer'' means to
|
|
(1) show the buffer in some window, (2) make that window the selected
|
|
window (and its frame the selected frame), and (3) make the buffer the
|
|
current buffer.
|
|
|
|
Do @emph{not} use these functions to make a buffer temporarily
|
|
current just so a Lisp program can access or modify it. They have
|
|
side-effects, such as changing window histories (@pxref{Window
|
|
History}), which will surprise the user if used that way. If you want
|
|
to make a buffer current to modify it in Lisp, use
|
|
@code{with-current-buffer}, @code{save-current-buffer}, or
|
|
@code{set-buffer}. @xref{Current Buffer}.
|
|
|
|
@deffn Command switch-to-buffer buffer-or-name &optional norecord force-same-window
|
|
This command attempts to display @var{buffer-or-name} in the selected
|
|
window and make it the current buffer. It is often used interactively
|
|
(as the binding of @kbd{C-x b}), as well as in Lisp programs. The
|
|
return value is the buffer switched to.
|
|
|
|
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
|
|
returned by @code{other-buffer} (@pxref{The Buffer List}). If
|
|
@var{buffer-or-name} is a string that is not the name of any existing
|
|
buffer, this function creates a new buffer with that name; the new
|
|
buffer's major mode is determined by the variable @code{major-mode}
|
|
(@pxref{Major Modes}).
|
|
|
|
Normally, the specified buffer is put at the front of the buffer
|
|
list---both the global buffer list and the selected frame's buffer
|
|
list (@pxref{The Buffer List}). However, this is not done if the
|
|
optional argument @var{norecord} is non-@code{nil}.
|
|
|
|
Sometimes, @code{switch-to-buffer} may be unable to display the buffer
|
|
in the selected window. This happens if the selected window is a
|
|
minibuffer window, or if the selected window is strongly dedicated to
|
|
its buffer (@pxref{Dedicated Windows}). In that case, the command
|
|
normally tries to display the buffer in some other window, by invoking
|
|
@code{pop-to-buffer} (see below). However, if the optional argument
|
|
@var{force-same-window} is non-@code{nil}, it signals an error
|
|
instead.
|
|
@end deffn
|
|
|
|
By default, @code{switch-to-buffer} shows the buffer at its position of
|
|
@code{point}. This behavior can be tuned using the following option.
|
|
|
|
@defopt switch-to-buffer-preserve-window-point
|
|
If this variable is @code{nil}, @code{switch-to-buffer} displays the
|
|
buffer specified by @var{buffer-or-name} at the position of that
|
|
buffer's @code{point}. If this variable is @code{already-displayed}, it
|
|
tries to display the buffer at its previous position in the selected
|
|
window, provided the buffer is currently displayed in some other window
|
|
on any visible or iconified frame. If this variable is @code{t},
|
|
@code{switch-to-buffer} unconditionally tries to display the buffer at
|
|
its previous position in the selected window.
|
|
|
|
This variable is ignored if the buffer is already displayed in the
|
|
selected window or never appeared in it before, or if
|
|
@code{switch-to-buffer} calls @code{pop-to-buffer} to display the
|
|
buffer.
|
|
@end defopt
|
|
|
|
The next two commands are similar to @code{switch-to-buffer}, except for
|
|
the described features.
|
|
|
|
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
|
|
This function displays the buffer specified by @var{buffer-or-name} in
|
|
some window other than the selected window. It uses the function
|
|
@code{pop-to-buffer} internally (see below).
|
|
|
|
If the selected window already displays the specified buffer, it
|
|
continues to do so, but another window is nonetheless found to display
|
|
it as well.
|
|
|
|
The @var{buffer-or-name} and @var{norecord} arguments have the same
|
|
meanings as in @code{switch-to-buffer}.
|
|
@end deffn
|
|
|
|
@deffn Command switch-to-buffer-other-frame buffer-or-name &optional norecord
|
|
This function displays the buffer specified by @var{buffer-or-name} in a
|
|
new frame. It uses the function @code{pop-to-buffer} internally (see
|
|
below).
|
|
|
|
If the specified buffer is already displayed in another window, in any
|
|
frame on the current terminal, this switches to that window instead of
|
|
creating a new frame. However, the selected window is never used for
|
|
this.
|
|
|
|
The @var{buffer-or-name} and @var{norecord} arguments have the same
|
|
meanings as in @code{switch-to-buffer}.
|
|
@end deffn
|
|
|
|
The above commands use the function @code{pop-to-buffer}, which
|
|
flexibly displays a buffer in some window and selects that window for
|
|
editing. In turn, @code{pop-to-buffer} uses @code{display-buffer} for
|
|
displaying the buffer. Hence, all the variables affecting
|
|
@code{display-buffer} will affect it as well. @xref{Choosing Window},
|
|
for the documentation of @code{display-buffer}.
|
|
|
|
@deffn Command pop-to-buffer buffer-or-name &optional action norecord
|
|
This function makes @var{buffer-or-name} the current buffer and
|
|
displays it in some window, preferably not the window previously
|
|
selected. It then selects the displaying window. If that window is
|
|
on a different graphical frame, that frame is given input focus if
|
|
possible (@pxref{Input Focus}). The return value is the buffer that
|
|
was switched to.
|
|
|
|
If @var{buffer-or-name} is @code{nil}, it defaults to the buffer
|
|
returned by @code{other-buffer} (@pxref{The Buffer List}). If
|
|
@var{buffer-or-name} is a string that is not the name of any existing
|
|
buffer, this function creates a new buffer with that name; the new
|
|
buffer's major mode is determined by the variable @code{major-mode}
|
|
(@pxref{Major Modes}).
|
|
|
|
If @var{action} is non-@code{nil}, it should be a display action to
|
|
pass to @code{display-buffer} (@pxref{Choosing Window}).
|
|
Alternatively, a non-@code{nil}, non-list value means to pop to a
|
|
window other than the selected one---even if the buffer is already
|
|
displayed in the selected window.
|
|
|
|
Like @code{switch-to-buffer}, this function updates the buffer list
|
|
unless @var{norecord} is non-@code{nil}.
|
|
@end deffn
|
|
|
|
|
|
@node Choosing Window
|
|
@section Choosing a Window for Display
|
|
|
|
The command @code{display-buffer} flexibly chooses a window for
|
|
display, and displays a specified buffer in that window. It can be
|
|
called interactively, via the key binding @kbd{C-x 4 C-o}. It is also
|
|
used as a subroutine by many functions and commands, including
|
|
@code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching
|
|
Buffers}).
|
|
|
|
@cindex display action
|
|
@cindex action function, for @code{display-buffer}
|
|
@cindex action alist, for @code{display-buffer}
|
|
This command performs several complex steps to find a window to
|
|
display in. These steps are described by means of @dfn{display
|
|
actions}, which have the form @code{(@var{function} . @var{alist})}.
|
|
Here, @var{function} is either a function or a list of functions,
|
|
which we refer to as @dfn{action functions}; @var{alist} is an
|
|
association list, which we refer to as @dfn{action alists}.
|
|
|
|
An action function accepts two arguments: the buffer to display and
|
|
an action alist. It attempts to display the buffer in some window,
|
|
picking or creating a window according to its own criteria. If
|
|
successful, it returns the window; otherwise, it returns @code{nil}.
|
|
@xref{Display Action Functions}, for a list of predefined action
|
|
functions.
|
|
|
|
@code{display-buffer} works by combining display actions from
|
|
several sources, and calling the action functions in turn, until one
|
|
of them manages to display the buffer and returns a non-@code{nil}
|
|
value.
|
|
|
|
@deffn Command display-buffer buffer-or-name &optional action frame
|
|
This command makes @var{buffer-or-name} appear in some window, without
|
|
selecting the window or making the buffer current. The argument
|
|
@var{buffer-or-name} must be a buffer or the name of an existing
|
|
buffer. The return value is the window chosen to display the buffer.
|
|
|
|
The optional argument @var{action}, if non-@code{nil}, should normally
|
|
be a display action (described above). @code{display-buffer} builds a
|
|
list of action functions and an action alist, by consolidating display
|
|
actions from the following sources (in order):
|
|
|
|
@itemize
|
|
@item
|
|
The variable @code{display-buffer-overriding-action}.
|
|
|
|
@item
|
|
The user option @code{display-buffer-alist}.
|
|
|
|
@item
|
|
The @var{action} argument.
|
|
|
|
@item
|
|
The user option @code{display-buffer-base-action}.
|
|
|
|
@item
|
|
The constant @code{display-buffer-fallback-action}.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Each action function is called in turn, passing the buffer as the
|
|
first argument and the combined action alist as the second argument,
|
|
until one of the functions returns non-@code{nil}.
|
|
|
|
The argument @var{action} can also have a non-@code{nil}, non-list
|
|
value. This has the special meaning that the buffer should be
|
|
displayed in a window other than the selected one, even if the
|
|
selected window is already displaying it. If called interactively
|
|
with a prefix argument, @var{action} is @code{t}.
|
|
|
|
The optional argument @var{frame}, if non-@code{nil}, specifies which
|
|
frames to check when deciding whether the buffer is already displayed.
|
|
It is equivalent to adding an element @code{(reusable-frames
|
|
. @var{frame})} to the action alist of @var{action}. @xref{Display
|
|
Action Functions}.
|
|
@end deffn
|
|
|
|
@defvar display-buffer-overriding-action
|
|
The value of this variable should be a display action, which is
|
|
treated with the highest priority by @code{display-buffer}. The
|
|
default value is empty, i.e., @code{(nil . nil)}.
|
|
@end defvar
|
|
|
|
@defopt display-buffer-alist
|
|
The value of this option is an alist mapping conditions to display
|
|
actions. Each condition may be either a regular expression matching a
|
|
buffer name or a function that takes two arguments: a buffer name and
|
|
the @var{action} argument passed to @code{display-buffer}. If the name
|
|
of the buffer passed to @code{display-buffer} either matches a regular
|
|
expression in this alist or the function specified by a condition
|
|
returns non-@code{nil}, then @code{display-buffer} uses the
|
|
corresponding display action to display the buffer.
|
|
@end defopt
|
|
|
|
@defopt display-buffer-base-action
|
|
The value of this option should be a display action. This option can
|
|
be used to define a ``standard'' display action for calls to
|
|
@code{display-buffer}.
|
|
@end defopt
|
|
|
|
@defvr Constant display-buffer-fallback-action
|
|
This display action specifies the fallback behavior for
|
|
@code{display-buffer} if no other display actions are given.
|
|
@end defvr
|
|
|
|
|
|
@node Display Action Functions
|
|
@section Action Functions for @code{display-buffer}
|
|
|
|
The following basic action functions are defined in Emacs. Each of
|
|
these functions takes two arguments: @var{buffer}, the buffer to
|
|
display, and @var{alist}, an action alist. Each action function
|
|
returns the window if it succeeds, and @code{nil} if it fails.
|
|
|
|
@defun display-buffer-same-window buffer alist
|
|
This function tries to display @var{buffer} in the selected window.
|
|
It fails if the selected window is a minibuffer window or is dedicated
|
|
to another buffer (@pxref{Dedicated Windows}). It also fails if
|
|
@var{alist} has a non-@code{nil} @code{inhibit-same-window} entry.
|
|
@end defun
|
|
|
|
@defun display-buffer-reuse-window buffer alist
|
|
This function tries to ``display'' @var{buffer} by finding a window
|
|
that is already displaying it.
|
|
|
|
If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry,
|
|
the selected window is not eligible for reuse. If @var{alist}
|
|
contains a @code{reusable-frames} entry, its value determines which
|
|
frames to search for a reusable window:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{nil} means consider windows on the selected frame.
|
|
(Actually, the last non-minibuffer frame.)
|
|
@item
|
|
@code{t} means consider windows on all frames.
|
|
@item
|
|
@code{visible} means consider windows on all visible frames.
|
|
@item
|
|
0 means consider windows on all visible or iconified frames.
|
|
@item
|
|
A frame means consider windows on that frame only.
|
|
@end itemize
|
|
|
|
Note that these meanings differ slightly from those of the
|
|
@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window
|
|
Ordering}).
|
|
|
|
If @var{alist} contains no @code{reusable-frames} entry, this function
|
|
normally searches just the selected frame; however, if the variable
|
|
@code{pop-up-frames} is non-@code{nil}, it searches all frames on the
|
|
current terminal. @xref{Choosing Window Options}.
|
|
|
|
If this function chooses a window on another frame, it makes that frame
|
|
visible and, unless @var{alist} contains an @code{inhibit-switch-frame}
|
|
entry (@pxref{Choosing Window Options}), raises that frame if necessary.
|
|
@end defun
|
|
|
|
@defun display-buffer-pop-up-frame buffer alist
|
|
This function creates a new frame, and displays the buffer in that
|
|
frame's window. It actually performs the frame creation by calling
|
|
the function specified in @code{pop-up-frame-function}
|
|
(@pxref{Choosing Window Options}). If @var{alist} contains a
|
|
@code{pop-up-frame-parameters} entry, the associated value
|
|
is added to the newly created frame's parameters.
|
|
@end defun
|
|
|
|
@defun display-buffer-pop-up-window buffer alist
|
|
This function tries to display @var{buffer} by splitting the largest
|
|
or least recently-used window (typically one on the selected frame).
|
|
It actually performs the split by calling the function specified in
|
|
@code{split-window-preferred-function} (@pxref{Choosing Window
|
|
Options}).
|
|
|
|
The size of the new window can be adjusted by supplying
|
|
@code{window-height} and @code{window-width} entries in @var{alist}. To
|
|
adjust the window's height, use an entry whose @sc{car} is
|
|
@code{window-height} and whose @sc{cdr} is one of:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{nil} means to leave the height of the new window alone.
|
|
|
|
@item
|
|
A number specifies the desired height of the new window. An integer
|
|
number specifies the number of lines of the window. A floating point
|
|
number gives the fraction of the window's height with respect to the
|
|
height of the frame's root window.
|
|
|
|
@item
|
|
If the @sc{cdr} specifies a function, that function is called with one
|
|
argument: the new window. The function is supposed to adjust the
|
|
height of the window; its return value is ignored. Suitable functions
|
|
are @code{shrink-window-if-larger-than-buffer} and
|
|
@code{fit-window-to-buffer}, see @ref{Resizing Windows}.
|
|
@end itemize
|
|
|
|
To adjust the window's width, use an entry whose @sc{car} is
|
|
@code{window-width} and whose @sc{cdr} is one of:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{nil} means to leave the width of the new window alone.
|
|
|
|
@item
|
|
A number specifies the desired width of the new window. An integer
|
|
number specifies the number of columns of the window. A floating point
|
|
number gives the fraction of the window's width with respect to the
|
|
width of the frame's root window.
|
|
|
|
@item
|
|
If the @sc{cdr} specifies a function, that function is called with one
|
|
argument: the new window. The function is supposed to adjust the width
|
|
of the window; its return value is ignored.
|
|
@end itemize
|
|
|
|
This function can fail if no window splitting can be performed for some
|
|
reason (e.g., if the selected frame has an @code{unsplittable} frame
|
|
parameter; @pxref{Buffer Parameters}).
|
|
@end defun
|
|
|
|
@defun display-buffer-below-selected buffer alist
|
|
This function tries to display @var{buffer} in a window below the
|
|
selected window. This means to either split the selected window or use
|
|
the window below the selected one. If it does create a new window, it
|
|
will also adjust its size provided @var{alist} contains a suitable
|
|
@code{window-height} or @code{window-width} entry, see above.
|
|
@end defun
|
|
|
|
@defun display-buffer-in-previous-window buffer alist
|
|
This function tries to display @var{buffer} in a window previously
|
|
showing it. If @var{alist} has a non-@code{nil}
|
|
@code{inhibit-same-window} entry, the selected window is not eligible
|
|
for reuse. If @var{alist} contains a @code{reusable-frames} entry, its
|
|
value determines which frames to search for a suitable window as with
|
|
@code{display-buffer-reuse-window}.
|
|
|
|
If @var{alist} has a @code{previous-window} entry, the window
|
|
specified by that entry will override any other window found by the
|
|
methods above, even if that window never showed @var{buffer} before.
|
|
@end defun
|
|
|
|
@defun display-buffer-use-some-window buffer alist
|
|
This function tries to display @var{buffer} by choosing an existing
|
|
window and displaying the buffer in that window. It can fail if all
|
|
windows are dedicated to another buffer (@pxref{Dedicated Windows}).
|
|
@end defun
|
|
|
|
To illustrate the use of action functions, consider the following
|
|
example.
|
|
|
|
@example
|
|
@group
|
|
(display-buffer
|
|
(get-buffer-create "*foo*")
|
|
'((display-buffer-reuse-window
|
|
display-buffer-pop-up-window
|
|
display-buffer-pop-up-frame)
|
|
(reusable-frames . 0)
|
|
(window-height . 10) (window-width . 40)))
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
Evaluating the form above will cause @code{display-buffer} to proceed as
|
|
follows: If a buffer called *foo* already appears on a visible or
|
|
iconified frame, it will reuse its window. Otherwise, it will try to
|
|
pop up a new window or, if that is impossible, a new frame and show the
|
|
buffer there. If all these steps fail, it will proceed using whatever
|
|
@code{display-buffer-base-action} and
|
|
@code{display-buffer-fallback-action} prescribe.
|
|
|
|
Furthermore, @code{display-buffer} will try to adjust a reused window
|
|
(provided *foo* was put by @code{display-buffer} there before) or a
|
|
popped-up window as follows: If the window is part of a vertical
|
|
combination, it will set its height to ten lines. Note that if, instead
|
|
of the number ``10'', we specified the function
|
|
@code{fit-window-to-buffer}, @code{display-buffer} would come up with a
|
|
one-line window to fit the empty buffer. If the window is part of a
|
|
horizontal combination, it sets its width to 40 columns. Whether a new
|
|
window is vertically or horizontally combined depends on the shape of
|
|
the window split and the values of
|
|
@code{split-window-preferred-function}, @code{split-height-threshold}
|
|
and @code{split-width-threshold} (@pxref{Choosing Window Options}).
|
|
|
|
Now suppose we combine this call with a preexisting setup for
|
|
`display-buffer-alist' as follows.
|
|
|
|
@example
|
|
@group
|
|
(let ((display-buffer-alist
|
|
(cons
|
|
'("\\*foo\\*"
|
|
(display-buffer-reuse-window display-buffer-below-selected)
|
|
(reusable-frames)
|
|
(window-height . 5))
|
|
display-buffer-alist)))
|
|
(display-buffer
|
|
(get-buffer-create "*foo*")
|
|
'((display-buffer-reuse-window
|
|
display-buffer-pop-up-window
|
|
display-buffer-pop-up-frame)
|
|
(reusable-frames . 0)
|
|
(window-height . 10) (window-width . 40))))
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This form will have @code{display-buffer} first try reusing a window
|
|
that shows *foo* on the selected frame. If there's no such window, it
|
|
will try to split the selected window or, if that is impossible, use the
|
|
window below the selected window.
|
|
|
|
If there's no window below the selected one, or the window below the
|
|
selected one is dedicated to its buffer, @code{display-buffer} will
|
|
proceed as described in the previous example. Note, however, that when
|
|
it tries to adjust the height of any reused or popped-up window, it will
|
|
in any case try to set its number of lines to ``5'' since that value
|
|
overrides the corresponding specification in the @var{action} argument
|
|
of @code{display-buffer}.
|
|
|
|
|
|
@node Choosing Window Options
|
|
@section Additional Options for Displaying Buffers
|
|
|
|
The behavior of the standard display actions of @code{display-buffer}
|
|
(@pxref{Choosing Window}) can be modified by a variety of user
|
|
options.
|
|
|
|
@defopt pop-up-windows
|
|
If the value of this variable is non-@code{nil}, @code{display-buffer}
|
|
is allowed to split an existing window to make a new window for
|
|
displaying in. This is the default.
|
|
|
|
This variable is provided mainly for backward compatibility. It is
|
|
obeyed by @code{display-buffer} via a special mechanism in
|
|
@code{display-buffer-fallback-action}, which only calls the action
|
|
function @code{display-buffer-pop-up-window} (@pxref{Display Action
|
|
Functions}) when the value is @code{nil}. It is not consulted by
|
|
@code{display-buffer-pop-up-window} itself, which the user may specify
|
|
directly in @code{display-buffer-alist} etc.
|
|
@end defopt
|
|
|
|
@defopt split-window-preferred-function
|
|
This variable specifies a function for splitting a window, in order to
|
|
make a new window for displaying a buffer. It is used by the
|
|
@code{display-buffer-pop-up-window} action function to actually split
|
|
the window (@pxref{Display Action Functions}).
|
|
|
|
The default value is @code{split-window-sensibly}, which is documented
|
|
below. The value must be a function that takes one argument, a window,
|
|
and return either a new window (which will be used to display the
|
|
desired buffer) or @code{nil} (which means the splitting failed).
|
|
@end defopt
|
|
|
|
@defun split-window-sensibly window
|
|
This function tries to split @var{window}, and return the newly
|
|
created window. If @var{window} cannot be split, it returns
|
|
@code{nil}.
|
|
|
|
This function obeys the usual rules that determine when a window may
|
|
be split (@pxref{Splitting Windows}). It first tries to split by
|
|
placing the new window below, subject to the restriction imposed by
|
|
@code{split-height-threshold} (see below), in addition to any other
|
|
restrictions. If that fails, it tries to split by placing the new
|
|
window to the right, subject to @code{split-width-threshold} (see
|
|
below). If that fails, and the window is the only window on its
|
|
frame, this function again tries to split and place the new window
|
|
below, disregarding @code{split-height-threshold}. If this fails as
|
|
well, this function gives up and returns @code{nil}.
|
|
@end defun
|
|
|
|
@defopt split-height-threshold
|
|
This variable, used by @code{split-window-sensibly}, specifies whether
|
|
to split the window placing the new window below. If it is an
|
|
integer, that means to split only if the original window has at least
|
|
that many lines. If it is @code{nil}, that means not to split this
|
|
way.
|
|
@end defopt
|
|
|
|
@defopt split-width-threshold
|
|
This variable, used by @code{split-window-sensibly}, specifies whether
|
|
to split the window placing the new window to the right. If the value
|
|
is an integer, that means to split only if the original window has at
|
|
least that many columns. If the value is @code{nil}, that means not
|
|
to split this way.
|
|
@end defopt
|
|
|
|
@defopt pop-up-frames
|
|
If the value of this variable is non-@code{nil}, that means
|
|
@code{display-buffer} may display buffers by making new frames. The
|
|
default is @code{nil}.
|
|
|
|
A non-@code{nil} value also means that when @code{display-buffer} is
|
|
looking for a window already displaying @var{buffer-or-name}, it can
|
|
search any visible or iconified frame, not just the selected frame.
|
|
|
|
This variable is provided mainly for backward compatibility. It is
|
|
obeyed by @code{display-buffer} via a special mechanism in
|
|
@code{display-buffer-fallback-action}, which calls the action function
|
|
@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions})
|
|
if the value is non-@code{nil}. (This is done before attempting to
|
|
split a window.) This variable is not consulted by
|
|
@code{display-buffer-pop-up-frame} itself, which the user may specify
|
|
directly in @code{display-buffer-alist} etc.
|
|
@end defopt
|
|
|
|
@defopt pop-up-frame-function
|
|
This variable specifies a function for creating a new frame, in order
|
|
to make a new window for displaying a buffer. It is used by the
|
|
@code{display-buffer-pop-up-frame} action function (@pxref{Display
|
|
Action Functions}).
|
|
|
|
The value should be a function that takes no arguments and returns a
|
|
frame, or @code{nil} if no frame could be created. The default value
|
|
is a function that creates a frame using the parameters specified by
|
|
@code{pop-up-frame-alist} (see below).
|
|
@end defopt
|
|
|
|
@defopt pop-up-frame-alist
|
|
This variable holds an alist of frame parameters (@pxref{Frame
|
|
Parameters}), which is used by the default function in
|
|
@code{pop-up-frame-function} to make a new frame. The default is
|
|
@code{nil}.
|
|
@end defopt
|
|
|
|
@defopt same-window-buffer-names
|
|
A list of buffer names for buffers that should be displayed in the
|
|
selected window. If a buffer's name is in this list,
|
|
@code{display-buffer} handles the buffer by showing it in the selected
|
|
window.
|
|
@end defopt
|
|
|
|
@defopt same-window-regexps
|
|
A list of regular expressions that specify buffers that should be
|
|
displayed in the selected window. If the buffer's name matches any of
|
|
the regular expressions in this list, @code{display-buffer} handles the
|
|
buffer by showing 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
|
|
|
|
@node Window History
|
|
@section Window History
|
|
@cindex window history
|
|
|
|
Each window remembers in a list the buffers it has previously displayed,
|
|
and the order in which these buffers were removed from it. This history
|
|
is used, for example, by @code{replace-buffer-in-windows}
|
|
(@pxref{Buffers and Windows}). The list is automatically maintained by
|
|
Emacs, but you can use the following functions to explicitly inspect or
|
|
alter it:
|
|
|
|
@defun window-prev-buffers &optional window
|
|
This function returns a list specifying the previous contents of
|
|
@var{window}. The optional argument @var{window} should be a live
|
|
window and defaults to the selected one.
|
|
|
|
Each list element has the form @code{(@var{buffer} @var{window-start}
|
|
@var{window-pos})}, where @var{buffer} is a buffer previously shown in
|
|
the window, @var{window-start} is the window start position when that
|
|
buffer was last shown, and @var{window-pos} is the point position when
|
|
that buffer was last shown in @var{window}.
|
|
|
|
The list is ordered so that earlier elements correspond to more
|
|
recently-shown buffers, and the first element usually corresponds to the
|
|
buffer most recently removed from the window.
|
|
@end defun
|
|
|
|
@defun set-window-prev-buffers window prev-buffers
|
|
This function sets @var{window}'s previous buffers to the value of
|
|
@var{prev-buffers}. The argument @var{window} must be a live window
|
|
and defaults to the selected one. The argument @var{prev-buffers}
|
|
should be a list of the same form as that returned by
|
|
@code{window-prev-buffers}.
|
|
@end defun
|
|
|
|
In addition, each buffer maintains a list of @dfn{next buffers}, which
|
|
is a list of buffers re-shown by @code{switch-to-prev-buffer} (see
|
|
below). This list is mainly used by @code{switch-to-prev-buffer} and
|
|
@code{switch-to-next-buffer} for choosing buffers to switch to.
|
|
|
|
@defun window-next-buffers &optional window
|
|
This function returns the list of buffers recently re-shown in
|
|
@var{window} via @code{switch-to-prev-buffer}. The @var{window}
|
|
argument must denote a live window or @code{nil} (meaning the selected
|
|
window).
|
|
@end defun
|
|
|
|
@defun set-window-next-buffers window next-buffers
|
|
This function sets the next buffer list of @var{window} to
|
|
@var{next-buffers}. The @var{window} argument should be a live window
|
|
or @code{nil} (meaning the selected window). The argument
|
|
@var{next-buffers} should be a list of buffers.
|
|
@end defun
|
|
|
|
The following commands can be used to cycle through the global buffer
|
|
list, much like @code{bury-buffer} and @code{unbury-buffer}. However,
|
|
they cycle according to the specified window's history list, rather
|
|
than the global buffer list. In addition, they restore
|
|
window-specific window start and point positions, and may show a
|
|
buffer even if it is already shown in another window. The
|
|
@code{switch-to-prev-buffer} command, in particular, is used by
|
|
@code{replace-buffer-in-windows}, @code{bury-buffer} and
|
|
@code{quit-window} to find a replacement buffer for a window.
|
|
|
|
@deffn Command switch-to-prev-buffer &optional window bury-or-kill
|
|
This command displays the previous buffer in @var{window}. The
|
|
argument @var{window} should be a live window or @code{nil} (meaning
|
|
the selected window). If the optional argument @var{bury-or-kill} is
|
|
non-@code{nil}, this means that the buffer currently shown in
|
|
@var{window} is about to be buried or killed and consequently should
|
|
not be switched to in future invocations of this command.
|
|
|
|
The previous buffer is usually the buffer shown before the buffer
|
|
currently shown in @var{window}. However, a buffer that has been buried
|
|
or killed, or has been already shown by a recent invocation of
|
|
@code{switch-to-prev-buffer}, does not qualify as previous buffer.
|
|
|
|
If repeated invocations of this command have already shown all buffers
|
|
previously shown in @var{window}, further invocations will show buffers
|
|
from the buffer list of the frame @var{window} appears on (@pxref{The
|
|
Buffer List}), trying to skip buffers that are already shown in another
|
|
window on that frame.
|
|
@end deffn
|
|
|
|
@deffn Command switch-to-next-buffer &optional window
|
|
This command switches to the next buffer in @var{window}, thus undoing
|
|
the effect of the last @code{switch-to-prev-buffer} command in
|
|
@var{window}. The argument @var{window} must be a live window and
|
|
defaults to the selected one.
|
|
|
|
If there is no recent invocation of @code{switch-to-prev-buffer} that
|
|
can be undone, this function tries to show a buffer from the buffer list
|
|
of the frame @var{window} appears on (@pxref{The Buffer List}).
|
|
@end deffn
|
|
|
|
By default @code{switch-to-prev-buffer} and @code{switch-to-next-buffer}
|
|
can switch to a buffer that is already shown in another window on the
|
|
same frame. The following option can be used to override this behavior.
|
|
|
|
@defopt switch-to-visible-buffer
|
|
If this variable is non-@code{nil}, @code{switch-to-prev-buffer} and
|
|
@code{switch-to-next-buffer} may switch to a buffer that is already
|
|
visible on the same frame, provided the buffer was shown in the
|
|
relevant window before. If it is @code{nil},
|
|
@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} always
|
|
try to avoid switching to a buffer that is already visible in another
|
|
window on the same frame. The default is @code{t}.
|
|
@end defopt
|
|
|
|
|
|
@node Dedicated Windows
|
|
@section Dedicated Windows
|
|
@cindex dedicated window
|
|
|
|
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{Cyclic Window Ordering}) 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.
|
|
|
|
Functions supposed to remove a buffer from a window or a window from
|
|
a frame can behave specially when a window they operate on is dedicated.
|
|
We will distinguish three basic cases, namely where (1) the window is
|
|
not the only window on its frame, (2) the window is the only window on
|
|
its frame but there are other frames on the same terminal left, and (3)
|
|
the window is the only window on the only frame on the same terminal.
|
|
|
|
In particular, @code{delete-windows-on} (@pxref{Deleting Windows})
|
|
handles case (2) by deleting the associated frame and case (3) by
|
|
showing another buffer in that frame's only window. The function
|
|
@code{replace-buffer-in-windows} (@pxref{Buffers and Windows}) which is
|
|
called when a buffer gets killed, deletes the window in case (1) and
|
|
behaves like @code{delete-windows-on} otherwise.
|
|
|
|
When @code{bury-buffer} (@pxref{The Buffer List}) operates on the
|
|
selected window (which shows the buffer that shall be buried), it
|
|
handles case (2) by calling @code{frame-auto-hide-function}
|
|
(@pxref{Quitting Windows}) to deal with the selected frame. The other
|
|
two cases are handled as with @code{replace-buffer-in-windows}.
|
|
|
|
@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 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 Quitting Windows
|
|
@section Quitting Windows
|
|
|
|
When you want to get rid of a window used for displaying a buffer, you
|
|
can call @code{delete-window} or @code{delete-windows-on}
|
|
(@pxref{Deleting Windows}) to remove that window from its frame. If the
|
|
buffer is shown on a separate frame, you might want to call
|
|
@code{delete-frame} (@pxref{Deleting Frames}) instead. If, on the other
|
|
hand, a window has been reused for displaying the buffer, you might
|
|
prefer showing the buffer previously shown in that window, by calling the
|
|
function @code{switch-to-prev-buffer} (@pxref{Window History}).
|
|
Finally, you might want to either bury (@pxref{The Buffer List}) or kill
|
|
(@pxref{Killing Buffers}) the window's buffer.
|
|
|
|
The following command uses information on how the window for
|
|
displaying the buffer was obtained in the first place, thus attempting
|
|
to automate the above decisions for you.
|
|
|
|
@deffn Command quit-window &optional kill window
|
|
This command quits @var{window} and buries its buffer. The argument
|
|
@var{window} must be a live window and defaults to the selected one.
|
|
With prefix argument @var{kill} non-@code{nil}, it kills the buffer
|
|
instead of burying it. It calls the function @code{quit-restore-window}
|
|
described next to deal with the window and its buffer.
|
|
@end deffn
|
|
|
|
@defun quit-restore-window &optional window bury-or-kill
|
|
This function tries to restore the state of @var{window} that existed
|
|
before its buffer was displayed in it. The optional argument
|
|
@var{window} must be a live window and defaults to the selected one.
|
|
|
|
If @var{window} was created specially for displaying its buffer, this
|
|
function deletes @var{window} provided its frame contains at least one
|
|
other live window. If @var{window} is the only window on its frame and
|
|
there are other frames on the frame's terminal, the value of the
|
|
optional argument @var{bury-or-kill} determines how to proceed with the
|
|
window. If @var{bury-or-kill} equals @code{kill}, the frame is deleted
|
|
unconditionally. Otherwise, the fate of the frame is determined by
|
|
calling @code{frame-auto-hide-function} (see below) with that frame as
|
|
sole argument.
|
|
|
|
Otherwise, this function tries to redisplay the buffer previously shown
|
|
in @var{window}. It also tries to restore the window start
|
|
(@pxref{Window Start and End}) and point (@pxref{Window Point})
|
|
positions of the previously shown buffer. If, in addition,
|
|
@var{window}'s buffer was temporarily resized, this function will also
|
|
try to restore the original height of @var{window}.
|
|
|
|
The cases described so far require that the buffer shown in @var{window}
|
|
is still the buffer displayed by the last buffer display function for
|
|
this window. If another buffer has been shown in the meantime, or the
|
|
buffer previously shown no longer exists, this function calls
|
|
@code{switch-to-prev-buffer} (@pxref{Window History}) to show some other
|
|
buffer instead.
|
|
|
|
The optional argument @var{bury-or-kill} specifies how to deal with
|
|
@var{window}'s buffer. The following values are handled:
|
|
|
|
@table @code
|
|
@item nil
|
|
This means to not deal with the buffer in any particular way. As a
|
|
consequence, if @var{window} is not deleted, invoking
|
|
@code{switch-to-prev-buffer} will usually show the buffer again.
|
|
|
|
@item append
|
|
This means that if @var{window} is not deleted, its buffer is moved to
|
|
the end of @var{window}'s list of previous buffers, so it's less likely
|
|
that a future invocation of @code{switch-to-prev-buffer} will switch to
|
|
it. Also, it moves the buffer to the end of the frame's buffer list.
|
|
|
|
@item bury
|
|
This means that if @var{window} is not deleted, its buffer is removed
|
|
from @var{window}'s list of previous buffers. Also, it moves the buffer
|
|
to the end of the frame's buffer list. This value provides the most
|
|
reliable remedy to not have @code{switch-to-prev-buffer} switch to this
|
|
buffer again without killing the buffer.
|
|
|
|
@item kill
|
|
This means to kill @var{window}'s buffer.
|
|
@end table
|
|
|
|
@code{quit-restore-window} bases its decisions on information stored in
|
|
@var{window}'s @code{quit-restore} window parameter (@pxref{Window
|
|
Parameters}), and resets that parameter to @code{nil} after it's done.
|
|
@end defun
|
|
|
|
The following option specifies how to deal with a frame containing just
|
|
one window that should be either quit, or whose buffer should be buried.
|
|
|
|
@defopt frame-auto-hide-function
|
|
The function specified by this option is called to automatically hide
|
|
frames. This function is called with one argument---a frame.
|
|
|
|
The function specified here is called by @code{bury-buffer} (@pxref{The
|
|
Buffer List}) when the selected window is dedicated and shows the buffer
|
|
to bury. It is also called by @code{quit-restore-window} (see above)
|
|
when the frame of the window to quit has been specially created for
|
|
displaying that window's buffer and the buffer is not killed.
|
|
|
|
The default is to call @code{iconify-frame} (@pxref{Visibility of
|
|
Frames}). Alternatively, you may specify either @code{delete-frame}
|
|
(@pxref{Deleting Frames}) to remove the frame from its display,
|
|
@code{ignore} to leave the frame unchanged, or any other function that
|
|
can take a frame as its sole argument.
|
|
|
|
Note that the function specified by this option is called only if the
|
|
specified frame contains just one live window and there is at least one
|
|
other frame on the same terminal.
|
|
@end defopt
|
|
|
|
|
|
@node Window Point
|
|
@section Windows and Point
|
|
@cindex window position
|
|
@cindex window point
|
|
@cindex position in window
|
|
@cindex point in window
|
|
|
|
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
|
|
The window point is established when a window is first created; it is
|
|
initialized from the buffer's point, or from the window point of another
|
|
window opened on the buffer if such a window exists.
|
|
|
|
@item
|
|
Selecting a window sets the value of point in its buffer from the
|
|
window's value of point. Conversely, deselecting a window sets the
|
|
window's value of point from that of the buffer. Thus, when you switch
|
|
between windows that display a given buffer, the point value for the
|
|
selected window is in effect in the buffer, while the point values for
|
|
the other windows are stored in those windows.
|
|
|
|
@item
|
|
As long as the selected window displays the current buffer, the window's
|
|
point and the buffer's point always move together; they remain equal.
|
|
@end itemize
|
|
|
|
@cindex cursor
|
|
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. The default for
|
|
@var{window} is the selected window.
|
|
|
|
When @var{window} is the selected window, the value returned is the
|
|
value of point in that window's buffer. Strictly speaking, it would be
|
|
more correct to return the ``top-level'' value of point, outside of any
|
|
@code{save-excursion} forms. But that value is hard to find.
|
|
@end defun
|
|
|
|
@defun set-window-point window position
|
|
This function positions point in @var{window} at position
|
|
@var{position} in @var{window}'s buffer. It returns @var{position}.
|
|
|
|
If @var{window} is selected, this simply does @code{goto-char} in
|
|
@var{window}'s buffer.
|
|
@end defun
|
|
|
|
@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 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
|
|
at the upper left corner of the window. It is usually, but not
|
|
inevitably, at the beginning of a text line.
|
|
|
|
After switching windows or buffers, and in some other cases, if the
|
|
window start is in the middle of a line, Emacs adjusts the window
|
|
start to the start of a line. This prevents certain operations from
|
|
leaving the window start at a meaningless point within a line. This
|
|
feature may interfere with testing some Lisp code by executing it
|
|
using the commands of Lisp mode, because they trigger this
|
|
readjustment. To test such code, put it into a command and bind the
|
|
command to a key.
|
|
|
|
@defun window-start &optional window
|
|
@cindex window top line
|
|
This function returns the display-start position of window
|
|
@var{window}. If @var{window} is @code{nil}, the selected window is
|
|
used.
|
|
|
|
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 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)---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.
|
|
@end defun
|
|
|
|
@cindex window end position
|
|
@defun window-end &optional window update
|
|
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
|
|
Emacs redisplays and redisplay completes without being preempted.
|
|
|
|
If the last redisplay of @var{window} was preempted, and did not finish,
|
|
Emacs does not know the position of the end of display in that window.
|
|
In that case, this function returns @code{nil}.
|
|
|
|
If @var{update} is non-@code{nil}, @code{window-end} always returns an
|
|
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
|
|
way real redisplay would do. It does not alter the
|
|
@code{window-start} value. In effect, it reports where the displayed
|
|
text will end if scrolling is not required.
|
|
@end defun
|
|
|
|
@defun set-window-start window position &optional noforce
|
|
This function sets the display-start position of @var{window} to
|
|
@var{position} in @var{window}'s buffer. It returns @var{position}.
|
|
|
|
The display routines insist that the position of point be visible when a
|
|
buffer is displayed. Normally, they change the display-start position
|
|
(that is, scroll the window) whenever necessary to make point visible.
|
|
However, if you specify the start position with this function using
|
|
@code{nil} for @var{noforce}, it means you want display to start at
|
|
@var{position} even if that would put the location of point off the
|
|
screen. If this does place point off screen, the display routines move
|
|
point to the left margin on the middle line in the window.
|
|
|
|
For example, if point @w{is 1} and you set the start of the window
|
|
@w{to 37}, the start of the next line, point will be ``above'' the top
|
|
of the window. The display routines will automatically move point if
|
|
it is still 1 when redisplay occurs. Here is an example:
|
|
|
|
@example
|
|
@group
|
|
;; @r{Here is what @samp{foo} looks like before executing}
|
|
;; @r{the @code{set-window-start} expression.}
|
|
@end group
|
|
|
|
@group
|
|
---------- Buffer: foo ----------
|
|
@point{}This is the contents of buffer foo.
|
|
2
|
|
3
|
|
4
|
|
5
|
|
6
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
|
|
@group
|
|
(set-window-start
|
|
(selected-window)
|
|
(save-excursion
|
|
(goto-char 1)
|
|
(forward-line 1)
|
|
(point)))
|
|
@result{} 37
|
|
@end group
|
|
|
|
@group
|
|
;; @r{Here is what @samp{foo} looks like after executing}
|
|
;; @r{the @code{set-window-start} expression.}
|
|
---------- Buffer: foo ----------
|
|
2
|
|
3
|
|
@point{}4
|
|
5
|
|
6
|
|
---------- Buffer: foo ----------
|
|
@end group
|
|
@end example
|
|
|
|
If @var{noforce} is non-@code{nil}, and @var{position} would place point
|
|
off screen at the next redisplay, then redisplay computes a new window-start
|
|
position that works well with point, and thus @var{position} is not used.
|
|
@end defun
|
|
|
|
@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}.
|
|
|
|
This function considers only vertical scrolling. If @var{position} is
|
|
out of view only because @var{window} has been scrolled horizontally,
|
|
@code{pos-visible-in-window-p} returns non-@code{nil} anyway.
|
|
@xref{Horizontal Scrolling}.
|
|
|
|
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 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 @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:
|
|
|
|
@example
|
|
@group
|
|
;; @r{If point is off the screen now, recenter it now.}
|
|
(or (pos-visible-in-window-p
|
|
(point) (selected-window))
|
|
(recenter 0))
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun window-line-height &optional line 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
|
|
to obtain related information.
|
|
|
|
If there is no line corresponding to the specified @var{line},
|
|
@code{window-line-height} returns @code{nil}. Otherwise, it returns
|
|
a list @code{(@var{height} @var{vpos} @var{ypos} @var{offbot})},
|
|
where @var{height} is the height in pixels of the visible part of the
|
|
line, @var{vpos} and @var{ypos} are the vertical position in lines and
|
|
pixels of the line relative to the top of the first text line, and
|
|
@var{offbot} is the number of off-window pixels at the bottom of the
|
|
text line. If there are off-window pixels at the top of the (first)
|
|
text line, @var{ypos} is negative.
|
|
@end defun
|
|
|
|
@node Textual Scrolling
|
|
@section Textual Scrolling
|
|
@cindex textual scrolling
|
|
@cindex scrolling textually
|
|
|
|
@dfn{Textual scrolling} means moving the text up or down through a
|
|
window. It works by changing the window's display-start location. It
|
|
may also change the value of @code{window-point} to keep point on the
|
|
screen (@pxref{Window Point}).
|
|
|
|
The basic textual scrolling functions are @code{scroll-up} (which
|
|
scrolls forward) and @code{scroll-down} (which scrolls backward). In
|
|
these function names, ``up'' and ``down'' refer to the direction of
|
|
motion of the buffer text relative to the window. Imagine that the
|
|
text is written on a long roll of paper and that the scrolling
|
|
commands move the paper up and down. Thus, if you are looking at the
|
|
middle of a buffer and repeatedly call @code{scroll-down}, you will
|
|
eventually see the beginning of the buffer.
|
|
|
|
Unfortunately, this sometimes causes confusion, because some people
|
|
tend to think in terms of the opposite convention: they
|
|
imagine the window moving over text that remains in place, so that
|
|
``down'' commands take you to the end of the buffer. This convention
|
|
is consistent with fact that such a command is bound to a key named
|
|
@key{PageDown} on modern keyboards.
|
|
@ignore
|
|
We have not switched to this convention as that is likely to break
|
|
existing Emacs Lisp code.
|
|
@end ignore
|
|
|
|
Textual scrolling functions (aside from @code{scroll-other-window})
|
|
have unpredictable results if the current buffer is not the one
|
|
displayed in the selected window. @xref{Current Buffer}.
|
|
|
|
If the window contains a row taller than the height of the window
|
|
(for example in the presence of a large image), the scroll functions
|
|
will adjust the window's vertical scroll position to scroll the
|
|
partially visible row. Lisp callers can disable this feature by
|
|
binding the variable @code{auto-window-vscroll} to @code{nil}
|
|
(@pxref{Vertical Scrolling}).
|
|
|
|
@deffn Command scroll-up &optional count
|
|
This function scrolls forward by @var{count} lines in the selected
|
|
window.
|
|
|
|
If @var{count} is negative, it scrolls backward instead. If
|
|
@var{count} is @code{nil} (or omitted), the distance scrolled is
|
|
@code{next-screen-context-lines} lines less than the height of the
|
|
window's text area.
|
|
|
|
If the selected window cannot be scrolled any further, this function
|
|
signals an error. Otherwise, it returns @code{nil}.
|
|
@end deffn
|
|
|
|
@deffn Command scroll-down &optional count
|
|
This function scrolls backward by @var{count} lines in the selected
|
|
window.
|
|
|
|
If @var{count} is negative, it scrolls forward instead. In other
|
|
respects, it behaves the same way as @code{scroll-up} does.
|
|
@end deffn
|
|
|
|
@deffn Command scroll-up-command &optional count
|
|
This behaves like @code{scroll-up}, except that if the selected window
|
|
cannot be scrolled any further and the value of the variable
|
|
@code{scroll-error-top-bottom} is @code{t}, it tries to move to the
|
|
end of the buffer instead. If point is already there, it signals an
|
|
error.
|
|
@end deffn
|
|
|
|
@deffn Command scroll-down-command &optional count
|
|
This behaves like @code{scroll-down}, except that if the selected
|
|
window cannot be scrolled any further and the value of the variable
|
|
@code{scroll-error-top-bottom} is @code{t}, it tries to move to the
|
|
beginning of the buffer instead. If point is already there, it
|
|
signals an error.
|
|
@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
|
|
as in @code{scroll-up}.
|
|
|
|
You can specify which buffer to scroll by setting the variable
|
|
@code{other-window-scroll-buffer} to a buffer. If that buffer isn't
|
|
already displayed, @code{scroll-other-window} displays it in some
|
|
window.
|
|
|
|
When the selected window is the minibuffer, the next window is normally
|
|
the leftmost one immediately above it. You can specify a different
|
|
window to scroll, when the minibuffer is selected, by setting the variable
|
|
@code{minibuffer-scroll-window}. This variable has no effect when any
|
|
other window is selected. When it is non-@code{nil} and the
|
|
minibuffer is selected, it takes precedence over
|
|
@code{other-window-scroll-buffer}. @xref{Definition of
|
|
minibuffer-scroll-window}.
|
|
|
|
When the minibuffer is active, it is the next window if the selected
|
|
window is the one at the bottom right corner. In this case,
|
|
@code{scroll-other-window} attempts to scroll the minibuffer. If the
|
|
minibuffer contains just one line, it has nowhere to scroll to, so the
|
|
line reappears after the echo area momentarily displays the message
|
|
@samp{End of buffer}.
|
|
@end deffn
|
|
|
|
@defvar other-window-scroll-buffer
|
|
If this variable is non-@code{nil}, it tells @code{scroll-other-window}
|
|
which buffer's window to scroll.
|
|
@end defvar
|
|
|
|
@defopt scroll-margin
|
|
This option specifies the size of the scroll margin---a minimum number
|
|
of lines between point and the top or bottom of a window. Whenever
|
|
point gets within this many lines of the top or bottom of the window,
|
|
redisplay scrolls the text automatically (if possible) to move point
|
|
out of the margin, closer to the center of the window.
|
|
@end defopt
|
|
|
|
@defopt scroll-conservatively
|
|
This variable controls how scrolling is done automatically when point
|
|
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 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}.
|
|
|
|
The default value is zero, which means that conservative scrolling
|
|
never happens.
|
|
@end defopt
|
|
|
|
@defopt scroll-down-aggressively
|
|
The value of this variable should be either @code{nil} or a fraction
|
|
@var{f} between 0 and 1. If it is a fraction, that specifies where on
|
|
the screen to put point when scrolling down. More precisely, when a
|
|
window scrolls down because point is above the window start, the new
|
|
start position is chosen to put point @var{f} part of the window
|
|
height from the top. The larger @var{f}, the more aggressive the
|
|
scrolling.
|
|
|
|
A value of @code{nil} is equivalent to .5, since its effect is to center
|
|
point. This variable automatically becomes buffer-local when set in any
|
|
fashion.
|
|
@end defopt
|
|
|
|
@defopt scroll-up-aggressively
|
|
Likewise, for scrolling up. The value, @var{f}, specifies how far
|
|
point should be placed from the bottom of the window; thus, as with
|
|
@code{scroll-up-aggressively}, a larger value scrolls more aggressively.
|
|
@end defopt
|
|
|
|
@defopt scroll-step
|
|
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
|
|
|
|
@cindex @code{scroll-command} property
|
|
@defopt scroll-preserve-screen-position
|
|
If this option is @code{t}, whenever a scrolling command moves point
|
|
off-window, Emacs tries to adjust point to keep the cursor at its old
|
|
vertical position in the window, rather than the window edge.
|
|
|
|
If the value is non-@code{nil} and not @code{t}, Emacs adjusts point
|
|
to keep the cursor at the same vertical position, even if the
|
|
scrolling command didn't move point off-window.
|
|
|
|
This option affects all scroll commands that have a non-@code{nil}
|
|
@code{scroll-command} symbol property.
|
|
@end defopt
|
|
|
|
@defopt next-screen-context-lines
|
|
The value of this variable is the number of lines of continuity to
|
|
retain when scrolling by full screens. For example, @code{scroll-up}
|
|
with an argument of @code{nil} scrolls so that this many lines at the
|
|
bottom of the window appear instead at the top. The default value is
|
|
@code{2}.
|
|
@end defopt
|
|
|
|
@defopt scroll-error-top-bottom
|
|
If this option is @code{nil} (the default), @code{scroll-up-command}
|
|
and @code{scroll-down-command} simply signal an error when no more
|
|
scrolling is possible.
|
|
|
|
If the value is @code{t}, these commands instead move point to the
|
|
beginning or end of the buffer (depending on scrolling direction);
|
|
only if point is already on that position do they signal an error.
|
|
@end defopt
|
|
|
|
@deffn Command recenter &optional count
|
|
@cindex centering point
|
|
This function scrolls the text in the selected window so that point is
|
|
displayed at a specified vertical position within the window. It does
|
|
not ``move point'' with respect to the text.
|
|
|
|
If @var{count} is a non-negative number, that puts the line containing
|
|
point @var{count} lines down from the top of the window. If
|
|
@var{count} is a negative number, then it counts upward from the
|
|
bottom of the window, so that @minus{}1 stands for the last usable
|
|
line in the window.
|
|
|
|
If @var{count} is @code{nil} (or a non-@code{nil} list),
|
|
@code{recenter} puts the line containing point in the middle of the
|
|
window. If @var{count} is @code{nil}, this function may redraw the
|
|
frame, according to the value of @code{recenter-redisplay}.
|
|
|
|
When @code{recenter} is called interactively, @var{count} is the raw
|
|
prefix argument. Thus, typing @kbd{C-u} as the prefix sets the
|
|
@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets
|
|
@var{count} to 4, which positions the current line four lines from the
|
|
top.
|
|
|
|
With an argument of zero, @code{recenter} positions the current line at
|
|
the top of the window. The command @code{recenter-top-bottom} offers
|
|
a more convenient way to achieve this.
|
|
@end deffn
|
|
|
|
@defopt recenter-redisplay
|
|
If this variable is non-@code{nil}, calling @code{recenter} with a
|
|
@code{nil} argument redraws the frame. The default value is
|
|
@code{tty}, which means only redraw the frame if it is a tty frame.
|
|
@end defopt
|
|
|
|
@deffn Command recenter-top-bottom &optional count
|
|
This command, which is the default binding for @kbd{C-l}, acts like
|
|
@code{recenter}, except if called with no argument. In that case,
|
|
successive calls place point according to the cycling order defined
|
|
by the variable @code{recenter-positions}.
|
|
@end deffn
|
|
|
|
@defopt recenter-positions
|
|
This variable controls how @code{recenter-top-bottom} behaves when
|
|
called with no argument. The default value is @code{(middle top
|
|
bottom)}, which means that successive calls of
|
|
@code{recenter-top-bottom} with no argument cycle between placing
|
|
point at the middle, top, and bottom of the window.
|
|
@end defopt
|
|
|
|
|
|
@node Vertical Scrolling
|
|
@section Vertical Fractional Scrolling
|
|
@cindex vertical fractional scrolling
|
|
@cindex vertical scroll position
|
|
|
|
@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
|
|
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
|
|
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}. 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
|
|
(window-vscroll)
|
|
@result{} 0
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defun set-window-vscroll window lines &optional pixels-p
|
|
This function sets @var{window}'s vertical scroll position to
|
|
@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.
|
|
|
|
|
|
The actual vertical scroll position must always correspond
|
|
to an integral number of pixels, so the value you specify
|
|
is rounded accordingly.
|
|
|
|
The return value is the result of this rounding.
|
|
|
|
@example
|
|
@group
|
|
(set-window-vscroll (selected-window) 1.2)
|
|
@result{} 1.13
|
|
@end group
|
|
@end example
|
|
|
|
If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of
|
|
pixels. In this case, the return value is @var{lines}.
|
|
@end defun
|
|
|
|
@defvar auto-window-vscroll
|
|
If this variable is non-@code{nil}, the @code{line-move},
|
|
@code{scroll-up}, and @code{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
|
|
@section Horizontal Scrolling
|
|
@cindex horizontal scrolling
|
|
|
|
@dfn{Horizontal scrolling} means shifting the image in the window left
|
|
or right by a specified multiple of the normal character width. Each
|
|
window has a @dfn{horizontal scroll position}, which is a number, never
|
|
less than zero. It specifies how far to shift the contents left.
|
|
Shifting the window contents left generally makes all or part of some
|
|
characters disappear off the left, and all or part of some other
|
|
characters appear at the right. The usual value is zero.
|
|
|
|
The horizontal scroll position is measured in units of the normal
|
|
character width, which is the width of space in the default font. Thus,
|
|
if the value is 5, that means the window contents are scrolled left by 5
|
|
times the normal character width. How many characters actually
|
|
disappear off to the left depends on their width, and could vary from
|
|
line to line.
|
|
|
|
Because we read from side to side in the ``inner loop'', and from top
|
|
to bottom in the ``outer loop'', the effect of horizontal scrolling is
|
|
not like that of textual or vertical scrolling. Textual scrolling
|
|
involves selection of a portion of text to display, and vertical
|
|
scrolling moves the window contents contiguously; but horizontal
|
|
scrolling causes part of @emph{each line} to go off screen.
|
|
|
|
Usually, no horizontal scrolling is in effect; then the leftmost
|
|
column is at the left edge of the window. In this state, scrolling to
|
|
the right is meaningless, since there is no data to the left of the edge
|
|
to be revealed by it; so this is not allowed. Scrolling to the left is
|
|
allowed; it scrolls the first columns of text off the edge of the window
|
|
and can reveal additional columns on the right that were truncated
|
|
before. Once a window has a nonzero amount of leftward horizontal
|
|
scrolling, you can scroll it back to the right, but only so far as to
|
|
reduce the net horizontal scroll to zero. There is no limit to how far
|
|
left you can scroll, but eventually all the text will disappear off the
|
|
left edge.
|
|
|
|
@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 set-minimum
|
|
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.
|
|
|
|
The return value is the total amount of leftward horizontal scrolling in
|
|
effect after the change---just like the value returned by
|
|
@code{window-hscroll} (below).
|
|
|
|
Once you scroll a window as far right as it can go, back to its normal
|
|
position where the total leftward scrolling is zero, attempts to scroll
|
|
any farther right have no effect.
|
|
|
|
If @var{set-minimum} is non-@code{nil}, the new scroll amount becomes
|
|
the lower bound for automatic scrolling; that is, automatic scrolling
|
|
will not scroll a window to a column less than the value returned by
|
|
this function. Interactive calls pass non-@code{nil} for
|
|
@var{set-minimum}.
|
|
@end deffn
|
|
|
|
@deffn Command scroll-right &optional count set-minimum
|
|
This function scrolls the selected window @var{count} columns to the
|
|
right (or to the left if @var{count} is negative). The default
|
|
for @var{count} is the window width, minus 2. Aside from the direction
|
|
of scrolling, this works just like @code{scroll-left}.
|
|
@end deffn
|
|
|
|
@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. The default for
|
|
@var{window} is the selected window.
|
|
|
|
The return value is never negative. It is zero when no horizontal
|
|
scrolling has been done in @var{window} (which is usually the case).
|
|
|
|
|
|
@example
|
|
@group
|
|
(window-hscroll)
|
|
@result{} 0
|
|
@end group
|
|
@group
|
|
(scroll-left 5)
|
|
@result{} 5
|
|
@end group
|
|
@group
|
|
(window-hscroll)
|
|
@result{} 5
|
|
@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,
|
|
and this overrides what the function did. You can observe the
|
|
function's effect if you call it while point is sufficiently far from
|
|
the left margin that it will remain visible.
|
|
|
|
The value returned is @var{columns}.
|
|
|
|
@example
|
|
@group
|
|
(set-window-hscroll (selected-window) 10)
|
|
@result{} 10
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
Here is how you can determine whether a given position @var{position}
|
|
is off the screen due to horizontal scrolling:
|
|
|
|
@example
|
|
@group
|
|
(defun hscroll-on-screen (window position)
|
|
(save-excursion
|
|
(goto-char position)
|
|
(and
|
|
(>= (- (current-column) (window-hscroll window)) 0)
|
|
(< (- (current-column) (window-hscroll window))
|
|
(window-width window)))))
|
|
@end group
|
|
@end example
|
|
|
|
@node Coordinates and Windows
|
|
@section Coordinates and Windows
|
|
@cindex frame-relative coordinate
|
|
@cindex coordinate, relative to frame
|
|
@cindex window position
|
|
|
|
This section describes functions that report the position of a
|
|
window. Most of these functions report positions relative to the
|
|
window's frame. In this case, the coordinate origin @samp{(0,0)} lies
|
|
near the upper left corner of the frame. For technical reasons, on
|
|
graphical displays the origin is not located at the exact corner of
|
|
the graphical window as it appears on the screen. If Emacs is built
|
|
with the GTK+ toolkit, the origin is at the upper left corner of the
|
|
frame area used for displaying Emacs windows, below the title-bar,
|
|
GTK+ menu bar, and tool bar (since these are drawn by the window
|
|
manager and/or GTK+, not by Emacs). But if Emacs is not built with
|
|
GTK+, the origin is at the upper left corner of the tool bar (since in
|
|
this case Emacs itself draws the tool bar). In both cases, the X and
|
|
Y coordinates increase rightward and downward respectively.
|
|
|
|
Except where noted, X and Y coordinates are reported in integer
|
|
character units, i.e., numbers of lines and columns respectively. On a
|
|
graphical display, each ``line'' and ``column'' corresponds to the
|
|
height and width of a default character specified by the frame's
|
|
default font.
|
|
|
|
@defun window-edges &optional window
|
|
This function returns a list of the edge coordinates of @var{window}.
|
|
If @var{window} is omitted or @code{nil}, it defaults to the selected
|
|
window.
|
|
|
|
The return value has the form @code{(@var{left} @var{top} @var{right}
|
|
@var{bottom})}. These list elements are, respectively, the X
|
|
coordinate of the leftmost column occupied by the window, the Y
|
|
coordinate of the topmost row, the X coordinate one column to the
|
|
right of the rightmost column, and the Y coordinate one row down from
|
|
the bottommost row.
|
|
|
|
Note that these are the actual outer edges of the window, including
|
|
any header line, mode line, scroll bar, fringes, and display margins.
|
|
On a text terminal, if the window has a neighbor on its right, its
|
|
right edge includes the separator line between the window and its
|
|
neighbor.
|
|
@end defun
|
|
|
|
@defun window-inside-edges &optional window
|
|
This function is similar to @code{window-edges}, but the returned edge
|
|
values are for the text area of the window. They exclude any header
|
|
line, mode line, scroll bar, fringes, display margins, and vertical
|
|
separator.
|
|
@end defun
|
|
|
|
@defun window-top-line &optional window
|
|
This function returns the Y coordinate of the topmost row of
|
|
@var{window}, equivalent to the @var{top} entry in the list returned
|
|
by @code{window-edges}.
|
|
@end defun
|
|
|
|
@defun window-left-column &optional window
|
|
This function returns the X coordinate of the leftmost column of
|
|
@var{window}, equivalent to the @var{left} entry in the list returned
|
|
by @code{window-edges}.
|
|
@end defun
|
|
|
|
The following functions can be used to relate a set of
|
|
frame-relative coordinates to a window:
|
|
|
|
@defun window-at x y &optional frame
|
|
This function returns the live window at the frame-relative
|
|
coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no
|
|
window at that position, the return value is @code{nil}. If
|
|
@var{frame} is omitted or @code{nil}, it defaults to the selected
|
|
frame.
|
|
@end defun
|
|
|
|
@defun coordinates-in-window-p coordinates window
|
|
This function checks whether a window @var{window} occupies the
|
|
frame-relative coordinates @var{coordinates}, and if so, which part of
|
|
the window that is. @var{window} should be a live window.
|
|
@var{coordinates} should be a cons cell of the form @code{(@var{x}
|
|
. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates.
|
|
|
|
If there is no window at the specified position, the return value is
|
|
@code{nil} . Otherwise, the return value is one of the following:
|
|
|
|
@table @code
|
|
@item (@var{relx} . @var{rely})
|
|
The coordinates are inside @var{window}. The numbers @var{relx} and
|
|
@var{rely} are the equivalent window-relative coordinates for the
|
|
specified position, counting from 0 at the top left corner of the
|
|
window.
|
|
|
|
@item mode-line
|
|
The coordinates are in the mode line of @var{window}.
|
|
|
|
@item header-line
|
|
The coordinates are in the header line of @var{window}.
|
|
|
|
@item vertical-line
|
|
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
|
|
argument because it always uses the frame that @var{window} is on.
|
|
@end defun
|
|
|
|
The following functions return window positions in pixels, rather
|
|
than character units. Though mostly useful on graphical displays,
|
|
they can also be called on text terminals, where the screen area of
|
|
each text character is taken to be ``one pixel''.
|
|
|
|
@defun window-pixel-edges &optional window
|
|
This function returns a list of pixel coordinates for the edges of
|
|
@var{window}. If @var{window} is omitted or @code{nil}, it defaults
|
|
to the selected window.
|
|
|
|
The return value has the form @code{(@var{left} @var{top} @var{right}
|
|
@var{bottom})}. The list elements are, respectively, the X pixel
|
|
coordinate of the left window edge, the Y pixel coordinate of the top
|
|
edge, one more than the X pixel coordinate of the right edge, and one
|
|
more than the Y pixel coordinate of the bottom edge.
|
|
@end defun
|
|
|
|
@defun window-inside-pixel-edges &optional window
|
|
This function is like @code{window-pixel-edges}, except that it
|
|
returns the pixel coordinates for the edges of the window's text area,
|
|
rather than the pixel coordinates for the edges of the window itself.
|
|
@var{window} must specify a live window.
|
|
@end defun
|
|
|
|
The following functions return window positions in pixels, relative
|
|
to the display screen rather than the frame:
|
|
|
|
@defun window-absolute-pixel-edges &optional window
|
|
This function is like @code{window-pixel-edges}, except that it
|
|
returns the edge pixel coordinates relative to the top left corner of
|
|
the display screen.
|
|
@end defun
|
|
|
|
@defun window-inside-absolute-pixel-edges &optional window
|
|
This function is like @code{window-inside-pixel-edges}, except that it
|
|
returns the edge pixel coordinates relative to the top left corner of
|
|
the display screen. @var{window} must specify a live window.
|
|
@end defun
|
|
|
|
@node Window Configurations
|
|
@section Window Configurations
|
|
@cindex window configurations
|
|
@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 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.
|
|
|
|
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. @xref{Frame Configurations}.
|
|
|
|
@defun current-window-configuration &optional frame
|
|
This function returns a new object representing @var{frame}'s current
|
|
window configuration. The default for @var{frame} is the selected
|
|
frame. The variable @code{window-persistent-parameters} specifies
|
|
which window parameters (if any) are saved by this function.
|
|
@xref{Window Parameters}.
|
|
@end defun
|
|
|
|
@defun set-window-configuration configuration
|
|
This function restores the configuration of windows and buffers as
|
|
specified by @var{configuration}, for the frame that @var{configuration}
|
|
was created for.
|
|
|
|
The argument @var{configuration} must be a value that was previously
|
|
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}
|
|
(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
|
|
know how to tell whether the new configuration actually differs from the
|
|
old one.
|
|
|
|
If the frame from which @var{configuration} was saved is dead, all this
|
|
function does is restore the three variables @code{window-min-height},
|
|
@code{window-min-width} and @code{minibuffer-scroll-window}. In this
|
|
case, the function returns @code{nil}. Otherwise, it returns @code{t}.
|
|
|
|
Here is a way of using this function to get the same effect
|
|
as @code{save-window-excursion}:
|
|
|
|
@example
|
|
@group
|
|
(let ((config (current-window-configuration)))
|
|
(unwind-protect
|
|
(progn (split-window-below nil)
|
|
@dots{})
|
|
(set-window-configuration config)))
|
|
@end group
|
|
@end example
|
|
@end defun
|
|
|
|
@defmac save-window-excursion forms@dots{}
|
|
This macro records the window configuration of the selected frame,
|
|
executes @var{forms} in sequence, then restores the earlier window
|
|
configuration. The return value is the value of the final form in
|
|
@var{forms}.
|
|
|
|
Most Lisp code should not use this macro; @code{save-selected-window}
|
|
is typically sufficient. In particular, this macro cannot reliably
|
|
prevent the code in @var{forms} from opening new windows, because new
|
|
windows might be opened in other frames (@pxref{Choosing Window}), and
|
|
@code{save-window-excursion} only saves and restores the window
|
|
configuration on the current frame.
|
|
|
|
Do not use this macro in @code{window-size-change-functions}; exiting
|
|
the macro triggers execution of @code{window-size-change-functions},
|
|
leading to an endless loop.
|
|
@end defmac
|
|
|
|
@defun window-configuration-p object
|
|
This function returns @code{t} if @var{object} is a window configuration.
|
|
@end defun
|
|
|
|
@defun compare-window-configurations config1 config2
|
|
This function compares two window configurations as regards the
|
|
structure of windows, but ignores the values of point and mark and the
|
|
saved scrolling positions---it can return @code{t} even if those
|
|
aspects differ.
|
|
|
|
The function @code{equal} can also compare two window configurations; it
|
|
regards configurations as unequal if they differ in any respect, even a
|
|
saved point or mark.
|
|
@end defun
|
|
|
|
@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.
|
|
|
|
The objects returned by @code{current-window-configuration} die
|
|
together with the Emacs process. In order to store a window
|
|
configuration on disk and read it back in another Emacs session, you
|
|
can use the functions described next. These functions are also useful
|
|
to clone the state of a frame into an arbitrary live window
|
|
(@code{set-window-configuration} effectively clones the windows of a
|
|
frame into the root window of that very frame only).
|
|
|
|
@defun window-state-get &optional window writable
|
|
This function returns the state of @var{window} as a Lisp object. The
|
|
argument @var{window} must be a valid window and defaults to the root
|
|
window of the selected frame.
|
|
|
|
If the optional argument @var{writable} is non-@code{nil}, this means to
|
|
not use markers for sampling positions like @code{window-point} or
|
|
@code{window-start}. This argument should be non-@code{nil} when the
|
|
state will be written to disk and read back in another session.
|
|
|
|
Together, the argument @var{writable} and the variable
|
|
@code{window-persistent-parameters} specify which window parameters are
|
|
saved by this function. @xref{Window Parameters}.
|
|
@end defun
|
|
|
|
The value returned by @code{window-state-get} can be used in the same
|
|
session to make a clone of a window in another window. It can be also
|
|
written to disk and read back in another session. In either case, use
|
|
the following function to restore the state of the window.
|
|
|
|
@defun window-state-put state &optional window ignore
|
|
This function puts the window state @var{state} into @var{window}. The
|
|
argument @var{state} should be the state of a window returned by an
|
|
earlier invocation of @code{window-state-get}, see above. The optional
|
|
argument @var{window} must specify a live window and defaults to the
|
|
selected one.
|
|
|
|
If the optional argument @var{ignore} is non-@code{nil}, it means to ignore
|
|
minimum window sizes and fixed-size restrictions. If @var{ignore}
|
|
is @code{safe}, this means windows can get as small as one line
|
|
and/or two columns.
|
|
@end defun
|
|
|
|
|
|
@node Window Parameters
|
|
@section Window Parameters
|
|
@cindex window parameters
|
|
|
|
This section 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 either @code{nil}, or an association list whose elements have 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
|
|
|
|
By default, the functions that save and restore window configurations or the
|
|
states of windows (@pxref{Window Configurations}) do not care about
|
|
window parameters. This means that when you change the value of a
|
|
parameter within the body of a @code{save-window-excursion}, the
|
|
previous value is not restored when that macro exits. It also means
|
|
that when you restore via @code{window-state-put} a window state saved
|
|
earlier by @code{window-state-get}, all cloned windows have their
|
|
parameters reset to @code{nil}. The following variable allows you to
|
|
override the standard behavior:
|
|
|
|
@defvar window-persistent-parameters
|
|
This variable is an alist specifying which parameters get saved by
|
|
@code{current-window-configuration} and @code{window-state-get}, and
|
|
subsequently restored by @code{set-window-configuration} and
|
|
@code{window-state-put}. @xref{Window Configurations}.
|
|
|
|
The @sc{car} of each entry of this alist is a symbol specifying the
|
|
parameter. The @sc{cdr} should be one of the following:
|
|
|
|
@table @asis
|
|
@item @code{nil}
|
|
This value means the parameter is saved neither by
|
|
@code{window-state-get} nor by @code{current-window-configuration}.
|
|
|
|
@item @code{t}
|
|
This value specifies that the parameter is saved by
|
|
@code{current-window-configuration} and (provided its @var{writable}
|
|
argument is @code{nil}) by @code{window-state-get}.
|
|
|
|
@item @code{writable}
|
|
This means that the parameter is saved unconditionally by both
|
|
@code{current-window-configuration} and @code{window-state-get}. This
|
|
value should not be used for parameters whose values do not have a read
|
|
syntax. Otherwise, invoking @code{window-state-put} in another session
|
|
may fail with an @code{invalid-read-syntax} error.
|
|
@end table
|
|
@end defvar
|
|
|
|
Some functions (notably @code{delete-window},
|
|
@code{delete-other-windows} and @code{split-window}), may behave specially
|
|
when their @var{window} argument has a parameter set. You can override
|
|
such special behavior by binding the following variable to a
|
|
non-@code{nil} value:
|
|
|
|
@defvar ignore-window-parameters
|
|
If this variable is non-@code{nil}, some standard functions do not
|
|
process window parameters. The functions currently affected by this are
|
|
@code{split-window}, @code{delete-window}, @code{delete-other-windows},
|
|
and @code{other-window}.
|
|
|
|
An application can bind this variable to a non-@code{nil} value around
|
|
calls to these functions. If it does so, the application is fully
|
|
responsible for correctly assigning the parameters of all involved
|
|
windows when exiting that function.
|
|
@end defvar
|
|
|
|
The following parameters are currently used by the window management
|
|
code:
|
|
|
|
@table @asis
|
|
@item @code{delete-window}
|
|
This parameter affects the execution of @code{delete-window}
|
|
(@pxref{Deleting Windows}).
|
|
|
|
@item @code{delete-other-windows}
|
|
This parameter affects the execution of @code{delete-other-windows}
|
|
(@pxref{Deleting Windows}).
|
|
|
|
@item @code{split-window}
|
|
This parameter affects the execution of @code{split-window}
|
|
(@pxref{Splitting Windows}).
|
|
|
|
@item @code{other-window}
|
|
This parameter affects the execution of @code{other-window}
|
|
(@pxref{Cyclic Window Ordering}).
|
|
|
|
@item @code{no-other-window}
|
|
This parameter marks the window as not selectable by @code{other-window}
|
|
(@pxref{Cyclic Window Ordering}).
|
|
|
|
@item @code{clone-of}
|
|
This parameter specifies the window that this one has been cloned
|
|
from. It is installed by @code{window-state-get} (@pxref{Window
|
|
Configurations}).
|
|
|
|
@item @code{quit-restore}
|
|
This parameter is installed by the buffer display functions
|
|
(@pxref{Choosing Window}) and consulted by @code{quit-restore-window}
|
|
(@pxref{Quitting Windows}). It contains four elements:
|
|
|
|
The first element is one of the symbols @code{window}, meaning that the
|
|
window has been specially created by @code{display-buffer}; @code{frame},
|
|
a separate frame has been created; @code{same}, the window has
|
|
displayed the same buffer before; or @code{other}, the window showed
|
|
another buffer before.
|
|
|
|
The second element is either one of the symbols @code{window} or
|
|
@code{frame}, or a list whose elements are the buffer shown in the
|
|
window before, that buffer's window start and window point positions,
|
|
and the window's height at that time.
|
|
|
|
The third element is the window selected at the time the parameter was
|
|
created. The function @code{quit-restore-window} tries to reselect that
|
|
window when it deletes the window passed to it as argument.
|
|
|
|
The fourth element is the buffer whose display caused the creation of
|
|
this parameter. @code{quit-restore-window} deletes the specified window
|
|
only if it still shows that buffer.
|
|
@end table
|
|
|
|
There are additional parameters @code{window-atom} and @code{window-side};
|
|
these are reserved and should not be used by applications.
|
|
|
|
|
|
@node Window Hooks
|
|
@section Hooks for Window Scrolling and Changes
|
|
@cindex hooks for window operations
|
|
|
|
This section describes how a Lisp program can take action whenever a
|
|
window displays a different part of its buffer or a different buffer.
|
|
There are three actions that can change this: scrolling the window,
|
|
switching buffers in the window, and changing the size of the window.
|
|
The first two actions run @code{window-scroll-functions}; the last runs
|
|
@code{window-size-change-functions}.
|
|
|
|
@defvar window-scroll-functions
|
|
This variable holds a list of functions that Emacs should call before
|
|
redisplaying a window with scrolling. 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 take care when using @code{window-end}
|
|
(@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
|
|
work.
|
|
@end defvar
|
|
|
|
@defvar window-size-change-functions
|
|
This variable holds a list of functions to be called if the size of any
|
|
window changes for any reason. The functions are called just once per
|
|
redisplay, and just once for each frame on which size changes have
|
|
occurred.
|
|
|
|
Each function receives the frame as its sole argument. There is no
|
|
direct way to find out which windows on that frame have changed size, or
|
|
precisely how. However, if a size-change function records, at each
|
|
call, the existing windows and their sizes, it can also compare the
|
|
present sizes and the previous sizes.
|
|
|
|
Creating or deleting windows counts as a size change, and therefore
|
|
causes these functions to be called. Changing the frame size also
|
|
counts, because it changes the sizes of the existing windows.
|
|
|
|
You may use @code{save-selected-window} in these functions
|
|
(@pxref{Selecting Windows}). However, do not use
|
|
@code{save-window-excursion} (@pxref{Window Configurations}); exiting
|
|
that macro counts as a size change, which would cause these functions
|
|
to be called over and over.
|
|
@end defvar
|
|
|
|
@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 buffer-local part of this hook is run once for 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}.
|