XQueryTextExtents()XQueryTextExtents()Name
XQueryTextExtents – query the server for string and font metrics.
Synopsis
XQueryTextExtents(display, font_ID, string, nchars, direction_return,
font_ascent_return, font_descent_return, overall_return)
Display *display;
XID font_ID;
char *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
font_ID Specifies the appropriate font ID previously returned by
XLoadFont(), or the GContext that specifies the font.
string Specifies the character string for which metrics are to be
returned.
nchars Specifies the number of characters in string.
direction_return
Returns the direction the string would be drawn using the
specified font. Either FontLeftToRight or FontRightToLeft.
font_ascent_return
Returns the maximum ascent for the specified font.
font_descent_return
Returns the maximum descent for the specified font.
overall_return
Returns the overall characteristics of the string. These are
the sum of the width measurements for each character, the
maximum font_ascent_return and font_descent_return, the mini‐
mum lbearing added to the width of all characters up to the
character with the smallest lbearing, and the maximum rbear‐
ing added to the width of all characters up to the character
with the largest rbearing.
DescriptionXQueryTextExtents() returns the dimensions in pixels that specify the
bounding box of the specified string of characters in the named font,
and the maximum ascent and descent for the entire font. This function
queries the server and, therefore, suffers the round trip overhead that
is avoided by XTextExtents(), but XQueryTextExtents() does not require
a filled XFontInfo structure stored on the client side. Therefore,
this function would be used when memory is precious, or when just a
small number of text width calculations are to be done.
The returned font_ascent_return and font_descent_return should usually
be used to calculate the line spacing, while the width, rbearing, and
lbearing members of overall_return should be used for horizontal mea‐
sures. The total height of the bounding rectangle, good for any string
in this font, is font_ascent_return + font_descent_return.
overall_return.ascent is the maximum of the ascent metrics of all char‐
acters in the string. The overall_return.descent is the maximum of the
descent metrics. The overall_return.width is the sum of the character-
width metrics of all characters in the string. The over‐
all_return.lbearing is usually the lbearing of the first character in
the string, and overall_return.rbearing is the rbearing of the last
character in the string plus the sum of the widths of all the charac‐
ters up to but not including the last character. More technically,
here is the X protocol definition: For each character in the string,
let W be the sum of the character-width metrics of all characters pre‐
ceding it in the string, let L be the lbearing metric of the character
plus W, and let R be the rbearing metric of the character plus W. The
overall_return.lbearing is the minimum L of all characters in the
string, and the overall_return.rbearing is the maximum R.
For more information on drawing text, see Volume One, Chapter 6, Draw‐
ing Graphics and Text.
Structures
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Errors
BadFont
BadGC
See AlsoXDrawImageString(), XDrawImageString16(), XDrawString(), XDraw‐
String16(), XDrawText(), XDrawText16(), XQueryTextExtents16(), XTextEx‐
tents(), XTextExtents16(), XTextWidth(), XTextWidth16().
Xlib - Text XQueryTextExtents()
