XDrawText(3)

NAME

       XDrawText, XDrawText16, XTextItem, XTextItem16 - draw polytext text and
       text drawing structures

SYNTAX

       int XDrawText(Display *display, Drawable d, GC gc, int x, int y, XTex-
              tItem *items, int nitems);

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

ARGUMENTS

       d         Specifies the drawable.

       display   Specifies the connection to the X server.

       gc        Specifies the GC.

       items     Specifies an array of text items.

       nitems    Specifies the number of text items in the array.

       x
       y         Specify the x and y coordinates, which are relative to the
                 origin of the specified drawable and define the origin of the
                 first character.

DESCRIPTION

       The XDrawText16 function is similar to XDrawText except that it uses
       2-byte or 16-bit characters.  Both functions allow complex spacing and
       font shifts between counted strings.

       Each text item is processed in turn.  A font member other than None in
       an item causes the font to be stored in the GC and used for subsequent
       text.  A text element delta specifies an additional change in the posi-
       tion along the x axis before the string is drawn.  The delta is always
       added to the character origin and is not dependent on any characteris-
       tics of the font.  Each character image, as defined by the font in the
       GC, is treated as an additional mask for a fill operation on the draw-
       able.  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 index-
       ing, each XChar2b structure is interpreted as a 16-bit number with
       byte1 as the most significant byte.

       Both functions use these GC components: function, plane-mask, fill-
       style, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-
       mask.  They also use these GC mode-dependent components: foreground,
       background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-
       origin.

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

STRUCTURES

       The XTextItem and XTextItem16 structures contain:

       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 GC.  If an error was generated during text draw-
       ing, the previous items may have been drawn.  The baseline of the char-
       acters 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 XDrawIm-
       ageString.  If you want the upper-left corner of the background rectan-
       gle 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.

DIAGNOSTICS

       BadDrawable
                 A value for a Drawable argument does not name a defined Win-
                 dow or Pixmap.

       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 GCon-
                 text.

       BadMatch  An InputOnly window is used as a Drawable.

SEE ALSO

       XDrawImageString(3X11), XDrawString(3X11), XLoadFont(3X11)
       Xlib - C Language X Interface

X Version 11                     libX11 1.1.1                     XDrawText(3)