[Emacs-diffs] trunk r116709: Update docs for window dividers and `window-text-pixel-size'.

[Martin Rudalics]

------------------------------------------------------------
revno: 116709
revision-id: address@hidden
parent: address@hidden
committer: martin rudalics <address@hidden>
branch nick: trunk
timestamp: Sun 2014-03-09 12:36:51 +0100
message:
  Update docs for window dividers and `window-text-pixel-size'.
  
  * xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
  * elisp.texi (Top): Rename section "Width" to "Size of Displayed
  Text".
  * text.texi (Primitive Indent):
  * strings.texi (String Basics):
  * sequences.texi (Sequence Functions): Update references
  accordingly.
  * display.texi (Size of Displayed Text): Rename section from
  "Width".  Add description for `window-text-pixel-size'.
  (Window Dividers): Reword description of window dividers.
  * frames.texi (Layout Parameters): Improve description of window
  divider parameters.
  * windows.texi (Window Sizes): Add descriptions of
  `window-mode-line-height' and `window-header-line-height'.
  (Coordinates and Windows): Mention window dividers.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/display.texi       
display.texi-20091113204419-o5vbwnq5f7feedwu-6172
  doc/lispref/elisp.texi         elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
  doc/lispref/frames.texi        
frames.texi-20091113204419-o5vbwnq5f7feedwu-6180
  doc/lispref/sequences.texi     
sequences.texi-20091113204419-o5vbwnq5f7feedwu-6209
  doc/lispref/strings.texi       
strings.texi-20091113204419-o5vbwnq5f7feedwu-6212
  doc/lispref/text.texi          text.texi-20091113204419-o5vbwnq5f7feedwu-6215
  doc/lispref/windows.texi       
windows.texi-20091113204419-o5vbwnq5f7feedwu-6224
  src/ChangeLog                  changelog-20091113204419-o5vbwnq5f7feedwu-1438
  src/xdisp.c                    xdisp.c-20091113204419-o5vbwnq5f7feedwu-240

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-03-07 15:11:12 +0000
+++ b/doc/lispref/ChangeLog     2014-03-09 11:36:51 +0000
@@ -1,3 +1,20 @@
+2014-03-09  Martin Rudalics  <address@hidden>
+
+       * elisp.texi (Top): Rename section "Width" to "Size of Displayed
+       Text".
+       * text.texi (Primitive Indent):
+       * strings.texi (String Basics):
+       * sequences.texi (Sequence Functions): Update references
+       accordingly.
+       * display.texi (Size of Displayed Text): Rename section from
+       "Width".  Add description for `window-text-pixel-size'.
+       (Window Dividers): Reword description of window dividers.
+       * frames.texi (Layout Parameters): Improve description of window
+       divider parameters.
+       * windows.texi (Window Sizes): Add descriptions of
+       `window-mode-line-height' and `window-header-line-height'.
+       (Coordinates and Windows): Mention window dividers.
+
 2014-03-07  Martin Rudalics  <address@hidden>
 
        * buffers.texi (The Buffer List): Rename node to Buffer List.

=== modified file 'doc/lispref/display.texi'
--- a/doc/lispref/display.texi  2014-03-07 19:12:31 +0000
+++ b/doc/lispref/display.texi  2014-03-09 11:36:51 +0000
@@ -18,7 +18,7 @@
 * Selective Display::   Hiding part of the buffer text (the old way).
 * Temporary Displays::  Displays that go away automatically.
 * Overlays::            Use overlays to highlight parts of the buffer.
-* Width::               How wide a character or string is on the screen.
+* Size of Displayed Text::  How large displayed text is.
 * Line Height::         Controlling the height of lines.
 * Faces::               A face defines a graphics style for text characters:
                           font, colors, etc.
@@ -1765,8 +1765,8 @@
     (point)))
 @end smallexample
 
