Since not all characters have the same width, these functions let you check the width of a character. See Indentation Primitives, and Motion by Screen Lines, for related functions.
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; see Display Tables). The width of a tab character is usually tab-width
(see Usual Display Conventions).
Return non-nil if char is an uppercase character
according to Unicode.
This function returns the width in columns of the string string,
if it were displayed in the current buffer and the selected window.
Optional arguments from and to specify the substring of
string to consider, and are interpreted as in substring
(see Creating Strings).
The return value is an approximation: it only considers the values
returned by char-width for the constituent characters, always
takes a tab character as taking tab-width columns, ignores
display properties and fonts, etc. For these reasons, we recommend
using window-text-pixel-size or string-pixel-width,
described below, instead.
This function returns a new string that is a truncation of string which fits within width columns on display.
If string is narrower than width, the result is equal to string; otherwise excess characters are omitted from the result. If a multi-column character in string exceeds the goal width, that character is omitted from the result. Thus, the result can sometimes fall short of width, but cannot go beyond it.
The optional argument start-column specifies the starting
column; it defaults to zero. If this is non-nil, then the
first start-column columns of the string are omitted from the
result. If one multi-column character in string extends across
the column start-column, that character is omitted.
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
appended at the end of the result if it falls short of width, as
many times as needed to reach width. It is also prepended at
the beginning of the result if a 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 when it is truncated. In this case,
more characters will be removed from string to free enough space
for ellipsis to fit within width columns. However, if
the display width of string is less than the display width of
ellipsis, ellipsis will not be appended to the result. If
ellipsis is non-nil and not a string, it stands for the
value returned by the function truncate-string-ellipsis,
described below.
The optional argument ellipsis-text-property, if non-nil,
means hide the excess parts of string with a display text
property (see The display Property) showing the ellipsis, instead of
actually truncating the string.
(truncate-string-to-width "\tab\t" 12 4)
⇒ "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\s)
⇒ " ab "
This function uses string-width and char-width to find
the suitable truncation point when string is too wide, so it
suffers from the same basic issues as string-width does. In
particular, when character composition happens within string,
the display width of a string could be smaller than the sum of widths
of the constituent characters, and this function might return
inaccurate results.
This function returns the string to be used as an ellipses in
truncate-string-to-width and other similar contexts. The value
is that of the variable truncate-string-ellipsis, if it’s
non-nil, the string with the single character U+2026
HORIZONTAL ELLIPSIS if that character can be displayed on the
selected frame, and the string ‘...’ otherwise.
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
(see Resizing Windows) to make a window exactly as large as the text
it contains.
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. This function exists to allow Lisp programs to adjust the dimensions of window to the buffer text it needs to display, and for other similar situations.
The return value can also optionally (see below) include the buffer position of the first line whose dimensions were measured.
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
stands for the minimum accessible position that is not a newline
character. If from is a cons, its car specifies a buffer
position, and its cdr specifies the vertical offset in pixels
from that position to the first screen line whose text is to be
measured. (The measurement will start from the visual beginning of
that screen line.) In that case, the return value will instead be a
list of the pixel-width, pixel-height, and the buffer position of the
first line that was measured. 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 stands for the maximum accessible position
that is not a newline character.
The optional argument x-limit, if non-nil, specifies the
maximum X coordinate beyond which text should be ignored; it is
therefore also the largest value of pixel-width that the function can
return. If x-limit nil or omitted, it means to use the
pixel-width of window’s body (see Window Sizes); this
default means that text of truncated lines wider than the window will
be ignored. This default 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; in
particular, if truncated lines are expected and their text needs to be
accounted for, x-limit should be set to a large value. 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 Y coordinate beyond which text is to be ignored; it is
therefore also the maximum pixel-height that the function can return.
If y-limit is nil or omitted, it means to consider all the
lines of text till the buffer position specified by to. 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-lines nil or omitted means to
not include the height of the mode-, tab- or header-line of window
in the return value. If it is either the symbol mode-line,
tab-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 all of these lines, if present, in the return value.
The optional argument ignore-line-at-end controls whether or not to count the height of text in to’s screen line as part of the returned pixel-height. This is useful if your Lisp program is only interested in the dimensions of text up to and excluding the visual beginning of to’s screen line.
window-text-pixel-size treats the text displayed in a window as a
whole and does not care about the size of individual lines. The
following function does.
This function calculates the pixel dimensions of each line displayed in the specified window. It does so by walking window’s current glyph matrix—a matrix storing the glyph (see Glyphs) of each buffer character currently displayed in window. If successful, it returns a list of cons pairs representing the x- and y-coordinates of the lower right corner of the last character of each line. Coordinates are measured in pixels from an origin (0, 0) at the top-left corner of window. window must be a live window and defaults to the selected one.
If the optional argument first is an integer, it denotes the index
(starting with 0) of the first line of window’s glyph matrix to be
returned. Note that if window has a header line, the line with
index 0 is that header line. If first is nil, the first line to
be considered is determined by the value of the optional argument
body: If body is non-nil, this means to start with
the first line of window’s body, skipping any header line, if
present. Otherwise, this function will start with the first line of
window’s glyph matrix, possibly the header line.
If the optional argument last is an integer, it denotes the index
of the last line of window’s glyph matrix that shall be returned.
If last is nil, the last line to be considered is determined by
the value of body: If body is non-nil, this means to
use the last line of window’s body, omitting window’s mode
line, if present. Otherwise, this means to use the last line of
window which may be the mode line.
The optional argument inverse, if nil, means that the
y-pixel value returned for any line specifies the distance in pixels
from the left edge (body edge if body is non-nil) of
window to the right edge of the last glyph of that line.
inverse non-nil means that the y-pixel value returned for
any line specifies the distance in pixels from the right edge of the
last glyph of that line to the right edge (body edge if body is
non-nil) of window. This is useful for determining the
amount of slack space at the end of each line.
The optional argument left, if non-nil means to return the
x- and y-coordinates of the lower left corner of the leftmost character
on each line. This is the value that should be used for windows that
mostly display text from right to left.
If left is non-nil and inverse is nil, this
means that the y-pixel value returned for any line specifies the
distance in pixels from the left edge of the last (leftmost) glyph of
that line to the right edge (body edge if body is non-nil)
of window. If left and inverse are both
non-nil, the y-pixel value returned for any line specifies the
distance in pixels from the left edge (body edge if body is
non-nil) of window to the left edge of the last (leftmost)
glyph of that line.
This function returns nil if the current glyph matrix of
window is not up-to-date which usually happens when Emacs is busy,
for example, when processing a command. The value should be retrievable
though when this function is run from an idle timer with a delay of zero
seconds.
This is much like window-text-pixel-size, but can be used when
the buffer isn’t shown in a window. (window-text-pixel-size is
faster when it is, so this function shouldn’t be used in that case.)
buffer-or-name must specify a live buffer or the name of a live buffer and defaults to the current buffer. window must be a live window and defaults to the selected one; the function will compute the text dimensions as if buffer is displayed in window. The return value is a cons of the maximum pixel-width of any text line and the pixel-height of all the text lines of the buffer specified by buffer-or-name.
The optional arguments x-limit and y-limit have the same
meaning as with window-text-pixel-size.
This is a convenience function that uses window-text-pixel-size
to compute the width of string (in pixels).
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 (see Line Height).
When character compositions are in effect, sequence of characters can be composed for display to form grapheme clusters, for example to display accented characters, or ligatures, or Emoji, or when complex text shaping requires that for some scripts. When that happens, characters no longer map in a simple way to display columns, and display layout decisions with such strings, such as truncating too wide strings, can be a complex job. This function helps in performing such jobs: it splits up its argument string into a list of substrings, where each substring produces a single grapheme cluster that should be displayed as a unit. Lisp programs can then use this list to construct visually-valid substrings of string which will look correctly on display, or compute the width of any substring of string by adding the width of its constituents in the returned list, etc.
For instance, if you want to display a string without the first glyph, you can say:
(apply #'insert (cdr (string-glyph-split string))))
When a buffer is displayed with line numbers (see Display Custom in The GNU Emacs Manual), it is sometimes useful to know the width taken for displaying the line numbers. The following function is for Lisp programs which need this information for layout calculations.
This function returns the width used for displaying the line numbers
in the selected window. If the optional argument pixelwise is
the symbol columns, the return value is a float number of the
frame’s canonical columns; if pixelwise is t or any other
non-nil value, the value is an integer and is measured in
pixels. If pixelwise is omitted or nil, the value is the
integer number of columns of the font defined for the
line-number face, and doesn’t include the 2 columns used to pad
the numbers on display. If line numbers are not displayed in the
selected window, the value is zero regardless of the value of
pixelwise. Use with-selected-window (see Selecting Windows) if you need this information about another window.