elisp: Splitting Windows
27.6 Splitting Windows
======================
This section describes functions for creating a new window by
“splitting” an existing one.
-- Function: split-window &optional window size side pixelwise
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’ (
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 area 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 areas like a mode line or a scroll bar. The function
‘window-min-size’ (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.
The optional fourth argument PIXELWISE, if non-‘nil’, means to
interpret SIZE in units of pixels, instead of lines and columns.
If WINDOW is a live window, the new window inherits various
properties from it, including margins and scroll bars. If WINDOW
is an internal window, the new window inherits the properties of
the window selected within 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.
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.
-- Command: split-window-right &optional size
This function splits the selected window into two side-by-side
windows, putting the selected window on the left. If SIZE is
positive, the left window gets SIZE columns; if SIZE is negative,
the right window gets −SIZE columns.
-- Command: split-window-below &optional size
This function splits the selected window into two windows, one
above the other, leaving the upper window selected. If SIZE is
positive, the upper window gets SIZE lines; if SIZE is negative,
the lower window gets −SIZE lines.
-- User Option: split-window-keep-point
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.
Info Catalog
elisp: Preserving Window Sizes
elisp: Windows
elisp: Deleting Windows