XDrawText(3X)                                       XDrawText(3X)



NAME
     XDrawText, XDrawText16 - draw polytext text  and  manipulate
     the XTextItem and XTextItem16 structures

SYNOPSIS
     XDrawText (display, d, gc, x, y, items, nitems)
     Display *display;
     Drawable d;
     GC gc;
     int x,y;
     XTextItem *items;
     int nitems;

     XDrawText16 (display, d, gc, x, y, items, nitems)
     Display *display;
     Drawable d;
     GC gc;
     int x,y;
     XTextItem16 *items;
     int nitems;

DESCRIPTION
     The XDrawText and XDrawText16 functions draw 8-bit and 16-
     bit polytext characters in the specified drawable.  Both
     functions allow complex spacing and font shifts between
     counted strings.

     Each text item is processed in turn.  A font member whose
     value is other than None in an item causes the font to be
     stored in the graphic context and used for subsequent text.
     A text element delta specifies an additional change in the
     position along the x axis before the string is drawn. The
     delta is always added to the character origin and is not
     dependent on any characteristics of the font.  Each charac-
     ter image, as defined by the font in the graphic context, is
     treated as an additional mask for a fill operation on the
     drawable.  The drawable is modified only where the font
     character has a bit set to 1.  If a text item generates a
     BadFont error, the previous text items may have been drawn.

     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.

     Both functions use these graphic context components:  func-
     tion, plane-mask, fill-style, font, subwindow-mode, clip-x-
     origin, clip-y-origin, and clip-mask.  They also use these
     mode-dependent graphic context components: foreground, back-
     ground, tile, stipple, tile-stipple-x-origin, and tile-
     stipple-y-origin.





November, 1990                                                  1

XDrawText(3X)                                       XDrawText(3X)



   Structures
     The XTextItem and XTextItem16 structures are defined as fol-
     lows.

     typedef struct {
       char *chars;   /* pointer to string */
       int nchars;    /* number of characters */
       int delta;     /* delta between strings */
       Font font;     /* Font to print it in, */
                      /* None don't change */
     } XTextItem;

     typedef struct {
       XChar2b *chars;/* pointer to two-byte */
                      /* characters */
       int nchars;    /* number of characters */
       int delta;     /* delta between strings */
       Font font;     /* font to print it in, */
                      /* None don't change */
     } XTextItem16;

     If the font member is not None, the font is changed before
     printing and also is stored in the graphic context.  If an
     error is generated during text drawing, the previous items
     may have been drawn.  The baseline of the characters are
     drawn starting at the x and y coordinates that you pass in
     the text drawing functions.

     For example, consider the background rectangle drawn by
     XDrawImageString.  If you want the upper-left corner of the
     background rectangle to be at pixel coordinate (x,y), pass
     the (x,y + ascent) as the baseline origin coordinates to the
     text functions.  The ascent is the font ascent, as given in
     the XFontStruct structure.  If you want the lower-left
     corner of the background rectangle to be at pixel coordinate
     (x,y), pass the (x,y - descent + 1) as the baseline origin
     coordinates to the text functions.  The descent is the font
     descent, as given in the XFontStruct structure.

   Arguments
     These functions accept the following arguments:

     d       Specifies the drawable.

     display Specifies the connection to the X server.

     gc      Specifies the graphic context.

     items   Specifies a pointer to an array of text items.

     nitems  Specifies the number of text items in the array.




2                                                  November, 1990

XDrawText(3X)                                       XDrawText(3X)



     x, y    Specify the x and y coordinates.

ERRORS
     BadDrawable
             A value for a Drawable argument does not name a de-
             fined window or pixel map.

     BadFont A value for a Font or GC argument does not name a
             defined font.

     BadGC   A value for a GC argument does not name a defined
             graphic context.

     BadMatch
             An InputOnly window is used as a drawable.

     XDrawText and XDrawText16 can generate BadDrawable, BadFont,
     BadGC, and BadMatch errors.

SEE ALSO
     XDrawImageString(3X), XDrawString(3X), XLoadFont(3X)

     Xlib - C Language Interface

































November, 1990                                                  3