From 7e940b654669e8b1f4fc92ef541c165f68873248 Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Sun, 9 Mar 2014 12:36:51 +0100 Subject: [PATCH] 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. --- doc/lispref/ChangeLog | 17 ++++++ doc/lispref/display.texi | 105 ++++++++++++++++++++++++++++++------- doc/lispref/elisp.texi | 2 +- doc/lispref/frames.texi | 12 ++--- doc/lispref/sequences.texi | 6 +-- doc/lispref/strings.texi | 14 ++--- doc/lispref/text.texi | 2 +- doc/lispref/windows.texi | 54 ++++++++++++++++--- src/ChangeLog | 8 ++- src/xdisp.c | 16 +++--- 10 files changed, 184 insertions(+), 52 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 88a20fd8a2..93153a1ecb 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,20 @@ +2014-03-09 Martin Rudalics + + * 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 * buffers.texi (The Buffer List): Rename node to Buffer List. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 56dd718588..bffb840bfe 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -18,7 +18,7 @@ that Emacs presents to the user. * 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 @@ changes. (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 @@ -1823,6 +1823,54 @@ to or less than the display width of @var{ellipsis}. If @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 @@ -3904,28 +3952,28 @@ to use the value specified by the frame. @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 @@ -3944,6 +3992,23 @@ least three pixels wide. To obtain a solid appearance, set this to the 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 diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index f0a5596837..c0040d748c 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1338,7 +1338,7 @@ Emacs Display * 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. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 166ec6d8de..206f14e751 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -747,15 +747,15 @@ widths are negative, only the left fringe gets the specified width. @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 diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 52a1cf5e32..01de4ccb0c 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -107,9 +107,9 @@ Emacs character code. @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 diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 5c814b22b2..04e11fec61 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -48,13 +48,13 @@ Vectors}). Unlike in C, Emacs Lisp strings are @emph{not} terminated 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. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 5a38ce1e0d..d93f937bd8 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2202,7 +2202,7 @@ count from zero at the left margin. 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 diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index fb022de546..3e1cd40c45 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -618,6 +618,29 @@ argument @var{pixelwise} is passed to the function called. @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 @@ -3476,18 +3499,18 @@ coordinate of the topmost row, the X coordinate one column to the 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 @@ The coordinates are in the mode line of @var{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 @@ -3597,6 +3628,17 @@ returns the edge pixel coordinates relative to the top left corner of 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 diff --git a/src/ChangeLog b/src/ChangeLog index 5b75161f91..af8cd0e492 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,9 +1,13 @@ +2014-03-09 Martin Rudalics + + * xdisp.c (Fwindow_text_pixel_size): Adjust doc-string. + 2014-03-08 Jan Djärv * 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 diff --git a/src/xdisp.c b/src/xdisp.c index 0216aaea11..b7821eb504 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -9600,19 +9600,23 @@ character. TO, if non-nil, specifies the last text position and 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, -- 2.20.1