Description
XDeleteProperty deletes a window property, so that it no longer contains any data. Its atom, specified by property, still exists after the call so that it can be used again later by any application to set the property once again. If the property was defined on the specified window, XDeleteProperty generates a PropertyNotify event.
See the introduction to properties in Volume One, Chapter 2, X Concepts, or more detailed information in Volume One, Chapter 10, Interclient Communication.
Errors
BadAtom BadWindow
Related Commands
XChangeProperty,XGetAtomName,XGetFontProperty, XGetWindowProperty, XInternAtom, XListProperties, XRotateWindowProperties,XSetStandard-Properties.
132 xiib Reference Manual
— Xlib - Association Tables-
J XDestroyAssocTable
Name
XDestroyAssocTable — free the memory allocated for an association table.
Synopsis
XDestroyAssocTable(table) XAssocTable *table;
Arguments
tabl e Specifies the association table whose memory is to be freed.
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <Xll/X10.h> and link with the library -loldX.
Using an XAssocTable after it has been destroyed will have unpredictable consequences. For more information on association tables, see Volume One, Appendix B, XI0 Compatibility.
Structures
typedef struct {
XAssoc ^buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */
} XAssocTable;
Related Commands
XCreateAssocTable,XDeleteAssoc,XLookUpAssoc,XMakeAssoc.
XDestroylmage\ x,,b-,ma ge s-
Name
XDestroylmage — deallocate memory associated with an image.
Synopsis
int XDestroylmage (ximage) Xlmage * ximage;
Arguments
ximage Specifies a pointer to the image.
Description
XDestroylmage deallocates the memory associated with an Ximage structure. This mem ory includes both the memory holding the ximage structure, and the memory holding the actual image data. (If the image data is statically allocated, the pointer to the data in the Ximage structure must be set to zero before calling XDestroylmage.)
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. Related Commands
ImageByteOrder, XAddPixel, XCreatelmage, XGet Image, XGetPixel, XGet-Sublmage,XPutImage,XPutPixel,XSubImage.
-x,, b - Regions / XDestroyRegion
Name
XDestroyRegion — deallocate storage associated with a region.
Synopsis
XDestroyRegion(r) Region r;
Arguments
r Specifies the region to be destroyed.
Description
XDestroyRegion frees the memory associated with a region and invalidates pointer r.
See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions.
Related Commands
XClipBox, XCreateRegion, XEmptyRegion, XEqualRegion,Xlntersect-Region,XOffsetRegion,XPointlnRegion,XPolygonRegion,XRectlnRegion, XSetRegion,XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.
XDestroySubwindows
Xlib - Window Existence —
Name
XDestroySubwindows — destroy all subwindows of a window.
Synopsis
XDestroySubwindows( display, w) Display * display ; Window w;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window whose subwindows are to be destroyed.
Description
This function destroys all descendants of the specified window (recursively), in bottom to top stacking order.
XDestroySubwindows generates exposure events on window »/, if any mapped subwindows were actually destroyed. This is much more efficient than deleting many subwindows one at a time, since much of the work need only be performed once for all of the windows rather than for each window. It also saves multiple exposure events on the windows about to be destroyed. The subwindows should never again be referenced.
xcioseDisplay automatically destroys all windows that have been created by that client on the specified display (unless called after a fork system call).
Never call XDestroySubwindows with the window argument set to the root window! This will destroy all the applications on the screen, and if there is only one screen, often the server as well.
Errors
BadWindow
Related Commands
XCreateSimpleWindow,XCreateWindow, XDestroyWindow.
— Xlib - Window Existence-
J XDestroyWindow
Name
XDestroyWindow — unmap and destroy a window and all subwindows.
Synopsis
XDestroyWindow(display, window) Display *display; Window window;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
window Specifies the ID of the window to be destroyed.
Description
If window is mapped, an UnmapWindow request is performed automatically. The window and all inferiors (recursively) are then destroyed, and a DestroyNotify event is generated for each window. The ordering of the DestroyNotif y events is such that for any given win dow, DestroyNotif y is generated on all inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise con strained.
The windows should never again be referenced.
Destroying a mapped window will generate exposure events on other windows that were obscured by the windows being destroyed. XDestroyWindow may also generate Enter-Notify events if window was mapped and contained the pointer.
No windows are destroyed if you try to destroy the root window.
Errors
BadWindow
Related Commands
XCreateSimpleWindow, XCreateWindow, XDestroySubwindows.
XDisableAccessControl \ X||b _ Host Accass _
Name
XDisableAccessControl — allow access from any host.
Synopsis
XDisableAccessControl(display) Display * display;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
Description
XDisableAccessControl instructs the server to allow access from clients on any host. This disables use of the host access list.
This routine can only be called from a client running on the same host as the server.
For more information on access control, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadAccess
Related Commands
XAddHost,XAddHosts, XEnableAccessControl,XListHosts, XRemoveHost, XRemoveHosts,XSetAccessControl.
—Xlib - Window Manager Hints-
XDisplayKeycodes
Name
XDisplayKeycodes — obtain the range of legal keycodes for a server.
Synopsis
XDisplayKeycodes(display, min_keycodes, max_keycodes) Display *display; int *min_keycode r *max_keycode; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
min_keycode Returns the minimum keycode. max_keycode Returns the maximum keycode.
Description
XDisplayKeycodes returns the min_keycode and max_keycode supported by the specified server. The minimum keycode returned is never less than 8, and the maximum key-code returned is never greater than 255. Not all keycodes in this range are required to have cor responding keys.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Related Commands
XKeycodeToKeysym, XKeysymToKeycode,XLookupString.
XDisplayName \
•Xlib-Error Handling-
Name
XDisplayName — report the display name (when connection to a display fails).
Synopsis
char *XDisplayName (string) char *string;
Arguments
string Specifies the character string.
Description
XDisplayName is normally used to report the name of the display the program attempted to open with xopenDisplay. This is necessary because X error handling begins only after the connection to the server succeeds. If a NULL string is specified, XDisplayName looks in the DISPLAY environment variable and returns the display name that the user was requesting. Otherwise, XDisplayName returns its own argument. This makes it easier to report to the user precisely which server the program attempted to connect to.
For more information, see Volume One, Chapter 3, Basic Window Program. Related Commands
XGetErrorDatabaseText,XGetErrorText,XSetAfterFunction,XSetError-Handler, XSetlOErrorHandler,XSynchronize.
— Xlib - Drawing Primitives '
Name
XDraw — draw a polyline or curve between vertex list (from XI0). Synopsis
Status XDraw( display, drawable, gc f vllst, vcount) Display *dlsplay; Drawable drawable; GC gc;
Vertex *vllst; int vcount;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
vllst Specifies a pointer to the list of vertices that indicates what to draw.
vcount Specifies how many vertices are in vllst.
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <Xll/X10.h> and link with the library -loldX. Its performance is likely to be low.
XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of vertices (vllst). The points are connected by lines as specified in the flags each the Vertex structure.
The Vertex structure contains an x,y coordinate and a bitmask called flags that specifies the drawing parameters.
The x and y elements of Vertex are the coordinates of the vertex that are relative to either the previous vertex (if VertexRelative is 1) or the upper-left inside corner of the drawable (if VertexRelative is 0). If VertexRelative is 0 the coordinates are said to be absolute. The first vertex must be an absolute vertex.
If the VertexDontDraw bit is 1, no line or curve is drawn from the previous vertex to this one. This is analogous to picking up the pen and moving to another place before drawing another line.
If the VertexCurved bit is 1, a spline algorithm is used to draw a smooth curve from the pre vious vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the previous vertex to this one. It makes sense to set VertexCurved to 1 only if a previous and next vertex are both defined (either explicitly in the array, or through the definition of a closed curve—see below.)
It is permissible for VertexDontDraw bits and VertexCurved bits to both be 1. This is useful if you want to define the previous point for the smooth curve, but you do not want an actual curve drawing to start until this point.
XDraw (continued) Xlib - Drawing Primitives
If VertexStartClosed bit is 1, then this point marks the beginning of a closed curve. This vertex must be followed later in the array by another vertex whose absolute coordinates are identical and which has VertexEndClosed bit of 1. The points in between form a cycle for the purpose of determining predecessor and successor vertices for the spline algorithm.
XDraw achieves the effects of the X10 XDraw, XDrawDashed, and XDrawPatterned functions.
XDraw uses the following graphics context 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. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
A Status of zero is returned on failure, and nonzero on success.
For more information, see Volume One, Appendix B, XI0 Compatibility.
Structures
typedef struct _Vertex {
short x,y;
unsigned short flags; } Vertex;
/* defined constants for use as flags */
#define VertexRelative 0x0001 /* else absolute */
#define VertexDontDraw 0x0002 /* else draw */
#define VertexCurved 0x0004 /* else straight */
#define VertexStartClosed 0x0008 /* else not */
#define VertexEndClosed 0x0010 /* else not */
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDrawArc,XDrawArcs, XDrawFilled,XDrawLine,XDrawLines,XDrawPoint,XDrawPoints,XDraw-Rectangle, XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFill-Polygon,XFillRectangle, XFillRectangles.
Xlib Reference Manual
.. J XDrawArc
—Xlib - Drawing Primitives *
Name
XDrawArc — draw an arc fitting inside a rectangle.
Synopsis
XDrawArc (display, drawable, gc, x f y, width, height,
anglel, angle2) Display *display; Drawable drawable ; GC gc; int x r y;
unsigned int width, height; int anglel, angle2;
Arguments
display Specifies a connection to an X server; returned from xopenoisplay.
drawa&le Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the upper-left corner of the rectangle that
y contains the arc, relative to the origin of the specified drawable.
width Specify the width and height in pixels of the major and minor axes of the arc.
height
anglel Specifies the start of the arc relative to the three-o'clock position from the
center. Angles are specified in 64ths of a degree (360 * 64 is a complete circle).
angle2 Specifies the end of the arc relative to the start of the arc. Angles are speci
fied in 64ths of a degree (360 * 64 is a complete circle).
Description
XDrawArc draws a circular or elliptical arc. An arc is specified by a rectangle and two angles. The x and y coordinates are relative to the origin of the drawable, and define the upper-left cor ner of the rectangle. 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, respectively. The angles are signed integers in 64ths of a degree, with positive values indicating counterclockwise motion and negative values indicating clockwise motion, truncated to a maximum of 360 degrees. The start of the arc is specified by anglel relative to the three-o'clock position from the center, and the path and extent of the arc is specified by angle2 relative to the start of the arc.
By specifying one axis to be zero, a horizontal or vertical line is drawn (inefficiently).
Angles are computed based solely on the coordinate system and ignore the aspect ratio. In other words, if the bounding rectangle of the arc is not square and anglel is zero and angle2 is (45x64), a point drawn from the center of the bounding box through the endpoint of the arc will not pass through the corner of the rectangle.
XDrawArc
(continued)
Xlib - Drawing Primitives
For any given arc, no pixel is drawn more than once, even if angle2 is greater than anglel by more than 360 degrees.
XDrawArc uses these graphics context 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. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text,
width
6 o'clock
Angle = 270x64=17280 Angle = -( 90x64)=5760
Center of bounding rectangle.
3 o'clock
Angle = 0
Example 1:
Arc from A1 to A2, Counterclockwise
A1 = 90 X 64
A2 = 45 X 64
Example 2:
Arc from B1 to B2, Clockwise
B1 = 270 X 64
B2 = -(45X64)
Errors
BadDrawable
BadGC
BadMatch
144
Xlib Reference Manual
Xlib - Drawing Primitives (continued) XDrawArc
Related Commands
XClearArea,XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArcs, XDrawFilled, XDrawLine,XDrawLines,XDrawPoint, XDrawPoints,XDraw-Rectangle,XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFill-Polygon,XFillRectangle, XFillRectangles.
XDrawArcs
X
•Xlib - Drawing Primitives-
Name
XDrawArcs — draw multiple arcs.
Synopsis
XDrawArcs( display, drawable , Display * display ; Drawable drawable; GC gc; XArc *arcs; int r>arcs;
gc, arcs, narcs)
Arguments
di splay
drawable
gc
arcs
narcs
Specifies a connection to an X server; returned from XOpenDisplay. Specifies the drawable. Specifies the graphics context. Specifies a pointer to an array of arcs. Specifies the number of arcs in the array.
width
6 o'clock
Angle = 270x64=17280 Angle = - (90x64)=5760
Example 1:
Arc from A1 to A2, Counterclockwise
A1 = 90 X 64
A2 = 45 X 64
Center of bounding rectangle.
3 o'clock
Angle = 0
Example 2:
Arc from 81 to B2, Clockwise
B1 = 270 X 64
B2 = -(45X64)
146
Xlib Reference Manual
Xlib - Drawing Primitives (continued) XDrawArcs
Description
This is the plural version of XDrawArc. See XDrawArc for details of drawing a single arc.
There is a limit to the number of arcs that can be drawn in a single call. It varies according to the server. To determine how many arcs you can draw in a single call, find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by three: this is the maximum number of arcs you can draw in a single XDrawArcs call.
The arcs are drawn in the order listed in the arcs array.
By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are com puted based solely on the coordinate system, ignoring the aspect ratio.
For any given arc, no pixel is drawn more than once. 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. If two arcs join correctly and if line_width is greater than 0 and the arcs intersect, no pixel is drawn 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.
XDrawArcs uses these graphics context 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. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
The following is a technical explanation of the points drawn by XDrawArcs. For an arc speci fied as [x, y, width, height, anglel, angle2 ], the origin of the major and minor axes is at [x+ (width/2), y+ (height 12 ) ], 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. That is, they are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line width line_width, the bounding outlines for filling are given by the infinitely thin paths describing the arcs:
[x+dx/2, y+dy/2, width-dx, height-dy, anglel, angle2]
and
[x-line_width/2, y-line_width/2, width+line_width, height+line_width, anglel, angle2]
where
dx=min(line_width,width) dy=min(line width,height)
XDrawArcs (continued) Xlib - Drawing Primitives
If (height ! = width) 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 rela tionship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows:
skewed-angle = atan(tan(normal-angle) * width/height) + adjust
The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree) in the range [0,2*PI], and where atan returns a value in the range [-PI/2, PI/2] ,and where adjust is:
0 for normal-angle in the range [0,PI/2]
PI for normal-angle in the range [PI/2, (3*PI)/2]
2*PI for normal-angle in the range [ (3*PI)/2,2*PI]
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. Structures
typedef struct {
short x, y;
unsigned short width, height;
short anglel, angle2; /* Start and end of arc, in */
/* 64ths of degrees */ } XArc;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea,XClearWindow, XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawFilled,XDrawLine,XDrawLines,XDrawPoint,XDrawPoints,XDraw-Rectangle, XDrawRectangles,XDrawSegments,XFillArc,XFillArcs,XFill-Polygon,XFillRectangle, XFillRectangles.
-Xlib - Drawing Primmv.s / XDrawFilted
Name
XDrawFilled — draw a filled polygon or curve from vertex list (from X10).
Synopsis
Status XDrawFilled(display, drawable, gc, vlist, vcount) Display *display; Drawable drawable ; GC gc;
Vertex *vlist; int vcount ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
vl i s t Specifies a pointer to the list of vertices.
vcount Specifies how many vertices are in v 1 i s t.
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <XlllX10.h> and link with the library -loldX. XDrawFilled achieves the effects of the X Version 10 XDrawTiled and XDrawFilled functions.
XDrawFilled draws arbitrary polygons or curves, according to the same rules as XDraw, and then fills them.
XDrawFilled uses the following graphics context 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. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, dash_list, f ill_style and f ill_rule.
XDrawFilled returns a Status of zero on failure, and nonzero on success. For more information, see Volume One, Appendix B,X10 Compatibility.
Related Commands
XClearArea,XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawLine,XDrawLines,XDrawPoint, XDrawPoints,XDraw-Rectangle,XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFill-Polygon,XFillRectangle, XFillRectangles.
XDrawlmageString \
•Xlib-Text-
Name
XDrawlmageString — draw 8-bit image text characters.
Synopsis
XDrawlmageString( display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x f y; char *string; int length;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the image
y text character, relative to the origin of the specified drawable.
string Specifies the character string.
length Specifies the number of characters in the st ring argument.
Description
XDrawlmageString draws a string, but unlike XDrawString it draws both the foreground and the background of the characters. It draws the characters in the foreground and fills the bounding box with the background.
XDrawlmageString uses these graphics context components: plane_mask, fore ground, background, font, subwindow_mode, clip_x_origin, clip_y_ origin, and clip_mask. The function and fill_style defined in gc are ignored; the effective function is GXcopy and the effective f ill_style is FillSolid.
XDrawlmageString first fills a destination rectangle with the background pixel defined in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled rectangle is at [x, y - font_ascent], the width is overall->width and the height is ascent + descent, where overall->width, ascent, and descent are as would be returned by XQueryTextExtents using gc and string.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
xiib - Text (continued) XDrawlmageString
Related Commands
XDrawImageStringlS, XDrawString, XDrawStringl6, XDrawText, XDraw-Textl6,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents, XText-Extentsl6,XTextWidth,XTextWidthl6.
XDrawlmageStri ng16 \
•Xlib-Text—
Name
XDrawImageStringl6 — draw 16-bit image text characters.
Synopsis
XDrawImageStringl6(display, drawable, gc, x, y, string, length) Display * display; Drawable drawable; GC gc; int x r y; XChar2b *string; int length;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the image
y text character, relative to the origin of the specified drawable.
string Specifies the character string.
length Specifies the number of characters in the string argument.
Description
XDrawlmageStringl6 draws a string, but unlike XDrawStringl6 it draws both the fore ground and the background of the characters. It draws the characters in the foreground and fills the bounding box with the background.
XDrawlmageStringl6 uses these graphics context components: plane_mask, fore ground, background, font, subwindow_mode, clip_x_origin, clip_y_ origin, and clip_mask. The function and fill_style defined in gc are ignored; the effective function is GXcopy and the effective f ill_style is FillSolid.
XDrawlmageStringlG first fills a destination rectangle with the background pixel defined in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled rectangle is at [x, y - font_ascent], the width is overall->width and the height is ascent + descent, where overall->width, ascent, and descent are as would be returned by XQueryTextExtentslG using gc and string.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
unsigned char bytel;
unsigned char byte2; } XChar2b;
- Text (continued) XDrawlmageStringl 6
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDrawImageString,XDrawString,XDrawStringl6,XDrawText,XDrawTextl6 :
XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText-
Extentsl6,XTextWidth,XTextWidthl6.
XDrawLine \ _ Xllb _ Drawlng Pr|m|tives _
Name
XDrawLine — draw a line between two points.
Synopsis
XDrawLine ( display, drawable, gc, xl , yl , x2 , y2) Display * display; Drawable dravrable; GC gc; int xl r yl r x2, y2 ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
xl Specify the coordinates of the endpoints of the line relative to the drawable
yl origin. XLine connects point (xl , yl) to point (x2, y2).
x2
Description
XDrawLine uses the components of the specified graphics context to draw a line between two points in the specified drawable. No pixel is drawn more than once.
XDrawLine uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, fill_style, subwindow_mode, clip_ x_origin, clip_y_origin, and clip_mask. XDrawLine also uses these graphics con text mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Errors
BadDrawable Specified drawable is invalid.
BadGC Specified GC is invalid, or does not match the depth of drawable.
BadMatch Specified drawable is an inputOnly window.
Related Commands
XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDrawPoints, XDraw-Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill-Polygon, XFillRectangle, XFillRectangles.
-X..b - Drawing Primitives - /
Name
XDrawLines — draw multiple connected lines.
Synopsis
XDrawLines ( display, drawable, gc , points, npoints, mode) Display *display; Drawable drawable; GC gc;
XPoint *points; int npoints; int mode ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
point s Specifies a pointer to an array of points.
npoints Specifies the number of points in the array.
mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord-
ModePrevious.
Description
XDrawLines draws a series of lines joined end-to-end.
It draws lines connecting each point in the list (points array) to the next point in the list. The lines are drawn in the order listed in the points array. For any given line, no pixel is drawn more than once. If thin (zero line width) lines intersect, pixels will be drawn multiple times. If the first and last points coincide, the first and last lines will join correctly. If wide lines inter sect, the intersecting pixels are drawn only once, as though the entire multiline request were a single filled shape.
There is a limit to the number of lines that can be drawn in a single call, that varies according to the server. To determine how many lines you can draw in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by two, and this is the maximum number of lines you can draw in a single XDrawLines call.
The mode argument may have two values:
CoordModeOrigin indicates that all points are relative to the drawable's origin.
• CoordModePrevious indicates that all points after the first are relative to the previ ous point. (The first point is always relative to the drawable's origin.)
XDrawLines uses the following components of the specified graphics context to draw multi ple connected lines in the specified drawable: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode,
XDrawLlnes (continued) Xlib - Drawing Primitives
clip_x_origin, clip_y_ origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct { short x, y; } XPoint;
Errors
BadDrawable Specified drawable is invalid.
BadGC Specified GC is invalid, or does not match the depth of drawable.
BadMatch Specified drawable is an InputOnly window. BadValue Invalid coordinate_mode.
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawPoint,XDrawPoints,XDraw-Rectangle, XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFill-Polygon,XFillRectangle, XFillRectangles.
-X,,b- Drawing Primitives / XDrawPoint
Name
XDrawPoint — draw a point.
Synopsis
XDrawPoint( display, drawable, gc, x r y) Display *display; Drawable drawable; GC gc; int x r y;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the point, relative to the origin of the draw-
y able.
Description
XDrawPoint draws a single point into the specified drawable. XDrawPoint uses these graphics context components: function, plane_mask, foreground, subwin-dow_mode, clip_x_origin, clip_y_origin, and clip_mask. Use XDrawPoints to draw multiple points.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea,XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoints,XDraw-Rectangle,XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFill-Polygon,XFillRectangle, XFillRectangles.
XDrawPoints \ Xllb _ Drawing Pr|m|tives _
Name
XDrawPoints — draw multiple points.
Synopsis
XDrawPoints( display, drawable, gc, points, npoints, mode) Display ^display; Drawable drawable; GC gc;
XPoint *points; int npoints; int mode;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
points Specifies a pointer to an array of XPoint structures containing the positions
of the points.
npoints Specifies the number of points to be drawn.
mode Specifies the coordinate mode. CoordModeOrigin treats all coordinates as
relative to the origin, while CoordModePrevious treats all coordinates after the first as relative to the previous point, while the first is still relative to the origin.
Description
XDrawPoints draws one or more points into the specified drawable.
There is a limit to the number of points that can be drawn in a single call, that varies according to the server. To determine how many points you can draw in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract 3 and this is the maxi mum number of points you can draw in a single XDrawPoints call.
XDrawPoints uses these graphics context components: function, plane_mask, fore ground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct { short x, y; } XPoint;
Xlib - Drawing Primitives (continued) XDrawPointS
Errors
BadDrawable BadGC BadMatch BadValue
Related Commands
XClearArea,XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPointS,XDraw-Rectangle,XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFill-Polygon,XFillRectangle,XFillRectangles.
XDrawRectangle
X
•Xllb - Drawing Primitives—
Name
XDrawRectangle — draw an outline of a rectangle.
Synopsis
XDrawRectangle (display, drawable, gc, x, y, width, height) Display * display; Drawable drawable; GC gc; int x r y; unsigned int width, height;
Arguments
di spl ay
drawable
gc
x
y
width height
Specifies a connection to an X server; returned from XOpenDisplay. Specifies the drawable. Specifies the graphics context.
Specify the x and y coordinates of the upper-left corner of the rectangle, rela tive to the drawable's origin.
Specify the width and height in pixels. These dimensions define the outline of the rectangle.
20 pixels
20 pixels
Description
XDrawRectangle draws the outline of the rectangle by using the x and y coordinates, width and height, and graphics context you specify. Specifically, XDrawRectangle uses these graphics context 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. This function also uses these graphics con text mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For the specified rectangle, no pixel is drawn more than once.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
160
Xlib Reference Manual
Xlib - Drawing Primitives (continued) X Draw Rectangle
Structure
typedef struct {
short x, y;
unsigned short width, height; } XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw,XDrawArc, XDrawArcs,XDrawFilled,XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFillPolygon, XFillRectangle,XFillRectangles.
XDrawRectangles
X
•Xlib - Drawing Primitives-
Name
XDrawRectangles — draw the outlines of multiple rectangles.
Synopsis
XDrawRectangles(display, drawable, gc, rectangles, nrectangles) Display *display; Drawable drawa≤ GC gc;
XRectangle rectangles [] ; int nrectangles;
Arguments
di splay Specifies a connection to an X server; returned from xopenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
rectangles Specifies a pointer to an array of rectangles containing position and size information.
nrectangles Specifies the number of rectangles in the array.
20 pixels
Description
XDrawRectangles draws the outlines of the specified rectangles by using the position and size values in the array of rectangles. The x and y coordinates of each rectangle are relative to the drawable's origin, and define the upper-left corner of the rectangle.
The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, pixels are drawn multiple times.
There is a limit to the number of rectangles that can be drawn in a single call. It varies accord ing to the server. To determine how many rectangles you can draw in a single call, find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by two. This is the maximum number of rectangles you can draw in a single XDraw Rectangles call.
This function uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwin-dow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawRectangles
162
Xlib Reference Manual
Xlib - Drawing Primitives (continued) XDrawRectangles
also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height; } XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint, XDrawPoints, XDrawRectangle, XDrawSegments,XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles.
XDrawSegments \
•Xlib - Drawing Primitives-
Name
XDrawSegments — draw multiple disjoint lines.
Synopsis
XDrawSegments(display, drawable, gc, segments, nsegments) Display *display; Drawable drawable; GC gc;
XSegment * segments; int nsegments;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
segments Specifies a pointer to an array of line segments.
nsegmen ts Specifies the number of segments in the array.
Description
XDrawSegments draws multiple line segments into the specified drawable. Each line is specified by a pair of points, so the line may be connected or disjoint.
For each segment, XDrawSegments draws a line between (xl, yl) and (x2, y2). The lines are drawn in the order listed in segments. For any given line, no pixel is drawn more than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn sepa rately, without regard to the join_style.
There is a limit to the number of segments that can be drawn in a single call. It varies accord ing to the server. To determine how many segments you can draw in a single call, find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by two. This is the maximum number of segments you can draw in a single XDrawSegments call.
XDrawSegments uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, fill_style, subwindow__mode, clip_ x_origin, clip_y_origin, and clip_mask. XDrawSegments also uses these graph ics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_of f set, and dash_list.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
short xl, yl, x2, y2; } XSegment;
Xlib - Drawing Primitives (continued) XDrawSegmentS
Errors
BadDrawable Specified drawable is invalid.
BadGC Specified GC is invalid, or does not match the depth of drawable.
BadMatch Specified drawable is an InputOnly window.
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs, XDrawFilled,XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangle,XDrawRectangles,XFillArc, XFillArcs, XFillPolygon, XFillRectangle,XFillRectangles.
XDrawString \
•Xlib-Text—
Name
XDrawString — draw an 8-bit text string, foreground only.
Synopsis
XDrawString (display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x, y; char *string; int length;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wai>l e Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the char-
y acter, relative to the origin of the specified drawable.
string Specifies the character string.
length Specifies the number of characters in st ring.
Description
XDrawString draws the given string into a drawable using the foreground only to draw set bits in the font. It does not affect any other pixels in the bounding box for each character.
The y coordinate defines the baseline row of pixels while the x coordinate is the point from which Ibearing, rbearing, and width are measured.
XDrawString uses these graphics context components: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character image, as defined by the font in gc, is treated as an additional mask for a fill operation on the drawable.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Errors
BadDrawable BadFont BadGC BadMatch
Xiib-Text (continued) XDrawString
Related Commands
XDrawImageString,XDrawImageStringl6, XDrawStringl6, XDrawText, XDrawTextl6,XQueryTextExtents,XQueryTextExtentslG,XTextExtents, XTextExtentsl6,XTextWidth,XTextWidthlG.
XDrawString16 , xnb _ Text _
Name
XDrawStringl6 — draw two-byte text strings.
Synopsis
XDrawStringl6(display, drawable, gc, x, y f string, length) Display * display; Drawable drawable; GC gc ; int x, y; XChar2b *string; int length;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDisplay.
draw-able Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the char-
y acter, relative to the origin of the specified drawable.
string Specifies the character string. Characters are two bytes wide.
length Specifies the number of characters in string.
Description
XDrawStringl6 draws a string in the foreground pixel value without drawing the surround ing pixels.
The y coordinate defines the baseline row of pixels while the x coordinate is the point from which Ibearing, rbearing, and width are measured. For more information on text placement, see Volume One, Chapter 6, Drawing Graphics and Text.
XDrawStringl6 uses these graphics context components: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character image, as defined by the font in gc, is treated as an additional mask for a fill operation on the drawable.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
unsigned char bytel;
unsigned char byte2; } XChar2b;
Xlib Reference Manual
Xiib-Text (continued) XDrawString16
Errors
BadDrawable BadFont BadGC BadMatch
Related Commands
XDrawImageString,XDrawImageStringlG,XDrawString,XDrawText,XDraw-Textl6,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText-Extentsl6,XTextWidth, XTextWidthl6.
Xlib Reference Manual
Name
XDrawText — draw 8-bit polytext strings.
Synopsis
XDrawText( display, drawable, gc, x, y, Items, nltems) Display *dlsplay; Drawable drawable; GC gc; int x, y; XTextltem * Items; int nltems;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the initial
y string, relative to the origin of the specified drawable.
i t ems Specifies a pointer to an array of text items.
nl terns Specifies the number of text items in the Items array.
Description
XDrawText is capable of drawing multiple strings on the same horizontal line and changing fonts between strings. Each XTextltem structure contains a string, the number of characters in the string, the delta offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each XTextltem is stored in the specified GC and used for subsequent text. If the XTextltem. font is None, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is permitted.
The delta in each XTextltem specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the draw direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8, the string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The delta for the second string begins at the rbearing of the last character in the first string. A negative delta would tend to overlay subsequent strings on the end of the previous string.
Only the pixels selected in the font are drawn (the background member of the GC is not used to fill the bounding box).
There is a limit to the number and size of strings that can be drawn in a single call, that varies according to the server. To determine how much text you can draw in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract four, and then sub tract ( (strlen (string) +2) / 4) for each string. This is the maximum amount of text you can draw in a single XDrawText call.
170 Xlib Reference Manual
Xlib-Text (continued) XDrawText
XDrawText uses the following elements in the specified GC: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
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 */
} XTextltem;
Errors
BadDrawable BadFont BadGC BadMatch
Related Commands
XDrawImageString,XDrawImageStringl6,XDrawString, XDrawStringlS, XDrawTextlS, XQueryTextExtents,XQueryTextExtentslS,XTextExtents, XTextExtentsl6,XTextWidth,XTextWidthlG.
XDrawText16 \ X|ib Tex( _
Name
XDrawTextl6 — draw 16-bit poly text strings.
Synopsis
XDrawTextlS( display, drawable, gc, x, y, items, nitems) Display * display; Drawable drawable; GC gc; int x r y;
XTextIteml6 * items; int nitems;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the baseline starting position for the initial
y string, relative to the origin of the specified drawable.
items Specifies a pointer to an array of text items using two-byte characters,
nit ems Specifies the number of text items in the array.
Description
XDrawTextlG is capable of drawing multiple strings on the same horizontal line and chang ing fonts between strings. Each XTextltem structure contains a string, the number of charac ters in the string, the delta offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each XTextltem is stored in the specified GC and used for subsequent text. If the XTextIteml6 . font is None, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is per mitted.
The delta in each XTextltem specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the drawing direction of the font. For example, if x = 40,y = 20, and items [0] .delta = 8, the string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The delta for the second string begins at the rbearing of the last character in the first string. A negative delta would tend to overlay subsequent strings on the end of the previous string.
Only the pixels selected in the font are drawn (the background member of the GC is not used to fill the bounding box).
There is a limit to the number and size of strings that can be drawn in a single call, that varies according to the server. To determine how much text you can draw in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract four, and then sub tract ( (strlen (string) +2) / 4) for each string. This is the maximum amount of text you can draw in a single XDrawText 16 call.
Xlib - Text
(continued)
XDrawText16
XDrawText 16 uses the following elements in the specified GC: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin.
Note that the chars member of the XText Iteml 6 structure is of type XChar2b, rather than of type char as it is in the XText Item structure. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server will interpret each member of the XChar2b structure as a 16-bit number that has been transmitted most significant byte first. In other words, the bytel member of the XChar2b structure is taken as the most significant byte.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
/* 2 byte characters */
/* number of characters */
/* delta between strings */
/* font to print it in, None don't change
/* normal 16 bit characters are two bytes */
Structures
typedef struct {
XChar2b *chars; int nchars; int delta;
Font font; } XTextltemlG;
typedef struct {
unsigned char bytel;
unsigned char byte2; } XChar2b;
Errors
BadDrawable BadFont BadGC BadMatch
Related Commands
XDrawImageString,XDrawImageStringl6,XDrawString,XDrawStringl6, XDrawText,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents, XTextExtentslG,XTextWidth, XTextWidthl6.
Xlib Reference Manual
XEmptyRegion \
-Xlib- Regions-
Name
XEmptyRegion — determine if a region is empty.
Synopsis
Bool XEmptyRegion(r) Region r;
Arguments
r Specifies the region to be checked.
Description
XEmptyRegion will return True if the specified region is empty, or False otherwise.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion,XDestroyRegion,XEqualRegion, Xlntersect-Region,XOffsetRegion,XPointlnRegion,XPolygonRegion,XRectlnRegion, XSetRegion,XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnionRegion, XXorRegion.
-x,,b - HO,« Access / XEnableAccessControl
Name
XEnableAccessControl — use access control list to allow or deny connection requests.
Synopsis
XEnableAccessControl(display) Display * display ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
Description
XEnableAccessControl instructs the server to use the host access list to determine whether access should be granted to clients seeking a connection with the server.
By default, the host access list is used. If access has not been disabled with XDisable-AccessControl or XSetAccessControl, this routine does nothing.
This routine can only be called by clients running on the same host as the server. For more information, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadAccess
Related Commands
XAddHost,XAddHosts, XDisableAccessControl,XListHosts, XRemoveHost, XRemoveHosts,XSetAccessControl.
XEqualRegion
Xlib - Regions-Name
XEqualRegion — determine if two regions have the same size, offset, and shape.
Synopsis
Bool XEqualRegion (rl, r2) Region rl, r2;
Arguments
rl Specify the two regions you want to compare.
r2
Description
XEqualRegion returns True if the two regions are identical; i.e., they have the same offset, size and shape, or False otherwise.
Regions are located using an offset from a point (the region origin) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion,XDestroyRegion,XEmptyRegion, Xlntersect-Region,XOffsetRegion,XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion,XShrinkRegion,XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.
-Xlib - Resource Manager /
Name
XEventsQueued — check the number of events in the event queue.
Synopsis
int XEventsQueued( display, mode) Display * display; int mode;
Arguments
display Specifies a connection to a Display structure, returned from XOpen-
Display.
mode Specifies whether the request buffer is flushed if there are no events in Xlib's
queue. You can specify one of these constants: QueuedAlready, QueuedAfterFlush, QueuedAfterReading.
Description
XEventsQueued checks whether events are queued. If there are events in Xlib's queue, the routine returns immediately to the calling routine. Its return value is the number of events regardless of mode.
mode specifies what happens if no events are found on Xlib's queue.
• If mode is QueuedAlready, and there are no events in the queue, XEvents Queued returns zero (it does not flush the request buffer or attempt to read more events from the connection).
• If mode is QueuedAfterFlush, and there are no events in the queue, XEvents Queued flushes the request buffer, attempts to read more events out of the applica tion's connection, and returns the number read.
If mode is QueuedAfterReading, and there are no events in the queue, XEventsQueued attempts to read more events out of the application's connection without flushing the request buffer and returns the number read.
Note that XEventsQueued always returns immediately without I/O if there are events already in the queue.
XEventsQueued with mode QueuedAfterFlush is identical in behavior to XPending. XEventsQueued with mode QueuedAlready is identical to the QLength macro (see Appendix C, Macros).
For more information, see Volume One, Chapter 8, Events. Related Commands
QLength,XAllowEvents,XChecklfEvent,XCheckMaskEvent,XCheckTyped-Event, XCheckTypedWindowEvent,XCheckWindowEvent, XGetlnputFocus, XGetMotionEvents,XlfEvent,XMaskEvent,XNextEvent,XPeekEvent,XPeek-IfEvent, XPending, XPutBackEvent,XSelectlnput,XSendEvent,XSetlnput-Focus,XSynchronize,XWindowEvent.
XFetchBuffer "\
•Xlib-Cut Buffers—
Name
XFetchBuffer — return data from a cut buffer.
Synopsis
char *XFetchBuffer(display, nbytes, buffer) Display * display;
int * nbytes; /* RETURN */ int buffer;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
nbytes Returns the number of bytes in buffer returned by XFetchBuffer. If
there is no data in the buffer, * nbytes is set to 0.
buffer Specifies which buffer you want data from. Specify an integer from 0 to 7
inclusive.
Description
XFetchBuffer returns data from one of the 8 buffers provided for interclient communica tion. If the buffer contains data, XFetchBuffer returns the number of bytes in nbytes, otherwise it returns NULL and sets *nbytes to 0. The appropriate amount of storage is allo cated and the pointer returned; the client must free this storage when finished with it by calling XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte.
Selections are preferred over cut buffers as a communication scheme.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech niques.
Errors
BadValue buffer not an integer between 0 and 7 inclusive.
Related Commands
XFetchBytes,XRotateBuffers,XStoreBuffer, XStoreBytes.
—Xlib-Cut Buffers-
J XFetch Bytes
Name
XFetchBytes — return data from cut buffer 0.
Synopsis
char *XFetchBytes( display, nbytes) Display ^display; int * nbytes; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
nbytes Returns the number of bytes in the string returned by XFetchBytes. If
there is no data in the buffer, * nbytes is set to 0.
Description
XFetchBytes returns data from cut buffer 0 of the 8 buffers provided for interclient commu nication. If the buffer contains data, XFetchBytes returns the number of bytes in nbytes, otherwise it returns NULL and sets * nbytes to 0. The appropriate amount of storage is allo cated and the pointer returned; the client must free this storage when finished with it by calling XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte.
Use XFetchBuf f er to fetch data from any specified cut buffer. Selections are preferred over cut buffers as a communication method.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech niques.
Related Commands
XFetchBuffer,XRotateBuffers,XStoreBuffer, XStoreBytes.
XFetChName V xm>-W.ndow Manager Hints-
Name
XFetchName — get a window's name (XA_WM_NAME property).
Synopsis
Status XFetchName ( display, w, window_name) Display * display; Window w; char **window_name; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XQpenDisplay.
w Specifies the ID of the window whose name you want a pointer set to.
window_name Returns a pointer to the window name, which will be a null-terminated string. If the XA_WM_NAME property has not been set for this window, XFetchName sets windowname to NULL. When finished with it, a client can free the name string using XFree.
Description
XFetchName is superseded by XGetWMName in Release 4. XFetchName returns the current value of the XA_WM_NAME property for the specified window. XFetchName returns nonzero if it succeeds, and zero if the property has not been set for the argument window.
For more information, see Volume One, Chapter 10, Interdient Communication, and Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XGetClassHint,XGetlconName,XGetlconSizes, XGetNormalHints,XGet-SizeHints,XGetTransientForHint,XGetWMHints, XGetZoomHints, XSet-ClassHint,XSetCommand,XSetlconName, XSetlconSizes, XSetNormalHints, XSetSizeHints,XSetTransientForHint,XSetWMHints,XSetZoomHints, XStoreName.
-Xllb - Drawing Primitives ' XFlll Arc
Name
XFillArc — fill an arc.
Synopsis
XFillArc (display, draw-able, gc , x, y, width, height,
anglel, angle2) Display *display; Drawable drawable; GC gc; int x, y ;
unsigned int width, height; int anglel, angle2;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the upper-left corner of the bounding box
y containing the arc, relative to the origin of the drawable.
width Specify the width and height in pixels. These are the major and minor axes of
height the arc.
anglel Specifies the start of the arc relative to the three-o'clock position from the
center. Angles are specified in 64ths of degrees.
angle2 Specifies the path and extent of the arc relative to the start of the arc. Angles
are specified in 64ths of degrees.
Description
XFillArc draws a filled arc. The x, y, width, and height arguments specify the bounding box for the arc. See XDrawArc for the description of how this bounding box is used to com pute the arc. Some, but not all, of the pixels drawn with XDrawArc will be drawn by XFill Arc with the same arguments. See XFillRectangle for an example of the differences in pixels drawn by the draw and fill routines.
The arc forms one boundary of the area to be filled. The other boundary is determined by the arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used.
XFillArc uses these graphics context components: function, plane_mask, f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, and ts_y_ origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
XFIIIArc (continued) Xlib - Drawing Primitives
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArcs,XFill-Polygon, XFillRectangle,XFillRectangles.
Xlib Reference Manual
-Xlib - Drawing Primitives ' XFIIIArCS
Name
XFillArcs — fill multiple arcs.
Synopsis
XFillArcs(display, drawable, gc, arcs, narcs) Display *display; Drawable drawable; GC gc; XArc *arcs; int narcs;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
draviable Specifies the drawable.
gc Specifies the graphics context.
arcs Specifies a pointer to an array of arc definitions.
narcs Specifies the number of arcs in the array.
Description
For each arc, XFillArcs fills the region closed by the specified arc and one or two line seg ments, depending on the arc_mode specified in the GC. It does not draw the complete out lines of the arcs, but some pixels may overlap.
The arc forms one boundary of the area to be filled. The other boundary is determined by the arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. The arcs are filled in the order listed in the array. For any given arc, no pixel is drawn more than once. If filled arcs intersect, pixels will be drawn multiple times.
There is a limit to the number of arcs that can be filled in a single call, that varies according to the server. To determine how many arcs you can fill in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by three, and this is the maximum number of arcs you can fill in a single XFillArcs call.
XFillArcs use these graphics context components: function, plane_mask, f ill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and clipjmask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x__origin, and ts_y_ origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct { short x, y; unsigned short width, height;
XFillArcs
(continued)
Xlib - Drawing Primitives
short anglel, angle2; /* 64ths of Degrees */
} XArc;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArc, XFill-Polygon, XFillRectangle, XFillRectangles.
184
Xlib Reference Manual
—Xlib - Drawing Primitives-
f XFillPolygon
Name
XFillPolygon — fill a polygon.
Synopsis
XFillPolygon (display, draw-able, gc, points, npoints, shape, mode) Display * display; Drawable draw-able; GC gc;
XPoint * points; int npoints; int shape; int mode;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
dra wabl e Specifies the drawable.
gc Specifies the graphics context.
points Specifies a pointer to an array of points.
npoin t s Specifies the number of points in the array.
shape Specifies an argument that helps the server to improve performance. Pass the
last constant in this list that is valid for the polygon to be filled: Complex, Nonconvex, or Convex.
mode Specifies the coordinate mode. Pass either CoordModeOrigin or Coord-
ModePrevious.
Description
XFillPolygon fills the region closed by the specified path. Some but not all of the path itself will be drawn. The path is closed automatically if the last point in the list does not coin cide with the first point. No pixel of the region is drawn more than once.
The mode argument affects the interpretation of the points that define the polygon:
CoordModeOrigin indicates that all points are relative to the drawable's origin.
• CoordModePrevious indicates that all points after the first are relative to the previ ous point. (The first point is always relative to the drawable's origin.)
The shape argument allows the fill routine to optimize its performance given tips on the confi guration of the area.
Complex indicates the path may self-intersect. The f ill_rule of the GC must be consulted to determine which areas are filled. See Volume One, Chapter 5, The Graphics Context, for a discussion of the fill rules EvenOddRule and WindingRule.
XFMIPolygon (continued) Xlib - Drawing Primitives
None on vex indicates the path does not self-intersect, but the shape is not wholly con vex. If known by the client, specifying Nonconvex instead of Complex may improve performance. If you specify Nonconvex for a self-intersecting path, the graphics results are undefined.
• Convex means that for every pair of points inside the polygon, the line segment con necting them does not intersect the path. This can improve performance even more, but if the path is not convex, the graphics results are undefined.
Contiguous coincident points in the path are not treated as self-intersection.
XFillPolygon uses these graphics context components when filling the polygon area:
function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_ x_origin, clip_y_origin, and clip_mask. This function also uses these mode-depen dent components of the GC: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y; } XPoint;
Errors
BadDrawable BadGC BadMatch BadValue
Related Commands
XClearArea,XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangle,XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFillRectangle, XFillRectangles.
—Xllb - Drawing Primitives-
XFillRectangle
Name
XFillRectangle — fill a rectangular area.
Synopsis
XFillRectangle(display, drawable, gc, x, y, width, height) Display *display; Drawable drawable; GC gc; int x, y ; unsigned int width, height;
Arguments
display Specifies a connection to an X server; returned from XQpenDisplay.
drawable Specifies the drawable.
gc Specifies the graphics context.
x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-
y live to the origin of the drawable.
wi dth Specify the dimensions in pixels of the rectangle to be filled.
height
20 pixels 20 pixels
Description
XFillRectangle fills the rectangular area in the specified drawable using the x and y coor dinates, width and height dimensions, and graphics context you specify. XFill Rectangle draws some but not all of the path drawn by XDrawRectangle with the same arguments.
XFillRectangle uses these graphics context components: function, plane_mask,
fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_
mask. This function also uses these graphics context components depending on the
fill_style: foreground, background tile, stipple, ts_x_origin, and
ts_y_origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5,
The Graphics Context.
Xlib Reference Manual
XFillRectangle (continued) Xlib - Drawing Primitives
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea,XClearWindow, XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint, XDrawPoints. XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFillPolygon, XFillRectangles.
188
Xlib Reference Manual
—Xlib - Drawing Primitives-
XFMIRectangles
Name
XFillRectangles — fill multiple rectangular areas.
Synopsis
XFillRectangles (display, drawable, gc, rectangles, nrectangles) Display * display; Drawable drawable; GC gc ;
XRectangle * rectangles; int nrectangles;
Arguments
display drawable
Specifies a connection to an X server; returned from xopenDisplay.
Specifies the drawable. gc Specifies the graphics context.
rectangles Specifies a pointer to an array of rectangles. nrectangles Specifies the number of rectangles in the array.
20 pixels
20 pixels
Description
XFillRectangles fills multiple rectangular areas in the specified drawable using the graph ics context.
The x and y coordinates of each rectangle are relative to the drawable's origin, and define the upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will be drawn multiple times.
There is a limit to the number of rectangles that can be filled in a single call, that varies accord ing to the server. To determine how many rectangles you can fill in a single call, you find out your server's maximum request size using XMaxRequestSize. Subtract 3 and divide by two, and this is the maximum number of rectangles you can fill in a single XDraw-Rectangles call.
XFillRectangles uses these graphics context components: function, plane_mask, fill style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_
Xlib Reference Manual
XFillRectangles (continued) Xlib - Drawing Primitives
mask. This function also uses these graphics context components depending on the f ill_ style: foreground, background, tile, stipple, ts_x_origin, and ts_y_ origin.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text, and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height; } XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XClearArea, XClearWindow,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs,XDrawFilled, XDrawLine,XDrawLines,XDrawPoint,XDrawPoints, XDrawRectangle,XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFillPolygon,XFillRectangle, XFillRectangles.
XFindContext
—Xlib - Context Manager
Name
XFindContext — get data from the context manager (not graphics context).
Synopsis
int XFindContext( display, w, context, data) Display * display; Window w; XContext context; caddr_t *data; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window with which the data is associated.
context Specifies the context type to which the data corresponds.
data Returns the data.
Description
XFindContext gets data that has been assigned to the specified window and context ID. The context manager is used to associate data with windows for use within an application.
This application should have called XUniqueContext to get a unique ID, and then xsave-Context to save the data into the array. The meaning of the data is indicated by the context ID, but is completely up to the client.
XFindContext returns XCNOENT (a nonzero error code) if the context could not be found and zero (0) otherwise.
For more information on the context manager, see Volume One, Chapter 13, Other Program ming Techniques.
Structures
typedef int XContext/
Related Commands
XDeleteContext,XSaveContext, XUniqueContext.
Name
XFIush — flush the request buffer (display all queued requests).
Synopsis
XFIush (display)
Display *display;
Arguments
display Specifies a connection to an X server; returned from xopenoisplay.
Description
XFIush sends to the server ("flushes") all requests that have been buffered but not yet sent.
Flushing is done automatically when input is read if no matching events are in Xlib's queue (with XPending, XNextEvent, or XWindowEvent, etc.), or when a call is made that gets information from the server (such as XQueryPointer, XGetFontlnf o) so XFIush is sel dom needed. It is used when the buffer must be flushed before any of these calls are reached.
For more information, see Volume One, Chapter 2, X Concepts, and Chapter 3, Basic Window Program.
Related Commands
XSync.
192 Xlib Reference Manual
-Mb - screen saver / XForceScreenSaver
Name
XForceScreenSaver — turn the screen saver on or off.
Synopsis
XForceScreenSaver(display, mode) Display * display; int mode;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
mode Specifies whether the screen saver is active or reset. The possible modes are:
ScreenSaverActive or ScreenSaverReset.
Description
XForceScreenSaver resets or activates the screen saver.
If the specified mode is ScreenSaverActive and the screen saver currently is disabled, the screen saver is activated, even if the screen saver had been disabled by calling xset Screen-Saver with a timeout of zero (0). This means that the screen may go blank or have some ran dom change take place to save the phosphors.
If the specified mode is ScreenSaverReset and the screen saver currently is enabled, the screen is returned to normal, the screen saver is deactivated and the activation timer is reset to its initial state (as if device input had been received). Expose events may be generated on all visible windows if the server cannot save the entire screen contents.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadValue
Related Commands
XActivateScreenSaver,XGetScreenSaver, XResetScreenSaver,XSet-ScreenSaver.
^ Xlib - HouseKeeping —
Name
XFree — free specified memory allocated by an Xlib function.
Synopsis
XFree (data)
caddr_t data;
Arguments
data Specifies a pointer to the data that is to be freed.
Description
XFree is a general purpose routine for freeing memory allocated by Xlib calls.
Related Commands
DefaultScreen,XCloseDisplay, XNoOp,XOpenDisplay.
-X. - co,ormaps / XFreeColormap
Name
XFreeColormap — delete a colormap and install the default colormap.
Synopsis
XFreeColormap (display, cmap) Display *display; Colo rmap cmap;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
cmap Specifies the colormap to delete.
Description
XFreeColormap destroys the specified colormap, unless it is the default colormap for a screen. That is, it not only uninstalls cmap from the hardware colormap if it is installed, but also frees the associated memory including the colormap ID.
XFreeColormap performs the following processing:
If cmap is an installed map for a screen, it uninstalls the colormap and installs the default if not already installed.
If cmap is defined as the colormap attribute for a window (by XCreateWindow or XChangeWindowAttributes), it changes the colormap attribute for the window to the constant None, generates a ColormapNotif y event, and frees the colormap. The colors displayed with a colormap of None are server-dependent, since the default color-map is normally used.
For more information, see Volume One, Chapter 7, Color. Errors
BadColormap
Related Commands
DefaultColormap,DisplayCells,XCopyColormapAndFree,XCreate-Colormap,XGetStandardColormap,XInstallColormap, XListlnstalled-Colormaps,XSetStandardColormap, XSetWindowColormap, XUninstall-Colormap.
XFreeColors \
•Xlib-Color Cells-
Name
XFreeColors — free colormap cells or planes.
Synopsis
XFreeColors(display, cmap, pixels, npixels, planes) Display *display; Colormap cmap; unsigned long pixels[]; int npixels; unsigned long planes;
Arguments
display Specifies a connection to an X server; returned from XQpenDisplay.
cmap Specifies the colormap.
pixels Specifies an array of pixel values.
npixels Specifies the number of pixels.
pi anes Specifies the planes you want to free.
Description
XFreeColors frees the cells whose values are computed by ORing together subsets of the planes argument with each pixel value in the pixels array.
If the cells are read/write, they become available for reuse, unless they were allocated with XAllocColorPlanes, in which case all the related pixels may need to be freed before any become available.
If the cells were read-only, they become available only if this is the last client to have allocated those shared cells.
For more information, see Volume One, Chapter 7, Color.
Errors
BadAccess Attempt to free a colorcell not allocated by this client (either unallocated or allocated by another client).
BadColormap
BadValue A pixel value is not a valid index into cmap.
Note: if more than one pixel value is in error, the one reported is arbitrary.
Related Commands
BlackPixel,WhitePixel,XAllocColor,XAllocColorCells,XAllocColor Planes, XAllocNamedColor,XLookupColor,XParseColor, XQueryColor, XQueryColors,XStoreColor,XStoreColors, XStoreNamedColor.
— Xlib -Cursors-
J XFreeCursor
Name
XFreeCursor — release a cursor.
Synopsis
XFreeCursor(display, cursor) Display *display; Cursor cursor;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
cursor Specifies the ID of the cursor to be affected.
Description
XFreeCursor deletes the association between the cursor ID and the specified cursor. The cursor storage is freed when all other clients have freed it. Windows with their cursor attribute set to this cursor will have this attribute set to None (which implies CopyFromParent). The specified cursor ID should not be referred to again.
Errors
BadCursor
Related Commands
XCreateFontCursor,XCreateGlyphCursor,XCreatePixmapCursor,XDefine-Cursor, XQueryBestCursor,XQueryBestSize, XRecolorCursor,XUndefine-Cursor.
XFreeExtensionList \ XMb _ Extensions _
Name
XFreeExtensionList — free memory allocated for a list of installed extensions.
Synopsis
XFreeExtensionList( list) char **Iist;
Arguments
list Specifies a pointer to the list of extensions returned from XList-
Extensions.
Description
XFreeExtensionList frees the memory allocated by XListExt ens ions.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XListExtensions,XQueryExtension.
XFreeFont
Name
XFreeFont — unload a font and free storage for the font structure.
Synopsis
XFreeFont ( display, font_struct ) Display * display; XFontStruct *font_struct ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
f ont_struct Specifies the storage associated with the font.
Description
XFreeFont frees the memory allocated for the font_struct font information structure (XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees all stor age associated with the font_struct argument. Neither the data nor the font should be ref erenced again.
The server unloads the font itself if no other client has loaded it.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* Font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_bytel; /* first row that exists */
unsigned max_bytel; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned def ault_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Errors
BadFont
Related Commands
XCreateFontCursor, XFreeFontlnf o, XFreeFontNames, XFreeFontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWithlnf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFont, XSetFontPath, XUnloadFont.
Xlib Reference Manual
XFreeFontlnfo \ XIlb _ Fonts _
Name
XFreeFontlnfo — free the memory allocated by XListFontsWithlnf o.
Synopsis
XFreeFontlnfo (names, info, actual_count) char ** names; XFontStruct *info; int actual_count;
Arguments
names Specifies a pointer to the list of font names that were returned by XList-
FontsWithlnfo.
info Specifies a pointer to the list of font information that was returned by
XListFontsWithlnfo.
actual_count
Specifies the number of matched font names returned by XLis t Fonts-Withlnfo.
Description
XFreeFontlnfo frees the list of font information structures allocated by XListFonts Withlnf o. It does not unload the specified fonts themselves.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* Font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max char or byte2; /* last character */
unsigned min_bytel; /* first row that exists */
unsigned max bytel; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XCreateFontCursor,XFreeFont,XFreeFontNames,XGetFontPath,XGetFont-Property,XListFonts,XListFontsWithlnfo,XLoadFont, XLoadQueryFont, XQueryFont,XSetFont,XSetFontPath,XUnloadFont.
—Xlib-Fonts •
J XFreeFontNames
Name
XFreeFontNames — free the memory allocated by XListFonts. Synopsis
XFreeFontNames(list) char *list [ ] ;
Arguments
list Specifies the array of font name strings to be freed.
Description
XFreeFontNames frees the array of strings returned by XListFonts.
Related Commands
XCreateFontCursor,XFreeFont,XFreeFontlnfo, XFreeFontPath,XGetFont-Path, XGetFontProperty,XListFonts, XListFontsWithlnfo,XLoadFont, XLoadQueryFont,XQueryFont,XSetFont, XSetFontPath, XUnloadFont.
XFreeFontPath \ x,, b -Fon,s-
Name
XFreeFontPath — free the memory allocated by XGetFontPath.
Synopsis
XFreeFontPath(list) char **list;
Arguments
list Specifies an array of strings allocated by XGetFontPath.
Description
XFreeFontPath frees the data used by the array of pathnames returned by XGetFont Path.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text. Related Commands
XCreateFontCursor,XFreeFont,XFreeFontlnfo,XFreeFontNames,XGet FontPath, XGetFontProperty,XListFonts, XListFontsWithlnfo,XLoad-Font, XLoadQueryFont,XQueryFont,XSetFont, XSetFontPath,XUnloadFont.
-Xlib - Graphics Context ' XFreeGC
Name
XFreeGC — free a graphics context.
Synopsis
XFreeGC (display, gc) Display * display; GC gc ;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
gc Specifies the graphics context to be freed.
Description
XFreeGC frees all memory associated with a graphics context, and removes the GC from the server and display hardware.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadGC
Related Commands
DefaultGC,XChangeGC,XCopyGC, XCreateGC, XGContextFromGC,XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetDashes, XSetFillRule,XSetFillStyle,XSetForeground, XSet-Function,XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask, XSetState,XSetStipple, XSetSubwindowMode, XSetTSOrigin.
XFreeModifiermap \
X|lb _
Name
XFreeModifiermap — destroy and free a keyboard modifier mapping structure.
Synopsis
XF r eeModi f ie rmap ( modmap )
XModif ierKeymap * modmap;
Arguments
modmap Specifies a pointer to the XModif ierKeymap structure to be freed.
Description
XFreeModifiermap frees an XModif ierKeymap structure originally allocated by XNew-Modif ierMap or XGetModif ierMapping.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Structures
typedef struct {
int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modif iermap; /* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
} XModif ierKeymap;
Related Commands
XChangeKeyboardMapping, XDeleteModif iermapEntry, XGetKeyboard-Mapping, XGetModif ierMapping, XInsertModif iermapEntry, XKeycode-ToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookup-String, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRef resh-KeyboardMapping, XSetModif ierMapping, XStringToKeysym.
-Mb - Pixmaps and TNes /
Name
XFreePixmap — free a pixmap ID.
Synopsis
XFreePixmap (display, pixmap) Display *display; Pixmap pixmap;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
pixmap Specifies the pixmap whose ID should be freed.
Description
XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for that resource, it is freed. The Pixmap should never be referenced again by this client. If it is, the ID will be unknown and a BadPixmap error will result.
Errors
BadPixmap
Related Commands
XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, XQueryBestSize,XQueryBestStipple,XQueryBestTile, XReadBitmapFile, XSetTile,XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XWriteBitmapFile.
Xlib Reference Manual 205
XFreeStringList V Vl]
^ Xlib - Window Manager Hints-Name
XFreeStringList — free the in-memory data associated with the specified string list.
Synopsis
void XFreeStringList(list) char **Iist;
Arguments
list Specifies the list of strings to be freed.
Availability
Release 4 and later.
Description
XFreeStringList releases memory allocated by XTextPropertyToStringList.
Related Commands
XGetTextProperty, XSetTextProperty, XStringListToTextProperty, XTextPropertytoStringList.
Name
XGContextFromGC — obtain the GContext (resource ID) associated with the specified graphics context.
Synopsis
GContext XGContextFromGC( gc) GC gc;
Arguments
gc Specifies the graphics context of the desired resource ID.
Description
XGContextFromGC extracts the resource ID from the GC structure. The GC structure is Xlib's local cache of GC values and contains a field for the GContext ID. This function is essentially a macro that accesses this field, since the GC structure is intended to be opaque.
A GContext is needed to set a field of the xvisuallnf o structure prior to calling XGet-Visuallnfo.
Related Commands
DefaultGC,XChangeGC,XCopyGC, XCreateGC, XFreeGC, XSetArcMode,XSet-Background,XSetClipMask,XSetClipOrigin, XSetClipRectangles,XSet-Dashes,XSetFillRule,XSetFillStyle, XSetForeground,XSetFunction, XSetGraphicsExposures,XSetLineAttributes, XSetPlaneMask, XSetState, XSetStipple,XSetSubwindowMode, XSetTSOrigin.
Xlib Reference Manual 207
v Xlib - Standard Geometry-Name
XGeometry — calculate window geometry given user geometry string and default geometry.
Synopsis
int XGeometry(display, screen, user_geom, default_geom r bwidth,
fwidth r fheight, xadder, yadder f x, y, width, height) Display *display; int screen;
char *user_geom r *default_geom; unsigned int bwidth; unsigned int fwidth r fheight; int xadder, yadder; int *x r *y, * width, *height;/* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
screen Specifies which screen the window is on.
user_geom Specifies the user or program supplied geometry string, perhaps incomplete.
de fa u 11_ ge om
Specifies the default geometry string and must be complete.
bwi dth Specifies the border width.
f height Specify the font height and width in pixels (increment size).
fwidth
xadder Specify additional interior padding in pixels needed in the window,
yadder
x Return the user-specified or default coordinates of the window.
y
wi dth Return the window dimensions in pixels.
height
Description
XGeometry has been superseded by XWMGeometry as of Release 4.
XGeometry returns the position and size of a window given a user-supplied geometry (allowed to be partial) and a default geometry. Each user-supplied specification is copied into the appropriate returned argument, unless it is not present, in which case the default specifica tion is used. The default geometry should be complete while the user-supplied one may not be.
XGeometry is useful for processing command line options and user preferences. These geom etry strings are of the form:
=<width>x<height>{+-}<xoffset>( +-} <yoffset>
208 Xlib Reference Manual
Xlib - Standard Geometry (continued) XGeometry
The "=" at the beginning of the string is now optional. (Items enclosed in <> are integers, and items enclosed in {} are a set from which one item is to be chosen. Note that the brackets should not appear in the actual string.)
The XGeometry return value is a bitmask that indicates which values were present in user_geom. This bitmask is composed of the exclusive OR of the symbols XValue, YValue, WidthValue, HeightValue, XNegative, or YNegative.
If the function returns either xvalue or YValue, you should place the window at the requested position. The border width (bwidtti), size of the width and height increments (typi cally fwidth and fheight), and any additional interior space (xadder and yadder) are passed in to make it easy to compute the resulting size.
Related Commands
XParseGeometry,XTranslateCoordinates, XWMGeometry.
XGetAtomName V ™
^ Xlib - Properties-Name
XGetAtomName — get a string name for a property given its atom.
Synopsis
char *XGetAtomName ( display, atom) Display *display; Atom atom;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
atom Specifies the atom whose string name you want returned.
Description
An atom is a number identifying a property. Properties also have a string name. XGetAtom Name returns the string name that was specified in the original call to xinternAtom that returned this atom, or, for predefined atoms, a string version of the symbolic constant without the XA_ is returned. If the specified atom is not defined, XGetAtomName returns NULL, and generates a BadAtom error.
For example, XGetAtomName returns "XA_WM_CLASS" (a string) when passed the prede fined atom XA_WM_CLASS (a defined constant).
You should free the resulting string with XFree when it is no longer needed. XinternAtom performs the inverse function, returning the atom given the string.
Errors
BadAtom
Related Commands
XChangeProperty,XDeleteProperty,XGetFontProperty, XGetWindow-Property,XinternAtom, XListProperties, XRotateWindowProperties, XSetStandardProperties.
-X.ib-W.ndowManagerH.n,, / XGetClaSSHint
Name
XGetClassHint — get the XA_WM_CLASS property of a window.
Synopsis
Status XGetClassHint(display, v, class_hints) Display *display; Window w; XClassHint *class_hints ; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window for which the property is desired.
class_hints Returns the XClassHints structure.
Description
XGetClassHint obtains the XA_WM_CLASS property for the specified window. This property stores the resource class and instance name, that the window manager uses to get any resource settings that may control how the window manager manages the application that set this prop erty. XGetClassHint returns a Status of zero on failure, nonzero on success.
The XClassHint structure returned contains res_class, which is the name of the client such as "emacs", and res_name, which should be the first of the following that applies:
command line option (-rn name)
a specific environment variable (e.g., RESOURCE_NAME)
the trailing component of argv [ 0 ] (after the last /)
To free res_name and res_class when finished with the strings, use XFree. For more information on using hints, see Volume One, Chapter W,Interclient Communication.
Structures
typedef struct {
char *res_name;
char *res_class; } XClassHint;
Errors
BadWindow
Related Commands
XAllocClassHint,XFetchName,XGetlconName, XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-Hints,XSetClassHint,XSetCommand,XSetlconName, XSetlconSizes,XSet-NormalHints,XSetSizeHints,XSetTransientForHint,XSetWMHints,XSet-ZoomHints, XStoreName, XSetWMProperties,XSetWMProperties.
v Xllb - Window Manager Hints-Name
XGetCommand — get the XA_WM_COMMAND property (command line arguments).
Synopsis
Status XGetCommand (display, w, argv_return, argc_return) Display ^display; Window w;
char ***argv_return; int *argc_return;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
argv_return Returns the application's argument list. argc_return Returns the number of arguments returned.
Description
XGetCommand reads the XA_WM_COMMAND property from the specified window and returns a string list. If the XA_WM_COMMAND property exists, it is of type XA_STRING and format 8. If suf ficient memory can be allocated to contain the string list, XGetCommand fills in the argv_return and argc_return arguments and returns a non-zero status. Otherwise, it returns a zero status. To free the memory allocated to the string list, use XFreeStringList.
Errors
BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName, XGetlconSizes, XGetNormal-Hints, XGetSizeHints,XGetTransientForHint,XGetWMHints, XGetZoom-Hints, XSetClassHint,XSetlconName,XSetlconSizes,XSetNormalHints, XSetSizeHints, XSetTransientForHint,XSetWMHints,XSetZoomHints, XStoreName.
212 Xlib Reference Manual
XGetDefault
Name
XGetDefault — extract an option value from the resource database.
Synopsis
char *XGetDefault (display, program, option) Display * display ; char * program; char * opt ion;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
program Specifies the program name to be looked for in the resource database. The pro gram name is usually argv [ 0 ] , the first argument on the UNIX command line.
option Specifies the option name or keyword. Lines containing both the program
name and the option name, separated only by a period or asterisk, will be matched.
Description
XGetDefault returns a character string containing the user's default value for the specified program name and option name. XGetDefault returns NULL if no key can be found that matches option and program. For a description of the matching rules, see XrmGet-Resource.
The strings returned by XGetDefault are owned by Xlib and should not be modified or freed by the client.
Lines in the user's resource database look like this:
xterm. foreground: #cOcOff
xterm. geometry : =81x28
xterm. saveLines : 256
xterm. font: 8x13
xterm. keyMapFile: /usr/black/ .keymap
xterm. activelcon: on
xmh. header. font 9x15
The portion on the left is known as a key; the portion on the right is the value. Upper or lower case is important in keys. The convention is to capitalize only the second and successive words in each option, if any.
Resource specifications are usually loaded into the XA_RESOURCE_MANAGER property on the root window at login. If no such property exists, a resource file in the user's home directory is loaded. On a UNIX-based system, this file is $HOMEIXdefoults. After loading these defaults, XGetDefault merges additional defaults specified by the XENVIRONMENT environment variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource file. If XENVIRONMENT is not defined, XGetDefault looks for $HOMEI Xdefoults-name, where name specifies the name of the machine on which the application is running.
Xlib Reference Manual 213
XGetDefault (continued) Xlib - User Preferences
The first invocation of XGetDefault reads and merges the various resource files into Xlib so that subsequent requests are fast Therefore, changes to the resource files from the program will not be felt until the next invocation of the application.
For more information, see Volume One, Chapter 11, Managing User Preferences. Related Commands
XAutoRepeatOf f, XAutoRepeatOn, XBell, XChangeKeyboardControl, XGet-KeyboardControl.XGetPointerControl.
214 Xlib Reference Manual
-xnb - Error Handling / XGetErrorDatabaseText
Name
XGetErrorDatabaseText — obtain error messages from the error database.
Synopsis
XGetErrorDatabaseText( display, name, message,
default_string, buffer, length) Display display; char *name, *message; char *default_string;
char * buffer; /* RETURN */
int length;
Arguments
di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay.
name Specifies the name of the application.
message Specifies the type of the error message. One of XProtoError, xiib-Message, or XRequestMa jor (see Description below).
default_string
Specifies the default error message.
buffer Returns the error description. length Specifies the size of the return buffer.
Description
XGetErrorDatabaseText returns a message from the error message database. Given name and message as keys, XGetErrorDatabaseText uses the resource manager to look up a string and returns it in the buffer argument. Xlib uses this function internally to look up its error messages. On a UNIX-based system, the error message database is usually lusrlliblXl 1 IXErrorDB.
The name argument should generally be the name of your application. The message argu ment should indicate which type of error message you want. Three predefined message types are used by Xlib to report errors:
XProtoError The protocol error number is used as a string for the message argument. xlibMessage These are the message strings that are used internally by Xlib. XReques tMa jor The major request protocol number is used for the message argument.
If no string is found in the error database, XGetErrorDatabaseText returns the def ault_string that you specify to the buffer. The string in buffer will be of length length. For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName,XGetErrorText, XSetAfterFunction, XSetErrorHandler, XSetlOErrorHandler,XSynchronize.
XGetErrorText \ Xllb _ Error Handnng _
Name
XGetErrorText — obtain a description of error code.
Synopsis
XGetErrorText( display, code, buffer, length) Display *display; int code ;
char * buffer; /* RETURN */
int length;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
code Specifies the error code for which you want to obtain a description.
buffer Returns a pointer to the error description text.
length Specifies the size of the buffer.
Description
XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer to a null-terminated string describing the specified error code with length length. This string is copied from static data and therefore may be freed. This routine allows extensions to the Xlib library to define their own error codes and error strings that can be accessed easily.
For more information, see Volume One, Chapter 3, Basic Window Program. Related Commands
XDisplayName,XGetErrorDatabaseText,XSetAfterFunction,XSetError-Handler,XSetlOErrorHandler,XSynchronize.
— XI ib-Fonts-
J XGetFontPath
Name
XGetFontPath — get the current font search path.
Synopsis
char **XGetFontPath( display, npaths) Display ^display; int * npaths; /* RETURN number of elements */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
npaths Returns the number of strings in the font path array.
Description
XGetFontPath allocates and returns an array of strings containing the search path for fonts. The data in the font path should be freed when no longer needed.
Related Commands
XCreateFontCursor,XFreeFont,XFreeFontlnfo,XFreeFontNames,XFree-FontPath,XGetFontProperty,XListFonts, XListFontsWithlnfo,XLoad-Font, XLoadQueryFont,XQueryFont,XSetFont, XSetFontPath, XUnloadFont.
XGetFontProperty
X
•Xlib-Properties-
Name
XGetFontProperty — get a font property given its atom.
Synopsis
Bool XGetFontProperty (font_struct f atom, value) XFontStruct *font_struct ; Atom atom; unsigned long *value; /* RETURN */
Arguments
font struct Specifies the storage associated with the font.
atom value
Specifies the atom associated with the property name you want returned.
Returns the value of the font property.
Description
XGetFontProperty returns the value of the specified font property, given the atom for that property. The function returns False if the atom was not defined, or True if was defined.
There are a set of predefined atoms for font properties which can be found in <XlllXatom.h>. These atoms are listed and described in Volume One, Chapter 6, Drawing Graphics and Text. This set contains the standard properties associated with a font. The predefined font properties are likely but not guaranteed to be present for any given font.
See Volume One, Appendix I, Logical Font Description Conventions, for more information on font properties.
Structures
typedef struct {
XExtData *ext_data; Font fid;
unsigned direction; unsigned min_char_or_byte2; unsigned max_char_or_byte2; unsigned min_bytel; unsigned max_bytel; Bool all_chars_exist; unsigned default_char; int n_properties; XFontProp ^properties; XCharStruct min_bounds; XCharStruct max bounds;
XCharStruct ' int ascent; int descent; } XFontStruct;
per_char;
/* hook for extension to hang data */
/* Font ID for this font */
/* hint about direction the 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*/
/* minimum bounds over all existing char*/
/* first_char to last__char information */
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
Related Commands
XChangeProperty,XDeleteProperty, XGetAtomName, XGetWindowProperty, XInternAtom, XListProperties,XRotateWindowProperties,XSetStandard-Properties.
218
Xlib Reference Manual
—Xlib - Window Manager Hints-
XGetGCValues
Name
XGetGCValues — obtain components of a given GC from Xlib's GC cache.
Synopsis
Status XGetGCValues(display, gc, valuemask, values) Display ^display; GC gc;
unsigned long valuemask; XGCValues * values;
Arguments
di sp 1 ay
gc
valuemask
values
/* RETURN */
Specifies a connection to an X server; returned from XOpenDisplay. Specifies the GC.
Specifies which components in the GC are to be returned in the values argument. This argument is the bitwise inclusive OR of one or more of the valid GC component mask bits.
Returns the GC values in the specified XGCValues structure.
Availability
Release 4 and later.
Description
XGetGCValues returns the components specified by valuemask for the specified GC. Note that the clip mask and dash list (represented by the GCClipMask and GCDashList bits, respectively, in the valuemask) cannot be requested. If the valuemask contains a valid set of GC mask bits (any of those listed in the Structures section with the exception of GCClipMask and GCDashList) and no error occur, XGetGCValues sets the requested components in values and returns a nonzero status. Otherwise, it returns a zero status.
For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
int function; /*
unsigned long plane_mask; /*
unsigned long foreground; /*
unsigned long background; /*
int line_width; /*
int line_style; /*
int cap_style; /*
int join_style; /*
int fill_style; /*
int fill_rule; /*
int arc_mode; /*
Pixmap tile; /*
Pixmap stipple; /*
int ts_x_origin; /*
logical operation */
plane mask */
foreground pixel */
background pixel */
line width */
LineSolid, LineOnOffDash, LineDoubleDash */
CapNotLast, CapButt, CapRound, CapProjecting */
JoinMiter, JoinRound, JoinBevel */
FillSolid, Fill-Tiled, FillStippled */
EvenOddRule, WindingRule */
ArcPieSlice, ArcChord */
tile pixmap for tiling operations */
stipple 1 plane pixmap for stipping */
offset for tile or stipple operations */
Xlib Reference Manual
XGetGCValues
(continued)
Xlib - Window Manager Hints
int ts_y_origin; Font font; int subwindow mode; Bool graphics_exposures; int clip_x_origin; int clip_y_origin; Pixmap clip_mask; int dash_offset; char dashes; } XGCValues;
/* default text font for text operations */
/* ClipByChildren, Includelnferiors */
/* generate events on XCopyArea, XCopyPlane */
/* origin for clipping */
/* bitmap clipping; other calls for rects */
/* patterned/dashed line information */
/* not valid in this call */ /* not valid in this call */
Related Commands
XChangeGC,XCopyGC, XCreateGC.
220
Xlib Reference Manual
— Xlib - Window Attributes-
J XGetGeometry
Name
XGetGeometry — obtain the current geometry of drawable.
Synopsis
Status XGetGeometry(display, drawable, root, x, y,
width, height, border_width, depth) Display ^display; Drawable drawable;
Window *root; /* RETURN */
int *x, *y; /* RETURN */
unsigned int *width, *height; /* RETURN */
unsigned int *border_width ; /* RETURN */
unsigned int * depth; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawabl e Specifies the drawable, either a window or a pixmap. root Returns the root window ID of the specified window.
x Return the coordinates of the upper-left pixel of the window's border, relative
y to its parent's origin. For pixmaps, these coordinates are always zero.
width Return the dimensions of the drawable. For a window, these return the inside
height size (not including the border).
border_width
Returns the borderwidth, in pixels, of the window's border, if the drawable is a window. Returns zero if the drawable is a pixmap.
depth Returns the depth of the pixmap or window (bits per pixel for the object).
Description
This function gets the current geometry of a drawable, plus the ID of the root window of the screen the window is on.
XGetGeometry returns a Status of zero on failure, or nonzero on success.
Errors
BadDrawable
Related Commands
XConfigureWindow,XGetWindowAttributes, XMoveResizeWindow,XMove-Window, XResizeWindow.
Name
XGetlconName — get the name to be displayed in an icon.
Synopsis
Status XGetlconName ( display, w, icon_name) Display *display; Window w; char **icon_name; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window whose icon name you want to leam.
icon_name Returns a pointer to the name to be displayed in the window's icon. The name should be a null-terminated string. If a name hasn't been assigned to the window, XGetlconName sets this argument to NULL. When finished with it, a client must free the icon name string using XFree.
Description
XGetlconName is superseded by XGetWMlconName in Release 4. XGetlconName reads the icon name property of a window. This function is primarily used by window managers to get the name to be written in a window's icon when they need to display that icon.
XGetlconName returns a nonzero Status if it succeeds, and zero if no icon name has been set for the argument window.
For more information, see Volume One, Chapter WJnterclient Communication. Errors
BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconSizes,XGetNormalHints,XGetSize-Hints, XGetTransientForHint,XGetWMHints,XGetZoomHints, XSetClass-Hint,XSetCommand,XSetlconName,XSetlconSizes,XSetNormalHints,XSet-SizeHints, XSetTransientForHint,XSetWMHints, XSetZoomHints, XStore-Name.
222 Xlib Reference Manual
-XHb-W.ndowM.n.g.rH.n., / XGetlCOnSizeS
Name
XGetlconSizes — get preferred icon sizes.
Synopsis
Status XGetlconSizes(display, w, size_list, count) Display *display; Window w;
XlconSize **size_list; /* RETURN */ int * count; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID (usually of the root window).
si ze_l 1st Returns a pointer to the size list.
count Returns the number of items in the size list.
Description
XGetlconSizes reads the XA_WM_ICON_SIZE property that should be set by the window manager to specify its desired icon sizes. XGetlconSizes returns a Status of zero if a window manager has not set icon sizes, and a nonzero Status otherwise. This function should be called by all programs to find out what icon sizes are preferred by the window man ager. The application should then use XSetWMHints to supply the window manager with an icon pixmap or window in one of the supported sizes. To free the data allocated in size_list, use XFree.
For more information, see Volume One, Chapter 10, Interclient Communication. Structures
typedef struct {
int min_width, min_height; int max_width, max_height; int width_inc, height_inc; } XlconSize;
/* width_inc and height_inc provide the preferred
* increment of sizes in the range from min_width
* to max_width and min_height to max_height. */
Errors
BadWindow
XGetlconSizes (continued) Xlib - Window Manager Hints
Related Commands
XAllocIconSize,XFetchName,XGetClassHint,XGetlconName,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints, XGetZoom-Hints,XSetClassHint,XSetCommand,XSetlconSizes, XSetNormalHints, XSetSizeHints,XSetTransientForHint,XSetWMHints, XSetZoomHints, XStoreName.
Xlib Reference Manual
-X.ib-.mage, /
Name
XGetlmage — place contents of a rectangle from drawable into an image.
Synopsis
Xlmage *XGetImage( display, drawable, x, y, width, height,
plane_mask, format) Display * display; Drawable drawable; int x, y ;
unsigned int width, height; unsigned long plane_mask; int format;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
drawable Specifies the drawable to get the data from.
x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-
y live to the origin of the drawable.
wi dth Specify the width and height in pixels of the image.
height
plane_mask Specifies a plane mask that indicates which planes are represented in the image.
format Specifies the format for the image. Pass either XYPixmap or ZPixmap.
Description
XGetlmage dumps the contents of the specified rectangle, a drawable, into a client-side Xlm age structure, in the format you specify. Depending on which format you pass to the format argument, the function does the following:
If the format is XYP ixmap
Gets only the bit planes you passed to the plane_mask argument. • If the format is ZP ixmap
Sets to 0 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.
XGetlmage returns the depth of the image to the depth member of the ximage structure. This depth is as specified when the drawable was created.
If the drawable is a pixmap, the specified rectangle must be completely inside the pixmap, or a BadMatch error will occur, and the visual field in the image will be None. If XGetlmage fails, it returns NULL. If the drawable is a window, the window must be viewable, and the speci fied rectangle must not go off the edge of the screen. Otherwise, a BadMatch error will occur. If the drawable is a window, the visual argument will return the visual specified when the drawable was created.
Xlib Reference Manual 225
XGetlmage (continued) Xlib - Images
The returned image will include any visible portions of inferiors or overlapping windows con tained in the rectangle. The image will not include the cursor. The specified area can include the borders. The returned contents of visible regions of inferiors of different depth than the specified window are undefined.
If the window has a backing-store, the backing-store contents are returned for regions of the window that are obscured by noninferior windows. Otherwise, the return contents of such obscured regions are undefined. Also undefined are the returned contents of visible regions of inferiors of different depth than the specified window.
The data in the image structure is stored in the server's natural byte- and bit-order. For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadDrawable
BadMatch See Description above.
BadValue
Related Commands
ImageByteOrder,XAddPixel,XCreatelmage,XDestroyImage, XGetPixel, XGetSublmage,XPutlmage,XPutPixel,XSubImage.
Xlib Reference Manual
— Xllb-Input Handling-
J XGetlnputFocus
Name
XGetlnputFocus — return the current keyboard focus window.
Synopsis
XGetlnputFocus(display, focus, revert_to) Display *display;
window * focus; /* RETURN */
int *revert_to; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
focus Returns the ID of the focus window, or one of the constants PointerRoot
or None.
revert_to Returns the window to which the focus would revert if the focus window became invisible. This is one of these constants: Re vert TOP a rent, RevertToPointerRoot, or RevertToNone. Must not be a window ID.
Description
XGetlnputFocus returns the current keyboard focus window and the window to which the focus would revert if the focus window became invisible.
XGetlnputFocus does not report the last focus change time. This is available only from Focus In and FocusOut events.
Related Commands
QLength, XAllowEvents,XChecklfEvent,XCheckMaskEvent,XCheckTyped-Event, XCheckTypedWindowEvent,XCheckWindowEvent,XEventsQueued, XGetMotionEvents,XlfEvent,XMaskEvent, XNextEvent, XPeekEvent, XPeek-IfEvent, XPending,XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput-Focus,XSynchronize,XWindowEvent.
XGetKeyboardControl
•Xlib - User Preferences—
Name
XGetKeyboardControl — obtain a list of the current keyboard preferences.
Synopsis
XGetKeyboardControl(display, values) Display *display; XKeyboardState *values; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
values Returns filled XKeyboardState structure.
Description
XGetKeyboardControl returns the current control values for the keyboard. For the LEDs (light emitting diodes), the least significant bit of led_jnask corresponds to LED 1, and each bit that is set to 1 in led_mask indicates an LED that is lit. auto_repeats is a bit vector; each bit that is set to 1 indicates that auto-repeat is enabled for the corresponding key. The vec tor is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the least significant bit in the byte representing key 8N. global_auto_repeat is either AutoRepeatModeOn or AutoRepeatModeOff.
For the ranges of each member of XKeyboardState, see the description of XChange-PointerControl.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Structures
typedef struct {
int key_click_percent;
int bell_percent;
unsigned int bell_pitch, bell_duration;
unsigned long led_mask;
int global_auto_repeat;
char auto_repeats[32]; } XKeyboardState;
Related Commands
XAutoRepeatOff,XAutoRepeatOn,XBell, XChangeKeyboardControl,XGet-Default,XGetPointerControl.
Xlib Reference Manual
— Xlib-Keyboard
/ XGetKeyboardMapping
Name
XGetKeyboardMapping — return symbols for keycodes. Synopsis
KeySym *XGetKeyboardMapping(display, first_keycode,
keycode_count, keysyms_per_keycode) Display * display; KeyCode first_keycode; int keycode_count; int *keysyms_per_keycode; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay. first_keycode
Specifies the first keycode that is to be returned.
keycode_count
Specifies the number of keycodes that are to be returned.
£eysyms_per_.keycode
Returns the number of keysyms per keycode.
Description
Starting with first_keycode, XGetKeyboardMapping returns the symbols for the specified number of keycodes. The specified first_keycode must be greater than or equal to min_keycode as returned by XDisplayKeycodes, otherwise a BadValue error occurs. In addition, the following expression must be less than or equal to max_keycode (also returned by XDisplayKeycodes) as returned in the Display structure, otherwise a BadValue error occurs:
first_keycode + keycode_count - 1 The number of elements in the keysyms list is:
keycode_count * keysyms_per_keycode
Then, keysym number N (counting from 0) for keycode K has an index (counting from 0) of the following (in keysyms):
(K - first_keycode) * keysyms_per_keycode + N
The keysyms_per_keycode value is chosen arbitrarily by the server to be large enough to report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused elements for individual keycodes.
Use XFree to free the returned keysym list when you no longer need it.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
XGetKeyboardMapping (continued) Xlib - Keyboard
Errors
BadValue first_keycode less than display->min_keycode .
display->max_keycode exceeded.
Related Commands
XChangeKeyboardMapping,XDeleteModifiermapEntry, XFreeModifiermap, XGetModifierMapping,XInsertModifiermapEntry,XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString,XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRefreshKeyboard-Mapping, XSetModifierMapping,XStringToKeysym.
—X Programming Library-
J XGetModifierMapping
Name
XGetModifierMapping — obtain a mapping of modifier keys (Shift, Control, etc.). Synopsis
XModifierKeymap *XGetModifierMapping(display) Display *display;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
Description
XGetModifierMapping returns the keycodes of the keys being used as modifiers.
There are eight modifiers, represented by the symbols Shif tMapindex, LockMapindex, ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map-Index, and ModSMapIndex. The modifiermap member of the XModifierKeymap structure contains eight sets of keycodes, each set containing max_keypermod keycodes. Zero keycodes are not meaningful. If an entire modif iermap is filled with zero's, the corre sponding modifier is disabled. No keycode will appear twice anywhere in the map.
Structures
typedef struct {
int max keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by max_keypermod array of
* keycodes to be used as modifiers */
} XModifierKeymap;
/* modifier names. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. */ #define ShiftMapIndex 0 #define LockMapindex 1
#define ControlMapIndex 2
#define ModlMapIndex 3 #define Mod2MapIndex 4 #define ModSMapIndex 5 tdefine ModSMapIndex 6 #define ModSMapIndex 7
Related Commands
XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap, XGetKeyboardMapping, XInsertModif iermapEntry, XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString,XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRefreshKeyboard-Mapping, XSetModifierMapping,XStringToKeysym.
Xlib Reference Manual
XGetMotionEvents \ xlib . lnputH and,,n g -
Name
XGetMotionEvents — get events from pointer motion history buffer.
Synopsis
XTimeCoord *XGetMotionEvents( display, w, start, stop, nevents) Display *display; Window w; Time start, stop; int * nevents; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
vf Specifies the ID of the window whose associated pointer motion events will be
returned.
start Specify the time interval for which the events are returned from the motion his-
stop tory buffer. Pass a time stamp (in milliseconds) or Cur rent Time.
nevents Returns the number of events returned from the motion history buffer.
Description
XGetMotionEvents returns all events in the motion history buffer that fall between the specified start and stop times (inclusive) and that have coordinates that lie within (including borders) the specified window at its present placement. The x and y coordinates of the XTimeCoord return structure are reported relative to the origin of w.
XGetMotionEvent returns NULL if the server does not support a motion history buffer (which is common), or if the start time is after the stop time, or if the start time is in the future. A motion history buffer is supported if XDisplayMotionBuf f erSize (display) > 0. The pointer position at each pointer hardware interrupt is then stored for later retrieval.
If the start time is later than the stop time, or if the start time is in the future, no events are returned. If the stop time is in the future, it is equivalent to specifying the constant Current-Time, since the server does not wait to report future events.
Use XFree to free the returned XTimeCoord structures when they are no longer needed. For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
typedef struct _XTimeCoord {
Time time;
short x, y; } XTimeCoord;
Errors
BadWindow
Xlib - Input Handling (continued) XGetMotionEventS
Related Commands
QLength,XAllowEvents,XChecklfEvent, XCheckMaskEvent, XCheckTyped-Event, XCheckTypedWindowEvent,XCheckWindowEvent, XEventsQueued, XGetlnputFocus,XlfEvent,XMaskEvent, XNextEvent, XPeekEvent, XPeek-IfEvent,XPending,XPutBackEvent,XSelectlnput, XSendEvent, XSetlnput-Focus,XSynchronize,XWindowEvent.
Name
XGetNormalHints — get the size hints property of a window in normal state (not zoomed or iconified).
Synopsis
Status XGetNormalHints(display, w, hints) Display *display; Window w; XSizeHints *hints; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window to be queried.
hints Returns the sizing hints for the window in its normal state.
Description
XGetNormalHints has been superseded by XGetWMNormalHints as of Release 4, because new interclient communication conventions are now standard.
XGetNormalHints returns the size hints for a window in its normal state by reading the XA_WM_NORMAL_HINTS property. This function is normally used only by a window manager. It returns a nonzero Status if it succeeds, and zero if it fails (e.g., the application specified no normal size hints for this window.)
For more information on using hints, see Volume One, Chapter W,Interclient Communication. Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints;
/* flags argument in size hints */
ttdefine USPosition (1L « O)/* user specified x, y */
#define USSize (1L « I)/* user specified width, height */
#define PPosition (1L « 2)/* program specified position */
#define PSize (1L « 3)/* program specified size */
#define PMinSize (1L « 4)/* program specified minimum size */
tdefine PMaxSize (1L « 5)/* program specified maximum size */
234 Xlib Reference Manual
Xlib - Window Manager Hints (continued) XGetNormalHintS
tdefine PResizelnc (1L « 6)/* program specified resize increments */ #define PAspect (1L « 7)/* program specified min/max aspect ratios */ #define PAllHints (PPosition|PSizeIPMinSizeIPMaxSize|PResizelncIPAspect)
Errors
BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName,XGetlconSizes,XGetSize-Hints, XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass-Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints,XSet-SizeHints, XSetTransientForHint,XSetWMHints, XSetZoomHints,XStore-Name.
XGetPixel
\
-Xlib- Images-
Name
XGetPixel — obtain a single pixel value from an image.
Synopsis
unsigned long XGetPixel (ximage, x, y) Xlmage * ximage; int x; int y;
Arguments
ximage
x
y
Specifies a pointer to the image.
Specify the x and y coordinates of the pixel whose value is to be returned.
Description
XGetPixel returns the specified pixel from the named image. The x and y coordinates are relative to the origin (upper left [0,0]) of the image). The pixel value is returned in the clients bit- and byte-order. The x and y coordinates must be contained in the image.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
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; char *obdata; struct funcs {
struct _XImage * (*create_image) () ;
int (*destroy_image)();
unsigned long (*get_pixel)();
int (*put_pixel)();
struct _XImage * (*sub_image) () ;
int (*add_pixel)(); } f; } Ximage;
size of image */
number of pixels offset in X direction */
/* XYBitmap, XYPixmap, ZPixmap */
pointer to image data */
data byte order, LSBFirst, MSBFirst */
quant, of scan line 8, 16, 32 */
LSBFirst, MSBFirst */
8, 16, 32 either XY or ZPixmap */
depth of image */
accelerator to next line */
bits per pixel (ZPixmap) */
bits in z arrangment */
/* hook for the object routines to hang on /* image manipulation routines */
Xlib Reference Manual
Related Commands
ImageByteOrder, XAddPixel, XCreateImage, XDestroyImage, XGetlmage, XGetSublmage, XPutlmage, XPutPixel, XSublmage.
Xlib Reference Manual 237
XGetPointerControl "\
Xlib-Pointer-
Name
XGetPointerControl — get the current pointer preferences.
Synopsis
XGetPointerControl(display, accel_numerator, accel_denominator,
threshold) Display * display;
int *accel_numerator f *accel_denominator; /* RETURN */ int * threshold; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
accel_numerator
Returns the numerator for the acceleration multiplier.
accel_denominator
Returns the denominator for the acceleration multiplier.
threshold Returns the acceleration threshold in pixels. The pointer must move more than this amount before acceleration takes effect.
Description
XGetPointerControl gets the pointer acceleration parameters.
accel_numerator divided by accel_denominator is the number of pixels the cursor moves per unit of motion of the pointer, applied only to the amount of movement over threshold.
Related Commands
XChangeActivePointerGrab,XChangePointerControl,XGetPointer-Mapping,XGrabPointer,XQueryPointer, XSetPointerMapping,XUngrab-Pointer, XWarpPointer.
Xlib Reference Manual
— Xlib-Pointer •
J XGetPointerMapping
Name
XGetPointerMapping — get the pointer button mapping.
Synopsis
int XGetPointerMapping(display, map, nmap) Display * display;
unsigned char map [ ] ; /* RETURN */ int nmap;
Arguments
displ ay Specifies a connection to an X server; returned from XOpenDisplay.
map Returns the mapping list. Array begins with map [ ].
nmap Specifies the number of items in mapping list.
Description
XGetPointerMapping returns the current mapping of the pointer buttons. Information is returned in both the arguments and the function's return value, map is an array of the numbers of the buttons as they are currently mapped. Elements of the list are indexed starting from 1. The nominal mapping for a pointer is the identity mapping: map[i]=i. If map [3] =2, it means that the third physical button triggers the second logical button.
nmap indicates the desired number of button mappings.
The return value of the function is the actual number of elements in the pointer list, which may be greater or less than nmap.
Related Commands
XChangeActivePointerGrab,XChangePointerControl, XGetPointer-Control,XGrabPointer,XQueryPointer, XSetPointerMapping,XUngrab-Pointer,XWarpPointer.
XGetRGBColOrmapS \ x,, b -W,ndow Manages-
Name
XGetRGBColormaps — obtain the XStandardColormap structure associated with the specified property.
Synopsis
Status XGetRGBColormaps( display, w, std_colormap, count,
property) Display *display; Window w;
XStandardColormap **std_colormap; /* RETURN */ int * count; /* RETURN */
Atom property;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
std_colormap
Returns the XStandardColormap structure.
count Returns the number of colormaps.
property Specifies the property name.
Availability
Release 4 and later.
Description
XGetRGBColormaps returns the RGB colormap definitions stored in the specified property on the named window. If the property exists, is of type RGB_COLOR_MAP , is of format 32, and is long enough to contain a colormap definition, XGetRGBColormaps allocates and fills in space for the returned colormaps, and returns a non-zero status. Otherwise, none of the fields are set, and XGetRGBColormaps returns a zero status. If the visualid field is not present, XGetRGBColormaps assumes the default visual for the screen on which the window is located; if the killid field is not present, it is assumed to have a value of None, which indicates that the resources cannot be released. Note that it is the caller's responsibility to honor the ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition.
XGetRGBColormaps supersedes XGetStandardColormap. For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green max;
Xlib Reference Manual
Xlib - Window Manager Hints (continued) XGetRGBColormaps
unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel;
VisuallD visualid; /* added by ICCCM version 1 */
XID killid; /* added by ICCCM version 1 */
} XStandardColormap;
Errors
BadAtom BadWindow
Related Commands
XAllocStandardColormap,XSetRGBColormaps.
XGetScreenSaver \.
•Xllb - Screen Saver—
Name
XGetScreenSaver — get the current screen saver parameters.
Synopsis
XGetScreenSaver( display, timeout, interval, prefer_blanking,
allow_exposures) Display *display;
int *timeout, * interval ; /* RETURN */ int *prefer_blanking; /* RETURN */
int *allow_exposures; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XQpenDisplay.
timeout Returns the idle time, in seconds, until the screen saver turns on.
interval Returns the interval between screen changes, in seconds.
prefer_blanking
Returns the current screen blanking preference, one of these constants: DontPreferBlanking,PreferBlanking, or DefaultBlanking.
allotvr_exposures
Returns the current screen save control value, either DontAllow-Exposures, AllowExposures, or DefaultExposures.
Description
XGetScreenSaver returns the current settings of the screen saver, which may be set with
XSetScreenSaver.
A positive timeout indicates that the screen saver is enabled. A timeout of zero indicates that the screen saver is disabled.
If the server-dependent screen saver method supports periodic change, interval serves as a hint about the length of the change period, and zero serves as a hint that no periodic change will be made. An interval of zero indicates that random pattern motion is disabled.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XActivateScreenSaver,XForceScreenSaver,XResetScreenSaver,XSet-ScreenSaver.
— Xlib-Selections-
J XGetSelectionOwner
Name
XGetSelectionOwner — return the owner of a selection.
Synopsis
Window XGetSelectionOwner( display, selection) Display * display; Atom selection;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
selecti on Specifies the selection atom whose owner you want returned. Description
XGetSelectionOwner returns the window ID of the current owner of the specified selec tion. If no selection was specified, or there is no owner, the function returns the constant None,
For more information on selections, see Volume One, Chapter WJnterclient Communication. Errors
BadAtom
Related Commands
XConvertSelection,XSetSelectionOwner.
X,,b-W,ndowMan ag er «,„«,-
Name
XGetSizeHintS — read any property of type XA_SIZE_HINTS.
Synopsis
Status XGetSizeHintS( display, w, hints, property) Display *display; Window w;
XSizeHints *hints; /* RETURN */ Atom property;
Arguments
di spl ay Specifies a connection to an X server; returned from XOpenDi sp 1 ay.
w Specifies the ID of the window for which size hints will be returned.
hints Returns the size hints structure.
property Specifies a property atom of type XA_WM_SIZE_HINTS. May be XA_WM_NORMAL_HINTS, XA_WM_ZOOM_HINTS (in Release 3), or a property defined by an application.
Description
XGetSizeHintS has been superseded by XGetWMSizeHints as of Release 4, because the interclient communication conventions are now standard.
XGetSizeHintS returns the XSizeHints structure for the named property and the speci fied window. This is used by XGetNormalHints and XGetZoomHints, and can be used to retrieve the value of any property of type XA_WM_SIZE_HINTS; thus, it is useful if other proper ties of that type get defined. This function is used almost exclusively by window managers.
XGetSizeHintS returns a nonzero Status if a size hint was defined, and zero otherwise. For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
244 Xlib Reference Manual
Xlib - Window Manager Hints
(continued)
XGetSizeHints
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) A
tdefine PMinSize (1L « 4) /'
#define PMaxSize (1L « 5) /'
tfdefine PResizelnc (1L « 6) /'
#define PAspect (1L « 7) /'
program specified size */ program specified minimum size */ program specified maximum size */ program specified resize increments */ program specified min/max aspect ratios */
tdefine PAllHints (PPosition|PSizeIPMinSizeIPMaxSizeIPResizelncIPAspect)
Errors
BadAtom BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName, XGetlconSizes,XGetNormal-Hints, XGetTransientForHint,XGetWMHints,XGetZoomHints,XSetClass-Hint,XSetCommand, XSetlconName,XSetlconSizes, XSetNormalHints,XSet-SizeHints,XSetTransientForHint,XSetWMHints, XSetZoomHints, XStore-Name.
Xlib Reference Manual
Name
XGetStandardColormap — get the standard colormap property.
Synopsis
Status XGetStandardColormap( display, w, cmap_info, property) Display * display; Window w;
XStandardColormap *cmap_info;/* RETURN */ Atom property;
Arguments
di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay.
w Specifies the ID of the window on which the property is set. This is normally
the root window.
cmap_info Returns the filled colormap information structure.
property Specifies the atom indicating the type of standard colormap desired. The predefined standard colormap atoms are XA_RGB_BEST_MAP,
XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP.
Description
XGetStandardColormap is superseded by XGetWMColormap in Release 4.
XGetStandardColormap gets a property on the root window that describes a standard colormap.
This call does not install the colormap into the hardware colormap, it does not allocate entries, and it does not even create a virtual colormap. It just provides information about one design of colormap and the ID of the colormap if some other client has already created it. The applica tion can otherwise attempt to create a virtual colormap of the appropriate type, and allocate its entries according to the information in the XStandardColormap structure. Installing the colormap must then be done with XlnstallColormap, in cooperation with the window manager. Any of these steps could fail, and the application should be prepared.
If the server or another client has already created a standard colormap of this type, then its ID will be returned in the colormap member of the XStandardColormap structure. Some servers and window managers, particular on high-performance workstations, will create some or all of the standard colormaps so they can be quickly installed when needed by applications.
Get Xlib Reference Manual for Version 11 Volume 2, 5th Editon now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
