28.2 Splitting Windows

The functions described here are the primitives used to split a window into two windows. Two higher level functions sometimes split a window, but not always: pop-to-buffer and display-buffer (see section 28.7 Displaying Buffers in Windows).

The functions described here do not accept a buffer as an argument. The two "halves" of the split window initially display the same buffer previously visible in the window that was split.

Command: split-window &optional window size horizontal

This function splits window into two windows. The original window window remains the selected window, but occupies only part of its former screen area. The rest is occupied by a newly created window which is returned as the value of this function.

If horizontal is non-nil, then window splits into two side by side windows. The original window window keeps the leftmost size columns, and gives the rest of the columns to the new window. Otherwise, it splits into windows one above the other, and window keeps the upper size lines and gives the rest of the lines to the new window. The original window is therefore the left-hand or upper of the two, and the new window is the right-hand or lower.

If window is omitted or nil, then the selected window is split. If size is omitted or nil, then window is divided evenly into two parts. (If there is an odd line, it is allocated to the new window.) When split-window is called interactively, all its arguments are nil.

The following example starts with one window on a screen that is 50 lines high by 80 columns wide; then the window is split.

(setq w (selected-window)) => #<window 8 on windows.texi> (window-edges) ; Edges in order: => (0 0 80 50) ; left--top--right--bottom ;; Returns window created (setq w2 (split-window w 15)) => #<window 28 on windows.texi> (window-edges w2) => (0 15 80 50) ; Bottom window; ; top is line 15 (window-edges w) => (0 0 80 15) ; Top window

The screen looks like this:

__________ | | line 0 | w | |__________| | | line 15 | w2 | |__________| line 50 column 0 column 80

Next, the top window is split horizontally:

(setq w3 (split-window w 35 t)) => #<window 32 on windows.texi> (window-edges w3) => (35 0 80 15) ; Left edge at column 35 (window-edges w) => (0 0 35 15) ; Right edge at column 35 (window-edges w2) => (0 15 80 50) ; Bottom window unchanged

Now, the screen looks like this:

column 35 __________ | | | line 0 | w | w3 | |___|______| | | line 15 | w2 | |__________| line 50 column 0 column 80

Normally, Emacs indicates the border between two side-by-side windows with a scroll bar (see section Scroll Bars) or `|' characters. The display table can specify alternative border characters; see 38.17 Display Tables.

Command: split-window-vertically &optional size

This function splits the selected window into two windows, one above the other, leaving the upper of the two windows selected, with size lines. (If size is negative, then the lower of the two windows gets - size lines and the upper window gets the rest, but the upper window is still the one selected.)

Command: split-window-horizontally &optional size

This function splits the selected window into two windows side-by-side, leaving the selected window with size columns.

This function is basically an interface to split-window. You could define a simplified version of the function like this:

(defun split-window-horizontally (&optional arg) "Split selected window into two windows, side by side..." (interactive "P") (let ((size (and arg (prefix-numeric-value arg)))) (and size (< size 0) (setq size (+ (window-width) size))) (split-window nil size t)))

Function: one-window-p &optional no-mini all-frames

This function returns non-nil if there is only one window. The argument no-mini, if non-nil, means don't count the minibuffer even if it is active; otherwise, the minibuffer window is included, if active, in the total number of windows, which is compared against one.

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

nil

Count the windows in the selected frame, plus the minibuffer used by that frame even if it lies in some other frame.

t

Count all windows in all existing frames.

visible

Count all windows in all visible frames.

0

Count all windows in all visible or iconified frames.

anything else

Count precisely the windows in the selected frame, and no others.