This chapter describes the functions and variables related to Emacs windows. See Frames, for how windows are assigned an area of screen available for Emacs to use. See Emacs Display, for information on how text is displayed in windows.
A window is an area of the screen that can be used to display a buffer (see Buffers). Windows are grouped into frames (see Frames). Each frame contains at least one window; the user can subdivide a frame 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.
Emacs uses the term “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 graphical X window owned by the Emacs process corresponds to one Emacs frame. When Emacs is run on a text terminal, each Emacs frame fills the entire terminal screen. In either case, the frame may contain one or more Emacs windows. For disambiguation, we use the term window-system window when we mean the window-system window corresponding to an Emacs frame.
Unlike X windows, Emacs windows are tiled; they never overlap within the area of their frame. When a window is created, resized, or deleted, the change in window space is taken from or given to other windows on the same frame, so that the total area of the frame is unchanged. The window layout of a frame is the result of all tiling operations for that frame.
In Emacs Lisp, windows are represented by a special Lisp object type (see Window Type). Two windows are identical if and only if they are represented by the same Lisp object.
This function returns t if object is a window (whether or
not it displays a buffer). Otherwise, it returns nil.
A live window is one that is actually displaying a buffer in a frame.
This function returns t if object is a live window and
nil otherwise. A live window is one that displays a buffer.
The windows in each frame are organized into a window tree. See 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 internal windows, which are not live.
A valid window is one that is either live or internal. A valid window can be deleted, i.e., removed from its frame (see 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 (see Window Configurations).
You can distinguish valid windows from deleted windows with
window-valid-p.
This function returns t if object is a live window, or an
internal window in a window tree. Otherwise, it returns nil,
including for the case where object is a deleted window.
The following schematic shows the structure of a live window:
____________________________________________
|________________ Tab Line _______________|RD| ^
|______________ Header Line ______________| | |
^ |LS|LM|LF| |RF|RM|RS| | |
| | | | | | | | | | |
Window | | | | | | | | | Window
Body | | | | | Window Body | | | | | Total
Height | | | | | | | | | Height
| | | | |<- Window Body Width ->| | | | | |
v |__|__|__|_______________________|__|__|__| | |
|_________ Horizontal Scroll Bar _________| | |
|_______________ Mode Line _______________|__| |
|_____________ Bottom Divider _______________| v
<---------- Window Total Width ------------>
At the center of that window is the body, where the buffer text is displayed. The body can be surrounded by a series of optional areas which we will call window decorations. On the left and right, from innermost to outermost, these are the left and right fringes, denoted by LF and RF (see Fringes); the left and right margins, denoted by LM and RM in the schematic (see Displaying in the Margins); the left or right vertical scroll bar, only one of which is present at any time, denoted by LS and RS (see Scroll Bars); and the right divider, denoted by RD (see Window Dividers). Together these are the window’s left and right decorations.
At the top of the window are the tab line and the header line (see Window Header Lines). The text area of the window includes the header line and the tab line, if they are present in the window. At the bottom of the window are the horizontal scroll bar (see Scroll Bars); the mode line (see Mode Line Format); and the bottom divider (see Window Dividers). Together these form the window’s top and bottom decorations.
There are two special areas omitted in the schematic:
In either case, the resulting artifact is considered part of the window’s body although its screen space cannot be used for displaying buffer text.
Note also, that line numbers (and their surrounding whitespace) as
displayed by display-line-numbers-mode (see Display Custom in The GNU Emacs Manual) do not count as decorations either; they
are part of the window’s body too.
Internal windows neither show any text nor do they have decorations. Hence, the concept of “body” does not make sense for them. In fact, most functions operating on the body of a window will yield an error when applied to an internal window.
By default, an Emacs frame exhibits one special live window that is used for displaying messages and accepting user input—the minibuffer window (see Minibuffer Windows). Since the minibuffer window is used for displaying text, it has a body but it does not have a tab or header line or any margins. Finally, a tooltip window which is used for displaying a tooltip in a tooltip frame (see Tooltips) has a body too but no decorations at all.
Each window belongs to exactly one frame (see Frames). For all windows belonging to a specific frame, we sometimes also say that these windows are owned by that frame or simply that they are on that frame.
This function returns the specified window’s frame—the frame
that window belongs to. If window is omitted or nil,
it defaults to the selected window (see Selecting Windows).
This function returns a list of all live windows owned by the specified
frame. If frame is omitted or nil, it defaults to
the selected frame (see Input Focus).
The optional argument minibuffer specifies whether to include the
minibuffer window (see Minibuffer Windows) in that list. If
minibuffer is t, the minibuffer window is included. If
nil or omitted, the minibuffer window is included only if it is
active. If minibuffer is neither nil nor t, the
minibuffer window is never included.
The optional argument window, if non-nil, must be a live
window on the specified frame; then window will be the first
element in the returned list. If window is omitted or nil,
the window selected within frame (see Selecting Windows) is
the first element.
Windows on the same frame are organized into a 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 root window. It is either a live window or an internal window. If it is a live window, then the frame has just one window besides the minibuffer window, or the frame is a minibuffer-only frame, see Frame Layout.
A minibuffer window (see Minibuffer Windows) that is not alone on
its frame does not have a parent window, so it strictly speaking is not
part of its frame’s window tree. Nonetheless, it is a sibling window of
the frame’s root window, and thus can be reached from the root window via
window-next-sibling, see below. Also, the function
window-tree described at the end of this section lists the
minibuffer window alongside the actual window tree.
This function returns the root window for frame-or-window. The
argument frame-or-window should be either a window or a frame;
if omitted or nil, it defaults to the selected frame. If
frame-or-window is a window, the return value is the root window
of that window’s frame.
When a live window is split (see Splitting Windows), 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 child windows of a single internal window. If necessary, Emacs automatically creates this internal window, which is also called the parent window, and assigns it to the appropriate position in the window tree. The set of windows that share the same parent are called siblings.
This function returns the parent window of window. If
window is omitted or nil, it defaults to the selected
window. The return value is nil if window has no parent
(i.e., it is a minibuffer window or the root window of its frame).
A parent window always has at least two child windows. If this number were to fall to one as a result of window deletion (see Deleting Windows), Emacs automatically deletes the parent window too, and its sole remaining child window takes its place in the window tree.
A 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 screen area—the union of the areas occupied by the live windows that are ultimately descended from it.
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 vertical combination; if they are arranged side by side, they are said to form a horizontal combination. Consider the following example:
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
The root window of this frame is an internal window, W1. Its child windows form a horizontal combination, consisting of the live window W2 and the internal window W3. The child windows of W3 form a vertical combination, consisting of the live windows W4 and W5. Hence, the live windows in this window tree are W2, W4, and W5.
The following functions can be used to retrieve a child window of an internal window, and the siblings of a child window. Their window argument always defaults to the selected window (see Selecting Windows).
This function returns the topmost child window of window, if
window is an internal window whose children form a vertical
combination. For any other type of window, the return value is
nil.
This function returns the leftmost child window of window, if
window is an internal window whose children form a horizontal
combination. For any other type of window, the return value is
nil.
This function returns the first child window of the internal window
window—the topmost child window for a vertical combination, or
the leftmost child window for a horizontal combination. If
window is a live window, the return value is nil.
This function returns a non-nil value if and only if
window is part of a vertical combination.
If the optional argument horizontal is non-nil, this
means to return non-nil if and only if window is part of
a horizontal combination.
This function returns the next sibling of the specified window. The
return value is nil if window is the last child of its
parent.
This function returns the previous sibling of the specified window.
The return value is nil if window is the first child of its
parent.
The functions window-next-sibling and window-prev-sibling
should not be confused with the functions next-window and
previous-window, which return the next and previous window in the
cyclic ordering of windows (see Cyclic Ordering of Windows).
The following functions can be useful to locate a window within its frame.
This function returns the live window at the upper left corner of the
frame specified by frame-or-window. The argument
frame-or-window must denote a window or a live frame and defaults
to the selected frame. If 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
(frame-first-window) returns W2.
This function returns t if window is located at
side of its containing frame. The argument window must be
a valid window and defaults to the selected one. The argument
side can be any of the symbols left, top,
right or bottom. The default value nil is
handled like bottom.
Note that this function disregards the minibuffer window
(see Minibuffer Windows). Hence, with side equal to
bottom it may return t also when the minibuffer window
appears right below window.
This function returns the nearest live window in direction
direction as seen from the position of window’s point
(see Windows and Point). The argument direction must be one of
above, below, left or right. The optional
argument window must denote a live window and defaults to the
selected one.
This function does not return a window for which
window-no-other-p (see Cyclic Ordering of Windows) returns
non-nil. If the nearest window’s no-other-window
parameter is non-nil, this function tries to find another window
in the indicated direction whose no-other-window parameter is
nil. However, if the optional argument ignore is
non-nil, a window may be returned even if its
no-other-window parameter is non-nil.
If the optional argument sign is a negative number, it means to
use the right or bottom edge of window as reference position
instead of window-point. If sign is a positive number, it
means to use the left or top edge of window as reference position.
If the optional argument wrap is non-nil, this means to
wrap direction around frame borders. For example, if window
is at the top of the frame and direction is above, then
this function usually returns the frame’s minibuffer window if it’s
active and a window at the bottom of the frame otherwise.
If the optional argument minibuf is t, this function may
return the minibuffer window even when it’s not active. If the
optional argument minibuf is nil, this means to return
the minibuffer window if and only if it is currently active.
If minibuf is neither nil nor t, this function
never returns the minibuffer window. However, if wrap is
non-nil, it always acts as if minibuf were nil.
If it doesn’t find a suitable window, this function returns
nil.
Don’t use this function to check whether there is no window in
direction. Calling window-at-side-p described above is a
much more efficient way to do that.
The following function retrieves the entire window tree of a frame:
This function returns a list representing the window tree for frame
frame. If frame is omitted or nil, it defaults to
the selected frame.
The return value is a list of the form (root mini),
where root represents the window tree of the frame’s root
window, and mini is the frame’s minibuffer window.
If the root window is live, root is that window itself.
Otherwise, root is a list (dir edges w1
w2 ...) where dir is nil for a horizontal
combination and t for a vertical combination, 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 edges element is a list (left
top right bottom), similar to the value returned by
window-edges (see Coordinates and Windows).
In each frame, at any time, exactly one Emacs window is designated
as selected within the frame. For the selected frame, that
window is called the selected window—the one in which most
editing takes place, and in which the cursor for selected windows
appears (see Cursor Parameters). Keyboard input that inserts or
deletes text is also normally directed to this window. The selected
window’s buffer is usually also the current buffer, except when
set-buffer has been used (see The Current Buffer). As for
non-selected frames, the window selected within the frame becomes the
selected window if the frame is ever selected.
This function returns the selected window (which is always a live window).
The following function explicitly selects a window and its frame.
This function makes window the selected window and the window
selected within its frame, and selects that frame. It also makes
window’s buffer (see Buffers and Windows) current and sets
that buffer’s value of point to the value of window-point
(see Windows and Point) in window. window must be a live
window. The return value is window.
By default, this function also moves window’s buffer to the front
of the buffer list (see The Buffer List) and makes window the most
recently selected window. If the optional argument norecord is
non-nil, these additional actions are omitted.
In addition, this function by default also tells the display engine to
update the display of window when its frame gets redisplayed the
next time. If norecord is non-nil, such updates are
usually not performed. If, however, norecord equals the special
symbol mark-for-redisplay, the additional actions mentioned above
are omitted but window’s display will be nevertheless updated.
Note that sometimes selecting a window is not enough to show it, or make its frame the top-most frame on display: you may also need to raise the frame or make sure input focus is directed to that frame. See Input Focus.
For historical reasons, Emacs does not run a separate hook whenever a window gets selected. Applications and internal routines often temporarily select a window to perform a few actions on it. They do that either to simplify coding—because many functions by default operate on the selected window when no window argument is specified—or because some functions did not (and still do not) take a window as argument and always operate(d) on the selected window instead. Running a hook every time a window gets selected for a short time and once more when the previously selected window gets restored is not useful.
However, when its norecord argument is nil,
select-window updates the buffer list and thus indirectly runs
the normal hook buffer-list-update-hook (see The Buffer List).
Consequently, that hook provides one way to run a function whenever a
window gets selected more “permanently”.
Since buffer-list-update-hook is also run by functions that are
not related to window management, it will usually make sense to save the
value of the selected window somewhere and compare it with the value of
selected-window while running that hook. Also, to avoid false
positives when using buffer-list-update-hook, it is good practice
that every select-window call supposed to select a window only
temporarily passes a non-nil norecord argument. If
possible, the macro with-selected-window (see below) should be
used in such cases.
Emacs also runs the hook window-selection-change-functions
whenever the redisplay routine detects that another window has been
selected since last redisplay. See Hooks for Window Scrolling and Changes, for a detailed
explanation. window-state-change-functions (described in the
same section) is another abnormal hook run after a different window
has been selected but is triggered by other window changes as well.
The sequence of calls to select-window with a non-nil
norecord argument determines an ordering of windows by their
selection or use time, see below. The function get-lru-window,
for example, can then be used to retrieve the least recently selected
window (see Cyclic Ordering of Windows).
This function returns the window on frame that is selected
within that frame. frame should be a live frame; if omitted or
nil, it defaults to the selected frame.
This function makes window the window selected within the frame
frame. frame should be a live frame; if nil, it
defaults to the selected frame. window must denote a live window.
If frame is the selected frame, this makes window the selected window.
If the optional argument norecord is non-nil, this function
does not alter the ordering of the most recently selected windows, nor
the buffer list.
The following macros are useful to temporarily select a window without affecting the ordering of recently selected windows or the buffer list.
This macro records the selected frame, as well as the selected window of each frame, executes 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 forms.
This macro does not save or restore anything about the sizes, arrangement or contents of windows; therefore, if forms change them, the change persists. If the previously selected window of some frame is no longer live at the time of exit from 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 forms remains selected. The current buffer is restored if and only if it is still live when exiting forms.
This macro changes neither the ordering of recently selected windows nor the buffer list.
This macro selects window, executes 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 forms; for
example, by calling select-window with argument norecord
nil. Hence, this macro is the preferred way to temporarily work
with window as the selected window without needlessly running
buffer-list-update-hook.
Note that this macro temporarily puts the window management code in an
unstable state. In particular, the most recently used window (see below)
will not necessarily match the selected one. Hence, functions like
get-lru-window and get-mru-window may return unexpected
results when called from the body of this macro.
This macro executes forms with frame as the selected frame. The value returned is the value of the last form in forms. This macro saves and restores the selected frame, and changes the order of neither the recently selected windows nor the buffers in the buffer list.
This function returns the use time of window window. window must be a live window and defaults to the selected one.
The use time of a window is not really a time value, but an
integer that does increase monotonically with each call of
select-window with a nil norecord argument. The
window with the lowest use time is usually called the least recently
used window. The window with the highest use time is called the most
recently used one (see Cyclic Ordering of Windows) and is usually the
selected window unless with-selected-window has been used.
This function marks window as being the second most recently
used one (after the selected window). It does nothing if window
is the selected window or the selected window does not have the
highest use time among all windows which may happen within the scope
of with-selected-window.
Sometimes several windows collectively and
cooperatively display a buffer, for example, under the management of
Follow Mode (see (emacs)Follow Mode), where the windows together
display a bigger portion of the buffer than one window could alone.
It is often useful to consider such a window group as a single
entity. Several functions such as window-group-start
(see The Window Start and End Positions) allow you to do this by supplying, as
an argument, one of the windows as a stand-in for the whole group.
When the selected window is a member of a group of windows, this function returns a list of the windows in the group, ordered such that the first window in the list is displaying the earliest part of the buffer, and so on. Otherwise the function returns a list containing just the selected window.
The selected window is considered part of a group when the buffer
local variable selected-window-group-function is set to a
function. In this case, selected-window-group calls it with no
arguments and returns its result (which should be the list of windows
in the group).
Emacs provides miscellaneous functions for finding the height and width
of a window. The return value of many of these functions can be
specified either in units of pixels or in units of canonical lines and
columns. On a graphical display, the latter actually correspond to the
height and width of a default character specified by the frame’s default
font as returned by frame-char-height and frame-char-width
(see Frame Font). Thus, if a window is displaying text with a
different font or size, the reported line height and column width for
that window may differ from the actual number of text lines or columns
displayed within it.
The total height of a window is the number of lines comprising its body and its top and bottom decorations (see Basic Concepts of Emacs Windows).
This function returns the total height, in canonical lines, of the
window window. If window is omitted or nil, it
defaults to the selected window. If window is an internal window,
the return value is the total height occupied by its descendant windows.
If a window’s pixel height is not an integral multiple of its frame’s default character height, the number of lines occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total heights of all its child windows internally equals the total height of their parent. This means that although two windows have the same pixel height, their internal total heights may differ by one line. This means also, that if a window is vertically combined and has a next sibling, the topmost row of that sibling can be calculated as the sum of this window’s topmost row and total height (see Coordinates and Windows)
If the optional argument round is ceiling, this function
returns the smallest integer larger than window’s pixel height
divided by the canonical character height of its frame; if it is
floor, it returns the largest integer smaller than said value;
with any other value of round it returns the internal value of
windows’s total height.
The total width of a window is the number of columns comprising its body and its left and right decorations (see Basic Concepts of Emacs Windows).
This function returns the total width, in canonical columns, of the
window window. If window is omitted or nil, it
defaults to the selected window. If window is internal, the
return value is the total width occupied by its descendant windows.
If a window’s pixel width is not an integral multiple of its frame’s
canonical character width, the number of columns occupied by the window
is rounded internally. This is done in a way such that, if the window
is a parent window, the sum of the total widths of all its children
internally equals the total width of their parent. This means that
although two windows have the same pixel width, their internal total
widths may differ by one column. This means also, that if this window
is horizontally combined and has a next sibling, the leftmost column of
that sibling can be calculated as the sum of this window’s leftmost
column and total width (see Coordinates and Windows). The optional
argument round behaves as it does for window-total-height.
This function returns either the total height in lines or the total
width in columns of the window window. If horizontal is
omitted or nil, this is equivalent to calling
window-total-height for window; otherwise it is equivalent
to calling window-total-width for window. The optional
argument round behaves as it does for window-total-height.
The following two functions can be used to return the total size of a window in units of pixels.
This function returns the total height of window window in pixels. window must be a valid window and defaults to the selected one.
The return value includes the heights of window’s top and bottom decorations. If window is an internal window, its pixel height is the pixel height of the screen areas spanned by its children.
This function returns the width of window window in pixels. window must be a valid window and defaults to the selected one.
The return value includes the widths of window’s left and right decorations. If window is an internal window, its pixel width is the width of the screen areas spanned by its children.
The following functions can be used to determine whether a given window has any adjacent windows.
This function returns non-nil if window has no other window
above or below it in its frame. More precisely, this means that the
total height of window equals the total height of the root window
on that frame. The minibuffer window does not count in this regard. If
window is omitted or nil, it defaults to the selected
window.
This function returns non-nil if 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 window is omitted or
nil, it defaults to the selected window.
The body height of a window is the height of its body, which does not include any of its top or bottom decorations (see Basic Concepts of Emacs Windows).
This function returns the height, in canonical lines, of the body of
window window. If window is omitted or nil, it
defaults to the selected window; otherwise it must be a live window.
The optional argument pixelwise defines the units to use for the
height. If nil, return the body height of window in
canonical characters, rounded down to the nearest integer, if necessary.
This means that if a line at the bottom of the text area is only
partially visible, that line is not counted. It also means that the
height of a window’s body can never exceed its total height as returned
by window-total-height.
If pixelwise is remap and the default face is remapped
(see Face Remapping), use the remapped face to determine the
character height. For any other non-nil value, return the
height in pixels.
The body width of a window is the width of its body and of the text area, which does not include any of its left or right decorations (see Basic Concepts of Emacs Windows).
Note that when one or both fringes are removed (by setting their width
to zero), the display engine reserves two character cells, one on each
side of the window, for displaying the continuation and truncation
glyphs, which leaves 2 columns less for text display. (The function
window-max-chars-per-line, described below, takes this
peculiarity into account.)
This function returns the width, in canonical columns, of the body of
window window. If window is omitted or nil, it
defaults to the selected window; otherwise it must be a live window.
The optional argument pixelwise defines the units to use for the
width. If nil, return the body width of window in
canonical characters, rounded down to the nearest integer, if necessary.
This means that if a column on the right of the text area is only
partially visible, that column is not counted. It also means that the
width of a window’s body can never exceed its total width as returned by
window-total-width.
If pixelwise is remap and the default face is remapped
(see Face Remapping), use the remapped face to determine the
character width. For any other non-nil value, return the width
in pixels.
This function returns the body height or body width of window. If
horizontal is omitted or nil, it is equivalent to calling
window-body-height for window; otherwise it is equivalent
to calling window-body-width. In either case, the optional
argument pixelwise is passed to the function called.
The pixel heights of a window’s mode, tab and header line can be retrieved with the functions given below. Their return value is usually accurate unless the window has not been displayed before: In that case, the return value is based on an estimate of the font used for the window’s frame.
This function returns the height in pixels of window’s mode line. window must be a live window and defaults to the selected one. If window has no mode line, the return value is zero.
This function returns the height in pixels of window’s tab line. window must be a live window and defaults to the selected one. If window has no tab line, the return value is zero.
This function returns the height in pixels of window’s header line. window must be a live window and defaults to the selected one. If window has no header line, the return value is zero.
Functions for retrieving the height and/or width of window dividers (see Window Dividers), fringes (see Fringes), scroll bars (see Scroll Bars), and display margins (see Displaying in the Margins) are described in the corresponding sections.
If your Lisp program needs to make layout decisions, you will find the following function useful:
This function returns the number of characters displayed in the
specified face face in the specified window window (which
must be a live window). If face was remapped (see Face Remapping), the information is returned for the remapped face. If
omitted or nil, face defaults to the default face, and
window defaults to the selected window.
Unlike window-body-width, this function accounts for the actual
size of face’s font, instead of working in units of the canonical
character width of window’s frame (see Frame Font). It also
accounts for space used by the continuation glyph, if window lacks
one or both of its fringes.
Commands that change the size of windows (see Resizing Windows),
or split them (see Splitting Windows), obey the variables
window-min-height and window-min-width, which specify the
smallest allowable window height and width. They also obey the variable
window-size-fixed, with which a window can be fixed in
size (see Preserving Window Sizes).
This option specifies the minimum total height, in lines, of any window. Its value has to accommodate at least one text line and any top or bottom decorations.
This option specifies the minimum total width, in columns, of any window. Its value has to accommodate at least two text columns and any left or right decorations.
The following function tells how small a specific window can get taking
into account the sizes of its areas and the values of
window-min-height, window-min-width and
window-size-fixed (see Preserving Window Sizes).
This function returns the minimum size of window. window
must be a valid window and defaults to the selected one. The optional
argument horizontal non-nil means to return the minimum
number of columns of window; otherwise return the minimum number
of window’s lines.
The return value makes sure that all components of window remain
fully visible if window’s size were actually set to it. With
horizontal nil it includes any top or bottom decorations.
With horizontal non-nil it includes any left or right
decorations of window.
The optional argument ignore, if non-nil, means ignore
restrictions imposed by fixed size windows, window-min-height or
window-min-width settings. If ignore equals safe,
live windows may get as small as window-safe-min-height lines and
window-safe-min-width columns. If ignore is a window,
ignore restrictions for that window only. Any other non-nil
value means ignore all of the above restrictions for all windows.
The optional argument pixelwise non-nil means to return the
minimum size of window counted in pixels.
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 at least one other window. If there is just one window on a frame, its size cannot be changed except by resizing the frame (see Frame Size).
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.
This function returns delta if the size of window can be
changed vertically by delta lines. If the optional argument
horizontal is non-nil, it instead returns delta if
window can be resized horizontally by delta columns. It
does not actually change the window size.
If window is nil, it defaults to the selected window.
A positive value of delta means to check whether the window can be enlarged by that number of lines or columns; a negative value of delta means to check whether the window can be shrunk by that many lines or columns. If delta is non-zero, a return value of 0 means that the window cannot be resized.
Normally, the variables window-min-height and
window-min-width specify the smallest allowable window size
(see Window Sizes). However, if the optional argument ignore
is non-nil, this function ignores window-min-height and
window-min-width, as well as window-size-fixed. Instead,
it considers the minimum height of a window as the sum of its top and
bottom decorations plus the text of one line; and its minimum width
as the sum of its left and right decorations plus text that takes two
columns.
If the optional argument pixelwise is non-nil,
delta is interpreted as pixels.
This function resizes window by delta increments. If
horizontal is nil, it changes the height by delta
lines; otherwise, it changes the width by delta columns. A
positive delta means to enlarge the window, and a negative
delta means to shrink it.
If window is nil, it defaults to the selected window. If
the window cannot be resized as demanded, an error is signaled.
The optional argument ignore has the same meaning as for the
function window-resizable above.
If the optional argument pixelwise is non-nil,
delta will be interpreted as pixels.
The choice of which window edges this function alters depends on the
values of the option window-combination-resize and the
combination limits of the involved windows; in some cases, it may alter
both edges. See Recombining Windows. To resize by moving only the
bottom or right edge of a window, use the function
adjust-window-trailing-edge.
This function moves window’s bottom edge by delta lines.
If optional argument horizontal is non-nil, it instead
moves the right edge by delta columns. If window is
nil, it defaults to the selected window.
If the optional argument pixelwise is non-nil,
delta is interpreted as pixels.
A positive delta moves the edge downwards or to the right; a negative delta moves it upwards or to the left. If the edge cannot be moved as far as specified by delta, this function moves it as far as possible but does not signal an 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.
If the value of this option is non-nil, Emacs resizes windows in
units of pixels. This currently affects functions like
split-window (see Splitting Windows), maximize-window,
minimize-window, fit-window-to-buffer,
fit-frame-to-buffer and
shrink-window-if-larger-than-buffer (all listed below).
Note that when a frame’s pixel size is not a multiple of its character
size, at least one window may get resized pixelwise even if this
option is nil. The default value is nil.
The following commands resize windows in more specific ways. When called interactively, they act on the selected window.
This command adjusts the height or width of window to fit the text
in it. It returns non-nil if it was able to resize window,
and nil otherwise. If window is omitted or nil, it
defaults to the selected window. Otherwise, it should be a live window.
If window is part of a vertical combination, this function adjusts
window’s height. The new height is calculated from the actual
height of the accessible portion of its buffer. The optional argument
max-height, if non-nil, specifies the maximum total height
that this function can give window. The optional argument
min-height, if non-nil, specifies the minimum total height
that it can give, which overrides the variable window-min-height.
Both max-height and min-height are specified in lines and
include any top or bottom decorations of window.
If window is part of a horizontal combination and the value of the
option fit-window-to-buffer-horizontally (see below) is
non-nil, this function adjusts window’s width. The new
width of window is calculated from the maximum length of its
buffer’s lines that follow the current start position of window.
The optional argument max-width specifies a maximum width and
defaults to the width of window’s frame. The optional argument
min-width specifies a minimum width and defaults to
window-min-width. Both max-width and min-width are
specified in columns and include any left or right decorations of
window.
The optional argument preserve-size, if non-nil, will
install a parameter to preserve the size of window during future
resize operations (see Preserving Window Sizes).
If the option fit-frame-to-buffer (see below) is non-nil,
this function will try to resize the frame of window to fit its
contents by calling fit-frame-to-buffer (see below).
If this is non-nil, fit-window-to-buffer can resize
windows horizontally. If this is nil (the default)
fit-window-to-buffer never resizes windows horizontally. If this
is only, it can resize windows horizontally only. Any other
value means fit-window-to-buffer can resize windows in both
dimensions.
If this option is non-nil, fit-window-to-buffer can fit a
frame to its buffer. A frame is fit if and only if its root window is a
live window and this option is non-nil. If this is
horizontally, frames are fit horizontally only. If this is
vertically, frames are fit vertically only. Any other
non-nil value means frames can be resized in both dimensions.
If you have a frame that displays only one window, you can fit that
frame to its buffer using the command fit-frame-to-buffer.
This command adjusts the size of frame to display the contents of
its buffer exactly. frame can be any live frame and defaults to
the selected one. Fitting is done only if frame’s root window is
a live window. On window systems that use size hints, exact fitting can
be often achieved if and only if frame-resize-pixelwise
(see Frame Size) is non-nil.
The arguments max-height, min-height, max-width and
min-width, if non-nil, specify bounds on the new body size
of frame’s root window. A non-nil value specified by any
of these arguments overrides the corresponding value specified by
the option fit-frame-to-buffer-sizes described below.
If the optional argument only is vertically, this function
may resize the frame vertically only. If only is
horizontally, it may resize the frame horizontally only.
The behavior of fit-frame-to-buffer can be controlled with the
help of the two options listed next.
This option can be used to specify margins around frames to be fit by
fit-frame-to-buffer. Such margins can be useful to avoid, for
example, that the resized frame overlaps the taskbar or parts of its
parent frame.
It specifies the numbers of pixels to be left free on the left, above,
the right, and below a frame that shall be fit. The default specifies
nil for each which means to use no margins. The value specified
here can be overridden for a specific frame by that frame’s
fit-frame-to-buffer-margins parameter, if present.
This option specifies size boundaries for fit-frame-to-buffer.
It specifies the maximum and minimum lines and maximum and minimum
columns of the root window’s body of any frame that shall be fit to its
buffer. Any value this option specifies will be overridden by the
corresponding argument of fit-frame-to-buffer, if non-nil.
This command attempts to reduce window’s height as much as
possible while still showing its full buffer, but no less than
window-min-height lines. The return value is non-nil if
the window was resized, and nil otherwise. If window is
omitted or 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.
This command calls fit-window-to-buffer (see above) to do its
work.
This function balances windows in a way that gives more space to full-width and/or full-height windows. If window-or-frame specifies a frame, it balances all windows on that frame. If window-or-frame specifies a window, it balances only that window and its siblings (see Windows and Frames).
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.
This function attempts to make window as large as possible, in
both dimensions, without resizing its frame or deleting other windows.
If window is omitted or nil, it defaults to the selected
window.
This function attempts to make window as small as possible, in
both dimensions, without deleting it or resizing its frame. If
window is omitted or nil, it defaults to the selected
window.
A window can get resized explicitly by using one of the functions from the preceding section or implicitly, for example, when resizing an adjacent window, when splitting or deleting a window (see Splitting Windows, see Deleting Windows) or when resizing the window’s frame (see Frame Size).
It is possible to avoid implicit resizing of a specific window when there are one or more other resizable windows on the same frame. For this purpose, Emacs must be advised to preserve the size of that window. There are two basic ways to do that.
If this buffer-local variable is non-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 the window’s size, if there
is no choice.
If the value is height, then only the window’s height is fixed;
if the value is width, then only the window’s width is fixed.
Any other non-nil value fixes both the width and the height.
If this variable is nil, this does not necessarily mean that any
window showing the buffer can be resized in the desired direction. To
determine that, use the function window-resizable.
See Resizing Windows.
Often window-size-fixed is overly aggressive because it inhibits
any attempt to explicitly resize or split an affected window as well.
This may even happen after the window has been resized implicitly, for
example, when deleting an adjacent window or resizing the window’s
frame. The following function tries hard to never disallow resizing
such a window explicitly:
This function (un-)marks the height of window window as preserved
for future resize operations. window must be a live window and
defaults to the selected one. If the optional argument horizontal
is non-nil, it (un-)marks the width of window as preserved.
If the optional argument preserve is t, this means to
preserve the current height/width of window’s body. The
height/width of window will change only if Emacs has no better
choice. Resizing a window whose height/width is preserved by this
function never throws an error.
If preserve is nil, this means to stop preserving the
height/width of window, lifting any respective restraint induced
by a previous call of this function for window. Calling
enlarge-window, shrink-window or
fit-window-to-buffer with window as argument may also
remove the respective restraint.
window-preserve-size is currently invoked by the following
functions:
fit-window-to-bufferIf the optional argument preserve-size of that function
(see Resizing Windows) is non-nil, the size established by
that function is preserved.
display-bufferIf the alist argument of that function (see Choosing a Window for Displaying a Buffer)
contains a preserve-size entry, the size of the window produced
by that function is preserved.
window-preserve-size installs a window parameter (see Window Parameters) called window-preserved-size which is consulted by the
window resizing functions. This parameter will not prevent resizing the
window when the window shows another buffer than the one when
window-preserve-size was invoked or if its size has changed since
then.
The following function can be used to check whether the height of a particular window is preserved:
This function returns the preserved height of window window in
pixels. window must be a live window and defaults to the selected
one. If the optional argument horizontal is non-nil, it
returns the preserved width of window. It returns nil if
the size of window is not preserved.
This section describes functions for creating a new window by splitting an existing one. Note that some windows are special in the sense that these functions may fail to split them as described here. Examples of such windows are side windows (see Side Windows) and atomic windows (see Atomic Windows).
This function creates a new live window next to the window
window. If window is omitted or 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 size determines the sizes of
window and/or the new window. If it is omitted or nil,
both windows are given equal sizes; if there is an odd line, it is
allocated to the new window. If size is a positive number,
window is given size lines (or columns, depending on the
value of side). If size is a negative number, the new
window is given −size lines (or columns).
If size is nil, this function obeys the variables
window-min-height and window-min-width (see Window Sizes). Thus, it signals an error if splitting would result in making
a window smaller than those variables specify. However, a
non-nil value for 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 that is one line tall and/or two columns
wide.
Hence, if size is specified, it’s the caller’s responsibility to
check whether the emanating windows are large enough to encompass all of
their decorations like a mode line or a scroll bar. The function
window-min-size (see Window Sizes) can be used to determine
the minimum requirements of window in this regard. Since the new
window usually inherits areas like the mode line or the scroll bar from
window, that function is also a good guess for the minimum size of
the new window. The caller should specify a smaller size only if it
correspondingly removes an inherited area before the next redisplay.
The optional third argument side determines the position of the
new window relative to window. If it is nil or
below, the new window is placed below window. If it is
above, the new window is placed above window. In both
these cases, size specifies a total window height, in lines.
If side is t or right, the new window is placed on
the right of window. If side is left, the new
window is placed on the left of window. In both these cases,
size specifies a total window width, in columns.
As a rule, if window already forms a combination (see Windows and Frames) that matches side (a horizontal combination matches
side if it is left or right, a vertical combination
matches side if it is above or below) and
window-combination-limit (see Recombining Windows) is
nil, this function reuses window’s parent in the window
tree as parent of the new window.
However, if window is in a combination that does not match
side or if window-combination-limit is non-nil, this
function makes a new parent window that replaces window in the
window tree and makes window and the new window its sole child
windows. This standard behavior can be overridden via the refer
argument.
The optional fourth argument pixelwise, if non-nil, means
to interpret size in units of pixels, instead of lines and
columns.
If the optional fifth argument refer is non-nil, it
specifies a reference window used for setting up properties of the new
window. If non-nil, refer can be either a window or a cons
cell of two windows.
If refer is a cons cell, its CAR has to specify a deleted, former live window – a window that has shown a buffer before – on the same frame as window. That buffer must be still live. The CDR has to specify a deleted window that was, before its deletion, a parent window on the same frame as window. In this case, rather then making new windows, this function replaces window with the CDR of refer in the window tree and makes window and refer’s CAR its new child windows. Buffer, start and point positions of refer’s CAR are set to the values they had immediately before refer’s CAR was deleted the last time. Decorations and parameters remain unaltered from their values before refer’s CAR and CDR were deleted.
Alternatively, refer may specify a deleted, former live window – a window that has shown a buffer before – on the same frame as window. That buffer must be still live. In this case, this function does not make a new window but rather makes refer live again and inserts it into the window tree at the position and with the sizes the new window would have been given. Buffer, start and point positions of refer are set to the values they had immediately before refer was deleted the last time. Decorations and parameters remain unaltered from their values before refer was deleted. The parent of refer is then determined as if it were a window created anew.
In any other case, refer must specify a live window. Then the new
window will inherit properties like buffer, start and point positions
and some decorations from refer. If refer is nil or
omitted, then if window is live, the new window inherits these
properties from window. If, however, window is an internal
window, the new window will inherit these properties from the window
selected on window’s frame.
The behavior of this function may be altered by the window parameters
of window, so long as the variable
ignore-window-parameters is nil. If the value of
the split-window window parameter is t, this function
ignores all other window parameters. Otherwise, if the value of the
split-window window parameter is a function, that function is
called with the arguments window, size, and side, in
lieu of the usual action of split-window. Otherwise, this
function obeys the window-atom or window-side window
parameter, if any. See Window Parameters.
As an example, here is a sequence of split-window calls that
yields the window configuration discussed in 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 W4. Calling
(split-window W4) yields this window configuration:
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
|| ||
|| ||
|| ||
||_________________W5_________________||
|__________________W3__________________|
The split-window call has created a new live window, denoted by
W5. It has also created a new internal window, denoted by
W3, which becomes the root window and the parent of both
W4 and W5.
Next, we call (split-window W3 nil 'left), passing the
internal window W3 as the argument. The result:
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| ||| |||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
A new live window W2 is created, to the left of the internal window W3. A new internal window W1 is created, becoming the new root window.
For interactive use, Emacs provides two commands which always split
the selected window. These call split-window internally.
This function splits the window window-to-split into two side-by-side windows, putting window-to-split on the left. window-to-split defaults to the selected window. If size is positive, the left window gets size columns; if size is negative, the right window gets −size columns.
This function splits the window window-to-split into two windows, one above the other, leaving the upper window selected. window-to-split defaults to the selected window. If size is positive, the upper window gets size lines; if size is negative, the lower window gets −size lines.
This function splits the whole frame in two. The current window
configuration is retained on the top, and a new window is created
below, taking up the whole width of the frame. size is treated
as by split-window-below.
This function splits the whole frame in two. The current window
configuration is retained on the left, and a new window is created on
the right, taking up the whole height of the frame. size is treated
as by split-window-right.
If the value of this variable is non-nil (the default),
split-window-below behaves as described above.
If it is nil, 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
split-window-below, not the lower-level split-window
function.
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 (see Window Configurations).
This function removes window from display and returns
nil. If window is omitted or 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) or all remaining windows on window’s frame are side windows (see Side Windows), an error is signaled. If window is part of an atomic window (see Atomic Windows), this function tries to delete the root of that atomic window instead.
By default, the space taken up by window is given to one of its
adjacent sibling windows, if any. However, if the variable
window-combination-resize is non-nil, the space is
proportionally distributed among any remaining windows in the same
window combination. See Recombining Windows.
The behavior of this function may be altered by the window parameters of
window, so long as the variable ignore-window-parameters is
nil. If the value of the delete-window window parameter
is t, this function ignores all other window parameters.
Otherwise, if the value of the delete-window window parameter is
a function, that function is called with the argument window, in
lieu of the usual action of delete-window. See Window Parameters.
When delete-window deletes the selected window of its frame, it
has to make another window the new selected window of that frame. The
following option allows configuring which window is chosen.
This option allows specifying which window should become a frame’s
selected window after delete-window has deleted the previously
selected one. Possible choices are
mru
(the default) means to choose the most recently used window
(see Cyclic Ordering of Windows) other than the selected one on that
frame.
pos
means to choose the window comprising the position of
window-point (see Windows and Point) of the previously selected
window on that frame.
nil
means to choose the first window (the window returned by
frame-first-window, see Windows and Frames) on that frame.
A window for which window-no-other-p (see Cyclic Ordering of Windows) returns non-nil is chosen only if all other windows on
that frame have their no-other-window parameter set to a
non-nil value too.
This function makes window fill its frame, deleting other
windows as necessary. If window is omitted or nil, it
defaults to the selected window. An error is signaled if window
is a side window (see Side Windows). If window is part of
an atomic window (see Atomic Windows), this function tries to make
the root of that atomic window fill its frame. The return
value is nil.
The behavior of this function may be altered by the window parameters of
window, so long as the variable ignore-window-parameters is
nil. If the value of the delete-other-windows window
parameter is t, this function ignores all other window
parameters. Otherwise, if the value of the delete-other-windows
window parameter is a function, that function is called with the
argument window, in lieu of the usual action of
delete-other-windows. See Window Parameters.
Also, if ignore-window-parameters is nil, this function
does not delete any window whose no-delete-other-windows
parameter is non-nil.
This function deletes all windows showing buffer-or-name, by
calling delete-window on those windows. buffer-or-name
should be a buffer, or the name of a buffer; if omitted or 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 frame specifies which frames to operate on:
nil
means operate on all frames.
t
means operate on the selected frame.
visible
means operate on all visible frames.
0
means operate on all visible or iconified frames.
Note that this argument does not have the same meaning as in other
functions which scan all live windows (see Cyclic Ordering of Windows). Specifically, the meanings of t and nil here
are the opposite of what they are in those other functions.
The above commands delete windows explicitly. However, Emacs may also
delete a window implicitly when it thinks that it’s more intuitive to
eliminate it rather than showing some unrelated buffer in it. Functions
that may delete windows implicitly are kill-buffer
(see Killing Buffers), quit-restore-window (see Quitting Windows) and bury-buffer (see The Buffer List). Some of these
delete a window if and only if that window is dedicated to its buffer
(see Dedicated Windows). Others delete a window when that window
has been created by display-buffer (see Displaying a Buffer in a Suitable Window).
Some will also try to delete a window’s frame together with the window,
provided there are other frames on the same terminal and the frame does
not host the active minibuffer window.
The hook described next can be used to avoid that a window gets deleted by these functions.
This is an abnormal hook that can be used to avoid that a window gets
deleted implicitly. The value should be a list of functions that take
two arguments. The first argument is the window about to be deleted.
The second argument, if non-nil, means that the window is the
only window on its frame and would be deleted together with its frame.
The window’s buffer is current when running this hook.
If any of these functions returns nil, the window will not be
deleted and another buffer will be shown in it. This hook is run
(indirectly) by the functions quit-restore-window,
kill-buffer and bury-buffer. It is not run by functions
that delete windows explicitly like delete-window,
delete-other-windows or delete-windows-on.
The purpose of this hook is to give its clients a chance to save a window or its frame from deletion because they might still want to use that window or frame for their own purposes.
When deleting the last sibling of a window W, its parent window is deleted too, with W replacing it in the window tree. This means that W must be recombined with its parent’s siblings to form a new window combination (see Windows and Frames). In some occasions, deleting a live window may even entail the deletion of two internal windows.
______________________________________
| ______ ____________________________ |
|| || __________________________ ||
|| ||| ___________ ___________ |||
|| |||| || ||||
|| ||||____W6_____||_____W7____||||
|| |||____________W4____________|||
|| || __________________________ ||
|| ||| |||
|| ||| |||
|| |||____________W5____________|||
||__W2__||_____________W3_____________ |
|__________________W1__________________|
Deleting W5 in this configuration normally causes the deletion of W3 and W4. The remaining live windows W2, W6 and W7 are recombined to form a new horizontal combination with parent W1.
Sometimes, however, it makes sense to not delete a parent window like 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 W2 and W3 and their parent W1.
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
Split W2 to make a new window W4 as follows.
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
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 W4 will steal space from W3.
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
||_________________W4_________________||
| ____________________________________ |
||_________________W3_________________||
|__________________W1__________________|
Deleting W4 will now give its entire space to W2, including the space earlier stolen from W3.
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
||_________________W3_________________||
|__________________W1__________________|
This can be counterintuitive, in particular if W4 were used for displaying a buffer only temporarily (see 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 W2. The variable described next allows that to be done.
This variable controls whether splitting a window shall make a new parent window. The following values are recognized:
nilThis 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).
window-sizeThis means that display-buffer makes a new parent window when
it splits a window and is passed a window-height or
window-width entry in the alist argument (see Action Functions for Buffer Display). Otherwise, window splitting behaves as
for a value of nil.
temp-buffer-resizeIn this case with-temp-buffer-window makes a new parent window
when it splits a window and temp-buffer-resize-mode is enabled
(see Temporary Displays). Otherwise, window splitting behaves as
for nil.
temp-bufferIn this case with-temp-buffer-window always makes a new parent
window when it splits an existing window (see Temporary Displays).
Otherwise, window splitting behaves as for nil.
display-bufferThis means that when display-buffer (see Choosing a Window for Displaying a Buffer)
splits a window it always makes a new parent window. Otherwise, window
splitting behaves as for nil.
tThis means that splitting a window always creates a new parent window.
Thus, if the value of this variable is at all times 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).
The default is window-size. Other values are reserved for future
use.
If, as a consequence of this variable’s setting, split-window
makes a new parent window, it also calls
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).
If window-combination-limit is t, splitting W2 in
the initial configuration of our scenario would have produced this:
______________________________________
| ____________________________________ |
|| __________________________________ ||
||| |||
|||________________W2________________|||
|| __________________________________ ||
||| |||
|||________________W4________________|||
||_________________W5_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
A new internal window W5 has been created; its children are W2 and the new live window W4. Now, W2 is the only sibling of W4, so enlarging W4 will try to shrink W2, leaving W3 unaffected. Observe that W5 represents a vertical combination of two windows embedded in the vertical combination W1.
This function sets the combination limit of the window
window to limit. This value can be retrieved via the
function window-combination-limit. See below for its effects;
note that it is only meaningful for internal windows. The
split-window function automatically calls this function, passing
it t as limit, provided the value of the variable
window-combination-limit is t when it is called.
This function returns the combination limit for window.
The combination limit is meaningful only for an internal window. If it
is nil, then Emacs is allowed to automatically delete
window, in response to a window deletion, in order to group the
child windows of window with its sibling windows to form a new
window combination. If the combination limit is t, the child
windows of window are never automatically recombined with its
siblings.
If, in the configuration shown at the beginning of this section, the
combination limit of W4 (the parent window of W6 and
W7) is t, deleting W5 will not implicitly delete
W4 too.
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 splitting windows that would be otherwise too small for such an operation.
If this variable is nil, split-window can only split a
window (denoted by window) if window’s screen area is large
enough to accommodate both itself and the new window.
If this variable is t, split-window tries to resize all
windows that are part of the same combination as window, in order
to accommodate the new window. In particular, this may allow
split-window to succeed even if window is a fixed-size
window or too small to ordinarily split. Furthermore, subsequently
resizing or deleting window may resize all other windows in its
combination.
The default is nil. Other values are reserved for future use. A
specific split operation may ignore the value of this variable if it is
affected by a non-nil value of window-combination-limit.
If you plan to use a sequence of split-window calls to produce a
specific, predefined layout of windows on a frame, bind this variable
temporarily to nil. window-state-put (see Window Configurations) and the functions which change window layouts
(see Changing Window Layouts) do that in order to restore a previous
or systematically changed layout of a frame.
To illustrate the effect of window-combination-resize, consider
the following frame layout.
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
||_________________W3_________________||
|__________________W1__________________|
If window-combination-resize is nil, splitting window
W3 leaves the size of W2 unchanged:
______________________________________
| ____________________________________ |
|| ||
|| ||
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
||_________________W3_________________||
| ____________________________________ |
|| ||
||_________________W4_________________||
|__________________W1__________________|
If window-combination-resize is t, splitting W3
instead leaves all three live windows with approximately the same
height:
______________________________________
| ____________________________________ |
|| ||
|| ||
||_________________W2_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W3_________________||
| ____________________________________ |
|| ||
|| ||
||_________________W4_________________||
|__________________W1__________________|
Deleting any of the live windows W2, W3 or W4 will distribute its space proportionally among the two remaining live windows.
The following two functions allow to expressly make a new parent window for several adjacent windows and to undo that operation.
This function combines the windows from first to last inclusive. first and last must be valid windows in the same combination, that is, windows with the same parent window. If neither first has a previous nor last has a next sibling, it returns that parent window. Otherwise, it makes a new parent window whose first child window becomes first and whose last child window becomes last, inserts that parent window in the window tree in lieu of the windows starting with first and ending with last and returns the new parent window.
This function is useful to operate on several siblings of the same
parent window as a whole. Consider three sibling windows w1,
w2 and w3 aligned side by side. To create a window below
w1 and w2 but not below w3, first combine w1 and
w2 using this function, and then split the window it returned. You
can also call window-state-get (see Window Configurations) on
the return value of combine-windows to obtain the combined state
of w1 and w2.
This function uncombines the specified window. window
should be an internal window whose parent window is an internal window
of the same type. This means that window and its parent should
be either both horizontal or both vertical window combinations. If this
is the case, the function makes the child windows of window become
child windows of window’s parent, and returns t.
Otherwise, it leaves the current configuration of window’s frame
unchanged and returns nil.
This function is useful to undo the effect of combine-windows.
For example, to calculate the state of two adjacent windows w1 and
w2, proceed as follows: first, call combine-windows with w1
and w2 as arguments, and store the result in w. Then call
window-state-get with the argument w. Finally, call
uncombine-window with w as its argument to obtain the
window configuration that existed before the call to combine-windows.
After a window has been deleted (see Deleting Windows) it cannot be used any more by functions that require a valid window as their argument even if some Lisp variable still references that window. When the last reference to a window has ceased to exist, the window’s Lisp object will be eventually recycled by the garbage collector (see Garbage Collection).
There are two ways to resurrect a deleted window whose object has not
been yet recycled by the collector: The first is to keep a reference to
that window in a saved window configuration (see Window Configurations) and then call set-window-configuration with that
configuration as argument. The second one is to keep a reference to
that window in a variable or let-bind it and then use that reference as
refer argument in split-window (see Splitting Windows).
The major difference between these two is that
set-window-configuration restores the frame layout as it existed
before deleting the window. The split-window approach, on the
other hand, allows for arbitrary variations of the layout.
Consider the following example starting with a frame containing a single window showing the buffer *scratch*:
(let* ((old (selected-window))
(new (split-window old nil 'right))
overlay)
(with-current-buffer (get-buffer-create "*Messages*")
(set-window-buffer new (current-buffer))
(setq overlay (make-overlay (point-min) (point-max)))
(overlay-put overlay 'face 'highlight)
(overlay-put overlay 'window new)
(message "new %s parent %s" new (window-parent new))
(sit-for 3))
(delete-window new)
(setq new (split-window old nil 'left))
(set-window-buffer new (get-buffer-create "*Messages*"))
(format "new %s parent %s" new (window-parent new)))
When you run that code in *scratch* it will first split the window showing *scratch* to display *Messages* in a new window on the right. It also sets up an overlay with a window property to highlight the text of *Messages* in the new window and displays a message showing the new window and its parent in the window tree. It then deletes the new window and resurrects it on the left of the *scratch* window again displaying a message showing the new window and its parent in the window tree.
Note that both, new window and its parent have changed after moving the *Messages* window to the left. Also, the highlighting disappears because any properties set up for the new window on the right are lost when the new window is re-created on the left.
The following code uses the refer argument of split-window
instead.
(let* ((old (selected-window))
(new (split-window old nil 'right))
overlay)
(with-current-buffer (get-buffer-create "*Messages*")
(set-window-buffer new (current-buffer))
(setq overlay (make-overlay (point-min) (point-max)))
(overlay-put overlay 'face 'highlight)
(overlay-put overlay 'window new)
(message "new %s parent %s" new (window-parent new))
(sit-for 3))
(delete-window new)
(split-window old nil 'left nil new)
(format "new %s parent %s" new (window-parent new)))
Note that all properties of the resurrected window like its decorations,
parameters as well as any overlays with a window property are preserved
as if that window had never been deleted. The only things that changed
are its position in the window tree and consequently the values returned
by window-left-child of its parent window as well as the values
returned by window-prev-sibling and window-next-sibling of
the window and its sibling.
The following code passes both, the new window on the right and its
parent, via the refer argument to split-window instead.
(let* ((old (selected-window))
(new (split-window old nil 'right))
(parent (window-parent new))
overlay)
(with-current-buffer (get-buffer-create "*Messages*")
(set-window-buffer new (current-buffer))
(setq overlay (make-overlay (point-min) (point-max)))
(overlay-put overlay 'face 'highlight)
(overlay-put overlay 'window new)
(message "new %s parent %s" new (window-parent new))
(sit-for 3))
(delete-window new)
(split-window old nil 'left nil (cons new parent))
(format "new %s parent %s" new (window-parent new)))
Note that the parent window has been resurrected along with the new window.
Resurrecting dead windows is useful to preserve the identity of windows in actions that are supposed to do that like moving windows around on a frame or hiding them temporarily. Any properties of such a window like its decorations, the buffer it has shown previously, that buffer’s start and point position in the window, the window’s dedicated status or its cursor type are left untouched and there’s no need to recreate them from scratch. For internal windows, the value of that window’s combination limit is preserved which means that the window can be recombined (see Recombining Windows) as before.
Sometimes it can be useful to change the layout of windows such that two or more windows occupy the locations of each other. The commands described in this section do that in an orderly manner. Conceptually, these commands affect a rectangular subset of the windows on a frame. As a rule, they neither affect the location of a frame’s minibuffer window nor of any of its side windows (see Side Windows).
Common to all these commands is that they preserve the identity of
windows by deleting them first and resurrecting them
(see Resurrecting Windows) in their new locations afterwards. No
window gets lost and no window is added or duplicated. Where possible,
these commands try to preserve the relative size of windows as well as
all other non-geometric properties including parameters. These commands
will signal an error if windows about to change their locations are
atomic or of fixed size. The option transpose-dedicated-windows
described below decides whether dedicated windows may change their
locations.
The window argument of all functions described in this section
must specify a valid parent window (see Windows and Frames). If it
is nil, it stands for the main window (see Side Windows) of
the selected frame. Interactively, a prefix argument means to operate
on the parent window of the selected window. In the examples given
below, we shall always assume that the windows displayed constitute
their frame’s main window and the window argument is nil
unless stated otherwise.
The first two commands rotate a window layout either clockwise or counterclockwise.
This command rotates the window layout clockwise by 90 degrees. Imagine a layout with three live windows A, B and C as depicted on the left below. Then this command will produce the layout on the right.
___________ ___________
| | | | |
| A | | B | |
|___________| --> |_____| A |
| | | | | |
| B | C | | C | |
|_____|_____| |_____|_____|
This is like window-layout-rotate-clockwise but rotates the
layout in the opposite direction as demonstrated in the example below.
___________ ___________
| | | | |
| A | | | C |
|___________| --> | A |_____|
| | | | | |
| B | C | | | B |
|_____|_____| |_____|_____|
The next two commands flip the window layout—rotate it around an imaginary horizontal or vertical axis. If the number of windows to be flipped is odd, the window in the middle remains in its original place.
This command flips windows such that windows on the bottom become windows on the top and vice-versa as in the example below.
___________ ___________
| | | | |
| A | | B | C |
|___________| --> |_____|_____|
| | | | |
| B | C | | A |
|_____|_____| |___________|
This command rearranges window in a way that the windows on the right become the windows on the left, and vice-versa.
___________ ___________
| | | |
| A | | A |
|___________| --> |___________|
| | | | | |
| B | C | | C | B |
|_____|_____| |_____|_____|
The next command can be used to transpose windows—changing horizontal splits to vertical ones and vice-versa.
This command reorganizes windows such that every horizontal split becomes a vertical split and vice versa.
___________ ___________
| | | | |
| A | | | B |
|___________| --> | A |_____|
| | | | | |
| B | C | | | C |
|_____|_____| |_____|_____|
The final two commands can be used to rotate windows within the
existing layout. They are like the commands that rotate the layout but
leave the underlying structure of the layout unchanged. What actually
changes are the positions of windows within the existing layout. This
happens in a way that the space formerly occupied by any window will be
occupied by the window preceding (following if reverse is
non-nil) it in the cyclic ordering of windows (see Cyclic Ordering of Windows) on window’s frame.
This command rotates window’s child windows in cyclic ordering. The optional argument reverse means to rotate windows backwards, in reverse cyclic order.
___________ ___________
| | | |
| A | | C |
|___________| --> |___________|
| | | | | |
| B | C | | A | B |
|_____|_____| |_____|_____|
This command rotates window’s child windows backwards in cyclic ordering.
___________ ___________
| | | |
| A | | B |
|___________| --> |___________|
| | | | | |
| B | C | | C | A |
|_____|_____| |_____|_____|
All commands described above are subject to the following option.
If this is nil, the functions described in this section will
report an error when they encounter a dedicated window (see Dedicated Windows). If this is t, they handle dedicated windows like
non-dedicated ones.
The last two commands are subject to the following option.
If this is nil, the selected window will remain unaffected by
rotate-windows and rotate-windows-back. If this is
t (the default), the selected window will change to the window
that appears at the location of the window selected before any of these
commands were invoked.
When you use the command C-x o (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 cyclic ordering of windows.
The ordering is determined by a depth-first traversal of each frame’s window tree, retrieving the live windows which are the leaf nodes of the tree (see 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.
This function returns a live window, the one following window in
the cyclic ordering of windows. window should be a live window;
if omitted or nil, it defaults to the selected window.
The optional argument minibuf specifies whether minibuffer windows
should be included in the cyclic ordering. Normally, when minibuf
is nil, a minibuffer window is included only if it is currently
active; this matches the behavior of C-x o. (Note that a
minibuffer window is active as long as its minibuffer is in use; see
Minibuffers).
If minibuf is t, the cyclic ordering includes all
minibuffer windows. If minibuf is neither t nor
nil, minibuffer windows are not included even if they are active.
The optional argument all-frames specifies which frames to consider:
nil
means to consider windows on window’s frame. If the minibuffer
window is considered (as specified by the minibuf argument),
then frames that share the minibuffer window are considered too.
t
means to consider windows on all existing frames.
visible
means to consider windows on all visible frames.
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 (see Finding All Frames).
This function returns a live window, the one preceding window in
the cyclic ordering of windows. The other arguments are handled like
in next-window.
This function selects a live window, one count places from the selected window in the cyclic ordering of windows. If count is a positive number, it skips count windows forwards; if count is negative, it skips −count windows backwards; if count is zero, that simply re-selects the selected window. When called interactively, count is the numeric prefix argument.
The optional argument all-frames has the same meaning as in
next-window, like a nil minibuf argument to
next-window. When called interactively, all-frames is
always nil, so only windows on the selected frame can be
selected.
If the other-window parameter of the selected window is a
function, and ignore-window-parameters is nil, that
function will be called with the arguments count and
all-frames instead of the normal operation of this function.
Otherwise, this function does not select a window for which the function
window-no-other-p (see next) returns nil.
This function returns non-nil if window should not be used
as “other” window by commands like other-window or functions
like get-lru-window (see below). It’s also called when deleting
the selected window (see Deleting Windows) and a new selected window
has to be chosen.
More precisely, this function returns non-nil if the
no-other-window parameter of window is non-nil and
ignore-window-parameters is nil. It returns nil in
any other case.
Note that if this function returns nil, this does not necessarily
mean that window can be selected. A tooltip window (see Basic Concepts of Emacs Windows), for example, has its no-other-window parameter set to
t by default but cannot be selected.
This function calls the function fun once for each live window, with the window as the argument.
It follows the cyclic ordering of windows. The optional arguments
minibuf and all-frames specify the set of windows
included; these have the same arguments as in next-window. If
all-frames specifies a frame, the first window walked is the
first window on that frame (the one returned by
frame-first-window), not necessarily the selected window.
If 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 fun for the first time.
This function returns t if the selected window is the only live
window, and nil otherwise.
If the minibuffer window is active, it is normally considered (so that
this function returns nil). However, if the optional argument
no-mini is non-nil, the minibuffer window is ignored even
if active. The optional argument all-frames has the same
meaning as for next-window.
The following functions return a window which satisfies some criterion, without selecting it:
This function returns a live window which is heuristically the least
recently used one. The least recently used window is the least
recently selected one—the window whose use time is less than the use
time of all other live windows (see Selecting Windows). The
optional argument all-frames has the same meaning as in
next-window.
If any full-width windows are present, only those windows are
considered. A minibuffer window is never a candidate. A dedicated
window (see Dedicated Windows) is never a candidate unless the
optional argument dedicated is non-nil. The selected
window is never returned, unless it is the only candidate. However, if
the optional argument not-selected is non-nil, this
function returns nil in that case. The optional argument
no-other, if non-nil, means to never return a window for
which window-no-other-p (see Cyclic Ordering of Windows) returns
non-nil.
This function is like get-lru-window, but it returns the most
recently used window instead. The most recently used window is
the most recently selected one—the window whose use time exceeds the
use time of all other live windows (see Selecting Windows). The
meaning of the arguments is the same as for get-lru-window.
Since in practice the most recently used window is always the selected
one, it usually makes sense to call this function with a non-nil
not-selected argument only.
This function returns the window with the largest area (height times
width). If there are two candidate windows of the same size, it prefers
the one that comes first in the cyclic ordering of windows, starting
from the selected window. The meaning of the arguments is the same as
for get-lru-window.
This function calls the function 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-nil for any
window, this function stops and returns that window. If no such
window is found, the return value is default (which defaults to
nil).
The optional arguments minibuf and all-frames specify the
windows to search, and have the same meanings as in
next-window.
This section describes low-level functions for examining and setting the contents of windows. See Switching to a Buffer in a Window, for higher-level functions for displaying a specific buffer in a window.
This function returns the buffer that window is displaying. If
window is omitted or nil it defaults to the selected
window. If window is an internal window, this function returns
nil.
This function makes window display buffer-or-name.
window should be a live window; if nil, it defaults to
the selected window. 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 (see The Current Buffer). Its return value is nil.
If window is strongly dedicated to a buffer and buffer-or-name does not specify that buffer, this function signals an error. See Dedicated Windows.
By default, this function resets 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
keep-margins is non-nil, it leaves window’s display
margins, fringes and scroll bar settings alone.
When writing an application, you should normally use
display-buffer (see Choosing a Window for Displaying a Buffer) or the higher-level
functions described in Switching to a Buffer in a Window, instead of calling
set-window-buffer directly.
This runs window-scroll-functions, followed by
window-configuration-change-hook. See Hooks for Window Scrolling and Changes.
This buffer-local variable records the number of times a buffer has been
displayed in a window. It is incremented each time
set-window-buffer is called for the buffer.
This buffer-local variable records the time at which a buffer was last
displayed in a window. The value is nil if the buffer has
never been displayed. It is updated each time
set-window-buffer is called for the buffer, with the value
returned by current-time (see Time of Day).
This function returns the first window displaying buffer-or-name
in the cyclic ordering of windows, starting from the selected window
(see Cyclic Ordering of Windows). If no such window exists, the
return value is nil.
buffer-or-name should be a buffer or the name of a buffer; if
omitted or nil, it defaults to the current buffer. The
optional argument all-frames specifies which windows to
consider:
t means consider windows on all existing frames.
visible means consider windows on all visible frames.
Note that these meanings differ slightly from those of the
all-frames argument to next-window (see Cyclic Ordering of Windows). This function may be changed in a future version of Emacs
to eliminate this discrepancy.
The following function can tell for a specific window whether its buffer shares the text of some other buffer (see Indirect Buffers).
This function returns non-nil if window is indirectly
related to buffer-or-name. window must be a live window and
defaults to the selected window. buffer-or-name may be a buffer
or the name of an existing buffer and defaults to the current buffer.
window is indirectly related to buffer-or-name if one of the following conditions hold:
It returns nil if none of the above holds.
This function returns a list of all windows currently displaying
buffer-or-name. buffer-or-name should be a buffer or the
name of an existing buffer. If omitted or nil, it defaults to
the current buffer. If the currently selected window displays
buffer-or-name, it will be the first in the list returned by
this function.
The arguments minibuf and all-frames have the same
meanings as in the function next-window (see Cyclic Ordering of Windows). Note that the all-frames argument does not
behave exactly like in get-buffer-window.
The optional argument indirect non-nil means to append to
the list of windows showing buffer-or-name a list of all windows
that are indirectly related to buffer-or-name, that is, windows
for which window-indirect-buffer-p (see above) with the window
and the buffer specified by buffer-or-name as arguments returns
non-nil.
This command replaces buffer-or-name with some other buffer, in
all windows displaying it. buffer-or-name should be a buffer, or
the name of an existing buffer; if omitted or nil, it defaults to
the current buffer.
The replacement buffer in each window is usually chosen via
switch-to-prev-buffer (see Window History). With the
exception of side windows (see Side Windows), any dedicated window
displaying buffer-or-name is deleted if possible (see 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.
The main purpose of this function is to decide what to do with windows
whose buffers are about to be killed by kill-buffer
(see Killing Buffers). It will, however, also remove the buffer
specified by buffer-or-name from the lists of previous and next
buffers (see Window History) of all windows (including dead windows
that are only referenced by window configurations) and remove any
quit-restore or quit-restore-prev parameters
(see Window Parameters) referencing that buffer.
This function does not replace the buffer specified by buffer-or-name in any minibuffer window showing it, nor does it delete minibuffer windows or minibuffer frames. It removes, however, that buffer from the lists of previous and next buffers of all minibuffer windows.
By default, replace-buffer-in-windows deletes only windows
dedicated to their buffers and ignores any quit-restore or
quit-restore-prev parameters of the windows it works on. The
following option is useful for circumventing these restrictions.
If this option is nil, kill-buffer (and in consequence
replace-buffer-in-windows) may only delete windows that are
dedicated to the buffer about to be killed. If this is non-nil,
replace-buffer-in-windows has quit-restore-window
(see Quitting Windows) deal with any such window. That function may
delete such a window even if it’s not dedicated to its buffer. Also,
delete-windows-on will use quit-restore-window as fallback
when a window cannot be deleted and another buffer must be shown in it.
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 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 (see 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
with-current-buffer, save-current-buffer, or
set-buffer. See The Current Buffer.
This command attempts to display buffer-or-name in the selected window and make it the current buffer. It is often used interactively (as the binding of C-x b), as well as in Lisp programs. The return value is the buffer switched to.
If buffer-or-name is nil, it defaults to the buffer
returned by other-buffer (see The Buffer List). If
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 major-mode
(see 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 (see The Buffer List). However, this is not done if the
optional argument norecord is non-nil.
Sometimes, the selected window may not be suitable for displaying the
buffer. This happens if the selected window is a minibuffer window, or
if the selected window is strongly dedicated to its buffer
(see Dedicated Windows). In such cases, the command normally tries
to display the buffer in some other window, by invoking
pop-to-buffer (see below).
If the optional argument force-same-window is non-nil and
the selected window is not suitable for displaying the buffer, this
function always signals an error when called non-interactively. In
interactive use, if the selected window is a minibuffer window, this
function will try to use some other window instead. If the selected
window is strongly dedicated to its buffer, the option
switch-to-buffer-in-dedicated-window described next can be used
to proceed.
This option, if non-nil, allows switch-to-buffer to
proceed when called interactively and the selected window is strongly
dedicated to its buffer.
The following values are respected:
nilDisallows switching and signals an error as in non-interactive use.
promptPrompts the user whether to allow switching.
popInvokes pop-to-buffer to proceed.
tMarks the selected window as non-dedicated and proceeds.
This option does not affect non-interactive calls of
switch-to-buffer.
By default, switch-to-buffer tries to preserve
window-point. This behavior can be tuned using the following
option.
If this variable is nil, switch-to-buffer displays the
buffer specified by buffer-or-name at the position of that
buffer’s point. If this variable is 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 t,
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
switch-to-buffer calls pop-to-buffer to display the
buffer.
If this variable is non-nil, switch-to-buffer respects
display actions specified by display-buffer-overriding-action,
display-buffer-alist (see Action Functions for Buffer Display)
and other buffer display related variables (see Action Alists for Buffer Display).
The next two commands are similar to switch-to-buffer, except for
the described features.
This function displays the buffer specified by buffer-or-name in
some window other than the selected window. It uses the function
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 buffer-or-name and norecord arguments have the same
meanings as in switch-to-buffer.
This function displays the buffer specified by buffer-or-name in a
new frame. It uses the function 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 buffer-or-name and norecord arguments have the same
meanings as in switch-to-buffer.
The above commands use the function pop-to-buffer, which
flexibly displays a buffer in some window and selects that window for
editing. In turn, pop-to-buffer uses display-buffer for
displaying the buffer. Hence, all the variables affecting
display-buffer will affect it as well. See Choosing a Window for Displaying a Buffer,
for the documentation of display-buffer.
This function makes buffer-or-name the current buffer and displays it in some window, preferably not the window currently selected. It then selects the displaying window. If that window is on a different graphical frame, that frame is given input focus if possible (see Input Focus).
If buffer-or-name is nil, it defaults to the buffer
returned by other-buffer (see The Buffer List). If
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 major-mode
(see Major Modes). In any case, that buffer is made current and
returned, even when no suitable window was found to display it.
If action is non-nil, it should be a display action to
pass to display-buffer (see Choosing a Window for Displaying a Buffer).
Alternatively, a non-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 switch-to-buffer, this function updates the buffer list
unless norecord is non-nil.
This section describes lower-level functions Emacs uses to find or
create a window for displaying a specified buffer. The common
workhorse of these functions is display-buffer which eventually
handles all incoming requests for buffer display (see Choosing a Window for Displaying a Buffer).
display-buffer delegates the task of finding a suitable
window to so-called action functions (see Action Functions for Buffer Display). First, display-buffer compiles a so-called action
alist—a special association list that action functions can use to
fine-tune their behavior. Then it passes that alist on to each action
function it calls (see Action Alists for Buffer Display).
The behavior of display-buffer is highly customizable. To
understand how customizations are used in practice, you may wish to
study examples illustrating the order of precedence which
display-buffer uses to call action functions (see Precedence of Action Functions). To avoid conflicts between Lisp programs
calling display-buffer and user customizations of its behavior,
it may make sense to follow a number of guidelines which are sketched
in the final part of this section (see The Zen of Buffer Display).
The command 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 C-x 4 C-o. It is also
used as a subroutine by many functions and commands, including
switch-to-buffer and pop-to-buffer (see Switching to a Buffer in a Window).
This command performs several complex steps to find a window to
display in. These steps are described by means of display
actions, which have the form (functions . alist).
Here, functions is either a single function or a list of
functions, referred to as “action functions” (see Action Functions for Buffer Display); and alist is an association list, referred
to as “action alist” (see Action Alists for Buffer Display).
See The Zen of Buffer Display, for samples of display actions.
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 nil.
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-nil
value.
This command makes buffer-or-name appear in some window, without
selecting the window or making the buffer current. The argument
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,
or nil if no suitable window was found.
The optional argument action, if non-nil, should normally
be a display action (described above). display-buffer builds a
list of action functions and an action alist, by consolidating display
actions from the following sources (in order of their precedence,
from highest to lowest):
display-buffer-overriding-action.
display-buffer-alist.
display-buffer-base-action.
display-buffer-fallback-action.
In practice this means that display-buffer builds a list of all
action functions specified by these display actions. The first
element of this list is the first action function specified by
display-buffer-overriding-action, if any. Its last element is
display-buffer-pop-up-frame—the last action function
specified by display-buffer-fallback-action. Duplicates are
not removed from this list—hence one and the same action function
may be called multiple times during one call of display-buffer.
display-buffer calls the action functions specified by this
list 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-nil. See Precedence of Action Functions, for examples how display actions specified by different
sources are processed by display-buffer.
Note that the second argument is always the list of all action
alist entries specified by the sources named above. Hence, the first
element of that list is the first action alist entry specified by
display-buffer-overriding-action, if any. Its last element is
the last alist entry of display-buffer-base-action, if any (the
action alist of display-buffer-fallback-action is empty).
Note also, that the combined action alist may contain duplicate entries and entries for the same key with different values. As a rule, action functions always use the first association of a key they find. Hence, the association an action function uses is not necessarily the association provided by the display action that specified that action function,
The argument action can also have a non-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, action is t. Lisp programs
should always supply a list value.
The optional argument frame, if non-nil, specifies which
frames to check when deciding whether the buffer is already displayed.
It is equivalent to adding an element (reusable-frames . frame) to the action alist of action (see Action Alists for Buffer Display). The frame argument is provided for
compatibility reasons, Lisp programs should not use it.
The value of this variable should be a display action, which is
treated with the highest priority by display-buffer. The
default value is an empty display action, i.e., (nil . nil).
The value of this option is an alist mapping conditions to display
actions. Each condition is passed to buffer-match-p
(see The Buffer List), along with the buffer name and the action
argument passed to display-buffer. If it returns a
non-nil value, then display-buffer uses the
corresponding display action to display the buffer. Caveat: if you
use derived-mode or major-mode as condition,
buffer-match-p could fail to report a match if
display-buffer is called before the major mode of the buffer is
set.
If the caller of display-buffer passes a category as a symbol
in its action argument, then you can use the same category in
display-buffer-alist to match buffers with different names,
for example:
(add-to-list 'display-buffer-alist
'((category . comint)
(display-buffer-same-window)
(inhibit-same-window . nil)))
(display-buffer (get-buffer-create "*my-shell*")
'(nil (category . comint)))
See buffer-match-p.
Regardless of the displayed buffer’s name the caller defines a category
as a symbol comint. Then display-buffer-alist matches
this category for all buffers displayed with the same category.
This avoids the need to construct a complex regular expression
that matches a buffer name.
You can also match on the command now being executed. This is useful when different commands display buffers with the same name, but you want different command’s buffers to be displayed differently. For example:
(add-to-list 'display-buffer-alist
'((and "^\\*vc-diff\\*"
(not (this-command . vc-root-diff)))
nil
(post-command-select-window . nil)))
This means that windows displaying VC diffs, such as those generated by
C-x v = (vc-diff, see Old Revisions in the Emacs
Manual) are not left selected, except for windows displaying buffers
generated by C-x v D (vc-root-diff), which are left
selected.
The value of this option should be a display action. This option can
be used to define a standard display action for calls to
display-buffer.
This display action specifies the fallback behavior for
display-buffer if no other display actions are given.
An action function is a function display-buffer calls for
choosing a window to display a buffer. Action functions take two
arguments: buffer, the buffer to display, and alist, an
action alist (see Action Alists for Buffer Display). They are
supposed to return a window displaying buffer if they succeed
and nil if they fail.
The following basic action functions are defined in Emacs.
This function tries to display buffer in the selected window.
It fails if the selected window is a minibuffer window or is dedicated
to another buffer (see Dedicated Windows). It also fails if
alist has a non-nil inhibit-same-window entry.
This function tries to display buffer by finding a window that is already displaying it. Windows on the selected frame are preferred to windows on other frames.
If alist has a non-nil inhibit-same-window entry,
the selected window is not eligible for reuse. The set of frames to
search for a window already displaying buffer can be specified
with the help of the reusable-frames action alist entry. If
alist contains no reusable-frames entry, this function
searches just the selected frame.
If this function chooses a window on another frame, it makes that
frame visible and, unless alist contains an
inhibit-switch-frame entry, raises that frame if necessary.
If alist has a non-nil reuse-indirect entry and no
window showing buffer has been found, this function tries to find
a window that is indirectly related to buffer—a window for which
window-indirect-buffer-p (see Buffers and Windows) with the
window and buffer as arguments returns non-nil. If such a
window has been found and the CDR of the reuse-indirect
entry equals the symbol buffer, it does not replace the buffer of
that window with buffer but returns the window with its old buffer
in place. Otherwise, it puts buffer into that window and returns
that window.
This function tries to display buffer by finding a window that is displaying a buffer in a given mode.
If alist contains a mode entry, its value specifies a
major mode (a symbol) or a list of major modes. If alist
contains no mode entry, the current major mode of buffer
is used instead. A window is a candidate if it displays a buffer
whose mode derives from one of the modes specified thusly.
The behavior is also controlled by alist entries for
inhibit-same-window, reusable-frames and
inhibit-switch-frame, like display-buffer-reuse-window
does.
This function tries to display buffer by splitting the largest
or least recently-used window (usually located on the selected frame).
It actually performs the split by calling the function specified by
split-window-preferred-function (see Additional Options for Displaying Buffers).
The size of the new window can be adjusted by supplying
window-height and window-width entries in alist.
If alist contains a preserve-size entry, Emacs will also
try to preserve the size of the new window during future resize
operations (see Preserving Window Sizes).
This function fails if no window can be split. More often than not,
this happens because no window is large enough to allow splitting.
Setting split-height-threshold or split-width-threshold
to lower values may help in this regard. Splitting also fails when
the selected frame has an unsplittable frame parameter;
see Buffer Parameters.
This function tries to display buffer in a window where it was displayed previously.
If alist contains a non-nil inhibit-same-window
entry, the selected window is not eligible for use. A dedicated
window is usable only if it already shows buffer. If
alist contains a previous-window entry, the window
specified by that entry is usable even if it never showed buffer
before.
If alist contains a reusable-frames entry (see Action Alists for Buffer Display), its value determines which frames to search
for a suitable window. If alist contains no
reusable-frames entry, this function searches just the selected
frame if display-buffer-reuse-frames and pop-up-frames
are both nil; it searches all frames on the current terminal if
either of those variables is non-nil.
If more than one window qualifies as usable according to these rules, this function makes a choice in the following order of preference:
previous-window alist entry,
provided it is not the selected window.
previous-window alist entry or showed buffer
before.
This function tries to display buffer by choosing an existing
window and displaying the buffer in that window. It first tries to find
a window that has not been used recently (see Cyclic Ordering of Windows) on any frame specified by a lru-frames alist
entry, falling back to the selected frame if no such entry exists. It
also prefers windows that satisfy the constraints specified by
window-min-width and window-min-height alist
entries; preferring full-width windows if no window-min-width
entry is found. Finally, it will not return a window whose use time is
higher than that specified by any lru-time entry provided by
alist.
If no less recently used window is found, this function will try to use some other window, preferably a large window on some visible frame. It can fail if all windows are dedicated to other buffers (see Dedicated Windows).
The above describes the behavior when the some-window alist
entry is lru or nil which is the default. Another
possible value is mru. If, for example,
display-buffer-base-action is customized to (nil . ((some-window . mru))), then this function will prefer the most
recently used window. This will try to display several buffers from
consecutive calls of display-buffer in the same window. Consider
a configuration of three or more windows where a user wants to consult,
in a non-selected window, one after the other, the results of a query
spread among several buffers. With the lru strategy, Emacs may
continuously choose another window because the least recently used
window changes with every call of display-buffer-use-some-window.
With the mru strategy, the window chosen would always remain the
same, resulting in a predictable user experience.
This function is similar to display-buffer-use-some-window, but
will try harder to not use a recently used window. In particular,
it does not use the selected window. In addition, it will first try to
reuse a window that shows buffer already, base the decision
whether it should use a window showing another buffer on that window’s
use time alone and pop up a new window if no usable window is found.
Finally, this function will bump the use time (see Selecting Windows) of any window it returns in order to avoid that further
invocations will use that window for showing another buffer. An
application that wants to display several buffers in a row can help this
function by providing a lru-time alist entry it has
initially set to the value of the selected window’s use time. Each
invocation of this function will then bump the use time of the window
returned to a value higher than that and a subsequent invocation will
inhibit this function to use a window it returned earlier.
This function tries to display buffer at a location specified by
alist. For this purpose, alist should contain a
direction entry whose value is one of left, above
(or up), right and below (or down). Other
values are usually interpreted as below.
If alist also contains a window entry, its value
specifies a reference window. That value can be a special symbol like
main which stands for the selected frame’s main window
(see Side Window Options and Functions) or root standing
for the selected frame’s root window (see Windows and Frames). It
can also specify an arbitrary valid window. Any other value (or
omitting the window entry entirely) means to use the selected
window as reference window.
This function first tries to reuse a window in the specified direction
that already shows buffer. If no such window exists, it tries
to split the reference window in order to produce a new window in the
specified direction. If this fails as well, it will try to display
buffer in an existing window in the specified direction. In
either case, the window chosen will appear on the side of the
reference window specified by the direction entry, sharing at
least one edge with the reference window.
If the reference window is live, the edge the chosen window will share
with it is always the opposite of the one specified by the
direction entry. For example, if the value of the
direction entry is left, the chosen window’s right edge
coordinate (see Coordinates and Windows) will equal the reference
window’s left edge coordinate.
If the reference window is internal, a reused window must share with
it the edge specified by the direction entry. Hence if, for
example, the reference window is the frame’s root window and the value
of the direction entry is left, a reused window must be
on the left of the frame. This means that the left edge coordinate of
the chosen window and that of the reference window are the same.
A new window, however, will be created by splitting the reference window such that the chosen window will share the opposite edge with the reference window. In our example, a new root window would be created with a new live window and the reference window as its children. The chosen window’s right edge coordinate would then equal the left edge coordinate of the reference window. Its left edge coordinate would equal the left edge coordinate of the frame’s new root window.
Four special values for direction entries allow implicitly
specifying the selected frame’s main window as the reference window:
leftmost, top, rightmost and bottom. This
means that instead of, for example, (direction . left) (window . main) one can just specify (direction . leftmost). An existing window alist entry is ignored
in such cases.
This function tries to display buffer in a window below the selected window. If there is a window below the selected one and that window already displays buffer, it reuses that window.
If there is no such window, this function tries to create a new window
by splitting the selected one, and displays buffer there. It will
also try to adjust that window’s size provided alist contains a
suitable window-height or window-width entry, see above.
If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing buffer.
If alist contains a window-min-height entry, this
function ensures that the window used is or can become at least as
high as specified by that entry’s value. Note that this is only a
guarantee. In order to actually resize the window used, alist
must also provide an appropriate window-height entry.
This function tries to display buffer in a window at the bottom of the selected frame.
This either tries to split the window at the bottom of the frame or the frame’s main window, or to reuse an existing window at the bottom of the selected frame.
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 pop-up-frame-function
(see Additional Options for Displaying Buffers). If alist contains a
pop-up-frame-parameters entry, the associated value is added to
the newly created frame’s parameters.
This function displays the buffer on the current frame, deleting all other windows so that it takes up the full frame.
This function tries to display buffer in a child frame
(see Child Frames) of the selected frame, either reusing an
existing child frame or by making a new one. If alist has a
non-nil child-frame-parameters entry, the corresponding
value is an alist of frame parameters to give the new frame. A
parent-frame parameter specifying the selected frame is
provided by default. If the child frame should become the child of
another frame, a corresponding entry must be added to alist.
The appearance of child frames is largely dependent on the parameters
provided via alist. It is advisable to use at least ratios to
specify the size (see Size Parameters) and the position
(see Position Parameters) of the child frame, and to add a
keep-ratio parameter (see Frame Interaction Parameters), in
order to make sure that the child frame remains visible. For other
parameters that should be considered see Child Frames.
This function tries to display buffer by finding a frame that meets a predicate (by default any frame other than the selected frame).
If this function chooses a window on another frame, it makes that
frame visible and, unless alist contains an
inhibit-switch-frame entry, raises that frame if necessary.
If alist has a non-nil frame-predicate entry, its
value is a function taking one argument (a frame), returning
non-nil if the frame is a candidate; this function replaces the
default predicate.
If alist has a non-nil inhibit-same-window entry,
the selected window is not used; thus if the selected frame has a
single window, it is not used.
This function tries to display buffer in a new tab.
If alist contains a non-nil tab-name entry (which
may be a string or a function), the buffer is displayed in a new tab
with that name. If the tab-name entry is a function, it is
called with two arguments (buffer and alist), and should
return the tab name.
If the tab-name entry is omitted or nil, a new tab is
created without an explicit name.
If alist contains a non-nil tab-group entry, this
defines the tab group, overriding user option
tab-bar-new-tab-group. This entry may again be a string or a
function which is called in the same manner as tab-name.
This function tries to display buffer in a new or existing tab.
If alist contains a non-nil reusable-frames entry
then the frames indicated by its value are searched for an existing tab
which already displays the buffer. The possible values of
reusable-frames are:
t
means consider all existing frames.
visible
means consider all visible frames.
nil value
means consider the selected frame.
nil
means do not search any frames (equivalent to omitting the entry). Note
that this is different to the typical meaning of the value nil
for a reusable-frames entry in a buffer display action alist.
If alist contains a non-nil ignore-current-tab
entry, then the current tab is skipped when searching for a reusable
tab. Otherwise the current tab is used by preference if it already
displays the buffer.
If a window displaying the buffer is located in any reusable tab then that tab and window are selected.
If no such window is located, the buffer is displayed in a new or
existing tab based on the alist entry tab-name (which may
be a string or a function). If a tab with this name already exists then
that tab is selected, otherwise a new tab with that name is created. If
the tab-name entry is a function, it is called with two arguments
(buffer and alist), and should return the tab name. If the
tab-name entry is omitted or nil, a new tab is created
without an explicit name.
If a new tab is created and alist contains a non-nil
tab-group entry, this defines the tab group, overriding user
option tab-bar-new-tab-group. This entry may again be a string
or a function which is called in the same manner as tab-name.
If alist has a non-nil allow-no-window entry, then
this function does not display buffer and returns the symbol
fail. This constitutes the only exception to the convention
that an action function returns either nil or a window showing
buffer. If alist has no such allow-no-window
entry, this function returns nil.
If this function returns fail, display-buffer will skip
the execution of any further display actions and return nil
immediately. If this function returns nil,
display-buffer will continue with the next display action, if
any.
It is assumed that when a caller of display-buffer specifies a
non-nil allow-no-window entry, it is also able to handle
a nil return value.
Two other action functions are described in their proper
sections—display-buffer-in-side-window (see Displaying Buffers in Side Windows) and display-buffer-in-atom-window
(see Atomic Windows).
An action alist is an association list mapping predefined
symbols recognized by action functions to values these functions are
supposed to interpret accordingly. In each call,
display-buffer constructs a new, possibly empty action alist
and passes that entire list on to any action function it calls.
By design, action functions are free in their interpretation of
action alist entries. In fact, some entries like
allow-no-window or previous-window have a meaning only
for one or a few action functions, and are ignored by the rest. Other
entries, like inhibit-same-window or window-parameters,
are supposed to be respected by most action functions, including those
provided by application programs and external packages.
In the previous subsection we have described in detail how
individual action functions interpret the action alist entries they
care about. Here we give a reference list of all known action alist
entries according to their symbols, together with their values and
action functions (see Action Functions for Buffer Display) that
recognize them. Throughout this list, the terms “buffer” will refer
to the buffer display-buffer is supposed to display, and
“value” refers to the entry’s value.
inhibit-same-window ¶If the value is non-nil, this signals that the selected window
must not be used for displaying the buffer. All action functions that
(re-)use an existing window should respect this entry.
previous-window ¶The value must specify a window that may have displayed the buffer
previously. display-buffer-in-previous-window will give
preference to such a window provided it is still live and not
dedicated to another buffer.
mode ¶The value is either a major mode or a list of major modes.
display-buffer-reuse-mode-window may reuse a window whenever
the value specified by this entry matches the major mode of that
window’s buffer. Other action functions ignore such entries.
frame-predicate ¶The value must be a function taking one argument (a frame), supposed
to return non-nil if that frame is a candidate for displaying
the buffer. This entry is used by
display-buffer-use-some-frame.
reusable-frames ¶The value specifies the set of frames to search for a window that can be reused because it already displays the buffer. It can be set as follows:
nil means consider only windows on the selected frame.
(Actually, the last frame used that is not a minibuffer-only frame.)
visible means consider windows on all visible frames.
t means consider windows on all frames. (Note that this value
is rarely the right thing to use—it might also return a tooltip frame.)
Note that the meaning of nil differs slightly from that of the
all-frames argument to next-window (see Cyclic Ordering of Windows).
A major client of this is display-buffer-reuse-window, but all
other action functions that try to reuse a window are affected as
well. display-buffer-in-previous-window consults it when
searching for a window that previously displayed the buffer on another
frame.
The action function display-buffer-in-tab searches the tabs of
the frame(s) identified by this entry, and also interprets the value
nil differently.
inhibit-switch-frame ¶A non-nil value prevents another frame from being raised or
selected, if the window chosen by display-buffer is displayed
there. Primarily affected by this are
display-buffer-use-some-frame and
display-buffer-reuse-window. Ideally,
display-buffer-pop-up-frame should be affected as well, but there
is no guarantee that the window manager will comply.
window-parameters ¶The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry.
window-min-width ¶The value specifies a minimum width of the window used, in canonical
frame columns. The special value full-width means the chosen
window should be one that has no other windows on the left or right of
it in its frame.
This entry is currently honored by display-buffer-use-some-window
and display-buffer-use-least-recent-window, which try hard to avoid
returning a less recently used window that does not satisfy the entry.
Note that providing such an entry alone does not necessarily make the
window as wide as specified by its value. To actually resize an
existing window or make a new window as wide as specified by this
entry’s value, a window-width entry specifying that value
should be provided as well. Such a window-width entry can,
however, specify a completely different value, or ask the window width
to fit that of its buffer, in which case the
window-min-width entry provides the guaranteed minimum width of
the window.
window-min-height ¶The value specifies a minimum height of the window used, in canonical
frame lines. The special value full-height means the chosen
window should be a full-height window, one that has no other windows
above or below it in its frame.
This entry is currently honored by display-buffer-below-selected
which does not use a window that is not as high as specified by this
entry. It’s also honored by display-buffer-use-some-window and
display-buffer-use-least-recent-window which try hard to avoid
returning a less recently used window if it does not satisfy this
constraint.
Note that providing such an entry alone does not necessarily make the
window as tall as specified by its value. To actually resize an
existing window or make a new window as tall as specified by that
value, a window-height entry specifying that value should be
provided as well. Such a window-height entry can, however,
specify a completely different value or ask the window height to be
fit to that of its buffer in which case the window-min-height
entry provides the guaranteed minimum height of the window used.
window-height ¶The value specifies whether and how to adjust the height of the chosen window and can be one of the following:
nil means to leave the height of the chosen window alone.
body-lines and whose CDR is an
integer that specifies the height of the chosen window’s body in frame
lines.
fit-window-to-buffer and
shrink-window-if-larger-than-buffer, see Resizing Windows.
By convention, the height of the chosen window is adjusted only if the window is part of a vertical combination (see Windows and Frames) to avoid changing the height of other, unrelated windows. Also, this entry should be processed only under certain conditions which are specified right below this list.
window-width ¶This entry is similar to the window-height entry described
before, but used to adjust the chosen window’s width instead. The
value can be one of the following:
nil means to leave the width of the chosen window alone.
body-columns and whose CDR is
an integer that specifies the width of the chosen window’s body in frame
columns.
window-size ¶This entry is a combination of the two preceding ones and can be used to
adjust the chosen window’s height and width. Since windows can
be resized in one direction only without affecting other windows,
window-size is effective only to set up the size of a window
appearing alone on a frame. The value can be one of the following:
nil means to leave the size of the chosen window alone.
body-chars and whose CDR
is a cons cell of two integers—the desired body width and height of
the chosen window in frame columns and lines. It’s effect is to adjust
the size of the frame accordingly.
This entry should be processed under only certain conditions which are specified right below this list.
dedicated ¶If non-nil, such an entry tells display-buffer to mark any
window it creates as dedicated to its buffer (see Dedicated Windows). It does that by calling set-window-dedicated-p with
the chosen window as first argument and the entry’s value as second.
Side windows are by default dedicated with the value side
(see Side Window Options and Functions). Windows that are reused
are not marked as dedicated regardless of whether they already showed
the buffer before or not. If a window dedicated to its buffer gets
reused for showing the same buffer again, its dedicated flag is left
alone.
preserve-size ¶If non-nil such an entry tells Emacs to preserve the size of
the window chosen (see Preserving Window Sizes). The value should
be either (t . nil) to preserve the width of the window,
(nil . t) to preserve its height or (t . t) to
preserve both, its width and its height. This entry should be
processed only under certain conditions which are specified right
after this list.
lru-frames ¶The value specifies the set of frames to search for a window that can be
used to display the buffer. It is honored by
display-buffer-use-some-window and
display-buffer-use-least-recent-window when trying to find a less
recently used window showing some other buffer. Its values are the same
as for the reusable-frames entry described above.
lru-time ¶The value is supposed to specify a use time (see Selecting Windows).
This entry is honored by display-buffer-use-some-window and
display-buffer-use-least-recent-window when trying to find a less
recently used window showing some other buffer. If a window’s use time
is higher than the value specified by this option, these action
functions will not consider such a window for displaying the buffer.
bump-use-time ¶If non-nil, such an entry will cause display-buffer to
bump the use time (see Selecting Windows) of the window it uses.
This should avoid later use of this window by action functions
like display-buffer-use-some-window and
display-buffer-use-least-recent-window for showing another
buffer.
There is a fine difference between using this entry and using the action
function display-buffer-use-least-recent-window. Calling the
latter means to only bump the use times of windows that function uses
for displaying the buffer. The entry described here will cause
display-buffer to bump the use time of any window used for
displaying a buffer.
pop-up-frame-parameters ¶The value specifies an alist of frame parameters to give a new frame,
if one is created. display-buffer-pop-up-frame is its one and
only addressee.
pop-up-frames ¶The value controls whether display-buffer may display buffers by
making new frames. It has the same meaning as the pop-up-frames
variable and takes precedence over it when present. Its main intended
purpose is to override a non-nil value of the variable for
particular buffers which the user prefers to keep in the selected frame.
parent-frame ¶The value specifies the parent frame to be used when the buffer is
displayed on a child frame. This entry is used only by
display-buffer-in-child-frame.
child-frame-parameters ¶The value specifies an alist of frame parameters to use when the buffer
is displayed on a child frame. This entry is used only by
display-buffer-in-child-frame.
side ¶The value denotes the side of the frame or window where a new window
displaying the buffer shall be created. This entry is used by
display-buffer-in-side-window to indicate the side of the frame
where a new side window shall be placed (see Displaying Buffers in Side Windows). It is also used by
display-buffer-in-atom-window to indicate the side of an
existing window where the new window shall be located (see Atomic Windows).
slot ¶If non-nil, the value specifies the slot of the side window
supposed to display the buffer. This entry is used only by
display-buffer-in-side-window.
direction ¶The value specifies a direction which, together with a window
entry, allows display-buffer-in-direction to determine the
location of the window to display the buffer.
window ¶The value specifies a window that is in some way related to the window
chosen by display-buffer. This entry is currently used by
display-buffer-in-atom-window to indicate the window on whose
side the new window shall be created. It is also used by
display-buffer-in-direction to specify the reference window on
whose side the resulting window shall appear.
allow-no-window ¶If the value is non-nil, display-buffer does not
necessarily have to display the buffer and the caller is prepared to
accept that. This entry is not intended for user customizations,
since there is no guarantee that an arbitrary caller of
display-buffer will be able to handle the case that no window
will display the buffer. display-buffer-no-window is the only
action function that cares about this entry.
some-window ¶If the value is nil or lru, display-buffer-use-some-window
prefers the least recently used window while avoiding selecting windows
that are not full-width and windows on another frame. If the value is
mru, it prefers the most recently used window not considering the
selected window and windows on any frame but the selected one. If the
value is a function, it is called with two arguments: a buffer and an
alist, and should return the window where to display the buffer.
body-function ¶The value must be a function taking one argument (a displayed window).
This function can be used to fill the displayed window’s body with
some contents that might depend on dimensions of the displayed window.
It is called after the buffer is displayed, and before
the entries window-height, window-width and
preserve-size are applied that could resize the window to fit
it to the inserted contents.
post-command-select-window ¶If the value is non-nil, the buffer displayed by display-buffer
is selected after the current command is executed by running the hook
post-command-hook (see Command Loop Overview).
If the value is nil, the buffer selected by such functions as
pop-to-buffer is deselected, and the window that was selected
before calling this function will remain selected regardless of which
windows were selected afterwards within this command.
category ¶If the caller of display-buffer passes an alist entry
(category . symbol) in its action argument, then you
can match the displayed buffer by using the same category symbol in the
condition part of display-buffer-alist entries. See buffer-match-p. Thus, if a Lisp program uses a particular
symbol as the category when calling display-buffer, users
can customize how these buffers will be displayed by including such an
entry in display-buffer-alist.
tab-name ¶The value names the tab in which the buffer should be displayed. This
entry is used by display-buffer-in-new-tab and (conditionally) by
display-buffer-in-tab.
tab-group ¶The value names the tab group to use when creating a new tab, overriding
user option tab-bar-new-tab-group. This entry is used by
display-buffer-in-new-tab and display-buffer-in-tab.
By convention, the entries window-height, window-width
and preserve-size are applied after the chosen window’s buffer
has been set up and if and only if that window never showed another
buffer before. More precisely, the latter means that the window must
have been either created by the current display-buffer call or
the window was created earlier by display-buffer to show the
buffer and never was used to show another buffer until it was reused
by the current invocation of display-buffer.
If no window-height, window-width or window-size
entry was specified, the window may still be resized automatically when
the buffer is temporary and temp-buffer-resize-mode has been
enabled, Temporary Displays. In that case, the CDR of a
window-height, window-width or window-size entry
can be used to inhibit or override the default behavior of
temp-buffer-resize-mode for specific buffers or invocations of
display-buffer.
The behavior of buffer display actions (see Choosing a Window for Displaying a Buffer) can be further modified by the following user options.
If the value of this variable is non-nil, 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 for backward compatibility only. It is
obeyed by display-buffer via a special mechanism in
display-buffer-fallback-action, which calls the action function
display-buffer-pop-up-window (see Action Functions for Buffer Display) when the value of this option is non-nil. It is
not consulted by display-buffer-pop-up-window itself, which the
user may specify directly in display-buffer-alist etc.
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
display-buffer-pop-up-window action function to actually split
the window.
The value must be a function that takes one argument, a window, and
returns either a new window (which will be used to display the desired
buffer) or nil (which means the splitting failed). The default
value is split-window-sensibly, which is documented next.
This function tries to split window and return the newly created
window. If window cannot be split, it returns nil. If
window is omitted or nil, it defaults to the selected
window.
This function obeys the usual rules that determine when a window may be
split (see Splitting Windows). It first tries either a vertical
split by placing the new window below, subject to the restriction
imposed by split-height-threshold (see below), or a horizontal
split that places the new window to the right, subject to
split-width-threshold, in addition to any other restrictions.
Whether it tries first to split vertically or horizontally depends on
the value of the user option split-window-preferred-direction.
If splitting along the first dimension fails, it tries to split along
the other dimension. If that also fails, and the window is the only
window on its frame, this function again tries to split and place the
new window below, disregarding split-height-threshold. If this
fails as well, this function gives up and returns nil.
This variable specifies whether split-window-sensibly is
allowed 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 nil, that means not to split this
way.
This variable specifies whether split-window-sensibly is
allowed 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 nil,
that means not to split this way.
This variable determines the first dimension along which
split-window-sensibly tries to split the window, if the window
could be split both vertically and horizontally, as determined by the
values of split-height-threshold and
split-width-threshold. The default value is longest,
which means to split vertically if the height of the window’s frame is
greater or equal to its width, and horizontally otherwise. The values
vertical and horizontal specify the direction in which to
attempt the first split.
This variable, if non-nil, causes display-buffer to even
window sizes whenever it reuses an existing window, and that window is
adjacent to the selected one.
If its value is width-only, sizes are evened only if the reused
window is on the left or right of the selected one and the selected
window is wider than the reused one. If its value is height-only
sizes are evened only if the reused window is above or beneath the
selected window and the selected window is higher than the reused one.
Any other non-nil value means to even sizes in any of these cases
provided the selected window is larger than the reused one in the sense
of their combination.
If the value of this variable is non-nil, that means
display-buffer may display buffers by making new frames. The
default is nil.
A non-nil value also means that when display-buffer is
looking for a window already displaying buffer-or-name, it can
search any visible or iconified frame, not just the selected frame.
An entry by the same name in display-buffer’s alist
takes precedence over the variable.
This variable is provided mainly for backward compatibility. It is
obeyed by display-buffer via a special mechanism in
display-buffer-fallback-action, which calls the action function
display-buffer-pop-up-frame (see Action Functions for Buffer Display) if the value is non-nil. (This is done before
attempting to split a window.) This variable is not consulted by
display-buffer-pop-up-frame itself, which the user may specify
directly in display-buffer-alist etc.
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
display-buffer-pop-up-frame action function.
The value should be a function that takes no arguments and returns a
frame, or nil if no frame could be created. The default value
is a function that creates a frame using the parameters specified by
pop-up-frame-alist (see below).
This variable holds an alist of frame parameters (see Frame Parameters), which is used by the function specified by
pop-up-frame-function to make a new frame. The default is
nil.
This option is provided for backward compatibility only. Note, that
when display-buffer-pop-up-frame calls the function specified
by pop-up-frame-function, it prepends the value of all
pop-up-frame-parameters action alist entries to
pop-up-frame-alist so that the values specified by the action
alist entry effectively override any corresponding values of
pop-up-frame-alist.
Hence, users should set up a pop-up-frame-parameters action
alist entry in display-buffer-alist instead of customizing
pop-up-frame-alist. Only this will guarantee that the value of
a parameter specified by the user overrides the value of that
parameter specified by the caller of display-buffer.
Many efforts in the design of display-buffer have been given
to maintain compatibility with code that uses older options like
pop-up-windows, pop-up-frames,
pop-up-frame-alist, same-window-buffer-names and
same-window-regexps. Lisp Programs and users should refrain
from using these options. Above we already warned against customizing
pop-up-frame-alist. Here we describe how to convert the
remaining options to use display actions instead.
pop-up-windows ¶This variable is t by default. Instead of customizing it to
nil and thus telling display-buffer what not to do, it’s
much better to list in display-buffer-base-action the action
functions it should try instead as, for example:
(setopt
display-buffer-base-action
'((display-buffer-reuse-window display-buffer-same-window
display-buffer-in-previous-window
display-buffer-use-some-window)))
pop-up-frames ¶Instead of customizing this variable to t, you can customize
display-buffer-base-action, for example, as follows:
(setopt display-buffer-base-action '(nil (pop-up-frames . t)))
same-window-buffer-names ¶same-window-regexpsInstead of adding a buffer name or a regular expression to one of
these options use a display-buffer-alist entry for that buffer
specifying the action function display-buffer-same-window.
(setopt
display-buffer-alist
(cons '("\\*foo\\*" (display-buffer-same-window))
display-buffer-alist))
From the past subsections we already know that display-buffer
must be supplied with a number of display actions (see Choosing a Window for Displaying a Buffer) in order to display a buffer. In a completely uncustomized
Emacs, these actions are specified by
display-buffer-fallback-action in the following order of
precedence: Reuse a window, pop up a new window on the same frame, use
a window previously showing the buffer, use some window and pop up a
new frame. (Note that the remaining actions named by
display-buffer-fallback-action are void in an uncustomized
Emacs).
Consider the following form:
(display-buffer (get-buffer-create "*foo*"))
Evaluating this form in the buffer *scratch* of an uncustomized
Emacs session will usually fail to reuse a window that shows
*foo* already, but succeed in popping up a new window.
Evaluating the same form again will now not cause any visible
changes—display-buffer reused the window already showing
*foo* because that action was applicable and had the highest
precedence among all applicable actions.
Popping up a new window will fail if there is not enough space on
the selected frame. In an uncustomized Emacs it typically fails when
there are already two windows on a frame. For example, if you now
type C-x 1 followed by C-x 2 and evaluate the form
once more, *foo* should show up in the lower
window—display-buffer just used “some” window. If, before
typing C-x 2 you had typed C-x o, *foo*
would have been shown in the upper window because “some” window
stands for the “least recently used” window and the selected window
has been least recently used if and only if it is alone on its frame.
Let’s assume you did not type C-x o and *foo* is shown in the lower window. Type C-x o to get there followed by C-x left and evaluate the form again. This should display *foo* in the same, lower window because that window had already shown *foo* previously and was therefore chosen instead of some other window.
So far we have only observed the default behavior in an uncustomized
Emacs session. To see how this behavior can be customized, let’s
consider the option display-buffer-base-action. It provides a
very coarse customization which conceptually affects the display of
any buffer. It can be used to supplement the actions supplied
by display-buffer-fallback-action by reordering them or by
adding actions that are not present there but fit more closely the
user’s editing practice. However, it can also be used to change the
default behavior in a more profound way.
Let’s consider a user who, as a rule, prefers to display buffers on another frame. Such a user might provide the following customization:
(setopt display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0)))
This setting will cause display-buffer to first try to find a
window showing the buffer on a visible or iconified frame and, if no
such frame exists, pop up a new frame. You can observe this behavior
on a graphical system by typing C-x 1 in the window showing
*scratch* and evaluating our canonical display-buffer
form. This will usually create (and give focus to) a new frame whose
root window shows *foo*. Iconify that frame and evaluate the
canonical form again: display-buffer will reuse the window on
the new frame (usually raising the frame and giving it focus too).
Only if creating a new frame fails, display-buffer will
apply the actions supplied by display-buffer-fallback-action
which means to again try reusing a window, popping up a new window and
so on. A trivial way to make frame creation fail is supplied by the
following form:
(let ((pop-up-frame-function 'ignore)) (display-buffer (get-buffer-create "*foo*")))
We will forget about that form immediately after observing that it fails to create a new frame and uses a fallback action instead.
Note that display-buffer-reuse-window appears redundant in
the customization of display-buffer-base-action because it is
already part of display-buffer-fallback-action and should be
tried there anyway. However, that would fail because due to the
precedence of display-buffer-base-action over
display-buffer-fallback-action, at that time
display-buffer-pop-up-frame would have already won the race.
In fact, this:
(setopt display-buffer-base-action '(display-buffer-pop-up-frame (reusable-frames . 0)))
would cause display-buffer to always pop up a new frame
which is probably not what our user wants.
So far, we have only shown how users can customize the
default behavior of display-buffer. Let us now see how
applications can change the course of display-buffer.
The canonical way to do that is to use the action argument of
display-buffer or a function that calls it, like, for example,
pop-to-buffer (see Switching to a Buffer in a Window).
Suppose an application wants to display *foo* preferably below the selected window (to immediately attract the attention of the user to the new window) or, if that fails, in a window at the bottom of the frame. It could do that with a call like this:
(display-buffer (get-buffer-create "*foo*") '((display-buffer-below-selected display-buffer-at-bottom)))
In order to see how this new, modified form works, delete any frame
showing *foo*, type C-x 1 followed by C-x 2 in the
window showing *scratch*, and subsequently evaluate that form.
display-buffer should split the upper window, and show
*foo* in the new window. Alternatively, if after C-x 2
you had typed C-x o, display-buffer would have split the
window at the bottom instead.
Suppose now that, before evaluating the new form, you have made the
selected window as small as possible, for example, by evaluating the
form (fit-window-to-buffer) in that window. In that case,
display-buffer would have failed to split the selected window
and would have split the frame’s root window instead, effectively
displaying *foo* at the bottom of the frame.
In either case, evaluating the new form a second time should reuse the window already showing *foo* since both functions supplied by the action argument try to reuse such a window first.
By setting the action argument, an application effectively
overrules any customization of display-buffer-base-action. Our
user can now either accept the choice of the application, or redouble
by customizing the option display-buffer-alist as follows:
(setopt
display-buffer-alist
'(("\\*foo\\*"
(display-buffer-reuse-window display-buffer-pop-up-frame))))
Trying this with the new, modified form above in a configuration that
does not show *foo* anywhere, will display *foo* on a
separate frame, completely ignoring the action argument of
display-buffer.
Note that we didn’t care to specify a reusable-frames action
alist entry in our specification of display-buffer-alist.
display-buffer always takes the first one it finds—in our
case the one specified by display-buffer-base-action. If we
wanted to use a different specification, for example, to exclude
iconified frames showing *foo* from the list of reusable ones,
we would have to specify that separately, however:
(setopt
display-buffer-alist
'(("\\*foo\\*"
(display-buffer-reuse-window display-buffer-pop-up-frame)
(reusable-frames . visible))))
If you try this, you will notice that repeated attempts to display *foo* will succeed to reuse a frame only if that frame is visible.
The above example would allow the conclusion that users customize
display-buffer-alist for the sole purpose to overrule the
action argument chosen by applications. Such a conclusion would
be incorrect. display-buffer-alist is the standard option for
users to direct the course of display of specific buffers in a
preferred way regardless of whether the display is also guided by an
action argument.
We can, however, reasonably conclude that customizing
display-buffer-alist differs from customizing
display-buffer-base-action in two major aspects: it is stronger
because it overrides the action argument of
display-buffer, and it enables you to explicitly specify the
affected buffers. In fact, displaying other buffers is not affected
in any way by a customization for *foo*. For example,
(display-buffer (get-buffer-create "*bar*"))
continues being governed by the settings of
display-buffer-base-action and
display-buffer-fallback-action only.
We could stop with our examples here but Lisp programs still have
an ace up their sleeves which they can use to overrule any
customization of display-buffer-alist. It’s the variable
display-buffer-overriding-action which they can bind around
display-buffer calls as follows:
(let ((display-buffer-overriding-action
'((display-buffer-same-window))))
(display-buffer
(get-buffer-create "*foo*")
'((display-buffer-below-selected display-buffer-at-bottom))))
Evaluating this form will usually display *foo* in the selected window regardless of the action argument and any user customizations. (Usually, an application will not bother to also provide an action argument. Here it just serves to illustrate the fact that it gets overridden.)
It might be illustrative to look at the list of action functions
display-buffer would have tried to display *foo* with
the customizations we provided here. The list (including comments
explaining who added this and the subsequent elements) is:
(display-buffer-same-window ;; `display-buffer-overriding-action' display-buffer-reuse-window ;; `display-buffer-alist' display-buffer-pop-up-frame display-buffer-below-selected ;; ACTION argument display-buffer-at-bottom display-buffer-reuse-window ;; `display-buffer-base-action' display-buffer-pop-up-frame display-buffer--maybe-same-window ;; `display-buffer-fallback-action' display-buffer-reuse-window display-buffer--maybe-pop-up-frame-or-window display-buffer-in-previous-window display-buffer-use-some-window display-buffer-pop-up-frame)
Note that among the internal functions listed here,
display-buffer--maybe-same-window is effectively ignored while
display-buffer--maybe-pop-up-frame-or-window actually runs
display-buffer-pop-up-window.
The action alist passed in each function call is:
((reusable-frames . visible) (reusable-frames . 0))
which shows that we have used the second specification of
display-buffer-alist above, overriding the specification
supplied by display-buffer-base-action. Suppose our user had
written that as
(setopt
display-buffer-alist
'(("\\*foo\\*"
(display-buffer-reuse-window display-buffer-pop-up-frame)
(inhibit-same-window . t)
(reusable-frames . visible))))
In this case the inhibit-same-window alist entry will
successfully invalidate the display-buffer-same-window
specification from display-buffer-overriding-action and
display-buffer will show *foo* on another frame. To
make display-buffer-overriding-action more robust in this
regard, the application would have to specify an appropriate
inhibit-same-window entry too, for example, as follows:
(let ((display-buffer-overriding-action
'(display-buffer-same-window (inhibit-same-window . nil))))
(display-buffer (get-buffer-create "*foo*")))
This last example shows that while the precedence order of action functions is fixed, as described in Choosing a Window for Displaying a Buffer, an action alist entry specified by a display action ranked lower in that order can affect the execution of a higher ranked display action.
In its most simplistic form, a frame accommodates always one single
window that can be used for displaying a buffer. As a consequence, it
is always the latest call of display-buffer that will have
succeeded in placing its buffer there.
Since working with such a frame is not very practical, Emacs by
default allows for more complex frame layouts controlled by the
default values of the frame size and the split-height-threshold
and split-width-threshold options. Displaying a buffer not yet
shown on a frame then either splits the single window on that frame or
(re-)uses one of its two windows.
The default behavior is abandoned as soon as the user customizes
one of these thresholds or manually changes the frame’s layout. The
default behavior is also abandoned when calling display-buffer
with a non-nil action argument or the user customizes one
of the options mentioned in the previous subsections. Mastering
display-buffer soon may become a frustrating experience due to
the plethora of applicable display actions and the resulting frame
layouts.
However, refraining from using buffer display functions and falling back on a split & delete windows metaphor is not a good idea either. Buffer display functions give Lisp programs and users a framework to reconcile their different needs; no comparable framework exists for splitting and deleting windows. Buffer display functions also allow to at least partially restore the layout of a frame when removing a buffer from it later (see Quitting Windows).
Below we will give a number of guidelines to redeem the frustration mentioned above and thus to avoid literally losing buffers in-between the windows of a frame.
Writing display actions can be a pain because one has to lump together
action functions and action alists in one huge list. (Historical
reasons prevented us from having display-buffer support
separate arguments for these.) It might help to memorize some basic
forms like the ones listed below:
'(nil (inhibit-same-window . t))
specifies an action alist entry only and no action function. Its sole
purpose is to inhibit a display-buffer-same-window function
specified elsewhere from showing the buffer in the same window, see
also the last example of the preceding subsection.
'(display-buffer-below-selected)
on the other hand, specifies one action function and an empty action alist. To combine the effects of the above two specifications one would write the form
'(display-buffer-below-selected (inhibit-same-window . t))
to add another action function one would write
'((display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t))
and to add another alist entry one would write
'((display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) (window-height . fit-window-to-buffer))
That last form can be used as action argument of
display-buffer in the following way:
(display-buffer (get-buffer-create "*foo*") '((display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) (window-height . fit-window-to-buffer)))
In a customization of display-buffer-alist it would be used as
follows:
(setopt
display-buffer-alist
'(("\\*foo\\*"
(display-buffer-below-selected display-buffer-at-bottom)
(inhibit-same-window . t)
(window-height . fit-window-to-buffer))))
To add a customization for a second buffer one would then write:
(setopt
display-buffer-alist
'(("\\*foo\\*"
(display-buffer-below-selected display-buffer-at-bottom)
(inhibit-same-window . t)
(window-height . fit-window-to-buffer))
("\\*bar\\*"
(display-buffer-reuse-window display-buffer-pop-up-frame)
(reusable-frames . visible))))
display-buffer-alist and display-buffer-base-action are
user options—Lisp programs must never set or rebind them.
display-buffer-overriding-action, on the other hand, is
reserved for applications—who seldom use that option and if they use
it, then with utmost care.
Older implementations of display-buffer frequently caused
users and applications to fight over the settings of user options like
pop-up-frames and pop-up-windows (see Additional Options for Displaying Buffers). This was one major reason for redesigning
display-buffer—to provide a clear framework specifying what
users and applications should be allowed to do.
Lisp programs must be prepared that user customizations may
cause buffers to get displayed in an unexpected way. They should
never assume in their subsequent behavior, that the buffer has been
shown precisely the way they asked for in the action argument of
display-buffer.
Users should not pose too many and too severe restrictions on how
arbitrary buffers get displayed. Otherwise, they will risk to lose
the characteristics of showing a buffer for a certain purpose.
Suppose a Lisp program has been written to compare different versions
of a buffer in two windows side-by-side. If the customization of
display-buffer-alist prescribes that any such buffer should be
always shown in or below the selected window, the program will have a
hard time to set up the desired window configuration via
display-buffer.
To specify a preference for showing an arbitrary buffer, users
should customize display-buffer-base-action. An example of how
users who prefer working with multiple frames would do that was given
in the previous subsection. display-buffer-alist should be
reserved for displaying specific buffers in a specific way.
Generally, it’s always a good idea for users and Lisp
programmers to be prepared for the case that a window already shows
the buffer in question and to reuse that window. In the preceding
subsection we have shown that failing to do so properly may cause
display-buffer to continuously pop up a new frame although a
frame showing that buffer existed already. In a few cases only, it
might be undesirable to reuse a window, for example, when a different
portion of the buffer should be shown in that window.
Hence, display-buffer-reuse-window is one action function
that should be used as often as possible, both in action
arguments and customizations. An inhibit-same-window entry in
the action argument usually takes care of the most common case
where reusing a window showing the buffer should be avoided—that
where the window in question is the selected one.
This is a no-brainer for people working with multiple frames—the
frame showing the buffer will automatically raise and get focus unless
an inhibit-switch-frame entry forbids it. For single frame
users this task can be considerably more difficult. In particular,
display-buffer-pop-up-window and
display-buffer-use-some-window can become obtrusive in this
regard. They split or use a seemingly arbitrary (often the largest or
least recently used) window, distracting the user’s attention.
Some Lisp programs therefore try to choose a window at the bottom of
the frame, for example, in order to display the buffer in vicinity of
the minibuffer window where the user is expected to answer a question
related to the new window. For non-input related actions
display-buffer-below-selected might be preferable because the
selected window usually already has the user’s attention.
Many applications call display-buffer from within window
excursions produced by with-selected-window or
select-window calls with a non-nil norecord
argument. This is almost always a bad idea because the window selected
within such an excursion is usually not the window selected in the
configuration presented to the user.
If, for example, a user had added an inhibit-same-window alist
entry, that entry would have avoided the window selected within the
scope of the excursion and not the window selected in the resulting
configuration. Even if no such entry has been added, the resulting
behavior might be strange. While in a frame containing one live
window, evaluating the following form
(progn (split-window) (display-buffer "*Messages*"))
will display a window showing the *Messages* buffer at the bottom and leave the other window selected. Evaluating the next form
(with-selected-window (split-window) (display-buffer "*Messages*"))
will display *Messages* in a window on the top and select it
which is usually not what display-buffer is supposed to do.
On the other hand, while evaluating the following form
(progn (split-window) (pop-to-buffer "*Messages*"))
will correctly select the *Messages* buffer, the next form
(progn
(split-window)
(with-selected-window (selected-window)
(pop-to-buffer "*Messages*")))
will not.
Also, invocations of action functions like
display-buffer-use-some-window and
display-buffer-use-least-recent-window that expect the selected
window to have the highest use time among all windows, may fail to
produce a window according to their specifications.
Hence, an application that relies on using a window excursion should try
to postpone the display-buffer call until after the excursion has
terminated.
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 replace-buffer-in-windows
(see Buffers and Windows), and when quitting windows
(see Quitting Windows). The list is automatically maintained by
Emacs, but you can use the following functions to explicitly inspect
or alter it:
This function returns a list specifying the previous contents of window. The optional argument window should be a live window and defaults to the selected one.
Each list element has the form (buffer window-start
window-pos), where buffer is a buffer previously shown in
the window, window-start is a marker that gives the window start
position (see The Window Start and End Positions) when that buffer was last shown,
and window-pos is a marker that gives the window point position
(see Windows and Point) when that buffer was last shown in 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.
As a rule, elements are removed from this list when their buffer gets killed. In rare cases, however, elements may have survived the killing of their buffer. It’s a good idea therefore to always check buffers for liveness when processing the return value of this function.
This function sets window’s previous buffers to the value of
prev-buffers. The argument window must be a live window
and defaults to the selected one. The argument prev-buffers
should be a list of the same form as that returned by
window-prev-buffers.
In addition, each window maintains a list of next buffers, which
is a list of buffers re-shown by switch-to-prev-buffer (see
below). This list is mainly used by switch-to-prev-buffer and
switch-to-next-buffer for choosing buffers to switch to.
This function returns the list of buffers recently re-shown in
window via switch-to-prev-buffer. The window
argument must denote a live window or nil (meaning the selected
window).
This function sets the next buffer list of window to
next-buffers. The window argument should be a live window
or nil (meaning the selected window). The argument
next-buffers should be a list of buffers.
The following commands can be used to cycle through the global buffer
list, much like bury-buffer and 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
switch-to-prev-buffer command, in particular, is used by
replace-buffer-in-windows, bury-buffer and
quit-window to find a replacement buffer for a window.
This command displays the previous buffer in window. The
argument window should be a live window or nil (meaning
the selected window). If the optional argument bury-or-kill is
non-nil, this means that the buffer currently shown in
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 window. However, a buffer that has been buried
or killed, or has been already shown by a recent invocation of
switch-to-prev-buffer, does not qualify as previous buffer.
If repeated invocations of this command have already shown all buffers previously shown in window, further invocations will show buffers from the buffer list of the frame window appears on (see The Buffer List).
The option switch-to-prev-buffer-skip described below can be
used to inhibit switching to certain buffers, for example, to those
already shown in another window. Also, if window’s frame has a
buffer-predicate parameter (see Buffer Parameters), that
predicate may inhibit switching to certain buffers.
This command switches to the next buffer in window, thus undoing
the effect of the last switch-to-prev-buffer command in
window. The argument window must be a live window and
defaults to the selected one.
If there is no recent invocation of switch-to-prev-buffer that
can be undone, this function tries to show a buffer from the buffer list
of the frame window appears on (see The Buffer List).
The option switch-to-prev-buffer-skip and the
buffer-predicate (see Buffer Parameters) of window’s
frame affect this command as they do for switch-to-prev-buffer.
By default switch-to-prev-buffer and
switch-to-next-buffer can switch to a buffer that is already
shown in another window. The following option can be used to override
this behavior.
If this variable is nil, switch-to-prev-buffer may
switch to any buffer, including those already shown in other windows.
If this variable is non-nil, switch-to-prev-buffer will
refrain from switching to certain buffers. The following values can
be used:
this means do not switch to a buffer shown on the frame that
hosts the window switch-to-prev-buffer is acting upon.
visible means do not switch to a buffer shown on any visible
frame.
t means do not switch to a buffer shown on any live frame.
switch-to-prev-buffer, a buffer switch-to-prev-buffer
intends to switch to and the bury-or-kill argument of
switch-to-prev-buffer. If that function returns
non-nil, switch-to-prev-buffer will refrain from
switching to the buffer specified by the second argument.
The command switch-to-next-buffer obeys this option in a
similar way. If this option specifies a function,
switch-to-next-buffer will call that function with the third
argument always nil.
Note that since switch-to-prev-buffer is called by
bury-buffer, replace-buffer-in-windows and
quit-restore-window as well, customizing this option may also
affect the behavior of Emacs when a window is quit or a buffer gets
buried or killed.
Note also that under certain circumstances
switch-to-prev-buffer and switch-to-next-buffer may
ignore this option, for example, when there is only one buffer left
these functions can switch to.
This user option should be either a regular expression or a list of
regular expressions. Buffers whose names match one of those regular
expressions will be ignored by switch-to-prev-buffer and
switch-to-next-buffer (except when there’s no other buffer to
switch to).
Functions for displaying a buffer can be told to not use specific
windows by marking these windows as dedicated to their buffers.
display-buffer (see Choosing a Window for Displaying a Buffer) never uses a dedicated
window for displaying another buffer in it. get-lru-window and
get-largest-window (see Cyclic Ordering of Windows) do not
consider dedicated windows as candidates when their dedicated
argument is non-nil. The behavior of set-window-buffer
(see 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 four 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, (3)
the window is the only window on the only frame on the same terminal,
and (4) the dedication’s value is side
(see Displaying Buffers in Side Windows).
In particular, delete-windows-on (see Deleting Windows)
handles case (2) by deleting the associated frame and cases (3) and (4)
by showing another buffer in that frame’s only window. The function
replace-buffer-in-windows (see Buffers and Windows) which is
called when a buffer gets killed, deletes the window in case (1) and
behaves like delete-windows-on otherwise.
When bury-buffer (see The Buffer List) operates on the
selected window (which shows the buffer that shall be buried), it
handles case (2) by calling frame-auto-hide-function
(see Quitting Windows) to deal with the selected frame. The other
two cases are handled as with replace-buffer-in-windows.
This function returns non-nil if window is dedicated to its
buffer and nil otherwise. More precisely, the return value is
the value assigned by the last call of set-window-dedicated-p for
window, or nil if that function was never called with
window as its argument. The default for window is the
selected window.
This function marks window as dedicated to its buffer if
flag is non-nil, and non-dedicated otherwise.
Interactively you can use the C-x w d
(toggle-window-dedicated) command to do the same.
As a special case, if flag is t, window becomes
strongly dedicated to its buffer. 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 t differently from any
non-nil value.
You can also tell display-buffer to mark a window it creates as
dedicated to its buffer by providing a suitable dedicated
action alist entry (see Action Alists for Buffer Display).
After a command uses display-buffer to put a buffer on the
screen, the user may decide to hide it and return to the previous
configuration of the Emacs display. We call that quitting the
window. The way to do this is to call quit-window while the
window used by display-buffer is the selected window.
The right way to restore the previous configuration of the display depends on what was done to the window where the buffer now appears. It might be right to delete that window, or delete its frame, or just display another buffer in that window. One complication is that the user may have changed the window configuration since the act of displaying that buffer, and it would be undesirable to undo the user’s explicitly requested changes.
To enable quit-window to do the right thing,
display-buffer saves information about what it did in the
window’s quit-restore parameter (see Window Parameters).
This command quits window and buries its buffer. (It could also
kill the buffer, subject to quit-window-kill-buffer, see below.)
The argument window must be a live window and defaults to the
selected one. With prefix argument kill non-nil, it kills
the buffer instead of burying it.
The function quit-window first runs quit-window-hook.
Then it calls the function quit-restore-window, described below,
which does the hard work.
The following option tells quit-window whether it should kill or
bury window’s buffer when the kill argument is nil.
This variable controls whether quit-window kills the buffer of
its window argument. If the value is nil (the default)
quit-window will kill window’s buffer only if the
kill argument is non-nil. If this is t,
quit-window will try to kill window’s buffer regardless of
the value of the kill argument. Otherwise, this should be a list
of major modes; quit-window will kill the buffer of window
regardless of the value of kill if that buffer’s major mode is
either a member of this list or is derived from a member of this list.
In any other case, quit-window will kill the buffer only if
kill is non-nil and bury it otherwise.
You can get more control by calling quit-restore-window instead
of quit-window.
This function handles window and its buffer after quitting. The
optional argument window must be a live window and defaults to
the selected one. The function takes account of the window’s
quit-restore parameter.
The optional argument bury-or-kill specifies how to deal with window’s buffer. The following values are meaningful:
nilThis means to not deal with the buffer in any particular way. As a
consequence, if window is not deleted, invoking
switch-to-prev-buffer will usually show the buffer again.
appendThis means that if window is not deleted, its buffer is moved to
the end of window’s list of previous buffers (see Window History), so it’s less likely that future invocations of
switch-to-prev-buffer will switch to it. Also, it moves the
buffer to the end of the frame’s buffer list (see The Buffer List).
buryThis means that if window is not deleted, its buffer is removed
from window’s list of previous buffers. Also, it moves the
buffer to the end of the frame’s buffer list. This is the most
reliable way to prevent switch-to-prev-buffer from switching to
this buffer again, short of killing the buffer.
killThis means to kill window’s buffer.
killingThis is handled like kill but assumes that window’s buffer
gets killed elsewhere. This value is used by
replace-buffer-in-windows and quit-windows-on.
buryingThis is handled like bury but assumes that window’s buffer
gets buried elsewhere. This value is used by quit-windows-on.
The argument bury-or-kill also specifies what to do with
window’s frame when window should be deleted, if it is the
only window on its frame, and there are other frames on that frame’s
terminal. If bury-or-kill equals kill, it means to
delete the frame. Otherwise, the fate of the frame is determined by
calling frame-auto-hide-function (see below) with that frame as
sole argument.
A window’s quit-restore and quit-restore-prev parameters
(see Window Parameters) guide quit-restore-window through its
process of dealing with its window argument. If such a parameter
is absent or nil, this usually means that the window has been
created by a command like split-window-below or
split-window-right (see Split Window in The GNU Emacs
Manual) and quit-restore-window will delete the window only if
it was dedicated to its buffer.
If non-nil, any such parameter is a list of four elements:
(method obuffer owindow this-buffer)
The first element, method, is one of the four symbols
window, frame, same and other.
frame and window control how to delete window,
while same and other control displaying some other
buffer in it.
Specifically, window means that the window has been specially
created by display-buffer; frame means that a separate
frame has been created; same, that the window has only ever
displayed this buffer; other, that the window showed another
buffer before.
The second element, obuffer, is either one of the symbols
window or frame, or a list of the form
(prev-buffer prev-window-start prev-window-point height)
which says which buffer was shown in window before, that buffer’s window start (see The Window Start and End Positions) and window point (see Windows and Point) positions at that time, and window’s height at that time. If prev-buffer is still live when quitting window, quitting the window may reuse window to display prev-buffer.
The third element, owindow, is the window that was selected just before the displaying was done. If quitting deletes window, it tries to select owindow.
The fourth element, this-buffer, is the buffer whose displaying
set the quit-restore parameter. Quitting window will use
the information stored by that parameter if and only if it still shows
that buffer.
quit-restore-window tries to delete its window if (1)
method is either window or frame, (2) the window has
no history of previously-displayed buffers and (3) this-buffer
equals the buffer currently displayed in window. If window
is part of an atomic window (see Atomic Windows), it will try to
delete the root of that atomic window instead. In either case, it tries
to avoid signaling an error when window cannot be deleted.
If obuffer is a list, and prev-buffer is still live, quitting displays prev-buffer in window according to the rest of the elements of obuffer. This includes resizing the window to height if it was temporarily resized to display this-buffer.
Otherwise, if window was previously used for displaying other buffers (see Window History), the most recent buffer in that history will be displayed.
Conceptually, the quit-restore parameter is used for undoing
the first buffer display operation for a specific window. The
quit-restore-prev parameter is used for undoing the last buffer
display operation in a row of such operations for a specific window.
Any buffer display operation for that window that happened in between,
is undone by displaying the buffer previously shown in that window.
display-buffer sets up the quit-restore parameter of any
window it uses when that window has been either created by it or has no
non-nil quit-restore parameter. If the window already has
a quit-restore parameter, display-buffer adds a
quit-restore-prev parameter whose method element is either
same or other. In either case, if the window already has
a quit-restore-prev or quit-restore parameter, it may
update that parameter’s contents.
quit-restore-window now first tries to find a suitable
quit-restore-prev parameter for its window telling which buffer
to show instead. If it doesn’t find one, it will look for a suitable
quit-restore parameter to either delete the window or show
another buffer in it.
Once it has used one of these parameters, quit-restore-window
resets it to nil. Parameters it did not use are left alone. Any
of these parameters are also reset by replace-buffer-in-windows
(see Buffers and Windows) when they reference a buffer that is about
to be killed, either as the buffer specified by prev-buffer or as
the buffer specified by this-buffer.
All operations on these parameters are supposed to preserve the
following invariant: If a window has a non-nil
quit-restore-prev parameter, it also has a non-nil
quit-restore parameter.
The following option allows quit-restore-window to delete its
window more aggressively.
If this option is nil, quit-restore-window will always
call switch-to-prev-buffer unless the window has been made by
display-buffer. If this is t, quit-restore-window
will try hard to switch only to buffers previously shown in that window.
If this is the symbol skip-first, it will switch to a previous
buffer if and only the window has at least two previous buffers.
In either case, if quit-restore-window doesn’t switch to a
previous buffer, it will try to delete the window (and maybe its
frame) instead. Note also that if a window is dedicated,
quit-restore-window will usually not switch to a previous
buffer in it either.
The following option specifies a function to do the right thing with a frame containing one window when quitting that window.
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 bury-buffer
(see The Buffer List) when the selected window is dedicated and shows
the buffer to bury. It is also called by 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 iconify-frame (see Visibility of Frames). Alternatively, you may specify either delete-frame
(see Deleting Frames) to remove the frame from its display,
make-frame-invisible to make the frame invisible, 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.
For a particular frame, the value specified here may be overridden by
that frame’s auto-hide-function frame parameter (see Frame Interaction Parameters).
Side windows are special windows positioned at any of the four sides of a frame’s root window (see Windows and Frames). In practice, this means that the area of the frame’s root window is subdivided into a main window and a number of side windows surrounding that main window. The main window is either a “normal” live window or specifies the area containing all the normal windows.
In their most simple form of use, side windows allow displaying
specific buffers always in the same area of a frame. Hence they can
be regarded as a generalization of the concept provided by
display-buffer-at-bottom (see Action Functions for Buffer Display) to the remaining sides of a frame. With suitable
customizations, however, side windows can be also used to provide
frame layouts similar to those found in so-called integrated
development environments (IDEs).
The following action function for display-buffer (see Action Functions for Buffer Display) creates or reuses a side window for
displaying the specified buffer.
This function displays buffer in a side window of the selected
frame. It returns the window used for displaying buffer,
nil if no such window can be found or created.
alist is an association list of symbols and values as for
display-buffer. The following symbols in alist are special
for this function:
sideDenotes the side of the frame where the window shall be located. Valid
values are left, top, right and bottom. If
unspecified, the window is located at the bottom of the frame.
slotDenotes a slot at the specified side where to locate the window. A
value of zero means to preferably position the window in the middle of
the specified side. A negative value means to use a slot preceding
(that is, above or on the left of) the middle slot. A positive value
means to use a slot following (that is, below or on the right of) the
middle slot. Hence, all windows on a specific side are ordered by their
slot value. If unspecified, the window is located in the middle
of the specified side.
dedicatedThe dedicated flag (see Dedicated Windows) has a slightly different
meaning for side windows. When a side window is created, that flag is
set to the value side to prevent display-buffer to use the
window in other action functions. Its value persists across invocations
of quit-window, kill-buffer, previous-buffer and
next-buffer.
In particular, these commands will refrain from showing, in a side
window, buffers that have not been displayed in that window before.
They will also refrain from having a normal, non-side window show a
buffer that has been already displayed in a side window. A notable
exception to the latter rule occurs when an application, after
displaying a buffer, resets that buffer’s local variables. To override
these rules and always delete a side window with quit-window or
kill-buffer, and eventually prevent the use of
previous-buffer and next-buffer, set this value to
t or specify a value via display-buffer-mark-dedicated.
If you specify the same slot on the same side for two or more different buffers, the buffer displayed last is shown in the corresponding window. Hence, slots can be used for sharing the same side window between buffers.
This function installs the window-side and window-slot
parameters (see Window Parameters) and makes them persistent. It
does not install any other window parameters unless they have been
explicitly provided via a window-parameters entry in alist.
By default, side windows cannot be split via split-window
(see Splitting Windows). Also, a side window is not reused or
split by any buffer display action (see Action Functions for Buffer Display) unless it is explicitly specified as target of that
action. Note also that delete-other-windows cannot make a side
window the only window on its frame (see Deleting Windows).
The following options provide additional control over the placement of side windows.
If non-nil, the side windows on the left and right of a frame
occupy the frame’s full height. Otherwise, the side windows on the top
and bottom of the frame occupy the frame’s full width.
This option specifies the maximum number of side windows on each side of
a frame. The value is a list of four elements specifying the number of
side window slots on (in this order) the left, top, right and bottom of
each frame. If an element is a number, it means to display at most that
many windows on the corresponding side. If an element is nil, it
means there’s no bound on the number of slots on that side.
If any of the specified values is zero, no window can be created on the
corresponding side. display-buffer-in-side-window will not
signal an error in that case, but will return nil. If a specified
value just forbids the creation of an additional side window, the most
suitable window on that side is reused and may have its
window-slot parameter changed accordingly.
This option specifies whether top/bottom side windows should appear in
reverse order. When this is nil, side windows on the top and
bottom of a frame are always drawn from left to right with increasing
slot values. When this is t, the drawing order is reversed and
side windows on the top and bottom of a frame are drawn from right to
left with increasing slot values.
When this is bidi, the drawing order is reversed if and only if
the value of bidi-paragraph-direction (see Bidirectional Display) is right-to-left in the buffer displayed in the window
most recently selected within the main window area of this frame.
Sometimes that window may be hard to find, so heuristics are used to
avoid that the drawing order changes inadvertently when another window
gets selected.
The layout of side windows on the left or right of a frame is not affected by the value of this variable.
When a frame has side windows, the following function returns the main window of that frame.
This function returns the main window of the specified frame. The optional argument frame must be a live frame and defaults to the selected one.
If frame has no side windows, it returns frame’s root
window. Otherwise, it returns either an internal non-side window such
that all other non-side windows on frame descend from it, or the
single live non-side window of frame. Note that the main window
of a frame cannot be deleted via delete-window.
The following command is handy to toggle the appearance of all side windows on a specified frame.
This command toggles side windows on the specified frame. The optional argument frame must be a live frame and defaults to the selected one.
If frame has at least one side window, this command saves the
state of frame’s root window in the frame’s
window-state frame parameter and deletes all side windows on
frame afterwards.
If frame has no side windows, but does have a window-state
parameter, this command uses that parameter’s value to restore the side
windows on frame leaving frame’s main window alone.
An error is signaled if frame has no side windows and no saved state is found for it.
Side windows can be used to create more complex frame layouts like those provided by integrated development environments (IDEs). In such layouts, the area of the main window is where the normal editing activities take place. Side windows are not conceived for editing in the usual sense. Rather, they are supposed to display information complementary to the current editing activity, like lists of files, tags or buffers, help information, search or grep results or shell output.
The layout of such a frame might appear as follows:
___________________________________
| *Buffer List* |
|___________________________________|
| | | |
| * | | * |
| d | | T |
| i | | a |
| r | Main Window Area | g |
| e | | s |
| d | | * |
| * | | |
|_____|_______________________|_____|
| *help*/*grep*/ | *shell*/ |
| *Completions* | *compilation* |
|_________________|_________________|
| Echo Area |
|___________________________________|
The following example illustrates how window parameters (see Window Parameters) can be used with display-buffer-in-side-window
(see Displaying Buffers in Side Windows) to set up code for
producing the frame layout sketched above.
(defvar parameters
'(window-parameters . ((no-other-window . t)
(no-delete-other-windows . t))))
(setq fit-window-to-buffer-horizontally t)
(setq window-resize-pixelwise t)
(setq
display-buffer-alist
`(("\\*Buffer List\\*" display-buffer-in-side-window
(side . top) (slot . 0) (window-height . fit-window-to-buffer)
(preserve-size . (nil . t)) ,parameters)
("\\*Tags List\\*" display-buffer-in-side-window
(side . right) (slot . 0) (window-width . fit-window-to-buffer)
(preserve-size . (t . nil)) ,parameters)
("\\*\\(?:help\\|grep\\|Completions\\)\\*"
display-buffer-in-side-window
(side . bottom) (slot . -1) (preserve-size . (nil . t))
,parameters)
("\\*\\(?:shell\\|compilation\\)\\*" display-buffer-in-side-window
(side . bottom) (slot . 1) (preserve-size . (nil . t))
,parameters)))
This specifies display-buffer-alist entries (see Choosing a Window for Displaying a Buffer) for buffers with fixed names. In particular, it asks for
showing *Buffer List* with adjustable height at the top of the
frame and *Tags List* with adjustable width on the frame’s right.
It also asks for having the *help*, *grep* and
*Completions* buffers share a window on the bottom left side of
the frame and the *shell* and *compilation* buffers appear
in a window on the bottom right side of the frame.
Note that the option fit-window-to-buffer-horizontally must
have a non-nil value in order to allow horizontal adjustment of
windows. Entries are also added that ask for preserving the height of
side windows at the top and bottom of the frame and the width of side
windows at the left or right of the frame. To assure that side windows
retain their respective sizes when maximizing the frame, the variable
window-resize-pixelwise is set to a non-nil value.
See Resizing Windows.
The last form also makes sure that none of the created side windows
are accessible via C-x o by installing the no-other-window
parameter for each of these windows. In addition, it makes sure that
side windows are not deleted via C-x 1 by installing the
no-delete-other-windows parameter for each of these windows.
Since dired buffers have no fixed names, we use a special
function dired-default-directory-on-left in order to display a
lean directory buffer on the left side of the frame.
(defun dired-default-directory-on-left ()
"Display `default-directory' in side window on left, hiding details."
(interactive)
(let ((buffer (dired-noselect default-directory)))
(with-current-buffer buffer (dired-hide-details-mode t))
(display-buffer-in-side-window
buffer `((side . left) (slot . 0)
(window-width . fit-window-to-buffer)
(preserve-size . (t . nil)) ,parameters))))
Evaluating the preceding forms and typing, in any order, M-x list-buffers, C-h f, M-x shell, M-x list-tags, and M-x dired-default-directory-on-left should now reproduce the frame layout sketched above.
Atomic windows are rectangular compositions of at least two live windows. They have the following distinctive characteristics:
split-window (see Splitting Windows), when
applied to a constituent of an atomic window, will try to create the new
window outside of the atomic window.
delete-window (see Deleting Windows), when
applied to a constituent of an atomic window, will try to delete the
entire atomic window instead.
delete-other-windows (see Deleting Windows),
when applied to a constituent of an atomic window, will try to make the
atomic window fill its frame or main window (see Side Windows).
This means that the basic groups of functions that alter the window structure treat an atomic window like a live one, thus preserving the internal structure of the atomic window.
Atomic windows are useful to construct and preserve window layouts that are meaningful only when all involved buffers are shown simultaneously in a specific manner, such as when showing differences between file revisions, or the same text in different languages or markups. They can also be used to permanently display information pertinent to a specific window in bars on that window’s sides.
Atomic windows are implemented with the help of the reserved
window-atom window parameter (see Window Parameters) and an
internal window (see Basic Concepts of Emacs Windows) called the root window of the
atomic window. All windows that are part of the same atomic window have
this root window as their common ancestor and are assigned a
non-nil window-atom parameter.
The following function returns the root of the atomic window a specified window is part of:
This functions returns the root of the atomic window window is a
part of. The specified window must be a valid window and defaults
to the selected one. It returns nil if window is not part
of an atomic window.
The most simple approach to make a new atomic window is to take an existing internal window and apply the following function:
This function converts window into an atomic window. The
specified window must be an internal window. All this function
does is to set the window-atom parameter of each descendant of
window to t.
To create a new atomic window from an existing live window or to add a new window to an existing atomic window, the following buffer display action function (see Action Functions for Buffer Display) can be used:
This function tries to display buffer in a new window that will be combined with an existing window to form an atomic window. If the existing window is already part of an atomic window, it adds the new window to that atomic window.
The specified alist is an association list of symbols and values. The following symbols have a special meaning:
windowThe value of such an element specifies an existing window the new window
shall be combined with. If it specifies an internal window, all
children of that window become part of the atomic window too. If no
window is specified, the new window becomes a sibling of the selected
window. The window-atom parameter of the existing window is set
to main provided that window is live and its window-atom
parameter was not already set.
sideThe value of such an element denotes the side of the existing window
where the new window shall be located. Valid values are below,
right, above and left. The default is
below. The window-atom parameter of the new window is set
to this value.
The return value is the new window, nil when creating that window
failed.
Note that the value of the window-atom parameter does not really
matter as long as it is non-nil. The values assigned by
display-buffer-in-atom-window just allow for easy retrieval of
the original and the new window after that function has been applied.
Note also that the window-atom parameter is the only window
parameter assigned by display-buffer-in-atom-window. Further
parameters have to be set by the application explicitly via a
window-parameters entry in alist.
Atomic windows automatically cease to exist when one of their
constituents gets deleted. To dissolve an atomic window manually,
reset the window-atom parameter of its constituents—the root
of the atomic window and all its descendants.
The following code snippet, when applied to a single-window frame, first splits the selected window and makes the selected and the new window constituents of an atomic window with their parent as root. It then displays the buffer *Messages* in a new window at the frame’s bottom and makes that new window part of the atomic window just created.
(let ((window (split-window-right))) (window-make-atom (window-parent window)) (display-buffer-in-atom-window (get-buffer-create "*Messages*") `((window . ,(window-parent window)) (window-height . 5))))
At this moment typing C-x 2 in any window of that frame produces a new window at the bottom of the frame. Typing C-x 3 instead will put the new window at the frame’s right. In either case, typing now C-x 1 in any window of the atomic window will remove the new window only. Typing C-x 0 in any window of the atomic window will make that new window fill the frame.
Each window has its own value of point (see 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.
with-selected-window (see Selecting Windows) or running
window-configuration-change-hook (see Hooks for Window Scrolling and Changes).
Emacs displays the cursor, by default as a rectangular block, in each window at the position of that window’s point. When the user switches to another buffer in a window, Emacs moves that window’s cursor to where point is in that buffer. If the exact position of point is hidden behind some display element, such as a display string or an image, Emacs displays the cursor immediately before or after that display element.
This function returns the current position of point in 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 window is the selected window.
When 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
save-excursion forms. But that value is hard to find.
This function positions point in window at position position in window’s buffer. It returns position.
If window is selected, this simply does goto-char in
window’s buffer.
This variable specifies the marker insertion type (see Marker Insertion Types) of window-point. The default is nil,
so window-point will stay behind text inserted there.
This function sets the cursor shape for window. This setting
takes precedence over the cursor-type variable, and type
has the same format as the value of that variable. See Cursor Parameters. If window is nil, it means to set the cursor
type for the selected window.
The initial value for new windows is t, which says to respect the
buffer-local value of cursor-type. The value set by this
function persists across buffers shown in window, so
set-window-buffer does not reset it. See Buffers and Windows.
This function returns the cursor type of window, defaulting to the selected window.
This function returns information about the cursor of window, defaulting to the selected window.
The value returned by the function is a vector of the form
[type x y width height ascent]. Here’s the description of each components of this
vector:
The type of the cursor, a symbol. This is the same value returned by
window-cursor-type.
The pixel coordinates of the cursor’s top-left corner, relative to the top-left corner of window’s text area.
The pixel dimensions of the cursor.
The number of pixels the cursor extends above the baseline.
If the cursor is not currently displayed for window, this function
returns nil.
Any element except the first one in the returned vector may be
-1, meaning the actual value is currently unavailable.
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 display-start position of the window (or just the 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.
This function returns the display-start position of window
window. If window is 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 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.
This function is like window-start, except that when
window is a part of a group of windows (see Window Group),
window-group-start returns the start position of the entire
group. This condition holds when the buffer local variable
window-group-start-function is set to a function. In this
case, window-group-start calls the function with the single
argument window, then returns its result.
This function returns the position where display of its buffer ends in window. The default for window is the selected window.
Simply changing the buffer text or moving point does not update the
value that window-end returns. The value is updated only when
Emacs redisplays and redisplay completes without being preempted.
If the last redisplay of 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 nil.
If update is non-nil, window-end always returns an
up-to-date value for where display ends, based on the current
window-start value. If a previously saved value of that position
is still valid, window-end returns that value; otherwise it
computes the correct value by scanning the buffer text.
Even if update is non-nil, 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
window-start value. In effect, it reports where the displayed
text will end if scrolling is not required. Note that the position it
returns might be only partially visible.
This function is like window-end, except that when window
is a part of a group of windows (see Window Group),
window-group-end returns the end position of the entire group.
This condition holds when the buffer local variable
window-group-end-function is set to a function. In this case,
window-group-end calls the function with the two arguments
window and update, then returns its result. The argument
update has the same meaning as in window-end.
This function sets the display-start position of window to position in window’s buffer. It returns position.
The display routines insist that the position of point be visible when a
buffer is displayed. Normally, they select the display-start position
according to their internal logic (and scroll the window if necessary)
to make point visible. However, if you specify the start position
with this function using nil for noforce, it means you
want display to start at position even if that would put the
location of point off the screen. If this does place point off
screen, the display routines attempt to move point to the left margin
on the middle line in the window.
For example, if point is 1 and you set the start of the window 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:
;; Here is what ‘foo’ looks like before executing
;; the set-window-start expression.
---------- Buffer: foo ---------- ∗This is the contents of buffer foo. 2 3 4 5 6 ---------- Buffer: foo ----------
(set-window-start (selected-window) (save-excursion (goto-char 1) (forward-line 1) (point))) ⇒ 37
;; Here is what ‘foo’ looks like after executing
;; the set-window-start expression.
---------- Buffer: foo ----------
2
3
∗4
5
6
---------- Buffer: foo ----------
If the attempt to make point visible (i.e., in a fully-visible screen line) fails, the display routines will disregard the requested window-start position and compute a new one anyway. Thus, for reliable results Lisp programs that call this function should always move point to be inside the window whose display starts at position.
If noforce is non-nil, and 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 position is not used.
This function is like set-window-start, except that when
window is a part of a group of windows (see Window Group),
set-window-group-start sets the start position of the entire
group. This condition holds when the buffer local variable
set-window-group-start-function is set to a function. In this
case, set-window-group-start calls the function with the three
arguments window, position, and noforce, then
returns its result. The arguments position and noforce in
this function have the same meaning as in set-window-start.
This function returns non-nil if position is within the
range of text currently visible on the screen in window. It
returns nil if position is scrolled vertically out of
view. Locations that are partially obscured are not considered
visible unless partially is non-nil. The argument
position defaults to the current position of point in
window; window defaults to the selected window. If
position is t, that means to check either the first
visible position of the last screen line in window, or the
end-of-buffer position, whichever comes first.
This function considers only vertical scrolling. If position is
out of view only because window has been scrolled horizontally,
pos-visible-in-window-p returns non-nil anyway.
See Horizontal Scrolling.
If position is visible, pos-visible-in-window-p returns
t if partially is nil; if partially is
non-nil, and the character following position is fully
visible, it returns a list of the form (x y), where
x and y are the pixel coordinates relative to the top left
corner of the window; otherwise it returns an extended list of the form
(x y rtop rbot rowh vpos),
where rtop and rbot specify the number of off-window pixels
at the top and bottom of the row at position, rowh specifies
the visible height of that row, and vpos specifies the vertical
position (zero-based row number) of that row.
Here is an example:
;; If point is off the screen now, recenter it now.
(or (pos-visible-in-window-p
(point) (selected-window))
(recenter 0))
This function is like pos-visible-in-window-p, except that when
window is a part of a group of windows (see Window Group),
pos-visible-in-window-group-p tests the visibility of pos
in the entire group, not just in the single window. This
condition holds when the buffer local variable
pos-visible-in-window-group-p-function is set to a function.
In this case pos-visible-in-window-group-p calls the function
with the three arguments position, window, and
partially, then returns its result. The arguments
position and partially have the same meaning as in
pos-visible-in-window-p.
This function returns the height of text line line in
window. If line is one of header-line or
mode-line, window-line-height returns information about
the corresponding line of the window. Otherwise, line is a text
line number starting from 0. A negative number counts from the end of
the window. The default for line is the current line in
window; the default for window is the selected window.
If the display is not up to date, window-line-height returns
nil. In that case, pos-visible-in-window-p may be used
to obtain related information.
If there is no line corresponding to the specified line,
window-line-height returns nil. Otherwise, it returns
a list (height vpos ypos offbot),
where height is the height in pixels of the visible part of the
line, vpos and ypos are the vertical position in lines and
pixels of the line relative to the top of the first text line, and
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, ypos is negative.
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 window-point to keep point on the
screen (see Windows and Point).
The basic textual scrolling functions are scroll-up (which
scrolls forward) and 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 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 PageDown on modern keyboards.
Textual scrolling functions (aside from scroll-other-window)
have unpredictable results if the current buffer is not the one
displayed in the selected window. See The 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 auto-window-vscroll to nil
(see Vertical Fractional Scrolling).
This function scrolls forward by count lines in the selected window.
If count is negative, it scrolls backward instead. If
count is nil (or omitted), the distance scrolled is
next-screen-context-lines lines less than the height of the
window’s body.
If the selected window cannot be scrolled any further, this function
signals an error. Otherwise, it returns nil.
This function scrolls backward by count lines in the selected window.
If count is negative, it scrolls forward instead. In other
respects, it behaves the same way as scroll-up does.
This behaves like scroll-up, except that if the selected window
cannot be scrolled any further and the value of the variable
scroll-error-top-bottom is t, it tries to move to the
end of the buffer instead. If point is already there, it signals an
error.
This behaves like scroll-down, except that if the selected
window cannot be scrolled any further and the value of the variable
scroll-error-top-bottom is t, it tries to move to the
beginning of the buffer instead. If point is already there, it
signals an error.
This function scrolls the text in another window upward count
lines. Negative values of count, or nil, are handled
as in scroll-up.
You can specify which buffer to scroll by setting the variable
other-window-scroll-buffer to a buffer. If that buffer isn’t
already displayed, 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
minibuffer-scroll-window. This variable has no effect when any
other window is selected. When it is non-nil and the
minibuffer is selected, it takes precedence over
other-window-scroll-buffer. See Definition of minibuffer-scroll-window.
This function scrolls the text in another window downward count
lines. Negative values of count, or nil, are handled as
in scroll-down. In other respects, it behaves the same way as
scroll-other-window does.
If this variable is non-nil, it tells scroll-other-window
which buffer’s window to scroll.
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.
This variable limits the effective value of scroll-margin to a
fraction of the current window line height. For example, if the
current window has 20 lines and maximum-scroll-margin is 0.1,
then the scroll margins will never be larger than 2 lines, no matter
how big scroll-margin is.
maximum-scroll-margin itself has a maximum value of 0.5, which
allows setting margins large to keep the cursor at the middle line of
the window (or two middle lines if the window has an even number of
lines). If it’s set to a larger value (or any value other than a
float between 0.0 and 0.5) then the default value of 0.25 will be used
instead.
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 n, then redisplay scrolls the text up to
n lines in either direction, if that will bring point back into
proper view. This behavior is called conservative scrolling.
Otherwise, scrolling happens in the usual way, under the control of
other variables such as scroll-up-aggressively and
scroll-down-aggressively.
The default value is zero, which means that conservative scrolling never happens.
The value of this variable should be either nil or a fraction
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 f part of the window
height from the top. The larger f, the more aggressive the
scrolling.
A value of nil is equivalent to .5, since its effect is to center
point. This variable automatically becomes buffer-local when set in any
fashion.
Likewise, for scrolling up. The value, f, specifies how far
point should be placed from the bottom of the window; thus, as with
scroll-down-aggressively, a larger value scrolls more
aggressively.
This variable is an older variant of scroll-conservatively.
The difference is that if its value is n, that permits scrolling
only by precisely n lines, not a smaller number. This feature
does not work with scroll-margin. The default value is zero.
If this option is 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-nil and not 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-nil
scroll-command symbol property.
The value of this variable is the number of lines of continuity to
retain when scrolling by full screens. For example, scroll-up
with an argument of nil scrolls so that this many lines at the
bottom of the window appear instead at the top. The default value is
2.
If this option is nil (the default), scroll-up-command
and scroll-down-command simply signal an error when no more
scrolling is possible.
If the value is 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.
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 count is a non-negative number, that puts the line containing point count lines down from the top of the window. If count is a negative number, then it counts upward from the bottom of the window, so that −1 stands for the last usable line in the window.
If count is nil (or a non-nil list),
recenter puts the line containing point in the middle of the
window. If count is nil and redisplay is
non-nil, this function may redraw the frame, according to the
value of recenter-redisplay. Thus, omitting the second
argument can be used to countermand the effect of
recenter-redisplay being non-nil. Interactive calls
pass non-nil for redisplay.
When recenter is called interactively, count is the raw
prefix argument. Thus, typing C-u as the prefix sets the
count to a non-nil list, while typing C-u 4 sets
count to 4, which positions the current line four lines from the
top.
With an argument of zero, recenter positions the current line at
the top of the window. The command recenter-top-bottom offers
a more convenient way to achieve this.
This function is like recenter, except that when the selected
window is part of a group of windows (see Window Group),
recenter-window-group scrolls the entire group. This condition
holds when the buffer local variable
recenter-window-group-function is set to a function. In this
case, recenter-window-group calls the function with the
argument count, then returns its result. The argument
count has the same meaning as in recenter, but with
respect to the entire window group.
If this variable is non-nil, calling recenter with a
nil count argument and non-nil redisplay
argument redraws the frame. The default value is tty, which
means only redraw the frame if it is a tty frame.
This command, which is the default binding for C-l, acts like
recenter, except if called with no argument. In that case,
successive calls place point according to the cycling order defined
by the variable recenter-positions.
This variable controls how recenter-top-bottom behaves when
called with no argument. The default value is (middle top
bottom), which means that successive calls of
recenter-top-bottom with no argument cycle between placing
point at the middle, top, and bottom of the window.
Vertical fractional scrolling means shifting text in a window up or down by a specified multiple or fraction of a line. Emacs uses it, for example, on images and screen lines which are taller than the window. Each window has a vertical scroll position, which is a number, never less than zero. It specifies how far to raise the contents of the window when displaying them. 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 will be 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.
This function returns the current vertical scroll position of
window. The default for window is the selected window.
If pixels-p is non-nil, the return value is measured in
pixels, rather than in units of the normal line height.
(window-vscroll)
⇒ 0
This function sets window’s vertical scroll position to
lines. If window is nil, the selected window is
used. The argument 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.
(set-window-vscroll (selected-window) 1.2)
⇒ 1.13
If pixels-p is non-nil, lines specifies a number of
pixels. In this case, the return value is lines.
Normally, the vscroll does not take effect on windows that aren’t the
minibuffer-scroll-window or the selected window when the
mini-window is resized (see Minibuffer Windows). This “frozen”
behavior is disabled when the preserve-vscroll-p parameter is
non-nil, which means to set the vscroll as usual.
If this variable is non-nil, the line-move,
scroll-up, and 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.
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 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 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.
If 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.
The default value of auto-hscroll-mode is t; setting
it to current-line activates a variant of automatic horizontal
scrolling whereby only the line showing the cursor is horizontally
scrolled to make point visible, the rest of the window is left either
unscrolled, or at the minimum scroll amount set by scroll-left
and scroll-right, see below.
This function scrolls the selected window count columns to the left (or to the right if count is negative). The default for 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
window-hscroll (below).
Note that text in paragraphs whose base direction is right-to-left
(see Bidirectional Display) moves in the opposite direction: e.g.,
it moves to the right when scroll-left is invoked with a
positive value of count.
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 set-minimum is non-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-nil for
set-minimum.
This function scrolls the selected window count columns to the
right (or to the left if count is negative). The default
for count is the window width, minus 2. Aside from the direction
of scrolling, this works just like scroll-left.
This function returns the total leftward horizontal scrolling of window—the number of columns by which the text in window is scrolled left past the left margin. (In right-to-left paragraphs, the value is the total amount of the rightward scrolling instead.) The default for window is the selected window.
The return value is never negative. It is zero when no horizontal scrolling has been done in window (which is usually the case).
(window-hscroll)
⇒ 0
(scroll-left 5)
⇒ 5
(window-hscroll)
⇒ 5
This function sets horizontal scrolling of window. The value of columns specifies the amount of scrolling, in terms of columns from the left margin (right margin in right-to-left paragraphs). The argument columns should be zero or positive; if not, it is taken as zero. Fractional values of columns are not supported at present.
Note that set-window-hscroll may appear not to work if you test
it by evaluating a call with 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 columns.
(set-window-hscroll (selected-window) 10)
⇒ 10
Here is how you can determine whether a given position position is off the screen due to horizontal scrolling:
(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)))))
This section describes functions that report positions of and within a window. Most of these functions report positions relative to an origin at the native position of the window’s frame (see Frame Geometry). Some functions report positions relative to the origin of the display of the window’s frame. In any case, the origin has the coordinates (0, 0) and X and Y coordinates increase rightward and downward respectively.
For the following functions, 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 the default character specified by the frame’s default font (see Frame Font).
This function returns a list of the edge coordinates of window.
If window is omitted or nil, it defaults to the selected
window.
The return value has the form (left top right
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 of its decorations. 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.
If the optional argument body is nil, this means to
return the edges corresponding to the total size of window.
body non-nil means to return the edges of window’s
body. If body is non-nil, window must specify a
live window.
If the optional argument absolute is nil, this means to
return edges relative to the native position of window’s frame.
absolute non-nil means to return coordinates relative to
the origin (0, 0) of window’s display. On non-graphical systems
this argument has no effect.
If the optional argument pixelwise is nil, this means to
return the coordinates in terms of the default character width and
height of window’s frame (see Frame Font), rounded if
necessary. pixelwise non-nil means to return the
coordinates in pixels. Note that the pixel specified by right and
bottom is immediately outside of these edges. If absolute
is non-nil, pixelwise is implicitly non-nil too.
This function returns the edges of window’s body (see Window Sizes). Calling (window-body-edges window) is equivalent to
calling (window-edges window t), see above.
The following functions can be used to relate a set of frame-relative coordinates to a window:
This function returns the live window at the coordinates x and y given in default character sizes (see Frame Font) relative to the native position of frame (see Frame Geometry).
If there is no window at that position, the return value is nil.
If frame is omitted or nil, it defaults to the selected
frame.
This function checks whether a window window occupies the frame relative coordinates coordinates, and if so, which part of the window that is. window should be a live window.
coordinates should be a cons cell of the form (x
. y), where x and y are given in default character
sizes (see Frame Font) relative to the native position of
window’s frame (see Frame Geometry).
If there is no window at the specified position, the return value is
nil . Otherwise, the return value is one of the following:
(relx . rely)The coordinates are inside window. The numbers relx and rely are the equivalent window-relative coordinates for the specified position, counting from 0 at the top left corner of the window.
mode-lineThe coordinates are in the mode line of window.
header-lineThe coordinates are in the header line of window.
tab-lineThe coordinates are in the tab line of window.
right-dividerThe coordinates are in the divider separating window from a window on the right.
bottom-dividerThe coordinates are in the divider separating window from a window beneath.
vertical-lineThe coordinates are in the vertical line between 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.
left-fringeright-fringeThe coordinates are in the left or right fringe of the window.
left-marginright-marginThe coordinates are in the left or right margin of the window.
nilThe coordinates are not in any part of window.
The function coordinates-in-window-p does not require a frame as
argument because it always uses the frame that window is on.
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.
This function returns a list of pixel coordinates for the edges of
window. Calling (window-pixel-edges window) is equivalent
to calling (window-edges window nil nil t), see above.
This function returns the pixel edges of window’s body. Calling
(window-body-pixel-edges window) is equivalent to calling
(window-edges window t nil t), see above.
The following functions return window positions in pixels, relative to the origin of the display screen rather than that of the frame:
This function returns the pixel coordinates of window relative to
an origin at (0, 0) of the display of window’s frame. Calling
(window-absolute-pixel-edges) is equivalent to calling
(window-edges window nil t t), see above.
This function returns the pixel coordinates of window’s body
relative to an origin at (0, 0) of the display of window’s frame.
Calling (window-absolute-body-pixel-edges window) is equivalent
to calling (window-edges window t t t), see above.
Combined with set-mouse-absolute-pixel-position, this function
can be used to move the mouse pointer to an arbitrary buffer position
visible in some window:
(let ((edges (window-absolute-body-pixel-edges))
(position (pos-visible-in-window-p nil nil t)))
(set-mouse-absolute-pixel-position
(+ (nth 0 edges) (nth 0 position))
(+ (nth 1 edges) (nth 1 position))))
On a graphical terminal this form “warps” the mouse cursor to the upper left corner of the glyph at the selected window’s point. A position calculated this way can be also used to show a tooltip window there.
The following function returns the screen coordinates of a buffer position visible in a window:
If the buffer position position is visible in window window,
this function returns the display coordinates of the upper/left corner
of the glyph at position. The return value is a cons of the X-
and Y-coordinates of that corner, relative to an origin at (0, 0) of
window’s display. It returns nil if position is not
visible in window.
window must be a live window and defaults to the selected
window. position defaults to the value of window-point
of window.
This means that in order to move the mouse pointer to the position of point in the selected window, it’s sufficient to write:
(let ((position (window-absolute-pixel-position))) (set-mouse-absolute-pixel-position (car position) (cdr position)))
The following function returns the largest rectangle that can be inscribed in a window without covering text displayed in that window.
This function calculates the dimensions of the largest empty rectangle that can be inscribed in the specified window’s text area. window must be a live window and defaults to the selected one.
The return value is a triple of the width and the start and end
y-coordinates of the largest rectangle that can be inscribed into the
empty space (space not displaying any text) of the text area of
window. No x-coordinates are returned by this function—any such
rectangle is assumed to end at the right edge of window’s text
area. If no empty space can be found, the return value is nil.
The optional argument count, if non-nil, specifies a
maximum number of rectangles to return. This means that the return
value is a list of triples specifying rectangles with the largest
rectangle first. count can be also a cons cell whose car
specifies the number of rectangles to return and whose CDR, if
non-nil, states that all rectangles returned must be disjoint.
The optional arguments min-width and min-height, if
non-nil, specify the minimum width and height of any rectangle
returned.
The optional argument positions, if non-nil, is a cons cell
whose CAR specifies the uppermost and whose CDR specifies the
lowermost pixel position that must be covered by any rectangle returned.
These positions measure from the start of the text area of window.
The optional argument left, if non-nil, means to return
values suitable for buffers displaying right to left text. In that
case, any rectangle returned is assumed to start at the left edge of
window’s text area.
Note that this function has to retrieve the dimensions of each line of
window’s glyph matrix via window-lines-pixel-dimensions
(see Size of Displayed Text). Hence, this function may also return
nil when the current glyph matrix of window is not
up-to-date.
The following option enables automatically selecting the window under the mouse pointer. This accomplishes a policy similar to that of window managers that give focus to a frame (and thus trigger its subsequent selection) whenever the mouse pointer enters its window-system window (see Input Focus, see Focus Events).
If this variable is non-nil, Emacs will try to automatically
select the window under the mouse pointer. The following values are
meaningful:
This specifies a delay in seconds after which auto-selection triggers. The window under the mouse pointer is selected after the mouse has remained in it for the entire duration of the delay.
A negative number has a similar effect as a positive number, but selects the window under the mouse pointer only after the mouse pointer has remained in it for the entire duration of the absolute value of that number and in addition has stopped moving.
Any other non-nil value means to select a window instantaneously
as soon as the mouse pointer enters it.
In either case, the mouse pointer must enter the text area of a window in order to trigger its selection. Dragging the scroll bar slider or the mode line of a window conceptually should not cause its auto-selection.
Mouse auto-selection selects the minibuffer window only if it is active, and never deselects the active minibuffer window.
Mouse auto-selection can be used to emulate a focus follows mouse policy
for child frames (see Child Frames) which usually are not tracked by
the window manager. This requires setting the value of
focus-follows-mouse (see Input Focus) to a non-nil
value. If the value of focus-follows-mouse is auto-raise,
entering a child frame with the mouse will raise it automatically above
all other child frames of that frame’s parent frame.
A window configuration records the entire layout of one
frame—all windows, their sizes, their decorations, which buffers they
contain, how those buffers are scrolled, and their value of point, It
also includes the value of 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. See Frame Configurations.
This function returns a new object representing frame’s current
window configuration. The default for frame is the selected
frame. The variable window-persistent-parameters specifies
which window parameters (if any) are saved by this function.
See Window Parameters.
This function restores the configuration of windows and buffers as
specified by configuration, for the frame that
configuration was created for, regardless of whether that frame
is selected or not. The argument configuration must be a value
that was previously returned by current-window-configuration
for that frame. Normally the function also selects the frame which is
recorded in the configuration, but if dont-set-frame is
non-nil, it leaves selected the frame which was already
selected at the start of the function.
Normally the function restores the saved minibuffer (if any), but if
dont-set-miniwindow is non-nil, the minibuffer current
at the start of the function (if any) remains in the mini-window.
If the frame from which configuration was saved is dead, all
this function does is to restore the value of the variable
minibuffer-scroll-window and to adjust the value returned by
minibuffer-selected-window. In this case, the function returns
nil. Otherwise, it returns t.
This function consults the variable
window-restore-killed-buffer-windows (see below) when it tries to
restore a window whose buffer was killed after configuration was
recorded.
Here is a way of using this function to get the same effect as
save-window-excursion:
(let ((config (current-window-configuration)))
(unwind-protect
(progn (split-window-below nil)
...)
(set-window-configuration config)))
This macro records the window configuration of the selected frame, executes forms in sequence, then restores the earlier window configuration. The return value is the value of the final form in forms.
Most Lisp code should not use this macro; save-selected-window
is typically sufficient. In particular, this macro cannot reliably
prevent the code in forms from opening new windows, because new
windows might be opened in other frames (see Choosing a Window for Displaying a Buffer), and
save-window-excursion only saves and restores the window
configuration on the current frame.
This function returns t if object is a window configuration.
This function says whether two window configurations have the same
window layout, but ignores the values of point and the saved scrolling
positions—it can return t even if those aspects differ.
This function returns the frame for which the window configuration config was made.
Other primitives to look inside of window configurations would make sense, but are not implemented because we did not need them. See the file winner.el for some more operations on windows configurations.
The objects returned by 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
(set-window-configuration effectively clones the windows of a
frame into the root window of that very frame only).
This function returns the state of window as a Lisp object. The argument window must be a valid window and defaults to the root window of the selected frame.
If the optional argument writable is non-nil, this means to
not use markers for sampling positions like window-point or
window-start. This argument should be non-nil when the
state will be written to disk and read back in another session.
Together, writable and the variable
window-persistent-parameters specify which window parameters are
saved by this function. The default is to save the clone-of
parameter if writable is nil. See Window Parameters.
Bind window-state-normalize-buffer-name to non-nil to
normalize buffer names under uniquify management by removing its
prefixes and suffixes. This helps restore window buffers across Emacs
sessions. See Uniquify in The GNU Emacs Manual.
The value returned by window-state-get can be used in the same
session to clone a window (see below). 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.
This function puts the window state state into window. The
argument state should be the state of a window returned by an
earlier invocation of window-state-get, see above. The optional
argument window can be either a live window or an internal window
(see Windows and Frames). If window is not a live window, it
is replaced by a new live window created on the same frame before
putting state into it. If window is nil, it puts the
window state into a new window.
This function assigns all window parameters that have been stored in
state. By default, this is the clone-of parameter provided
state was obtained from an invocation of window-state-get
with the argument writable nil. See Window Parameters.
This function consults the variable
window-restore-killed-buffer-windows (see below) when it tries to
restore a window whose buffer was killed after state was recorded.
If the optional argument ignore is non-nil, it means to ignore
minimum window sizes and fixed-size restrictions. If ignore
is safe, this means windows can get as small as one line
and/or two columns.
In the context of window states, the clone of a window is a window that has the same decorations and contents as the window whose state was used to produce it, but is actually represented by another window object. Hence it does not have the same identity as the original window. Operating on the original or the clone of a window does not affect the other in any way.
Note that while set-window-configuration always restores the
identity of the windows it puts back into their frame,
window-state-put never does that. Note also that while
window-state-get clones existing windows, these clones are not
yet valid windows. They become valid only after window-state-put
has put them into a live frame.
By default, set-window-configuration and window-state-put
may delete a window from the restored configuration or state when they
find out that its buffer was killed since the corresponding
configuration or state has been recorded. The variable described next
can be used to fine-tune that behavior.
This variable specifies how set-window-configuration and
window-state-put shall handle a window whose buffer has been
killed since the corresponding configuration or state was recorded. Any
such window may be live—in which case it shows some other buffer—or
dead at the time one of these functions is called. Usually,
set-window-configuration leaves the window alone if it is live
while window-state-put deletes it.
The following values can be used to override the default behavior for
dead windows in the case of set-window-configuration and for dead
and live windows in the case of window-state-put.
tThis value means to unconditionally restore the window and show some other buffer in it.
deleteThis means to unconditionally try to delete the window.
dedicatedThis means to try to delete the window if and only if it is dedicated to its buffer.
nilThis is the default, and it means that set-window-configuration
will try to delete the window if and only if it is dedicated to its
buffer, and window-state-put will unconditionally try to delete
it.
This means to restore the window and show some other buffer in it, like
if the value is t, and also add an entry for that window to a
list that will be later passed as the second argument to that function.
If a window cannot be deleted (typically, because it is the last window
on its frame), set-window-configuration and
window-state-put will show another buffer in it.
If the value of this variable is a function, that function should take
three arguments. The first argument specifies the frame whose windows
have been restored. The third argument is either the symbol
configuration if the windows are restored by
set-window-configuration, or the symbol state if the
windows are restored by window-state-put.
The second argument specifies a list of entries for all windows
whose previous buffers have been found dead at the time
set-window-configuration or window-state-put tried to
restore them (minibuffer windows are excluded). This means that the
function may also delete windows which were found live by
set-window-configuration.
Each entry in the list that is passed as the second argument to the
function is itself a list of six values: the window whose buffer was
found dead, the dead buffer or its name, the positions of window start
(see The Window Start and End Positions) and window point (see Windows and Point)
of the buffer in that window, the dedicated state of the window as
previously reported by window-dedicated-p and a flag that is
t if the window has been found to be alive by
set-window-configuration and nil otherwise.
The functions window-state-get and window-state-put also
allow exchanging the contents of two live windows. The following
function does precisely that:
This command swaps the states of the two live windows window-1 and window-2. window-1 must specify a live window and defaults to the selected one. window-2 must specify a live window and defaults to the window following window-1 in the cyclic ordering of windows, excluding minibuffer windows and including live windows on all visible frames.
Optional argument size non-nil means to try swapping the
sizes of window-1 and window-2 as well. A value of
height means to swap heights only, a value of width
means to swap widths only, while t means to swap both widths
and heights, if possible. Frames are not resized by this function.
This section describes the window parameters that can be used to associate additional information with windows.
This function returns window’s value for parameter. The
default for window is the selected window. If window has no
setting for parameter, this function returns nil.
This function returns all parameters of window and their values.
The default for window is the selected window. The return value
is either nil, or an association list whose elements have the form
(parameter . value).
This function sets window’s value of parameter to value and returns value. The default for window is the selected window.
By default, the functions that save and restore window configurations
or the states of windows (see Window Configurations) do not care
about window parameters. This means that when you change the value of
a parameter within the body of a save-window-excursion, the
previous value is not restored when that macro exits. It also means
that when you restore via window-state-put a window state saved
earlier by window-state-get, all cloned windows have their
parameters reset to nil. The following variable allows you to
override the standard behavior:
This variable is an alist specifying which parameters get saved by
current-window-configuration and window-state-get, and
subsequently restored by set-window-configuration and
window-state-put. See Window Configurations.
The CAR of each entry of this alist is a symbol specifying the parameter. The CDR should be one of the following:
nilThis value means the parameter is saved neither by
window-state-get nor by current-window-configuration.
tThis value specifies that the parameter is saved by
current-window-configuration and (provided its writable
argument is nil) by window-state-get.
writableThis means that the parameter is saved unconditionally by both
current-window-configuration and window-state-get. This
value should not be used for parameters whose values do not have a read
syntax. Otherwise, invoking window-state-put in another session
may fail with an invalid-read-syntax error.
Some functions (notably delete-window,
delete-other-windows and split-window), may behave
specially when the window specified by their window argument has
a parameter whose name is equal to the function’s name. You can
override such special behavior by binding the following variable to a
non-nil value:
If this variable is non-nil, some standard functions do not
process window parameters. The functions currently affected by this are
split-window, delete-window, delete-other-windows,
and other-window.
An application can bind this variable to a non-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.
The following parameters are currently used by the window management code:
delete-window ¶This parameter affects the execution of delete-window
(see Deleting Windows).
delete-other-windows ¶This parameter affects the execution of delete-other-windows
(see Deleting Windows).
no-delete-other-windows ¶This parameter marks the window as not deletable by
delete-other-windows (see Deleting Windows).
split-window ¶This parameter affects the execution of split-window
(see Splitting Windows).
other-window ¶This parameter affects the execution of other-window
(see Cyclic Ordering of Windows).
no-other-window ¶This parameter marks the window as not selectable by other-window
(see Cyclic Ordering of Windows). It is by default t for tooltip
windows (see Basic Concepts of Emacs Windows). Use window-no-other-p
(see Cyclic Ordering of Windows) to check whether it applies to a
specific window.
clone-of ¶This parameter specifies the window that this one has been cloned from.
It is persistent by default and as such gets saved by
window-state-get and installed by window-state-put
(see Window Configurations).
window-preserved-size ¶This parameter specifies a buffer, a direction where nil means
vertical and t horizontal, and a size in pixels. If this window
displays the specified buffer and its size in the indicated direction
equals the size specified by this parameter, then Emacs will try to
preserve the size of this window in the indicated direction. This
parameter is installed and updated by the function
window-preserve-size (see Preserving Window Sizes).
quit-restorequit-restore-prev ¶These parameters are installed by the buffer display functions
(see Choosing a Window for Displaying a Buffer) and consulted by quit-restore-window
(see Quitting Windows). They are lists of four elements, see the
description of quit-restore-window in Quitting Windows for
details.
window-side ¶window-slotThese parameters are used internally for implementing side windows (see Side Windows).
window-atom ¶This parameter is used internally for implementing atomic windows, see Atomic Windows.
mode-line-format ¶This parameter replaces the value of the buffer-local variable
mode-line-format (see Mode Line Basics) of this window’s
buffer whenever this window is displayed. The symbol none means
to suppress display of a mode line for this window. Display and
contents of the mode line on other windows showing this buffer are not
affected.
header-line-format ¶This parameter replaces the value of the buffer-local variable
header-line-format (see Mode Line Basics) of this window’s
buffer whenever this window is displayed. The symbol none means
to suppress display of a header line for this window. Display and
contents of the header line on other windows showing this buffer are not
affected.
tab-line-format ¶This parameter replaces the value of the buffer-local variable
tab-line-format (see Mode Line Basics) of this window’s
buffer whenever this window is displayed. The symbol none means
to suppress display of a tab line for this window. Display and
contents of the tab line on other windows showing this buffer are not
affected.
min-margins ¶The value of this parameter is a cons cell whose CAR and
CDR, if non-nil, specify the minimum values (in columns)
for the left and right margin of this window (see Displaying in the Margins).
When present, Emacs will use these values instead of the actual margin
widths for determining whether a window can be split or shrunk
horizontally.
Emacs never auto-adjusts the margins of any window after splitting or
resizing it. It is the sole responsibility of any application setting
this parameter to adjust the margins of this window as well as those of
any new window that inherits this window’s margins due to a split.
Both window-configuration-change-hook and
window-size-change-functions (see Hooks for Window Scrolling and Changes) should be
employed for this purpose.
This parameter was introduced in Emacs version 25.1 to support applications that use large margins to center buffer text within a window and should be used, with due care, exclusively by those applications. It might be replaced by an improved solution in future versions of Emacs.
This section describes how Lisp programs can take action after a window has been scrolled or other window modifications occurred. We first consider the case where a window shows a different part of its buffer.
This variable holds a list of functions that Emacs should call before redisplaying a window with scrolling. Displaying a different buffer in a window and making a new window also call 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. At the time of the call, the display-start position of the argument window is already set to its new value, and the buffer to be displayed in the window is set as the current buffer.
These functions must take care when using window-end
(see The Window Start and End Positions); if you need an up-to-date value, you
must use the update argument to ensure you get it.
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.
In addition, you can use 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. See Other Font Lock Variables.
The remainder of this section covers six hooks that are called
during redisplay provided a significant, non-scrolling change of a
window has been detected. For simplicity, these hooks and the
functions they call will be collectively referred to as window
change functions. As any hook, these hooks can be set either
globally or buffer-locally via the local argument of
add-hook (see Setting Hooks) when the hook is installed.
The first of these hooks is run after a window buffer change is detected, which means that a window was created, deleted or assigned another buffer.
This variable specifies functions called during redisplay when window buffers have changed. The value should be a list of functions that take one argument.
Functions specified buffer-locally are called for each window showing the corresponding buffer if and only if that window has been added or changed its buffer since the last redisplay. Note that functions may be run twice for such a window: Once for the buffer shown in the window at the time of the last redisplay (provided that buffer is still live) and once for the buffer currently shown in the window. In either case the window is passed as argument and the respective buffer is made temporarily current.
If you are using the buffer-local version of this hook, you may want to discern the case where the buffer was removed from a window from the case where the buffer is now shown in that window. If window denotes the window argument passed to a function on this hook, then to detect the case where the buffer was removed from window use the idiom
(eq (window-old-buffer window) (current-buffer))
while to detect whether the buffer is now shown in window use
(eq (window-buffer window) (current-buffer))
instead.
Functions specified by the default value are called for a frame if at least one window on that frame has been added, deleted or assigned another buffer since the last time window change functions were run. In this case the frame is passed as argument.
The second of these hooks is run when a window size change has been detected which means that a window was created, assigned another buffer, or changed its total size or that of its text area.
This variable specifies functions called during redisplay when a window size change occurred. The value should be a list of functions that take one argument.
Functions specified buffer-locally are called for any window showing the corresponding buffer if that window has been added or assigned another buffer or changed its total or body size since the last time window change functions were run. In this case the window is passed as argument and the respective buffer is temporarily made current.
Functions specified by the default value are called for a frame if at least one window on that frame has been added or assigned another buffer or changed its total or body size since the last time window change functions were run. In this case the frame is passed as argument.
The third of these hooks is run when a window selection change has selected another window since the last redisplay.
This variable specifies functions called during redisplay when the selected window or a frame’s selected window has changed. The value should be a list of functions that take one argument.
Functions specified buffer-locally are called for any window showing the corresponding buffer if that window has been selected or deselected (among all windows or among all windows on its frame) since the last time window change functions were run. In this case the window is passed as argument and the respective buffer is temporarily made current.
Functions specified by the default value are called for a frame if that frame has been selected or deselected or the frame’s selected window has changed since the last time window change functions were run. In this case the frame is passed as argument.
The fourth of these hooks is run when a window state change has been detected, which means that at least one of the three preceding window changes has occurred.
This variable specifies functions called during redisplay when a window buffer or size change occurred or the selected window or a frame’s selected window has changed. The value should be a list of functions that take one argument.
Functions specified buffer-locally are called for any window showing the corresponding buffer if that window has been added or assigned another buffer, changed its total or body size or has been selected or deselected (among all windows or among all windows on its frame) since the last time window change functions were run. In this case the window is passed as argument and the respective buffer is temporarily made current.
Functions specified by the default value are called for a frame if at least one window on that frame has been added, deleted or assigned another buffer, changed its total or body size or that frame has been selected or deselected or the frame’s selected window has changed since the last time window change functions were run. In this case the frame is passed as argument.
Functions specified by the default value are also run for a frame when that frame’s window state change flag (see below) has been set since last redisplay.
The fifth of these hooks is run when a window configuration change has been detected which means that either the buffer or the size of a window changed. It differs from the four preceding hooks in the way it is run.
This variable specifies functions called during redisplay when either the buffer or the size of a window has changed. The value should be a list of functions that take no argument.
Functions specified buffer-locally are called for any window showing the corresponding buffer if at least one window on that frame has been added, deleted or assigned another buffer or changed its total or body size since the last time window change functions were run. Each call is performed with the window showing the buffer temporarily selected and its buffer current.
Functions specified by the default value are called for each frame if at least one window on that frame has been added, deleted or assigned another buffer or changed its total or body size since the last time window change functions were run. Each call is performed with the frame temporarily selected and the selected window’s buffer current.
Finally, Emacs runs a normal hook that generalizes the behavior of
window-state-change-functions.
The default value of this variable specifies functions called during redisplay when a window state change has been detected or the window state change flag has been set on at least one frame. The value should be a list of functions that take no argument.
Applications should put a function on this hook only if they want to
react to changes that happened on (or have been signaled for) two or
more frames since last redisplay. In every other case, putting the
function on window-state-change-functions should be preferred.
Window change functions are called during redisplay for each frame as
follows: First, any buffer-local window buffer change function, window
size change function, selected window change and window state change
functions are called in this order. Next, the default values for
these functions are called in the same order. Then any buffer-local
window configuration change functions are called followed by functions
specified by the default value of those functions. Finally, functions
on window-state-change-hook are run.
Window change functions are run for a specific frame only if a corresponding change was registered for that frame earlier. Such changes include the creation or deletion of a window or the assignment of another buffer or size to a window. Note that even when such a change has been registered, this does not mean that any of the hooks described above is run. If, for example, a change was registered within the scope of a window excursion (see Window Configurations), this will trigger a call of window change functions only if that excursion still persists at the time change functions are run. If it is exited earlier, hooks will be run only if registered by a change outside the scope of that excursion.
The window state change flag of a frame, if set, will cause
the default values of window-state-change-functions (for that
frame) and window-state-change-hook to be run during next
redisplay regardless of whether a window state change actually
occurred for that frame or not. After running any functions on these
hooks, the flag is reset for each frame. Applications can set that
flag and inspect its value using the following functions.
This function sets frame’s window state change flag if arg
is non-nil and resets it otherwise. frame must be a live
frame and defaults to the selected one.
This functions returns t if frame’s window state change
flag is set and nil otherwise. frame must be a live
frame and defaults to the selected one.
While window change functions are run, the functions described next can be called to get more insight into what has changed for a specific window or frame since the last redisplay. All these functions take a live window as single, optional argument, defaulting to the selected window.
This function returns the buffer shown in window at the last time
window change functions were run for window’s frame. If it
returns nil, window is either an internal window or has
been created after that. If it returns t, window was not
shown at that time but has been restored from a previously saved window
configuration afterwards. Otherwise, the return value is the buffer
shown by window at that time. As a special case, if window
has been deleted, this function returns the last buffer window had
shown at that time. window can be any window and defaults to the
selected one.
This function returns the total pixel width of window the last time window change functions found window live on its frame. It is zero if window was created after that.
This function returns the total pixel height of window the last time window change functions found window live on its frame. It is zero if window was created after that.
This function returns the pixel width of window’s text area the last time window change functions found window live on its frame. It is zero if window was created after that.
This function returns the pixel height of window’s text area the last time window change functions found window live on its frame. It is zero if window was created after that.
In order to find out which window or frame was selected the last time window change functions were run, the following functions can be used:
This function returns the selected window of frame at the last
time window change functions were run. If omitted or nil
frame defaults to the selected frame.
This function returns the selected window at the last time window change functions were run.
This function returns the selected frame at the last time window change functions were run.
Note that window change functions provide no information about which windows have been deleted since the last time they were run. If necessary, applications should remember any window showing a specific buffer in a local variable of that buffer and update it in a function run by the default values of any of the hooks that are run when a window buffer change was detected.
The following caveats should be considered when adding a function to window change functions:
window-state-change-hook.
save-window-excursion, with-selected-window
or with-current-buffer can be used when running window change
functions.
window-configuration-change-hook it does not
save or restore the selected window or frame or the current buffer
either.