| Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 |
|---|
Once you have established a connection to a display, you can use the Xlib graphics functions to:
If the same drawable and GC is used for each call, Xlib batches back-to-back calls to XDrawPoint, XDrawLine, XDrawRectangle, XFillArc, and XFillRectangle. Note that this reduces the total number of requests sent to the server.
Xlib provides functions that you can use to clear an area or the entire window. Because pixmaps do not have defined backgrounds, they cannot be filled by using the functions described in this section. Instead, to accomplish an analogous operation on a pixmap, you should use XFillRectangle, which sets the pixmap to a known value.
To clear a rectangular area of a given window, use XClearArea.
XClearArea(display, w, x, y, width, height, exposures) Display *display; Window w; int x, y; unsigned int width, height; Bool exposures;
The XClearArea function paints a rectangular area in the specified window according to the specified dimensions with the window's background pixel or pixmap. The subwindow-mode effectively is ClipByChildren. If width is zero, it is replaced with the current width of the window minus x. If height is zero, it is replaced with the current height of the window minus y. If the window has a defined background tile, the rectangle clipped by any children is filled with this tile. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, one or more Expose events are generated for regions of the rectangle that are either visible or are being retained in a backing store. If you specify a window whose class is InputOnly, a BadMatch error results.
XClearArea can generate BadMatch, BadValue, and BadWindow errors.
To clear the entire area in a given window, use XClearWindow.
XClearWindow(display, w) Display *display; Window w;
The XClearWindow function clears the entire area in the specified window and is equivalent to XClearArea (display, w, 0, 0, 0, 0, False). If the window has a defined background tile, the rectangle is tiled with a plane-mask of all ones and GXcopy function. If the window has background None, the contents of the window are not changed. If you specify a window whose class is InputOnly, a BadMatch error results.
XClearWindow can generate BadMatch and BadWindow errors.
| Home |
|---|
Xlib provides functions that you can use to copy an area or a bit plane.
To copy an area between drawables of the same root and depth, use XCopyArea.
XCopyArea(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y;
The XCopyArea function combines the specified rectangle of src with the specified rectangle of dest. The drawables must have the same root and depth, or a BadMatch error results.
If regions of the source rectangle are obscured and have not been retained in backing store or if regions outside the boundaries of the source drawable are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing store. If the destination is a window with a background other than None, corresponding regions of the destination are tiled with that background (with plane-mask of all ones and GXcopy function). Regardless of tiling or whether the destination is a window or a pixmap, if graphics-exposures is True, then GraphicsExpose events for all corresponding destination regions are generated. If graphics-exposures is True but no GraphicsExpose events are generated, a NoExpose event is generated. Note that by default graphics-exposures is True in new GCs.
This function uses these GC components: function, plane-mask, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.
XCopyArea can generate BadDrawable, BadGC, and BadMatch errors.
To copy a single bit plane of a given drawable, use XCopyPlane.
XCopyPlane(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y, plane) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y; unsigned long plane;
The XCopyPlane function uses a single bit plane of the specified source rectangle combined with the specified GC to modify the specified rectangle of dest. The drawables must have the same root but need not have the same depth. If the drawables do not have the same root, a BadMatch error results. If plane does not have exactly one bit set to 1 and the value of plane is not less than 2n, where n is the depth of src, a BadValue error results.
Effectively, XCopyPlane forms a pixmap of the same depth as the rectangle of dest and with a size specified by the source region. It uses the foreground/background pixels in the GC (foreground everywhere the bit plane in src contains a bit set to 1, background everywhere the bit plane in src contains a bit set to 0) and the equivalent of a CopyArea protocol request is performed with all the same exposure semantics. This can also be thought of as using the specified region of the source bit plane as a stipple with a fill-style of FillOpaqueStippled for filling a rectangular area of the destination.
This function uses these GC components: function, plane-mask, foreground, background, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.
XCopyPlane can generate BadDrawable, BadGC, BadMatch, and BadValue errors.
| Home |
|---|
Xlib provides functions that you can use to draw:
Some of the functions described in the following sections use these structures:
| typedef struct { | |
| short x1, y1, x2, y2; | |
| } XSegment; | |
| typedef struct { | |
| short x, y; | |
| } XPoint; | |
| typedef struct { | |
| short x,y; unsigned short width, height; | |
| } XRectangle; | |
| typedef struct { | ||
| short x, y; unsigned short width, height; short angle1, angle2; | /* Degrees * 64 */ | |
| } XArc; | ||
All x and y members are signed integers. The width and height members are 16-bit unsigned integers. You should be careful not to generate coordinates and sizes out of the 16-bit ranges, because the protocol only has 16-bit fields for these values.
To draw a single point in a given drawable, use XDrawPoint.
XDrawPoint(display, d, gc, x, y) Display *display; Drawable d; GC gc; int x, y;
To draw multiple points in a given drawable, use XDrawPoints.
XDrawPoints(display, d, gc, points, npoints, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int mode;
The XDrawPoint function uses the foreground pixel and function components of the GC to draw a single point into the specified drawable; XDrawPoints draws multiple points this way. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point. XDrawPoints draws the points in the order listed in the array.
Both functions use these GC components: function, plane-mask, foreground, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
XDrawPoint can generate BadDrawable, BadGC, and BadMatch errors. XDrawPoints can generate BadDrawable, BadGC, BadMatch, and BadValue errors.
| Home |
|---|
To draw a single line between two points in a given drawable, use XDrawLine.
XDrawLine(display, d, gc, xl, yl, x2, y2) Display *display; Drawable d; GC gc; int xl, yl, x2, y2;
To draw multiple lines in a given drawable, use XDrawLines.
XDrawLines(display, d, gc, points, npoints, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int mode;
To draw multiple, unconnected lines in a given drawable, use XDrawSegments.
XDrawSegments(display, d, gc, segments, nsegments) Display *display; Drawable d; GC gc; XSegment *segments; int nsegments;
The XDrawLine function uses the components of the specified GC to draw a line between the specified set of points (x1, y1) and (x2, y2). It does not perform joining at coincident endpoints. For any given line, XDrawLine does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times.
The XDrawLines function uses the components of the specified GC to draw npoints-1 lines between each pair of points (point[i], point[i+1]) in the array of XPoint structures. It draws the lines in the order listed in the array. The lines join correctly at all intermediate points, and if the first and last points coincide, the first and last lines also join correctly. For any given line, XDrawLines does not draw a pixel more than once. If thin (zero line-width) lines intersect, the intersecting pixels are drawn multiple times. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire PolyLine protocol request were a single, filled shape. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point.
The XDrawSegments function draws multiple, unconnected lines. For each segment, XDrawSegments draws a line between (x1, y1) and (x2, y2). It draws the lines in the order listed in the array of XSegment structures and does not perform joining at coincident endpoints. For any given line, XDrawSegments does not draw a pixel more than once. If lines intersect, the intersecting pixels are drawn multiple times.
All three functions use these GC components: function, plane-mask, line-width, line-style, capstyle, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. The XDrawLines function also uses the join-style GC component. All three functions also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list.
XDrawLine, XDrawLines, and XDrawSegments can generate BadDrawable, BadGC, and BadMatch errors. XDrawLines also can generate BadValue errors.
| Home |
|---|
To draw the outline of a single rectangle in a given drawable, use XDrawRectangle.
XDrawRectangle(display, d, gc, x, y, width, height) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height;
To draw the outline of multiple rectangles in a given drawable, use XDrawRectangles.
XDrawRectangles(display, d, gc, rectangles, nrectangles) Display *display; Drawable d; GC gc; XRectangle rectangles[]; int nrectangles;
The XDrawRectangle and XDrawRectangles functions draw the outlines of the specified rectangle or rectangles as if a five-point PolyLine protocol request were specified for each rectangle:
[x,y] [x+width,y] [x+width,y+height] [x,y+height] [x,y]
For the specified rectangle or rectangles, these functions do not draw a pixel more than once. XDrawRectangles draws the rectangles in the order listed in the array. If rectangles intersect, the intersecting pixels are drawn multiple times.
Both functions use these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, 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, tile-stipple-y-origin, dash-offset, and dash-list.
XDrawRectangle and XDrawRectangles can generate BadDrawable, BadGC, and BadMatch errors.
| Home |
|---|
To draw a single arc in a given drawable, use XDrawArc.
XDrawArc(display, d, gc, x, y, width, height, angle1, angle2) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height; int angle1, angle2;
To draw multiple arcs in a given drawable, use XDrawArcs.
XDrawArcs(dispiay, d, gc, arcs, narcs) Display *dispiay; Drawable d; GC gc; XArc *arcs; int narcs;
XDrawArc draws a single circular or elliptical arc, and XDrawArcs draws multiple circular or elliptical arcs. Each arc is specified by a rectangle and two angles. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height. Positive angles indicate counterclockwise motion, and negative angles indicate clockwise motion. If the magnitude of angle2 is greater than 360 degrees, XDrawArc or XDrawArcs truncates it to 360 degrees.
For an arc specified as [x, y, width, height, angle1, angle2], the origin of the major and minor axes is at [x + width/2, y + height/2] and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at [x, y + height/2] and [x + width, y + height/2 ] and intersects the vertical axis at [x + width/2, y] and [x + width/2, y + height]. These coordinates can be fractional and so are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line-width 1w, the bounding outlines for filling are given by the two infinitely thin paths consisting of all points whose perpendicular distance from the path of the circle/ellipse is equal to lw/2 (which may be a fractional value). The cap-style and join-style are applied the same as for a line corresponding to the tangent of the circle/ellipse at the endpoint.
For an arc specified as [x, y, width, height, angle1, angle2], the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows:
The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled by 64) in the range [0, 2p] and where atan returns a value in the range [-p/2, p/2] and adjust is:
For any given arc, XDrawArc and XDrawArcs do not draw a pixel more than once. If two arcs join correctly and if the line-width is greater than zero and the arcs intersect, XDrawArc and XDrawArcs do not draw a pixel more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins.
If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio.
Both functions use these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, 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, tile-stipple-y-origin, dash-offset, and dash-list.
XDrawArc and XDrawArcs can generate BadDrawable, BadGC, and BadMatch errors.
| Home |
|---|
Xlib provides functions that you can use to fill:
To fill a single rectangular area in a given drawable, use XFillRectangle.
XFillRectangle(display, d, gc, x, y, width, height) Display *display; Drawable d; GC gc; int x,y; unsigned int width, height;
To fill multiple rectangular areas in a given drawable, use XFillRectangles.
XFillRectangles(display, d, gc, rectangles, nrectangles) Display *display; Drawable d; GC gc; XRectangle *rectangles; int nrectangles;
The XFillRectangle and XFillRectangles functions fill the specified rectangle or rectangles as if a four-point FillPolygon protocol request were specified for each rectangle:
Each function uses the x and y coordinates, width and height dimensions, and GC you specify.
XFillRectangles fills the rectangles in the order listed in the array. For any given rectangle, XFillRectangle and XFillRectangles do not draw a pixel more than once. If rectangles intersect, the intersecting pixels are drawn multiple times.
Both functions use these GC components: function, plane-mask, fill-style, 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.
XFillRectangle and XFillRectangles can generate BadDrawable, BadGC, and BadMatch errors.
| Home |
|---|
To fill a polygon area in a given drawable, use XFillPolygon.
XFillPolygon(display, d, gc, points, npoints, shape, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int shape; int mode;
XFillPolygon fills the region closed by the specified path. The path is closed automatically if the last point in the list does not coincide with the first point. XFillPolygon does not draw a pixel of the region more than once. CoordModeOrigin treats all coordinates as relative to the origin, and CoordModePrevious treats all coordinates after the first as relative to the previous point.
Depending on the specified shape, the following occurs:
The fill-rule of the GC controls the filling behavior of self-intersecting polygons.
This function uses these GC components: function, plane-mask, fill-style, fill-rule, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.
XFillPolygon can generate BadDrawable, BadGC, BadMatch, and BadValue errors.
| Home |
|---|
To fill a single arc in a given drawable, use XFillArc.
XFillArc(display, d, gc, x, y, width, height, angle1, angle2)
Display *display;
Drawable d;
GC gc;
int x, y;
unsigned int width, height;
int angle1, angle2;
To fill multiple arcs in a given drawable, use XFillArcs.
XFillArcs(display, d, gc, arcs, narcs) Display *display; Drawable d; GC gc; XArc *arcs; int narcs;
For each arc, XFillArc or XFillArcs fills the region closed by the infinitely thin path described by the specified arc and, depending on the arc-mode specified in the GC, one or two line segments. For ArcChord, the single line segment joining the endpoints of the arc is used. For ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. XFillArcs fills the arcs in the order listed in the array. For any given arc, XFillArc and XFillArcs do not draw a pixel more than once. If regions intersect, the intersecting pixels are drawn multiple times.
Both functions use these GC components: function, plane-mask, fill-style, arc-mode, 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.
XFillArc and XFillArcs can generate BadDrawable, BadGC, and BadMatch errors.
| Home |
|---|
A font is a graphical description of a set of characters that are used to increase efficiency whenever a set of small, similar sized patterns are repeatedly used.
This section discusses how to:
The X server loads fonts whenever a program requests a new font. The server can cache fonts for quick lookup. Fonts are global across all screens in a server. Several levels are possible when dealing with fonts. Most applications simply use XLoadQueryFont to load a font and query the font metrics.
Characters in fonts are regarded as masks. Except for image text requests, the only pixels modified are those in which bits are set to 1 in the character. This means that it makes sense to draw text using stipples or tiles (for example, many menus gray-out unusable entries).
The XFontStruct structure contains all of the information for the font and consists of the font-specific information as well as a pointer to an array of XCharStruct structures for the characters contained in the font. The XFontStruct, XFontProp, and XCharStruct structures contain:
| typedef struct { | ||
| short lbearing; short rbearing; short width; short ascent; short descent; unsigned short attributes; | /* origin to left edge of raster */ /* origin to right edge of raster */ /* advance to next char's origin */ /* baseline to top edge of raster */ /* baseline to bottom edge of raster */ /* per char flags (not predefined) */ | |
| } XCharStruct; | ||
| typedef struct { | |
| Atom name; unsigned long card32; | |
| } XFontProp; | |
| typedef struct { | /* normal 16 bit characters are two bytes */ | ||
| unsigned char byte1; unsigned char byte2; | |||
| } XChar2b; | |||
| typedef struct { | ||
| XExtData *ext_data; Font fid; unsigned direction; unsigned min_char_or_byte2; unsigned max_char_or_byte2; unsigned min_byte1; unsigned max_byte1; Bool all_chars_exist; unsigned default_char; int n_properties; XFontProp *properties; XCharStruct min_bounds; XCharStruct max_bounds; XCharStruct *per_char; int ascent; int descent: | /* hook for extension to hang data */ /* Font id for this font */ /* hint about the direction font is painted */ /* first character */ /* last character */ /* first row that exists */ /* last row that exists */ /* flag if all characters have nonzero size */ /* char to print for undefined character */ /* how many properties there are */ /* pointer to array of additional properties */ /* minimum bounds over all existing char */ /* maximum bounds over all existing char */ /* first_char to last_char information */ /* logical extent above baseline for spacing */ /* logical decent below baseline for spacing */ | |
| } XFontStruct; | ||
X supports single byte/character, two bytes/character matrix, and 16-bit character text operations. Note that any of these forms can be used with a font, but a single byte/character text request can only specify a single byte (that is, the first row of a 2-byte font). You should view 2-byte fonts as a two-dimensional matrix of defined characters: byte1 specifies the range of defined rows and byte2 defines the range of defined columns of the font. Single byte/character fonts have one row defined, and the byte2 range specified in the structure defines a range of characters.
The bounding box of a character is defined by the XCharStruct of that character. When characters are absent from a font, the default_char is used. When fonts have all characters of the same size, only the information in the XFontStruct min and max bounds are used.
The members of the XFontStruct have the following semantics:
where:
Its width is:
Its height is:
For a character origin at [x, y], the bounding box of a character (that is, the smallest rectangle that encloses the character's shape) described in terms of XCharStruct components is a rectangle with its upper-left corner at:
Its width is:
Its height is:
The origin for the next character is defined to be:
The lbearing member defines the extent of the left edge of the character ink from the origin. The rbearing member defines the extent of the right edge of the character ink from the origin. The ascent member defines the extent of the top edge of the character ink from the origin. The descent member defines the extent of the bottom edge of the character ink from the origin. The width member defines the logical width of the character.
Note that the baseline (the y position of the character origin) is logically viewed as being the scanline just below nondescending characters. When descent is zero, only pixels with Y-coordinates less than y are drawn, and the origin is logically viewed as being coincident with the left edge of a nonkerned character. When lbearing is zero, no pixels with X-coordinate less than x are drawn. Any of the XCharStruct metric members could be negative. If the width is negative, the next character will be placed to the left of the current origin.
The X protocol does not define the interpretation of the attributes member in the XCharStruct structure. A nonexistent character is represented with all members of its XCharStruct set to zero.
A font is not guaranteed to have any properties. The interpretation of the property value (for example, long or unsigned long) must be derived from a priori knowledge of the property. A basic set of font properties is specified in the X Consortium standard X Logical Font Description Conventions (provided in printed version only).
| Home |
|---|
Xlib provides functions that you can use to load fonts, get font information, unload fonts, and free font information. A few font functions use a GContext resource ID or a font ID interchangeably.
To load a given font, use XLoadFont.
FontXLoadFont(display, name) Display *display; char *name;
The XLoadFont function loads the specified font and returns its associated font ID. If the font name is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. When the characters "?" and "*" are used in a font name, a pattern match is performed and any matching font is used. In the pattern, the "?" character will match any single character, and the "*" character will match any number of characters. A structured format for font names is specified in the X Consortium standard X Logical Font Description Conventions (provided in printed version only). If XLoadFont was unsuccessful at loading the specified font, a BadName error results. Fonts are not associated with a particular screen and can be stored as a component of any GC. When the font is no longer needed, call XUnloadFont.
XLoadFont can generate BadAlloc and BadName errors.
To return information about an available font, use XQueryFont.
XFontStruct *XQueryFont(display, font_ID) Display *display; XID font_ID;
The XQueryFont function returns a pointer to the XFontStruct structure, which contains information associated with the font. You can query a font or the font stored in a GC. The font ID stored in the XFontStruct structure will be the GContext ID, and you need to be careful when using this ID in other functions (see XGContextFromGC). If the font does not exist, XQueryFont returns NULL. To free this data, use XFreeFontInfo.
To perform a XLoadFont and XQueryFont in a single operation, use XLoadQueryFont.
XFontStruct *XLoadQueryFont(display, name) Display *display; char *name;
The XLoadQueryFont function provides the most common way for accessing a font. XLoadQueryFont both opens (loads) the specified font and returns a pointer to the appropriate XFontStruct structure. If the font name is not in the Host Portable Character Encoding, the result is implementation dependent. If the font does not exist, XLoadQueryFont returns NULL.
XLoadQueryFont can generate a BadAlloc error.
To unload the font and free the storage used by the font structure that was allocated by XQueryFont or XLoadQueryFont, use XFreeFont.
XFreeFont(display, font_struct) Display *display; XFontStruct *font_struct;
The XFreeFont function deletes the association between the font resource ID and the specified font and frees the XFontStruct structure. The font itself will be freed when no other resource references it. The data and the font should not be referenced again. XFreeFont can generate a BadFont error.
To return a given font property, use XGetFontProperty.
Bool XGetFontProperty(font_struct, atom, value_return) XFontStruct *font_struct; Atom atom; unsigned long *value_return;
Given the atom for that property, the XGetFontProperty function returns the value of the specified font property. XGetFontProperty also returns False if the property was not defined or True if it was defined. A set of predefined atoms exists for font properties, which can be found in <X11/Xatom.h>. This set contains the standard properties associated with a font. Although it is not guaranteed, it is likely that the predefined font properties will be present.
To unload a font that was loaded by XLoadFont, use XUnloadFont.
XUnloadFont(display, font) Display *display; Font font;
The XUnloadFont function deletes the association between the font resource ID and the specified font. The font itself will be freed when no other resource references it. The font should not be referenced again.
XUnloadFont can generate a BadFont error.
| Home |
|---|
You obtain font names and information by matching a wildcard specification when querying a font type for a list of available sizes and so on.
To return a list of the available font names, use XListFonts.
char **XListFonts(display, pattern, maxnames, actual_count_return)
Display *display;
char *pattern;
int maxnames;
int *actual_count_ return;
The XListFonts function returns an array of available font names (as controlled by the font search path; see XSetFontPath) that match the string you passed to the pattern argument. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of characters, and each question mark (?) is a wildcard for a single character. If the pattern string is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. Each returned string is null-terminated. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent. If there are no matching font names, XListFonts returns NULL. The client should call XFreeFontNames when finished with the result to free the memory.
To free a font name array, use XFreeFontNames.
XFreeFontNames(list) char *list[];
The XFreeFontNames function frees the array and strings returned by XListFonts or XListFontsWithInfo .
To obtain the names and information about available fonts, use XListFontsWithInfo.
char **XListFontsWithInfo(display, pattern, maxnames, count _return, info_return)
Display *display;
char *pattern;
int maxnames;
int *count_return;
XFontStruct **info_return;
The XListFontsWithlnfo function returns a list of font names that match the specified pattern and their associated font information. The list of names is limited to size specified by maxnames. The information returned for each font is identical to what XLoadQueryFont would return except that the per-character metrics are not returned. The pattern string can contain any characters, but each asterisk (*) is a wildcard for any number of characters, and each question mark (?) is a wildcard for a single character. If the pattern string is not in the Host Portable Character Encoding, the result is implementation dependent. Use of uppercase or lowercase does not matter. Each returned string is null-terminated. If the data returned by the server is in the Latin Portable Character Encoding, then the returned strings are in the Host Portable Character Encoding. Otherwise, the result is implementation dependent. If there are no matching font names, XListFontsWithInfo returns NULL.
To free only the allocated name array, the client should call XFreeFontNames. To free both the name array and the font information array or to free just the font information array, the client should call XFreeFontlnfo.
To free font structures and font names, use XFreeFontInfo.
XFreeFontInfo(names, free_info, actual_count) char **names; XFontStruct *free_info; int actual_count;
The XFreeFontlnfo function frees a font structure or an array of font structures, and optionally an array of font names. If NULL is passed for names, no font names are freed. If a font structure for an open font (returned by XLoadQueryFont) is passed, the structure is freed but the font is not closed; use XUnloadFont to close the font.
| Home |
|---|
Xlib provides functions that you can use to compute the width, the logical extents, and the server information about 8-bit and 2-byte text strings. The width is computed by adding the character widths of all the characters. It does not matter if the font is an 8-bit or 2-byte font. These functions return the sum of the character metrics, in pixels.
To determine the width of an 8-bit character string, use XTextWidth.
int XTextWidth(font_struct, string, count)
XFontStruct *font_struct;
char *string;
int count;
To determine the width of a 2-byte character string, use XTextWidth16.
int XTextWidth16(font_struct, string, count)
XFontStruct *font_struct;
XChar2b *string;
int count;
| Home |
|---|
To compute the bounding box of an 8-bit character string in a given font, use XTextExtents.
XTextExtents(font_struct, string, nchars, direction_return, font _ascent_return,
font_descent_return, overall_return)
XFontStruct *font_struct;
char *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;
To compute the bounding box of a 2-byte character string in a given font, use XTextExtents16.
XTextExtents16(font_struct, string, nchars, direction_return, font_ascent_return,
font_descent_return, overall_return)
XFontStruct *font_struct;
XChar2b *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;
The XTextExtents and XTextExtents16 functions perform the size computation locally and, thereby, avoid the round-trip overhead of XQueryTextExtents and XQueryTextExtents16. Both functions return an XCharStruct structure, whose members are set to the values as follows.
The ascent member is set to the maximum of the ascent metrics of all characters in the string. The descent member is set to the maximum of the descent metrics. The width member is set to the sum of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string. Let L be the left-side-bearing metric of the character plus W. Let R be the right-side-bearing metric of the character plus W. The lbearing member is set to the minimum L of all characters in the string. The rbearing member is set to the maximum R.
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. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics.
| Home |
|---|
To query the server for the bounding box of an 8-bit character string in a given font, use XQueryTextExtents.
XQueryTextExtents(display, font_ID, string, nchars, direction_return,
font_ascent_return, font_descent_return, overall_return)
Display *display;
XID font_ID;
char *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;
To query the server for the bounding box of a 2-byte character string in a given font, use XQueryTextExtents16 .
XQueryTextExtentsl6(display, font_ID, string, nchars, direction_return,
font_ascent_return, font_descent_return, overall_return)
Display *display;
XID font_ID;
XChar2b *string;
int nchars;
int *direction_return;
int *font_ascent_return, *font_descent_return;
XCharStruct *overall_return;
The XQueryTextExtents and XQueryTextExtents16 functions return the bounding box of the specified 8-bit and 16-bit character string in the specified font or the font contained in the specified GC. These functions query the X server and, therefore, suffer the round-trip overhead that is avoided by XTextExtents and XTextExtents16. Both functions return a XCharStruct structure, whose members are set to the values as follows.
The ascent member is set to the maximum of the ascent metrics of all characters in the string. The descent member is set to the maximum of the descent metrics. The width member is set to the sum of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string. Let L be the left-side-bearing metric of the character plus W. Let R be the right-side-bearing metric of the character plus W. The lbearing member is set to the minimum L of all characters in the string. The rbearing member is set to the maximum R.
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. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics.
Characters with all zero metrics are ignored. If the font has no defined default_char, the undefined characters in the string are also ignored.
XQueryTextExtents and XQueryTextExtents16 can generate BadFont and BadGC errors.
| Home |
|---|
This section discusses how to draw:
The fundamental text functions XDrawText and XDrawText16 use the following structures:
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 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.
| Home |
|---|
To draw 8-bit characters in a given drawable, use XDrawText.
XDrawText(display, d, gc, x, y, items, nitems) Display *display; Drawable d; GC gc; int x, y; XTextItem *items; int nitems;
To draw 2-byte characters in a given drawable, use XDrawText16.
XDrawTextl6(display, d, gc, x, y, items, nitems) Display *display; Drawable d; GC gc; int x, y; XTextltem16 *items; int nitems;
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 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 character image, as defined by the font in the GC, 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 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.
| Home |
|---|
To draw 8-bit characters in a given drawable, use XDrawString.
XDrawString(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; char *string; int length;
To draw 2-byte characters in a given drawable, use XDrawString16.
XDrawString16(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; XChar2b *string; int length;
Each character image, as defined by the font in the GC, 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. For fonts defined with 2-byte matrix indexing and used with XDrawString16, each byte is used as a byte2 with a byte1 of zero. Both functions use these GC components: function, plane-mask, fill-style, font, errors.
| Home |
|---|
Some applications, in particular terminal emulators, need to print image text in which both the foreground and background bits of each character are painted. This prevents annoying flicker on many displays.
To draw 8-bit image text characters in a given drawable, use XDrawImageString.
XDrawImageString(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; char *string; int length;
To draw 2-byte image text characters in a given drawable, use XDrawImageString16.
XDrawImageString16(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; XChar2b *string; int length;
The XDrawImageString16 function is similar to XDrawImageString except that it uses 2-byte or 16-bit characters. Both functions also use both the foreground and background pixels of the GC in the destination.
The effect is first to fill a destination rectangle with the background pixel defined in the GC and then to paint the text with the foreground pixel. The upper-left corner of the filled rectangle is at:
[x, y - font-ascent]
The overall-width, font-ascent, and font-descent are as would be returned by XQueryTextExtents using gc and string. The function and fill-style defined in the GC are ignored for these functions. The effective function is GXcopy, and the effective fill-style is FillSolid.
For fonts defined with 2-byte matrix indexing and used with XDrawlmageString, each byte is used as a byte2 with a byte1 of zero.
Both functions use these GC components: plane-mask, foreground, background, font, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask.
XDrawImageString and XDrawImageString16 can generate BadDrawable, BadGC, and BadMatch errors.
| Home |
|---|
Xlib provides functions that you can use to transfer images between a client and the server. Because the server may require diverse data formats, Xlib provides an image object that fully describes the data in memory and that provides for basic operations on that data. You should reference the data through the image object rather than referencing the data directly. However, some implementations of the Xlib library may efficiently deal with frequently used data formats by replacing functions in the procedure vector with special case functions. Supported operations include destroying the image, getting a pixel, storing a pixel, extracting a subimage of an image, and adding a constant to an image (see section 16.8).
All the image manipulation functions discussed in this section make use of the XImage structure, which describes an image as it exists in the client's memory.
| typedef struct_XImage { | |||
| int width, height; int xoffset; int format; char *data; int byte_order; int bitmap_unit; int bitmap_bit_order; int bitmap_pad; int depth; int bytes_per_line; int bits_per_pixel; unsigned long red_mask; unsigned long green_mask; unsigned long blue_mask; XPointer obdata; struct funcs { | /* size of image */ /* number of pixels offset in X direction */ /* XYBitmap, XYPixmap, ZPixmap */ /* pointer to image data */ /* data byte order, LSBFirst, MSBFirst */ /* quant. of scanline 8, 16, 32 */ /* LSBFirst, MSBFirst */ /* 8, 16, 32 either XY or ZPixmap */ /* depth of image */ /* accelerator to next scanline */ /* bits per pixel (ZPixmap) */ /* bits in z arrangement */ /* hook for the object routines to hang on */ /* image manipulation routines */ | ||
| struct_XImage
*(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct_XImage *(*sub_image)(); int (*add_pixel)(); | |||
| } f; | |||
| } XImage; | |||
To initialize the image manipulation routines of an image structure, use XInitImage.
Status XInitImage(image)
XImage *image;
The XInitImage function initializes the internal image manipulation routines of an image structure, based on the values of the various structure members. All fields other than the manipulation routines must already be initialized. If the bytes_per_line member is zero, XInitImage will assume the image data is contiguous in memory and set the bytes_per_line member to an appropriate value based on the other members; otherwise, the value of bytes_per_line is not changed. All of the manipulation routines are initialized to functions that other Xlib image manipulation functions need to operate on the type of image specified by the rest of the structure.
This function must be called for any image constructed by the client before passing it to any other Xlib function. Image structures created or returned by Xlib do not need to be initialized in this fashion.
This function returns a nonzero status if initialization of the structure is successful. It returns zero if it detected some error or inconsistency in the structure, in which case the image is not changed.
To combine an image with a rectangle of a drawable on the display, use XPutImage.
XPutImage(display, d, gc, image, src_x, src_y, dest_x, dest_y, width, height)
Display *display;
Drawable d;
GC gc;
XImage *image;
int src_x, src_y;
int dest_x, dest_y;
unsigned int width, height;
| Home |
|---|
The XPutImage function combines an image with a rectangle of the specified drawable. The section of the image defined by the src_x, src_y, width, and height arguments is drawn on the specified part of the drawable. If XYBitmap format is used, the depth of the image must be one, or a BadMatch error results. The foreground pixel in the GC defines the source for the one bits in the image, and the background pixel defines the source for the zero bits. For XYPixmap and ZPixmap, the depth of the image must match the depth of the drawable, or a BadMatch error results.
If the characteristics of the image (for example, byte_order and bitmap_unit) differ from what the server requires, XPutImage automatically makes the appropriate conversions.
This function uses these GC components: function, plane-mask, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground and background.
XPutImage can generate BadDrawable, BadGC, BadMatch, and BadValue errors.
To return the contents of a rectangle in a given drawable on the display, use XGetImage. This function specifically supports rudimentary screen dumps.
XImage *XGetImage(display, d, x, y, width, height, plane_mask, format)
Display *display;
Drawable d;
int x, y;
unsigned int width, height;
unsigned long plane_mask;
int format;
The XGetImage function returns a pointer to an XImage structure. This structure provides you with the contents of the specified rectangle of the drawable in the format you specify. If the format argument is XYPixmap, the image contains only the bit planes you passed to the plane_mask argument. If the plane_mask argument only requests a subset of the planes of the display, the depth of the returned image will be the number of planes requested. If the format argument is ZPixmap, XGetImage returns as zero the bits in all planes not specified in the plane_mask argument. The function performs no range checking on the values in plane_mask and ignores extraneous bits.
XGetImage returns the depth of the image to the depth member of the XImage structure. The depth of the image is as specified when the drawable was created, except when getting a subset of the planes in XYPixmap format, when the depth is given by the number of bits set to 1 in plane_mask.
If the drawable is a pixmap, the given rectangle must be wholly contained within the pixmap, or a BadMatch error results. If the drawable is a window, the window must be viewable, and it must be the case that if there were no inferiors or overlapping windows, the specified rectangle of the window would be fully visible on the screen and wholly contained within the outside edges of the window, or a BadMatch error results. Note that the borders of the window can be included and read with this request. If the window has backing-store, the backing-store contents are returned for regions of the window that are obscured by noninferior windows. If the window does not have backing-store, the returned contents of such obscured regions are undefined. The returned contents of visible regions of inferiors of a different depth than the specified window's depth are also undefined. The pointer cursor image is not included in the returned contents. If a problem occurs, XGetImage returns NULL.
XGetImage can generate BadDrawable, BadMatch, and BadValue errors.
To copy the contents of a rectangle on the display to a location within a preexisting image structure, use XGetSubImage.
XImage *XGetSubImage(display, d, x, y, width, height, plane_mask, format,
dest_image, dest_x, dest_y)
Display *display;
Drawable d;
int x, y;
unsigned int width, height;
unsigned long plane_mask;
int format;
XImage *dest_image;
int dest_x, dest_y;
The XGetSubImage function updates dest_image with the specified subimage in the same manner as XGetImage. If the format argument is XYPixmap, the image contains only the bit planes you passed to the plane_mask argument. If the format argument is ZPixmap, XGetSublmage returns as zero the bits in all planes not specified in the plane_mask argument. The function performs no range checking on the values in plane_mask and ignores extraneous bits. As a convenience, XGetSubImage returns a pointer to the same XImage structure specified by dest_image.
The depth of the destination XImage structure must be the same as that of the drawable. If the specified subimage does not fit at the specified location on the destination image, the right and bottom edges are clipped. If the drawable is a pixmap, the given rectangle must be wholly contained within the pixmap, or a BadMatch error results. If the drawable is a window, the window must be viewable, and it must be the case that if there were no inferiors or overlapping windows, the specified rectangle of the window would be fully visible on the screen and wholly contained within the outside edges of the window, or a BadMatch error results. If the window has backing-store, then the backing-store contents are returned for regions of the window that are obscured by noninferior windows. If the window does not have backing-store, the returned contents of such obscured regions are undefined. The returned contents of visible regions of inferiors of a different depth than the specified window's depth are also undefined. If a problem occurs, XGetSubImage returns NULL.
XGetSubImage can generate BadDrawable, BadGC, BadMatch, and BadValue errors.
| Home |
|---|
| Contents | Previous Chapter | Next Chapter |