XmbTextPerCharExtents(XS)      6 January 1993      XmbTextPerCharExtents(XS)
                          X Version 11 (Release 5)


 Name

    XmbTextPerCharExtents - obtain per-character information for a text
    string

 Syntax


    Status XmbTextPerCharExtents (font_set, string, num_bytes, ink_array_return,
                                  logical_array_return, array_size,
                                  num_chars_return, overall_return)
          XFontSet font_set;
          char *string;
          int num_bytes;
          XRectangle *ink_array_return;
          XRectangle *logical_array_return;
          int array_size;
          int *num_chars_return;
          XRectangle *overall_ink_return;
          XRectangle *overall_logical_return;

    Status XwcTextPerCharExtents (font_set, string, num_wchars,
                                  ink_array_return, logical_array_return,
                                  array_size, num_chars_return, overall_return)
          XFontSet font_set;
          wchar_t *string;
          int num_wchars;
          XRectangle *ink_array_return;
          XRectangle *logical_array_return;
          int array_size;
          int *num_chars_return;
          XRectangle *overall_ink_return;
          XRectangle *overall_logical_return;


 Arguments


    arraysize     Specifies the size of inkarrayreturn and
                   logicalarrayreturn.  Note that the caller must pass in
                   arrays of this size.

    fontset       Specifies the font set.

    inkarrayreturn
                   Returns the ink dimensions for each character.

    logicalarrayreturn
                   Returns the logical dimensions for each character.

    numbytes      Specifies the number of bytes in the string argument.

    numcharsreturn
                   Returns the number characters in the string argument.

    numwchars     Specifies the number of characters in the string argument.

    overallinkreturn
                   Returns the overall ink extents of the entire string.

    overalllogicalreturn
                   Returns the overall logical extents of the entire string.

    string         Specifies the character string.

 Description

    The XmbTextPerCharExtents and XwcTextPerCharExtents return the text
    dimensions of each character of the specified text, using the fonts
    loaded for the specified font set.  Each successive element of
    inkarrayreturn and logicalarrayreturn is set to the successive
    character's drawn metrics, relative to the drawing origin of the string,
    one XRectangle for each character in the supplied text string.  The num-
    ber of elements of inkarrayreturn and logicalarrayreturn that have
    been set is returned to numcharsreturn.

    Each element of inkarrayreturn is set to the bounding box of the corre-
    sponding character's drawn foreground color.  Each element of
    logicalarrayreturn is set to the bounding box which provides minimum
    spacing to other graphical features for the corresponding character.
    Other graphical features should not intersect any of the
    logicalarrayreturn rectangles.

    Note that an XRectangle represents the effective drawing dimensions of
    the character, regardless of the number of font glyphs that are used to
    draw the character, or the direction in which the character is drawn.  If
    multiple characters map to a single character glyph, the dimensions of
    all the XRectangles of those characters are the same.

    When the XFontSet has missing charsets, metrics for each unavailable
    character are taken from the default string returned by XCreateFontSet,
    so that the metrics represent the text as it will actually be drawn.  The
    behavior for an invalid codepoint is undefined.

    If the arraysize is too small for the number of characters in the sup-
    plied text, the functions return zero and numcharsreturn is set to the
    number of rectangles required.  Otherwise, the routines return a non-zero
    value.

    If the overallinkreturn or overalllogicalreturn argument is non-NULL,
    XmbTextPerCharExtents and XwcTextPerCharExtents return the maximum extent
    of the string's metrics to overallinkreturn or overalllogicalreturn,
    as returned by XmbTextExtents or XwcTextExtents.

 See also

    XmbTextEscapement(XS), XmbTextExtents(XS)
    Xlib - C Language X Interface