38.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.

Function: one-window-p &optional nomini which-frames which-devices

This function returns non-nil if there is only one window. The argument nomini, 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 remaining arguments controls which set of windows are counted, as with next-window.

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 frame 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 frame 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, SXEmacs 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 &optional 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-window. 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 &optional 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-window. 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))