From f2c5082b9302fa6eb6be3f0b502528a8d61cc813 Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Fri, 7 Mar 2014 10:53:23 +0100 Subject: [PATCH] Add/update elisp texinfo for window-min-size and split-window. * windows.texi (Window Sizes): Describe `window-min-size'. (Splitting Windows): Update description of `split-window'. --- doc/lispref/ChangeLog | 5 ++++ doc/lispref/windows.texi | 60 ++++++++++++++++++++++++++++++++++------ 2 files changed, 57 insertions(+), 8 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index cac66f6e9e1..114d0197308 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2014-03-07 Martin Rudalics + + * windows.texi (Window Sizes): Describe `window-min-size'. + (Splitting Windows): Update description of `split-window'. + 2014-03-06 Martin Rudalics * frames.texi (Size and Position): Rewrite entries for diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 3fa4117e52c..0020c8bc967 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -656,6 +656,36 @@ determine that, use the function @code{window-resizable}. @xref{Resizing Windows}. @end defvar +The following function tells how small a specific window can get taking +into account the sizes of its areas and the values of +@code{window-min-height}, @code{window-min-width} and +@code{window-size-fixed}. + +@defun window-min-size &optional window horizontal ignore pixelwise +This function returns the minimum size of @var{window}. @var{window} +must be a valid window and defaults to the selected one. The optional +argument @var{horizontal} non-@code{nil} means to return the minimum +number of columns of @var{window}; otherwise return the minimum number +of @var{window}'s lines. + +The return value makes sure that all components of @var{window} remain +fully visible if @var{window}'s size were actually set to it. With +@var{horizontal} @code{nil} it includes the mode and header line and the +bottom divider. With @var{horizontal} non-@code{nil} it includes the +fringes, a scroll bar, and a right divider, if present. It does not, +however, include the space reserved for the margins. + +The optional argument @var{ignore}, if non-@code{nil}, means ignore +restrictions imposed by fixed size windows, @code{window-min-height} or +@code{window-min-width} settings. If @var{ignore} equals @code{safe}, +live windows may get as small as @code{window-safe-min-height} lines and +@code{window-safe-min-width} columns. If @var{ignore} is a window, +ignore restrictions for that window only. Any other non-@code{nil} +value means ignore all of the above restrictions for all windows. + +The optional argument @var{pixelwise} non-@code{nil} means to return the +minimum size of @var{window} counted in pixels. +@end defun @node Resizing Windows @section Resizing Windows @@ -718,7 +748,7 @@ the window cannot be resized as demanded, an error is signaled. The optional argument @var{ignore} has the same meaning as for the function @code{window-resizable} above. -If the optional argument @code{pixelwise} is non-@code{nil}, +If the optional argument @var{pixelwise} is non-@code{nil}, @var{delta} will be interpreted as pixels. The choice of which window edges this function alters depends on the @@ -879,7 +909,7 @@ window. This section describes functions for creating a new window by @dfn{splitting} an existing one. -@defun split-window &optional window size side +@defun split-window &optional window size side pixelwise This function creates a new live window next to the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. That window is ``split'', and reduced in @@ -894,15 +924,25 @@ value of @var{side}). If @var{size} is a negative number, the new window is given @minus{}@var{size} lines (or columns). If @var{size} is @code{nil}, this function obeys the variables -@code{window-min-height} and @code{window-min-width}. @xref{Change -Window,,Deleting and Rearranging Windows, emacs, The GNU Emacs -Manual}. Thus, it signals an error if splitting would result in -making a window smaller than those variables specify. However, a +@code{window-min-height} and @code{window-min-width} (@pxref{Window +Sizes}). Thus, it signals an error if splitting would result in making +a window smaller than those variables specify. However, a non-@code{nil} value for @var{size} causes those variables to be -ignored; in that case, the smallest allowable window is considered to -be one that has space for a text area one line tall and/or two columns +ignored; in that case, the smallest allowable window is considered to be +one that has space for a text area one line tall and/or two columns wide. +Hence, if @var{size} is specified, it's the caller's responsibility to +check whether the emanating windows are large enough to encompass all +areas like a mode line or a scroll bar. The function +@code{window-min-size} (@pxref{Window Sizes}) can be used to determine +the minimum requirements of @var{window} in this regard. Since the new +window usually ``inherits'' areas like the mode line or the scroll bar +from @var{window}, that function is also a good guess for the minimum +size of the new window. The caller should specify a smaller size only +if it correspondingly removes an inherited area before the next +redisplay. + The optional third argument @var{side} determines the position of the new window relative to @var{window}. If it is @code{nil} or @code{below}, the new window is placed below @var{window}. If it is @@ -914,6 +954,10 @@ the right of @var{window}. If @var{side} is @code{left}, the new window is placed on the left of @var{window}. In both these cases, @var{size} specifies a total window width, in columns. +The optional fourth argument @var{pixelwise}, if non-@code{nil}, means +to interpret @var{size} in units of pixels, instead of lines and +columns. + If @var{window} is a live window, the new window inherits various properties from it, including margins and scroll bars. If @var{window} is an internal window, the new window inherits the -- 2.39.2