elisp: Size of Displayed Text
37.10 Size of Displayed Text
============================
Since not all characters have the same width, these functions let you
DONTPRINTYET check the width of a character. Primitive Indent, and *noteDONTPRINTYET check the width of a character. Primitive Indent, and
Screen Lines, for related functions.
-- Function: char-width char
This function returns the width in columns of the character CHAR,
if it were displayed in the current buffer (i.e., taking into
account the buffer’s display table, if any; Display
Tables). The width of a tab character is usually ‘tab-width’
(Usual Display).
-- Function: string-width string
This function returns the width in columns of the string STRING, if
it were displayed in the current buffer and the selected window.
-- Function: truncate-string-to-width string width &optional
start-column padding ellipsis
This function returns the part of STRING that fits within WIDTH
columns, as a new string.
If STRING does not reach WIDTH, then the result ends where STRING
ends. If one multi-column character in STRING extends across the
column WIDTH, that character is not included in the result. Thus,
the result can fall short of WIDTH but cannot go beyond it.
The optional argument START-COLUMN specifies the starting column.
If this is non-‘nil’, then the first START-COLUMN columns of the
string are omitted from the value. If one multi-column character
in STRING extends across the column START-COLUMN, that character is
not included.
The optional argument PADDING, if non-‘nil’, is a padding character
added at the beginning and end of the result string, to extend it
to exactly WIDTH columns. The padding character is used at the end
of the result if it falls short of WIDTH. It is also used at the
beginning of the result if one multi-column character in STRING
extends across the column START-COLUMN.
If ELLIPSIS is non-‘nil’, it should be a string which will replace
the end of STRING (including any padding) if it extends beyond
WIDTH, unless the display width of STRING is equal to or less than
the display width of ELLIPSIS. If ELLIPSIS is non-‘nil’ and not a
string, it stands for the value of the variable
‘truncate-string-ellipsis’.
(truncate-string-to-width "\tab\t" 12 4)
⇒ "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\s)
⇒ " ab "
The following function returns the size in pixels of text as if it
were displayed in a given window. This function is used by
‘fit-window-to-buffer’ and ‘fit-frame-to-buffer’ (Resizing
Windows) to make a window exactly as large as the text it contains.
-- Function: 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 WINDOW’s buffer in
pixels. 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 FROM, if non-‘nil’, specifies the first text
position to consider and defaults to the minimum accessible
position of the buffer. If FROM is ‘t’, it uses the minimum
accessible position that is not a newline character. The optional
argument TO, if non-‘nil’, specifies the last text position to
consider and defaults to the maximum accessible position of the
buffer. If TO is ‘t’, it uses the maximum accessible position that
is not a newline character.
The optional argument X-LIMIT, if non-‘nil’, specifies the maximum
pixel-width that can be returned. X-LIMIT ‘nil’ or omitted, means
to use the pixel-width of WINDOW’s body (Window Sizes);
this is useful when the caller does not intend to change the width
of WINDOW. Otherwise, the caller should specify here the maximum
width WINDOW’s body may assume. 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 needed; in particular, if the buffer might contain long
lines that will be truncated anyway.
The optional argument Y-LIMIT, if non-‘nil’, specifies the maximum
pixel-height that can be returned. Text lines whose y-coordinate
is beyond 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 MODE-AND-HEADER-LINE ‘nil’ or omitted means
to 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 it is ‘t’, include the height of both, if
present, in the return value.
-- Function: line-pixel-height
This function returns the height in pixels of the line at point in
the selected window. The value includes the line spacing of the
line (Line Height).