XDrawText(3)			XLIB FUNCTIONS			  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(3), XDrawString(3), XLoadFont(3)
       Xlib - C Language X Interface



X Version 11			 libX11 1.6.0			  XDrawText(3)