[Emacs-diffs] master 276bd75: Describe window size preserving options.

[Martin Rudalics]

branch: master
commit 276bd75ca56d29b6ddbd2aca3659c83118b3f548
Author: Martin Rudalics <address@hidden>
Commit: Martin Rudalics <address@hidden>

    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 7424ab0..5b37506 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,14 @@
+2014-12-19  Martin Rudalics  <address@hidden>
+
+       * 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  <address@hidden>
 
        * display.texi (Low-Level Font): Document font-info and query-font.
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index fa665da..f6e7729 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 5060fef..c54eb90 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
 
address@hidden window-size-fixed
-If this buffer-local variable is address@hidden, 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 address@hidden 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}.
address@hidden Windows}.
address@hidden 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.
 
address@hidden Command fit-window-to-buffer &optional window max-height 
min-height max-width min-width
address@hidden 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 address@hidden 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 address@hidden, 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 address@hidden,
 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
 
+
address@hidden Preserving Window Sizes
address@hidden Preserving Window Sizes
address@hidden 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.
+
address@hidden window-size-fixed
+If this buffer-local variable is address@hidden, 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 address@hidden 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}.
address@hidden Windows}.
address@hidden 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:
+
address@hidden 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 address@hidden, 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
address@hidden, @code{shrink-window} or
address@hidden with @var{window} as argument may also
+remove the respective restraint.
address@hidden defun
+
address@hidden is currently invoked by the following
+functions:
+
address@hidden @code
address@hidden fit-window-to-buffer
+If the optional argument @var{preserve-size} of that function
+(@pxref{Resizing Windows}) is address@hidden, the size established by
+that function is preserved.
+
address@hidden 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.
address@hidden 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
address@hidden 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:
+
address@hidden 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 address@hidden, it
+returns the preserved width of @var{window}.  It returns @code{nil} if
+the size of @var{window} is not preserved.
address@hidden 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 address@hidden, means to preserve the width
+of the window and whose @sc{cdr}, if address@hidden, 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}).
 
address@hidden @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
address@hidden (@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}