address@hidden Width
address@hidden Width
address@hidden Size of Displayed Text
address@hidden Size of Displayed Text
 
 Since not all characters have the same width, these functions let you
 check the width of a character.  @xref{Primitive Indent}, and
@@ -1823,6 +1823,54 @@
 @end example
 @end defun
 
+The following function returns the size in pixels of text as if it were
+displayed in a given window.  This function is used by
address@hidden (@pxref{Resizing Windows}) and
address@hidden (@pxref{Size and Position}) to make a window
+exactly as large as the text it contains.
+
address@hidden window-text-pixel-size &optional window from to x-limit y-limit 
mode-and-header-line
+This function returns the size of the text of @var{window}'s buffer in
+pixels.  @var{window} must be a live window and defaults to the selected
+one.  The return value is a cons of the maximum pixel-width of any text
+line and the maximum pixel-height of all text lines.
+
+The optional argument @var{from}, if address@hidden, specifies the first
+text position to consider and defaults to the minimum accessible
+position of the buffer.  If @var{from} is @code{t}, it uses the minimum
+accessible position that is not a newline character.  The optional
+argument @var{to}, if address@hidden, specifies the last text position
+to consider and defaults to the maximum accessible position of the
+buffer.  If @var{to} is @code{t}, it uses the maximum accessible
+position that is not a newline character.
+
+The optional argument @var{x-limit}, if address@hidden, specifies the
+maximum pixel-width that can be returned.  @var{x-limit} @code{nil} or
+omitted, means to use the pixel-width of @var{window}'s body
+(@pxref{Window Sizes}); this is useful when the caller does not intend
+to change the width of @var{window}.  Otherwise, the caller should
+specify here the maximum width @var{window}'s body may assume.  Text
+whose x-coordinate is beyond @var{x-limit} is ignored.  Since
+calculating the width of long lines can take some time, it's always a
+good idea to make this argument as small as needed; in particular, if
+the buffer might contain long lines that will be truncated anyway.
+
+The optional argument @var{y-limit}, if address@hidden, specifies the
+maximum pixel-height that can be returned.  Text lines whose
+y-coordinate is beyond @var{y-limit} are ignored.  Since calculating the
+pixel-height of a large buffer can take some time, it makes sense to
+specify this argument; in particular, if the caller does not know the
+size of the buffer.
+
+The optional argument @var{mode-and-header-line} @code{nil} or omitted
+means to not include the height of the mode- or header-line of
address@hidden in the return value.  If it is either the symbol
address@hidden or @code{header-line}, include only the height of that
+line, if present, in the return value.  If it is @code{t}, include the
+height of both, if present, in the return value.
address@hidden defun
+
+
 @node Line Height
 @section Line Height
 @cindex line height
@@ -3904,28 +3952,28 @@
 @cindex bottom dividers
 
 Window dividers are bars drawn between a frame's windows.  A ``right''
-divider is drawn between a window and its sibling(s) on the right.  Its
-width is specified by the frame parameter @code{right-divider-width}.  A
-``bottom'' divider is drawn between a window and its sibling(s) on the
-bottom or the echo area.  Its width is specified by the frame parameter
address@hidden  In either case, specifying a width of zero
-means to not draw such dividers.  @xref{Layout Parameters}.
+divider is drawn between a window and any adjacent windows on the right.
+Its width (thickness) is specified by the frame parameter
address@hidden  A ``bottom'' divider is drawn between a
+window and adjacent windows on the bottom or the echo area.  Its width
+is specified by the frame parameter @code{bottom-divider-width}.  In
+either case, specifying a width of zero means to not draw such dividers.
address@hidden Parameters}.
 
    Technically, a right divider ``belongs'' to the window on its left,
