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.9 XDrawText(3)
xorg-libX11 1.6.9 - Generated Thu Oct 24 19:02:18 CDT 2019