[Emacs-diffs] trunk r116580: Document some (perhaps incomplete) pixelwise window operations.

[Xue Fuqiao]

------------------------------------------------------------
revno: 116580 [merge]
revision-id: address@hidden
parent: address@hidden
parent: address@hidden
committer: Xue Fuqiao <address@hidden>
branch nick: trunk
timestamp: Thu 2014-02-27 20:58:23 +0800
message:
  Document some (perhaps incomplete) pixelwise window operations.
  
  * doc/lispref/windows.texi (Window Sizes, Resizing Windows):
  Document some pixelwise window operations.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/windows.texi       
windows.texi-20091113204419-o5vbwnq5f7feedwu-6224

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-02-27 11:59:35 +0000
+++ b/doc/lispref/ChangeLog     2014-02-27 12:56:45 +0000
@@ -1,5 +1,8 @@
 2014-02-27  Xue Fuqiao  <address@hidden>
 
+       * 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

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2014-02-21 13:33:57 +0000
+++ b/doc/lispref/windows.texi  2014-02-27 12:56:45 +0000
@@ -427,26 +427,55 @@
 a frame may also contain an echo area, menu bar, and tool bar
 (@pxref{Size and Position}).
 
address@hidden window-total-height &optional window
address@hidden 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
address@hidden 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
address@hidden's pixel height divided by the character height of
address@hidden's frame.  Any other value of @var{round} means to return
+the internal total height of @var{window}.
 @end defun
 
address@hidden window-total-width &optional window
address@hidden 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
address@hidden 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
address@hidden, 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
 
address@hidden window-total-size &optional window horizontal
address@hidden 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
address@hidden
address@hidden  The optional argument @code{ROUND} is handled as for
address@hidden and @code{window-total-width}.
 @end defun
 
 @cindex full-width window
@@ -479,7 +508,7 @@
 @dfn{body width} is the width of the text area, which does not include
 the scroll bar, fringes, or margins.
 
address@hidden window-body-height &optional window
address@hidden 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 +518,7 @@
 use @code{window-text-height}, below.
 @end defun
 
address@hidden window-body-width &optional window
address@hidden 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 +600,7 @@
 arguments.  Resizing an internal window causes its child windows to be
 resized to fit the same space.
 
address@hidden window-resizable window delta &optional horizontal ignore
address@hidden 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 address@hidden, it instead returns @var{delta} if
@@ -596,9 +625,12 @@
 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 address@hidden,
address@hidden will be interpreted as pixels.
 @end defun
 
address@hidden window-resize window delta &optional horizontal ignore
address@hidden 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 +643,9 @@
 The optional argument @var{ignore} has the same meaning as for the
 function @code{window-resizable} above.
 
+If the optional argument @code{pixelwise} is address@hidden,
address@hidden 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 +658,15 @@
 @c shrink-window, and shrink-window-horizontally are documented in the
 @c Emacs manual.  They are not preferred for calling from Lisp.
 
address@hidden adjust-window-trailing-edge window delta &optional horizontal
address@hidden 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 address@hidden, 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 address@hidden,
address@hidden 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 +677,21 @@
 window is fixed-size), it may resize other windows.
 @end defun
 
address@hidden pixelwise, resizing windows
address@hidden window-resize-pixelwise
+If the value of this user option is address@hidden, window resizing
+operations will be pixelwise.  This currently affects the following
+functions: @code{split-window}, @code{maximize-window},
address@hidden, @code{fit-window-to-buffer} and
address@hidden, 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
address@hidden
address@hidden defopt
+
   The following commands resize windows in more specific ways.  When
 called interactively, they act on the selected window.