Commit 276bd75c authored by Martin Rudalics's avatar Martin Rudalics
Browse files

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.
parent ad013ba6
2014-12-19 Martin Rudalics <rudalics@gmx.at>
* 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 <eliz@gnu.org>
* display.texi (Low-Level Font): Document font-info and query-font.
......
......@@ -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
......
......@@ -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}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment