The X Version 11 and X Version 10 functions discussed in this appendix are obsolete, have been superseded by newer X Version 11 functions, and are maintained for compatibility reasons only. You can use the X Version 11 compatibility functions to: Set standard properties Set and get window sizing hints Set and get an XStandardColormap structure Parse window geometry Get X environment defaults To specify a minimum set of properties describing the simplest application, use XSetStandardProperties. This function has been superseded by XSetWMProperties and sets all or portions of the WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, and WM_NORMAL_HINTS properties. XSetStandardProperties XSetStandardProperties Display *display Window w char *window_name char *icon_name Pixmap icon_pixmap char **argv int argc XSizeHints *hints display Specifies the connection to the X server. w Specifies the window. window_name Specifies the window name, which should be a null-terminated string. icon_name Specifies the icon name, which should be a null-terminated string. icon_pixmap Specifies the bitmap that is to be used for the icon or None. argv Specifies the application's argument list. argc Specifies the number of arguments. hints Specifies a pointer to the size hints for the window in its normal state. The XSetStandardProperties function provides a means by which simple applications set the most essential properties with a single call. XSetStandardProperties should be used to give a window manager some information about your program's preferences. It should not be used by applications that need to communicate more information than is possible with XSetStandardProperties. (Typically, argv is the argv array of your main program.) If the strings are not in the Host Portable Character Encoding, the result is implementation-dependent. XSetStandardProperties can generate BadAlloc and BadWindow errors. Xlib provides functions that you can use to set or get window sizing hints. The functions discussed in this section use the flags and the XSizeHints structure, as defined in the <X11/Xutil.h> X11/Xutil.h Files<X11/Xutil.h> Headers<X11/Xutil.h> header file and use the WM_NORMAL_HINTS property. To set the size hints for a given window in its normal state, use XSetNormalHints. This function has been superseded by XSetWMNormalHints. XSetNormalHints XSetNormalHints Display *display Window w XSizeHints *hints display Specifies the connection to the X server. w Specifies the window. hints Specifies a pointer to the size hints for the window in its normal state. The XSetNormalHints function sets the size hints structure for the specified window. Applications use XSetNormalHints to inform the window manager of the size or position desirable for that window. In addition, an application that wants to move or resize itself should call XSetNormalHints and specify its new desired location and size as well as making direct Xlib calls to move or resize. This is because window managers may ignore redirected configure requests, but they pay attention to property changes. To set size hints, an application not only must assign values to the appropriate members in the hints structure but also must set the flags member of the structure to indicate which information is present and where it came from. A call to XSetNormalHints is meaningless, unless the flags member is set to indicate which members of the structure have been assigned values. XSetNormalHints can generate BadAlloc and BadWindow errors. To return the size hints for a window in its normal state, use XGetNormalHints. This function has been superseded by XGetWMNormalHints. XGetNormalHints Status XGetNormalHints Display *display Window w XSizeHints *hints_return display Specifies the connection to the X server. w Specifies the window. hints_return Returns the size hints for the window in its normal state. The XGetNormalHints function returns the size hints for a window in its normal state. It returns a nonzero status if it succeeds or zero if the application specified no normal size hints for this window. XGetNormalHints can generate a BadWindow error. The next two functions set and read the WM_ZOOM_HINTS property. To set the zoom hints for a window, use XSetZoomHints. This function is no longer supported by the Inter-Client Communication Conventions Manual. XSetZoomHints XSetZoomHints Display *display Window w XSizeHints *zhints display Specifies the connection to the X server. w Specifies the window. zhints Specifies a pointer to the zoom hints. Many window managers think of windows in one of three states: iconic, normal, or zoomed. The XSetZoomHints function provides the window manager with information for the window in the zoomed state. XSetZoomHints can generate BadAlloc and BadWindow errors. To read the zoom hints for a window, use XGetZoomHints. This function is no longer supported by the Inter-Client Communication Conventions Manual. XGetZoomHints Status XGetZoomHints Display *display Window w XSizeHints *zhints_return display Specifies the connection to the X server. w Specifies the window. zhints_return Returns the zoom hints. The XGetZoomHints function returns the size hints for a window in its zoomed state. It returns a nonzero status if it succeeds or zero if the application specified no zoom size hints for this window. XGetZoomHints can generate a BadWindow error. To set the value of any property of type WM_SIZE_HINTS, use XSetSizeHints. This function has been superseded by XSetWMSizeHints. XSetSizeHints XSetSizeHints Display *display Window w XSizeHints *hints Atom property display Specifies the connection to the X server. w Specifies the window. hints Specifies a pointer to the size hints. property Specifies the property name. The XSetSizeHints function sets the XSizeHints structure for the named property and the specified window. This is used by XSetNormalHints and XSetZoomHints and can be used to set the value of any property of type WM_SIZE_HINTS. Thus, it may be useful if other properties of that type get defined. XSetSizeHints can generate BadAlloc, BadAtom, and BadWindow errors. To read the value of any property of type WM_SIZE_HINTS, use XGetSizeHints. This function has been superseded by XGetWMSizeHints. XGetSizeHints Status XGetSizeHints Display *display Window w XSizeHints *hints_return Atom property display Specifies the connection to the X server. w Specifies the window. hints_return Returns the size hints. property Specifies the property name. The XGetSizeHints function returns the XSizeHints structure for the named property and the specified window. This is used by XGetNormalHints and XGetZoomHints. It also can be used to retrieve the value of any property of type WM_SIZE_HINTS. Thus, it may be useful if other properties of that type get defined. XGetSizeHints returns a nonzero status if a size hint was defined or zero otherwise. XGetSizeHints can generate BadAtom and BadWindow errors. To get the XStandardColormap structure associated with one of the described atoms, use XGetStandardColormap. This function has been superseded by XGetRGBColormaps. XGetStandardColormap Status XGetStandardColormap Display *display Window w XStandardColormap *colormap_return Atom property display Specifies the connection to the X server. w Specifies the window. colormap_return Returns the colormap associated with the specified atom. property Specifies the property name. The XGetStandardColormap function returns the colormap definition associated with the atom supplied as the property argument. XGetStandardColormap returns a nonzero status if successful and zero otherwise. For example, to fetch the standard GrayScale colormap for a display, you use XGetStandardColormap with the following syntax: XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, XA_RGB_GRAY_MAP); See section 14.3 for the semantics of standard colormaps. XGetStandardColormap can generate BadAtom and BadWindow errors. To set a standard colormap, use XSetStandardColormap. This function has been superseded by XSetRGBColormaps. XSetStandardColormap XSetStandardColormap Display *display Window w XStandardColormap *colormap Atom property display Specifies the connection to the X server. w Specifies the window. colormap Specifies the colormap. property Specifies the property name. The XSetStandardColormap function usually is only used by window or session managers. XSetStandardColormap can generate BadAlloc, BadAtom, BadDrawable, and BadWindow errors. To parse window geometry given a user-specified position and a default position, use XGeometry. This function has been superseded by XWMGeometry. Windowdetermining location XGeometry int XGeometry Display *display int screen char*position, *default_position unsignedint bwidth unsignedintfwidth, fheight intxadder, yadder int*x_return, *y_return int*width_return, *height_return display Specifies the connection to the X server. screen Specifies the screen. position default_position Specify the geometry specifications. bwidth Specifies the border width. fheight fwidth Specify the font height and width in pixels (increment size). xadder yadder Specify additional interior padding needed in the window. x_return y_return Return the x and y offsets. width_return height_return Return the width and height determined. You pass in the border width (bwidth), size of the increments fwidth and fheight (typically font width and height), and any additional interior space (xadder and yadder) to make it easy to compute the resulting size. The XGeometry function returns the position the window should be placed given a position and a default position. XGeometry determines the placement of a window using a geometry specification as specified by XParseGeometry and the additional information about the window. Given a fully qualified default geometry specification and an incomplete geometry specification, XParseGeometry returns a bitmask value as defined above in the XParseGeometry call, by using the position argument. The returned width and height will be the width and height specified by default_position as overridden by any user-specified position. They are not affected by fwidth, fheight, xadder, or yadder. The x and y coordinates are computed by using the border width, the screen width and height, padding as specified by xadder and yadder, and the fheight and fwidth times the width and height from the geometry specifications. The XGetDefault function provides a primitive interface to the resource manager facilities discussed in chapter 15. It is only useful in very simple applications. XGetDefault char *XGetDefault Display *display char *program char *option display Specifies the connection to the X server. program Specifies the program name for the Xlib defaults (usually argv[0] of the main program). option Specifies the option name. The XGetDefault function returns the value of the resource prog.option, where prog is the program argument with the directory prefix removed and option must be a single component. Note that multilevel resources cannot be used with XGetDefault. The class "Program.Name" is always used for the resource lookup. If the specified option name does not exist for this program, XGetDefault returns NULL. The strings returned by XGetDefault are owned by Xlib and should not be modified or freed by the client. If a database has been set with XrmSetDatabase, that database is used for the lookup. Otherwise, a database is created and is set in the display (as if by calling XrmSetDatabase). The database is created in the current locale. To create a database, XGetDefault uses resources from the RESOURCE_MANAGER property on the root window of screen zero. If no such property exists, a resource file in the user's home directory is used. On a POSIX-conformant system, this file is "$HOME/.Xdefaults". Files$HOME/.Xdefaults 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 "$HOME/.Xdefaults-name" , where name specifies the name of the machine on which the application is running. You can use the X Version 10 compatibility functions to: Draw and fill polygons and curves Associate user data with a value Xlib provides functions that you can use to draw or fill arbitrary polygons or curves. These functions are provided mainly for compatibility with X Version 10 and have no server support. That is, they call other Xlib functions, not the server directly. Thus, if you just have straight lines to draw, using XDrawLines XDrawLines or XDrawSegments XDrawSegments is much faster. The functions discussed here provide all the functionality of the X Version 10 functions XDraw, X10 compatibilityXDraw XDrawFilled, X10 compatibilityXDrawFilled XDrawPatterned, X10 compatibilityXDrawPatterned XDrawDashed, X10 compatibilityXDrawDashed and XDrawTiled. X10 compatibilityXDrawTiled They are as compatible as possible given X Version 11's new line-drawing functions. One thing to note, however, is that VertexDrawLastPoint is no longer supported. Also, the error status returned is the opposite of what it was under X Version 10 (this is the X Version 11 standard error status). XAppendVertex and XClearVertexFlag from X Version 10 also are not supported. Just how the graphics context you use is set up actually determines whether you get dashes or not, and so on. Lines are properly joined if they connect and include the closing of a closed figure (see XDrawLines). The functions discussed here fail (return zero) only if they run out of memory or are passed a Vertex list that has a Vertex with VertexStartClosed set that is not followed by a Vertex with VertexEndClosed set. To achieve the effects of the X Version 10 XDraw, X10 compatibilityXDraw XDrawDashed, X10 compatibilityXDrawDashed and XDrawPatterned, X10 compatibilityXDrawPatterned use XDraw. #include <X11/X10.h> Status XDraw Display *display Drawable d GC gc Vertex *vlist int vcount display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the GC. vlist Specifies a pointer to the list of vertices that indicate what to draw. vcount Specifies how many vertices are in vlist. The XDraw function draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of vertices (vlist). The points are connected by lines as specified in the flags in the vertex structure. Each Vertex, as defined in <X11/X10.h>, X11/X10.h Files<X11/X10.h> Headers<X11/X10.h> is a structure with the following members: Vertex typedef struct _Vertex { short x,y; unsigned short flags; } Vertex; The x and y members are the coordinates of the vertex that are relative to either the upper left inside corner of the drawable (if VertexRelative is zero) or the previous vertex (if VertexRelative is one). The flags, as defined in <X11/X10.h>, X11/X10.h Files<X11/X10.h> Headers<X11/X10.h> are as follows: VertexRelative VertexDontDraw VertexCurved VertexStartClosed VertexEndClosed VertexRelative 0x0001 /* else absolute */ VertexDontDraw 0x0002 /* else draw */ VertexCurved 0x0004 /* else straight */ VertexStartClosed 0x0008 /* else not */ VertexEndClosed 0x0010 /* else not */ If VertexRelative is not set, the coordinates are absolute (that is, relative to the drawable's origin). The first vertex must be an absolute vertex. If VertexDontDraw is one, 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 VertexCurved is one, a spline algorithm is used to draw a smooth curve from the previous 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 one only if a previous and next vertex are both defined (either explicitly in the array or through the definition of a closed curve). It is permissible for VertexDontDraw bits and VertexCurved bits both to be one. This is useful if you want to define the previous point for the smooth curve but do not want an actual curve drawing to start until this point. If VertexStartClosed is one, then this point marks the beginning of a closed curve. This vertex must be followed later in the array by another vertex whose effective coordinates are identical and that has a VertexEndClosed bit of one. The points in between form a cycle to determine predecessor and successor vertices for the spline algorithm. This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, and dash-list. To achieve the effects of the X Version 10 XDrawTiled X10 compatibilityXDrawTiled and XDrawFilled, X10 compatibilityXDrawFilled use XDrawFilled. #include <X11/X10.h> Status XDrawFilled Display *display Drawable d GC gc Vertex *vlist int vcount display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the GC. vlist Specifies a pointer to the list of vertices that indicate what to draw. vcount Specifies how many vertices are in vlist. The XDrawFilled function draws arbitrary polygons or curves and then fills them. This function uses these GC components: function, plane-mask, line-width, line-style, cap-style, join-style, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin, dash-offset, dash-list, fill-style, and fill-rule. These functions have been superseded by the context management functions (see section 16.10). It is often necessary to associate arbitrary information with resource IDs. Xlib provides the XAssocTable functions that you can use to make such an association. Hash Lookup WindowIDs Resource IDs Application programs often need to be able to easily refer to their own data structures when an event arrives. The XAssocTable system provides users of the X library with a method for associating their own data structures with X resources (Pixmaps, Fonts, Windows, and so on). An XAssocTable can be used to type X resources. For example, the user may want to have three or four types of windows, each with different properties. This can be accomplished by associating each X window ID with a pointer to a window property data structure defined by the user. A generic type has been defined in the X library for resource IDs. It is called an XID. There are a few guidelines that should be observed when using an XAssocTable : All XIDs are relative to the specified display. Because of the hashing scheme used by the association mechanism, the following rules for determining the size of a XAssocTable should be followed. Associations will be made and looked up more efficiently if the table size (number of buckets in the hashing system) is a power of two and if there are not more than 8 XIDs per bucket. To return a pointer to a new XAssocTable, use XCreateAssocTable. XCreateAssocTable XAssocTable *XCreateAssocTable int size size Specifies the number of buckets in the hash system of XAssocTable. The size argument specifies the number of buckets in the hash system of XAssocTable. For reasons of efficiency the number of buckets should be a power of two. Some size suggestions might be: use 32 buckets per 100 objects, and a reasonable maximum number of objects per buckets is 8. If an error allocating memory for the XAssocTable occurs, a NULL pointer is returned. To create an entry in a given XAssocTable, use XMakeAssoc. XMakeAssoc XMakeAssoc Display *display XAssocTable *table XID x_id char *data display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. data Specifies the data to be associated with the X resource ID. The XMakeAssoc function inserts data into an XAssocTable keyed on an XID. Data is inserted into the table only once. Redundant inserts are ignored. The queue in each association bucket is sorted from the lowest XID to the highest XID. To obtain data from a given XAssocTable, use XLookUpAssoc. XLookUpAssoc char *XLookUpAssoc Display *display XAssocTable *table XID x_id display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. The XLookUpAssoc function retrieves the data stored in an XAssocTable by its XID. If an appropriately matching XID can be found in the table, XLookUpAssoc returns the data associated with it. If the x_id cannot be found in the table, it returns NULL. To delete an entry from a given XAssocTable, use XDeleteAssoc. XDeleteAssoc XDeleteAssoc Display *display XAssocTable *table XID x_id display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. The XDeleteAssoc function deletes an association in an XAssocTable keyed on its XID. Redundant deletes (and deletes of nonexistent XIDs) are ignored. Deleting associations in no way impairs the performance of an XAssocTable. To free the memory associated with a given XAssocTable, use XDestroyAssocTable. XDestroyAssocTable XDestroyAssocTable XAssocTable *table table Specifies the assoc table.