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

If the extension involves additional event types, the base event type code is returned in first__event. Otherwise, zero is returned in first_event. The format of the events is specific to the extension.

If the extension involves additional error codes, the base error code is returned in first_error. Otherwise, zero is returned. The format of additional data in the errors is specific to the extension.

See Volume One, Chapter 13, Other Programming Techniques, for more information on using extensions, and Volume One, Appendix C, Writing Extensions to X, for information on writing them.

Related Commands

XFreeExtensionList,XListExtensions.

XQueryFont , X|ib FOM> _

Name

XQueryFont — return information about a loaded font.

Synopsis

XFontStruct *XQueryFont(display, font_ID) Display * display; XID font_ID;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

font_io Specifies either the font ID or the graphics context ID. You can declare the

data type for this argument as either Font or GContext (both X IDs). If GContext, the font in that GC will be queried.

Description

XQueryFont returns a pointer to an XFontStruct structure containing information describing the specified font. This call is needed if you loaded the font with XLoadFont, but need the font information for multiple calls to determine the extent of text. XLoadQuery-Font combines these two operations.

If the font hasn't been loaded (or the font ID passed is invalid), XQueryFont returns NULL.

If font_lD is declared as data type GContext (also a resource ID), this function queries the font specified by the font component of the GC specified by this ID. This is useful for getting information about the default font, whose ID is stored in the default GC. However, in this case the GContext ID will be the ID stored in the fid field of the returned XFontStruct, and you can't use that ID in XSetFont or XUnloadFont, since it is not itself the ID of the font.

Use XFreeFont to free this data.

For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadFont

Structures

typedef struct {

XExtData *ext_data; /* hook for extension to hang data */

Font fid; /* font ID for this font */

unsigned direction; /* hint about direction 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*/

Xllb - Fonts

(continued)

XQueryFont

XCharStruct int ascent; int descent;

XFontStruct;

•per char;

/* first_char to last_char information */

/* logical extent above baseline for spacing */

/* logical descent below baseline for spacing */

Related Commands

XCreateFontCursor,XFreeFont,XFreeFontlnfo, XFreeFontNames,XFree-FontPath,XGetFontPath,XGetFontProperty,XListFonts, XListFontsWith-Info,XLoadFont,XLoadQueryFont,XSetFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual

XQueryKeymap \ X|ib _ Keyboard _

Name

XQueryKeymap — obtain a bit vector for the current state of the keyboard.

Synopsis

XQue ryKeymap ( di spl ay, keys) Display * display; char keys [32] ; /* RETURN */

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenD i sp 1 ay.

keys Returns an array of bytes that identifies which keys are pressed down. Each

bit represents one key of the keyboard.

Description

XQueryKeymap returns a bit vector for the logical state of the keyboard, where each bit set to 1 indicates that the corresponding key is currently pressed down. The vector 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. Note that the logical state may lag the physical state if device event processing is frozen due to a grab.

Related Commands

XChangeKeyboardMapping,XDeleteModifiermapEntry, XFreeModifiermap, XGetKeyboardMapping,XGetModifierMapping, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString, XLookupKeysym, XLookupString,XNewModifierMap,XRebindKeysym, XRefreshKeyboard-Mapping,XSetModifierMapping,XStringToKeysym.

— Xlib-Pointer-

J XQueryPointer

Name

XQueryPointer — get the current pointer location.

Synopsis

Bool XQueryPointer(display, w, root, child, root_x, root_y,

win_x, win_y, keys_buttons) Display *display; Window w;

Window *root, *child; /* RETURN */

int *root_x, *root_y; /* RETURN */

int *win_x, *win_y; /* RETURN */

unsigned int *keys_buttons / /* RETURN */

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies a window which indicates which screen the pointer position is

returned for, and child will be a child of this window if pointer is inside a child.

root Returns the root window ID the pointer is currently on.

child Returns the ID of the child of w the pointer is located in, or zero if it not in a

child.

root_x Return the x and y coordinates of the pointer relative to the root's origin. root_y

win_x Return the x and y coordinates of the pointer relative to the origin of window w.

win_y

keys_buttons

Returns the current state of the modifier keys and pointer buttons. This is a mask composed of the OR of any number of the following symbols: Shift-Mask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, ModSMask, ButtonlMask, Button2Mask, ButtonSMask, Button4Mask,ButtonSMask.

Description

XQueryPointer gets the pointer coordinates relative to a window and relative to the root window, the root window ID and the child window ID (if any) the pointer is currently in, and the current state of modifier keys and buttons.

If XQueryPointer returns False, then the pointer is not on the same screen as v, child is None, and win_x and win_y are zero. However, root, root_x, and root_y are still valid. If XQueryPointer returns True, then the pointer is on the same screen as the win dow v/, and all return values are valid.

The logical state of the pointer buttons and modifier keys can lag behind their physical state if device event processing is frozen due to a grab.

XQueryPointer (continued) Xllb - Pointer

Errors

BadWindow

Related Commands

XChangeActivePointerGrab, XChangePointerControl, XGetPointer-Control, XGetPointerMapping,XGrabPointer, XSetPointerMapping, XUngrabPointer, XWarpPointer.

— Xlib-Text-

J XQueryTextExtents

Name

XQueryTextExtents — query the server for string and font metrics. Synopsis

XQueryTextExtents( display, font_ID, string, nchars,

direction, ascent, descent, overall) Display *display; XID font_ID; char *string; int nchars;

int * direct ion; /* RETURN */

int * ascent, *descent; /* RETURN */ XCharStruct *overall; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

font_lD Specifies the appropriate font ID previously returned by XLoadFont, or the

GContext that specifies the font.

string Specifies the character string for which metrics are to be returned.

nchars Specifies the number of characters in string.

direction Returns the direction the string would be drawn using the specified font. Either FontLef tToRight or FontRightToLef t.

ascent Returns the maximum ascent for the specified font.

descent Returns the maximum descent for the specified font.

overall Returns the overall characteristics of the string. These are the sum of the

width measurements for each character, the maximum ascent and descent, the minimum Ibearing added to the width of all characters up to the character with the smallest Ibearing, and the maximum rbearing added to the width of all characters up to the character with the largest rbearing.

Description

XQueryTextExtents returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by XTextExtents, but XQueryTextExtents does not require a filled XFont-Inf o structure stored on the client side. Therefore, this would be used when memory is pre cious, or when just a small number of text width calculations are to be done.

The returned ascent and descent should usually be used to calculate the line spacing, while the width, rbearing, and Ibearing members of overall should be used for hori zontal measures. The total height of the bounding rectangle, good for any string in this font, is

ascent+descent.

XQueryTextExtentS (continued) Xlib - Text

overall. ascent is the maximum of the ascent metrics of all characters in the string. The overall. descent is the maximum of the descent metrics. The overall. width is the sum of the character-width metrics of all characters in the string. The overall . Ibearing is usually the Ibearing of the first character in the string, and overall. rbearing is the rbearing of the last character in the string plus the sum of the widths of all the characters up to but not including the last character. More technically, here is the X protocol definition: For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string, let L be the Ibearing metric of the character plus W, and let R be the rbearing metric of the character plus W. The overall. Ibearing is the minimum L of all characters in the string, and the overall. rbearing is the maximum R.

For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

typedef struct {

short Ibearing; /* origin to left edge of character */

short rbearing; /* origin to right edge of character */

short width; /* advance to next char's origin */

short ascent; /* baseline to top edge of character */

short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */

} XCharStruct;

Errors

BadFont

Related Commands

XDrawImageString,XDrawImageStringl6,XDrawString,XDrawStringl6, XDrawText,XDrawTextl6,XQueryTextExtentS16,XTextExtents, XText-Extentsl6,XTextWidth, XTextWidthlG.

— Xlib-Text-

J XQueryTextExtentsI 6

Name

XQueryTextExtentsI6 — query the server for string and font metrics of a 16-bit character string.

Synopsis

XQueryTextExtentsI6(display, font_ID, string, nchars,

direction, ascent, descent, overall) Display * display; XID font_ID; XChar2b *string; int nchars;

int * direct ion; /* RETURN */

int *ascent, *descent; /* RETURN */ XCharStruct * overall; /* RETURN */

Arguments

di splay Specifies a connection to an X server; returned from xopenDisplay.

font_TD Specifies the appropriate font ID previously returned by XLoadFont, or the

GContext that specifies the font.

string Specifies the character string for which metrics are to be returned.

nchars Specifies the number of characters in string.

direction Returns the direction of painting in the specified font. Either FontLef tto-

Right or FontRighttoLeft.

a scent Returns the maximum ascent in pixels for the specified font.

descent Returns the maximum descent in pixels for the specified font.

overall Returns the overall characteristics of the string. These are the sum of the

Description

XQueryTextExtentsI6 returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by XTextExtentslG, but XQueryTextExtents does not require a filled XFontlnf o structure.

ascent + descent.

XQueryTextExtentSl 6 (continued) Xlib - Text

overall. ascent is the maximum of the ascent metrics of all characters in the string. The overall. descent is the maximum of the descent metrics. The overall. width is the sum of the character-width metrics of all characters in the string. The overall. Ibearing is usually the Ibearing of the first character in the string, and overall. rbearing is the rbearing of the last character in the string plus the sum of the widths of all the characters up to but not including the last character. More technically, here is the X protocol definition: For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string, let L be the Wearing metric of the character plus W, and let R be the rbearing metric of the character plus W. The overall. Ibearing is the minimum L of all characters in the string, and the overall. rbearing is the maximum R.

For fonts defined with linear indexing rather than two-byte matrix indexing, the server inter prets each XChar2b as a 16-bit number that has been transmitted with the most significant byte first. That is, byte one of the XChar2b is taken as the most significant byte.

If the font has no defined default character, then undefined characters in the string are taken to have all zero metrics.

Structures

typedef struct { /* normal 16-bit characters are two bytes */

unsigned char bytel;

unsigned char byte2; } XChar2b;

typedef struct {

short Ibearing; /* origin to left edge of character */

short rbearing; /* origin to right edge of character */

short width; /* advance to next char's origin */

short ascent; /* baseline to top edge of character */

short descent; /* baseline to bottom edge of character */ unsigned short attributes; /* per char flags (not predefined) */

} XCharStruct;

Errors

BadFont

Related Commands

XDrawImageString,XDrawImageStringlG,XDrawString, XDrawStringlG, XDrawText,XDrawTextlS, XQueryTextExtents,XTextExtents, XText-Extentsl6, XTextWidth, XTextWidthl6.

— Xlib - Window Manipulation-Name

XQueryTree — return a list of children, parent, and root.

Synopsis

Status XQueryTree ( display, w

nchildren) Display *display; Window w;

Window *root; /* RETURN

Window *parent ; /* RETURN

Window ** children; /* RETURN unsigned int *nchildren; /* RETURN

XQueryTree

root, parent, children,

*/ */ */ */

Arguments

display

Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be queried. For this window, XQuery

Tree will list its children, its root, its parent, and the number of children.

root Returns the root ID for the specified window.

parent Returns the parent window of the specified window.

children Returns the list of children associated with the specified window. nchildren Returns the number of children associated with the specified window. Description

XQueryTree uses its last four arguments to return the root ID, the parent ID, a pointer to a list of children and the number of children in that list, all for the specified window w. The chil dren are listed in current stacking order, from bottommost (first) to topmost (last). XQuery Tree returns zero if it fails, nonzero if it succeeds.

You should deallocate the list of children with XFree when it is no longer needed.

Errors

BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown, XCirculate-SubwindowsUp,XConfigureWindow,XLowerWindow, XMoveResizeWindow, XMoveWindow, XRaiseWindow,XReparentWindow, XResizeWindow, XRestack-Windows.

Xlib Reference Manual

XRaiseWindow

•Xlib - Window Manipulation —

Name

XRaiseWindow — raise a window to the top of the stacking order.

Synopsis

XRaiseWindow (display, v/) Display *display; Window w;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window to be raised to the top of the stack.

Description

XRaiseWindow moves a window to the top of the stacking order among its siblings. If the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack, while leaving its x and y location on the desk constant.

Raising a mapped window may generate exposure events for that window and any mapped subwindows of that window that were formerly obscured.

If the override_redirect attribute of the window (see Volume One, Chapter 4, Window Attributes) is False and the window manager has selected SubstructureRedirectMask on the parent, then a Conf igureRequest event is sent to the window manager, and no fur ther processing is performed.

Errors

BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown,XCirculate-SubwindowsUp, XConfigureWindow, XLowerWindow, XMoveResizeWindow, XMoveWindow,XQueryTree,XReparentWindow,XResizeWindow, XRestack-Windows.

—Xlib - Pixmaps and Tiles-

j XReadBitmapFlle

Name

XReadBitmapFile — read a bitmap from disk.

Synopsis

int XReadBitmapFile(display, drawable, filename, width,

height, bitmap, x_hot, y_hot) Display * display; Drawable drawable; char * filename;

unsigned int * width, * height; /* RETURN */ Pixmap * bitmap; /* RETURN */

int *x_hot, *y_hot; /* RETURN */

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

dra wabl e Specifies the drawable.

filename Specifies the filename to use. The format of the filename is operating system specific.

width Return the dimensions in pixels of the bitmap that is read.

height

bi tmap Returns the pixmap resource ID that is created.

x_hot Return the hotspot coordinates in the file (or -1,-1 if none present).

y_hot

Description

XReadBitmapFile reads in a file containing a description of a pixmap of depth 1 (a bitmap) in X Version 11 bitmap format.

XReadBitmapFile creates a pixmap of the appropriate size and reads the bitmap data from the file into the pixmap. The caller should free the pixmap using XFreePixmap when fin ished with it.

If the file cannot be opened, XReadBitmapFile returns BitmapOpenFailed. If the file can be opened but does not contain valid bitmap data, XReadBitmapFile returns Bitmap-Filelnvalid. If insufficient working storage is allocated, XReadBitmapFile returns BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns Bitmap-Success.

XReadBitmapFile (continued) Xlib - Pixmaps and Tiles

Here is an example X Version 11 bitmap file:

tdefine name_width 16

#define name_height 16

#define name_x_hot 8

#define name y hot 8

static char name_bits[] = {

Oxf8, Oxlf, Oxe3, Oxc7, Oxcf, Oxf3, Ox9f, Oxf9, Oxbf, Oxfd, 0x33, Oxcc,

Ox7f, Oxfe, Ox7f, Oxfe, Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd,

Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf};

For more information, see Volume One, Chapter 6, Drawing Graphics and Text. Errors

BadDrawable

Related Commands

XCreateBitmapFromData,XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile,XSet-Tile,XSetWindowBackgroundPixmap,XSetWindowBorderPixmap, XWrite-BitmapFile.

—Xlib-Keyboard-

J XRebindKeysym

Name

XRebindKeysym — rebind a keysym to a string for client.

Synopsis

XRebindKeysym (display, keysym, mod_list, mod_count, string,

num_bytes) Display * display; KeySym keysym; KeySym *mod_list ; int mod_count; unsigned char *string; int num_bytes;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

keysym Specifies the keysym to be rebound.

mod_list Specifies a pointer to an array of keysyms that are being used as modifiers.

mod_count Specifies the number of modifiers in the modifier list.

string Specifies a pointer to the string that is to be copied and returned by

XLookupString in response to later events.

num_bytes Specifies the length of the string. Description

XRebindKeysym binds the ASCII string to the specified keysym, so that string and keysym are returned by XLookukpSt ring when that key is pressed and the modifiers speci fied in mod_list are also being held down. This function rebinds the meaning of a keysym for a client. It does not redefine the keycode in the server but merely provides an easy way for long strings to be attached to keys. Note that you are allowed to rebind a keysym that may not exist.

See Volume One, Chapter 9, The Keyboard and Pointer, for a description of keysyms and key board mapping.

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString,XNewModifierMap,XQueryKeymap, XRefreshKeyboard-Mapping,XSetModifierMapping,XStringToKeysym.

XRecolorCursor \ xHb-cu«.r.-

Name

XRecolorCursor — change the color of a cursor.

Synopsis

XRecolorCursor( display, cursor, foreground_color r

background_color) Display * display; Cursor cursor; XColor *foreground_color f *background_color;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

cursor Specifies the cursor ID.

foreground_color

Specifies the red, green, and blue (RGB) values for the foreground.

background_color

Specifies the red, green, and blue (RGB) values for the background.

Description

XRecolorCursor applies a foreground and background color to a cursor. Cursors are nor mally created using a single plane pixmap, composed of O's and 1's, with one pixel value assigned to 1's and another assigned to O's. XRecolorCursor changes these pixel values. If the cursor is being displayed on a screen, the change is visible immediately. On some servers, these color selections are read/write cells from the colormap, and can't be shared by applica tions.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

char flags; /* DoRed, DoGreen, DoBlue */

char pad; } XColor;

Errors

BadCursor

Related Commands

XCreateFontCursor,XCreateGlyphCursor,XCreatePixmapCursor,XDefine-Cursor,XFreeCursor,XQueryBestCursor,XQueryBestSize, XUndefine-Cursor.

-X,.b-W.ndowManager Hints / XReCOHfigureWMWindOW

Name

XReconfigureWMWindow — request that a top-level window be reconfigured.

Synopsis

Status XReconfigureWMWindow( display, w, screen_number,

value_mask, values) Display *display; Window w;

int screen_number; unsigned int value_mask; XWindowChanges * values;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window.

screen_number

Specifies the appropriate screen number on the host server.

value_mask Specifies which values are to be set using information in the values structure. This mask is the bitwise inclusive OR of the valid configure window values bits.

values Specifies a pointer to the XWindowChanges structure.

Availability

Release 4 and later.

Description

XReconfigureWMWindow issues a Configurewindow request on the specified top-level window. If the stacking mode is changed and the request fails with a BadMatch error, the error event is trapped and a synthetic Conf igureRequest event containing the same confi guration parameters is sent to the root of the specified window. Window managers may elect to receive this event and treat it as a request to reconfigure the indicated window.

For more information, see Volume One, Chapter 10, Interclient Communication. Structures

typedef struct { int x, y;

int width, height; int border_width; Window sibling; int stack_mode; } XWindowChanges;

XReCOPf igureWMWindOW (continued) Xlib - Window Manager Hints

Errors

BadValue BadWindow

Related Commands

XlconifyWindow,XWithdrawWindow.

— Xlib -Regions-

J XRectlnRegion

Name

XRectlnRegion — determine if a rectangle resides in a region.

Synopsis

int XRectlnRegion (r, x, y, width, height) Region r; int x r y; unsigned int width, height;

Arguments

r Specifies the region.

x Specify the x and y coordinates of the upper-left corner of the rectangle, rela-

y live to the region's origin.

width Specify the width and height in pixels of the rectangle.

height

Description

XRectlnRegion returns Rectangleln if the rectangle is completely contained in the region r, RectangleOut if it is completely outside, and RectanglePart if it is partially inside.

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. If the region is to be used as a clip_mask by calling xsetRegion, the upper-left corner of region relative to the drawable used in the graphics request will be at (xoffset + clip_x_origin, yof f set + clip_y_origin), where xoffset and yof f set are the offset of the region and clip_x_origin and clip_y_origin are the clip origin in the GC used.

For this function, the x and y arguments are interpreted relative to the region origin; no draw-able is involved.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion,XDestroyRegion,XEmptyRegion,XEqualRegion, XIntersectRegion,XOffsetRegion,XPointlnRegion, XPolygonRegion, XSetRegion,XShrinkRegion,XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.

XRefreshKeyboardMapping \ X||b _ Keyboard _

Name

XRefreshKeyboardMapping — read keycode-keysym mapping from server into Xlib.

Synopsis

XRefreshKeyboardMapping( event) XMappingEvent *event;

Arguments

event Specifies the mapping event that triggered this call.

Description

XRefreshKeyboardMapping causes Xlib to update its knowledge of the mapping between keycodes and keysyms. This updates the application's knowledge of the keyboard.

The application should call XRefreshKeyboardMapping when a MappingNot if y event occurs. MappingNotify events occur when some client has called XChangeKeyboard-Mapping.

For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Structures

typedef struct {

int type;

unsigned long serial; /* # of last request processed by server */

Bool send_event; /* true if this came from a SendEvent request */

Display ^display; /* display the event was read from */

Window window; /* unused */

int request; /* one of MappingModifier, MappingKeyboard, MappingPointer */

int first_keycode; /* first keycode */

int count; /* defines range of change with first_keycode*/

} XMappingEvent;

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping,XGetModifierMapping, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString, XNewModifierMap,XQueryKeymap,XRebindKeysym, XSet-ModifierMapping, XStringToKeysym.

-xnb- save set ' XRemoveFromSaveSet

Name

XRemoveFromSaveSet — remove a window from the client's save-set.

Synopsis

XRemoveFromSaveSet(display, w) Display * display ; Window v/;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the window you want to remove from this client's save-set. This

window must have been created by a client other than the client making this call.

Description

XRemoveFromSaveSet removes a window from the save-set of the calling application.

The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a shadow or other background for each window. When the window manager dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so that they remain alive.

This call is not necessary when a window is destroyed since destroyed windows are automati cally removed from the save-set. Therefore, many window managers get away without ever calling XRemoveFromSaveSet. See Volume One, Chapter 14, Window Management, for more information about save-sets.

Errors

BadMatch wnot created by some other client.

BadWindow

Related Commands

XAddToSaveSet,XChangeSaveSet.

XRemoveHost , . XIib -Hos, Access-

Name

XRemoveHost — remove a host from the access control list.

Synopsis

XRemoveHost( display, host) Display ^display; XHostAddress *host ;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

host Specifies the network address of the machine to be removed.

Description

XRemoveHost removes the specified host from the access control list of the connected server. The server must be on the same host as the process that calls XRemoveHost in order to change the access control list.

If you remove your own machine from the access control list, you can no longer connect to that server, and there is no way back from this call other than to log out, edit the access control file, and reset the server.

The address data must be a valid address for the type of network in which the server oper ates, as specified in the family member.

For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte con tains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte.

For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.

Structures

typedef struct {

int family; /* for example Family Internet */

int length; /* length of address, in bytes */

char ^address; /* pointer to where to find the bytes */

} XHostAddress;

/* constants used for family member of XHostAddress */ #define Familylnternet 0 #define FamilyDECnet 1 #define FamilyChaos 2

Errors

BadAccess BadValue

Xlib - Host Access (continued) X Re move Host

Related Commands

XAddHost,XAddHosts,XDisableAccessControl,XEnableAccessControl, XListHosts,XRemoveHosts, XSetAccessControl.

XRemoveHosts A Vl

v Xlib - Host Access-Name

XRemoveHosts — remove multiple hosts from the access control list.

Synopsis

XRemoveHosts(display, hosts, num_hosts) Display * display; XHostAddress *hosts; int num_hosts;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

hosts Specifies the list of hosts that are to be removed.

n um_h osts Specifies the number of hosts that are to be removed.

Description

XRemoveHosts removes each specified host from the access control list of the connected server. The server must be on the same host as the process that call XRemoveHosts, in order to change the access control list.

If you remove your machine from the access control list, you can no longer connect to that server, and there is no way back from this call except to log out, edit the access control file, and reset the server.

The address data must be a valid address for the type of network in which the server oper ates, as specified in the family member.

For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.

Structures

typedef struct {

int family; /* for example Family Internet */

int length; /* length of address, in bytes */

char *address; /* pointer to where to find the bytes */

} XHostAddress;

/* constants used for family member of XHostAddress */

tdefine Familylnternet 0

#define FamilyDECnet 1

#define FamilyChaos 2

Xllb - Host Access (continued) XRemOveHoStS

Errors

BadAccess BadValue

Related Commands

XAddHost,XAddHosts, XDisableAccessControl,XEnableAccessConti XListHosts,XRemoveHost,XSetAccessControl.

Xlib Reference Manual

XReparentWindow , XMb . wlndowHanlpulatIon _

Name

XReparentWindow — insert a window between another window and its parent.

Synopsis

XReparentWindow(display, win, parent, x, y) Display * display ; Window win; Window parent; int x r y;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

win Specifies the ID of the window to be reparented.

pa ren t Specifies the window ID of the new parent window.

x Specify the coordinates of the window relative to the new parent.

y Description

XReparentWindow modifies the window hierarchy by placing window win as a child of window parent. This function is usually used by a window manager to put a decoration win dow behind each application window. In the case of the window manager, the new parent win dow must first be created as a child of the root window.

If win is mapped, an XUnmapWindow request is performed on it automatically, win is then removed from its current position in the hierarchy, and is inserted as a child of the specified parent, win is placed on top in the stacking order with respect to siblings.

A ReparentNotif y event is then generated. The override_redirect member of the structure returned by this event is set to either True or False . Window manager clients nor mally should ignore this event if this member is set to True.

Finally, if the window was originally mapped, an XMapWindow request is performed automati cally.

Descendants of win remain descendants of win; they are not reparented to the old parent of

win.

Normal exposure processing on formerly obscured windows is performed. The server might not generate exposure events for regions from the initial unmap that are immediately obscured by the final map. The request fails if the new parent is not on the same screen as the old parent, or if the new parent is the window itself or an inferior of the window.

Xlib - Window Manipulation (continued) XRepa rent Window

Errors

BadMatch parent not on same screen as old parent of win.

win has a ParentRelative background and parent is not the same depth as win.

parent is win or an inferior of win. BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown, XCirculate-SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaiseWindow, XResizeWindow,XRestack-Windows.

XResetScreenSaver \,

^ Xlib - Screen Saver—

Name

XResetScreenSaver — reset the screen saver.

Synopsis

XResetScreenSaver (display) Display * display ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

Description

XResetScreenSaver redisplays the screen if the screen saver was activated. This may result in exposure events to all visible windows if the server cannot save the screen contents. If the screen is already active, nothing happens.

For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.

Related Commands

XActivateScreenSaver,XForceScreenSaver,XGetScreenSaver, XSet-ScreenSaver.

—Xllb- Window Manipulation ' XReSJZeWmdOW

Name

XResizeWindow — change a window's size.

Synopsis

XResizeWindow( display, w, width, height) Display ^display; Window w; unsigned int width, height;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the ID of the window to be resized.

width Specify the new dimensions of the window in pixels.

height

Description

XResizeWindow changes the inside dimensions of the window. The border is resized to match but its border width is not changed. XResizeWindow does not raise the window, or change its origin. Changing the size of a mapped window may lose its contents and generate an Expose event, depending on the bit_gravity attribute (see Volume One, Chapter 4, Win dow Attributes). If a mapped window is made smaller, exposure events will be generated on windows that it formerly obscured.

If the override_redirect attribute of the window is False and the window manager has selected SubstructureRedirectMask on the parent, then a Conf igureRequest event is sent to the window manager, and no further processing is performed.

If the client has selected StructureNotifyMask on the window, then a Conf igure-Notif y event is generated after the move takes place, and the event will contain the final size of the window.

Errors

BadValue BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown,XCirculate-SubwindowsUp,XConfigureWindow, XLowerWindow, XMoveResizeWindow, XMoveWindow,XQueryTree,XRaiseWindow, XReparentWindow,XRestack-Windows.

XRestack Windows

•Xlib - Window Manipulation —

Name

XRestackWindows — change the stacking order of siblings.

Synopsis

XRestackWindows( display, windows, nwlndows) ; Display * display; Window windows[]; int nwlndows;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

windows Specifies an array containing the windows to be restacked. All the windows

must have a common parent.

nwlndows Specifies the number of windows in the windows array.

Description

XRestackWindows restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the windows array will be on top, and the other windows will be stacked underneath it in the order of the array. Note that you can exclude other siblings from the windows array so that the top window in the array will not move relative to these other siblings.

For each window in the window array that is not a child of the specified window, a BadMatch error will be generated. If the override_redirect attribute of the window is False and the window manager has selected SubstructureRedirectMask on the parent, then Conf igureRequest events are sent to the window manager for each window whose over-ride_redirect is not set, and no further processing is performed. Otherwise, the windows will be restacked in top to bottom order.

Errors

BadMatch BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate-SubwindowsUp,XConfigureWindow,XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaiseWindow, XReparentWindow,XResize-Window.

-x..b - wmdow Manager H.nts / XrmDestroyDatabase

Name

XrmDestroyDatabase — destroy a resource database.

Synopsis

void XrmDestroyDatabase(database) XrmDatabase database;

Arguments

da t abase Specifies the resource database.

Availability

Release 4 and later.

Description

XrmDestroyDatabase destroys a resource database and frees its allocated memory. The destroyed resource database should not be referenced again. If database is NULL, Xrm DestroyDatabase returns immediately.

For more information, see Volume One, Chapter 11, Managing User Preferences. Related Commands

XrmMergeDatabases.

XrmGetFileDatabase y

N Xlib - Resource Manager—

Name

XrmGetFileDatabase — retrieve a database from a file.

Synopsis

XrmDatabase XrmGetFileDatabase (filename) char *filename;

Arguments

filename Specifies the resource database filename.

Description

XrmGetFileDatabase opens the specified file, creates a new resource database, and loads the database with the data read in from the file. The return value of the function is as a pointer to the created database.

The specified file must contain lines in the format accepted by XrmPutLineResource. If XrmGetFileDatabase cannot open the specified file, it returns NULL.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase,XrmGetResource, XrmGetStringDatabase, Xrm-Initialize,XrmMergeDatabases,XrmParseCommand,XrmPutFileDatabase, XrmPutLineResource,XrmPutResource, XrmPutStringResource, XrmQGet-Resource,XrmQGetSearchList,XrmQGetSearchResource,XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List, XrmStringToQuarkList,XrmStringToQuark, XrmUniqueQuark.

-X,ib - Resource Manager /

Name

XrmGetResource — get a resource from name and class as strings.

Synopsis

Bool XrmGetResource( database, str_name, str_class,

str_type, value) XrmDatabase database; char *str_name; char *str_class;

char **str__type; /* RETURN */ XrmValue * value; /* RETURN */

Arguments

database Specifies the database that is to be used.

st r_name Specifies the fully specified name of the value being retrieved. str_class Specifies the fully specified class of the value being retrieved.

str_type Returns a pointer to the representation type of the destination. In this func tion, the representation type is represented as a string, not as an Xrm-

Representation.

val ue Returns the value in the database. Do not modify or free this data.

Description

The resource manager manages databases of resource specifications consisting of lines contain ing resource name/class strings followed by a colon and the value of the resource. XrmGet Resource retrieves a resource from the specified database. It takes fully specified name and class strings, and returns the representation and value of the matching resource. The value returned points into database memory; you must not modify that data. If a resource was found, XrmGetResource returns True. Otherwise, it returns False.

Currently, the database only frees or overwrites entries when new data is stored with Xrm-MergeDatabases, or XrmPutResource and related routines. A client that avoids these functions should be safe using the address passed back at any time until it exits.

XrmGetResource is very similar to XrmQGetResource, except that in XrmQGet-Resource, the equivalent arguments to str_name, str_class, and str_type are quarks instead of strings.

To understand how data is stored and retrieved from the database, you must understand:

1) The basic components that make up the storage key and retrieval keys.

2) How keys are made up from components.

3) The two ways that components can be bound together.

4) What sort of keys are used to store and retrieve data.

XrmGetResource (continued) Xlib - Resource Manager

5) How the storage key and retrieval keys are compared to determine whether they match.

6) If there are multiple matches, how the best match is chosen so only one value is returned. Each will be covered in turn.

1) The storage key and retrieval keys are composed of a variable number of components, bound together. There are two types of components: names and classes. By convention, names begin with a lower case character and classes begin with an upper case character. Therefore, xmh, background, and toe are examples of names, while Xmh, Box, and Command are examples of classes. A name key (like str_name) consists purely of name components. A class key (like str_class ) consists purely of class components. The retrieval keys are a pair of keys, one composed of purely name components, the other of purely class components. A storage key (like specifier in XrmPut-Resource) consists of a mixture of name and class components.

2) A key is composed of multiple components bound together in sequence. This allows you to build logical keys for your application. For example, at the top level, the application might consist of a paned window (that is, a window divided into several sections) named toe. One pane of the paned window is a button box window named buttons filled with command buttons. One of these command buttons is used to retrieve (include) new mail and has the name include. This window has a fully qualified name xmh. toe. but tons, include and a fully qualified class Xmh.VPaned. BOX. Command. Its fully quali fied name is the name of its parent, xmh. toe .buttons, followed by its name include. Its class is the class of its parent, Xmh.VPaned. BOX, followed by its particular class,

Command.

3) The components in a key can be bound together in two ways: by a tight binding (a dot ".") or by a loose binding (an asterisk "*"). Thus xmh.toe.background has three name components tightly bound together, while Xmh*Command. foreground uses both a loose and a tight binding. Bindings can also precede the first component (but may not follow the last component). By convention, if no binding is specified before the first component, a tight binding is assumed. For example, xmh.background and .xmh.background both begin with tight bindings before the xmh, while *xmh. background begins with a loose binding.

The difference between tight and loose bindings comes when comparing two keys. A tight binding means that the components on either side of the binding must be sequential. A loose binding is a sort of wildcard, meaning that there may be unspecified components between the two components that are loosely bound together. For example,

xmh.toe.background would match xmh*background and Background but not xmh. background or background.

4) A key used to store data into the database can use both loose and tight bindings. This allows you to specify a data value which can match to many different retrieval keys. In contrast, keys used to retrieve data from the database can use only tight bindings. You can only look up one item in the database at a time. Remember also that a storage key

Xlib - Resource Manager (continued) XrmGetResOUrce

can mix name and class components, while the retrieval keys are a pair of keys, one con sisting purely of name (first character lower case) components and one consisting purely of class (capitalized) components.

5) The resource manager must solve the problem of how to compare the pair of retrieval keys to a single storage key. (Actually, to many single storage keys, since the resource manager will compare the retrieval keys against every key in the database, but one at a time.) The solution of comparing a pair of keys to a single key is simple. The resource manager compares component by component, comparing a component from the storage key against both the corresponding component from the name retrieval key, and the cor responding component from the class retrieval key. If the storage key component matches either retrieval key component, then that component is considered to match. For example, the storage key xmh.toe.Foreground matches the name key xmh .toe . foreground with the class key Xmh. Box. Foreground. This is why storage keys can mix name and class components, while retrieval keys cannot.

6) Because the resource manager allows loose bindings (wildcards) and mixing names and classes in the storage key, it is possible for many storage keys to match a single name/class retrieval key pair. To solve this problem, the resource manager uses the fol lowing precedence rules to determine which is the best match (and only the value from that match will be returned). The precedence rules are, in order of preference:

1. The attribute of the name and class must match. For example, queries for

xterm. scrollbar.background (name) XTerm. Scrollbar. Background (class)

will not match the following database entry:

xterm.scrollbar: on

because background does not appear in the database entry.

2. Database entries with name or class prefixed by a dot (.) are more specific than those prefixed by an asterisk (*). For example, the entry xterm. geometry is more specific than the entry xterm*geometry.

3. Names are more specific than classes. For example, the entry *scrollbar.-background is more specific than the entry * Scrollbar. Background.

4. A name or class is more specific than omission. For example, the entry Scrollbar*Background is more specific than the entry *Background.

5. Left components are more specific than right components. For example, to query for .xterm. scrollbar .background, the entry xterm*background is more spe cific than the entry scrollbar*background.

Xlib Reference Manual

XrmGetResource (continued) Xlib - Resource Manager

Names and classes can be mixed. As an example of these rules, assume the following user pref erence specification:

xmh*background: red

*command.font: 8x13

*command.background: blue

*Command.Foreground: green

xmh.toc*Command.activeForeground: black

A query for the name xmh. toe .messagefunctions . include .activeForeground and class Xmh.VPaned. Box. Command. Foreground would match xmh.toc*-Command.activeForeground and return black. However, it also matches *Com-mand. Foreground but with lower preference, so it would not return green.

For more information, see Volume One, Chapter 11, Managing User Preferences, and Volume Four, X Toolkit Intrinsics Programming Manual, Chapter 9, Resource Management and Type Conversion.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef struct {

unsigned int size;

caddr_t addr; } XrmValue;

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase, XrmGetStringDatabase, Xrm-Initialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource,XrmPutResource,XrmPutStringResource,XrmQGet-Resource,XrmQGetSearchList,XrmQGetSearchResource,XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuark-List,XrmStringToQuarkList,XrmStringToQuark, XrmUniqueQuark.

-xi,b - Resource Manager / XrmGetStringDatabase

Name

XrmGetStringDatabase — create a database from a string.

Synopsis

XrmDatabase XrmGetStringDatabase(data) char *data;

Arguments

data Specifies the database contents using a string.

Description

XrmGetStringDatabase creates a new database and stores in it the resources specified in data. The return value is subsequently used to refer to the created database. XrmGet StringDatabase is similar to XrmGetFileDatabase, except that it reads the informa tion out of a string instead of a file. Each line in the string is separated by a new line character in the format accepted by XrmPutLineResource.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, Xrm-Initialize,XrmMergeDatabases,XrmParseCommand,XrmPutFileDatabase, XrmPutLineResource,XrmPutResource, XrmPutStringResource,XrmQGet-Resource,XrmQGetSearchList,XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List,XrmStringToQuarkList,XrmStringToQuark,XrmUniqueQuark.

Xrmlnitialize

Xlib - Resource Manager—

Name

Xrmlnitialize — initialize the resource manager.

Synopsis

void Xrmlnitialize( ) ;

Description

Xrmlnitialize initializes the resource manager, and should be called once before using any other resource manager functions. It just creates a representation type of "String" for val ues defined as strings. This representation type is used by XrmPutStringResource and XrmQPutStringResource, which require a value as a string. See XrmQPutResource for a description of representation types.

For more information, see Volume One, Chapter 11, Managing User Preferences. Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource, XrmGet-StringDatabase,XrmMergeDatabases,XrmParseCommand,XrmPutFile-Database, XrmPutLineResource,XrmPutResource, XrmPutStringResource, XrmQGetResource,XrmQGetSearchList,XrmQGetSearchResource, XrmQPut Resource, XrmQPutStringResource,XrmQuarkToString,XrmString-ToBindingQuarkList,XrmStringToQuarkList,XrmStringToQuark,Xrm-UniqueQuark.

Xlib Reference Manual

—Xlib - Resource Manager-

J XrmMergeDatabases

Name

XrmMergeDatabases — merge the contents of one database into another.

Synopsis

void XrmMergeDatabases( source_db, target_db) XrmDatabase source_db, *target_db;

Arguments

source_db Specifies the resource database to be merged into the existing database.

target_db Specifies a pointer to the resource database into which the source_db data base will be merged.

Description

XrmMergeDatabases merges source_db into target_db. This procedure is used to combine databases, for example, an application specific database of defaults and a database of user preferences. The merge is destructive; it destroys the original source_db database and modifies the original target_db.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmParseCommand,XrmPutFileDatabase, XrmPutLineResource,XrmPutResource,XrmPutStringResource,XrmQGet-Resource,XrmQGetSearchList,XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List, XrmStringToQuarkList,XrmStringToQuark, XrmUniqueQuark.

Xlib Reference Manual 387

XrmParseCommand \.

v Xlib - Resource Manager-Name

XrmParseCommand — load a resource database from command line arguments.

Synopsis

void XrmParseCommand( db, table, table_count, name, argc,

argv)

XrmDatabase *db; /* SEND and if NULL, RETURN */

XrmOptionDescList table; int table_count / char *name;

int *argc; /* SEND and RETURN */

char **argv; /* SEND and RETURN */

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

t abl e Specifies table of command line arguments to be parsed.

table_count Specifies the number of entries in the table. name Specifies the application name.

argc Before the call, specifies the number of arguments. After the call, returns the

number of arguments not parsed.

argv Before the call, specifies a pointer to the command line arguments. After the

call, returns a pointer to a string containing the command line arguments that could not be parsed.

Description

XrmParseCommand parses an (argc, argv) pair according to the specified option table, loads recognized options into the specified database, and modifies the (argc, argv) pair to remove all recognized options.

The specified table is used to parse the command line. Recognized entries in the table are removed from argv, and entries are made in the specified resource database. The table entries contain information on the option string, the option name, which style of option and a value to provide if the option kind is XrmoptionNoArg. See the example table below.

argc specifies the number of arguments in argv and is set to the remaining number of argu ments that were not parsed, name should be the name of your application for use in building the database entry, name is prepended to the resourceName in the option table before stor ing the specification. No separating (binding) character is inserted. The table must contain either a dot (".") or an asterisk ("*") as the first character in each resourceName entry. The resourceName entry can contain multiple components.

The following is a typical options table:

