Function: split-window-sensibly

split-window-sensibly is a byte-compiled function defined in window.el.gz.

Signature

(split-window-sensibly &optional WINDOW)

Documentation

Split WINDOW in a way suitable for display-buffer.

The variable split-window-preferred-direction prescribes an order of directions in which Emacs should try to split WINDOW. If that order mandates starting with a vertical split, and split-height-threshold specifies an integer that is at least as large a WINDOW's height, split WINDOW into two windows one below the other and return the lower one. If that order mandates starting with a horizontal split, and split-width-threshold specifies an integer that is at least as large as WINDOW's width, split WINDOW into two windows side by side and return the one on the right.

In either case, if the first attempt to split WINDOW fails, try to split the window in the other direction in the same manner as described above. If that attempt fails too, and WINDOW is the only window on its frame, try splitting WINDOW into two windows, one below the other, disregarding the value of split-height-threshold and return the window on the bottom.

By default display-buffer routines call this function to split the largest or least recently used window. To change the default customize the option split-window-preferred-function.

You can enforce this function to not split WINDOW horizontally, by setting (or binding) the variable split-width-threshold to nil. If, in addition, you set split-height-threshold to zero, chances increase that this function does split WINDOW vertically.

In order to not split WINDOW vertically, set (or bind) the variable split-height-threshold to nil. Additionally, you can set split-width-threshold to zero to make a horizontal split more likely to occur.

Have a look at the function window-splittable-p if you want to know how split-window-sensibly determines whether WINDOW can be split.

View in manual

Probably introduced at or before Emacs version 23.1.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defun split-window-sensibly (&optional window)
  "Split WINDOW in a way suitable for `display-buffer'.
The variable `split-window-preferred-direction' prescribes an order of
directions in which Emacs should try to split WINDOW.  If that order
mandates starting with a vertical split, and `split-height-threshold'
specifies an integer that is at least as large a WINDOW's height, split
WINDOW into two windows one below the other and return the lower one.
If that order mandates starting with a horizontal split, and
`split-width-threshold' specifies an integer that is at least as large
as WINDOW's width, split WINDOW into two windows side by side and return
the one on the right.

In either case, if the first attempt to split WINDOW fails, try to split
the window in the other direction in the same manner as described above.
If that attempt fails too, and WINDOW is the only window on its frame,
try splitting WINDOW into two windows, one below the other, disregarding
the value of `split-height-threshold' and return the window on the
bottom.

By default `display-buffer' routines call this function to split
the largest or least recently used window.  To change the default
customize the option `split-window-preferred-function'.

You can enforce this function to not split WINDOW horizontally,
by setting (or binding) the variable `split-width-threshold' to
nil.  If, in addition, you set `split-height-threshold' to zero,
chances increase that this function does split WINDOW vertically.

In order to not split WINDOW vertically, set (or bind) the
variable `split-height-threshold' to nil.  Additionally, you can
set `split-width-threshold' to zero to make a horizontal split
more likely to occur.

Have a look at the function `window-splittable-p' if you want to
know how `split-window-sensibly' determines whether WINDOW can be
split."
  (let ((window (or window (selected-window))))
    (or (if (or
             (eql split-window-preferred-direction 'horizontal)
             (and (eql split-window-preferred-direction 'longest)
                  (> (frame-width) (frame-height))))
            (or (window--try-horizontal-split window)
                (window--try-vertical-split window))
          (or (window--try-vertical-split window)
              (window--try-horizontal-split window)))
	(and
         ;; If WINDOW is the only usable window on its frame (it is
         ;; the only one or, not being the only one, all the other
         ;; ones are dedicated) and is not the minibuffer window, try
         ;; to split it vertically disregarding the value of
         ;; `split-height-threshold'.
         (let ((frame (window-frame window)))
           (or
            (eq window (frame-root-window frame))
            (catch 'done
              (walk-window-tree (lambda (w)
                                  (unless (or (eq w window)
                                              (window-dedicated-p w))
                                    (throw 'done nil)))
                                frame nil 'nomini)
              t)))
	 (not (window-minibuffer-p window))
         (let ((split-height-threshold 0))
           (window--try-vertical-split window))))))