Function: split-window-below

split-window-below is an interactive and byte-compiled function defined in window.el.gz.

Signature

(split-window-below &optional SIZE WINDOW-TO-SPLIT)

Documentation

Split WINDOW-TO-SPLIT into two windows, one above the other.

WINDOW-TO-SPLIT defaults to the selected window if omitted or nil. The newly created window will be below WINDOW-TO-SPLIT and will show the same buffer as WINDOW-TO-SPLIT, if it is a live window, else the buffer shown in the WINDOW-TO-SPLIT's frame's selected window. Return the new window.

If optional argument SIZE is omitted or nil, both windows get the same height, or close to it. If SIZE is positive, the upper
(selected) window gets SIZE lines. If SIZE is negative, the
lower (new) window gets -SIZE lines. Interactively, SIZE is the prefix numeric argument.

If the variable split-window-keep-point is non-nil, both windows get the same value of point as the WINDOW-TO-SPLIT. Otherwise, the window starts are chosen so as to minimize the amount of redisplay; this is convenient on slow terminals.

View in manual

Probably introduced at or before Emacs version 24.1.

Key Bindings

Aliases

split-window-vertically

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun split-window-below (&optional size window-to-split)
  "Split WINDOW-TO-SPLIT into two windows, one above the other.
WINDOW-TO-SPLIT defaults to the selected window if omitted or nil.
The newly created window will be below WINDOW-TO-SPLIT and will show
the same buffer as WINDOW-TO-SPLIT, if it is a live window, else the
buffer shown in the WINDOW-TO-SPLIT's frame's selected window.
Return the new window.

If optional argument SIZE is omitted or nil, both windows get the
same height, or close to it.  If SIZE is positive, the upper
\(selected) window gets SIZE lines.  If SIZE is negative, the
lower (new) window gets -SIZE lines.  Interactively, SIZE is
the prefix numeric argument.

If the variable `split-window-keep-point' is non-nil, both
windows get the same value of point as the WINDOW-TO-SPLIT.
Otherwise, the window starts are chosen so as to minimize the
amount of redisplay; this is convenient on slow terminals."
  (interactive `(,(when current-prefix-arg
                    (prefix-numeric-value current-prefix-arg))
                 ,(selected-window)))
  (let ((old-point (window-point))
        moved-by-window-height moved new-window bottom)
    (when (and size (< size 0) (< (- size) window-min-height))
      ;; `split-window' would not signal an error here.
      (error "Size of new window too small"))
    (setq new-window (split-window window-to-split size))
    (when (and (null split-window-keep-point)
               (or (null window-to-split)
                   (eq window-to-split (selected-window))))
      (with-current-buffer (window-buffer window-to-split)
	;; Use `save-excursion' around vertical movements below
	;; (Bug#10971).  Note: When WINDOW-TO-SPLIT's buffer has a
	;; header line, up to two lines of the buffer may not show up
	;; in the resulting configuration.
	(save-excursion
	  (goto-char (window-start))
	  (setq moved (vertical-motion (window-height)))
	  (set-window-start new-window (point))
	  (when (> (point) (window-point new-window))
	    (set-window-point new-window (point)))
	  (when (= moved (window-height))
	    (setq moved-by-window-height t)
	    (vertical-motion -1))
	  (setq bottom (point)))
	(and moved-by-window-height
	     (<= bottom (point))
	     (set-window-point window-to-split (1- bottom)))
	(and moved-by-window-height
	     (<= (window-start new-window) old-point)
	     (set-window-point new-window old-point)
	     (select-window new-window))))
    ;; Always copy quit-restore parameter in interactive use.
    (let ((quit-restore (window-parameter window-to-split 'quit-restore)))
      (when quit-restore
	(set-window-parameter new-window 'quit-restore quit-restore)))
    new-window))