XTextExtents(3)           XLIB FUNCTIONS          XTextExtents(3)



NAME
       XTextExtents, XTextExtents16, XQueryTextExtents, XQuery-
       TextExtents16 - 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 char-
                 acter 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 XQueryTextEx-
       tents16.  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 met-
       rics 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 charac-
       ters 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 met-
       rics.

       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 con-
       tained 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 func-
       tions return a XCharStruct structure, whose members are
       set to the values as follows.

       The ascent member is set to the maximum of the ascent met-
       rics 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 charac-
       ters 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 met-
       rics.

       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(3X11), XTextWidth(3X11)
       Xlib - C Language X Interface



X Version 11               libX11 1.1.5           XTextExtents(3)