-which means that its width is part of the total width of that window.  A
-bottom divider ``belongs'' to the window above it, which means that its
-height is part of the total height of that window.  @xref{Window Sizes}.
-When a window has both, a right and a bottom divider, the bottom divider
-``prevails''.  This means that the width of the bottom divider equals
-the total width of the window while the height of the right divider
-equals the total height of the window minus the height of the bottom
-divider.
+which means that its width contributes to the total width of that
+window.  A bottom divider ``belongs'' to the window above it, which
+means that its width contributes to the total height of that window.
address@hidden Sizes}.  When a window has both, a right and a bottom
+divider, the bottom divider ``prevails''.  This means that a bottom
+divider is drawn over the full total width of its window while the right
+divider ends above the bottom divider.
 
    Dividers can be dragged with the mouse and are therefore useful for
 adjusting the sizes of adjacent windows with the mouse.  They also serve
-to set windows visually apart from their siblings when no scroll bars or
-mode lines are present.  The following three faces allow to customize
-the appearance of dividers:
+to visually set apart adjacent windows when no scroll bars or mode lines
+are present.  The following three faces allow to customize the
+appearance of dividers:
 
 @table @code
 @item window-divider
@@ -3944,6 +3992,23 @@
 same value used for the @code{window-divider} face.
 @end table
 
+You can get the sizes of the dividers of a specific window with the
+following two functions.
+
address@hidden window-right-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s right divider.
address@hidden must be a live window and defaults to the selected one.
+The return value is always zero for a rightmost window.
address@hidden defun
+
address@hidden window-bottom-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s bottom divider.
address@hidden must be a live window and defaults to the selected one.
+The return value is zero for the minibuffer window or a bottommost
+window on a minibuffer-less frame.
address@hidden defun
+
+
 @node Display Property
 @section The @code{display} Property
 @cindex display specification

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2014-03-07 15:11:12 +0000
+++ b/doc/lispref/elisp.texi    2014-03-09 11:36:51 +0000
@@ -1338,7 +1338,7 @@
 * Selective Display::       Hiding part of the buffer text (the old way).
 * Temporary Displays::      Displays that go away automatically.
 * Overlays::                Use overlays to highlight parts of the buffer.
-* Width::                   How wide a character or string is on the screen.
+* Size of Displayed Text::  How large displayed text is.
 * Line Height::             Controlling the height of lines.
 * Faces::                   A face defines a graphics style
                               for text characters: font, colors, etc.

=== modified file 'doc/lispref/frames.texi'
--- a/doc/lispref/frames.texi   2014-03-06 13:41:58 +0000
+++ b/doc/lispref/frames.texi   2014-03-09 11:36:51 +0000
@@ -747,15 +747,15 @@
 
 @vindex right-divider-width, a frame parameter
 @item right-divider-width
-The width of the right divider (@pxref{Window Dividers}) of any window
-on the frame, in pixels.  A value of zero means to not draw right
-dividers.
+The width (thickness) reserved for the right divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels.  A value of zero means
+to not draw right dividers.
 
 @vindex bottom-divider-width, a frame parameter
 @item bottom-divider-width
-The width of the bottom divider (@pxref{Window Dividers}) of any window
-on the frame, in pixels.  A value of zero means to not draw bottom
-dividers.
+The width (thickness) reserved for the bottom divider (@pxref{Window
+Dividers}) of any window on the frame, in pixels.  A value of zero means
+to not draw bottom dividers.
 
 @vindex menu-bar-lines frame parameter
 @item menu-bar-lines

=== modified file 'doc/lispref/sequences.texi'
--- a/doc/lispref/sequences.texi        2014-01-05 01:33:33 +0000
+++ b/doc/lispref/sequences.texi        2014-03-09 11:36:51 +0000
@@ -107,9 +107,9 @@
 @noindent
 See also @code{string-bytes}, in @ref{Text Representations}.
 
-If you need to compute the width of a string on display, you should
-use @code{string-width} (@pxref{Width}), not @code{length}, since
address@hidden only counts the number of characters, but does not
+If you need to compute the width of a string on display, you should use
address@hidden (@pxref{Size of Displayed Text}), not @code{length},
+since @code{length} only counts the number of characters, but does not
 account for the display width of each character.
 
 @defun elt sequence index

