From: Xue Fuqiao Date: Thu, 27 Feb 2014 12:58:23 +0000 (+0800) Subject: Document some (perhaps incomplete) pixelwise window operations. X-Git-Tag: emacs-24.3.90~357^2~8 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=de37b1f449795b9c61c3e8212b698e1ec7482223;p=emacs.git Document some (perhaps incomplete) pixelwise window operations. * doc/lispref/windows.texi (Window Sizes, Resizing Windows): Document some pixelwise window operations. --- de37b1f449795b9c61c3e8212b698e1ec7482223 diff --cc doc/lispref/ChangeLog index 0e64feab6f9,8d473033bd2..0d0f787eb27 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@@ -1,7 -1,5 +1,10 @@@ 2014-02-27 Xue Fuqiao ++ * windows.texi (Window Sizes, Resizing Windows): Document some ++ pixelwise window operations. ++ + * text.texi (Margins): Fix the description of RET and `C-j'. + * frames.texi (Multiple Terminals): Document `display-monitor-attributes-list' and `display-monitor-attributes'. (Display Feature Testing): Add some notes about multi-monitor. diff --cc doc/lispref/windows.texi index f19a08c85e7,f19a08c85e7..08d82f57a93 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@@ -427,26 -427,26 +427,55 @@@ height of a frame is not the same as th a frame may also contain an echo area, menu bar, and tool bar (@pxref{Size and Position}). --@defun window-total-height &optional window ++@defun window-total-height &optional window round This function returns the total height, in lines, of the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. If @var{window} is an internal window, the return value is the total height occupied by its descendant windows. ++ ++If @var{window}'s pixel height is not an integral multiple of its ++frame's character height, the number of lines occupied by @var{window} ++is rounded internally. This is done in a way such that, if ++@var{window} is a parent window, the sum of the total heights of all ++its children internally equals the total height of @var{window}. ++ ++If the optional argument @var{round} is @code{ceiling}, this function ++will return the smallest integer larger than @var{window}'s pixel ++height divided by the character height of @var{window}'s frame; if it ++is @code{floor}, return the largest integer smaller than ++@var{window}'s pixel height divided by the character height of ++@var{window}'s frame. Any other value of @var{round} means to return ++the internal total height of @var{window}. @end defun --@defun window-total-width &optional window ++@defun window-total-width &optional window round This function returns the total width, in columns, of the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. If @var{window} is internal, the return value is the total width occupied by its descendant windows. ++ ++If @var{window}'s pixel width is not an integral multiple of its ++frame's character width, the number of lines occupied by @var{window} ++is rounded internally. This is done in a way such that, if ++@var{window} is a parent window, the sum of the total widths of all ++its children internally equals the total width of @var{window}. ++ ++If the optional argument @var{round} is @code{ceiling}, this function ++will return the smallest integer larger than @var{window}'s pixel ++width divided by the character width of @var{window}'s frame; if it is ++@code{floor}, return the largest integer smaller than @var{window}'s ++pixel width divided by the character width of @var{window}'s frame. ++Any other value of @var{round} means to return the internal total ++width of @var{window}. @end defun --@defun window-total-size &optional window horizontal ++@defun window-total-size &optional window horizontal round This function returns either the total height or width of the window @var{window}. If @var{horizontal} is omitted or @code{nil}, this is equivalent to calling @code{window-total-height} for @var{window}; otherwise it is equivalent to calling @code{window-total-width} for --@var{window}. ++@var{window}. The optional argument @code{ROUND} is handled as for ++@code{window-total-height} and @code{window-total-width}. @end defun @cindex full-width window @@@ -479,7 -479,7 +508,7 @@@ which does not include the mode or head @dfn{body width} is the width of the text area, which does not include the scroll bar, fringes, or margins. --@defun window-body-height &optional window ++@defun window-body-height &optional window pixelwise This function returns the body height, in lines, of the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. @@@ -489,7 -489,7 +518,7 @@@ that counts as a whole line; to exclud use @code{window-text-height}, below. @end defun --@defun window-body-width &optional window ++@defun window-body-width &optional window pixelwise This function returns the body width, in columns, of the window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. @@@ -571,7 -571,7 +600,7 @@@ changed except by resizing the frame (@ arguments. Resizing an internal window causes its child windows to be resized to fit the same space. --@defun window-resizable window delta &optional horizontal ignore ++@defun window-resizable window delta &optional horizontal ignore pixelwise This function returns @var{delta} if the size of @var{window} can be changed vertically by @var{delta} lines. If the optional argument @var{horizontal} is non-@code{nil}, it instead returns @var{delta} if @@@ -596,9 -596,9 +625,12 @@@ Instead, it considers the minimum-heigh of a header (if any), a mode line, plus a text area one line tall; and a minimum-width window as one consisting of fringes, margins, and scroll bar (if any), plus a text area two columns wide. ++ ++If the optional argument @code{pixelwise} is non-@code{nil}, ++@var{delta} will be interpreted as pixels. @end defun --@defun window-resize window delta &optional horizontal ignore ++@defun window-resize window delta &optional horizontal ignore pixelwise This function resizes @var{window} by @var{delta} increments. If @var{horizontal} is @code{nil}, it changes the height by @var{delta} lines; otherwise, it changes the width by @var{delta} columns. A @@@ -611,6 -611,6 +643,9 @@@ the window cannot be resized as demande 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}, ++@var{delta} will be interpreted as pixels. ++ The choice of which window edges this function alters depends on the values of the option @code{window-combination-resize} and the combination limits of the involved windows; in some cases, it may alter @@@ -623,12 -623,12 +658,15 @@@ bottom or right edge of a window, use t @c shrink-window, and shrink-window-horizontally are documented in the @c Emacs manual. They are not preferred for calling from Lisp. --@defun adjust-window-trailing-edge window delta &optional horizontal ++@defun adjust-window-trailing-edge window delta &optional horizontal pixelwise This function moves @var{window}'s bottom edge by @var{delta} lines. If optional argument @var{horizontal} is non-@code{nil}, it instead moves the right edge by @var{delta} columns. If @var{window} is @code{nil}, it defaults to the selected window. ++If the optional argument @code{pixelwise} is non-@code{nil}, ++@var{delta} will be interpreted as pixels. ++ A positive @var{delta} moves the edge downwards or to the right; a negative @var{delta} moves it upwards or to the left. If the edge cannot be moved as far as specified by @var{delta}, this function @@@ -639,6 -639,6 +677,21 @@@ moved. If this is not possible for som window is fixed-size), it may resize other windows. @end defun ++@cindex pixelwise, resizing windows ++@defopt window-resize-pixelwise ++If the value of this user option is non-@code{nil}, window resizing ++operations will be pixelwise. This currently affects the following ++functions: @code{split-window}, @code{maximize-window}, ++@code{minimize-window}, @code{fit-window-to-buffer} and ++@code{fit-frame-to-buffer}, and all functions that symmetrically ++resize a parent window. ++ ++Note that when a frame's pixel size is not a multiple of the frame's ++character size, at least one window may get resized pixelwise even if ++this option is nil. The default value of this user option is ++@code{nil}. ++@end defopt ++ The following commands resize windows in more specific ways. When called interactively, they act on the selected window.