Variable: split-window-preferred-function

split-window-preferred-function is a customizable variable defined in window.el.gz.

Value

split-window-sensibly

Documentation

Function called by display-buffer routines to split a window.

This function is called with a window as single argument and is supposed to split that window and return the new window. If the window can (or shall) not be split, it is supposed to return nil. The default is to call the function split-window-sensibly which tries to split the window in a way which seems most suitable. You can customize the options split-height-threshold and/or split-width-threshold in order to have split-window-sensibly prefer either vertical or horizontal splitting.

If you set this to any other function, bear in mind that the display-buffer routines may call this function two times. The argument of the first call is the largest window on its frame. If that call fails to return a live window, the function is called again with the least recently used window as argument. If that call fails too, display-buffer will use an existing window to display its buffer.

The window selected at the time display-buffer was invoked is still selected when this function is called. Hence you can compare the window argument with the value of selected-window if you intend to split the selected window instead or if you do not want to split the selected window.

This variable was added, or its default value changed, in Emacs 23.1.

Probably introduced at or before Emacs version 23.1.

Source Code

;; Defined in /usr/src/emacs/lisp/window.el.gz
(defcustom split-window-preferred-function 'split-window-sensibly
  "Function called by `display-buffer' routines to split a window.
This function is called with a window as single argument and is
supposed to split that window and return the new window.  If the
window can (or shall) not be split, it is supposed to return nil.
The default is to call the function `split-window-sensibly' which
tries to split the window in a way which seems most suitable.
You can customize the options `split-height-threshold' and/or
`split-width-threshold' in order to have `split-window-sensibly'
prefer either vertical or horizontal splitting.

If you set this to any other function, bear in mind that the
`display-buffer' routines may call this function two times.  The
argument of the first call is the largest window on its frame.
If that call fails to return a live window, the function is
called again with the least recently used window as argument.  If
that call fails too, `display-buffer' will use an existing window
to display its buffer.

The window selected at the time `display-buffer' was invoked is
still selected when this function is called.  Hence you can
compare the window argument with the value of `selected-window'
if you intend to split the selected window instead or if you do
not want to split the selected window."
  :type 'function
  :version "23.1"
  :group 'windows)