=== modified file 'doc/lispref/strings.texi'
--- a/doc/lispref/strings.texi  2014-01-10 17:54:32 +0000
+++ b/doc/lispref/strings.texi  2014-03-09 11:36:51 +0000
@@ -48,13 +48,13 @@
 by a distinguished character code.
 
   Since strings are arrays, and therefore sequences as well, you can
-operate on them with the general array and sequence functions
-documented in @ref{Sequences Arrays Vectors}.  For example, you can
-access or change individual characters in a string using the functions
address@hidden and @code{aset} (@pxref{Array Functions}).  However, note
-that @code{length} should @emph{not} be used for computing the width
-of a string on display; use @code{string-width} (@pxref{Width})
-instead.
+operate on them with the general array and sequence functions documented
+in @ref{Sequences Arrays Vectors}.  For example, you can access or
+change individual characters in a string using the functions @code{aref}
+and @code{aset} (@pxref{Array Functions}).  However, note that
address@hidden should @emph{not} be used for computing the width of a
+string on display; use @code{string-width} (@pxref{Size of Displayed
+Text}) instead.
 
   There are two text representations for address@hidden
 characters in Emacs strings (and in buffers): unibyte and multibyte.

=== modified file 'doc/lispref/text.texi'
--- a/doc/lispref/text.texi     2014-03-02 03:34:36 +0000
+++ b/doc/lispref/text.texi     2014-03-09 11:36:51 +0000
@@ -2202,7 +2202,7 @@
 
   This section describes the primitive functions used to count and
 insert indentation.  The functions in the following sections use these
-primitives.  @xref{Width}, for related functions.
+primitives.  @xref{Size of Displayed Text}, for related functions.
 
 @defun current-indentation
 @comment !!Type Primitive Function

=== modified file 'doc/lispref/windows.texi'
--- a/doc/lispref/windows.texi  2014-03-07 15:11:12 +0000
+++ b/doc/lispref/windows.texi  2014-03-09 11:36:51 +0000
@@ -618,6 +618,29 @@
 @code{window-width} is an alias for @code{window-body-width}.  These
 aliases are considered obsolete and will be removed in the future.
 
+   The pixel heights of a window's mode and header line can be retrieved
+with the functions given below.  Their return value is usually accurate
+unless the window has not been displayed before: In that case, the
+return value is based on an estimate of the font used for the window's
+frame.
+
address@hidden window-mode-line-height &optional window
+This function returns the height in pixels of @var{window}'s mode line.
address@hidden must be a live window and defaults to the selected one.  If
address@hidden has no mode line, the return value is zero.
address@hidden defun
+
address@hidden window-header-line-height &optional window
+This function returns the height in pixels of @var{window}'s header
+line.  @var{window} must be a live window and defaults to the selected
+one.  If @var{window} has no header line, the return value is zero.
address@hidden defun
+
+Functions for retrieving the height and/or width of window dividers
+(@pxref{Window Dividers}), fringes (@pxref{Fringes}), scroll bars
+(@pxref{Scroll Bars}), and display margins (@pxref{Display Margins}) are
+described in the corresponding sections.
+
 @cindex fixed-size window
 @vindex window-min-height
 @vindex window-min-width
@@ -3476,18 +3499,18 @@
 right of the rightmost column, and the Y coordinate one row down from
 the bottommost row.
 
-Note that these are the actual outer edges of the window, including
-any header line, mode line, scroll bar, fringes, and display margins.
-On a text terminal, if the window has a neighbor on its right, its
-right edge includes the separator line between the window and its
+Note that these are the actual outer edges of the window, including any
+header line, mode line, scroll bar, fringes, window divider and display
+margins.  On a text terminal, if the window has a neighbor on its right,
+its right edge includes the separator line between the window and its
 neighbor.
 @end defun
 
 @defun window-inside-edges &optional window
 This function is similar to @code{window-edges}, but the returned edge
 values are for the text area of the window.  They exclude any header
