From 276bd75ca56d29b6ddbd2aca3659c83118b3f548 Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Fri, 19 Dec 2014 11:27:43 +0100 Subject: [PATCH] Describe window size preserving options. * windows.texi (Resizing Windows): Describe new argument of `fit-window-to-buffer'. Move description of `window-size-fixed' to new section below. (Preserving Window Sizes): New section describing `window-size-fixed' and `window-preserve-size'. (Display Action Functions): Describe `preserve-size' alist entry. (Window Parameters): Describe `preserved-size' parameter. --- doc/lispref/ChangeLog | 11 ++++ doc/lispref/elisp.texi | 1 + doc/lispref/windows.texi | 132 ++++++++++++++++++++++++++++++++++----- 3 files changed, 127 insertions(+), 17 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 7424ab07cdf..5b3750697c8 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,14 @@ +2014-12-19 Martin Rudalics + + * windows.texi (Resizing Windows): Describe new argument of + `fit-window-to-buffer'. Move description of `window-size-fixed' + to new section below. + (Preserving Window Sizes): New section describing + `window-size-fixed' and `window-preserve-size'. + (Display Action Functions): Describe `preserve-size' alist + entry. + (Window Parameters): Describe `preserved-size' parameter. + 2014-12-18 Eli Zaretskii * display.texi (Low-Level Font): Document font-info and query-font. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index fa665da34a4..f6e7729e646 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1006,6 +1006,7 @@ Windows * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Splitting one window into two windows. * Deleting Windows:: Deleting a window gives its space to other windows. * Recombining Windows:: Preserving the frame layout when splitting and diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 5060fef804f..c54eb900da1 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -16,6 +16,7 @@ is displayed in windows. * Windows and Frames:: Relating windows to the frame they appear on. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. +* Preserving Window Sizes:: Preserving the size of windows. * Splitting Windows:: Creating a new window. * Deleting Windows:: Removing a window from its frame. * Recombining Windows:: Preserving the frame layout when splitting and @@ -657,22 +658,6 @@ window. Its value has to accommodate two text columns as well as margins, fringes, a scroll bar and a right divider, if present. @end defopt -@defvar window-size-fixed -If this buffer-local variable is non-@code{nil}, the size of any -window displaying the buffer cannot normally be changed. Deleting a -window or changing the frame's size may still change its size, if -there is no choice. - -If the value is @code{height}, then only the window's height is fixed; -if the value is @code{width}, then only the window's width is fixed. -Any other non-@code{nil} value fixes both the width and the height. - -If this variable is @code{nil}, this does not necessarily mean that any -window showing the buffer can be resized in the desired direction. To -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 @@ -817,7 +802,7 @@ option is @code{nil}. The default value is @code{nil}. The following commands resize windows in more specific ways. When called interactively, they act on the selected window. -@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width +@deffn Command fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size This command adjusts the height or width of @var{window} to fit the text in it. It returns non-@code{nil} if it was able to resize @var{window}, and @code{nil} otherwise. If @var{window} is omitted or @code{nil}, it @@ -845,6 +830,10 @@ defaults to the width of @var{window}'s frame. The optional argument specified in columns and include fringes, margins and scrollbars, if any. +The optional argument @var{preserve-size}, if non-@code{nil}, will +install a parameter to preserve the size of @var{window} during future +resize operations (@pxref{Preserving Window Sizes}). + If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, this function will try to resize the frame of @var{window} to fit its contents by calling @code{fit-frame-to-buffer} (@pxref{Size and @@ -1078,6 +1067,99 @@ point was previously on. Note that this only affects function. @end defopt + +@node Preserving Window Sizes +@section Preserving Window Sizes +@cindex preserving window sizes + +A window can get resized explicitly by using one of the functions from +the preceding section or implicitly, for example, when resizing an +adjacent window, when splitting or deleting a window (@pxref{Splitting +Windows}, @pxref{Deleting Windows}) or when resizing the window's frame +(@pxref{Size and Position}). + + It is possible to avoid implicit resizing of a specific window when +there are one or more other resizable windows on the same frame. For +this purpose, Emacs must be advised to @dfn{preserve} the size of that +window. There are two basic ways to do that. + +@defvar window-size-fixed +If this buffer-local variable is non-@code{nil}, the size of any window +displaying the buffer cannot normally be changed. Deleting a window or +changing the frame's size may still change the window's size, if there +is no choice. + +If the value is @code{height}, then only the window's height is fixed; +if the value is @code{width}, then only the window's width is fixed. +Any other non-@code{nil} value fixes both the width and the height. + +If this variable is @code{nil}, this does not necessarily mean that any +window showing the buffer can be resized in the desired direction. To +determine that, use the function @code{window-resizable}. +@xref{Resizing Windows}. +@end defvar + +Often @code{window-size-fixed} is overly aggressive because it inhibits +any attempt to explicitly resize or split an affected window as well. +This may even happen after the window has been resized implicitly, for +example, when deleting an adjacent window or resizing the window's +frame. The following function tries hard to never disallow resizing +such a window explicitly: + +@defun window-preserve-size &optional window horizontal preserve +This function (un-)marks the height of window @var{window} as preserved +for future resize operations. @var{window} must be a live window and +defaults to the selected one. If the optional argument @var{horizontal} +is non-@code{nil}, it (un-)marks the width of @var{window} as preserved. + +If the optional argument @var{preserve} is @code{t}, this means to +preserve the current height/width of @var{window}'s body. The +height/width of @var{window} will change only if Emacs has no better +choice. Resizing a window whose height/width is preserved by this +function never throws an error. + +If @var{preserve} is @code{nil}, this means to stop preserving the +height/width of @var{window}, lifting any respective restraint induced +by a previous call of this function for @var{window}. Calling +@code{enlarge-window}, @code{shrink-window} or +@code{fit-window-to-buffer} with @var{window} as argument may also +remove the respective restraint. +@end defun + +@code{window-preserve-size} is currently invoked by the following +functions: + +@table @code +@item fit-window-to-buffer +If the optional argument @var{preserve-size} of that function +(@pxref{Resizing Windows}) is non-@code{nil}, the size established by +that function is preserved. + +@item display-buffer +If the @var{alist} argument of that function (@pxref{Choosing Window}) +contains a @code{preserve-size} entry, the size of the window produced +by that function is preserved. +@end table + + @code{window-preserve-size} installs a window parameter (@pxref{Window +Parameters}) called @code{preserved-size} which is consulted by the +window resizing functions. This parameter will not prevent resizing the +window when the window shows another buffer than the one when +@code{window-preserve-size} was invoked or if its size has changed since +then. + +The following function can be used to check whether the height of a +particular window is preserved: + +@defun window-preserved-size &optional window horizontal +This function returns the preserved height of window @var{window} in +pixels. @var{window} must be a live window and defaults to the selected +one. If the optional argument @var{horizontal} is non-@code{nil}, it +returns the preserved width of @var{window}. It returns @code{nil} if +the size of @var{window} is not preserved. +@end defun + + @node Deleting Windows @section Deleting Windows @cindex deleting windows @@ -2233,6 +2315,13 @@ argument: the new window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize +If @var{alist} contains a @code{preserve-size} entry, Emacs will try to +preserve the size of the new window during future resize operations +(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a +cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width +of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve +the height of the window. + This function can fail if no window splitting can be performed for some reason (e.g., if the selected frame has an @code{unsplittable} frame parameter; @pxref{Buffer Parameters}). @@ -3900,6 +3989,15 @@ This parameter specifies the window that this one has been cloned from. It is installed by @code{window-state-get} (@pxref{Window Configurations}). +@item @code{preserved-size} +This parameter specifies a buffer, a direction where @code{nil} means +vertical and @code{t} horizontal, and a size in pixels. If this window +displays the specified buffer and its size in the indicated direction +equals the size specified by this parameter, then Emacs will try to +preserve the size of this window in the indicated direction. This +parameter is installed and updated by the function +@code{window-preserve-size} (@pxref{Preserving Window Sizes}). + @item @code{quit-restore} This parameter is installed by the buffer display functions (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} -- 2.39.2