NAME
XTextExtents, XTextExtents16, XQueryTextExtents, XQueryTextExtents16 - compute
or query text extents
SYNTAX
int
XTextExtents(XFontStruct * font_struct, char *string, int
nchars, int * direction_return, int * font_ascent_return,
int * font_descent_return, XCharStruct * overall_return);
int
XTextExtents16(XFontStruct * font_struct, XChar2b * string, int
nchars, int *direction_return, int * font_ascent_return,
int * font_descent_return, XCharStruct * overall_return);
int
XQueryTextExtents(Display * display, XID font_ID, char *
string, int nchars, int *direction_return, int *
font_ascent_return, int * font_descent_return, XCharStruct *
overall_return);
int
XQueryTextExtents16(Display * display, XID font_ID, XChar2b *
string, int nchars, int *direction_return, int *
font_ascent_return, int * font_descent_return, XCharStruct *
overall_return);
ARGUMENTS
- direction_return
- Returns the value of the direction hint (
FontLeftToRight or FontRightToLeft).
- display
- Specifies the connection to the X server.
- font_ID
- Specifies either the font ID or the GContext ID that
contains the font.
- font_ascent_return
- Returns the font ascent.
- font_descent_return
- Returns the font descent.
- font_struct
- Specifies the XFontStruct structure.
- nchars
- Specifies the number of characters in the character
string.
- string
- Specifies the character string.
- overall_return
- Returns the overall size in the specified
XCharStruct structure.
DESCRIPTION
The
XTextExtents and
XTextExtents16 functions perform the size
computation locally and, thereby, avoid the round-trip overhead of
XQueryTextExtents and
XQueryTextExtents16. Both functions return
an
XCharStruct structure, whose members are set to the values as
follows.
The ascent member is set to the maximum of the ascent metrics of all characters
in the string. The descent member is set to the maximum of the descent
metrics. The width member is set to the sum of the character-width metrics of
all characters in the string. For each character in the string, let W be the
sum of the character-width metrics of all characters preceding it in the
string. Let L be the left-side-bearing metric of the character plus W. Let R
be the right-side-bearing metric of the character plus W. The lbearing member
is set to the minimum L of all characters in the string. The rbearing member
is set to the maximum R.
For fonts defined with linear indexing rather than 2-byte matrix indexing, each
XChar2b structure is interpreted as a 16-bit number with byte1 as the
most significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
The
XQueryTextExtents and
XQueryTextExtents16 functions return the
bounding box of the specified 8-bit and 16-bit character string in the
specified font or the font contained in the specified GC. These functions
query the X server and, therefore, suffer the round-trip overhead that is
avoided by
XTextExtents and
XTextExtents16. Both functions
return a
XCharStruct structure, whose members are set to the values as
follows.
The ascent member is set to the maximum of the ascent metrics of all characters
in the string. The descent member is set to the maximum of the descent
metrics. The width member is set to the sum of the character-width metrics of
all characters in the string. For each character in the string, let W be the
sum of the character-width metrics of all characters preceding it in the
string. Let L be the left-side-bearing metric of the character plus W. Let R
be the right-side-bearing metric of the character plus W. The lbearing member
is set to the minimum L of all characters in the string. The rbearing member
is set to the maximum R.
For fonts defined with linear indexing rather than 2-byte matrix indexing, each
XChar2b structure is interpreted as a 16-bit number with byte1 as the
most significant byte. If the font has no defined default character, undefined
characters in the string are taken to have all zero metrics.
Characters with all zero metrics are ignored. If the font has no defined
default_char, the undefined characters in the string are also ignored.
XQueryTextExtents and
XQueryTextExtents16 can generate
BadFont and
BadGC errors.
DIAGNOSTICS
- BadFont
- A value for a Font or GContext argument does not name a
defined Font.
- BadGC
- A value for a GContext argument does not name a defined
GContext.
SEE ALSO
XLoadFont(3), XTextWidth(3)
Xlib - C Language X Interface