GNU Emacs Lisp Reference Manual

25.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 Displaying Buffers).

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-edges)          ; Edges in order:
     => (0 0 80 50)     ;   left--top--right--bottom
;; Returns window created
(setq w2 (split-window w 15))   
     => #
(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-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 Scroll Bars) or `|' characters. The display table can specify alternative border characters; see Display Tables.

Command: split-window-vertically size

This function splits the selected window into two windows, one above the other, leaving the selected window with size lines.

This function is simply an interface to split-windows. Here is the complete function definition for it:

(defun split-window-vertically (&optional arg)
  "Split current window into two windows, one above the other."
  (interactive "P")
  (split-window nil (and arg (prefix-numeric-value arg))))

Command: split-window-horizontally size

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

This function is simply an interface to split-windows. Here is the complete definition for split-window-horizontally (except for part of the documentation string):

(defun split-window-horizontally (&optional arg)
  "Split selected window into two windows, side by side..."
  (interactive "P")
  (split-window nil (and arg (prefix-numeric-value arg)) 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.