See the description of line and join styles in Volume One, Chapter 5, The Graphics Context. See also XSetDashes.
A line_width of zero (0) means to use the fastest algorithm for drawing a line of one pixel width. These lines may not meet properly with lines specified as width one or more.
Errors
BadGC BadValue
Related Commands
Def aultGC, XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetArcMode,XSetBackground,XSetClipMask,XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule,XSetFillStyle,XSetForeground, XSetFunction,XSetGraphicsExposures,XSetPlaneMask,XSetState, XSet-Stipple,XSetSubwindowMode,XSetTSOrigin.
Name
XSetModifierMapping — set keycodes to be used as modifiers (Shift, Control, etc.).
Synopsis
int XSetModifierMapping( display, mod_map) Display *display; XModifierKeymap *mod_map;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
mod_map Specifies the XModif ierKeymap structure containing the desired modifier key codes.
Description
XSetModifierMapping is one of two ways to specify the keycodes of the keys that are to be used as modifiers (like Shift, Control, etc.). XSetModifierMapping specifies all the keycodes for all the modifiers at once. The other, easier, way is to use xinsert-Modif iermapEntry and XDeleteModif iermapEntry, which add or delete a single keycode for a single modifier key. XSetModifierMapping does the work in a single call, but the price of this call is that you need to manually set up the XModif ierKeymap structure pointed to by mod_map. This requires you to know how the XModif ierKeymap structure is defined and organized, as described in the next three paragraphs.
The XModif ierKeymap structure for the mod_map argument should be created using XNewModif ierMap or XGetModif ierMapping. The Max_keypermod element of the structure specifies the maximum number of keycodes that can be mapped to each modifier. You define this number but there may be an upper limit on a particular server.
The modif iermap element of the structure is an array of keycodes. There are eight by max_keypermod keycodes in this array: eight because there are eight modifiers, and max_keypermod because that is the number of keycodes that must be reserved for each mod ifier.
The eight modifiers are represented by the constants ShiftMaplndex, LockMaplndex, ControlMapIndex, ModlMapIndex, Mod2MapIndex, ModSMapIndex, Mod4Map-Index, and ModSMapIndex. These are not actually used as arguments, but they are conve nient for referring to each row in the modif iermap structure while filling it. The definitions of these constants are shown in the Structures section below.
Now you can interpret the modif iermap array. For each modifier in a given modifier-map, the keycodes which correspond are from modif iermap [index * max_keypermod] to modifiermap[((index + 1) * max_keyspermod) -1] where index is the appropriate modifier index definition (ShiftMaplndex, LockMap lndex, etc.). You must set the mod_map array up properly before calling XSetModifier Mapping. Now you know why XInsertModif ierMapEntry and XDeleteModifier-MapEntry were created!
Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a BadValue error is generated). In addition, all of the nonzero keycodes must be in the range
454 Xlib Reference Manual
Xlib - Keyboard (continued) XSetModifierMapping
specified by min_keycode and max_keycode in the Display structure (otherwise a BadValue error occurs).
A server can impose restrictions on how modifiers can be changed. For example, certain keys may not generate up transitions in hardware, certain keys may always auto-repeat and therefore be unsuitable for use as modifiers, or multiple modifier keys may not be supported. If a restric tion is violated, then the status reply is MappingFailed, and none of the modifiers are changed.
XSetModifierMapping returns MappingSuccess or MappingBusy. The server gen erates a MappingNotif y event on a MappingSuccess status. If the new keycodes speci fied for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the down state, then the status reply is MappingBusy, and none of the modifi ers are changed.
A value of zero for modif iermap indicates that no keys are valid as any modifier. Structures
typedef struct {
int max_keypermod; /* server's max # of keys per modifier */ KeyCode *modifiermap; /* an 8 by max_keypermod array */
} XModifierKeymap;
c c
/* Modifier name symbols. Used to build a SetModifierMapping request
to read a GetModifierMapping request. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define ModlMapIndex 3
#define Mod2MapIndex 4
tdefine Mod3MapIndex 5
#define ModlMapIndex 6
#define ModSMapIndex 7
Errors
BadAlloc
BadValue Keycode appears twice in the map.
Keycode < disp-Zay->min_keycode or keycode > display->max_keycode.
Related Commands
XChangeKeyboardMapping,XDeleteModifiermapEntry,XDelete-ModifiermapEntry,XFreeModifiermap,XGetKeyboardMapping,XGet-ModifierMapping, XInsertModifiermapEntry, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString,XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeysym, XRefreshKeyboardMapping, XStringToKeysym.
Name
XSetNormalHints — set the size hints property of a window in normal state (not zoomed or iconified).
Synopsis
void XSetNormalHints(display, w, hints) Display *display; Window w, XSizeHints *hints;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID.
hints Specifies a pointer to the sizing hints for the window in its normal state.
Description
XSetNormalHints has been superseded by XSetWMNormalHints as of Release 4.
XSetNormalHints sets the XA_WM_NORMAL_HINTS property for the specified window. Applications use XSetNormalHints to inform the window manager of the size or position desirable for that window. In addition, an application wanting to move or resize itself should call XSetNormalHints specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead.
To set size hints, an application must assign values to the appropriate elements in the hints structure, and also set the flags field of the structure to indicate which members have assigned values and the source of the assignment These flags are listed in the Structures sec tion below.
For more information on using hints, see Volume One, Chapter WJnterclient Communication. Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints; /*~new fields in R4 here */
456 Xlib Reference Manual
Xlib - Window Manager Hints (continued) XSetNormalHints
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
tdefine PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
tdefine PMinSize (1L « 4) /* program specified minimum size */
tdefine PMaxSize (1L « 5) /* program specified maximum size */
tdefine PResizelnc (1L « 6) /* program specified resize increments */
tdefine PAspect (1L « 7) /* program specified min/max aspect ratios */
tdefine PAllHints (PPositionIPSize|PMinSizeIPMaxSizeIPResizelnc|PAspect)
Errors
BadAlloc BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName,XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-Hints,XSetClassHint,XSetCommand,XSetIconName,XSetIconSizes,XSet-SizeHints,XSetTransientForHint,XSetWMHints,XSetZoomHints,XStore-Name.
XSetPlaneMask \ Xlib _ Graphlcs Comext _
Name
XSetPlaneMask — set the plane mask in a graphics context.
Synopsis
XSetPlaneMask(display, gc, plane_mask) Display * display ; GC gc; unsigned long plane_mask;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
plane_mask Specifies the plane mask. You can use the macro AllPlanes if desired.
Description
XSetPlaneMask sets the plane_mask component of the specified GC. The plane_mask determines which planes of the destination drawable are affected by a graphics request.
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, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,XSetGraphicsExposures,XSetLineAttributes,XSetState, XSetStipple, XSetSubwindowMode,XSetTSOrigin.
—Xlib-Pointer •
j XSetPointerMapping
Name
XSetPointerMapping — set the pointer button mapping.
Synopsis
int XSetPointerMapping (display, map, nmap) Display *display; unsigned char map[] ; int nmap;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
map Specifies the mapping list.
nmap Specifies the number of items in the mapping list.
Description
XSetPointerMapping sets the mapping of the pointer buttons. Elements of the map list are indexed starting from 1. The length of the list nmap must be the same as XGetPointer-Mapping returns (you must call that first). The index is a physical button number, and the ele ment of the list defines the effective button number. In other words, if map [2] is set to 1, when the second physical button is pressed, a ButtonPress event will be generated if But-tonlMask was selected but not if Button2Mask was selected. The button member in the event will read Buttonl.
No two elements can have the same nonzero value (else a BadValue error). A value of zero for an element of map disables a button, and values for elements are not restricted in value by the number of physical buttons. If any of the buttons to be altered are currently in the down state, the returned value is MappingBusy and the mapping is not changed.
This function returns either MappingSuccess or MappingBusy. XSetPointer Mapping generates a MappingNotif y event when it returns MappingSuccess.
Errors
BadValue Two elements of map [ ] have same nonzero value.
nmap not equal to XGetPointerMapping return value.
Related Commands
XChangeActivePointerGrab,XChangePointerControl,XGetPointer-Control, XGetPointerMapping,XGrabPointer,XQueryPointer,XUngrab-Pointer, XWarpPointer.
Name
XSetRGBColormaps — set an XStandardColormap structure. Synopsis
void XSetRGBColormaps(display, w, std_colormap, count, prop erty)
Display *display; Window w;
XStandardColormap * std_col or/nap; int count; Atom property;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
std_col or/nap
Specifies the XStandardColormap structure to be used.
count Specifies the number of colormaps.
property Specifies the property name.
Availability
Release 4 and later.
Description
XSetRGBColormaps replaces the RGB colormap definition in the specified property on the named window. If the property does not already exist, XSetRGBColormaps sets the RGB colormap definition in the specified property on the named window. The property is stored with a type of RGB_COLOR_MAP and a format of 32. Note that it is the caller's responsibility to honor the ICCCM restriction that only RGB_DEFAULT_MAP contain more than one definition.
XSetRGBColormaps supersedes XSetStandardColormap. For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue mult;
460 Xlib Reference Manual
Xlib - Window Manager Hints (continued) XSetRG BColormapS
unsigned long base_jpixel;
VisuallD visualid; /* added by ICCCM version 1 */
XID killid; /* added by ICCCM version 1 */
} XStandardColormap;
Errors
BadAlloc
BadAtom
BadWindow
Related Commands
XAllocStandardColormap,XGetRGBColormaps, XVisuallDFromVisual.
XSetRegion V,
•Xlib-Regions-
Name
XSetRegion — set clip_mask of the graphics context to the specified region.
Synopsis
XSetRegion(display, gc, r) Display * display; GC gc; Region r;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
r Specifies the region.
Description
XSetRegion sets the clip_mask component of a GC to the specified region. Thereafter, all drawing made with gc will be confined to the the area of intersection of the region and the drawable.
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. When 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 (xof f set + clip_x_origin, yof f set + clip_y_origin), where xof f set and yof f set are the offset of the region and clip_x_origin and clip_y_origin are elements of the GC used in the graphics request
For more information on regions, see Volume One, Chapter 5, The Graphics Context, and Chapter 6, Drawing Graphics and Text.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox,XCreateRegion,XDestroyRegion,XEmptyRegion, XEqualRegion, XIntersectRegion,XOffsetRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,XShrinkRegion,XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.
j XSetScreenSaver
—Xlib - Screen Saver
Name
XSetScreenSaver — set the parameters of the screen saver.
Synopsis
XSetScreenSaver( display, timeout, interval,
prefer_blanking, allow_exposures) Display *display; int timeout, interval; int prefer_blanking; int allov_exposures;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
timeout Specifies the time of inactivity, in seconds, before the screen saver turns on.
interval Specifies the interval, in seconds, between screen saver invocations. This is for intermittent changes to the display, not blanking.
prefer_blanking
Specifies whether to enable screen blanking. Possible values are Dont-PreferBlanking, PreferBlanking, or DefaultBlanking.
allow_exposures
Specifies the current screen saver control values. Possible values are Dont-AllowExposures,AllowExposures, or DefaultExposures.
Description
XSetScreenSaver sets the parameters that control the screen saver, timeout and interval are specified in seconds. A positive timeout enables the screen saver. A timeout of zero (0) disables the screen saver, while a timeout of -1 restores the default. An interval of zero (0) disables the random pattern motion. If no input from devices (key board, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is activated.
For each screen, if blanking is preferred and the hardware supports video blanking, the screen will simply go blank. Otherwise, if either exposures are allowed or the screen can be regen erated without sending exposure events to clients, the screen is tiled with the root window background tile, with a random origin, each interval seconds. Otherwise, the state of the screen does not change. All screen states are restored at the next input from a device.
If the server-dependent screen saver method supports periodic change, interval serves as a hint about how long the change period should be, and a value of zero (0) hints that no periodic change should be made. Examples of ways to change the screen include scrambling the color map periodically, moving an icon image about the screen periodically, or tiling the screen with the root window background tile, randomly reoriginated periodically.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
XSetScreenSaver (continued) Xlib - Screen Saver
Errors
BadValue timeout < -I.
Related Commands
XActivateScreenSaver,XForceScreenSaver,XGetScreenSaver,XReset-ScreenSaver.
Xlib Reference Manual
_x,ib - s,,ec,,on, / XSetSelectionOwner
Name
XSetSelectionOwner — set the owner of a selection.
Synopsis
XSetSelectionOwner( display, selection, owner, time) Display *display; Atom selection; Window owner; Time time;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
selection Specifies the selection atom. Predefined atoms are XA PRIMARY and
XA_SECONDARY.
owner Specifies the desired owner of the specified selection atom. This value is
either a window ID or None.
time Specifies the time when the selection should take place. Pass either a times-
tamp, expressed in milliseconds, or the constant CurrentTime.
Description
XSetSelectionOwner sets the owner and last-change time of a selection property. This should be called by an application that supports cutting and pasting between windows (or at least cutting), when the user has made a selection of any kind of text, graphics, or data. This makes the information available so that other applications can request the data from the new selection owner using xconvertselection, which generates a SeiectionRequest event specifying the desired type and format of the data. Then the selection owner sends a SelectionNotify using xsendEvent, which notes that the information is stored in the selec tion property in the desired format or indicates that it couldn't do the conversion to the desired type.
If owner is specified as None, then this client is giving up ownership voluntarily. Otherwise, the new owner is the client executing the request
If the new owner is not the same as the current owner of the selection, and the current owner is a window, then the current owner is sent a SeiectionClear event. This indicates to the old owner that the selection should be unhighlighted.
If the selection owner window is later destroyed, the owner of the selection automatically reverts to None.
The value you pass to the time argument must be no earlier than the last-change time of the specified selection, and no later than the current time, or the selection is not affected. The new last-change time recorded is the specified time, with CurrentTime replaced by the current server time. If the X server reverts a selection owner to None, the last-change time is not affected.
For more information on selections, see Volume One, Chapter 10, Interclient Communication.
XSetSeleCtionOwner (continued) Xlib - Selections
Errors
BadAtom BadWindow
Related Commands
XConvertSelect!on,XGetSelectionOwner.
466
Xlib Reference Manual
-X,,b-W,ndowManag e rH,n,, ' XSetSizeHitltS
Name
XSetSizeHints — set the value of any property of type XA_SIZE_HINTS.
Synopsis
XSetSizeHints(display, w, hints, property) Display *display; Window w;
XSizeHints *hints; Atom property;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDisplay.
v Specifies the window ID.
hints Specifies a pointer to the size hints.
property Specifies the property atom.
Description
XSetSizeHints has been superseded by XSetWMSizeHints as of Release 4.
XSetSizeHints sets the named property on the specified window to the specified XSize Hints structure. This routine is useful if new properties of type XA_WM_SIZE_HINTS are defined. The predefined properties of that type have their own set and get functions, XSet-NormalHints and XSetZoomHints (XSetWMHints in Release 4—zoom hints are obso lete).
The flags member of XSizeHints must be set to the OR of the symbols representing each member to be set
For more information on using hints, see Volume One, Chapter IQJnterclient Communication. Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
tdefine USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
XSetSlzeHintS (continued) Xlib - Window Manager Hints
tdefine PMinSize (1L « 4) /* program specified minimum size */
tdefine PMaxSize (1L « 5) /* program specified maximum size */
#define PResizelnc (1L « 6) /* program specified resize increments */
tdefine PAspect (1L « 7) /* program specified min/max aspect ratios */
tdefine PAllHints (PPosition IPSizeIPMinSizeIPMaxSize|PResizelnc|PAspect)
Errors
BadAlloc
BadAtom
BadWindow
Related Commands
XFetchName,XGetClassHint,XGetIconName,XGetIconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints, XGetZoom-Hints, XSetClassHint,XSetCommand,XSetlconName,XSetlconSizes,XSet-NormalHints,XSetTransientForHint,XSetWMHints, XSetZoomHints, XStoreName.
Xlib Reference Manual
—Xlib - Colormaps-
J XSetStandardColormap
Name
XSetStandardColormap — change the standard colormap property.
Synopsis
void XSetStandardColormap ( display, w, cmap_info, property) Display *display; Window w;
XStandardColormap *cmap_info; Atom property;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDisplay. w Specifies the ID of the window with which this colormap will be associated.
cmap_info Specifies the filled colormap information structure.
property Specifies the standard colormap property to set. The predefined standard color-maps are: XA_RGB_BEST_MAP, XA_RGB_RED_MAP, XA_RGB_GREEN_ MAP,
XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_ GRAY_MAP.
Description
XSetStandardColormap has been superseded by XSetRGBColormap as of Release 4.
XSetStandardColormap defines a standard colormap property. To create a standard color-map, follow this procedure:
1. Open a new connection to the same server.
2. Grab the server.
3. See if property is on the property list of the root window for the display, using XGet -StandardColormap. If so, see if the colormap field is nonzero. If it is, the color-map already exists.
4. If the desired property is not present, do the following:
• Determine the color capabilities of the display. Choose a visual. Create a colormap (not required for XA_RGB_DEFAULT_MAP).
Call XAllocColorPlanes or XAllocColorCells to allocate cells in the colormap.
• Call xstoreColors to store appropriate color values in the colormap. Fill in the descriptive fields in the structure.
• Call XSetStandardColormap to set the property on the root window. Use XSetCloseDownMode to make the resource permanent.
Close the new connection to the server.
Xlib Reference Manual
XSetStandardColormap
(continued)
Xlib - Colormaps
5. Ungrab the server.
6. Close the new connection to the server.
See description of standard colormaps in Volume One, Chapter 7, Color.
Errors
BadAlloc
BadAtom
BadWindow
Structures
typedef struct {
Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green_max;
unsigned long green_mult,
unsigned long blue_max;
unsigned long blue_mult;
unsigned long base_pixel, } XStandardColormap;
ID of colormap made by XCreateColormap */
/* new fields in R4 */
Related Commands
DefaultColormap, DisplayCells,XCopyColormapAndFree,XCreate Colormap, XFreeColormap,XGetStandardColormap, XInstallColormap, XListlnstalledColormaps.XSetWindowColormap, XUninstallColormap.
470
Xlib Reference Manual
-x,, b -Prop.r«es / XSetStandardProperties
Name
XSetStandardProperties — set the minimum set of properties for the window manager.
Synopsis
XSetStandardProperties( display, w f window_name, icon_name,
icon_pixmap, argv, argc, hints) Display * display; Window w;
char *window_name; char *icon_name; Pixmap icon_pixmap; char **argv; int argc; XSizeHints *hints
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID.
window_name Specifies the name of the window.
i con_name Specifies the name to be displayed in the window's icon.
icon_pixmap Specifies the pixmap that is to be used for the icon, or None. This pixmap must be of depth 1.
argv Specifies a pointer to the command and arguments used to start the applica
tion.
argc Specifies the number of arguments.
hints Specifies a pointer to the size hints for the window in its normal state.
Description
XSetStandardProperties is superceded by XSetWMProperties in Release 4.
XSetStandardProperties sets in a single call the most essential properties for a quickie application. XSetStandardProperties gives a window manager some information about your program's preferences; it probably will not be sufficient for complex programs.
See Volume One, Chapter 10, Interclient Communication for a description of standard proper ties.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
XSetStandardProperties
(continued)
Xlib - Properties
struct {
int x; int y;
} min_aspect } XSizeHints;
/* numerator */ /* denominator */ max aspect; /* new fields in R4 */
/* flags argument in size hints */
#define USPosition (1L « O)/* user specified x, y */
tdefine USSize (1L « I)/* user specified width, height */
tdefine PPosition #define PSize #define PMinSize #define PMaxSize #define PResizelnc #define PAspect
(1L « 2)/* program specified position */
(1L « 3)/* program specified size */
(1L « 4)/* program specified minimum size */
(1L « 5)/* program specified maximum size */
(1L « 6)/* program specified resize increments */
(1L « 7)/* program specified min and max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizelnc|PAspect)
Errors
BadAlloc BadWindow
Related Commands
XChangeProperty,XDeleteProperty,XGetAtomName, XGetFontProperty, XGetWindowProperty,XInternAtom, XListProperties, XRotateWindow-Properties.
472
Xlib Reference Manual
-X,,bG raph,cs Context / XSetState
Name
XSetState — set the foreground, background, logical function, and plane mask in a graphics context.
Synopsis
XSetState (display, gc, foreground, background, function,
plane_mask) Display * display; GC gc;
unsigned long foreground, background; int function; unsigned long plane_mask;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
foreground Specifies the foreground for the specified graphics context.
background Specifies the background for the specified graphics context.
function Specifies the logical function for the specified graphics context,
pi ane_mask Specifies the plane mask for the specified graphics context.
Description
XSetState sets the foreground and background pixel values, the logical function, and the plane_mask in a GC. See XSetForeground, XSetBackground, XSet-Function, and XSetPlaneMask for what these members do and appropriate values.
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,XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,XSetGraphicsExposures,XSetLineAttributes,XSetPlane Mask, XSetStipple,XSetSubwindowMode, XSetTSOrigin.
XSetStipple ~\
•Xlib-Graphics Context-
Name
XSetStipple — set the stipple in a graphics context.
Synopsis
XSetStipple(display, gc, stipple) Display * display; GC gc; Pixmap stipple;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
stipple Specifies the stipple for the specified graphics context.
Description
XSetStipple sets the stipple component of a GC. The stipple is a pixmap of depth one. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn in the foreground pixel value. Unset bits in the stipple determine which pixels are drawn in the background pixel value if the fill_style is FillOpaqueStippled. If fill_style is FillStippled, pixels overlayed with unset bits in the stipple are not drawn. If f ill_style is FillTiled or FillSolid, the stipple is not used.
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,XSetClipMask, XSetClipOrigin, XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction,XSetGraphicsExposures,XSetLineAttributes,XSetPlane-Mask,XSetState,XSetSubwindowMode,XSetTSOrigin.
-x,, b - Graph.cs con,«t XSetSubwindowMode
Name
XSetSubwindowMode — set the subwindow mode in a graphics context.
Synopsis
XSetSubwindowMode(display, gc, subwindow_mode) Display * display; GC gc ; int subwindow_mode ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
subwindow_mode
Specifies the subwindow mode you want to set for the specified graphics con text. Possible values are ClipByChildren or Includelnf eriors.
Description
XSetSubwindowMode sets the subwindow_mode component of a GC. Clip ByChildren means that graphics requests will be clipped by all viewable children. Includelnf eriors means draw through all subwindows.
For more information, see Volume One, Chapter 5, The Graphics Context. Errors
BadGC BadValue
Related Commands
DefaultGC,XChangeGC,XCopyGC, XCreateGC,XFreeGC,XGContextFromGC, XSetArcMode,XSetBackground,XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle,XSetForeground, XSetFunction,XSetGraphicsExposures,XSetLineAttributes,XSetPlane-Mask,XSetState,XSetStipple, XSetTSOrigin.
XSetTeXtPrOperty \ x,,b-Window Managers-
Name
XSetTextProperty — set one of a window's text properties. Synopsis
void XSetTextProperty (display, w, text_prop, property) Display * display; Window w;
XTextProperty *text_prop; Atom property;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
property Specifies the property name.
Availability
Release 4 and later.
Description
XSetTextProperty sets the specified property for the named window with the data, type, format, and number of items determined by the value field, the encoding field, the format field, and the nitems field, respectively, of the specified XTextProperty structure.
Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
Errors
BadAlloc BadAtom BadValue BadWindow
Related Commands
XFreeStringList, XGetTextProperty, XStringListToTextProperty, XText-PropertytoStringList.
-Xllb - Plxmaps and Tiles ' XSetTHe
Name
XSetTile — set the fill tile in a graphics context.
Synopsis
XSetTile(display, gc, tile) Display * display; GC gc; Pixmap tile;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
gc Specifies the graphics context.
tile Specifies the desired tile for the specified graphics context.
Description
XSetTile sets the tile member of the GC. This member of the GC determines the pixmap used to tile areas. The tile must have the same depth as the destination drawable. This tile will only be used in drawing if the fill-style is Fill riled.
For more information, see Volume One, Chapter 5, The Graphics Context. Errors
BadGC
BadMatch
BadPixmap
Related Commands
XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile, XReadBitmapFile,XSetWindowBackgroundPixmap,XSetWindowBorder-Pixmap, XWriteBitmapFile.
XSetTransientForHint V X,ib-Window Manager H,ms-
Name
XSetTransientForHint — set the XA_WM_TRANSIENT_FOR property for a window.
Synopsis
XSetTransientForHint( display, w, prop_window) Display * display; Window w; Window prop_window;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID, normally of a dialog box popup.
prop_window Specifies the window ID that the XA_WM_TRANSIENT_FOR property is to be set to. This is usually the main window of the application.
Description
XSetTransientForHint sets the XA_WM_TRANSIENT_FOR property of the specified win dow. This should be done when the window w is a temporary child (for example, a dialog box) and the main top-level window of its application is prop_window. Some window managers may use this information to unmap an application's dialog boxes (for example, when the main application window gets iconified).
For more information, see Volume One, Chapter 10, Inter-client Communication. Errors
BadAlloc BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName,XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints, XGetZoom-Hints,XSetClassHint,XSetCommand,XSetlconName,XSetlconSizes,XSet-NormalHints,XSetSizeHints,XSetWMHints,XSetZoomHints,XStoreName.
f XSetTSOrigin
—Xlib - Graphics Context '
Name
XSetTSOrigin — set the tile/stipple origin in a graphics context.
Synopsis
XSetTSOrigin ( display, gc, ts_x_origin f ts_y_origin) Display * display ; GC gc; int ts_x_origin, ts_y_origin;
Arguments
display Specifies a connection to an X server; returned from xopenoisplay.
gc Specifies the graphics context.
ts_x_origin Specify the x and y coordinates of the tile/stipple origin.
ts_y_origin
Description
XSetTSOrigin sets the ts_x_origin and ts_y_origin components in a GC, which are measured relative to the origin of the drawable specified in the drawing request that uses the GC. This controls the placement of the tile or the stipple pattern that patterns an area. To tile or stipple a child so that the pattern matches the parent, you need to subtract the current posi tion of the child window from ts_x_origin and ts_y_origin.
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, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule, XSetFillStyle,XSetForeground, XSetFunction, XSetGraphicsExposures,XSetLineAttributes,XSetPlane-Mask,XSetState,XSetStipple, XSetSubwindowMode.
Name
XSetWMCIientMachine — set a window's WM_CLIENT_MACHINE property.
Synopsis
void XSetWMCIientMachine (display, w, text_prop) Display *display; Window w; XTextProperty *text_prop;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
text_jprop Specifies the XText Property structure to be used.
Availability
Release 4 and later.
Description
XSetWMCIientMachine performs an XSetTextProperty to set the WM_CLIENT_MACHINE property of the specified window. This property should contain the name of the host machine on which this client is being run, as seen from the server.
For more information, see Volume One, Chapter 10, Interclient Communication. Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
Related Commands
XGetWMClientMachine.
480 Xlib Reference Manual
—Xlib - Window Manager Hints-
XSetWMColormapWindows
Name
XSetWMColormapWindows — set a window's WM_COLORMAP_WINDOWS property.
Synopsis
Status XSetWMColormapWindows(display, w, colormap_windows,
count)
Display * display; Window w;
Window *colormap_windows; int count ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
colormap_windows
Specifies the list of windows.
count Specifies the number of windows in the list.
Availability
Release 4 and later.
Description
XSetWMColormapWindows sets the WM_cOLORMAP_wiNDOWS property on the specified win dow to the list of windows specified by the colormap_windows argument. The property is stored with a type of WINDOW and a format of 32. If it cannot intern the WM_COLORMAP_WINDOWS atom, XSetWMColormapWindows returns a zero status. Other wise, it returns a non-zero status.
This property tells the window manager that subwindows of this application need to have their own colormaps installed.
For more information, see Volume One, Chapter WJnterclient Communication.
Errors
BadAlloc BadWindow
Related Commands
XGetWMColormapWindows.
Name
XSetWMIconName — set a window's XA_WM_ICON_NAME property.
Synopsis
void XSetWMIconName ( display f w, text_prop) Display ^display; Window w; XTextProperty *text_prop;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
text_j>rop Specifies the XTextProperty structure to be used.
Availability
Release 4 and later.
Description
XSetWMIconName performs an XSetTextProperty to set the XA_WM_ICON_NAME prop erty of the specified window. XSetWMIconName supersedes XSetlconName.
This is usually called by an application to set the property 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 WJnterclient Communication. Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
Related Commands
XGetWMIconName,XGetWMName,XSetWMName, XSetWMProperties.
482 Xlib Reference Manual
-X,, b -Window Manag., H,n, / XSetWMName
Name
XSetWMName — set a window's XA_WM_NAME property.
Synopsis
void XSetWMName ( display, w, text_prop) Display * display; Window w; XTextProperty *text_propj
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
text_prop Specifies the XTextProperty structure to be used.
Availability
Release 4 and later.
Description
XSetWMName performs a xsetTextProperty to set the XA_WM_NAME property on the specified window. XSetWMName supersedes XStoreName. This property can also be set with XSetWMProperties.
XSetWMName be used by the application to communicate a string to the window manager. According to current conventions, this string should either:
permit the user to identify one of a number of instances of the same client, or provide the user with noncritical state information. Clients can assume that at least the beginning of this string is visible to the user.
The XA_WM_CLASS property, on the other hand, has two members which should be used to iden tify the application's instance and class name, for the lookup of resources. See XSetClass-Hint for details.
For more information, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
unsigned char *value;
Atom encoding;
int format;
unsigned long nitems; } XTextProperty;
/* same as Property routines */
/* prop type */
/* prop data format: 8, 16, or 32 */
/* number of data items in value */
Related Commands
XGetWMIconName, XGetWMName, XSetWMIconName, XSetWMProperties.
Xlib Reference Manual
Name
XSetWMNormalHints — set a window's XA_WM_NORMAL_HINTS property.
Synopsis
void XSetWMNormalHints(display, w, hints) Display *display; Window w; XSizeHints *hints;
Arguments
di spl ay Specifies a connection to an X server; returned from XOpenDi splay.
w Specifies the window.
hints Specifies the size hints for the window in its normal state.
Availability
Release 4 and later.
Description
XSetWMNormalHints sets the size hints in the XA_WM_NORMAL_HINTS property on the specified window. The property is stored with a type of WM_SIZE_HINTS and a format of 32. XSetWMNormalHints supersedes XSetNormalHints. This property can also be set with XSetWMProperties.
Applications use XSetNormalHints to inform the window manager of the sizes desirable for that window.
To set size hints, an application must assign values to the appropriate elements in the hints structure, and also set the flags field of the structure to indicate which members have assigned values and the source of the assignment These flags are listed in the Structures sec tion below.
For more information, see Volume One, Chapter 10, Interdient Communication. Structures
typedef struct {
long flags; /* marks which fields in this structure */
/* are defined */
int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect;
int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */
484 Xlib Reference Manual
Xlib - Window Manager Hints
(continued)
XSetWMNormalHints
} XSizeHints;
#define USPosition (1L « 0) A tdefine USSize (1L « 1) A
user specified x, y */
user specified width, height */
tdefine PPosition (1L « 2) /* program specified position
tdefine PSize (1L « 3) /
tdefine PMinSize (1L « 4) /
tdefine PMaxSize (1L « 5) /
tdefine PResizelnc (1L « 6) /
program specified size V program specified minimum size */ program specified maximum size */ program specified resize increments
tdefine PAspect (1L « 7) /* program specified min/max aspect ratios */
tdefine PAllHints (PPositionIPSizeIPMinSizeIPMaxSizeIPResizelncIPAspect) tdefine PBaseSize (1L « 8) /* program specified base
for incrementing */
tdefine PWinGravity (1L « 9)/* program specified window
gravity */
Errors
BadAlloc BadWindow
Related Commands
XGetWMNormalHints, XSetWMProperties, XSetWMSizeHints, XGetWMSize-Hints.
Xlib Reference Manual
XSetWMProperties
•Xlib - Window Manager Hints-
Name
XSetWMProperties — set a window's standard window manager properties.
Synopsis
void XSetWMProperties( display, w, window_name, icon_name, argv f
argc, normal_hints, wm_hints, class_hints) Display *display; Window w;
XTextProperty *window_name; XTextProperty *icon_name; char **argv; int argc;
XSizeHints *normal_hints ; XWMHints *wm_hints; XClassHint *class_hints ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window.
window_name Specifies the window name, which should be a null-terminated string.
i con_name Specifies the icon name, which should be a null-terminated string.
argv Specifies the application's argument list.
argc Specifies the number of arguments.
normal_hints
Specifies the size hints for the window in its normal state.
wm_hints Specifies the XWMHints structure to be used. class_hints Specifies the XClassHint structure to be used.
Availability
Release 4 and later.
Description
XSetWMProperties provides a single programming interface for setting the essential win dow properties that communicate with window and session managers. XSetWMProperties supersedes XSetStandardProperties.
If the window_name argument is non-null, XSetWMProperties calls XSetWMName, which, in turn, sets the WM_NAME property. If the icon_name argument is non-null, XSet WMProperties calls xsetWMiconName, which sets the WM_ICON_NAME property. If the argv argument is non-null, XSetWMProperties calls XSetCommand, which sets the WM_COMMAND property. Note that an argc of 0 is allowed to indicate a zero-length command. XSetWMProperties stores the hostname of this machine using XSetWMClientMachine.
Xlib - Window Manager Hints (continued) XSetWMPropertieS
If the normal_hints argument is non-null, XSetWMProperties calls XSetWMNormal-Hints, which sets the WM_NORMAL_HINTS property. If the wm_hints argument is non-null, XSetWMProperties calls XSetWMHints, which sets the WM_HINTS property.
If the class_hints argument is non-null, XSetWMProperties calls XSetClassHint, which sets the WM_CLASS property. If the res_name member in the XClassHint structure is set to the null pointer and the RESOURCE_NAME environment variable is set, then value of the environment variable is substituted for res_name. If the res_name member is NULL, and if the environment variable is not set, and if argvand argv[0] are set, then the value of argv[0], stripped of any directory prefixes, is substituted for res_name.
For more information, see Volume One, Chapter WJnterclient Communication. Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
typedef struct {
long flags; /* marks which fields in this structure */ /* are defined */
int x, y; /* obsolete for new window mgrs, but clients */
int width, height; /* should set so old wm's don't mess up */
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */ int y; /* denominator */
} min_aspect, max_aspect;
int base_width, base_height; /* added by ICCCM version 1 */
int win_gravity; /* added by ICCCM version 1 */
} XSizeHints;
typedef struct {
long flags; /* marks which fields in this structure */
/* are defined */ Bool input; /* does this application rely on the window */
/* manager to get keyboard input? */ int initial_state; /* see below */
Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* icon mask bitmap */
XSetWMProperties (continued) Xlib - Window Manager Hints
XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints;
typedef struct {
char *res_name;
char *res_class; } XClassHint;
Errors
BadAlloc BadWindow
Related Commands
XGetClassHints, XGetCommand, XGetWMHints, XGetWMIconName, XGetWMName, XGetWMNormalHints, XSetWMClientMachine, XSetWMColormapWindows,XSet-WMProtocols.
J XSetWMProtocols
— Xlib - Window Manager Hints '
Name
XSetWMProtocols — set a window's WM_PROTOCOLS property.
Synopsis
Status XSetWMProtocols (display, w, protocols, count) Display ^display; Window w; Atom ^protocols; int count;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDisp 1 ay.
w Specifies the window.
protocols Specifies the list of protocols.
count Specifies the number of protocols in the list.
Availability
Release 4 and later.
Description
XSetWMProtocols sets the WM_PROTOCOLS property on the specified window to the list of atoms specified by the protocols argument. The property is stored with a type of ATOM and a format of 32. If it cannot intern the WM_PROTOCOLS atom, XSetWMProtocols returns a zero status. Otherwise, it returns a non-zero status.
The list of standard protocols at present is as follows:
WM_TAKE_FOCUS Assignment of keyboard focus
WM_SAVE_YOURSELF Save client state warning
WM_DELETE_UNKNOWN Request to delete top-level window
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc BadWindow
Related Commands
XGetWMProtocols.
Name
XSetWMSizeHints — set a window's WM_SIZE_HINTS property.
Synopsis
void XSetWMSizeHints(display, w, hints, property) Display * display; Window w;
XSizeHints *hints; Atom property;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
w Specifies the window.
hints Specifies the XSizeHints structure to be used.
property Specifies the property name.
Availability
Release 4 and later.
Description
XSetWMSizeHints sets the size hints for the specified property on the named window. The property is stored with a type of WM_SIZE_HINTS and a format of 32. To set a window's nor mal size hints, you can use the XSetWMNormalHints function instead. XSetWMSize Hints supersedes XSetSizeHints.
This routine is useful if new properties of type XA_WM_SIZE_HINTS are defined.
The flags member of XSizeHints must be set to the OR of the symbols representing each member to be set
For more information, see Volume One, Chapter WJnterclient Communication. Structures
typedef struct {
long flags; /* marks which fields in this structure are */
/* defined as */
int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect;
int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */
490 xiib Reference Manual
Xlib - Window Manager Hints
(continued)
XSetWMSizeHints
} XSizeHints;
#define USPosition (1L « 0) #define USSize (1L « 1)
user specified x, y */
user specified width, height */
#define PPosition (1L « 2) /* program specified position
*/
tdefine PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizelnc (1L « 6) /* program specified resize increments *
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSizeIPMinSizeIPMaxSize|PResizelncIPAspect) tdefine PBaseSize (1L « 8) /* program specified base
for incrementing */ #define PWinGravity (1L « 9)/* program specified window
gravity */
Errors
BadAlloc
BadAtom
BadWindow
Related Commands
XAllocSizeHints, XGetWMNormalHints, XGetWMSizeHints, XSetWMNormal-Hints.
Xlib Reference Manual
XSetWindowBackground \
•Xlib - Window Attributes-
Name
XSetWindowBackground — set the background pixel value attribute of a window.
Synopsis
XSetWindowBackground( display, w, background_pixel) Display * display; Window w; unsigned long background_pixel;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID. Must be an inputOutput window.
background_pixel
Specifies which entry in the colormap is used as the background color. The constant CopyFromParent is NOT valid.
Description
XSetWindowBackground sets the background attribute of a window, setting the pixel value to be used to fill the background. This overrides any previous call to XSetWindow Background or XSetWindowBackgroundPixmap on the same window.
XSetWindowBackground does not change the current window contents immediately. The background is automatically repainted after Expose events. You can also redraw the back ground without Expose events by calling XClearWindow immediately after.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch Setting background of Input Only window.
BadWindow
Related Commands
XChangeWindowAttributes,XGetGeometry, XGetWindowAttributes,XSet WindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap.
Xlib Reference Manual
XSetWindowBackgroundPixmap
— Xlib - Pixmaps and Tiles
Name
XSetWindowBackgroundPixmap — change the background tile attribute of a window.
Synopsis
XSetWindowBackgroundPixmap(display, w, background_tile) Display *display; Window w; Pixmap background_tile;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID. Must be an inputOutput class window.
background_tile
Specifies a pixmap ID, None or ParentRelative, to be used as a back ground.
Description
XSetWindowBackgroundPixmap sets the background_pixmap attribute of a window. This overrides any previous background_pixel or background_pixmap attribute set ting set with XSetWindowBackgroundPixmap, XSetWindowBackground, or XChangeWindowAttributes. Drawing into the pixmap that was set as the background pixmap attribute has an undefined effect on the window background. The server may or may not make a copy of the pixmap.
If the background is set to a pixmap, the background is tiled with the pixmap. If the pixmap is not explicitly referenced again, it can be freed, since a copy is maintained in the server. The background of the window will not be redrawn with the new tile until the next Expose event or XClearWindow call.
If the background is set to None, The window background initially will be invisible and will share the bits of its parent, but only if the background_pixel attribute is not set. When anything is drawn by any client into the area enclosed by the window, the contents will remain until the area is explicitly cleared with XClearWindow. The background is not automatically refreshed after exposure.
If the background is set to ParentRelative, the parent's background is used, and the origin for tiling is the parent's origin (or the parent's parent if the parent's background_pixmap attribute is also ParentRelative, and so on). The difference between setting Parent-Relative and explicitly setting the same pixmap as the parent is the origin of the tiling. The difference between ParentRelative and None is that for ParentRelative the back ground is automatically repainted on exposure.
For ParentRelative, the window must have the same depth as the parent, or a BadMatch error will occur. If the parent has background None, then the window will also have back ground None. The parent's background is re-examined each time the window background is
Xlib Reference Manual
XSetWindOwBackgroundPixmap (continued) Xlib - Pixmaps and Tiles
required (when it needs to be redrawn due to mapping or exposure). The window's contents will be lost when the window is moved relative to its parent, and the contents will have to be redrawn.
Changing the background_pixmap attribute of the root window to None or Parent-Relative restores the default.
XSetWindOwBackgroundPixmap can only be performed on an Input Output window. A BadMatch error will result otherwise.
XSetwindowBackground may be used if a solid color instead of a tile is desired. For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadPixmap
BadWindow
Related Commands
XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile, XReadBitmapFile,XSetTile, XSetWindowBorderPixmap,XWriteBitmapFile.
f XSetWindowBorder
—Xlib - Window Attributes '
Name
XSetWindowBorder — change a window border pixel value attribute and repaint the border.
Synopsis
XSetWindowBorder(display, w, border^pixel) Display * display ; Window v, unsigned long border_pixel ;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID. Must be an inputOutput window.
border_pixel
Specifies the colormap entry with which the server will paint the border.
Description
XSetWindowBorder sets the border_jpixel attribute of window w to a pixel value, and repaints the border. The border is also automatically repainted after Expose events.
Use XSetwindowBorderPixmap to create a tiled border. On top-level windows, the win dow manager often resets the border, so applications should not depend on their settings.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch Setting border of inputOnly window.
BadWindow
Related Commands
XChangeWindowAttributes,XGetGeometry, XGetWindowAttributes,XSet-WindowBackground,XSetWindowBackgroundPixmap, XSetwindowBorder Pixmap.
Xlib Reference Manual 495
XSetWindowBorderPixmap
•Xlib - Pixmaps and Tiles-
Name
XSetWindowBorderPixmap — change a window border tile attribute and repaint the border.
Synopsis
XSetWindowBorderPixmap(display, w, border_tile) Display * display ; Window w; Pixmap jborder_tile;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of an inputOutput window whose border is to be to a file.
border_tile Specifies any pixmap or None.
Description
XSetWindowBorderPixmap sets the border_pixmap attribute of a window and repaints the border. The border_tile can be freed immediately after the call if no further explicit references to it are to be made.
This function can only be performed on an InputOutput window. On top-level windows, the window manager often resets the border, so applications should not depend on their set tings.
Errors
BadMatch
BadPixmap
BadWindow
Related Commands
XCreateBitmapFromData, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize, XQueryBestStipple, XQueryBestTile, XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XWriteBitmap-
File.
496 xiib Reference Manual
XSetWindowBorderWIdth
—Xlib - Window Manipulation-
Name
XSetWindowBorderWidth — change the border width of a window.
Synopsis
XSetWindowBorderWidth (display, w, width) Display *display; Window w; unsigned int width;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window whose border is to be changed.
wi dth Specifies the width of the window border.
Description
XSetWindowBorderWidth changes the border width of a window. This request is often used on top-level windows by the window manager as an indication of the current keyboard focus window, so other clients should not depend on the border width of top-level windows.
Errors
BadMatch Setting border width of an Input Only window.
BadWindow
Related Commands
XCirculateSubwindows, XCirculateSubwindowsDown,XCirculate-SubwindowsUp,XConfigureWindow, XLowerWindow, XMoveResizeWindow, XMoveWindow,XQueryTree, XRaiseWindow, XReparentWindow,XResize-Window, XRestackWindows.
XSetWindowColormap
Xlib - Window Attributes-
Name
XSetWindowColormap — set the colormap attribute for a window.
Synopsis
XSetWindowColormap( display, w r cmap) Display * display; Window w; Colormap cmap;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window for which you want to set the colormap.
cmap Specifies the colormap.
Description
XSetWindowColormap sets the colormap attribute of the specified window. The color-map need not be installed to be set as an attribute, cmap will be used to translate pixel values drawn into this window when cmap is installed in the hardware, which will be taken care of by the window manager.
In Release 3, applications must install their own colormaps if they cannot use the default color-map. In Release 4, they should never do so.
The colormap must have the same visual as the window.
Errors
BadColormap
BadMatch
BadWindow
Related Commands
XChangeWindowAttributes,XGetGeometry, XGetWindowAttributes,XSet-WindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XSetWMColormapWindows.
Xlib Reference Manual
Name
XSetWMHintS — set a window manager hints property.
Synopsis
XSetWMHintS (display, w, wmhints) Display * display; Window w; XWMHints * wmhints;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
w Specifies the ID for which window manager hints are to be set.
wmhints Specifies a pointer to the window manager hints.
Description
XSetWMHintS sets the window manager hints that include icon information and location, the initial state of the window, and whether the application relies on the window manager to get keyboard input.
This function is unnecessary in Release 4 if you call XSetWMProperties.
See Volume One, Chapter 10, Interclient Communication, for a description of each XWMHints structure member.
Structures
typedef struct {
long flags; /* marks defined fields in structure */
Bool input; /* does application need window manager for
* keyboard input */
int initial_state; /* see below */
Pixmap icon_pixmap; /* pixmap to be used as icon */
Window icon_window; /* window to be used as icon */
int icon_x, icon_y; /* initial position of icon */
Pixmap icon_mask; /* icon mask bitmap */
XID window_group; /* ID of related window group */
/* this structure may be extended in the future */ } XWMHints;
/* definitions for the flags field: */ #define InputHint (1L « 0) #define StateHint (1L « 1) #define IconPixmapHint (1L « 2) fdefine IconWindowHint (1L « 3) #define IconPositionHint (1L « 4) tdefine IconMaskHint (1L « 5) #define WindowGroupHint (1L « 6)
#define AllHints (InputHint|StateHint|IconPixmapHint|IconWindowHint| \ IconPositionHintIIconMaskHintIWindowGroupHint)
Xlib Reference Manual 499
XSetWMHints
(continued)
Xlib - Window Manager Hints
/* definitions for the initial state flag: */
#define DontCareState 0
#define NormalState 1
#define ZoomState 2
#define IconicState 3
#define InactiveState 4
/* don't know or care */
/* most applications want to start this way /* application wants to start zoomed */ /* application wants to start as an icon */ /* application believes it is seldom used; some wm's may put it on inactive menu */
Errors
BadAlloc BadWindow
Related Commands
XAllocWMHints,XFetchName, XGetClassHint, XGetlconName, XGetlcon-Sizes,XGetNormalHints, XGetSizeHints, XGetTransientForHint,XGet-WMHints, XGetZoomHints, XSetClassHint, XSetCommand. XSetlconName, XSetlconSizes,XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetZoomHints,XStoreName, XSetWMProperties.
500
Xlib Reference Manual
-Mb - Window Manager H,n,s ' XSetZOOITlHintS
Name
XSetZoomHints — set the size hints property of a zoomed window.
Synopsis
XSetZoomHints ( display, w, zhints) Display * display; Window w; XSizeHints * zhints;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window for which zoom hints are to be set.
zhints Specifies a pointer to the zoom hints.
Description
XSetZoomHints is no longer used as of Release 3.
XSetZoomHints sets the XA_WM_ZOOM_HINTS property for an application's top-level win dow in its zoomed state. Many window managers think of windows in three states: iconified, normal, or zoomed, corresponding to small, medium, and large. Applications use XSetZoom Hints to inform the window manager of the size or position desirable for the zoomed window.
In addition, an application wanting to move or resize its zoomed window should call XSet ZoomHints specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead.
To set size hints, an application must assign values to the appropriate elements in the hints structure, and set the flags field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below.
For more information on using hints, see Volume One, Chapter WJnterclient Communication. Structures
typedef struct {
long flags; /* marks defined fields in structure */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
/* new fields in R4 */ } XSizeHints;
XSetZoomHints (continued) Xlib - Window Manager Hints
/* flags argument in size hints */
tdefine USPosition (IL « 0) /* user specified x, y */
#define USSize (IL « 1) /* user specified width, height */
#define PPosition (IL « 2) /* program specified position */
#define PSize (IL « 3) /* program specified size */
#define PMinSize (IL « 4) /* program specified minimum size */
#define PMaxSize (IL « 5) /* program specified maximum size */
#define PResizelnc (IL « 6) /* program specified resize increments */
#define PAspect (IL « 7) /* program specified min/max aspect ratios */ #define PAHHints (PPosition|PSize|PMinSize|PMaxSize|PResizelnc|PAspect)
Errors
BadAlloc BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName, XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-Hints, XSetClassHint, XSetCoinmand, XSetlconName, XSetlconSizes, XSet-NormalHints,XSetSizeHints, XSetTransientForHint, XSetWMHints, XStoreName.
Xlib Reference Manual
f XShrinkRegion
— Xlib - Regions '
Name
XShrinkRegion — reduce or expand the size of a region.
Synopsis
XShrinkRegion (r, dx, dy) Region r; int dx, dy;
Arguments
r Specifies the region.
dx Specify the amounts by which you want to shrink or expand the specified
dy region. Positive values shrink the region while negative values expand the
region.
Description
XShrinkRegion changes the width and/or height of the specified region. Positive values shrink the region; negative values expand the region. It is legal to expand the region in one dimension at the same time as shrinking it in the other dimension. The offset of the region is changed to keep the center of the resized region near its original position.
The exact amount of shrinkage for a given value for dx or dy is not specified by Xlib.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion,XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion,XOffsetRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion, XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.
v Xlib - Cut Buffers—
Name
XStoreBuffer — store data in a cut buffer.
Synopsis
XStoreBuffer( display, bytes, nbytes, buffer) Display * display; char bytes[ ]; int nbytes; int buffer;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
bytes Specifies the string of bytes you want stored. The byte string is not necessarily
ASCII or null-terminated.
nbytes Specifies the number of bytes in the string.
buffer Specifies the cut buffer in which to store the byte string. Must be in the range 0-7.
Description
XStoreBuffer stores the specified data into any one of the eight cut buffers. All eight buf fers must be stored into before they can be circulated with XRotateBuf f ers. The cut buf fers are numbered 0 through 7. Use XFetchBuf f er to recover data from any cut buffer.
Note that selections are the preferred method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu nication.
Errors
BadAlloc BadAtom
Related Commands
XFetchBuffer,XFetchBytes, XRotateBuffers,XStoreBytes.
504 Xlib Reference Manual
f~ XStoreBytes
—Xlib - Cut Buffers '
Name
XStoreBytes — store data in cut buffer 0.
Synopsis
XStoreBytes(display, bytes, nbytes) Display * display; char bytes[] ; int nbytes;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
bytes Specifies the string of bytes to store. The byte string is not necessarily ASCII or
null-terminated.
nbytes Specifies the number of bytes to store.
Description
XStoreBytes stores data in cut buffer 0, usually for reading by another client that already knows the meaning of the contents. Note that the cut buffer's contents need not be text, so null bytes are not special.
The cut buffer's contents may be retrieved later by any client calling XFetchBytes.
Use XStoreBuffer to store data in buffers 1-7. Note that selections are the preferred method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Tech niques. For more information on selections, see Volume One, Chapter 10, Inter client Commu nication.
Errors
BadAlloc
Related Commands
XFetchBuffer,XFetchBytes,XRotateBuffers,XStoreBuffer.
Name
XStoreColor — set or change the RGB values of a read/write colormap entry to the closest pos sible hardware color.
Synopsis
XStoreColor( display, cmap, colorcell_def) Display *display; Colormap cmap; XColor *colorcell_def;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
cmap Specifies the colormap.
col orcell_def Specifies a pixel value and the desired RGB values.
Description
XStoreColor changes the RGB values of a colormap entry specified by col orcell_def.pixel to the closest values possible on the hardware. This pixel value must be a read/write cell and a valid index into cmap. XStoreColor changes the red, green, and/or blue color components in the cell according to the colorcell_def .flags member, which you set by ORing the constants DoRed, DoGreen, and/or DoBlue.
If the colormap is an installed map for its screen, the changes are visible immediately. For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad; } XColor;
Errors
BadAccess A specified pixel is unallocated or read-only.
BadColormap
BadValue pixel not valid index into cmap.
Related Commands
BlackPixel,WhitePixel,XAllocColor, XAllocColorCells,XAllocColor-Planes,XAllocNamedColor,XFreeColors, XLookupColor, XParseColor, XQueryColor,XQueryColors,XStoreColors, XStoreNamedColor.
506 Xlib Reference Manual
—Xlib-Color Cells-
J XStoreColors
Name
XStoreColors — set or change the RGB values of read/write colorcells to the closest possible hardware colors.
Synopsis
XStoreColors( display, cmap, colorcell_defs, ncolors) Display * display; Colormap cmap;
XColor colorcell_defs[ncolors]; int ncolors;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
cmap Specifies the colormap.
colorcell_defs
Specifies an array of color definition structures.
ncolors Specifies the number of XColor structures in colorcell_defs.
Description
XStoreColors changes the RGB values of each colormap entry specified by color-cell_defs[] .pixel to the closest possible hardware colors. Each pixel value must be a read/write cell and a valid index into cmap. XStoreColors changes the red, green, and/or blue color components in each cell according to the colorcell_defs [] .flags member, which you set by ORing the constants DoRed, DoGreen, and/or DoBlue. The specified pix els are changed if they are writable by any client, even if one or more pixels generates an error.
If the colormap is an installed map for its screen, the changes are visible immediately. For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad; } XColor;
Errors
BadAcce s s A specified pixel is unallocated or read-only.
BadColormap
BadValue A specified pixel is not a valid entry into cmap.
Related Commands
BlackPixel,WhitePixel,XAllocColor, XAllocColorCells,XAllocColor-Planes,XAllocNamedColor,XFreeColors, XLookupColor, XParseColor, XQueryColor,XQueryColors, XStoreColor, XStoreNamedColor.
Name
XStoreName — assign a name to a window for the window manager.
Synopsis
XStoreName ( display, w r window_name) Display *display; Window w; char *window_name ;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window to which you want to assign a name.
window_name Specifies the name of the window. The name should be a null-terminated string. This name is returned by any subsequent call to XFetchName.
Description
XStoreName is superceded in Release 4 by XSetWMName.
XStoreName sets the XA_WM_NAME property, which should be used by the application to com municate the following information to the window manager, according to current conventions:
To permit the user to identify one of a number of instances of the same client. To provide the user with noncritical state information. Clients can assume that at least the beginning of this string is visible to the user.
The XA_WM_CLASS property, on the other hand, has two members which should be used to iden tify the application's instance and class name, for the lookup of resources. See XSetClass-Hint for details.
For more information, see Volume One, Chapter 10, Inter-client Communication.
Errors
BadAlloc BadWindow
Related Commands
XFetchName,XGetClassHint,XGetlconName, XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom-Hints,XSetClassHint,XSetCommand,XSetlconName,XSetlconSizes,XSet-NormalHints,XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet-ZoomHints.
Xlib Reference Manual
Name
XStoreNamedColor — set RGB values of a read/write colorcell by color name.
Synopsis
XStoreNamedColor(display, cmap, colorname, pixel, flags) Display *display, Colormap cmap; char * colorname; unsigned long pixel; int flags;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
cmap Specifies the colormap.
colorname Specifies the color name string (for example, "red"). This cannot be in hex for mat (as used in XParseColor). Upper or lower case is not important. The string should be in ISO LATIN-1 encoding, which means that the first 128 char acter codes are ASCII, and the second 128 character codes are for special char acters needed in western languages other than English.
pixel Specifies the entry in the colormap to store color in.
flags Specifies which red, green, and blue indexes are set.
Description
XStoreNamedColor looks up the named color in the database, with respect to the screen associated with cmap, then stores the result in the read/write colorcell of cmap specified by pixel. Upper or lower case in name does not matter. The flags argument, a bitwise OR of the constants DoRed, DoGreen, and DoBlue, determines which subfields within the pixel value in the cell are written.
For more information, see Volume One, Chapter 7, Color.
Errors
BadAccess pixel is unallocated or read-only.
BadColormap
BadName col orname is not in server's color database.
BadValue pixel is not a valid index into cmap.
Related Commands
DefaultColormap,DisplayCells, XCopyColormapAndFree,XCreate-Colormap,XFreeColormap, XGetStandardColormap, XInstallColormap, XListInstalledColormaps,XSetStandardColormap,XSetWindowColormap, XUninstallColormap.
Xlib Reference Manual 509
XStringListToTextProperty \ XMb . wlndowManager Hints _
Name
XStringListToTextProperty — set the specified list of strings to an XTextProperty struc ture.
Synopsis
Status XStringListToTextProperty(list, count, text^prop) char **list; int count; XTextProperty *text_prop; /* RETURN */
Arguments
list Specifies a list of null-terminated character strings.
count Specifies the number of strings.
text_jDrop Returns the XTextProperty structure.
Availability
Release 4 and later.
Description
XStringListToTextProperty fills the specified XTextProperty structure so that it represents a property of type STRING (format 8) with a value representing the concatenation of the specified list of null-separated character strings. An extra byte containing NULL (which is not included in the nit ems member) is stored at the end of the value field of text_prop. If insufficient memory is available for the new value string, XStringListToText Property does not set any fields in the XTextProperty structure and returns a zero status. Otherwise, it returns a non-zero status. To free the storage for the value field, use XFree.
For more information, see Volume One, Chapter IQJnterclient Communication. Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
Related Commands
XSetTextProperty, XGetTextProperty, XTextPropertyToStringList, XFreeStringList.
-«* - Keyboard / XStringToKeysym
Name
XStringToKeysym — convert a keysym name string to a keysym.
Synopsis
KeySym XStringToKeysym ( string) char *string;
Arguments
string Specifies the name of the keysym that is to be converted.
Description
XStringToKeysym translates the character string version of a keysym name ("Shift") to the matching keysym which is a constant (XK_Shift). Valid keysym names are listed in <Xll/keysymdef.h>. If the specified string does not match a valid keysym, XString ToKeysym returns NoSymbol.
This string is not the string returned in the buffer argument of XLookupSt ring, which can be set with XRebindKeysym. If that string is used, XStringToKeysym will return No-Symbol except by coincidence.
In Release 4, XStringToKeysym can return keysyms that are not defined by the Xlib stan dard. Note that the set of keysyms that are available in this manner and the mechanisms by which Xlib obtains them is implementation dependent. (In the MIT sample implementation, the resource file lusrlliblXHIXKeysymDB is used starting in Release 4. The keysym name is used as the resource name, and the resource value is the keysym value in uppercase hexade cimal.)
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Related Commands
XChangeKeyboardMapping, XDeleteModifiermapEntry,XFreeModifiermap, XGetKeyboardMapping, XGetModifierMapping, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString,XNewModifierMap,XQueryKeymap, XRebindKeysym, XRefreshKeyboardMapping, XSetModifierMapping.
XSublmage \ X(|b _ lmages _
Name
XSublmage — create a subimage from part of an image.
Synopsis
Xlmage *XSubImage (ximage, x, y, subimage_width, subimage_height) Xlmage * ximage; int x;y; unsigned int subimage_width; subimage_height ;
Arguments
ximage Specifies a pointer to the image.
x Specify the x and y coordinates in the existing image where the subimage will be
y extracted.
s ubima ge_wi dt h subimage_height
Specify the width and height (in pixels) of the new subimage.
Description
XSublmage creates a new image that is a subsection of an existing one. It allocates the mem ory necessary for the new Xlmage structure and returns a pointer to the new image. The data is copied from the source image, and the rectangle defined by x, y, subimage_width, and subimage_height must by contained in the image.
XSublmage extracts a subimage from an image, while XGet Sub Image extracts an image from a drawable.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text. Related Commands
ImageByteOrder, XAddPixel, XCreatelmage, XDestroyImage, XGetlmage, XGetPixel, XGetSubImage,XPutImage, XPutPixel.
J XSubtractRegion
—Xlib - Regions '
Name
XSubtractRegion — subtract one region from another.
Synopsis
XSubtractRegion (sra, srb, dr) Region sra, srb; Region dr; /* RETURN */
Arguments
sra Specify the two regions in which you want to perform the computation.
srb
dr Returns the result of the computation.
Description
XSubtractRegion calculates the difference between the two regions specified (sra - srb) and puts the result in dr.
This function returns a region which contains all parts of sra that are not also in srb. For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion,XOffsetRegion,XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion, XShrinkRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.
XSync
Xlib- Output Buffer-
Name
XSync — flush the request buffer and wait for all events and errors to be processed by the server.
Synopsis
XSync(display, discard) Display * display; int discard;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
discard Specifies whether XSync discards all events on the input queue. This argu
ment is either True or False.
Description
XSync flushes the request buffer, then waits until all events and errors resulting from previous calls have been received and processed by the X server. Events are placed on the input queue. The client's XError routine is called once for each error received.
If discard is True, XSync discards all events on the input queue (including those events that were on the queue before XSync was called).
XSync is sometimes used with window manipulation functions (by the window manager) to wait for all resulting exposure events. Very few clients need to use this function.
Related Commands
XFlush.
J XSynchronize
—Xlib - Input Handling '
Name
XSynchronize — enable or disable synchronization for debugging.
Synopsis
int (*XSynchronize( display, onoff)) () Display * display ; Bool onoff;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
onoff Specifies whether to enable or disable synchronization. You can pass False
(normal asynchronous mode) or True (enable synchronization for debug ging).
Description
XSynchronize turns on or off synchronous mode for debugging. If onoff is True, it turns on synchronous behavior; False resets the state to normal mode.
When events are synchronized, they are reported as they occur instead of at some later time, but server performance is many times slower. This can be useful for debugging complex event handling routines. Under UNIX, the same result can be achieved without hardcoding by setting the global variable _xdebug to True from within a debugger.
XSynchronize returns the previous after function.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-Event,XCheckTypedWindowEvent,XCheckWindowEvent,XEventsQueued, XGetlnputFocus,XGetMotionEvents,XlfEvent, XMaskEvent,XNextEvent, XPeekEvent,XPeeklfEvent,XPending, XPutBackEvent,XSelectlnput, XSendEvent, XSetlnputFocus,XWindowEvent.
XTextExtents \ Xlib _ Text _
Name
XTextExtents — get string and font metrics locally.
Synopsis
XTextExtents (font_struct, string, nchars, direction,
ascent, descent, overall) XFontStruct *font_struct; char *string; int nchars;
int * direction; /* RETURN */
int * ascent, *descent; /* RETURN */
XCharStruct * overall; /* RETURN */
Arguments
f ont_struct Specifies a connection to an XFontStruct structure.
string Specifies the character string for which metrics are to be returned.
nchars Specifies the number of characters in the character string.
direction Returns the value of the direction element of the XFontStruct. Either FontRightToLeftor FontLeftToRight.
ascent Returns the font ascent element of the XFontStruct. This is the overall
maximum ascent for the font
descent Returns the font descent element of the XFontStruct. This is the overall
maximum descent for the 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
XTextExtents returns the dimensions in pixels that specify the bounding box of the speci fied string of characters in the named font, and the maximum ascent and descent for the entire font This function performs the size computation locally and, thereby, avoids the roundtrip overhead of XQueryTextExtents, but it requires a filled XFontStruct.
ascent and descent return information about the font, while overall returns information about the given string. The returned ascent and descent should usually be used to calcu late the line spacing, while the width, rbearing, and Ibearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
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
Xlib - Text
(continued)
XTextExtents
is the Ibearing of the character in the string with the smallest Ibearing plus the width of all the characters up to but not including that character. The overall. rbearing is the rbearing of the character in the string with the largest rbearing plus the width of all the characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /*
Font fid; /*
unsigned direction; /* unsigned min_char_or_byte2; /* unsigned max_char_or_byte2;/*
unsigned min bytel; /*
unsigned max_bytel; /*
Bool all_chars_exist; /*
unsigned default char; /*
int n_properties; /*
XFontProp *properties; /*
XCharStruct min bounds; /*
XCharStruct max_bounds; /*
XCharStruct *per_char; /*
int ascent; /*
int descent; /*
} XFontStruct;
hook, for extension to hang data */
font ID for this font */
hint about direction the font is painted */
first character */
last character */
first row that exists */
last row that exists */
flag if all characters have nonzero size*/
char to print for undefined character */
how many properties there are */
pointer to array of additional properties*/
minimum bounds over all existing char*/
minimum bounds over all existing char*/
first_char to last_char information */
logical extent above baseline for spacing */
logical descent below baseline for spacing */
typedef struct {
short Ibearing;
short rbearing;
short width;
short ascent;
short descent;
unsigned short attributes; } XCharStruct;
/* origin to left edge of character */
/* origin to right edge of character */
/* advance to next char's origin */
/* baseline to top edge of character */
/* baseline to bottom edge of character
/* per char flags (not predefined) */
*/
Related Commands
XDrawImageString,XDrawImageStringl6,XDrawString,XDrawStringlG, XDrawText,XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl6, XTextExtentsi6,XTextWidth, XTextWidthl6.
Xlib Reference Manual
XTextExtentsI 6 \ Xllb _ Text _
Name
XTextExtentsl6 — get string and font metrics of a 16-bit character string, locally.
Synopsis
XTextExtentsI6 (font_struct, string, nchars, direction,
ascent, descent, overall) XFontStruct *font_struct; XChar2b *string; int nchars;
int * direction; /* RETURN */
int * ascent, * descent; /* RETURN */
XCharStruct * overall; /* RETURN */
Arguments
font_struct Specifies a connection to an XFontStruct structure.
string Specifies the character string made up of XChar2 6 structures.
nchars Specifies the number of characters in the character string.
direction Returns the value of the direction element of the XFontStruct. Font-RightToLeft of FontLeftToRight.
ascent Returns the font ascent element of the XFontStruct. This is the overall
maximum ascent for the font.
descent Returns the font descent element of the XFontStruct. This is the overall
maximum descent for the 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
XTextExtentsI6 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 performs the size computation locally and, thereby, avoids the roundtrip overhead of XQueryTextExtentsl 6, but it requires a filled XFontStruct.
ascent and descent return information about the font, while overall returns information about the given string. The returned ascent and descent should usually be used to calcu late the line spacing, while the width, rbearing, and Ibearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
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
Xlib-Text
(continued)
XTextExtents16
is the Ibearing of the character in the string with the smallest Ibearing plus the width of all the characters up to but not including that character. The overall. rbearing is the rbearing of the character in the string with the largest rbearing plus the width of all the characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short Ibearing;
short rbearing;
short width;
short ascent;
short descent;
unsigned short attributes; } XCharStruct;
typedef struct {
XExtData *ext_data;
Font fid;
unsigned direction;
unsigned min_char_or_byte2;
unsigned max_char_or_byte2;
unsigned min_bytel;
unsigned max_bytel;
Bool all_chars_exist;
unsigned default char;
int n_properties;
XFontProp *properties;
XCharStruct min_bounds;
XCharStruct max_bounds;
XCharStruct *per_char;
int ascent;
int descent; } XFontStruct;
typedef struct {
unsigned char bytel; unsigned char byte2;
} XChar2b;
/* origin to left edge of character */
/* origin to right edge of character */
/* advance to next char's origin */
/* baseline to top edge of character */
/* baseline to bottom edge of character
/* per char flags (not predefined) */
/* hook for extension to hang data */
/* font ID for this font */
/* hint about direction the font is painted */
/* first character */
/* last character */
/* first row that exists */
/* last row that exists */
/* flag if all characters have nonzero size*/
/* char to print for undefined character */
/* how many properties there are */
/* pointer to array of additional properties*/
/* minimum bounds over all existing char*/
/* minimum bounds over all existing char*/
/* first_char to last_char information */
/* logical extent above baseline for spacing */
/* logical descent below baseline for spacing */
/* normal 16 bit characters are two bytes */
Related Commands
XDrawImageString,XDrawImageStringl6,XDrawString, XDrawStringlS, XDrawText,XDrawText16, XQueryTextExtents, XQueryTextExtentsi 6, XTextExtents,XTextWidth,XTextWidthl6.
Xlib Reference Manual
XTextPropertyToStringList \ X|ib . Wlndow Manager Hints _
Name
XTextPropertyToStringList — obtain a list of strings from a specified XTextProperty struc ture.
Synopsis
Status XTextPropertyToStringList (text_prop f list, count) XTextProperty *text_prop; char ***list; /* RETURN */ int * count; /* RETURN */
Arguments
text_prop Specifies the XTextProperty structure to be used.
list Returns a list of null-terminated character strings.
count Returns the number of strings.
Availability
Release 4 and later.
Description
XTextPropertyToStringList returns a list of strings representing the null-separated elements of the specified XTextProperty structure. The data in text_prop must be of type STRING and format 8. Multiple elements of the property (for example, the strings in a dis joint text selection) are separated by a NULL (encoding 0). The contents of the property are not null-terminated. If insufficient memory is available for the list and its elements, XText PropertyToStringList sets no return values and returns a zero status. Otherwise, it returns a non-zero status. To free the storage for the list and its contents, use XFreeString-List.
For more information, see Volume One, Chapter 10, Inter-client Communication. Structures
typedef struct {
unsigned char *value; /* same as Property routines */
Atom encoding; /* prop type */
int format; /* prop data format: 8, 16, or 32 */
unsigned long nitems; /* number of data items in value */ } XTextProperty;
Related Commands
XFreeStringList. XGetTextProperty, XSetTextProperty, XStringListTo-TextProperty.
Xlib Reference Manual
f XTextWidth
—Xlib - Text '
Name
XTextWidth — get the width in pixels of an 8-bit character string, locally.
Synopsis
int XTextWidth (font_struct, string, count) XFontStruct *font_struct; char *string; int count;
Arguments
font_struct Specifies the font description structure of the font in which you want to draw the string.
string Specifies the character string whose width is to be returned.
count Specifies the character count in s tring.
Description
XTextWidth returns the width in pixels of the specified string using the specified font This is the sum of the XCharSt ruct. width for each character in the string. This is also equiva lent to the value of overall, width returned by XQueryTextExtents or XText-Extents. The calculation is done assuming 8-bit font indexing.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2;/* first character */
unsigned max_char_or_byte2;/* last character */
unsigned min_bytel; /* first row that exists */
unsigned max_bytel; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp ^properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XDrawImageString,XDrawImageStringl6,XDrawString, XDrawStringlS, XDrawText,XDrawTextl6, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents,XTextExtentsl6,XTextWidthl6.
XTextWidth16 \ XHb . Text _
Name
XTextWidthl6 — get the width in pixels of a 16-bit character string, locally.
Synopsis
int XTextWidthl6 (font_struct, string, count) XFontStruct *font_struct ; XChar2b *string; int count;
Arguments
font_struct Specifies the font description structure of the font in which you want to draw the string.
string Specifies a character string made up of XChar2b structures,
count Specifies the character count in s t ri n g.
Description
XTextwidthl6 returns the width in pixels of the specified string using the specified font. This is the sum of the XCharStruct .width for each character in the string. This is also equivalent to the value of overall. width returned by XQueryTextExtentsl6 or XTextExtentsl6.
The calculation is done assuming 16-bit font indexing.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_bytel; /* first row that exists */
unsigned max_bytel; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlS,
XDrawText,XDrawTextl6,XQueryTextExtents,XQueryTextExtentsl6,
XTextExtents,XTextExtentsl6,XTextWidth.
j XTranslateCoordinates
—Xlib - Standard Geometry '
Name
XTranslateCoordinates — change the coordinate system from one window to another.
Synopsis
Bool XTranslateCoordinates(display, src_w, frame_w, src_x f
src_y, new_x, new_y, child) Display * display; Window src_w r frame_w; int src_x f src_y;
int *new_x, *nevr_y; /* RETURN */
Window * chiId; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
src_w Specifies the ID of the source window.
frame_w Specifies the ID of the frame of reference window.
src_x Specify the x and y coordinates within the source window.
src_y
new_x Return the translated x and y coordinates within the frame of reference window.
new_y
child If the point is contained in a mapped child of the destination window, then that
child ID is returned in child.
Description
XTranslateCoordinates translates coordinates from the frame of reference of one win dow to another.
XTranslateCoordinates returns False and *new_x and *new_y are set to zero if src_w and frame_w are on different screens. In addition, if the coordinates are contained in a mapped child of frame_w, then that child is returned in the child argument When src_w and frame_y are on the same screen, XTranslateCoordinates returns True, sets *new_x and *new_y to the location of the point relative to f~rame_w, and sets child to None.
This should be avoided in most applications since it requires a roundtrip request to the server. Most applications benefit from the window-based coordinate system anyway and don't need global coordinates. Window managers often need to perform a coordinate transformation from the coordinate space of one window to another, or unambiguously determine which subwindow a coordinate lies in. XTranslateCoordinates fulfills this need, while avoiding any race conditions by asking the server to perform this operation.
Errors
BadWindow
Related Commands
XGeometry,XParseGeometry.
XUndefineCursor \ Vl
v Xhb - Cursors-Name
XUndefineCursor — disassociate a cursor from a window.
Synopsis
XUndefineCursor (display, w) Display * display; Window w;
Arguments
di spl ay Specifies a connection to an X server; returned from XOpenDi spl ay.
w Specifies the ID of the window whose cursor is to be undefined.
Description
XUndefineCursor sets the cursor attribute for a window to its parent's cursor, undoing the effect of a previous XDef ineCursor for this window. On the root window the default cursor is restored.
Errors
BadWindow
Related Commands
XCreateFontCursor,XCreateGlyphCursor, XCreatePixmapCursor,XDefine Cursor, XFreeCursor,XQueryBestCursor, XQueryBestSize,XRecolor-Cursor.
Xlib Reference Manual
J XUngrabButton
—Xlib - Grabbing '
Name
XUngrabButton — release a button from a passive grab.
Synopsis
XUngrabButton (display, button, modifiers, w) Display *display; unsigned int button; unsigned int modifiers; Window w;
Arguments
display Specifies a connection to an X server, returned from XOpenDisplay.
button Specifies the mouse button to be released from grab. Specify Buttonl,
Button2, Buttons, Button4, Buttons, or the constant AnyButton, which is equivalent to issuing the ungrab request for all possible buttons.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. AnyModif ier is equivalent to issuing the ungrab button request for all pos sible modifier combinations (including no modifiers).
w Specifies the ID of the window you want to release the button grab.
Description
XUngrabButton cancels the passive grab on a button/key combination on the specified win dow if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issu ing the ungrab request for all possible modifier combinations (including the combination of no modifiers). A button of AnyButton is equivalent to issuing the request for all possible but tons. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Errors
BadWindow
BadValue Invalid button or modifiers mask.
Related Commands
XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabPointer,XGrabServer,XUngrabKey, XUngrabKeyboard, XUngrab-Pointer, XUngrabServer.
XUngrabKey \
•Xlib-Grabbing —
Name
XUngrabKey — release a key from a passive grab.
Synopsis
XUngrabKey(display, keycode, modifiers, w) Display *display; int keycode; unsigned int modifiers; Window w;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
keycode Specifies the keycode. This keycode maps to the specific key you want to
ungrab. Pass either a keycode or AnyKey.
modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. AnyModif ier is equivalent to issuing the ungrab key request for all pos sible modifier combinations (including no modifiers).
w Specifies the ID of the window for which you want to ungrab the specified
keys.
Description
XUngrabKey cancels the passive grab on the key combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A keycode of AnyKey is equivalent to issuing the request for all possible nonmodifier key codes. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadWindow
BadValue Invalid keycode or modifiers mask.
Related Commands
XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabPointer,XGrabServer,XUngrabButton, XUngrabKeyboard,XUngrab-Pointer,XUngrabServer.
-x,,b-Grabb,n g / XUngrabKeyboard
Name
XUngrabKeyboard — release the keyboard from an active grab.
Synopsis
XUngrabKeyboard(display, time) Display * display; Time time;
Arguments
display Specifies a connection to an X server; returned from xopenDisplay.
time Specifies the time. Pass either a timestamp, expressed in milliseconds, or the
constant CurrentTime. If this time is earlier than the last-keyboard-grab time or later than the current server time, the keyboard will not be ungrabbed.
Description
XUngrabKeyboard releases any active grab on the keyboard by this client. It executes as follows:
Releases the keyboard and any queued events if this client has it actively grabbed from either XGrabKeyboard or XGrabKey.
Does not release the keyboard and any queued events if time is earlier than the last-key board-grab time or is later than the current X server time.
Generates Focus In and FocusOut events.
The X server automatically performs an UngrabKeyboard if the grab_window (argument to XGrabkey and XGrabkeyboard) that becomes unviewable.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Related Commands
XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabPointer,XGrabServer,XUngrabButton,XUngrabKey,XUngrabPointer, XUngrabServer.
XUngrabPointer V.
-Xlib-Pointer-
Name
XUngrabPointer — release the pointer from an active grab.
Synopsis
XUngrabPointer(display, time) Display *display; Time time;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
time Specifies the time when the grab should take place. Pass either a timestamp,
expressed in milliseconds, or the constant CurrentTime. If this time is earlier than the last-pointer-grab time or later than current server time, the pointer will not be grabbed.
Description
XUngrabPointer releases an active grab on the pointer by the calling client. It executes as follows:
• Releases the pointer and any queued events, if this client has actively grabbed the pointer from XGrabPointer, XGrabButton, or from a normal button press.
Does not release the pointer if the specified time is earlier than the last-pointer-grab time or is later than the current X server time.
Generates EnterNotify and LeaveNotif y events.
The X server performs an XUngrabPointer automatically if the event_window or conf±ne_to window (arguments of XGrabButton and XGrabPointer) becomes not viewable, or if the conf ine_to window is moved, completely outside the root window.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Related Commands
XChangeActivePointerGrab,XChangePointerControl, XGetPointer-Control,XGetPointerMapping,XGrabPointer, XQueryPointer,XSet-PointerMapping,XWarpPointer.
Xlib Reference Manual
/
XUngrabServer
Name
XUngrabServer — release the server from grab.
Synopsis
XUngrabServer (display) Display * display;
Arguments
display Specifies a connection to an X server; returned from XOpenDi splay.
Description
XUngrabServer releases the grabbed server, and begins execution of all the requests queued during the grab. XUngrabServer is called automatically when a client closes its connection.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer. Related Commands
XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrab-Keyboard, XUngrabPointer.
XUninstaliColormap \
•Xlib-Colormaps—
Name
XUninstaliColormap — uninstall a colormap; install default if not already installed.
Synopsis
XUninstaliColormap (display, c/nap) Display * display; Colormap c/nap;
Arguments
di splay Specifies a connection to an X server; returned from XOpenDi splay.
c/nap Specifies the colormap to be uninstalled.
Description
If c/nap is an installed map for its screen, it is uninstalled. If the screen's default colormap is not installed, it is installed.
If c/nap is an installed map, a ColormapNotify event is generated on every window having this colormap as an attribute. If a colormap is installed as a result of the uninstall, a ColormapNotify event is generated on every window having that colormap as an attribute.
At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the required list. The length of the required list is at most the min_maps specified for each screen in the Display structure. When a colormap is installed with XInstallColormap it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at min_maps. When a colormap is uninstalled with XUninstali Colormap and it is in the required list, it is removed from the list. No other actions by the server or the client change the required list. It is important to realize that on all but high-per formance workstations, min_maps is likely to be one.
For more information on installing and uninstalling colormaps, see Volume One, Chapter 7, Color.
Errors
BadColormap
Related Commands
Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate-Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XListlnstalledColormaps.XSetStandardColormap, XSetWindowColormap.
Xlib Reference Manual
/
XUnionRectWithRegion
Name
XUnionRectWithRegion — add a rectangle to a region.
Synopsis
XUnionRectWithRegion (rectangle, src_region, dest_region) XRectangle * rectangle; Region src_regi on ; Region dest_region;
Arguments
rect angl e Specifies the rectangle to add to the region.
src_regi on Specifies the source region to be used.
dest_region Specifies the resulting region. May be the same as src_region.
Description
XUnionRectWithRegion computes the destination region from a union of the specified rectangle and the specified source region. The source and destination regions may be the same.
One common application of this function is to simplify the combining of the rectangles speci fied in contiguous Expose events into a clip_mask in the GC, thus restricting the redrawn areas to the exposed rectangles. Use XUnionRectWithRegion to combine the rectangle in each Expose event into a region, then call XSetRegion. XSetRegion sets the clip_mask in a GC to the region. In this case, src_region and dest_region would be the same region.
If src_region and dest_region are not the same region, src_region is copied to dest_region before the rectangle is added to dest_region.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text. Structures
typedef struct {
short x, y;
unsigned short width, height; } XRectangle;
Region is a pointer to an opaque data type. Related Commands
XClipBox, XDestroyRegion, XEmpty Region, XEqualRegion, Xlntersect-Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion.
XUnionRegion \
•Xlib- Regions-
Name
XUnionRegion — compute the union of two regions.
Synopsis
XUnionRegion (sra, srb, dr) Region sra, srb; Region dr;
Arguments
sra Specify the two regions in which you want to perform the computation,
srb
dr Returns the result of the computation.
Description
XUnionRegion computes the union of two regions and places the result in dr. The resulting region will contain all the area of both the source regions.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnion-RectWithRegion,XXorRegion.
Xlib Reference Manual
XUniqueContext
—Xlib - Context Manager '
Name
XUniqueContext — create a new context ID (not graphics context).
Synopsis
XContext XUniqueContext()
Description
The context manager allows association of arbitrary data with a resource ID. This call creates a unique ID that can be used in subsequent calls to XFindContext, XDeleteContext, and XSaveContext.
For more information on the context manager, see Volume One, Chapter 13, Other Program ming Techniques.
Structures
typedef int XContext;
Related Commands
XDeleteContext,XFindContext, XSaveContext.
XUnloadFont \ Xlib . Fonts _
Name
XUnloadFont — unload a font
Synopsis
XUnloadFont ( display, font ) Display * display; Font font;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
fon t Specifies the ID of the font to be unloaded.
Description
XUnloadFont indicates to the server that this client no longer needs the specified font The font may be unloaded on the X server if this is the last client that needs the font In any case, the font should never again be referenced by this client because Xlib destroys the resource ID.
For more information on loading and unloading fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadFont
Related Commands
XCreateFontCursor,XFreeFont,XFreeFontlnfo, XFreeFontNames,XFree-FontPath,XGetFontPath,XGetFontProperty,XListFonts,XListFontsWith-Info,XLoadFont,XLoadQueryFont,XQueryFont,XSetFont, XSetFontPath.
534
Xlib Reference Manual
J XUnmapSubwindows
—Xlib - Mapping '
Name
XUnmapSubwindows — unmap all subwindows of a given window.
Synopsis
XUnmapSubwindows(display, w) Display * display; Window w;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window whose subwindows are to be unmapped.
Description
XUnmapSubwindows performs an XUnmapWindow on all mapped children of w, in bottom to top stacking order. (It does not unmap subwindows of subwindows.)
XUnmapSubwindows also generates an UnmapNotify event on each subwindow and gen erates exposure events on formerly obscured windows. This is much more efficient than unmapping many subwindows one at a time, since much of the work need only be performed once for all of the subwindows rather than for each subwindow.
For more information on window mapping, see Volume One, Chapter 2, X Concepts. Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XMapWindow, XUnmapWindow.
XUnmapWindow \
•Xlib-Mapping-
Name
XUnmapWindow — unmap a window.
Synopsis
XUnmapWindow (di splay, w) Display * display; Window w;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the window ID.
Description
XUnmapWindow removes w and all its descendants from the screen (but does not unmap the descendents). If w is already unmapped, XUnmapWindow has no effect. Otherwise, w is unmapped and an UnmapNotify event is generated. Normal exposure processing on for merly obscured windows is performed.
Descendants of w will not be visible until w is mapped again. In other words, the subwindows are still mapped, but are not visible because w is unmapped. Unmapping a window will gener ate exposure events on windows that were formerly obscured by w.
For more information on window mapping, see Volume One, Chapter 2, X Concepts.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XMapWindow, XUnmapSubwindows.
536
Xlib Reference Manual
XVisuallDFromVisual
—Xlib - Window Manager Hints-Name
XVisuallDFromVisual — obtain the visual ID from a visual.
Synopsis
VisuallD XVisuallDFromVisual(visual) Visual *visual;
Arguments
visual Specifies the visual type.
Description
XVisuallDFromVisual returns the visual ID for the specified visual. This is needed when filling an xvisuallnf o structure template before calling XGetvisuallnf o. For more information, see Volume One, Chapter 10, Interclient Communication.
Related Commands
XGetvisuallnfo.
Name
XWMGeometry — obtain a window's geometry information.
Synopsis
int XWMGeometry(display, screen, user_geom r def_geom r bwidth,
hints, x, y, width, height, gravity) Display *display; int screen; char *user_geom; char *def_geom; unsigned int bwidth; XSizeHints *hints; int *x, *y; /* RETURN */
int * width, *height; /* RETURN */ int * gravity; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
screen Specifies the screen.
user_geom Specifies the user-specified geometry or NULL.
def_geom Specifies the application's default geometry or NULL.
bwi dth Specifies the border width.
hints Specifies the size hints for the window in its normal state.
x
y Return the x and y offsets.
width
height Return the width and height determined.
gravi ty Returns the window gravity.
Availability
Release 4 and later.
Description
XWMGeometry combines possibly incomplete or nonexistent geometry information (given in the format used by XParseGeometry) specified by the user and by the calling program with complete program-supplied default size hints (usually the ones to be stored in WM_NORMAL_HINTS) and returns the position, size, and gravity (NorthWestGravity, NorthEastGravity, SouthEastGravity or SouthWestGravity) that describe the window. If the base size is not set in the XSizeHints structure, the minimum size is used if set Otherwise, a base size of zero is assumed. If no minimum size is set in the hints structure, the base size is used. A mask (in the form returned by XParseGeometry) that describes
Xlib Reference Manual
Xlib - Window Manager Hints (continued) X WMGeometry
which values came from the user and whether or not the position coordinates are relative to the right and bottom edges is returned (which will have already been accounted for in the x and y values).
Note that invalid user geometry specifications can cause a width or height of zero to be returned. The caller may pass the address of the win_gravity field of the hints argument as the gravity argument
For more information, see Volume One, Chapter 10, Inter-client Communication. Structures
typedef struct {
long flags; /* marks which fields in this structure are
/* defined */
int x, y; /* obsolete for new window mgrs, but clients */ int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct {
int x; /* numerator */
int y; /* denominator */ } min_aspect, max_aspect;
int base_width, base_height; /* added by ICCCM version 1 */ int win_gravity; /* added by ICCCM version 1 */
} XSizeHints
Related Commands
XChangeWindowAttributes,XParseGeometry, XSetWMProperties.
Xlib Reference Manual
Name
XWarpPointer — move the pointer to another point on the screen.
Synopsis
XWarpPointer(display, src_w, dest_w, src_x, src_y,
src_width r src_height, dest_x, dest_y) Display *display; Window src_w, dest_w; int src_x, src_y;
unsigned int src_width, src_height; int dest_x, dest_y;
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
src_w Specifies the ID of the source window. You can also pass None.
dest_w Specifies the ID of the destination window. You can also pass None.
src_x Specify the x and y coordinates within the source window. These are used
src_y with src_width and src_height to determine the rectangle the
pointer must be in order to be moved. They are not the present pointer posi tion. If src_y is None, these coordinates are relative to the root window of src_w.
src_width Specify the width and height in pixels of the source area. Used with src_x src_height and src_y.
dest_x Specify the destination x and y coordinates within the destination window.
dest_y If dest_w is None, these coordinates are relative to the root window of
dest_w.
Description
XWarpPointer moves the pointer suddenly from one point on the screen to another.
If dest_w is a window, XWarpPointer moves the pointer to [dest_x, dest_y] relative to the destination window's origin. If dest_w is None, XWarpPointer moves the pointer according to the offsets [dest_x, dest_y] relative to the current position of the pointer.
If src_window is None, the move is independent of the current cursor position (dest_x and dest_y use global coordinates). If the source window is not None, the move only takes place if the pointer is currently contained in a visible portion of the rectangle of the source window (including its inferiors) specified by src_x, src_y, src_width and src_height. If src_width is zero (0), the pointer must be between src_x and the right edge of the window to be moved. If src_height is zero (0), the pointer must be between src_y and the bottom edge of the window to be moved.
XWarpPointer cannot be used to move the pointer outside the conf ine_to window of an active pointer grab. If this is attempted the pointer will be moved to the point on the border of the conf ine_to window nearest the requested destination.
540 Xlib Reference Manual
Xlib- Pointer (continued) XWarpPointer
XWarpPointer generates events as if the user had (instantaneously) moved the pointer.
This function should not be used unless absolutely necessary, and then only in tightly con trolled, predictable situations. It has the potential to confuse the user.
Errors
BadWindow
Related Commands
XChangeActivePointerGrab,XChangePointerControl,XGetPointer-Control,XGetPointerMapping,XGrabPointer,XQueryPointer,XSet-PointerMapping,XUngrabPointer.
XWindowEvent A XIib _ lnput Ha nd.ing-
Name
XWindowEvent — remove the next event that matches the specified mask and window.
Synopsis
XWindowEvent (display, w, event_mask, rep) Display * display; Window w; long event_mask; XEvent *rep; /* RETURN */
Arguments
display Specifies a connection to an X server; returned from XOpenDisplay.
w Specifies the ID of the window whose next matching event you want.
event_mask Specifies the event mask. See XSelectlnput for a complete list of event masks.
rep Returns the event removed from the input queue.
Description
XWindowEvent removes the next event in the queue which matches both the passed window and the passed mask. The event is copied into an XEvent structure supplied by the caller. Other events in the queue are not discarded. If no such event has been queued, XWindow Event flushes the request buffer and waits until one is received.
Structures
See individual event structures described in Volume One, Chapter 8, Events, and Appendix F, Structure Reference in this volume.
Related Commands
QLength,XAllowEvents,XChecklfEvent, XCheckMaskEvent,XCheckTyped-Event,XCheckTypedWindowEvent, XCheckWindowEvent,XEventsQueued, XGetInputFocus,XGetMotionEvents,XIfEvent, XMaskEvent, XNextEvent, XPeekEvent,XPeeklfEvent,XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnputFocus, XSynchronize.
XIib Reference Manual
J XWithdrawWindow
—Xlib - Window Manager Hints *
Name
XWithdrawWindow — request that a top-level window be withdrawn.
Synopsis
Status XWithdrawWindow (display, w, screen_number) Display *display; Window w; int screen_number;
Arguments
display Specifies a connection to an X server; returned from xopenDi splay.
w Specifies the window.
s creen_number
Specifies the appropriate screen number on the server.
Availability
Release 4 and later.
Description
XWithdrawWindow informs the window manager that the specified window and its icon should be unmapped. It unmaps the specified window and sends a synthetic UnmapNotify event to the root window of the specified screen. Window managers may elect to receive this message and may treat it as a request to change the window's state to withdrawn. When a win dow is in the withdrawn state, neither its normal nor its iconic representation is visible. XWithdrawWindow returns a nonzero status if the UnmapNotify event is successfully sent; otherwise, it returns a zero status.
For more information, see Volume One, Chapter 10, Inter client Communication.
Errors
BadWindow
Related Commands
XlconifyWindow, XReconfigureWindow.
Name
XWriteBitmapFile — write a bitmap to a file.
Synopsis
int XWriteBitmapFile(display, filename, bitmap, width,
height, x_hot, y_hot) Display *display; char * filename; Pixmap bitmap; unsigned int width, height; int x_hot r y_hot;
Arguments
display Specifies a connection to an X server; returned from XQpenDisplay.
filename Specifies the filename to use. The format of the filename is operating system specific.
bi tmap Specifies the bitmap to be written.
wi dth Specify the width and height in pixels of the bitmap to be written.
height
x_hot Specify where to place the hotspot coordinates (or -1,-1 if none present) in
y_hot the file.
Description
XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bitmap file format, shown below.
If the file cannot be opened for writing, XWriteBitmapFile returns BitmapOpen-Failed. If insufficient memory is allocated XWriteBitmapFile returns Bitmap-NoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuccess.
If x_hot and y_hot are not -1, -1, then XWriteBitmapFile writes them out as the hotspot coordinates for the bitmap.
The following is an example of the contents of a bitmap file created. The name used ("gray" in this example) is the portion of filename after the last"/".
#define gray_width 16
tdefine gray_height 16
#define gray_x_hot 8
#define gray_y_hot 8
static char gray_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 on bitmaps, see Volume One, Chapter 6, Drawing Graphics and Text.
544 xiib Reference Manual
Xlib - Pixmaps and Tiles (continued) XWriteBitmapFile
Errors
BadAlloc
BadDrawable
BadMatch The specified width and height did not match dimensions of the specified jbi tmap.
Related Commands
XCreateBitmapFromData.XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile, XReadBitmapFile, XSetTile, XSetWindowBackgroundPixmap, XSetWindow-BorderPixmap.
Xlib Reference Manual
XXorRegion ~\
•Xlib-Regions-
Name
XXorRegion — calculate the difference between the union and intersection of two regions.
Synopsis
XXorRegion (sra, srb, dr) Region sra, srb; Region dr; /* RETURN */
Arguments
sra Specify the two regions on which you want to perform the computation,
srb
dr Returns the result of the computation.
Description
XXorRegion calculates the union minus the intersection of two regions, and places it in dr. Xor is short for "Exclusive OR", meaning that a pixel is included in dr if it is set in either sra or srb but not in both.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
Region is a pointer to an opaque structure type.
Related Commands
XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion,XOffsetRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion,XSetRegion, XShrinkRegion, XSubtractRegion,XUnion-RectWithRegion,XUnionRegion.
Function Group Summary
This quick reference is intended to help you find and use the right function for a particular task. It supplies two lists:
• Listing of Functions by Groups
• Alphabetical Listing of Functions
Both functions and macros are listed in all the groups in which they belong. Therefore, sev eral of them are listed more than once.
Remember that Xlib functions begin with the letter "X"; macros do not
A.1 Group Listing with Brief Descriptions
Association Tables
XCreateAssocTable
XDeleteAssoc
XDestroyAssocTable
XLookUpAssoc
XMakeAssoc
Create a new association table (X10).
Delete an entry from an association table.
Free the memory allocated for an association table.
Obtain data from an association table.
Create an entry in an association table.
Buffers
XStoreBuffer
XStoreBytes
XFetchBuffer
XFetchBytes
XRotateBuffers
Store data in a cut buffer. Store data in cut buffer 0. Return data from a cut buffer. Return data from cut buffer 0. Rotate the cut buffers.
Function Group Summary
Client Connections
XKillClient XSetCloseDownMode
Destroy a client or its remaining resources. Change the close down mode of a client.
Colorcells
XAllocColor
XAllocColorCells XAllocColorPlanes XAllocNamedColor XLookupColor
XParseColor
XQueryColor
XQueryColors
XStoreColor
XStoreColors
XStoreNamedColor XFreeColors BlackPixel WhitePixel
Allocate a read-only colormap cell with closest hardware-sup ported color.
Allocate read/write (nonshared) colorcells. Allocate read/write (nonshareable) color planes. Allocate a read-only colorcell from color name. Get database RGB values and closest hardware-supported RGB values from color name.
Look up or translate RGB values from color name or hexade cimal value.
Obtain the RGB values for a specified pixel value. Obtain RGB values and flags for each specified pixel value. Set or change a read/write entry of a colormap to the closest available hardware color.
Set or change read/write colorcells to the closest available hardware colors.
Allocate a read/write colorcell by English color name. Free colormap cells or planes.
Return a black pixel value on the default colormap of screen. Return a pixel value representing white in default colormap.
Colormaps
XCopyColormapAndFree
XCreateColormap
XFreeColormap
XGetStandardColormap
XSetStandardColormap
XSetWindowColormap
XInstallColormap
XUninstallColormap
XListlnstalledColormaps
DefaultColormap
DefaultColormapOfScreen
DisplayCells
Copy a colormap and return a new colormap ID. Create a colormap.
Delete a colormap and install the default colormap. Get the standard colormap property. Change the standard colormap property. Set the colormap for a specified window. Install a colormap.
Uninstall a colormap; install default if not already installed. Get a list of installed colormaps. Return the default colormap on the default screen. Return the default colormap on the specified screen. Return the maximum number of colormap cells on the con nected display.
Context Manager
XDeleteContext XFindContext
Delete a context entry for a given window and type. Get data from the context manager (not graphics context).
545
Xlib Reference Manual
Context Manager (continued)
XSaveContext XUniqueContext
Save a data value corresponding to a window and context type
(not graphics context).
Create a new context ID (not graphics context).
Cursors
XDefineCursor
XUndefineCursor
XCreateFontCursor
XCreateGlyphCursor
XCreatePixmapCursor
XFreeCursor
XRecolorCursor
XQueryBestCursor
XQueryBestSize
Assign a cursor to a window.
Disassociate a cursor from a window.
Create a cursor from the standard cursor font
Create a cursor from font glyphs.
Create a cursor from two bitmaps.
Destroy a cursor.
Change the color of a cursor.
Get the closest supported cursor sizes.
Obtain the "best" supported cursor, tile, or stipple size.
Display Specifications
DefaultColormap
DefaultDepth
DefaultGC
DefaultScreen
DefaultVisual DisplayCells
DisplayHeight
DisplayHeightMM
DisplayPlanes
DisplayString
DisplayWidth
DisplayWidthMM
RootWindow
ScreenCount
XDisplayMotionBufferSize
XListDepths
XListPixmapFormats
XMaxRequestSize
XResourceManagerString
Return the default colormap on the specified screen. Return the depth of the default root window for a screen. Return the default graphics context for the root window of a screen.
Return the screen integer; the last segment of a string passed to XOpenDisplay, or the DISPLAY environment variable if NULL was used.
Return the default visual structure for a screen. Return the maximum number of colormap cells on the con nected display.
Return an integer that describes the height of the screen in pix els.
Return the height of the specified screen in millimeters. Return the number of planes on the connected display. Return the string that was passed to XOpenDisplay or if that was NULL, the DISPLAY variable. Return the width of the screen in pixels. Return the width of the specified screen in millimeters. Return the ID of the root window. Return the number of available screens. Return size of server's motion history buffer. Return a list of the depths supported on this server. Return a list of the pixmap formats supported on this server. Return maximum request size allowed on this server. Return string containing user's resource database.
Function Group Summary
Drawing Primitives
XDraw
XDrawArc
XDrawArcs
XDrawFilled
XDrawLine
XDrawLines
XDrawPoint
XDrawPoints
XDrawRectangle
XDrawRectangles
XDrawSegments
XCopyArea
XCopyPlane
XFillArc
XFillArcs
XFillPolygon
XFillRectangle
XFillRectangles
XClearArea
XClearWindow
Draw a polyline or curve between vertex list (from X10).
Draw an arc fitting inside a rectangle.
Draw multiple arcs.
Draw a filled polygon or curve from vertex list (from X10).
Draw a line between two points.
Draw multiple connected lines.
Draw a point.
Draw multiple points.
Draw an outline of a rectangle.
Draw the outlines of multiple rectangles.
Draw multiple disjoint lines.
Copy an area of a drawable.
Copy a single plane of a drawable into a drawable with depth,
applying pixel values.
Fill an arc.
Fill multiple arcs.
Fill a polygon.
Fill a rectangular area.
Fill multiple rectangular areas.
Clear a rectangular area in a window.
Clear an entire window.
Errors
XGetErrorDatabaseText
XGetErrorText
XSetErrorHandler
XSetlOErrorHandler
XDisplayName
XSetAfterFunction
XSynchronize
Obtain error messages from the error database.
Obtain a description of error code.
Set a nonfatal error event handler.
Handle fatal I/O errors.
Report the display name when connection to a display fails.
Set a function called after all Xlib functions.
Enable or disable synchronization for debugging.
Events
XSelectlnput
XSendEvent
XSetlnputFocus
XGetlnputFocus
XWindowEvent
XCheckWindowEvent
XCheckTypedEvent
XCheckTypedWindowEvent
XMaskEvent
XCheckMaskEvent
Select the event types to be sent to a window. Send an event
Set the keyboard focus window. Return the current keyboard focus window. Remove the next event matching mask and window. Remove the next event matching both passed window and pas sed mask; don't wait.
Return the next event in queue that matches event type; don't wait.
Return the next event in queue matching type and window. Remove the next event that matches mask. Remove the next event that matches mask; don't wait.
550
Xlib Reference Manual
Events (continued)
XIfEvent
XChecklfEvent
XPeekEvent
XPeeklfEvent
XAllowEvents
XGetMotionEvents
XNextEvent
XPutBackEvent
XEventsQueued
XPending
XSynchronize QLength
Wait for matching event
Check the event queue for a matching event
Get an event without removing it from the queue.
Get an event without recovering it from the queue; don't wait
Control the behavior of keyboard and pointer events when
these resources are grabbed.
Get pointer motion events.
Get the next event of any type or window.
Push an event back on the input queue.
Check the number of events in the event queue.
Rush the request buffer and return the number of pending
input events.
Enable or disable synchronization for debugging.
Return the current length of the input queue on the connected
display.
Extensions
XFreeExtensionList XListExtensions XQueryExtension
Free memory allocated for a list of installed extensions to X. Return a list of all extensions to X supported by the server. Get extension information.
Fonts
XLoadFont
XUnloadFont
XFreeFont
XFreeFontlnfo
XFreeFontNames
XFreeFontPath
XListFonts
XListFontsWithlnfo
XQueryFont
XSetFont
XSetFontPath
XGetFontPath
XGetFontProperty
XCreateFontCursor
Load a font if not already loaded; get font ID.
Unload a font
Unload a font and free storage for the font structure.
Free multiple font information arrays.
Free the font name array.
Free the memory allocated by XGetFontPath.
Return a list of the available font names.
Obtain the names and information about loaded fonts.
Return information about a loaded font.
Set the current font in a graphics context.
Set the font search path.
Get the current font search path.
Get a font property given its atom.
Create a cursor from the standard cursor font
Grabbing
XGrabKey
XUngrabKey
XGrabKeyboard
XUngrabKeyboard
XGrabButton
Grab a key.
Release a key from grab.
Grab the keyboard.
Release the keyboard from grab.
Grab a pointer button.
Function Group Summary
Grabbing (continued)
XUngrabButton
XGrabPointer
XUngrabPointer
XGrabServer
XUngrabServer
XChangeActivePointerGrab
Release a button from grab.
Grab the pointer.
Release the pointer from grab.
Grab the server grab.
Release the server from grab.
Change the parameters of an active pointer grab.
Graphics Context
XCreateGC
XChangeGC XCopyGC XFreeGC XGContextFromGC
XGetGCValues
XSetArcMode
XSetClipMask
XSetClipOrigin
XSetClipRectangles
XSetRegion
XSetDashes
XSetLineAttributes
XSetFillRule
XSetFillStyle
XSetTile
XSetStipple
XSetTSOrigin
XSetGraphicsExposures
XSetForeground
XSetBackground
XSetFunction
XSetPlaneMask
XSetState
XSetSubwindowMode DefaultGC
Create a new graphics context for a given screen with the
depth of the specified drawable.
Change the components of a given graphics context.
Copy a graphics context.
Free a graphics context.
Obtain the GContext (resource ID) associated with the
specified graphics context.
Get GC component values from Xlib's GC cache.
Set the arc mode in a graphics context.
Set clip_mask pixmap in a graphics context.
Set the clip origin in a graphics context.
Set clip_mask in a graphics context to the list of rectangles.
Set clip_mask of the graphics context to the specified
region.
Set dash_of f set and dashes (for lines) in a graphics
context.
Set the line drawing components in a graphics context.
Set the fill rule in a graphics context.
Set the fill style in a graphics context.
Set the fill tile in a graphics context.
Set the stipple in a graphics context.
Set the tile/stipple origin in a graphics context.
Set graphics_exposures in a graphics context.
Set the foreground pixel value in a graphics context.
Set the background pixel value in a graphics context.
Set the bitwise logical operation in a graphics context.
Set the plane mask in a graphics context.
Set the foreground, background, logical function and plane
mask in a graphics context.
Set the subwindow mode in a graphics context.
Return the default graphics context for the root window of a
screen.
552
Xlib Reference Manual
Host Access
XAddHost
XAddHosts
XListHosts
XRemoveHost
XRemoveHosts
XDisableAccessControl
XEnableAccessControl
XSetAccessControl
Add a host to the access control list.
Add multiple hosts to the access control list.
Obtain a list of hosts having access to this display.
Remove a host from the access control list.
Remove multiple hosts from the access control list.
Allow access from any host
Use access control list to allow or deny connection requests.
Disable or enable access control.
HouseKeeping
XFree
XOpenDisplay XCloseDisplay XNoOp
Free specified in-memory data created by an Xlib function. Connect a client program to an X server. Disconnect a client program from an X server and display. Send a NoOp to exercise connection with the server.
Images
XCreateImage XDestroyImage XPutlmage XSublmage XGetImage XGetSublmage
XAddPixel XPutPixel XGetPixel ImageByteOrder
Allocate memory for an Xlmage structure. Deallocate memory associated with an image. Draw a rectangular image on a window or pixmap. Create a subimage from part of an image. Place contents of a rectangle from drawable into an image. Copy a rectangle in drawable to a location within the pre existing image.
Add a constant value to every pixel value in an image. Set a pixel value in an image. Obtain a single pixel value from an image. Specify the required byte order for images for each scan line unit in XYFormat (bitmap) or for each pixel value in ZFor-mat. Returns either LSBFirst orMSBFirst.
Interclient Communication
(see Window Manager Hints, Selections, and Cut Buffers)
Keyboard
XKeycodeToKeysym
XKeysymToKeycode
XKeysymToString
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.