static XrmOptionDescRec opTable[ ] = {

{"-background", "*background", XrmoptionSepArg, (caddr_t) NULL},

Xlib - Resource Manager

(continued)

XrmParseCommand

{"-bg",

{"-borderwidth 1

{"-bordercolor 1

{"-bw",

{"-display",

{"-fg",

{"-fn",

{"-font",

{"-foreground",

{"-geometry",

{"-iconic",

{"-name",

{"-reverse",

-rv",

-synchronous'

-title",

-xrm",

"*borderColor",

"*background",

"*TopLevelShell.borderWidth",

"*borderColor",

"*TopLevelShell.borderWidth",

".display",

"^foreground",

"*font",

"*foreground",

".TopLevelShell.geometry",

".TopLevelShell.iconic",

".name",

"*reverseVideo",

11 . synchronous",

11 . TopLevelShell. title",

NULL,

In this table, if the -background (or -bg) option is used to set background colors, the stored resource specifier will match all resources of attribute background. If the -borderwidth option is used, the stored resource specifier applies only to border width attributes of class Top LevelShell (that is, outermost windows, including pop-up windows). If the -title option is used to set a window name, only the topmost application windows receive the resource.

When parsing the command line, any unique unambiguous abbreviation for an option name in the table is considered a match for the option. Note that upper case and lower case matter.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmoptionNoArg,

XrmoptionlsArg,

XrmoptionStickyArg,

XrmoptionSepArg,

XrmoptionResArg,

XrmoptionSkipArg,

XrmoptionSkipLine,

XrmoptionSkipNArgs

} XrmOptionKind;

typedef struct {

char *option; char *resourceName; XrmOptionKind argKind; caddr t value;

/* value is specified in OptionDescRec.value */

/* value is the option string itself */

/* value is chars immediately following option */

/* value is next argument in argv */

/* resource and value in next argument in argv */

/* ignore this option and next argument in argv */

/* ignore this option and the rest of argv */

/* new in R4: ignore this option, skip

number specified in next argument */

/* option specification string in argv */

/* binding & resource name (w/out application name)

/* which style of option it is */

/* value to provide if XrmoptionNoArg */

XrmOptionDescRec, *XrmOptionDescList;

Xlib Reference Manual

XrmParseCommand (continued) Xlib - Resource Manager

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase, XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmPutFile-Database, XrmPutLineResource,XrmPutResource, XrmPutStringResource, XrmQGetResource,XrmQGetSearchList, XrmQGetSearchResource,XrmQPut-Resource, XrmQPutStringResource,XrmQuarkToString, XrmString-ToBindingQuarkList,XrmStringToQuarkList, XrmStringToQuark, Xrm-UniqueQuark.

-XHb - Resource Manager / XrmPutFileDatabaSe

Name

XrmPutFileDatabase — store a resource database in a file.

Synopsis

void XrmPutFileDatabase( database, stored_db) XrmDatabase database; char *stored_db;

Arguments

database Specifies the resource database that is to be saved.

stored_db Specifies the filename for the stored database. Description

XrmPutFileDatabase stores a copy of the application's current database in the specified file. The file is an ASCII text file that contains lines in the format that is accepted by XrmPut-LineResource.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases, XrmParseCommand, XrmPutLineResource,XrmPutResource,XrmPutStringResource,XrmQGet-Resource, XrmQGetSearchList,XrmQGetSearchResource,XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List, XrmStringToQuarkList,XrmStringToQuark,XrmUniqueQuark.

XrmPutLineResource \,

v Xlib - Resource Manager—

Name

XrmPutLineResource — add a resource specification to a resource database.

Synopsis

void XrmPutLineResource(database, line)

XrmDatabase *database; /* SEND, and if NULL, RETURN */ char *line;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

line Specifies the resource name (possibly with multiple components) and value

pair as a single string, in the format resource: value.

Description

XrmPutLineResource adds a single resource entry to the specified database.

XrmPutLineResource is similar to XrmPutStringResource, except that instead of having separate string arguments for the resource and its value, XrmPutLineResource takes a single string argument (line) which consists of the resource name, a colon, then the value. Since the value is a string, it is stored into the database with representation type

String.

Any whitespace before or after the name or colon in the line argument is ignored. The value is terminated by a new-line or a NULL character. The value may contain embedded new-line characters represented by the "\" and "n" two character pair (not the single "\n" character), which are converted into a single linefeed character. In addition, the value may run over onto the next line, this is indicated by a "\" character at the end of each line to be continued.

Null-terminated strings without a new line are also permitted. XrmPutResource, Xrm-QPutResource, XrmPutStringResource, XrmQPutStringResource and Xrm PutLineResource all store data into a database. See XrmQPutResource for the most complete description of this process.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Xlib - Resource Manager (continued) XrmPutLineResOurce

Related Commands

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,XrmPutResource,XrmPutStringResource, XrmQGet-Resource, XrmQGetSearchList, XrmQGetSearchResource,XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List, XrmStringToQuarkList,XrmStringToQuark,XrmUniqueQuark.

XrmPutResource \

v Xhb - Resource Manager —

Name

XrmPutResource — store a resource specification into a resource database.

Synopsis

void XrmPutResource( database, specifier, type, value)

XrmDatabase * database; /* SEND, and if NULL, RETURN */ char * specifier; char *type; XrmValue * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

sped fier Specifies a complete or partial specification of the resource. type Specifies the type of the resource.

value Specifies the value of the resource.

Description

XrmPutResource is one of several functions which store data into a database.

XrmQPutResource first converts specifier into a binding list and a quark list by calling XrmStringToBindingQuarkList, and converts type into an XrmRepresentation by calling XrmStringToRepresentation. Finally, it puts the data into the database.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut-StringResource and XrmPutLineResource all store data into a database. See the description of XrmQPutResource for the most complete description of this process.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef struct {

unsigned int size;

caddr_t addr; } XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource, XrmPutStringResource, Xrm-QGetResource,XrmQGetSearchList,XrmQGetSearchResource,XrmQPut Resource, XrmQPutStringResource,XrmQuarkToString, XrmString ToBindingQuarkList, XrmStringToQuarkList,XrmStringToQuark,Xrm-UniqueQuark.

-X,,b- Resource Manager ' XrmPutStringResource

Name

XrmPutStringResource — add a resource specification with separate resource name and value.

Synopsis

void XrmPutStringResource(database, resource, ^alue)

XrmDatabase * database; /* SEND, and if NULL, RETURN */ char *resource; char * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

resource Specifies the resource, as a string.

val ue Specifies the value of the resource, as a string.

Description

XrmPutStringResource adds a resource specification with the specified resource and value to the specified database. The resource string may contain both names and classes, bound with either loose (*) or tight (.) bindings. See the description of XrmGetResource for more information about bindings.

The representation type used in the database is String.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut-StringResource and XrmPutLineResource all store data into a database. See Xrm QPutResource for the most complete description of this process.

For more information, see Volume One, Chapter II, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource,XrmPutResource,XrmQGet-Resource,XrmQGetSearchList,XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List, XrmStringToQuarkList, XrmStringToQuark,XrmUniqueQuark.

Xlib Reference Manual 395

XrmQGetResource

•Xllb - Resource Manager—

Name

XrmQGetResource — get a resource value using name and class as quarks.

Synopsis

Bool XrmQGetResource(database, quark_name, quark_class,

quark_type, value) XrmDatabase database; XrmNameList quark_name; XrmClassList quark_class;

XrmRepresentation *quark_type; /* RETURN */ XrmValue * value; /* RETURN */

Arguments

da t abase Specifies the database that is to be used.

quark_name Specifies the fully qualified name of the value being retrieved (as a list of quarks).

quark_class Specifies the fully qualified class of the value being retrieved (as a list of quarks).

quark_type Returns a pointer to the representation type of the value. In this function, the representation type is represented as a quark.

value Returns a pointer to the value in the database. Do not modify or free this

data.

Description

XrmQGetResource retrieves a resource from the specified database. It takes fully qualified name and class strings, and returns the representation and value of the matching resource. The value returned points into database memory; you must not modify that data. If a resource was found, XrmQGetResource returns True. Otherwise, it returns False.

XrmQGetResource is very similar to XrmGetResource, except that in XrmGet-Resource, the equivalent arguments to quark_name, quark_class, and quark_type arguments are strings instead of quarks.

See XrmGetResource for a full description of how data is looked up in the database. For more information, see Volume One, Chapter II, Managing User Preferences.

Xlib - Resource Manager (continued) XrmQGetResource

Structures

XrmDatabase is a pointer to an opaque data type.

typedef XrmQuarkList XrmNameList; typedef XrmQuarkList XrmClassList; typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr; } XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetSearchList, XrmQGetSearchResource,XrmQPut-Resource,XrmQPutStringResource,XrmQuarkToString,XrmString-ToBindingQuarkList,XrmStringToQuarkList,XrmStringToQuark,Xrm-UniqueQuark.

XrmQGetSearch List "\

> Xllb - Resource Manager—

Name

XrmQGetSearchList — return a list of database levels.

Synopsis

Bool XrmQGetSearchList( database, names, classes,

search_list, list_length) XrmDatabase database; XrmNameList names; XrmClassList classes;

XrmSearchList search_list; /* RETURN */ int list_length;

Arguments

database Specifies the database to be searched.

names Specifies a list of resource names.

classes Specifies a list of resource classes.

search_list Returns a search list for further use. The caller must allocate sufficient space for the list before calling XrmQGetSearchList.

list_length Specifies the number of entries (not the byte size) allocated for

search_list.

Description

XrmQGetSearchList is a tool for searching the database more efficiently. It is used in combination with XrmQGetSearchResource. Often, one searches the database for many similar resources which differ only in their final component (e.g., xmh.toc. foreground, xmh.toe.background, etc). Rather than looking for each resource in its entirety, Xrm-GetSearchList searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the search list. This search list is then used by XrmQGetSearchList, which searches for the last components one at a time. In this way, the common work of searching for similar resources is done only once, and the specific part of the search is done on the much shorter search list.

XrmQGetSearchList takes a list of names and classes and returns a list of database levels where a match might occur. The returned list is in best-to-worst order and uses the same algo rithm as XrmGetResource for determining precedence. If search_list was large enough for the search list, XrmQGetSearchList returns True. Otherwise, it returns False.

The size of the search list that must be allocated by the caller is dependent upon the number of levels and wildcards in the resource specifiers that are stored in the database. The worst case length is 3 n , where n is the number of name or class components in names or classes.

Only the common prefix of a resource name should be specified in the name and class list to XrmQGetSearchList. In the example above, the common prefix would be xmh.toc. However, note that XrmQGetSearchResource requires that name represent a single

Xlib - Resource Manager (continued) XrmQGetSearchList

component only. Therefore, the common prefix must be all but the last component of the name and class.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef XrmQuarkList XrmNameList; typedef XrmQuarkList XrmClassList; typedef XrmQuark XrmRepresentation;

XrmSearchList is a pointer to an opaque data type. Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResour.ee, XrmQGetResource, XrmQGetSearchResource, XrmQPut-Resource, XrmQPutStringResource,XrmQuarkToString,XrmString-ToBindingQuarkList,XrmStringToQuarkList,XrmStringToQuark,Xrm-UniqueQuark.

Name

XrmQGetSearchResource — search prepared list for a given resource.

Synopsis

Bool XrmQGetSearchResource( search_list, name, class,

type, value)

XrmSearchList search_list ; XrmName name ; XrmClass class;

XrmRepresentation *type; /* RETURN */ XrmValue * value; /* RETURN */

Arguments

search_list Specifies the search list returned by XrmQGetSearchList.

name Specifies the resource name.

class Specifies the resource class.

type Returns the data representation type.

value Returns the value from the database.

Description

XrmQGetSearchResource is a tool for searching the database more efficiently. It is used in combination with XrmQGetSearchList. Often, one searches the database for many simi lar resources which differ only in their final component (e.g., xmh. toe. foreground, xmh. toe .background, etc). Rather than looking for each resource in its entirety, Xrm QGetSearchList searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the search list. Xrm QGetSearchResource searches the search list for the resource that is fully identified by name and class. The search stops with the first match. XrmQGetSearchResource returns True if the resource was found; otherwise, it returns False.

A call to XrmQGetSearchList with a name and class list containing all but the last compo nent of a resource name followed by a call to XrmQGetSearchResource with the last com ponent name and class returns the same database entry as XrmQGet Re source or XrmQGet-Resource would with the fully qualified name and class.

For more information, see Volume One, Chapter 11, Managing User Preferences.

400 Xlib Reference Manual

Xllb - Resource Manager (continued) XrmQGetSearchResource

Structures

XrmDatabase is a pointer to an opaque data type.

typedef XrmQuark XrmName;

typedef XrmQuark XrmClass;

typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr; } XrmValue, *XrmValuePtr;

XrmSearchList is a pointer to an opaque data type.

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase, XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList,XrmQPutResource, XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuark-List,XrmStringToQuarkList,XrmStringToQuark,XrmUniqueQuark.

Name

XrmQPutResource — store a resource specification into a database using quarks.

Synopsis

void XrmQPutResource(database, bindings, quarks, type, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ XrmBindingList bindings; XrmQuarkList quarks; XrmRepresentation type; XrmValue * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

bindings Specifies a list of bindings for binding together the guards argument.

quarks Specifies the complete or partial name or class list of the resource to be stored,

type Specifies the type of the resource.

val ue Specifies the value of the resource.

Description

XrmQPutResource stores a resource specification into the database.

database can be a previously defined database, as returned by XrmGetStringDatabase, XrmGetFileDatabase, or from XrmMergeDatabases. If database is NULL, a new database is created and a pointer to it returned in database.

bindings and quarks together specify where the value should be stored in the database. See XrmStringToBindingQuarkList for a brief description of binding and quark lists. See XrmGetResource for a description of the resource manager naming conventions and lookup rules.

type is the representation type of value. This provides a way to distinguish between differ ent representations of the same information. Representation types are user defined character strings describing the way the data is represented. For example, a color may be specified by a color name ("red"), or be coded in a hexadecimal string ("#4f6c84") (if it is to be used as an argument to XParseColor.) The representation type would distinguish between these two. Representation types are created from simple character strings by using the macro Xrm-StringToRepresentation. The type XrmRepresentation is actually the same type as XrmQuark, since it is an ID for a string. The representation is stored along with the value in the database, and is returned when the database is accessed.

value returns the value of the resource, specified as an XrmValue.

XrmGetResource contains the complete description of how data is accessed from the data base, and so provides a good perspective on how it is stored.

402 Xlib Reference Manual

Xlib - Resource Manager (continued) XrmQPutResOUrce

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmBindTightly, XrmBindLoosely } XrmBinding, *XrmBindingList;

typedef int XrmQuark, *XrmQuarkList; typedef XrmQuarkList XrmNameList; typedef XrmQuark XrmRepresentation;

typedef struct {

unsigned int size;

caddr_t addr; } XrmValue, *XrmValuePtr;

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource, XrmPutResource, XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList,XrmQGetSearch-Resource,XrmQPutStringResource, XrmQuarkToString, XrmString-ToBindingQuarkList,XrmStringToQuarkList,XrmStringToQuark,Xrm-UniqueQuark.

XrmQPutStringResource \ Xllb _ Resource Manager _

Name

XrmQPutStringResource — add a resource specification to a database using a quark resource name and string value.

Synopsis

void XrmQPutStringResource( database, bindings, quarks, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ XrmBindingList bindings; XrmQuarkList quarks; char * value;

Arguments

database Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database.

bindings Specifies a list of bindings for binding together the guards argument. guards Specifies the complete or partial name or class list of the resource to be stored.

val ue Specifies the value of the resource as a string.

Description

XrmQPutStringResource stores a resource specification into the specified database.

XrmQPutStringResource is a cross between XrmQPutResource and XrmPut-StringResource. Like XrmQPutResource, it specifies the resource by guards and bindings, two lists that together make a name/class list with loose and tight bindings. Like XrmPutStringResource, it specifies the value to be stored as a string, that value is con verted into an XrmValue, and the default representation type String is used.

XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPut StringResource and XrmPutLineResource all store data into a database. See Xrm QPutResource for the most complete description of this process.

For more information, see Volume One, Chapter 11, Managing User Preferences.

Structures

XrmDatabase is a pointer to an opaque data type.

typedef enum {

XrmBindTightly, XrmBindLoosely } XrmBinding, *XrmBindingList;

typedef int XrmQuark, *XrmQuarkList;

Related Commands

Xlib - Resource Manager (continued) XrmQPutStringResource

Resource,XrmQPutResource, XrmQuarkToString, XrmStringToBinding-QuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.

XrmQuarkToString \ X||b _ Resource Managar _

Name

XrmQuarkToString — convert a quark to a string.

Synopsis

char *XrmQuarkToString( quark) XrmQuark quark;

Arguments

quark Specifies the quark for which the equivalent string is desired.

Description

XrmQuarkToString returns the string for which the specified quark is serving as a short hand symbol. The quark was earlier set to represent the string by XrmStringToQuark. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, XrmQuarkToString returns NULL.

Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are represented by integers, comparing quarks is trivial.

The three #def ine statements in the Structures section provide an extra level of abstraction. They define macros so that names, classes and representations can also be represented as quarks.

For more information, see Volume One, Chapter II, Managing User Preferences. Structures

typedef int XrmQuark;

/* macro definitions from <Xll/Xresource,h> */

#define XrmNameToString(name) XrmQuarkToString(name) #define XrmClassToString(class) XrmQuarkToString(class) #define XrmRepresentationToString(type) XrmQuarkToString(type)

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList, XrmQGetSearch-Resource,XrmQPutResource,XrmQPutStringResource,XrmString-ToBindingQuarkList,XrmStringToQuarkList,XrmStringToQuark, Xrm-UniqueQuark.

—Xlib - Resource Manager-

J XrmStringToBindingQuarkList

Name

XrmStringToBindingQuarkList — convert a key string to a binding list and a quark list. Synopsis

XrmStringToBindingQuarkList(string, bindings, quarks) char *string;

XrmBindingList bindings; /* RETURN */ XrmQuarkList quarks; /* RETURN */

Arguments

string Specifies the string for which the list of quarks and list of bindings are to be

generated. Must be NULL terminated.

bindings Returns the binding list. The caller must allocate sufficient space for the binding list before the call.

quark Returns the list of quarks. The caller must allocate sufficient space for the

quarks list before the call.

Description

XrmStringToBindingQuarkList converts a resource specification string into two lists— one of quarks and one of bindings. Component names in the list are separated by a dot (".") indicating a tight binding or an asterisk ("*") indicating a loose binding. If the string does not start with dot or asterisk, a dot (".") is assumed.

A tight binding means that the quarks on either side of the binding are consecutive in the key. A loose binding, on the other hand, is a wildcard that can match any number of unspecified components in between the two quarks separated by the binding. Tight and loose bindings are used in the match rules, which compare multicomponent strings to find matches and determine the best match. See XrmGet Re source for a full description of lookup rules.

For example, *a. b*c becomes:

quarks bindings

"a" XrmBindLoosely "b" XrmBindTightly "c" XrmBindLoosely

For more information, see Volume One, Chapter II, Managing User Preferences. Structures

typedef int XrmQuark, *XrmQuarkList; typedef enum (

XrmBindLoosely, XrmBindTightly ) XrmBinding, *XrmBindingList;

XrmStrlngToBlndingQuarkLiSt (continued) Xlib - Resource Manager

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList, XrmQGetSearch-Resource,XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToQuarkList,XrmStringToQuark,XrmUniqueQuark.

— Xlib - Resource Manager-

J XrmStringToQuark

Name

XrmStringToQuark — convert a string to a quark.

Synopsis

XrmQuark XrmStringToQuark (string) char *string;

Arguments

string Specifies the string for which a quark is to be allocated.

Description

XrmStringToQuark returns a quark that will represent the specified string. If a quark already exists for the string, that previously existing quark is returned. If no quark exists for the string, then a new quark is created, assigned to the string, and string is copied into the quark table. (Since string is copied, it may be freed. However, the copy of the string in the quark table must not be modified or freed.) XrmQuarkToString performs the inverse function.

Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are presently represented by integers, comparing quarks is trivial.

The three #def ine statements in the Structures section provide an extra level of abstraction. They define macros so that names, classes, and representations can also be represented as quarks.

For more information, see Volume One, Chapter 11, Managing User Preferences. Structures

typedef int XrmQuark;

/* macro definitions from <Xll/Xresource,h> */

tdefine XrmStringToName(string) XrmStringToQuark(string)

#define XrmStringToClass(string) XrmStringToQuark(string)

#define XrmStringToRepresentation(string) XrmStringToQuark(string)

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource, XrmGet-StringDatabase,Xrmlnitialize,XrmMergeDatabases,XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList,XrmQGetSearch-Resource, XrmQPutResource,XrmQPutStringResource,XrmQuarkToString, XrmStringToBindingQuarkList,XrmStringToQuarkList, XrmUniqueQuark.

Xlib Reference Manual 409

XrmStringToQuarkList \ XMb _ Resource Manager _

Name

XrmStringToQuarkList — convert a key string to a quark list.

Synopsis

void XrmStringToQuarkList( string, quarks) char *string; XrmQuarkList quarks; /* RETURN */

Arguments

string Specifies the string for which a list of quarks is to be generated. Must be null-

terminated. The components may be separated by the "." character (tight binding) or the "*" character (loose binding).

quarks Returns the list of quarks.

Description

XrmStringToQuarkList converts string (generally a fully qualified name/class string) to a list of quarks. Components of the string may be separated by a tight binding (the "." char acter) or a loose binding ("*"). Use XrmStringToBindingQuarkList for lists which contain both tight and loose bindings. See XrmGetResource for a description of tight and loose binding.

Each component of the string is individually converted into a quark. See XrmString-ToQuark for information about quarks and converting strings to quarks, quarks is a null-terminated list of quarks.

For example, xmh. toe . command. background is converted into a list of four quarks: the quarks for xmh, toe, command, and background, in that order. A NULLQUARK is appended to the end of the list.

Note that XrmStringToNameList and XrmStringToClassList are macros that per form exactly the same function as XrmStringToQuarkList. These may be used in cases where they clarify the code.

For more information, see Volume One, Chapter 11, Managing User Preferences. Structures

typedef int XrmQuark *XrmQuarkList;

#define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) tdefine XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))

Xlib - Resource Manager (continued) XrmStringToQuarkList

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGetStringDatabase, Xrmlnitialize,XrmMergeDatabases,XrmParseCommand,XrmPutFileDatabase,Xrm-PutLineResource,XrmPutResource,XrmPutStringResource,XrmQGetResource,Xrm-QGetSearchList,XrmQGetSearchResource,XrmQPutResource,XrmQPutString-Resource, XrmQuarkToString,XrmStringToBindingQuarkList,XrmStringToQuark, XrmStringToRepresentation.XrmUniqueQuark.

XrmUniqueQuark v.

v Xlib - Resource Manager-Name

XrmUniqueQuark — allocate a new quark.

Synopsis

XrmQuark XrmUniqueQuark( )

Description

XrmUniqueQuark allocates a quark that is guaranteed not to represent any existing string. For most applications, XrmStringToQuark is more useful, as it binds a quark to a string. However, on some occasions, you may want to allocate a quark that has no string equivalent.

The shorthand name for a string is called a quark and is the type XrmQuark. Quarks are used to improve performance of the resource manager, which must make many string comparisons. Quarks are presently represented as integers. Simple comparisons of quarks can be performed rather than lengthy string comparisons.

A quark is to a string what an atom is to a property name in the server, but its use is entirely local to your application.

For more information, see Volume One, Chapter 11, Managing User Preferences. Structures

typedef int XrmQuark;

Related Commands

XrmDestroyDatabase,XrmGetFileDatabase,XrmGetResource,XrmGet-StringDatabase,Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase,XrmPutLineResource,XrmPutResource,XrmPut-StringResource,XrmQGetResource,XrmQGetSearchList,XrmQGetSearch-Resource,XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList,XrmStringToQuarkList, XrmStringTo Quark.

D „ J XRotateBuffers

—Xlib - Cut Buffers '

Name

XRotateBuffers — rotate the cut buffers.

Synopsis

XRotateBuffers(display, rotate) Display * display; int rotate;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

rotate Specifies how many positions to rotate the cut buffers.

Description

XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. The contents

of buffer 0 moves to buffer rotate, contents of buffer 1 moves to buffer (rotate+1) mod 8,

contents of buffer 2 moves to buffer (rotate+2) mod 8, and so on.

This routine will not work if any of the buffers have not been stored into with xstoreBuf f er

orXStoreBytes.

This cut buffer numbering is global to the display.

See the description of cut buffers in Volume One, Chapter 13, Other Programming Techniques.

Related Commands

XFetchBuffer,XFetchBytes,XStoreBuffer,XStoreBytes.

XRotateWindowProperties

Xlib-Properties-

Name

XRotateWindowProperties — rotate properties in the properties array.

properties, num_jprop,

Synopsis

XRotateWindowProperties ( display,

npositions) Display * display; Window w;

Atom properties []; int num_prop; int npositions;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose properties are to be rearranged.

properties Specifies the list of properties to be rotated. num_prop Specifies the length of the properties array.

npositions Specifies the number of positions to rotate the property list. The sign controls the direction of rotation.

Description

XRotateWindowProperties rotates the contents of an array of properties on a window. If the property names in the properties array are viewed as if they were numbered starting from 0 and if there are num_prop property names in the list, then the value associated with property name / becomes the value associated with property name (/ + npositions) mod num_prop, for all / from 0 to num_prop - 1. Therefore, the sign of npositions controls the direction of rotation. The effect is to rotate the states by npositions places around the virtual ring of property names (right for positive npositions, left for negative nposi-tion).

If npositions mod num_j>rop is nonzero, a PropertyNotify event is generated for each property, in the order listed.

If a BadAtom, BadMatch, or Badwindow error is generated, no properties are changed.

Error

BadAtom

BadMatch Badwindow

Atom occurs more than once in list for the window. No property with that name for the window.

An atom appears more that once in the list or no property with that name is defined for the window.

414

Xlib Reference Manual

Xlib - Properties (continued) XRotateWindOWPrOpertieS

Related Commands

XChangeProperty,XDeleteProperty,XGetAtomName, XGetFontProperty, XGetWindowProperty,XInternAtom, XListProperties, XSetStandard-Properties.

XSaveContext \ Vll

N Xlib - Context Manager—

Name

XSaveContext — save a data value corresponding to a window and context type (not graphics context).

Synopsis

int XSaveContext( display, w, context, data) Display * display; Window w; XContext context; caddr_t data;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the ID of the window with which the data is associated.

context Specifies the context type to which the data corresponds.

data Specifies the data to be associated with the window and context.

Description

XSaveContext saves data to the context manager database, according to the specified win dow and context ID. The context manager is used for associating data with windows within an application. The client must have called XUniqueContext to get the context ID before calling this function. The meaning of the data is indicated by the context ID, but is completely up to the client.

If an entry with the specified window and context ID already exists, XSaveContext writes over it with the specified data.

The XSaveContext function returns XCNOMEM (a nonzero error code) if an error has occurred and zero (0) otherwise. For more information, see the description of the context manager in Volume One, Chapter 13, Other Programming Techniques.

Structures

typedef int XContext;

Related Commands

XDeleteContext,XFindContext,XUniqueContext.

-X,,b - ,npu, Hand,,ng

Name

XSelectlnput — select the event types to be sent to a window.

Synopsis

XSelectlnput (display, w, event_mask) Display * display ; Window w; long event_mask;

Arguments

display Specifies a connection to an X server; returned from xopenDisplay.

w Specifies the ID of the window interested in the events.

event_mask Specifies the event mask. This mask is the bitwise OR of one or more of the valid event mask bits (see below).

Description

XSelectlnput defines which input events the window is interested in. If a window is not interested in a device event (button, key, motion, or border crossing), it propagates up to the closest ancestor unless otherwise specified in the do_not_propagate_mask attribute.

The bits of the mask are defined in <Xll/X.h> :

ButtonPressMask NoEventMask

ButtonReleaseMask KeyPressMask

EnterWindowMask KeyReleaseMask

LeaveWindowMask ExposureMask

Point erMotionMask VisibilityChangeMask PointerMotionHintMask StructureNotifyMask

ButtonlMotionMask ResizeRedirectMask

Button2MotionMask SubstructureNotifyMask

ButtonSMotionMask SubstructureRedirectMask

Button4MotionMask FocusChangeMask

ButtonSMotionMask PropertyChangeMask

ButtonMotionMask ColormapChangeMask

KeymapStateMask OwnerGrabButtonMask

A call on XSelectlnput overrides any previous call on XSelectlnput for the same win dow from the same client but not for other clients. Multiple clients can select input on the same window; their event_mask window attributes are disjoint. When an event is generated it will be reported to all interested clients. However, only one client at a time can select for each of SubstructureRedirectMask, ResizeRedirectMask, and ButtonPress.

If a window has both ButtonPressMask and ButtonReleaseMask selected, then a ButtonPress event in that window will automatically grab the mouse until all buttons are released, with events sent to windows as described for XGrabPointer. This ensures that a

XSeleCtlnpUt (continued) Xlib - Input Handling

window will see the ButtonRelease event corresponding to the ButtonPress event, even though the mouse may have exited the window in the meantime.

If PointerMotionMask is selected, events will be sent independent of the state of the mouse buttons. If instead, one or more of ButtonlMotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, ButtonSMotionMask is selected, MotionNotif y events will be generated only when one or more of the specified buttons is depressed.

XCreateWindow and XChangeWindowAttributes can also set the event_mask attri bute.

For more information, see Volume One, Chapter 8, Events.

Errors

Badva lue Specified event mask invalid.

BadWindow

Related Commands

QLength,XAllowEvents,XChecklfEvent,XCheckMaskEvent, XCheckTyped-Event, XCheckTypedWindowEvent,XCheckWindowEvent, XEventsQueued, XGetlnputFocus,XGetMotionEvents,XlfEvent,XMaskEvent,XNextEvent, XPeekEvent,XPeeklfEvent,XPending, XPutBackEvent, XSendEvent, XSet-InputFocus,XSynchronize,XWindowEvent.

-xiib - input Handling / XSendEvent

Name

XSendEvent — send an event

Synopsis

Status XSendEvent(display, w, propagate, event_mask r event) Display *display; Window w; Bool propagate; long event_mask / XEvent *event;

Arguments

di spl ay Specifies a connection to an X server; returned from XQpenDi sp 1 ay.

w Specifies the ID of the window where you want to send the event Pass the

window resource ID, PointerWindow, or InputFocus.

propagate Specifies how the sent event should propagate depending on event_mask. See description below. May be True or False.

event_mask Specifies the event mask. See XSelectInput for a detailed list of the event masks.

event Specifies a pointer to the event to be sent.

Errors

BadValue Specified event is not a valid core or extension event type, or event mask is invalid.

BadWindow

Description

XSendEvent sends an event from one client to another (or conceivably to itself). This func tion is used for communication between clients using selections, for simulating user actions in demos, and for other purposes.

The specified event is sent to the window indicated by w regardless of active grabs.

If w is set to PointerWindow, the destination of the event will be the window that the pointer is in. If w is InputFocus is specified, then the destination is the focus window, regardless of pointer position.

If propagate is False, then the event is sent to every client selecting on the window speci fied by w any of the event types in event_mask. If propagate is True and no clients have been selected on w any of the event types in event_mask, then the event propagates like any other event.

The event code must be one of the core events, or one of the events defined by a loaded exten sion, so that the server can correctly byte swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the server. The send_event field in every event type, which if True indicates that the event was sent with XSendEvent.

Xlib Reference Manual 419

XSendEvent (continued) Xlib-Input Handling

This function is often used in selection processing. For example, the owner of a selection should use XSendEvent to send a Select ionNot if y event to a requestor when a selec tion has been converted and stored as a property. See Volume One, Chapter 10, Interclient Communication for more information.

The status returned by XSendEvent indicates whether or not the given XEvent structure was successfully converted into a wire event. This value is zero on failure, or nonzero on success. Along with changes in the extensions mechanism, this makes merging of two wire events into a single user-visible event possible.

Structures

See Appendix E, Event Reference, for the contents of each event structure.

Related Commands

QLength,XAllowEvents,XChecklfEvent,XCheckMaskEvent,XCheckTyped-Event, XCheckTypedWindowEvent,XCheckWindowEvent, XEventsQueued, XGetlnputFocus,XGetMotionEvents,XlfEvent,XMaskEvent, XNextEvent, XPeekEvent, XPeeklfEvent,XPending, XPutBackEvent,XSelectlnput,XSet-InputFocus,XSynchronize, XWindowEvent.

-x,ib - HO* Acce,, / XSetAccessControl

Name

XSetAccessControl — disable or enable access control.

Synopsis

XSetAccessControl(display, mode) Display * display ; int mode;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

mode Specifies whether you want to enable or disable the access control. Pass one

of these constants: EnableAccess orDisableAccess.

Description

XSetAccessControl specifies whether the server should check the host access list before allowing access to clients running on remote hosts. If the constant used is DisableAccess, clients from any host have access unchallenged.

This routine can only be called from a client running on the same host as the server.

For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.

Errors

BadAccess BadValue

Related Commands

XAddHost,XAddHosts, XDisableAccessControl, XEnableAccessControl, XListHosts,XRemoveHost,XRemoveHosts.

v Xlib - Error Handling-Name

XSetAfterFunction — set a function called after all Xlib functions.

Synopsis

int (*XSetAfterFunction(display, func))() Display * display; int (*func) () ;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

func Specifies the user-defined function to be called after each Xlib function. This

function is called with one argument, the display pointer.

Description

All Xlib functions that generate protocol requests can call what is known as an after function after completing their work (normally, they don't). XSetAfterFunction allows you to write a function to be called.

XSynchronize sets an after function to make sure that the input and request buffers are flushed after every Xlib routine.

For more information, see Volume One, Chapter 13, Other Programming Techniques. Related Commands

XDisplayName,XGetErrorDatabaseText,XGetErrorText,XSetError-Handler, XSetlOErrorHandler,XSynchronize.

422 Xlib Reference Manual

—Xlib - Graphics Context-

XSetArcMode

Name

XSetArcMode — set the arc mode in a graphics context.

Synopsis

XSetArcMode ( display, gc, arc_mode) Display * display; GC gc; int arc mode;

Arguments

display

arc mode

Specifies a connection to an X server; returned from XOpenDisplay. Specifies the graphics context.

Specifies the arc mode for the specified graphics context. Possible values are ArcChordorArcPieSli.ee.

Description

XSetArcMode sets the arc_mode component of a GC, which controls filling in the XFill-Arcs function. ArcChord specifies that the area between the arc and a line segment joining the endpoints of the arc is filled. ArcPieSlice specifies that the area filled is delimited by the arc and two line segments connecting the ends of the arc to the center point of the rectangle defining the arc.

ArcChord

ArcPieSlice

Xlib Reference Manual

XSetArcMode (continued) Xlib - Graphics Context

Errors

BadGC BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetBackground,XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetDashes,XSetFillRule,XSetFillStyle,XSetForeground, XSet-Function, XSetGraphicsExposures,XSetLineAttributes, XSetPlaneMask, XSetState,XSetStipple,XSetSubwindowMode, XSetTSOrigin.

—Xlib - Graphics Context-

J XSetBackground

Name

XSetBackground — set the background pixel value in a graphics context.

Synopsis

XSetBackground (display, gc, background) Display * display; GC gc; unsigned long background;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

background Specifies the background component of the GC.

Description

XSetBackground sets the background pixel value component of a GC. Note that this is different from the background of a window, which can be set with either XSetwindow-

Background or XSetWindowBackgroundPixmap.

The specified pixel value must be returned by BlackPixel, WhitePixel, or one of the rou tines that allocate colors.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode,XSetClipMask,XSetClipOrigin, XSetClipRectangles,XSet-Dashes,XSetFillRule,XSetFillStyle,XSetForeground,XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

Xlib Reference Manual 425

Name

XSetClassHint — set the XA_WM_CLASS property of a window.

Synopsis

XSetClassHint(display, w, class_hints) Display * display; Window w; XClassHint *class_hints;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window for which the class hint is to be set.

class_hints Specifies the XClassHint structure that is to be used.

Description

XSetClassHint sets the XA_WM_CLASS property for the specified window. The window manager may (or may not) read this property, and use it to get resource defaults that apply to the window manager's handling of this application.

The XClassHint structure set contains res_class, which is the name of the client such as "emacs", and res_name, which is 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 /)

For more information, see Volume One, Chapter 10, Interclient Communication.

Errors

BadAlloc BadWindow

Structures

typedef struct {

char *res_name;

char *res_class; } XClassHint;

Related Commands

XAllocClassHint,XFetchName,XGetClassHint,XGetIconName,XGetIcon-Sizes, XGetNormalHints,XGetSizeHints,XGetTransientForHint,XGet-WMHints,XGetZoomHints,XSetCommand, XSetIconName,XSetlconSizes, XSetNormalHints,XSetSizeHints,XSetTransientForHint,XSetWMHints, XSetZoomHints,XStoreName,XSetWMProperties.

426 Xlib Reference Manual

-XHb - Graphics Con«,x, ' XSetClipMask

Name

XSetClipMask — set clip_mask pixmap in a graphics context.

Synopsis

XSetClipMask (display , gc, clip_mask) Display *display; GC gc; Pixmap clip_mask;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

clip_jnas;c Specifies a pixmap of depth 1 to be used as the clip mask. Pass the constant None if no clipping is desired.

Description

XSetClipMask sets the clip_mask component of a GC to a pixmap. The clip_mask fil ters which pixels in the destination are drawn. If clip_mask is set to None, the pixels are always drawn, regardless of the clip origin. Use XSetClipRectangles to set clip_mask to a set of rectangles, or XSetRegion to set clip_mask to a region.

For more information, see Volume One, Chapter 5, The Graphics Context. Errors

BadGC

BadMatch

BadPixmap

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode,XSetBackground,XSetClipOrigin, XSetClipRectangles, XSetDashes,XSetFillRule,XSetFillStyle,XSetForeground,XSet-Function, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask, XSetState,XSetStipple,XSetSubwindowMode, XSetTSOrigin.

Name

XSetClipOrigin — set the clip origin in a graphics context.

Synopsis

XSetClipOrigin(display, gc, clip_x_origin, clip_y_origin) Display * display; GC gc; int clip_x_origin f cl ip_y_ origin;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

clip_x_origin Specify the coordinates of the clip origin (interpreted later relative to the clip_y_origin window drawn into with this GC).

Description

XSetClipOrigin sets the clip_x_origin and clip_y_origin components of a GC. The clip origin controls the position of the clip_mask in the GC, which filters which pixels are drawn in the destination of a drawing request using this GC.

For more information, see Volume One, Chapter 5, The Graphics Context. Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground,XSetClipMask, XSetClipRectangles,XSet-Dashes,XSetFillRule,XSetFillStyle, XSetForeground, XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask, XSetState, XSetStipple,XSetSubwindowMode, XSetTSOrigin.

428 Xlib Reference Manual

—Xlib - Graphics Context-

J XSetClipRectangles

Name

XSetClipRectangles — change clip_mask in a graphics context to a list of rectangles.

Synopsis

XSetClipRectangles(display, gc, clip_x_orlgin,

clip_y_origin, rectangles, nrects, ordering) Display *display; GC gc;

int clip_x_origin r clip_y_ origin; XRectangle rectangles[] ; int nrects; int ordering;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

clip_x_ origin Specify the x and y coordinates of the clip origin (interpreted later rela-clip_y_ origin live to the window drawn into with this GC).

rectangles Specifies an array of rectangles. These are the rectangles you want draw

ing clipped to.

nrects Specifies the number of rectangles.

ordering Specifies the ordering relations of the rectangles. Possible values are

Unsorted, YSorted, YXSorted, or YXBanded.

Description

XSetClipRectangles changes the clip_mask component in the specified GC to the specified list of rectangles and sets the clip origin to clip_x_origin and clip_y_ori-gin. The rectangle coordinates are interpreted relative to the clip origin. The output from drawing requests using that GC are henceforth clipped to remain contained within the rectan gles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This is the opposite of a clip_mask of None in XCreateGC, XChangeGC, or XSetClipMask.

If known by the client, ordering relations on the rectangles can be specified with the order ing argument This may provide faster operation by the server. If an incorrect ordering is specified, the X server may generate a BadMatch error, but it is not required to do so. If no error is generated, the graphics results are undefined. Unsorted means the rectangles are in arbitrary order. YSorted means that the rectangles are nondecreasing in their y origin. YXSorted additionally constrains YSorted order in that all rectangles with an equal y origin are nondecreasing in their x origin. YXBanded additionally constrains YXSorted by requir ing that, for every possible horizontal y scan line, all rectangles that include that scan line have identical y origins and y extents.

XSetClipRectangles (continued) Xlib - Graphics Context

To cancel the effect of this command, so that there is no clipping, pass None as the clip_mask in XChangeGC orXSetClipMask.

For more information, see Volume One, Chapter 5, The Graphics Context. Structures

typedef struct {

short x,y;

unsigned short width, height; } XRectangle;

Errors

BadAlloc

BadGC

BadMatch Incorrect ordering (error message server-dependent).

BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSet-Dashes,XSetFillRule,XSetFillStyle,XSetForeground,XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple, XSetSubwindowMode,XSetTSOrigin.

-XHb-C,ien, Connections / XSetCIOSeDOWnMOde

Name

XSetCloseDownMode — change the close down mode of a client.

Synopsis

XSetCloseDownMode (display, close_mode) Display * display; int close_mode;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

close_mode Specifies the client close down mode you want. Pass one of these constants:

DestroyAll, RetainPermanent, or RetainTemporary.

Description

XSetCloseDownMode defines what will happen to the client's resources at connection close. A connection between a client and the server starts in DestroyAll mode, and all resources associated with that connection will be freed when the client process dies. If the close down mode is RetainTemporary or RetainPermanent when the client dies, its resources live on until a call to XKillClient. The resource argument of XKillClient can be used to specify which client to kill, or it may be the constant AllTemporary, in which case XKill Client kills all resources of all clients that have terminated in RetainTemporary mode.

One use of RetainTemporary or RetainPermanent might be to allow an application to recover from a failure of the network connection to the display server. After restarting, the application would need to be able to identify its own resources and reclaim control of them.

Errors

BadValue

Related Commands

XKillClient.

Xlib Reference Manual

^-Window Manager Hints-

Name

XSetCommand — set the XA_WM_COMMAND atom (command line arguments).

Synopsis

XSetCommand (display, w, argv, argc) Display * display ; Window w; char **argv; int argc;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDi splay.

w Specifies the ID of the window whose atom is to be set.

argv Specifies a pointer to the command and arguments used to start the application.

argc Specifies the number of arguments.

Description

XSetCommand is superseded by XSetWMCommand in Release 4.

XSetCommand is used by the application to set the XA_WM_COMMAND property for the window manager with the command and its arguments used to invoke the application.

XSetCommand creates a zero-length property if argc is zero.

Use this command only if not calling XSetStandardProperties or XSet-WMProperties.

Errors

BadAlloc BadWindow

Related Commands

XFetchName, XGetClassHint,XGetlconName,XGetlconSizes, XGetNormal-Hints, XGetSizeHints,XGetTransientForHint,XGetWMHints, XGetZoom-Hints,XSetClassHint,XSetIconName,XSetIconSizes,XSetNormalHints, XSetSizeHints, XSetTransientForHint,XSetWMHints, XSetZoomHints, XStoreName.

—Xlib - Graphics Context-

XSetDashes

Name

XSetDashes — set a pattern of line dashes in a graphics context.

Synopsis

XSetDashes(display, gc, dash_offset, dash_list, n) Display * display; GC gc;

int dash_offset ; char dash_list[] ; int n;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.

gc Specifies the graphics context.

dash_offset Specifies the phase of the pattern for the dashed line style.

das£i_list Specifies the dash list for the dashed line style. An odd-length list is equiva lent to the same list concatenated with itself to produce an even-length list.

n Specifies the length of the dash list argument.

First pixel in line

Last pixel in line

dotted (3,1) dot_dashed (3,4,3,1) short_dashed (4,4) long_dashed (4,7) odd dashed (1,2,3)

1 2345678 910111213141516171819202122

Pixels

Xlib Reference Manual

XSetDasheS (continued) Xlib - Graphics Context

Description

XSetDashes sets the dashes component of a GC. The initial and alternating elements of the dash_list argument are the dashes, the others are the gaps. All of the elements must be nonzero, with lengths measured in pixels. The dash_offset argument defines the phase of the pattern, specifying how many pixels into the dash_list the pattern should actually begin in the line drawn by the request.

n specifies the length of dash_list. An odd value for n is interpreted as specifying the dash_list concatenated with itself to produce twice as long a list.

Ideally, a dash length is measured along the slope of the line, but server implementors are only required to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is suggested that the length be measured along the major axis of the line. The major axis is defined as the x axis for lines drawn at an angle of between -45 and +45 degrees or between 315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis.

See Volume One, Chapter 5, The Graphics Context, for further information.

Errors

BadAlloc

BadGC

BadValue No values in dash_list. Element in dash_list is 0.

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground,XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetFillRule,XSetFillStyle,XSetForeground,XSet-Function, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask, XSetState,XSetStipple,XSetSubwindowMode, XSetTSOrigin.

-x.ib - Error Hand.ing / XSetErrorHandler

Name

XSetErrorHandler — set a nonfatal error event handler.

Synopsis

In Release 3:

XSetErrorHandler (handler)

int (* handler) (Display *, XErrorEvent *) InRelease4: int (*XSetErrorHandler (handler) )()

int (* handler) (Display *, XErrorEvent *)

Arguments

handler The user-defined function to be called to handle error events. If a NULL

pointer, reinvoke the default handler, which prints a message and exits.

Description

The error handler function specified in handler will be called by Xlib whenever an XError event is received. These are nonfatal conditions, such as unexpected values for arguments, or a failure in server memory allocation. It is acceptable for this procedure to return, though the default handler simply prints a message and exits. However, the error handler should NOT per form any operations (directly or indirectly) on the server.

In Release 4, XSetErrorHandler returns a pointer to the previous error handler.

The function is called with two arguments, the display variable and a pointer to the XError Event structure. Here is a trivial example of a user-defined error handler:

int myhandler (display, myerr) Display *display; XErrorEvent *myerr; {

char msg[80];

XGetErrorText (display, myerr->error_code, msg, 80);

fprintf(stderr, "Error code %s\n", msg); }

This is how the example routine would be used in XSetErrorHandler. XSetErrorHandler(myhandler)/

Note that XSetErrorHandler is one of the few routines that does not require a display argument. The routine that calls the error handler gets the display variable from the XError Event structure.

The error handler is not called on BadName errors from OpenFont, LookupColor, and AllocNamedColor protocol requests, on BadFont errors from a QueryFont protocol request, or on BadAlloc or BadAccess errors. These errors are all indicated by Status return value of zero in the corresponding Xlib routines, which must be caught and handled by the application.

Use XlOErrorHandler to provide a handler for I/O errors such as network failures or server host crashes.

XSetErrorHandler (continued) Xlib - Error Handling

In the XErrorEvent structure shown below, the serial member is the number of requests (starting from 1) sent over the network connection since it was opened. It is the number that was the value of the request sequence number immediately after the failing call was made. The request_code member is a protocol representation of the name of the procedure that failed and is defined in <Xll/X.h>.

For more information, see Volume One, Chapter 3, Basic Window Program. Structures

typedef struct { int type

Display *display; /* display the event was read from */

XID resourceid; /* resource ID */

unsigned long serial; /* serial number of failed request */ unsigned char error_code;/* error code of failed request */ unsigned char request_code;/* major opcode of failed request */ unsigned char minor_code;/* minor opcode of failed request */

} XErrorEvent;

Related Commands

XDisplayName,XGetErrorDatabaseText,XGetErrorText, XSetAfter-Function, XSetlOErrorHandler,XSynchronize.

—Xlib - Graphics Context-

XSetFillRule

Name

XSetFillRule — set the fill rule in a graphics context.

Synopsis

XSetFillRule (display, gc, fill_rule) Display *display; GC gc; int fill_rule;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

gc Specifies the graphics context.

fill_rule Specifies the fill rule you want to set for the specified graphics context. Pos sible values are EvenOddRule orWindingRule.

Description

XSetFillRule sets the fill_rule component of a GC. The fill_rule member of the GC determines what pixels are drawn in XFillPolygon requests. Simply put, Winding-Rule fills overlapping areas of the polygon, while EvenOddRule does not fill areas that overlap an odd number of times. Technically, EvenOddRule means that the point is drawn if an arbitrary ray drawn from the point would cross the path determined by the request an odd number of times. WindingRule indicates that a point is drawn if a point crosses an unequal number of clockwise and counterclockwise path segments, as seen from the point.

Outline of polygon to fill

EvenOddRul<

WindingRule

Xlib Reference Manual

XSetFillRule (continued) Xlib - Graphics Context

A clockwise-directed path segment is one which crosses the ray from left to right as observed from the point. A counterclockwise segment is one which crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a seg ment

All calculations are performed on infinitely small points, so that if any point within a pixel is considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are con sidered inside only if the filled area is to the right, except that on horizontal boundaries, the pixel is considered inside only if the filled area is below the pixel.

See Volume One, Chapter 5, The Graphics Context, for more information.

Errors

BadGC BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground,XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillStyle, XSetForeground, XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple, XSetSubwindowMode,XSetTSOrigin.

—Xlib - Graphics Context-

XSetFillStyle

Name

XSetFillStyle — set the fill style in a graphics context.

Synopsis

XSetFillStyle (display, gc, fill_style) Display * display; GC gc; int fill_style;

Arguments

display

Specifies a connection to an X server; returned from xopenDisplay.

gc Specifies the graphics context.

fill_style Specifies the fill style for the specified graphics context. Possible values are

FillSolid, Fill-Tiled, FillStippled, or FillOpaque-Stippled.

GC foreground GC background Undrawn Pixels M

Tile

Stipple

FillSolid

FillTiled

FillStippled FillOpaqueStippled

Description

XSetFillStyle sets the fill_style component of a GC. The fill_style defines the contents of the source for line, text, and fill requests. FillSolid indicates that the pixels rep resented by set bits in the source are drawn in the foreground pixel value, and unset bits in the source are not drawn. FillTiled uses the tile specified in the GC to determine the pixel values for set bits in the source. FillOpaqueStippled specifies that bits set in the stipple are drawn in the foreground pixel value and unset bits are drawn in the back ground. FillStippled draws bits set in the source and set in the stipple in the fore ground color, and leaves unset bits alone.

Xlib Reference Manual

XSetFillStyle (continued) Xlib - Graphics Context

For more information, see Volume One, Chapter 5, The Graphics Context. Errors

BadGC BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground,XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetForeground, XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple,XSetSubwindowMode,XSetTSOrigin.

Xlib Reference Manual

Name

XSetFont — set the current font in a graphics context.

Synopsis

XSetFont (display, gc, font) Display * display; GC gc; Font font;

Arguments

di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.

gc Specifies the graphics context.

f on t Specifies the ID of the font to be used.

Description

XSetFont sets the font in the GC. Text drawing requests using this GC will use this font only if the font is loaded. Otherwise, the text will not be drawn.

For more information, see Volume One, Chapter 5, The Graphics Context. Errors

BadFont BadGC

Related Commands

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree-FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith-Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFontPath, XUnloadFont.

Xlib Reference Manual 441

XSetFontPath ~\

•Xlib-Fonts-

Name

XSetFontPath — set the font search path.

Synopsis

XSetFontPath( display, directories, ndirs) Display * display; char ** directories; int ndirs;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

directories Specifies the directory path used to look for the font. Setting the path to the empty list restores the default path defined for the X server.

ndi rs Specifies the number of directories in the path.

Description

XSetFontPath defines the directory search path for font lookup for all clients. Therefore the user should construct a new directory search path carefully by adding to the old directory search path obtained by XGetFontPath. Passing an invalid path can result in preventing the server from accessing any fonts. Also avoid restoring the default path, since some other client may have changed the path on purpose.

The interpretation of the strings is operating system dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system specific and are not intended to be used by client applications.

The meaning of errors from this request is system specific.

Errors

BadValue

Related Commands

XCreateFontCursor,XFreeFont,XFreeFontlnfo,XFreeFontNames,XFree-FontPath,XGetFontPath,XGetFontProperty,XListFonts,XListFontsWith-Info,XLoadFont,XLoadQueryFont,XQueryFont,XSetFont, XUnloadFont.

-x, lb -Graph,c,con,«, / XSetForeground

Name

XSetForeground — set the foreground pixel value in a graphics context.

Synopsis

XSetForeground(display, gc, foreground) Display * display ; GC gc; unsigned long foreground;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

foreground Specifies the foreground pixel value you want for the specified graphics con text

Description

XSetForeground sets the foreground component in a GC. This pixel value is used for set bits in the source according to the f ill_style. This pixel value must be returned by BlackPixel, whitePixel, or a routine that allocates colors.

See Volume One, Chapter 5, The Graphics Context, for more information on the GC.

Errors

BadGC

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode,XSetBackground,XSetClipMask, XSetClipOrigin, XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle, XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple, XSetSubwindowMode, XSetTSOrigin.

XSetFu notion

Xlib - Graphics Context—

Name

XSetFunction — set the bitwise logical operation in a graphics context.

Synopsis

XSetFunction(display, gc, function) Display *display; GC gc; int function;

Arguments

display

function

Specifies a connection to an X server; returned from XOpenDisplay. Specifies the graphics context.

Specifies the logical operation you want for the specified graphics context. See Description for the choices and their meanings.

Description

XSetFunction sets the logical operation applied between the source pixel values (generated by the drawing request) and existing destination pixel values (already in the window or pix-map) to generate the final destination pixel values in a drawing request (what is actually drawn to the window or pixmap). Of course, the plane_mask and clip_mask in the GC also affect this operation by preventing drawing to planes and pixels respectively. GXcopy, GXin-vert, and GXxor are the only logical operations that are commonly used.

See Volume One, Chapter 5, The Graphics Context, for more information about the logical function.

444

Xlib Reference Manual

Xlib - Graphics Context (continued) XSetFunctlon

Errors

BadGC BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle, XSetForeground, XSetGraphicsExposures,XSetLineAttributes,XSetPlaneMask,XSetState, XSetStipple,XSetSubwindowMode, XSetTSOrigin.

XSetGraphicsExposures \

•Xlib - Graphics Context-

Name

XSetGraphicsExposures — set the graphics_exposures component in a graphics context.

Synopsis

XSetGraphicsExposures( display, gc, graph!cs_exposures) Display *display; GC gc; Bool graphics_exposures;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

gc Specifies the graphics context.

graphics_exposures

Specifies whether you want GraphicsExpose and NoExpose events when calling XCopyArea and XCopyPlane with this graphics context.

Description

XSetGraphicsExposure sets the graphics_exposures member of a GC. If graphics_exposures is True, GraphicsExpose events will be generated when XCopyArea and XCopyPlane requests cannot be completely satisfied because a source region is obscured, and NoExpose events are generated when they can be completely satis fied. If graphics_exposures is False, these events are not generated.

These events are not selected in the normal way with XSelectInput. Setting the graphics_exposures member of the GC used in the CopyArea or CopyPlane request is the only way to select these events.

For more information, see Volume One, Chapter 5, The Graphics Context. Errors

BadGC BadValue

Related Commands

Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode,XSetBackground,XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle,XSetForeground, XSetFunction,XSetLineAttributes,XSetPlaneMask,XSetState,XSet-Stipple, XSetSubwindowMode,XSetTSOrigin.

-X,, b -W,ndowMana g erH,n,s ' XSetlCOnNaiTie

Name

XSetlconName — set the name to be displayed in a window's icon.

Synopsis

XSetlconName (display, w, icon_name) Display * display ; Window w; char *icon_name;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose icon name is being set.

i con_name Specifies the name to be displayed in the window's icon. The name should be a null-terminated string. This name is returned by any subsequent call to XGetlconName.

Description

XSetlconName is superseded by XSetWMlconName in Release 4.

XSetlconName sets the XA_WM_ICON_NAME property for a window. This is usually set by an application for the window manager. The name should be short, since it is to be displayed in association with an icon.

XSetStandardProperties (in Release 4) or XSetWMProperties (in Release 4) also set this property.

For more information, see Volume One, Chapter IQJnterclient Communication. Errors

BadAlloc BadWindow

Related Commands

XFetchName,XGetClassHint,XGetlconName,XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-Hints,XSetClassHint,XSetCorranand, XSetlconSizes,XSetNormalHints, XSetSizeHints, XSetTransientForHint,XSetWMHints, XSetZoomHints, XStoreName.

Name

XSetlconSizes — set the value of the XA_WM_ICON_SIZE property.

Synopsis

XSetlconSizes(display, w, size_list, count) Display * display ; Window ur;

XlconSize *size_list; int count;

Arguments

di splay Specifies a connection to an X server; returned from XOpenDisplay.

w Specifies the ID of the window whose icon size property is to be set. Nor

mally the root window.

si ze_l i s t Specifies a pointer to the size list.

count Specifies the number of items in the size list.

Description

XSetlconSizes is normally used by a window manager to set the range of preferred icon sizes in the XA_WM_ICON_SIZE property of the root window.

Applications can then read the property with XGetlconSizes. Structures

typedef struct {

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc; } XlconSize;

Errors

BadAlloc BadWindow

Related Commands

XAllocIconSize,XFetchName,XGetClassHint,XGetlconName,XGetlcon Sizes, XGetNormalHints,XGetSizeHints,XGetTransientForHint,XGet-WMHints,XGetZoomHints,XSetClassHint,XSetCommand, XSetlconName, XSetNormalHints,XSetSizeHints, XSetTransientForHint,XSetWMHints, XSetZoomHints, XStoreName.

448 XIib Reference Manual

J XSetlnputFocus

—Xlib - Input Handling '

Name

XSetlnputFocus — set the keyboard focus window.

Synopsis

XSetlnputFocus(display, focus, revert_to, time) Display *display; Window focus; int revert_to; Time time;

Arguments

display Specifies a connection to an X server; returned from XQpenDisplay.

focus Specifies the ID of the window you want to be the keyboard focus. Pass the

window ID, PointerRoot, or None.

revert_to Specifies which window the keyboard focus reverts to if the focus window becomes not viewable. Pass one of these constants: RevertToParent, RevertToPointerRoot, or RevertToNone. Must not be a window ID.

time Specifies the time when the focus change should take place. Pass either a

timestamp, expressed in milliseconds, or the constant CurrentTime. Also returns the time of the focus change when CurrentTime is specified.

Description

XSetlnputFocus changes the keyboard focus and the last-focus-change time. The function has no effect if time is earlier than the current last-focus-change time or later than the current X server time. Otherwise, the last-focus-change time is set to the specified time, with CurrentTime replaced by the current X server time.

XSetlnputFocus generates Focusln and FocusOut events if focus is different from the current focus.

XSetlnputFocus executes as follows, depending on what value you assign to the focus argument:

If you assign None, all keyboard events are discarded until you set a new focus window. In this case, revert_to is ignored.

If you assign a window ID, it becomes the main keyboard's focus window. If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally; otherwise, the event is reported to the focus window. The specified focus window must be viewable at the time of the request (else a BadMatch error). If the focus window later becomes not viewable, the focus window will change to the revert_to argument

• If you assign PointerRoot, the focus window is dynamically taken to be the root win dow of whatever screen the pointer is on at each keyboard event In this case, revert_to is ignored. This is the default keyboard focus setting.

If the focus window later becomes not viewable, XSetlnputFocus evaluates the revert_ to argument to determine the new focus window:

XSetlnpUtFOGUS (continued) Xlib - Input Handling

If you assign RevertToParent, the focus reverts to the parent (or the closest viewable ancestor) automatically with a new revert_to argument of RevertToName.

• If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that value automatically. Focus in and FocusOut events are generated when the focus reverts, but the last focus change time is not affected.

Errors

BadMatch focus window not viewable when XSetlnputFocus called.

BadValue BadWindow

Related Commands

QLength,XAllowEvents,XChecklfEvent,XCheckMaskEvent,XCheckTyped-Event,XCheckTypedWindowEvent,XCheckWindowEvent, XEventsQueued, XGetlnputFocus.XGetMotionEvents,XIfEvent, XMaskEvent,XNextEvent, XPeekEvent,XPeeklfEvent,XPending, XPutBackEvent,XSelectlnput, XSendEvent,XSynchroni ze,XWindowEvent.

f XSetlOErrorHandler

—Xlib - Error Handling '

Name

XSetErrorHandler — set a nonfatal error event handler.

Synopsis

In Release 3:

XSetlOErrorHandler (ha/idler)

int (* handler) (Display *, XErrorEvent *) In Release 4: int (*XSetIOErrorHandler(handler)) ()

int (* handler) (Display *, XErrorEvent *)

Arguments

handler Specifies user-defined fatal error handling routine. If NULL, reinvoke the

default fatal error handler.

Description

XSetlOErrorHandler specifies a user-defined error handling routine for fatal errors. This error handler will be called by Xlib if any sort of system call error occurs, such as the connec tion to the server being lost. The called routine should not return. If the I/O error handler does return, the client process will exit.

If handler is a NULL pointer, the default error handler is reinstated. The default I/O error handler prints an error message and exits.

In Release 4, XSetlOErrorHandler returns a pointer to the previous error handler. For more information, see Volume One, Chapter 3, Basic Window Program.

Related Commands

XDisplayName, XGetErrorDatabaseText,XGetErrorText,XSetAfter-Function,XSetErrorHandler, XSynchronize.

XSetLineAttributes

•Xlib - Graphics Context-

Name

XSetLineAttributes — set the line drawing components in a graphics context.

Synopsis

XSetLineAttributes(display, gc, line_width, line_style,

cap_style, join_style) Display *display; GC gc;

unsigned int li/ie_v/idth; int li/ie_style; int cap_style; int join_style;

Arguments

display Specifies a connection to an X server; returned from XOpenDisplay.

gc Specifies the graphics context.

line_style

LineSolid

LineOnOffDash

Line/Double Dash

cap_style

CapNotLast CapButt

join_style

CapRound

CapProjecting

JoinRound

JoinMiter

JoinBevel

fill_style

Ti| e GC foreground | GC background Q Undrawn Pixels [x]

FillSolid FillTiled FillStippled FillOpaqueStippled

Stipple

Xlib Reference Manual

Xlib - Graphics Context (continued) XSetLineAttributes

line_width Specifies the line width in the specified graphics context.

line_style Specifies the line style in the specified graphics context. Possible values are

LineSolid, LineOnOf f Dash, or LineDoubleDash.

cap_style Specifies the line and cap style in the specified graphics context. Possible values are CapNotLast, CapButt, CapRound, or CapPro jecting.

join_style Specifies the line-join style in the specified graphics context. Possible values are JoinMiter, JoinRound, or JoinBevel. If you specify Join-Mitre, JoinBevel is used instead if the angle separating the two lines is less than 11 degrees.

Description

XSetLineAttributes sets four types of line characteristics in the GC: line_width, line_style, cap_style, and join_style.

Get Xlib Reference Manual for Version 11 Volume 2, 5th Editon now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

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

Don’t leave empty-handed

It’s yours, free.

Check it out now on O’Reilly