From 43c59a3dca02f712c5e69c3d4be56d2353eb967b Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 18 Oct 2008 11:22:08 +0000 Subject: [PATCH] (Displaying Buffers): Minor wording fix. (Choosing Window): `split-height-threshold' can now be nil. Document `split-width-threshold'. `pop-up-frames' can have the value `graphic-only'. --- doc/lispref/ChangeLog | 7 ++++++ doc/lispref/windows.texi | 52 ++++++++++++++++++++++++++++++---------- etc/NEWS | 5 ++++ 3 files changed, 52 insertions(+), 12 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 5891f611050..cc74a973792 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2008-10-18 Eli Zaretskii + + * windows.texi (Displaying Buffers): Minor wording fix. + (Choosing Window): `split-height-threshold' can now be nil. + Document `split-width-threshold'. `pop-up-frames' can have the + value `graphic-only'. + 2008-10-17 Eli Zaretskii * os.texi (Startup Summary): Document `before-init-time' and diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 6cc5d03206f..09cfff227d4 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -794,7 +794,7 @@ See the preceding section for @ifnottex @xref{Buffers and Windows}, for @end ifnottex -low-level functions that give you more precise control. All of these +low-level primitives that give you more precise control. All of these functions work by calling @code{set-window-buffer}. Do not use the functions in this section in order to make a buffer @@ -951,6 +951,16 @@ Precisely how @code{display-buffer} finds or creates a window depends on the variables described below. @end deffn +@defun split-window-preferred-function window +This variable specifies how to split a window. Its value, if +non-@code{nil}, should be a function of one argument, which is a +window. If this variable specifies a function, @code{display-buffer} +will call it with one or more candidate windows when it looks for a +window to split. If the argument @var{window} fits, the function is +expected to split it and return a new window. If the function returns +@code{nil}, then @var{window} will not be split. +@end defun + @defopt display-buffer-reuse-frames If this variable is non-@code{nil}, @code{display-buffer} searches existing frames for a window displaying the buffer. If the buffer is @@ -964,16 +974,31 @@ variables, described below. @defopt pop-up-windows This variable controls whether @code{display-buffer} makes new windows. If it is non-@code{nil} and there is only one window, then that window -is split. If it is @code{nil}, then @code{display-buffer} does not -split the single window, but uses it whole. +is split vertically. If it is @code{nil}, then @code{display-buffer} +does not split the single window, but uses it whole. @end defopt @defopt split-height-threshold -This variable determines when @code{display-buffer} may split a window, -if there are multiple windows. @code{display-buffer} always splits the -largest window if it has at least this many lines. If the largest -window is not this tall, it is split only if it is the sole window and -@code{pop-up-windows} is non-@code{nil}. +This variable determines when @code{display-buffer} may split a window +vertically, if there are multiple windows. If the value is a number, +@code{display-buffer} splits the largest window if it has at least +this many lines. If the largest window is not this tall, or if the +value of this variable is @code{nil}, @code{display-buffer} tries to +split some window horizontally, subject to restrictions of +@code{split-width-threshold} (see below). If splitting horizontally +is impossible, @code{display-buffer} will split a window vertically +only if it's the only window on its frame and not the minibuffer +window, and only if @code{pop-up-windows} is non-@code{nil}. +Otherwise, @code{display-buffer} uses one of the existing windows. +@end defopt + +@defopt split-width-threshold +This variable determines when @code{display-buffer} may split a window +horizontally. If the value is a number, @code{display-buffer} may +split a window if it has at least this many columns. If the value of +this variable is @code{nil}, @code{display-buffer} will not split any +windows horizontally. (It still might split some window vertically, +though, see above.) @end defopt @defopt even-window-heights @@ -989,10 +1014,13 @@ will be left alone. @defopt pop-up-frames This variable controls whether @code{display-buffer} makes new frames. If it is non-@code{nil}, @code{display-buffer} looks for an existing -window already displaying the desired buffer, on any visible frame. If -it finds one, it returns that window. Otherwise it makes a new frame. -The variables @code{pop-up-windows} and @code{split-height-threshold} do -not matter if @code{pop-up-frames} is non-@code{nil}. +window already displaying the desired buffer, on any visible frame. +If it finds one, it returns that window. Otherwise it makes a new +frame, unless the variable's value is @code{graphic-only} and the +selected frame is not on a graphic display. The variables +@code{pop-up-windows}, @code{split-height-threshold}, and +@code{split-width-threshold} do not matter if @code{pop-up-frames} is +non-@code{nil}. If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either splits a window or reuses one. diff --git a/etc/NEWS b/etc/NEWS index 58c4388fba2..b2e73354061 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1221,16 +1221,21 @@ Emacs initialization. ** Changes affecting display-buffer ++++ *** New value nil for split-height-threshold inhibits vertical splitting unless there's no other window. ++++ *** New option split-width-threshold controls horizontal splitting. ++++ *** A window can be split horizontally even when it's not full-width. ++++ *** New option split-window-preferred-function can be set to a function to override the default splitting mechanism of display-buffer. ++++ *** If pop-up-frames has the value `graphic-only', display-buffer only makes a separate frame on graphic displays. -- 2.39.5