O'Reilly logo

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

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

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

Start Free Trial

No credit card required

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

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

Start Free Trial

No credit card required