O'Reilly logo

Xlib Reference Manual for Version 11 Volume 2, 5th Editon by Adrian Nye

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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&le; 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.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required