* 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.
+2014-03-09 Martin Rudalics <rudalics@gmx.at>
+
+ * 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 <rudalics@gmx.at>
* buffers.texi (The Buffer List): Rename node to Buffer List.
* 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.
(point)))
@end smallexample
-@node Width
-@section Width
+@node Size of Displayed Text
+@section 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
@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
+@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and
+@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window
+exactly as large as the text it contains.
+
+@defun 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 non-@code{nil}, 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 non-@code{nil}, 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 non-@code{nil}, 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 non-@code{nil}, 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
+@var{window} in the return value. If it is either the symbol
+@code{mode-line} 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.
+@end defun
+
+
@node Line Height
@section Line Height
@cindex line height
@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
-@code{bottom-divider-width}. 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
+@code{right-divider-width}. 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.
+@xref{Layout 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.
+@xref{Window 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
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.
+
+@defun window-right-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s right divider.
+@var{window} must be a live window and defaults to the selected one.
+The return value is always zero for a rightmost window.
+@end defun
+
+@defun window-bottom-divider-width &optional window
+Return the width (thickness) in pixels of @var{window}'s bottom divider.
+@var{window} 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.
+@end defun
+
+
@node Display Property
@section The @code{display} Property
@cindex display specification
* 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.
@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
@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
-@code{length} only counts the number of characters, but does not
+If you need to compute the width of a string on display, you should use
+@code{string-width} (@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
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
-@code{aref} 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
+@code{length} 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 non-@acronym{ASCII}
characters in Emacs strings (and in buffers): unibyte and multibyte.
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
@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.
+
+@defun window-mode-line-height &optional window
+This function returns the height in pixels of @var{window}'s mode line.
+@var{window} must be a live window and defaults to the selected one. If
+@var{window} has no mode line, the return value is zero.
+@end defun
+
+@defun 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.
+@end 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
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
@item header-line
The coordinates are in the header line of @var{window}.
+@item right-divider
+The coordinates are in the divider separating @var{window} from a
+window on the right.
+
+@item 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
the display screen. @var{window} must specify a live window.
@end defun
+@defun window-pixel-left &optional window
+This function returns the left pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+@defun window-pixel-top &optional window
+This function returns the top pixel edge of window @var{window}.
+@var{window} must be a valid window and defaults to the selected one.
+@end defun
+
+
@node Window Configurations
@section Window Configurations
@cindex window configurations
+2014-03-09 Martin Rudalics <rudalics@gmx.at>
+
+ * xdisp.c (Fwindow_text_pixel_size): Adjust doc-string.
+
2014-03-08 Jan Djärv <jan.h.d@swipnet.se>
* 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 <eliz@gnu.org>
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,
projects / emacs.git / commitdiff