-line, mode line, scroll bar, fringes, display margins, and vertical
-separator.
+line, mode line, scroll bar, fringes, window divider, display margins,
+and vertical separator.
 @end defun
 
 @defun window-top-line &optional window
@@ -3536,6 +3559,14 @@
 @item header-line
 The coordinates are in the header line of @var{window}.
 
address@hidden right-divider
+The coordinates are in the divider separating @var{window} from a
+window on the right.
+
address@hidden right-divider
+The coordinates are in the divider separating @var{window} from a
+window beneath.
+
 @item vertical-line
 The coordinates are in the vertical line between @var{window} and its
 neighbor to the right.  This value occurs only if the window doesn't
@@ -3597,6 +3628,17 @@
 the display screen.  @var{window} must specify a live window.
 @end defun
 
address@hidden window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}.
address@hidden must be a valid window and defaults to the selected one.
address@hidden defun
+
address@hidden window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}.
address@hidden must be a valid window and defaults to the selected one.
address@hidden defun
+
+
 @node Window Configurations
 @section Window Configurations
 @cindex window configurations

=== modified file 'src/ChangeLog'
--- a/src/ChangeLog     2014-03-08 15:49:59 +0000
+++ b/src/ChangeLog     2014-03-09 11:36:51 +0000
@@ -1,9 +1,13 @@
+2014-03-09  Martin Rudalics  <address@hidden>
+
+       * xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
+
 2014-03-08  Jan Djärv  <address@hidden>
 
        * nsterm.h (MAC_OS_X_VERSION_10_9): Add.
 
-       * nsterm.m (constrainFrameRect:toScreen:): Constrain normally when frame
-       is only on one screen (Bug#14713).
+       * nsterm.m (constrainFrameRect:toScreen:): Constrain normally
+       when frame is only on one screen (Bug#14713).
 
 2014-03-08  Eli Zaretskii  <address@hidden>
 

=== modified file 'src/xdisp.c'
--- a/src/xdisp.c       2014-03-08 13:18:43 +0000
+++ b/src/xdisp.c       2014-03-09 11:36:51 +0000
@@ -9600,19 +9600,23 @@
 defaults to the maximum accessible position of the buffer.  If TO is t,
 use the maximum accessible position that is not a newline character.
 
-The optional argument X_LIMIT, if non-nil, specifies the maximum text
-width that can be returned.  X_LIMIT nil or omitted, means to use the
+The optional argument X-LIMIT, if non-nil, specifies the maximum text
+width that can be returned.  X-LIMIT nil or omitted, means to use the
 pixel-width of WINDOW's body; use this if you do not intend to change
 the width of WINDOW.  Use the maximum width WINDOW may assume if you
-intend to change WINDOW's width.
+intend to change WINDOW's width.  In any case, text whose x-coordinate
+is beyond X-LIMIT is ignored.  Since calculating the width of long lines
+can take some time, it's always a good idea to make this argument as
+small as possible; in particular, if the buffer contains long lines that
+shall be truncated anyway.
 
-The optional argument Y_LIMIT, if non-nil, specifies the maximum text
+The optional argument Y-LIMIT, if non-nil, specifies the maximum text
 height that can be returned.  Text lines whose y-coordinate is beyond
-Y_LIMIT are ignored.  Since calculating the text height of a large
+Y-LIMIT are ignored.  Since calculating the text height of a large
 buffer can take some time, it makes sense to specify this argument if
 the size of the buffer is unknown.
 
-Optional argument MODE_AND_HEADER_LINE nil or omitted means do not
+Optional argument MODE-AND-HEADER-LINE nil or omitted means do not
 include the height of the mode- or header-line of WINDOW in the return
 value.  If it is either the symbol `mode-line' or `header-line', include
 only the height of that line, if present, in the return value.  If t,