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

size hints property of a zoomed window XGetZoomHints: read the XGetZoomHints

get the property list for a window XListProperties: XListProperties

map all subwindows of window XMapSubwindows: XMapSubwindows

XMapWindow: map a window XMapWindow

the size and position of a window /change XMoveResizeWindow

XMoveWindow: move a window XMoveWindow

the next event of any type or window XNextEvent: get XNextEvent

the event types to be sent to a window XSelectlnput: select XSelectlnput

the XA_WM_CLASS property of a window XSetClassHint: set XSetClassHint

set the keyboard focus window XSetlnputFocus: XSetlnputFocus

property for a window /the XA_WM_TRANSIENT_FOR XSetTransientForHint

pixel value attribute of a window /set the background XSetWindowBackground

background tile attribute of a window /change the XSetWindowBackgroundPixmap

change the border width of a window XSetWindowBorderWidth: XSetWindowBorderWidth

set the colormap attribute for a window XSetWindowColormap: XSetWindowColormap

size hints property of a zoomed window XSetZoomHints: set the XSetZoomHints

disassociate a cursor from a window XUndefineCursor: XUndefineCursor

unmap all subwindows of a given window XUnmapSubwindows: XUnmapSubwindows

XUnmapWindow: unmap a window XUnmapWindow

matches the specified mask and window /the next event that XWindowEvent

/unmap and destroy a window and all subwindows XDestroyWindow

/a data value corresponding to a window and context type (not/ XSaveContext

/insert a window between another window and its parent XReparentWindow

/next event matching both passed window and passed mask; don't/ XCheckWindowEvent

XCreateWindow: create a window and set attributes XCreateWindow

a context entry for a given window and type /delete XDeleteContext

XChangeWindowAttributes: set window attributes XChangeWindowAttributes

/request that a top-level window be iconified Xlconify Window

/request that a top-level window be reconfigured XReconfigureWMWindow

/request that a top-level window be withdrawn XWithdrawWindow

and/ XReparentWindow: insert a window between another window XReparentWindow

XSetWindowBorder: change a window border pixel value/ XSetWindowBorder

XSetWindowBorderPixmap: change a window border tile attribute and/ XSetWindowBorderPixmap

XStoreName: assign a name to a window for the window manager XStoreName

XRemoveFromSaveSet: remove a window from the client's/ XRemoveFromSaveSet

geometry/ XGeometry: calculate window geometry given user XGeometry

position and size from standard window geometry string /generate XParseGeometry

/get the size hints property of a window in normal state (not/ XGetNormalHints

/set the size hints property of a window in normal state (not/ XSetNormalHints

XLowerWindow: lower a window in the stacking order XLowerWindow

set of properties for the window manager /set the minimum XSetStandardProperties

a name to a window for the window manager /assign XStoreName

XGetWMHints: read the window manager hints property XGetWMHints

XSetWMHints: set a window manager hints property XSetWMHints

/set a window's standard window manager properties XSetWMProperties

XMapRaised: map a window on top of its siblings XMapRaised

XPutlmage: draw an image on a window or pixmap XPutlmage

XConfigureWindow: change the window position, size, border/ XConfigureWindow

XDeleteProperty: delete a window property XDeleteProperty

the coordinate system from one window to another /change XTranslateCoordinates

XAddToSaveSet: add a window to the client's save-set XAddToSaveSet

stacking/ XRaiseWindow: raise a window to the top of the XRaiseWindow

XWMGeometry: obtain a window's geometry information XWMGeometry

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

property) XFetchName: get a window's name (XA_WM_NAME XFetchName

XResizeWindow: change a window's size XResizeWindow

XSetWMProperties: set a window's standard window manager/ .— XSetWMProperties

XGetTextProperty: read one of a window's text properties XGetTextProperty

XSetTextProperty: set one of a window's text properties XSetTextProperty

XSetWMCIientMachine: set a

XSetWMColoimapWindows: set a

XSetWMProtocols: set a

XSetWMSizeHints: set a

property XGetWMIconName: read a

property XSetWMIconName: set a

XGetWMName: read a

XSetWMName:seta

XGetWMNormalHints: read a

XSetWMNormalHints: set a

XGetWMSizeHints: read a

that a top-level window be

/set a window's

XSetWMProtocols: set a window's

XSetWMSizeHints: set a window's

XWriteBitmapFile:

connect a client program to an

a client program from an

/a list of all extensions to

create a new association table

curve between vertex list (from

or curve from vertex list (from

/create a bitmap from

read any property of type

value of any property of type

XGetClassHint: get the

XSetClassHint: set the

arguments) XSetCommand: set the

XGetWMIconName: read a window's

XSetWMIconName: set a window's

/set the value of the

XFetchName: get a window's name

XGetWMName: read a window's

XSetWMName: set a window's

/read a window's

/set a window's

XGetWMSizeHints: read a window's

a/ XSetTransientForHint: set the

a/ XGetTransientForHint: get the

XAllocClassHint: allocate an

free the memory allocated by

XAllocIconSize: allocate an

allocate memory for an

components of a given GC from

free the memory allocated by

/free the memory allocated by

/delete an entry from an

/add a new entry to an

XAllocSizeHints: allocate an

/allocate an

XSetRGBColormaps: set an

XGetRGBColormaps: obtain the

specified list of strings to an

list of strings from a specified

XAllocWMHints: allocate an

of a window in normal state (not

window's WM_CLIENT_MACHINE/ ... XSetWMCIientMachine window's WM_COLORMAP_WINDOWS/ XSetWMColormapWindows window's WM_PROTOCOLS property . XSetWMProtocols window's WM_SIZE_HINTS property .. XSetWMSizeHints

window's XA_WMJCON_NAME XGetWMIconName

window's XA_WM_ICON_NAME XSetWMIconName

window's XA_WM_NAME property XGetWMName

window's XA_WM_NAME property XSetWMName

window's XA_WM_NORMAL_HINTS/ XGetWMNormalHints window's XA_WM_NORMAL_HINTS/ XSetWMNormalHints

window's XA_WM_SEE_fflNTS/ XGetWMSizeHints

withdrawn /request XWithdrawWindow

WM_CLIENT_MACHINE property XSetWMCIientMachine

WM_COLORMAP_WINDOWS property XSetWMColormapWindows

WM_PROTOCOLS property XSetWMProtocols

WM_SEE_fflNTS property XSetWMSizeHints

write a bitmap to a file XWriteBitmapFile

X server XOpenDisplay: XOpenDisplay

X server and display /disconnect XCloseDisplay

X supported by Xlib and the/ XListExtensions

(X10) XCreateAssocTable: XCreateAssocTable

X10) XDraw: draw a polyline or XDraw

X10) /draw a filled polygon XDrawFilled

XI1 bitmap format data XCreateBitmapFromData

XA_SEE_fflNTS XGetSizeHints: XGetSizeHints

XA_SEE_HINTS /set the XSetSizeHints

XA_WM_CLASS property of a window .XGetClassHint XA_WM_CLASS property of a window. XSetClassHint XA_WM_COMMAND atom (command line XSetCommand

XA_WM_ICON_NAME property XGetWMIconName

XA_WM_ICON_NAME property XSetWMIconName

XA_WM_ICON_SIZE property XSetlconSizes

(XA_WM_NAME property) XFetchName

XA_WM_NAME property XGetWMName

XA_WM_NAME property XSetWMName

XA_WM_NORMAL_fflNTS property .. XGetWMNormalHints XA_WM_NORMAL_HINTS property .. XSetWMNormalHints

XA_WM_SEE_HINTS property XGetWMSizeHints

XA_WM_TRANSIENT_FOR property for XSetTransientForHint XA_WM_TRANSIENT_FOR property of XGetTransientForHint

XClassHint structure

XGetFontPath XFreeFontPath: ...

XlconSize structure

Xlmage structure XCreatelmage:

Xlib's GC cache /obtain

XListFonts. XFreeFontNames: ....

XListFontsWithlnfo

XModifierKeymap structure

XSizeHints structure

XStandardColormap structure

XStandardColormap structure/

XTextProperty structure /set the

XTextProperty structure /a

XWMHints structure

zoomed or iconified) /property

XAllocClassHint

XFreeFontPath

XAllocIconSize

XCreatelmage

XGetGCValues

XFreeFontNames

XFreeFontlnfo

XDeleteModifiermapEntry

XlnsertModifiermapEntry

XAllocSizeHints

XAllocStandardColormap

XSetRGBColormaps

XGetRGBColormaps

XStringListToTextProperty

XTextPropertyToStringList

XAllocWMHints

XGetNormalHints

XSetNormalHints

Xlib Reference Manual

the size hints property of a zoomed window /read XGetZoomHints

set the size hints property of a zoomed window XSetZoomHints: XSetZoomHints

-xiib- Function Group / Introduction

This page describes the format of each reference page in this volume.

Name

XFunctionName — brief description of the function.

Synopsis

The Synopsis section presents the calling syntax for the routine, including the declarations of the arguments and return type. For example:

returntype XFunctionName( argl, arg2, arg3); typel argl;

type2 *arg2; /* RETURN */

type3 *arg3; /* SEND and RETURN */

The return type Status is of type int; it returns either True or False to indicate whether the routine was successful.

Arguments

The Arguments section describes each of the arguments used by the function. There are three sorts of arguments: arguments that specify data to the function, arguments that return data from the function, and arguments that do both. An example of each type is shown below:

argl Specifies information for XFunctionName. The description of arguments that

pass data to the function always begins with the word "Specifies," as shown in this example.

arg2 Returns a pointer to data to be filled in by XFunctionName. The description of

arguments that return data from the function always begins with the word "Returns."

arg3 Specifies information for XFunctionName, and returns data from the function.

The description of arguments that both pass data to the function and return data from the function uses both the words "Specifies" and "Returns."

Availability

The Availability section specifies that a given function is only available in Release 4 and later releases. If there is no Availability section, the function is available prior to Release 4.

Description

The Description section describes what the function does, what it returns, and what events or side-effects it causes. It also contains miscellaneous information such as examples of usage, special error cases, and pointers to related information in both volumes of this manual.

Structures

The Structures section contains the C definitions of the X-specific data types used by FunctionName as arguments or return values. It also contains definitions of important con-

Introduction (continued) Xlib - Function Group

slants used by the function. Additional structures not shown can be found in Appendix F, Structure Reference.

Errors

The general description of the error types is contained in Appendix B, Error Messages and Pro tocol Requests. Some functions generate errors due to function-specific interpretation of argu ments. Where appropriate, these function-specific causes have been listed along with the error event types they generate.

Related Commands

The Related Commands section lists the Xlib functions and macros related to XFunction-Name.

—Xlib - Screen Saver-

J XActivateScreenSaver

Name

XActivateScreenSaver — activate screen blanking. Synopsis

XActivateScreenSaver(display) Display *di splay;

Arguments

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

Description

XActivateScreenSaver turns on the screen saver using the parameters set with XSet-ScreenSaver. The screen saver blanks the screen or makes random changes to the display in order to save the phosphors from burnout when the screen is left unattended for an extended period of time. The interval that the server will wait before starting screen save activity can be set with XSetScreenSaver. Exactly how the screen saver works is server-dependent.

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

Related Commands

XForceScreenSaver,XGetScreenSaver,XResetScreenSaver, XSetScreen Saver.

XAddHOSt Xnb-Hos.Accsss-

Name

XAddHost — add a host to the access control list.

Synopsis

XAddHost (display, host) Display *display; XHostAddress *host;

Arguments

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

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

Description

XAddHost adds the specified host to the access control list for the server specified by dis play. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX-based sys tems, this file is called letclX?.hosts, where ? is the number of the server.

The application that calls XAddHost and the server whose list is being updated must be run ning on the same host machine.

The address data must be a valid address for the type of network in which the server oper ates, as specified in the family member. Internet, DECnet and ChaosNet networks are cur rently supported.

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

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

Structures

typedef struct {

int family; /* for example Familylnternet */

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

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

} XHostAddress;

/* The following constants for family member */

#define Familylnternet 0

ttdefine FamilyDECnet 1

#define FamilyChaos 2

Errors

BadAccess BadValue

Xlib - Host Access (continued) XAddHost

Related Commands

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

Xlib Reference Manual

XAddHOStS X,, b -Hos, Access-

Name

XAddHosts — add multiple hosts to the access control list.

Synopsis

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

Arguments

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

hosts Specifies each host that is to be added.

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

Description

XAddHosts adds each specified host to the access control list for the server specified by dis play. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX systems, this file is letclX?.hosts, where ? is the number of the display.

The application that calls XAddHosta and the server whose list is being updated must be run ning on the same host machine.

The address data must be a valid address for the type of network in which the server oper ates, as specified by the family member. Internet, DECnet and ChaosNet networks are cur rently supported.

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

Structures

typedef struct {

int family; /* for example Family Internet */

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

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

} XHostAddress;

/* The following constants for family member */ tdefine Familylnternet 0 #define FamilyDECnet 1 #define FamilyChaos 2

Xlib - Host Access (continued) XAddHostS

Errors

BadAccess BadValue

Related Commands

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

XAddPixel\ Xlib _ lmages _

Name

XAddPixel — add a constant value to every pixel value in an image.

Synopsis

XAddPixel (ximage, value) Xlmage *ximage ; unsigned long value;

Arguments

ximage Specifies a pointer to the image to be modified.

value Specifies the constant value that is to be added. Valid pixel value ranges

depend on the visual used to create the image. If this value added to the existing value causes an overflow, extra bits in the result are truncated.

Description

XAddPixel adds a constant value to every pixel value in an image. This function is useful when you have a base pixel value derived from the allocation of color resources and need to manipulate an image so that the pixel values are in the same range.

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

typedef struct Xlmage {

int width, height; /* size of image */

int xoffset; /* number of pixels offset in X direction */

int format; /* XYBitmap, XYPixmap, ZPixmap */

char *data; /* pointer to image data */

int byte_order; /* data byte order, LSBFirst, MSBFirst */

int bitmap_unit; /* quantity of scan line 8, 16, 32 */

int bitmap_bit_order; /* LSBFirst, MSBFirst */

int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */

int depth; /* depth of image */

int bytes per line; /* accelerator to next line */

int bits_per_pixel; /* bits per pixel (ZPixmap) */

unsigned long red_mask; /* bits in z arrangment */

unsigned long green mask;

unsigned long blue_mask;

char *obdata; /* hook for object routines to hang on */

struct funcs { /* image manipulation routines */

struct _XImage *(*create_image)();

int (*destroy_image)();

unsigned long (*get_pixel)();

int (*put_pixel)();

struct _XImage *(*sub_image)();

int (*add_pixel)();

} f;

} Xlmage;

Xlib-Images (continued) XAddPixel

Related Commands

ImageByteOrder, XCreatelmage, XDestroylmage, XGetlmage, XGetPixel, XGetSublmage, XPutlmage, XPutPixel, XSubImage.

XAddToSaveSet "\

XIib-Save Set —

Name

XAddToSaveSet — add a window to the client's save-set.

Synopsis

XAddToSaveSet( 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 you want to add to the client's save-set.

Description

XAddToSaveSet adds the specified window to the client's save-set.

The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a titlebar or other decorations for each application. When the window man ager dies unexpectedly, the windows in the save-set are reparented to their closest living ances tor, so that they remain alive. See Volume One, Chapter 13, Other Programming Techniques, for more information about save-sets.

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

Errors

BadMat ch w not created by some other client.

BadWindow

Related Commands

XChangeSaveSet,XRemoveFromSaveSet.

-XHb-W,ndow Manager Him, / XAIIOCCIaSSHint

Name

XAllocClassHint — allocate an XClassHint structure.

Synopsis

XClassHint *XAllocClassHint()

Availability

Release 4 and later.

Description

XAllocClassHint allocates and returns a pointer to an XClassHint structure, for use in calling XSetWMProperties, XGetClassHint, or XSetClassHint. Note that the pointer fields in the XClassHint structure are initially set to NULL. If insufficient memory is available, XAllocClassHint returns NULL. To free the memory allocated to this structure, useXFree.

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures.

For more information, see Volume One, Chapter WJnterclient Communication. Structures

typedef struct {

char *res_name;

char *res_class; } XClassHint;

Related Commands

XGetClassHint,XSetClassHint,XSetWMProperties.

XHb Reference Manual

XANocColor "\ Yll

v Xlib - Color Cells-Name

XAllocColor — allocate a read-only colormap cell with closest hardware-supported color.

Synopsis

Status XAllocColor( display, cmap, colorcell_def) Display * display; Colo rmap cmap ; XColor *colorcell_def; /* SENDs and RETURNS */

Arguments

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

cmap Specifies the ID of the colormap in which the colorcell is to be allocated.

col oreel l_def

Specifies desired RGB values, and also returns the pixel value and the RGB val ues actually used in the colormap.

Description

XAllocColor returns in the XColor structure the pixel value of a read-only (shareable) colorcell with the closest RGB values available in cmap. XAllocColor also returns the red, green, and blue values actually used.

If the display hardware has an immutable hardware colormap, the entire colormap will be read only, and the closest cell that exists will be returned. Otherwise, the colormap is read/write, and may have some read/write cells, some read-only cells, and some unallocated cells. If a read-only cell exists that matches the requested RGB values, that cell is returned. If no match ing cell exists but there are unallocated cells, a cell is allocated to match the specified RGB val ues. If no matching cell exists and there are no unallocated cells, XAllocColor returns a Status of zero (in read/write colormaps, it does not return the closest available read-only colorcell that has already been allocated). If it succeeds, XAllocColor returns nonzero.

Note that colorcell_def stores both the requested color when XAllocColor is called and the result when XAllocColor returns.

XAllocColor does not use or affect the flags member of the XColor structure. 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

BadColormap

Xlib - Color Cells (continued) XAIIOCColor

Related Commands

BlackPixel,WhitePixel,XAllocColorCells,XAllocColorPlanes,XAlloc-NamedColor,XFreeColors,XLookupColor, XParseColor, XQueryColor, XQueryColors,XStoreColor,XStoreColors, XStoreNamedColor.

XAIIocColorCells

•Xlib-Color Cells-

Name

XAIIocColorCells — allocate read/write (nonshared) colorcells.

Synopsis

Status XAIIocColorCells(display, cmap,

nplanes, pixels, ncolors) Display *display; Colormap cmap ; Bool contig;

unsigned long plane_masks[nplanes] unsigned int nplanes; unsigned long pixels[ncolors]; unsigned int ncolors;

contig, plane_masks,

/* RETURN

/* RETURN pixel values */

Arguments

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

cmap Specifies the ID of the colormap in which the colorcell is to be allocated.

contig Specifies a boolean value. Pass True if the planes must be contiguous or

False if the planes need not be contiguous.

plane_mask Returns an array of plane masks.

nplanes Specifies the number of plane masks returned in the plane masks array. Must

be nonnegative.

pixels Returns an array of pixel values.

ncolors Specifies the number of pixel values returned in the pixels array. Must be

positive.

Description

XAIIocColorCells allocates read/write colorcells in a read/write colormap. If ncolors and nplanes are requested, then ncolors pixels and nplanes plane masks are returned. No mask will have any bits in common with any other mask, or with any of the pixels. By ORing together each of the pixels with any combination of the plane_masks, ncolors*2 (npla/ies ) distinct pixels can be produced. For Grayscale or Pseudocolor, each mask will have exactly one bit, and for DirectColor each will have exactly three bits. If contig is True, then if all plane masks are ORed together, a single contiguous set of bits will be formed for Grayscale or Pseudocolor and three contiguous sets of bits (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined until set with XStoreColor, XStoreColors, or XStoreNamedColor.

Status is zero on failure, and nonzero on success.

For more information, see Volume One, Chapter 7, Color.

Xlib Reference Manual

Xlib - Color Cells (continued) XAIIOCColorCellS

Errors

BadColormap

BadValue nplanes is negative.

ncolors is not positive.

Related Commands

BlackPixel,WhitePixel,XAllocColor, XAllocColorPlanes, XAllocNamed-Color, XFreeColors,XLookupColor,XParseColor,XQueryColor, XQuery-Colors, XStoreColor,XStoreColors, XStoreNamedColor.

Xlib Reference Manual

XAIIocColorPlanes X v,,

v XHb - Color Cells-Name

XAIIocColorPlanes — allocate read/write (nonshareable) color planes.

Synopsis

Status XAIIocColorPlanes(display, cmap, contig, pixels, ncolors,

nreds r ngreens, nblues, rmask, gmask, bmask) Display *display; Colormap cmap ; Bool contig;

unsigned long pixels [ncolors] ; /* RETURN */ int ncolors;

int nreds, ngreens, nblues; unsigned long *rmask, *gmask, *bmask; /* RETURN */

Arguments

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

cmap Specifies the ID of the colormap to be used.

contig Specifies a boolean value. Pass True if the planes must be contiguous or False if the planes do not need to be contiguous.

pixels Returns an array of pixel values.

7i colors Specifies the number of pixel values returned in the pixels array. Must be posi tive.

nreds Specify the number of red, green, and blue planes (shades). Must be nonnega-

ngreens tive.

nblues

rmask Return bit masks for the red, green, and blue planes.

gmask

bmask

Description

If ncolors, nreds, ngreens, and nblues are requested, then ncolors pixels are returned, and the masks have nreds, ngreens, and nblues bits set to 1 respectively. Unique pixel values are generated by by ORing together subsets of masks with each item in the pixels list (pixels does not by itself contain pixel values). In doing this, note that

nCOlorS*( 2 (nreds+ngreens+nblues) ) distinct pixel ValuCS aTC allocated.

If contig is True, then each mask will have a contiguous set of bits. No mask will have any bits in common with any other mask, or with any of the pixels. For DirectColor, each mask will lie within the corresponding pixel subfield.

Note, however, that there are actually only ncolors*(2 nreds ) independent red entries, ncolors~*(2 n e reens ) independent green entries, and n colors* (2 nblues ) independent blue entries in the colormap. This is true even for Pseudocolor. This does not cause problems, though, because when the colormap entry for a pixel value is changed using xstoreColors

Xlib - Color Cells (continued) XAHocColorPlaneS

or XStoreNamedColor, the pixel is decomposed according to rmask, gmask, and bmask and the corresponding pixel subfield entries are updated.

Status is zero on failure, and nonzero on success.

For more information, see Volume One, Chapter 7, Color.

Errors

BadColormap

BadValue ncolors is not positive.

At least one of nreds, ngreens, nbl ues is negative.

Related Commands

BlackPixel,WhitePixel,XAllocColor, XAllocColorCells, XAllocNamed-Color, XFreeColors,XLookupColor,XParseColor,XQueryColor,XQuery-Colors,XStoreColor,XStoreColors,XStoreNamedColor.

v Xlib - Window Manager Hints-Name

XAllocIconSize — allocate anxiconSize structure.

Synopsis

XlconSize *XAllocIconSize( )

Availability

Release 4 and later.

Description

XAIIoclconSize allocates and returns a pointer to an XlconSize structure, for use in cal ling XGetlconSizes or XSetlconSizes. Note that all fields in the XlconSize struc ture are initially set to zero. If insufficient memory is available, XAIIoclconSize returns NULL. To free the memory allocated to this structure, use XFree.

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures.

For more information, see Volume One, Chapter WJnterclient Communication. Structures

typedef struct {

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc; } XlconSize;

Related Commands

XGetlconSizes,XSetlconSizes.

50 Xlib Reference Manual

—Xlib-Color Cells-

J XAIIocNamedColor

Name

XAIIocNamedColor — allocate a read-only colorcell from color name.

Synopsis

Status XAIIocNamedColor(display, cmap, colorname,

colorcell_def, rgb_db_def) Display * display; Colormap cmap; char * colorname;

XColor *colorcell_def; /* RETURN */ XColor *rgb_db_def; /* RETURN */

Arguments

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

cmap Specifies the ID of the colormap in which the colorcell will be allocated.

colorname Specifies the color name string (for example, "red") you want. Upper or lower case does not matter. The string should be in ISO LATIN-1 encoding, which means that the first 128 character codes are ASCII, and the second 128 character codes are for special characters needed in western languages other than English.

colorcell_def

Returns the pixel value and RGB values actually used in the colormap. This is the closest color supported by the hardware.

rgb_db_def Returns the exact RGB values from the database corresponding to the colorname supplied.

Description

XAIIocNamedColor determines the RGB values for the specified colorname from the color database, and then allocates a read-only colorcell with the closest color available, as described under XAllocColor. Both the 'exact' database definition of the color, and the color actually allocated are returned. If the colormap is not full, the RGB values allocated are the closest supported by the hardware. If the colormap is full, and is a StaticColor, DirectColor, or StaticGray visual class, XAIIocNamedColor returns the closest read-only colorcell already allocated, and does not actually create or set any new colorcell. If the colormap is full and is a Pseudocolor, TrueColor, or Grayscale visual class, XAIIocNamedColor fails and returns zero.

XAIIocNamedColor returns a Status of zero if colorname was not found in the data base or if the color could not be allocated. The function returns nonzero when it succeeds.

For more information, see Volume One, Chapter 7, Color.

XAllocNamedColor (continued) Xlib - Color Cells

Errors

BadColormap BadName

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

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

char pad; } XColor;

Related Commands

BlackPixel,WhitePixel,XAllocColor,XAllocColorCells,XAllocColor-Planes,XFreeColors,XLookupColor,XParseColor,XQueryColor,XQuery-Colors,XStoreColor,XStoreColors,XStoreNamedColor.

-XMb-WmdowManager Him, ' XAIIOCSizeHintS

Name

XAllocSizeHints —allocate an XSizeHints structure.

Synopsis

XSizeHints *XAllocSizeHints()

Availability

Release 4 and later.

Description

XAllocSizeHints allocates and returns a pointer to an XSizeHints structure, for use in calling XSetWMProperties,XSetWMNormalHints,orXGetWMNormalHints. Note that all fields in the XSizeHints structure are initially set to zero. If insufficient memory is available, XAllocSizeHints returns NULL. To free the memory allocated to this structure, use XFree.

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures.

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

typedef struct {

long flags; /* marks which fields in this structure are defined */

int x, y; /* Obsolete */

int width, height; /* Obsolete */

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; int win_gravity; } XSizeHints;

Related Commands

XGetWMNormalHints,XSetWMNormalHints,XSetWMProperties.

XAIIocStandardColormap V Vl .

v Xhb - Window Manager Hints-Name

XAIIocStandardColormap —allocate an XStandardColormap structure.

Synopsis

XStandardColormap *XAllocStandardColormap()

Availability

Release 4 and later.

Description

XAIIocStandardColormap allocates and returns a pointer to an XStandardColormap structure for use in calling XGetRGBColormaps or XSetRGBColormaps. Note that all fields in the XStandardColormap structure are initially set to zero. If insufficient memory is available, XAIIocStandardColormap returns NULL. To free the memory allocated to this structure, use XFree.

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures.

For more information, see Volume One, Chapter 7, Color. Structures

/* value for killid field */

#define ReleaseByFreeingColormap ( (XID) 1L)

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;

VisuallD visualid;

XID killid; } XStandardColormap;

Related Commands

XGetRGBColormaps,XSetRGBColormaps.

-Xlib- Window Manager Hints ' XAIIOCWMHmtS

Name

XAllocWMHints — allocate an XWMHints structure.

Synopsis

XWMHints *XAllocWMHints()

Availability

Release 4 and later.

Description

The XAllocWMHints function allocates and returns a pointer to an XWMHints structure, for use in calling XSetWMProperties, XSetWMHints, or XGetWMHints. Note that all fields in the XWMHints structure are initially set to zero. If insufficient memory is available, XAllocWMHints returns NULL. To free the memory allocated to this structure, use XFree.

The purpose of this function is to avoid compiled-in structure sizes, so that object files will be binary compatible with later releases that may have new members added to structures.

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

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; /* pixmap to be used as mask for icon_pixmap */

XID window_group; /* id of related window group */

/* this structure may be extended in the future */ } XWMHints;

Related Commands

XGetWMHints,XSetWMHints,XSetWMProperties.

Xlib Reference Manual

XAIIowEvents

•Xlib-Input Handling-

Name

XAIIowEvents — control the behavior of keyboard and pointer events when these resources are

Synopsis

XAIIowEvents ( display, event_mode, time) Display *display; int event_/node; Time time;

Arguments

display event mode

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

Specifies the event mode. Pass one of these constants: AsyncPointer, SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, ReplayKeyboard, AsyncBoth, or SyncBoth.

time Specifies the time when the grab should take place. Pass either a timestamp,

expressed in milliseconds, or the constant Cur rent Time.

Description

XAIIowEvents releases the events queued in the server since the last XAIIowEvents call for the same device and by the same client. Events are queued in the server (not released to Xlib to propagate into Xlib's queues) only when the client has caused a device to "freeze" (by grabbing the device with mode GrabModeSync). The request has no effect if time is earlier than the last-grab time or later than the current server time.

The event_mode argument controls what device events are released for and just how and when they are released. The event_mode is interpreted as follows:

AsyncPointer If XAIIowEvents is called with AsyncPointer while the

pointer is frozen by the client, pointer event processing resumes nor mally, even if the pointer is frozen twice by the client on behalf of two separate grabs. AsyncPointer has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client.

AsyncKeyboard If XAIIowEvents is called with AsyncKeyboard while the key

board is frozen by the client, keyboard event processing resumes normally, even if the keyboard is frozen twice by the client on behalf of two separate grabs. AsyncKeyboard has no effect if the key board is not frozen by the client, but the keyboard need not be grabbed by the client.

SyncPointer If XAIIowEvents is called with SyncPointer while the pointer

is frozen by the client, normal pointer event processing continues until the next ButtonPress or ButtonRelease event is reported to the client. At this time, the pointer again appears to freeze. However, if the reported event causes the pointer grab to be

Xlib Reference Manual

Xlib - Input Handling

(continued)

XAIIowEvents

SyncKeyboard

ReplayPointer

ReplayKeyboard

SyncBoth

AsyncBoth

released, then the pointer does not freeze, which is the case when an automatic grab is released by a ButtonRelease or when XGrab-Button or XGrabKey has been called and the specified key or but ton is released. SyncPointer has no effect if the pointer is not frozen or not grabbed by the client.

If XAIIowEvents is called with SyncKeyboard while the key board is frozen by the client, normal keyboard event processing con tinues until the next KeyPress or KeyRelease event is reported to the client. At this time, the keyboard again appears to freeze. However, if the reported event causes the keyboard grab to be released, then the keyboard does not freeze, which is the case when an automatic grab is released by a ButtonRelease or when XGrabButton or XGrabKey has been called and the specified key or button is released. SyncKeyboard has no effect if the keyboard is not frozen or not grabbed by the client.

This symbol has an effect only if the pointer is grabbed by the client and thereby frozen as the result of an event. In other words, XGrabButton must have been called and the selected button/key combination pressed, or an automatic grab (initiated by a Button-Press) must be in effect, or a previous XAIIowEvents must have been called with mode SyncPointer. If the pointer_mode of the XGrabPointer was GrabModeSync, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierar chy (towards the root) on the grab-window of the grab just released.

This symbol has an effect only if the keyboard is grabbed by the cli ent and if the keyboard is frozen as the result of an event. In other words, XGrabKey must have been called and the selected key com bination pressed, or a previous XAIIowEvents must have been called with mode SyncKeyboard. If the pointer_mode or keyboard_mode of the XGrabKey was GrabModeSync, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root).

SyncBoth has the effect described for both SyncKeyboard and SyncPointer. SyncBoth has no effect unless both pointer and keyboard are frozen by the client. If the pointer or keyboard is fro zen twice by the client on behalf of two separate grabs, SyncBoth "thaws" for both (but a subsequent freeze for SyncBoth will only freeze each device once).

AsyncBoth has the effect described for both AsyncKeyboard and AsyncPointer. AsyncBoth has no effect unless both pointer and keyboard are frozen by the client. If the pointer and the

Xlib Reference Manual

XAHowEventS (continued) Xlib-Input Handling

keyboard were frozen by the client, or if both are frozen twice by two separate grabs, event processing (for both devices) continues normally. If a device is frozen twice by the client on behalf of the two separate grabs, AsyncBoth releases events for both.

AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of keyboard events. AsyncKeyboard, SyncKeyboard, and ReplayKeyboard have no effect on the processing of pointer events.

It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is per formed for the device. It is also possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events will be released.

For more information on event handling, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadValue Invalid mode constant.

Related Commands

QLength,XChecklfEvent,XCheckMaskEvent, XCheckTypedEvent, XCheck-TypedWindowEvent, XCheckWindowEvent,XEventsQueued,XGetlnputFocus, XGetMotionEvents,XlfEvent,XMaskEvent,XNextEvent,XPeekEvent,XPeek-IfEvent, XPending, XPutBackEvent,XSelectlnput,XSendEvent,XSetlnput-Focus,XSynchronize,XWindowEvent.

—Xllb - User Preferences-

J XAutoRepeatOff

Name

XAutoRepeatOff — turn off the keyboard auto-repeat keys.

Synopsis

XAutoRepeatOff(display) Display *display;

Arguments

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

Description

XAutoRepeatOff turns off auto-repeat for the keyboard. It sets the keyboard so that holding any non-modal key down will not result in multiple events.

Related Commands

XAutoRepeatOn,XBell,XChangeKeyboardControl,XGetDefault,XGet-KeyboardControl, XGetPointerControl.

Xlib Reference Manual

XAutoRepeatOn \.

v Xlib - User Preferences-Name

XAutoRepeatOn — turn on the keyboard auto-repeat keys.

Synopsis

XAutoRepeatOn (display) Display *display;

Arguments

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

Description

XAutoRepeatOn sets the keyboard to auto-repeat; that is, holding any non-modal key down will result in multiple KeyPress and KeyRelease event pairs with the same keycode member. Keys such as Shift Lock will still not repeat.

Related Commands

XAutoRepeatOff,XBell, XChangeKeyboardControl,XGetDefault,XGet-KeyboardControl, XGetPointerControl.

—Xlib - User Preferences-

f XBell

Name

XBell — ring the bell (Control G).

Synopsis

XBe 11 ( di spl ay, per can t ) Display *display; int percent;

Arguments

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

percent Specifies the volume for the bell, relative to the base volume set with XChangeKeyboardControl. Possible values are -100 (off), through 0 (base volume), to 100 (loudest) inclusive.

Description

Rings the bell on the keyboard at a volume relative to the base volume, if possible, percent can range from -100 to 100 inclusive (else a BadValue error). The volume at which the bell is rung when percent is nonnegative is:

volume = base - [ (base * percent) / 100] + percent and when percent is negative:

volume = base + [(base * percent) / 100]

To change the base volume of the bell, set the bell_percent variable of XChange KeyboardControl.

Errors

BadValue percent < -100 or percent >100.

Related Commands

XAutoRepeatOff,XAutoRepeatOn,XChangeKeyboardControl,XGetDefault, XGetKeyboardControl,XGetPointerControl.

XChangeActivePointerGrab v^

Xlib-Pointer-

Name

XChangeActivePointerGrab — change the parameters of an active pointer grab.

Synopsis

XChangeActivePointerGrab(display, event_mask, cursor, time) Display *display; unsigned, int event_mask; Cursor cursor; Time time;

Arguments

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

event_mask Specifies which pointer events are reported to the client. This mask is the bit wise OR of one or more of these pointer event masks: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, PointerMotionHintMask, Buttonl-MotionMask, Button2MotionMask, ButtonSMotionMask, But-ton4MotionMask, ButtonSMotionMask, ButtonMotionMask, KeymapStateMask.

cursor Specifies the cursor that is displayed. A value of None will keep the current

cursor.

time Specifies the time when the grab should take place. Pass either a timestamp,

expressed in milliseconds, or the constant CurrentTime.

Description

XChangeActivePointerGrab changes the characteristics of an active pointer grab, if the specified time is no earlier than the last pointer grab time and no later than the current X server time. XChangeActivePointerGrab has no effect on the passive parameters of XGrab-Button, or the automatic grab that occurs between ButtonPress and ButtonRelease.

event_mask is always augmented to include ButtonPress and ButtonRelease.

For more information on pointer grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.

Errors

BadCursor

BadValue The event_mask argument is invalid.

Related Commands

XChangePointerControl,XGetPointerControl,XGetPointerMapping, XGrabPointer,XQueryPointer,XSetPointerMapping,XUngrabPointer, XWarpPointer.

—Xlib - Graphics Context-

f XChangeGC

Name

XChangeGC — change the components of a given graphics context.

Synopsis

XChangeGC(display, gc, valuemask, values) Display *display; GC gc;

unsigned long valuemask; XGCValues * values;

Arguments

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

gc Specifies the graphics context.

valuemask Specifies the components in the graphics context that you want to change. This argument is the bitwise OR of one or more of the GC component masks.

val ues Specifies a pointer to the XGCValues structure.

Description

XChangeGC changes any or all of the components of a GC. The valuemask specifies which components are to be changed; it is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (|). The values structure contains the values to be set. These two arguments operate just like they do in XCreateGC. Changing the clip_mask overrides any previous XSetClipRectangles request for this GC. Changing the dash_of f set or dash_list overrides any previous XSetDashes request on this GC.

Since consecutive changes to the same GC are buffered, there is no performance advantage to using this routine over the routines that set individual members of the GC.

Even if an error occurs, a subset of the components may have already been altered.

For more information, see Volume One, Chapter 5, The Graphics Context, and Chapter 6, Drawing Graphics and Text.

Structures

typedef struct {

int function; /* logical operation */

unsigned long plane_mask; /* plane mask */

unsigned long foreground; /* foreground pixel */

unsigned long background; /* background pixel */

int line_width; /* line width */

int line style; /* LineSolid, LineOnOffDash, LineDoubleDash */

int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */

int join style; /* JoinMiter, JoinRound, JoinBevel */

int fill~style; /* FillSolid, FillTiled, FillStippled */

int fill_rule; /* EvenOddRule, WindingRule */

int arc_mode; /* ArcChord, ArcPieSlice */

Pixmap tile; /* tile pixmap for tiling operations */

Pixmap stipple; /* stipple 1 plane pixmap for stipping */

int ts x origin; /* offset for tile or stipple operations */

XChangeGC

(continued)

Xlib-Graphics Context

int ts_y_origin; Font font; int subwindow_mode; Bool graphics exposures; int clip_x_origin; int clip_y_origin; Pixmap clip_mask; int dash_offset; char dashes; } XGCValues;

/* default text font for text operations */

/* ClipByChildren, Includelnferiors */

/* generate events on XCopy, Area, XCopyPlane*/

/* origin for clipping */

/* bitmap clipping; other calls for rects */

/* patterned/dashed line information */

Errors

BadAlloc

BadFont

BadGC

BadMatch

BadPixmap

BadValue

Related Commands

DefaultGC,XCopyGC,XCreateGC, XFreeGC, XGContextFromGC,XGetGCValues, XSetArcMode,XSetBackground, XSetClipMask, XSetClipOrigin,XSetClip-Rectangles,XSetDashes,XSetFillRule,XSetFillStyle,XSetForeground, XSetFunction,XSetGraphicsExposures,XSetLineAttributes,XSetPlane-Mask, XSetRegion,XSetState, XSetStipple, XSetSubwindowMode,XSet-TSOrigin.

Xlib Reference Manual

—Xlib - User Preferences-

J XChangeKeyboardControl

Name

XChangeKeyboardControl — change the keyboard preferences such as key click.

Synopsis

XChangeKeyboardControl(display, value_mask , values) Display * display; unsigned long value_mask; XKeyboardControl * values;

Arguments

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

value_mask Specifies a mask composed of ORed symbols from the table shown in the Structures section below, specifying which fields to set.

values Specifies the settings for the keyboard preferences.

Description

XChangeKeyboardControl sets user preferences such as key click, bell volume and dura tion, light state, and keyboard auto-repeat. Changing some or all these settings may not be pos sible on all servers.

The value_mask argument specifies which values are to be changed; it is made by combin ing any number of the mask symbols listed in the Structures section using bitwise OR (|).

The values structure contains the values to be set, as follows:

key_click_percent sets the volume for key clicks between 0 (off) and 100 (loud) inclu sive. Setting to -1 restores the default.

bell_percent sets the base volume for the bell between 0 (off) and 100 (loud) inclusive. Setting to -1 restores the default.

bell _jpitch sets the pitch (specified in Hz) of the bell. Setting to -1 restores the default.

bell_duration sets the duration (specified in milliseconds) of the bell. Setting to -1 restores the default.

led__mode is either LedModeOn or LedModeOf f. led is a number between 1 and 32 inclu sive that specifies which light's state is to be changed. If both led_mode and led are speci fied, then the state of the LED specified in led is changed to the state specified in led_mode. If only led_mode is specified, then all the LEDs assume the value specified by led_mode.

auto_repeat_mode is either AutoRepeatModeOn, AutoRepeatModeOf f, or Auto-RepeatModeDefault. key is a keycode between 7 and 255 inclusive. If both auto_repeat_mode and key are specified, then the auto-repeat mode of the key specified by key is set as specified by auto_repeat_mode. If only auto_repeat_mode is speci fied, then the global auto repeat mode for the entire keyboard is changed, without affecting the settings for each key. If the auto_repeat_mode is AutoRepeatModeDefault for either case, the key or the entire keyboard is returned to its default setting for the server, which is normally to have all non-modal keys repeat.

Xlib Reference Manual

XChangeKeyboardControl (continued) Xlib - User Preferences

When a key is being used as a modifier key, it does not repeat regardless of the individual or global auto repeat mode.

The order in which the changes are performed is server-dependent, and some may be completed when another causes an error.

For more information on user preferences, see Volume One, Chapter 9, The Keyboard and Pointer.

Structures

/* masks for ChangeKeyboardControl */

#define KBKeyClickPercent (1L«0)

#define KBBellPercent (1L«1)

#define KBBellPitch (1L«2)

#define KBBellDuration (1L«3)

#define KBLed (1L«4)

#define KBLedMode (1L«5)

tdefine KBKey (1L«6)

tdefine KBAutoRepeatMode (1L«7)

/* structure for ChangeKeyboardControl */

typedef struct {

int key_click_percent;

int bell_percent;

int bell_pitch;

int bell_duration;

int led;

int led_mode; /* LedModeOn or LedModeOff */

int key;

int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn,

AutoRepeatModeDefault */ } XKeyboardControl;

Errors

BadMatch values, key specified but values, auto. repeat .mode not specified, values. led specified but values. led_mode not specified.

BadValue values.key_click_percent < -1.

values.bell_percent < -1. values. bell_j3itch < -I. values.bell_duration < -1.

Related Commands

XAutoRepeatOf f, XAutoRepeatOn, XBell, XGetDef ault, XGetKeyboard-Control,XGetPointerControl.

Xlib Reference Manual

— XIib-Keyboard-

J XChangeKeyboardMapping

Name

XChangeKeyboardMapping — change the keyboard mapping. Synopsis

XChangeKeyboardMapping(display, first_code, keysyms_per_code,

keysyms, num_codes) Display * display; int first_keycode; int keysyms_per_keycode; KeySym * keysyms; int num_keycodes;

Arguments

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

fi rs t_keycode

Specifies the first keycode that is to be changed.

keysyms_per_keycode

Specifies the number of keysyms that the caller is supplying for each keycode.

keysyms Specifies a pointer to the list of keysyms.

num_keycodes

Specifies the number of keycodes that are to be changed.

Description

Starting with first_keycode, XChangeKeyboardMapping defines the keysyms for the specified number of keycodes. The symbols for keycodes outside this range remain unchanged. The number of elements in the keysyms list must be a multiple of keysyms_per_keycode (else a BadLength error). The specified first_keycode must be greater than or equal to min_keycode supplied at connection setup and stored in the display structure (else a Bad-Value error). In addition, the following expression must be less than or equal to max_key-code field of the Display structure (else a BadValue error):

max_keycode >= first_keycode + (num_keycodes / keysyms_per_keycode) - 1

The keysym number N (counting from 0) for keycode K has an index in the keysyms array (counting from 0) of the following (in keysyms):

index = (K - first keycode) * keysyms_per_keycode + N

The specified keysyms^per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special keysym value of NoSymbol should be used to fill in unused elements for individual keycodes. It is legal for NoSymbol to appear in nontrail-ing positions of the effective list for a keycode.

XChangeKeyboardMapping generates a MappingNotif y event, sent to this and all other clients, since the keycode to keysym mapping is global to all clients.

XChangeKeyboardMapping (continued) Xlib - Keyboard

Errors

BadAlloc

BadValue first. keycode less than display->min_keycode.

display->max_keycode exceeded (see above).

Related Commands

XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, XGetModifierMapping,XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString,XLookupKeysym, XLookupString, XNewModif ierMap, XQueryKeymap, XRebindKeySym, XRefreshKeyboard-Mapping, XSetModifierMapping, XStringToKeysym.

—Xlib -Pointers-

J XChangePointerControl

Name

XChangePointerControl — change the pointer preferences.

Synopsis

XChangePointerControl(display, do_accel , do_threshold r accel_numerator, accel_denominator, threshold) Display *display; Bool do_accel, do_threshold; int accel_numerator f accel_denominator; int threshold;

Arguments

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

do_accel Specifies a boolean value that controls whether the values for the accel_numerator or accel_denominator are set. You can pass one of these constants: True or False.

do_thresh old

Specifies a boolean value that controls whether the value for the threshold is set. You can pass one of these constants: True or False.

accel_numerator

Specifies the numerator for the acceleration multiplier.

accel_denominator

Specifies the denominator for the acceleration multiplier.

threshold Specifies the acceleration threshold.

Description

XChangePointerControl defines how the pointing device functions. The acceleration is a fraction (accel_numerator/accel_denominator) which specifies how many times faster than normal the sprite on the screen moves for a given pointer movement. Acceleration takes effect only when a particular pointer motion is greater than threshold pixels at once, and only applies to the motion beyond threshold pixels. The values for do_accel and do_ thresh old must be nonzero for the pointer values to be set; otherwise, the parameters will be unchanged. Setting any of the last three arguments to -1 restores the default for that argument.

The fraction may be rounded arbitrarily by the server. Errors

BadValue accel_de/iomiriator isO.

Negative value for do_accel or do_threshold.

Xlib Reference Manual

XChangePolnterControl (continued) Xlib - Pointers

Related Commands

XChangeActivePointerGrab,XGetPointerControl, XGetPointerMapping, XGrabPointer,XQueryPointer,XSetPointerMapping, XUngrabPointer, XWarpPointer.

— Xlib-Properties-

J XChangeProperty

Name

XChangeProperty — change a property associated with a window.

Synopsis

XChangeProperty(display, w, property, type, format, mode,

data, nelements) Display *display; Window w;

Atom property, type; int format; int mode;

unsigned char *data; int nelements;

Arguments

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

w Specifies the ID of the window whose property you want to change,

property Specifies the property atom.

type Specifies the type of the property. X does not interpret the type, but simply

passes it back to an application that later calls XGetProperty.

format Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit

quantities. This information allows the X server to correctly perform byte-swap operations as necessary. If the format is 16-bit or 32-bit, you must explicitly cast your data pointer to a (char *) in the call to XChange Property. Possible values are 8,16, and 32.

mode Specifies the mode of the operation. Possible values are PropMode-

Replace, PropModePrepend, PropModeAppend, or no value.

data Specifies the property data.

n el emen t s Specifies the number of elements in the property.

Description

XChangeProperty changes a property and generates PropertyNotify events if they have been selected.

XChangeProperty does the following according to the mode argument:

• PropModeReplace

Discards the previous property value and stores the new data.

• PropModePrepend

Inserts the data before the beginning of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data, type and format arguments must match the existing property value; otherwise a BadMatch error occurs.

XChangeProperty (continued) Xlib - Properties

• PropModeAppend

Appends the data onto the end of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data, type and format arguments must match the existing property value; otherwise a BadMatch error occurs.

The property may remain defined even after the client which defined it exits. The property becomes undefined only if the application calls XDeleteProperty, destroys the specified window, or closes the last connection to the X server.

The maximum size of a property is server-dependent and can vary dynamically if the server has insufficient memory.

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

Errors

BadAlloc

BadAtom

BadMatch

BadValue

BadWindow

Related Commands

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

— Xlib - Window Save Set-

J XChangeSaveSet

Name

XChangeSaveSet — add or remove a subwindow from the client's save-set.

Synopsis

XChangeSaveSet { display, w, change_mode) Display *display; Window w; int change_mode ;

Arguments

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

w Specifies the ID of the window whose children you want to add or remove

from the client's save-set; it must have been created by some other client.

change_mode Specifies the mode. Pass one of these constants: SetModelnsert (adds the window to this client's save-set) or SetModeDelete (deletes the win dow from this client's save-set).

Description

XChangeSaveSet adds or deletes windows from a client's save-set. This client is usually the window manager.

The save-set of the window manager is a list of other client's top-level windows which have been reparented. If the window manager dies unexpectedly, these top-level application win dows are children of a window manager window and therefore would normally be destroyed. The save-set prevents this by automatically reparenting the windows listed in the save-set to their closest existing ancestor, and then remapping them.

Windows are removed automatically from the save-set by the server when they are destroyed.

For more information on save-sets, see Volume One, Chapter 13, Other Programming Tech niques.

Errors

BadMat ch w not created by some other client.

BadValue BadWindow

Related Commands

XAddToSaveSet,XRemoveFromSaveSet.

XChangeWindowAttributes

•Xlib - Window Attributes-

Name

XChangeWindowAttributes — set window attributes.

Synopsis

XChangeWindowAttributes(display, w f valuemask, attributes) Display *display; Window w;

unsigned long valuemask; XSetWindowAttributes * attributes;

Arguments

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

w Specifies the window ID.

valuemask Specifies which window attributes are defined in the attributes argu ment. The mask is made by combining the appropriate mask symbols listed in the Structures section using bitwise OR (|). If valuemask is zero, the rest is ignored, and attributes is not referenced. The values and restric tions are the same as for XCreateWindow.

attributes Window attributes to be changed. The valuemask indicates which mem bers in this structure are referenced.

Description

XChangeWindowAttributes changes any or all of the window attributes that can be changed. For descriptions of the window attributes, see Volume One, Chapter 4, Window Attri butes.

Changing the background does not cause the window contents to be changed immediately-not until the next Expose event or XClearWindow call. 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. Setting the border causes the border to be repainted immediately. Changing the background of a root window to None or Parent-Relative restores the default background pixmap. Changing the border of a root window to CopyFromParent restores the default border pixmap.

Changing the win_gravity does not affect the current position of the window. Changing the backing_store of an obscured window to WhenMapped or Always may have no immediate effect. Also changing the backing_jplanes, backing_pixel, or save_under of a mapped window may have no immediate effect.

Multiple clients can select input on the same window; the event_mask attributes passed are disjoint. When an event is generated it will be reported to all interested clients. Therefore, the setting of the event_mask attribute by one client will not affect the event_mask of others on the same window. However, at most, one client at a time can select each of SubstructureRedirectMask, ResizeRedirectMask, and ButtonPressMask on any one window. If a client attempts to select on SubtructureRedirectMask, Resize-

Xlib - Window Attributes (continued) XChange Wi n dowAttri bu tes

RedirectMask, or ButtonPressMask and some other client has already selected it on the same window, the X server generates a BadAccess error.

There is only one do_not_propagate_mask for a window, not one per client.

Changing the colormap attribute of a window generates a ColormapNotif y event. Chang ing the colormap attribute of a visible window may have no immediate effect on the screen (because the colormap may not be installed until the window manager calls Xlnstall-Colormap).

Changing the cursor of a root window to None restores the default cursor.

For more information, see Volume One, Chapter 2, X Concepts, and Chapter 4, Window Attri butes.

Structures

* Data structure for setting window attributes.

*/ typedef struct {

Pixmap background_pixmap; /* pixmap. None, or ParentRelative */

unsigned long background_pixel; /* background pixel */

Pixmap border_pixmap; /* pixmap, None, or CopyFromParent */

unsigned long border_pixel; /* border pixel value */

int bit_gravity; /* one of bit gravity values */

int win_gravity; /* one of the window gravity values */

int backing_store; /* NotUseful, WhenMapped, Always */

unsigned long backing_planes; /* planes to be preseved if possible */

unsigned long backing_pixel; /* value to use in restoring planes */

Bool save_under; /* should bits under be saved (popups) */

long event_mask; /* set of events that should be saved */

long do not propagate_mask; /* set of events that should not propagate */

Bool override_redirect; /* override redirected config request */

Colormap colormap; /* colormap to be associated with window */

Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes;

/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes */

#define CWBackPixmap (1L«0)

#define CWBackPixel (1L«1)

#define CWBorderPixmap (1L«2)

#define CWBorderPixel (1L«3)

#define CWBitGravity (1L«4)

#define CWWinGravity (1L«5)

#define CWBackingStore (1L«6)

#define CWBackingPlanes (1L«7)

#define CWBackingPixel (1L«8)

#define CWOverrideRedirect (1L«9)

#define CWSaveUnder (1L«10)

#define CWEventMask (1L«11)

#define CWDontPropagate (1L«12)

fdefine CWColormap (1L«13)

#define CWCursor (1L«14)

XChangeWindOWAttributes (continued) Xlib - Window Attributes

Errors

BadAccess

BadColormap

BadCursor

BadMatch

BadPixmap

BadValue

BadWindow

Related Commands

XGetGeometry, XGetWindowAttributes,XSetWindowBackground, XSet-WindowBackgroundPixmap,XSetWindowBorder, XSetWindowBorderPixmap.

-X,ib - input Handling / XCheCklfEvent

Name

XChecklfEvent — check the event queue for a matching event.

Synopsis

Bool XChecklfEvent(display, event, predicate, arg) Display *display;

XEvent * event; /* RETURN */

Bool (*predicate) () ; char *arg;

Arguments

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

event Returns the matched event.

predicate Specifies the procedure that is called to determine if the next event matches your criteria.

arg Specifies the user-specified argument that will be passed to the predicate pro

cedure.

Description

XChecklfEvent returns the next event in the queue that is matched by the specified predi cate procedure. If found, that event is removed from the queue, and True is returned. If no match is found, XChecklfEvent returns False and flushes the request buffer. No other events are removed from the queue. Later events in the queue are not searched.

The predicate procedure is called with the arguments display, event, and arg. For more information, see Volume One, Chapter 8, Events.

Related Commands

QLength, XAllowEvents,XCheckMaskEvent,XCheckTypedEvent,XCheck-TypedWindowEvent,XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGetMotionEvents,XlfEvent,XMaskEvent,XNextEvent, XPeekEvent, XPeek-IfEvent,XPending,XPutBackEvent,XSelectInput,XSendEvent,XSetInput-Focus, XSynchronize,XWindowEvent.

XCheckMaskEvent \ xnb _ lnputH and,,n g -

Name

XCheckMaskEvent — remove the next event that matches mask; don't wait.

Synopsis

Bool XCheckMaskEvent(display, event_mask, event) Display * display; long event_mask; XEvent * event; /* RETURN */

Arguments

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

event_mask Specifies the event types to be returned. See list under XSelect Input. event Returns a copy of the matched event's XEvent structure.

Description

XCheckMaskEvent removes the next event in the queue that matches the passed mask. The event is copied into an XEvent supplied by the caller and XCheckMaskEvent returns True. Other events earlier in the queue are not discarded. If no such event has been queued, XCheckMaskEvent flushes the request buffer and immediately returns False, without wait ing.

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

QLength, XAllowEvents,XChecklfEvent,XCheckTypedEvent,XCheckTyped-WindowEvent,XCheckWindowEvent,XEventsQueued,XGetlnputFocus,XGet-MotionEvents,XlfEvent,XMaskEvent,XNextEvent,XPeekEvent,XPeek-IfEvent,XPending, XPutBackEvent,XSelectlnput, XSendEvent, XSetlnput-Focus,XSynchronize,XWindowEvent.

— Xlib-Input Handling-

J XCheckTypedEvent

Name

XCheckTypedEvent — return the next event in queue that matches event type; don't wait.

Synopsis

Bool XCheckTypedEvent(display, event_type, report) Display *display; int event_type ; XEvent * report; /* RETURN */

Arguments

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

event_type Specifies the event type to be compared. report Returns a copy of the matched event structure.

Description

XCheckTypedEvent searches first the event queue, then the events available on the server connection, for the specified even t_type. If there is a match, it returns the associated event structure. Events searched but not matched are not discarded. XCheckTypedEvent returns True if the event is found. If the event is not found, XCheckTypedEvent flushes the request buffer and returns False.

This command is similar to XCheckMaskEvent, but it searches through the queue instead of inspecting only the last item on the queue. It also matches only a single event type instead of multiple event types as specified by a mask.

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

QLength, XAllowEvents,XChecklfEvent,XCheckMaskEvent,XCheckTyped-WindowEvent,XCheckWindowEvent,XEventsQueued,XGetlnputFocus,XGet-MotionEvents,XlfEvent,XMaskEvent,XNextEvent,XPeekEvent,XPeek-IfEvent, XPending,XPutBackEvent,XSelectlnput,XSendEvent,XSetlnput-Focus,XSynchronize,XWindowEvent.

XCheckTypedWindowEvent \

x ,ib-

Name

XCheckTypedWindowEvent — return the next event in queue matching type and window.

Synopsis

Bool XCheckTypedWindowEvent ( display, w, event _ty pe , report) Display * display; Window w; int event_type; XEvent * report; /* RETURN */

Arguments

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

w Specifies the window ID.

even t_ type Specifies the event type to be compared.

report Returns the matched event's associated structure into this client-supplied

structure.

Description

XCheckTypedWindowEvent searches first the event queue, then any events available on the server connection, for an event that matches the specified window and the specified event type. Events searched but not matched are not discarded.

XCheckTypedWindowEvent returns True if the event is found; it flushes the request buffer and returns False if the event is not found.

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

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-Event, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGetMotion-Events, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeeklf Event, XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnputFocus, XSynchronize, XWindowEvent.

-Xllb- Input Handling / XCheCkWIndOWEvent

Name

XCheckWindowEvent — remove the next event matching both passed window and passed mask; don't wait.

Synopsis

Bool XCheckWindowEvent(display, w, event_mask r event) Display * display; Window w; long event_mask; XEvent * event; /* RETURN */

Arguments

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

w Specifies the window ID. The event must match both the passed window and

the passed event mask.

even t_mask Specifies the event mask. See XSelect Input for a list of mask elements. event Returns the XEvent structure.

Description

XCheckWindowEvent removes the next event in the queue that matches both the passed window and the passed mask. If such an event exists, it is copied into an XEvent supplied by the caller. Other events earlier in the queue are not discarded.

If a matching event is found, XCheckWindowEvent returns True. If no such event has been queued, it flushes the request buffer and returns False, without waiting.

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

QLength,XAllowEvents,XChecklfEvent, XCheckMaskEvent, XCheckTyped-Event, XCheckTypedWindowEvent, XEventsQueued, XGetlnputFocus, XGet-MotionEvents,XlfEvent,XMaskEvent,XNextEvent,XPeekEvent,XPeek-IfEvent, XPending,XPutBackEvent,XSelectlnput,XSendEvent,XSetlnput-Focus, XSynchronize,XWindowEvent.

Xlib Reference Manual

XCirculateSubwindows

•Xlib - Window Manipulation-Name

XCirculateSubwindows — circulate the stacking order of children up or down.

Synopsis

XCirculateSubwindows( display, w, direction) Display *display; Window w; int direction;

Arguments

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

w Specifies the window ID of the parent of the subwindows to be circulated.

direction Specifies the direction (up or down) that you want to circulate the children. Pass either RaiseLowest or LowerHighest.

Description

XCirculateSubwindows circulates the children of the specified window in the specified direction, either RaiseLowest or LowerHighest. If some other client has selected SubstructureRedirectMask on the specified window, then a CirculateRequest event is generated, and no further processing is performed. If you specify RaiseLowest, this function raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, this function lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is performed on formerly obscured windows.

For more information, see Volume One, Chapter 14, Window Management.

Errors

BadValue BadWindow

Related Commands

XCirculateSubwindowsDown,XCirculateSubwindowsUp, XConfigureWindow, XLowerWindow, XMoveResizeWindow,XMoveWindow,XQueryTree, XRaise-Window, XReparentWindow,XResizeWindow, XRestackWindows.

-x..b-w,ndowMan. pu .at,on ' XCirculateSubwindowsDown

Name

XCirculateSubwindowsDown — circulate the bottom child to the top of the stacking order.

Synopsis

XCirculateSubwindowsDown(display, w) Display * display ; Window w;

Arguments

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

w Specifies the window ID of the parent of the windows to be circulated.

Description

XCirculateSubwindowsDown lowers the highest mapped child of the specified window that partially or completely obscures another child. The lowered child goes to the bottom of the stack. Completely unobscured children are not affected.

This function generates exposure events on any window formerly obscured. Repeated execu tions lead to round-robin lowering. This is equivalent to XCirculateSubwindows (dis play, w, LowerHighest).

If some other client has selected SubstructureRedirectMask on the window, then a CirculateRequest event is generated, and no further processing is performed. This allows the window manager to intercept this request when w is the root window. Usually, only the window manager will call this on the root window.

For more information, see Volume One, Chapter 14, Window Management.

Errors

BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsUp,XConfigureWindow, XLowerWindow,XMoveResizeWindow,XMoveWindow,XQueryTree,XRaise-Window, XReparentWindow,XResizeWindow, XRestackWindows.

Xlib Reference Manual

XCirculateSubwindowsUp , vn

v Xlib - Window Manipulation —

Name

XCirculateSubwindowsUp — circulate the top child to the bottom of the stacking order.

Synopsis

XCirculateSubwindowsUp (display, w) Display * display; Window w;

Arguments

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

w Specifies the window ID of the parent of the windows to be circulated.

Description

XCirculateSubwindowsUp raises the lowest mapped child of the specified window that is partially or completely obscured by another child. The raised child goes to the top of the stack. Completely unobscured children are not affected. This generates exposure events on the raised child (and its descendents, if any). Repeated executions lead to round robin-raising. This is equivalent to XCirculateSubwindows (display, w, RaiseLowest).

For more information, see Volume One, Chapter 14, Window Management.

Errors

BadWindow

Related Commands

XCirculateSubwindows, XCirculateSubwindowsDown, XConfigureWindow, XLowerWindow, XMoveResizeWindow,XMoveWindow,XQueryTree, XRaise-Window, XReparentWindow,XResizeWindow, XRestackWindows.

—Xllb - Drawing Primitives '

Name

XClearArea — clear a rectangular area in a window. Synopsis

XClearArea(display, w, x, y, width, height, exposures) Display *display; Window w; int x f y;

unsigned int width, height; Bool exposures;

Arguments

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

w Specifies the ID of an input Output window.

x Specify the x and y coordinates of the upper-left corner of the rectangle to be

y cleared, relative to the origin of the window.

wi dth Specify the dimensions in pixels of the rectangle to be cleared.

height

exposures Specifies whether exposure events are generated. Must be either True or False.

Description

XClearArea clears a rectangular area in a window.

If width is zero, the window is cleared from x to the right edge of the window. If height is zero, the window is cleared from y to the bottom of the window. See figure above..

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled with a plane_mask of all 1's, a function of GXcopy, and a subwindow_mode of ClipByChildren. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, then one or more exposure events are gen erated for regions of the rectangle that are either visible or are being retained in a backing store.

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

Xlib Reference Manual

XCIearArea

(continued)

Xlib - Drawing Primitives

Window

[x,y] width

Window

[x,y] width

Window

[x,y] width = 0

Window

[x,y] width = 0

Errors

BadMatch BadValue BadWindow

Window is an inputOnly class window.

Related Commands

XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDraw-Filled, XDrawLine,XDrawLines,XDrawPoint,XDrawPoints,XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArc,XFillArcs, XFillPolygon, XFillRectangle,XFillRectangles.

Xlib Reference Manual

-Xlib-Drawing Primitives /

Name

XClearWindow — clear an entire window.

Synopsis

XClearWindow(display, w) Display *display; Window W,

Arguments

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

w Specifies the ID of the window to be cleared.

Description

XClearWindow clears a window, but does not cause exposure events. This function is equiv alent to XClearArea (display, w, 0, 0, 0, 0, False).

If the window has a defined background tile or it is ParentRelative, the rectangle is tiled with a plane_mask of all 1's and function of GXcopy. If the window has background None, the contents of the window are not changed.

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

Errors

BadMatch If vis an InputOnly class window.

BadValue BadWindow

Related Commands

XClearArea,XCopyArea,XCopyPlane,XDraw, XDrawArc, XDrawArcs, XDraw-Filled,XDrawLine,XDrawLines,XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArc,XFillArcs,XFillPolygon, XFillRectangle,XFillRectangles.

XCIipBox ~\

X Xlib - Regions-Name

XCIipBox — generate the smallest rectangle enclosing a region.

Synopsis

XCIipBox (r, rect) Region r; XRectangle *rect; /* RETURN */

Arguments

r Specifies the region.

rect Returns the smallest rectangle enclosing region r.

Description

XCIipBox returns the smallest rectangle that encloses the given region.

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

Structures

Region is a pointer to an opaque structure type.

Related Commands

XCreateRegion,XDestroyRegion,XEmptyRegion,XEqualRegion, XIntersectRegion,XOffsetRegion,XPointlnRegion, XPolygonRegion, XRectInRegion,XSetRegion,XShrinkRegion, XSubtractRegion,XUnion-RectWithRegion,XUnionRegion, XXorRegion.

Xlib Reference Manual

—Xlib-HouseKeeping-

J XCIoseDisplay

Name

XCIoseDisplay — disconnect a client program from an X server and display.

Synopsis

XCIoseDisplay(display) Display *display;

Arguments

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

Description

XCIoseDisplay closes the connection between the current client and the X server specified by the Display argument.

The XCIoseDisplay routine destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources (GCs) that the client application has created on this display, unless the close down mode of the client's resources has been changed by XSetCloseDownMode. Therefore, these windows, resource IDs, and other resources should not be referenced again. In addition, this routine discards any requests that have been buffered but not yet sent to the server.

Although these operations automatically (implicitly) occur when a process exits under UNIX, you should call XCIoseDisplay anyway.

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

Def aultScreen, XFree, XNoOp, XOpenDisplay.

XConfigureWindow . V|

v Xlib - Window Manipulation —

Name

XConfigureWindow — change the window position, size, border width, or stacking order.

Synopsis

XConf igureWindow ( display, i/, value_mask, values) Display * display; Window w;

unsigned int value_mask; XWindowChanges * values;

Arguments

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

w Specifies the ID of the window to be reconfigured.

value_mask Specifies which values are to be set using information in the values struc ture, val ue_mask is the bitwise OR of any number of symbols listed in the Structures section below.

val ues Specifies a pointer to the XWindowChanges structure containing new confi

guration information. See the Structures section below.

Description

XConfigureWindow changes the window position, size, border width, and/or the stacking order. If selected, a Conf igureNot if y event is generated to announce any changes.

If the window to be reconfigured is a top-level window, there will be interaction with the win dow manager if the override_redirect attribute of the window is False. In this case, the X server sends a Conf igureRequest event to the window manager and does not recon figure the window. The window manager receives this event and then makes the decision whether to allow the application to reconfigure its window. The client should wait for the Conf igureNot if y event to find out the size and position of the window.

In Release 4, XReconf igureWMWindow should be used instead of XConfigureWindow for top-level windows. This routine handles restacking of top-level windows properly.

If a window's size actually changes, the window's subwindows may move according to their window gravity. If they do, GravityNotif y events will be generated for them. Depending on the window's bit gravity, the contents of the window also may be moved. See Volume One, Chapter 4, Window Attributes for further information.

Exposure processing is performed on formerly obscured windows, including the window itself and its inferiors, if regions of them were obscured but afterward are not. As a result of increas ing the width or height, exposure processing is also performed on any new regions of the win dow and any regions where window contents are lost.

The members of XWindowChanges that you specify in val ues are:

go Xlib Reference Manual

Xlib - Window Manipulation

(continued)

XConfigureWindow

x Specify the x and y coordinates of the upper-left outer comer of the window

y relative to the parent's origin.

width Specify the inside size of the window in pixels, not including the border.

height These arguments must be positive.

horde r_width

Specifies the width of the border in pixels.

sibling Specifies the sibling window for stacking operations. If not specified, no

change in the stacking order will be made. If specified, stack_mode must also be specified.

stack_mode The stack mode can be any of these constants: Above, Below, Toplf, Bottomlf, or Opposite.

The computation for the Bottomlf, Toplf, and Opposite stacking modes is performed with respect to window i/s final size and position (as controlled by the other arguments to XConfigureWindow, not its initial position.) It is an error if sibling is specified without stack_mode. If sibling and stack_mode are specified, the window is restacked as fol lows:

Stacking Flag Position

Above Below Toplf

Bottomlf Opposite

w is placed just above sibling w is placed just below sibling

if sibling obscures w, then w is placed at the top of the stack

if w obscures sibling, then w is placed at the bot tom of the stack

if sibling occludes v/, then w is placed at the top of the stack. If w occludes sibling, then w is placed at the bottom of the stack. If wand sibling do not overlap, no change is made.

Xlib Reference Manual

XConfigureWindOW (continued) Xlib - Window Manipulation

If a stack_mode is specified but no sibling is specified, the window is restocked as follows:

Stacking Flag

Above Below Toplf

Bottomlf Opposite

Position

w is placed at the top of the stack w is placed at the bottom of the stack

if any sibling obscures w, then w is placed at the top of the stack

if w obscures any sibling, then window is placed at the bottom of the stack

if any sibling occludes w, then w is placed at the top of the stack, else if w occludes any sibling, then w is placed at the bottom of the stack

Under Release 4, use XReconf igureWMWindow to configure a top-level window. Structures

typedef struct {

int x, y;

int width, height;

int border_width;

Window sibling;

int stack_mode; } XWindowChanges;

/* ConfigureWindow structure */

/* ChangeWindow value bits definitions for valuemask */

tdefine CWX (1«0)

#define CWY (1«1)

#define CWWidth (1«2)

tdefine CWHeight (1«3)

#define CWBorderWidth (1«4)

#define CWSibling (1«5)

#define CWStackMode (1«6)

Errors

BadMatch

Attempt to set any invalid attribute of InputOnly window. sibling specified without a stack_mode. The sibling window is not actually a sibling.

BadValue width or height isO. BadWindow

Xlib Reference Manual

Xlib - Window Manipulation (continued) XConf IgureWlndOW

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown,XCirculate-SubwindowsUp, XLowerWindow, XMoveResizeWindow, XMoveWindow, XQuery-Tree, XReconf igureWMWindow, XRaiseWindow, XReparentWindow, XResize-Window,XRestackWindows.

XConvertSelection A

Name

XConvertSelection — use the value of a selection.

Synopsis

XConvertSelection( display, selection, target, property,

requestor, time) Display * display; Atom selection, target;

Atom property; /* may be None */

Window requestor; Time time;

Arguments

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

selection Specifies the selection atom. XA_PRIMARY and XA_SECONDARY are the stan dard selection atoms.

target Specifies the atom of the type property that specifies the desired format for

the data.

property Specifies the property in which the requested data is to be placed. None is also valid, but current conventions specify that the requestor is in a better position to select a property than the selection owner.

requestor Specifies the requesting window.

time Specifies the time when the conversion should take place. Pass either a

timestamp, expressed in milliseconds, or the constant CurrentTime.

Description

XConvertSelection causes a SelectionRequest event to be sent to the current selec tion owner if there is one, specifying the property to store the data in (selection), the format to convert that data into before storing it (target), the property to place the information in (property), the window that wants the information (requestor), and the time to make the conversion (time).

The selection owner responds by sending a SelectionNotify event, which confirms the selected atom and type. If no owner for the specified selection exists, or if the owner could not convert to the type specified by requestor, the X server generates or the owner sends a SelectionNotify event to the requestor with property None. Whether or not the owner exists, the arguments are passed unchanged. See Volume One, Chapter I0,lnterclient Commu nication, for a description of selection events and selection conventions.

Errors

BadAtom BadWindow

Related Commands

XGetSelectionOwner,XSetSelectionOwner.

— Xlib - Drawing Primitives-

J XCopyArea

Name

XCopyArea — copy an area of a drawable.

Synopsis

XCopyArea(display, src, dest, gc, src_x, src_y, width,

height, dest_x, dest_y) Display *display; Drawable src, dest; GC gc;

int src_x, src_y; unsigned int width, height; int dest_x, dest_y;

Arguments

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

src Specify the source and destination rectangles to be combined, src and

dest dest must have the same root and depth.

gc Specifies the graphics context.

src_x Specify the x and y coordinates of the upper-left corner of the source rectan-

src_y gle relative to the origin of the source drawable.

width Specify the dimensions in pixels of both the source and destination rectan-

height gles.

dest_x Specify the x and y coordinates within the destination window.

dest_y

Description

XCopyArea combines the specified rectangle of src with the specified rectangle of dest. src and dest must have the same root and depth.

If regions of the source rectangle are obscured and have not been retained in back-ing_store, or if regions outside the boundaries of the source drawable are specified, then those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing_store. If dest is a window with a background other than None, the corresponding regions of the destination are tiled (with plane_mask of all 1's and function GXcopy) with that background. Regardless of tiling, if the destination is a window and graphics_exposures in gc is True, then Graphics-Expose events for all corresponding destination regions are generated. If graph-ics_exposures is True but no regions are exposed, then a NoExpose event is generated.

If regions of the source rectangle are not obscured and graphics_exposures is False, one NoExpose event is generated on the destination.

Xlib Reference Manual 95

XCopyArea (continued) Xlib - Drawing Primitives

XCopyArea uses these graphics context components: function, plane_mask, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and clip_mask.

Errors

BadDrawable

BadGC

BadMatch The src and dest rectangles do not have the same root and depth.

Related Commands

XClearArea, XClearWindow, XCopyPlane, XDraw, XDrawArc, XDrawArcs, XDrawFilled,XDrawLine,XDrawLines,XDrawPoint,XDrawPoints,XDraw-Rectangle, XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFill-Polygon,XFillRectangle,XFillRectangles.

—Xlib-Colormaps-

j XCopyColormapAndFree

Name

XCopyColormapAndFree — copy a colormap and return a new colormap ID.

Synopsis

Colormap XCopyColormapAndFree( display f cmap) Display *display; Colormap cmap;

Arguments

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

cmap Specifies the colormap you are moving out of.

Description

XCopyColormapAndFree is used to obtain a new virtual colormap when allocating color-cells out of a previous colormap has failed due to resource exhaustion (that is, too many cells or planes were in use in the original colormap).

XCopyColormapAndFree moves all of the client's existing allocations from cmap to the returned Colormap and frees those entries in cmap. The visual type and screen for the new colormap is the same as for the old.

If cmap was created by the client with the all oc argument set to AllocAll, the new color-map is also created with AllocAll, all color values for all entries are copied from cmap, and then all entries in cmap are freed.

If cmap was created by the client with AllocNone, the allocations to be moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAlloc-NamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been freed since they were allocated. Values in other entries of the new Colormap are undefined.

For more information, see Volume One, Chapter 7, Color.

Errors

BadAlloc BadColormap

Related Commands

DefaultColormap, DisplayCells,XCreateColormap, XFreeColormap, XGet-StandardColormap,XInstallColormap, XListlnstalledColormaps,XSet-StandardColormap,XSetWindowColormap, XUninstallColormap.

Xlib Reference Manual

Py V xiib - Graphics Context-

Name

XCopyGC — copy a graphics context.

Synopsis

XCopyGC (display, src, valuemask, dest) Display *display; GC src, dest; unsigned long valuemask;

Arguments

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

src Specifies the components of the source graphics context.

valuemask Specifies the components in the source GC structure to be copied into the des tination GC. valuemask is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (|).

dest Specifies the destination graphics context.

Description

XCopyGC copies the selected elements of one graphics context to another. See Volume One, Chapter 5, The Graphics Context, for a description of the graphics context.

Structures

The GC structure contains the following elements:

* Data structure for setting graphics context.

*/ typedef struct {

int function; /* logical operation */

unsigned long plane_mask; /* plane mask */

unsigned long foreground; /* foreground pixel */

unsigned long background; /* background pixel */

int line_width; /* line width */

int line_style; /* Solid, OnOffDash, DoubleDash */

int cap_style; /* NotLast, Butt, Round, Projecting */

int join_style; /* Miter, Round, Bevel */

int fill_style; /* Solid, Tiled, Stippled */

int fill_rule; /* EvenOdd, Winding */

int arc_mode; /* PieSlice */

Pixmap tile; /* tile pixmap for tiling operations */

Pixmap stipple; /* stipple 1 plane pixmap for stipping */

int ts_x_origin; /* offset for tile or stipple operations */

int ts_y_origin;

Font font; /* default text font for text operations */

int subwindow_mode; /* ClipByChildren, Includelnferiors */

Bool graphics_exposures; /* boolean, should exposures be generated */

int clip_x_origin; /* origin for clipping */

Xlib-Graphics Context (continued) XCopyGC

int clip_y_origin;

Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */

char dashes; } XGCValues;

#define GCFunction

#define GCPlaneMask

tdefine GCForeground

#define GCBackground

#define GCLineWidth

#define GCLineStyle

#define GCCapStyle

tdefine GCJoinStyle

tdefine GCFillStyle

tdefine GCFillRule

#define GCTile

#define GCStipple

#define GCTileStipXOrigin

tdefine GCTileStipYOrigin

tdefine GCFont

tdefine GCSubwindowMode

tdefine GCGraphicsExposures

tdefine GCClipXOrigin

tdefine GCClipYOrigin

tdefine GCClipMask

tdefine GCDashOffset (1L«20)

tdefine GCDashList (1L«21)

tdefine GCArcMode (1L«22)

Errors

BadAlloc

BadGC

BadMatch src and dest do not have the same root and depth.

Related Commands

Def aultGC, XChangeGC, XCreateGC, XFreeGC, XGContextFromGC, XGet-GCValues, XSetArcMode,XSetBackground,XSetClipMask,XSetClipOrigin, XSetClipRectangles,XSetDashes,XSetFillRule, XSetFillStyle,XSet-Foreground,XSetFunction,XSetGraphicsExposures,XSetLineAttributes, XSetPlaneMask,XSetState,XSetStipple,XSetSubwindowMode,XSet-TSOrigin.

XCopyPlane \ xnb _ Drawlng

Name

XCopyPlane — copy a single plane of a drawable into a drawable with depth, applying pixel values.

Synopsis

XCopyPlane( display, src, dest, gc, src_x r src_y r width,

height, dest_x, dest_y, plane) Display *display; Drawable src, dest', GC gc;

int src_x, src_y; unsigned int width, height; int dest_x, dest_y; unsigned long plane;

Arguments

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

src Specify the source and destination drawables.

dest

gc Specifies the graphics context.

src_x Specify the x and y coordinates of the upper-left corner of the source rectan-

src_y gle relative to the origin of the drawable.

width Specify the width and height in pixels. These are the dimensions of both the

height source and destination rectangles.

dest_x Specify the x and y coordinates at which the copied area will be placed rela-

dest_y live to the origin of the destination drawable.

plane Specifies the source bit-plane. You must set exactly one bit, and the bit must

specify a plane that exists in src.

Description

XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a corre sponding rectangle in the destination. The plane of the source drawable and the f ore-ground/background pixel values in gc are combined to form a pixmap of the same depth as the destination drawable, and the equivalent of an XGopyArea is performed, with all the same exposure semantics.

XCopyPlane uses these graphics context components: function, plane_mask, foreground,background, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and clip_mask.

The src and dest drawables must have the same root, but need not have the same depth. For more information, see Volume One, Chapter 5, The Graphics Context.

Xlib - Drawing Primitives (continued) XCopyPlane

Errors

BadDrawable

BadGC

BadMatch src and dest do not have the same root

BadValue plane does not have exactly one bit set, or bit specified in plane is not a plane in src.

Related Commands

XClearArea, XClearWindow, XCopyArea, XDraw, XDrawArc, XDrawArcs, XDraw-Filled, XDrawLine,XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles,XDrawSegments,XFillArc, XFillArcs, XFillPolygon, XFillRectangle,XFillRectangles.

XCreateAssocTable

Xlib - Association Tables—

Name

XCreateAssocTable — create a new association table (X10).

Synopsis

XAssocTable *XCreateAssocTable(size) int size;

Arguments

si ze Specifies the number of buckets in the hashed association table.

Description

XCreateAssocTable creates an association table, which allows you to associate your own structures with X resources in a fast lookup table. This function is provided for compatibility with X Version 10. To use it you must include the file <Xll/X10.h> and link with the library -loldX.

The size argument specifies the number of buckets in the hash system of XAssocTable. For reasons of efficiency the number of buckets should be a power of two. Some size sugges tions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per buckets is 8.

If there is an error allocating memory for the XAssocTable, a NULL pointer is returned. For more information on association tables, see Volume One, Appendix E,X10 Compatibility.

Structures

typedef struct {

XAssoc *buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */

} XAssocTable;

Related Commands

XDeleteAssoc,XDestroyAssocTable,XLookUpAssoc, XMakeAssoc.

— Xlib - Pixmaps and Tiles-

J XCreateBitmapFromData

Name

XCreateBitmapFromData — create a bitmap from xil bitmap format data.

Synopsis

Pixmap XCreateBitmapFromData(display, drawable, data,

width, height) Display *display; Drawable drawable; char *data; unsigned int width, height;

Arguments

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

drawable Specifies a drawable. This determines which screen to create the bitmap on. data Specifies the bitmap data, in XI1 bitmap file format.

width Specify the dimensions in pixels of the created bitmap. If smaller than the

height bitmap data, the upper-left corner of the data is used.

Description

XCreateBitmapFromData creates a single-plane pixmap from an array of hexadecimal data. This data may be defined in the program or included. The bitmap data must be in X ver sion 11 format as shown below (it cannot be in X10 format). The following format is assumed for the data, where the variables are members of the ximage structure described in Volume One, Chapter 6, Drawing Graphics and Text:

format=XYP ixmap

bit_order=LSBFirst

byte_order=LSBFirst

bitmap_unit=8

bitmap_pad=8

xof fset=0

no extra bytes per line

XCreateBitmapFromData creates an image with the specified data and copies it into the created pixmap. The following is an example of creating a bitmap:

tdefine gray__width 16

tdefine gray_height 16

tdefine gray_x_hot 8

tdefine gray_y_hot 8

static char gray_bits[] = {

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

XCreateBitmapFromData (continued) Xlib - Pixmaps and Tiles

Ox7e, Ox7e, Ox7f, Oxfe, 0x37, Oxec, Oxbb, Oxdd, Ox9c, 0x39, Oxcf, Oxf3, Oxe3, Oxc7, Oxf8, Oxlf};

Pixmap XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);

If the call could not create a pixmap of the requested size on the server, XCreateBitmap FromData returns 0 (zero), and the server generates a BadAlloc error. If the requested depth is not supported on the screen of the specified drawable, the server generates a Bad-Match error.

The user should free the bitmap using XFreePixmap when it is no longer needed. For more information, see Volume One, Chapter 6, Drawing Graphics and Text.

Errors

BadAlloc Server has insufficient memory to create bitmap.

BadDrawable

BadValue Specified bitmap dimensions are zero. Related Commands

XCreatePixmap,XCreatePixmapFromBitmapData,XCreatePixmapFrom-BitmapData,XFreePixmap,XQueryBestSize, XQueryBestStipple,XQuery-BestTile,XReadBitmapFile,XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,XWriteBitmapFile.

— Xlib - Colormaps-

J XCreateColormap

Name

XCreateColormap — create a colormap.

Synopsis

Colormap XCreateColormap(display, w, visual, alloc) Display *display; Window w; Visual *visual; int alloc;

Arguments

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

w Specifies a window ID. The colormap created will be associated with the

same screen as the window.

visual Specifies a pointer to the visual structure for the colormap. The visual

class and depth must be supported by the screen.

alloc Specifies how many colormap entries to allocate. Pass either AllocNone or

AllocAll.

Description

XCreateColormap creates a colormap of the specified visual type and allocates either none or all of its entries, and returns the colormap ID.

It is legal to specify any visual class in the structure pointed to by the visual argument. If the class is StaticColor, StaticGray, or TrueColor, the colorcells will have pre-allocated read-only values defined by the individual server but unspecified by the XI1 protocol. In these cases, alloc must be specified as AllocNone (else a BadMatch error).

For the other visual classes, Pseudocolor, DirectColor, and Grayscale, you can pass either AllocAll or AllocNone to the alloc argument. If you pass AllocNone, the colormap has no allocated entries. This allows your client programs to allocate read-only colorcells with XAllocColor or read/write cells with XAllocColorCells, Alloc-ColorPlanes and XStoreColors. If you pass the constant AllocAll, the entire color-map is allocated writable (all the entries are read/write, nonshareable and have undefined initial RGB values), and the colors can be set with XStoreColors. However, you cannot free these entries with XFreeColors, and no relationships between the entries are defined.

If the visual class is Pseudocolor or Grayscale and alloc is AllocAll, this function simulates a call to the function XAllocColor cells returning all pixel values from 1 to (map_entries - 1). For a visual class of DirectColor, the processing for AllocAll simulates a call to the function XAllocColorPlanes, returning a pixel value of 0 and mask values the same as the red__mask, green_mask, and blue_mask members in visual.

XCreateColormap (continued) Xlib - Colormaps

The visual argument should be as returned from the Def aultvisual macro, XMatch-Visuallnf o, or XGetVisuallnf o.

If the hardware colormap on the server is immutable, and therefore there is no possibility that a virtual colormap could ever be installed, XCreateColormap returns the default colormap. Code should check the returned ID against the default colormap to catch this situation.

For more information on creating colormaps, see Volume One, Chapter 7, Color.

Errors

BadAlloc

BadMatch Didn't use AllocNone for StaticColor, StaticGray, or True-Color, visual type not supported on screen.

BadValue BadWindow

Related Commands

DefaultColormap, DisplayCells,XCopyColormapAndFree, XFreeColormap, XGetStandardColormap,XInstallColormap, XListlnstalledColormaps, XSetStandardColormap,XSetWindowColormap,XUninstallColormap.

— Xlib- Cursors-

XCreateFontCursor

Name

XCreateFontCursor — create a cursor from the standard cursor font.

Synopsis

#include <Xll/cursorf ont .h> Cursor XCreateFontCursor ( display,

Display * display ;

unsigned int shape;

shape)

Arguments

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

shape Specifies which character in the standard cursor font should be used for the cur

sor.

Description

X provides a set of standard cursor shapes in a special font named "cursor." Programs are encouraged to use this interface for their cursors, since the font can be customized for the indi vidual display type and shared between clients.

The hotspot comes from the information stored in the font. The initial colors of the cursor arc black for the foreground and white for the background. XRecolorCursor can be used to change the colors of the cursor to those desired.

For more information about cursors and their shapes in fonts, see Appendix I, The Cursor Font.

•a

X//6 Reference Manual

XCreateFontCursor (continued) Xlib - Cursors

Errors

BadAlloc

BadFont

BadValue The shape argument does not specify a character in the standard cursor font.

Related Commands

XCreateGlyphCursor, XCreatePixmapCursor,XDefineCursor, XFreeCursor, XQueryBestCursor,XQueryBestSize,XRecolorCursor, XUndefineCursor.

— Xlib - Graphics Context-

XCreateGC

Name

XCreateGC — create a new graphics context for a given screen with the depth of the specified drawable.

Synopsis

GC XCreateGC(display, drawable, valuemask, values) Display *display; Drawable drawable; unsigned long valuemask; XGCValues * values;

Arguments

di splay drawable

valuemask values

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

Specifies a drawable. The created GC can only be used to draw in drawables of the same depth as this drawable.

Specifies which members of the GC are to be set using information in the values structure, valuemask is made by combining any number of the mask symbols listed in the Structures section.

Specifies a pointer to an XGCValues structure which will provide compo nents for the new GC.

Description

XCreateGC creates a new graphics context resource in the server. The returned GC can be used in subsequent drawing requests, but only on drawables on the same screen and of the same depth as the drawable specified in the drawable argument.

The specified components of the new graphics context in valuemask are set to the values passed in the val ues argument. Unset components default as follows:

Component Value

plane_mask

foreground

background

line_width

line_style

cap_style

join_style

fill_style

fill_rule

arc_mode

tile

stipple

alll's

LineSolid

CapButt

JoinMiter

FillSolid

EvenOddRule

ArcPieSlice

Pixmap filled with foreground pixel

Pixmap filled with 1's

Xlib Reference Manual

XCreateGC

(continued)

Xlib - Graphics Context

An application should minimize the number of GCs it creates, because some servers cache a limited number of GCs in the display hardware, and can attain better performance with a small number of GCs.

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

Errors

BadAlloc Server could not allocate memory for GC.

BadDrawable Specified drawable is invalid.

BadFont Font specified for font component of GC has not been loaded.

BadMatch Pixmap specified for tile component has different depth or is on different screen from the specified drawable. Or pixmap specified for stipple or clip_mask component has depth other than 1.

BadPixmap Pixmap specified for tile, stipple, or clip_mask components is inva lid.

BadValue Values specified for function, line_style, cap_style, join_style, fill_style, fill_rule, subwindow_mode, graph-ics_exposures, dashes, or arcjmode are invalid, or invalid mask specified for valuemask argument.

Structures

typedef struct {

int function; /*

unsigned long plane mask; /*

unsigned long foreground; /*

unsigned long background; /*

int line_width; /*

int line_style; /*

int cap_style; /*

int join_style; /*

int fill_style; /*

int fill rule; /*

logical operation */

plane mask */

foreground pixel */

background pixel */

line width */

LineSolid, LineOnOffDash, LineDoubleDash */

CapNotLast, CapButt, CapRound, CapProjecting */

JoinMiter, JoinRound, JoinBevel */

FillSolid, FillTiled, FillStippled */

EvenOddRule, WindingRule */

110

Xlib Reference Manual

Xlib - Graphics Context

(continued)

XCreateGC

int arc_mode; Pixmap tile; Pixmap stipple; int ts_x_origin; int ts_y_origin; Font font; int subwindow_mode; Bool graphics_exposures; int clip_x_origin; int clip_y_origin; Pixmap clip_mask; int dash_offset; char dashes; } XGCValues;

#define GCFunction #define GCPlaneMask #define GCForeground #define GCBackground #define GCLineWidth #define GCLineStyle #define GCCapStyle #define GCJoinStyle #define GCFillStyle #define GCFillRule #define GCTile #define GCStipple #define GCTileStipXOrigin #define GCTileStipYOrigin #define GCFont #define GCSubwindowMode #define GCGraphicsExposures #define GCClipXOrigin #define GCClipYOrigin tdefine GCClipMask #define GCDashOffset #define GCDashList #define GCArcMode

/* ArcPieSlice, ArcChord */

/* tile pixmap for tiling operations */

/* stipple 1 plane pixmap for stipping */

/* offset for tile or stipple operations */

/* default text font for text operations */

/* ClipByChildren, Includelnferiors */

/* generate events on XCopyArea, XCopyPlane */

/* origin for clipping */

/* bitmap clipping; other calls for rects */

/* patterned/dashed line information */

(1L«20) (1L«22)

Related Commands

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

Xlib Reference Manual

XCreateGlyphCursor \

v Xlib - Cursors-Name

XCreateGlyphCursor — create a cursor from font glyphs.

Synopsis

Cursor XCreateGlyphCursor( display, source_font, mask_font, source_char r mask_char, foreground_color, back-ground_color)

Display * display ;

Font source_font, mask_font;

unsigned int source_char, mask_char;

XColor * foreground_color;

XColor *background_color;

Arguments

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

source_font Specifies the font from which a character is to be used for the cursor. mask_font Specifies the mask font. Optional; specify 0 if not needed. source_char Specifies the index into the cursor shape font.

mask_char Specifies the index into the mask shape font. Optional; specify 0 if not needed.

foreground_color

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

background_color

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

Description

XCreateGlyphCursor is similar to XCreatePixmapCursor, but the source and mask bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font and character are optional. If mask_char is not specified, all pixels of the source are displayed.

The x offset for the hotspot of the created cursor is the left-bearing for the source character, and the y offset is the ascent, each measured from the upper-left corner of the bounding rectangle of the character.

The origins of the source and mask (if it is defined) characters are positioned coincidently and define the hotspot. The source and mask need not have the same bounding box metrics, and there is no restriction on the placement of the hotspot relative to the bounding boxes.

Note that source_char and mask_char are of type unsigned int, not of type XChar2b. For two-byte matrix fonts, source_char and mask_char should be formed with the bytel member in the most significant byte and the byte2 member in the least signif icant byte.

Xlib-Cursors (continued) XCreateGlyphCursor

You can free the fonts with XFreeFont if they are no longer needed after creating the glyph cursor.

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

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

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

char pad; } XColor;

Errors

BadAlloc

BadFont

BadValue source_charnot defined in source_font.

mask_ch a mot defined in mask_font (if mas k_ font defined).

Related Commands

XCreateFontCursor,XCreatePixmapCursor,XDefineCursor,XFreeCursor, XQueryBestCursor,XQueryBestSize, XRecolorCursor, XUndefineCursor.

XCreatelmage \ X|jb _ |mages _

Name

XCreatelmage — allocate memory for an Xlmage structure.

Synopsis

tfinclude <Xll/Xutil.h>

Xlmage *XCreateImage (display, visual, depth, format, offset, data, width, height, bitmap_pad, bytes_per_line)

Display * display;

Visual *visual;

unsigned int depth;

int format;

int offset;

char *data;

unsigned int width;

unsigned int height;

int bitmap_pad;

int bytes_per_line;

Arguments

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

visual Specifies a pointer to a visual that should match the visual of the window the

image is to be displayed in.

depth Specifies the depth of the image.

format Specifies the format for the image. Pass one of these constants: XYPixmap,

or ZPixmap.

offset Specifies the number of pixels beyond the beginning of the data (pointed to

by data) where the image actually begins. This is useful if the image is not aligned on an even addressable boundary.

da t a Specifies a pointer to the image data.

wi dth Specify the width and height in pixels of the image.

height

bi t/nap_pad Specifies the quantum of a scan line. In other words, the start of one scan line is separated in client memory from the start of the next scan line by an integer multiple of this many bits. You must pass one of these values: 8,16, or 3 2.

jbytes_per_line

Specifies the number of bytes in the client image between the start of one scan line and the start of the next. If you pass a value of 0 here, Xlib assumes that the scan lines are contiguous in memory and thus calculates the value of bytes_per_line itself.

Xlib- Images (continued) XCreatelmage

Description

XCreatelmage allocates the memory needed for an Xlmage structure for the specified dis play and visual.

This function does not allocate space for the image itself. It initializes the structure with byte order, bit order, and bitmap unit values, and returns a pointer to the Xlmage structure. The red, green, and blue mask values are defined for ZPixmap format images only and are derived from the visual structure passed in.

For a description of images, see Volume One, Chapter 6, Drawing Graphics and Text. Related Commands

ImageByteOrder, XAddPixel, XDestroylmage, XGetlmage, XGetPixel, XGet-Sublmage, XPutlmage, XPutPixel, XSublmage.

Xlib Reference Manual

XCreatePixmap

Xlib - Pixmaps and Tiles-Name

XCreatePixmap — create a pixmap.

Synopsis

Pixmap XCreatePixmap(display, drawable, width, height, depth) Display * display; Drawable drawable; unsigned int width, height; unsigned int depth;

Arguments

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

drawable Specifies the drawable. May be an inputOnly window.

width Specify the width and height in pixels of the pixmap. The values must be

height nonzero.

depth Specifies the depth of the pixmap. The depth must be supported by the screen

of the specified drawable. (Use XListDepths if in doubt.)

Description

XCreatePixmap creates a pixmap resource and returns its pixmap ID. The initial contents of the pixmap are undefined.

The server uses the drawable argument to determine which screen the pixmap is stored on. The pixmap can only be used on this screen. The pixmap can only be drawn drawn into with GCs of the same depth, and can only be copied to drawables of the same depth, except in XCopyPlane.

A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11.

Pixmaps should be considered a precious resource, since many servers have limits on the amount of off-screen memory available.

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

Errors

BadAlloc

BadDrawable

BadValue width or height is 0.

depth is not supported on screen.

Related Commands

XCreateBitmapFromData,XCreatePixmapFromBitmapData,XFreePixmap, XListDepths,XListPixmapFormat,XQueryBestCursor,XQueryBestSize, XQueryBestStipple,XQueryBestTile,XReadBitmapFile,XSetTile, XSet-WindowBackgroundPixmap,XSetWindowBorderPixmap,XWriteBitmapFile.

— Xlib - Pixmaps and Tiles-

J XCreatePixmapCursor

Name

XCreatePixmapCursor — create a cursor from two bitmaps.

Synopsis

Cursor XCreatePixmapCursor( display, source, mask,

foreground_color, background_color, x_hot, y_hot) Display * display; Pixmap source; Pixmap mask;

XColor * foreground_color; XColor *background_color; unsigned int x_hot, y_hot;

Arguments

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

source Specifies the shape of the source cursor. A pixmap of depth 1.

mask Specifies the bits of the cursor that are to be displayed (the mask or stipple).

A pixmap of depth 1.

-foreground_color

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

jbacJegrour!d_co-Zor

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

x_hot Specify the coordinates of the cursor's hotspot relative to the source's origin.

y_hot Must be a point within the source.

Description

XCreatePixmapCursor creates a cursor and returns a cursor ID. Foreground and back ground RGB values must be specified using £oreground_color and back-ground_color, even if the server only has a monochrome screen. The fore-ground_color is used for the 1 bits in the source, and the background is used for the 0 bits. Both source and mask (if specified) must have depth 1, but can have any root. The mask pix map defines the shape of the cursor; that is, the 1 bits in the mask define which source pixels will be displayed. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the source.

The pixmaps can be freed immediately if no further explicit references to them are to be made. For more information on cursors, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

typedef struct {

unsigned long pixel;

unsigned short red, green, blue;

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

XCreatePixmapCursor (continued) Xlib - Pixmaps and Tiles

char pad; } XColor;

Errors

BadAlloc

BadMatch Mask bitmap must be the same size as source bitmap. BadPixmap

Related Commands

XCreateBitmapFromData,XDefineCursor,XCreateFontCursor,XCreate-Pixmap, XCreatePixmapCursor,XFreeCursor,XFreePixmap, XQueryBest-Cursor,XQueryBestCursor,XQueryBestSize,XQueryBestSize,XRead-BitmapFile,XRecolorCursor,XUndefineCursor.

— Xlib - Pixmaps and Bitmaps-

XCreatePixmapFromBJtmapData

Name

XCreatePixmapFromBitmapData — create a pixmap with depth from bitmap data.

Synopsis

Pixmap XCreatePixmapFromBitmapData( display, drawable, data,

width, height, fg, bg, depth) Display *display; Drawable drawable; char *data;

unsigned int width, height; unsigned long fg, bg; unsigned int depth;

Arguments

display Specifies a connection to an Display structure, returned from XOpen-

Display.

drawable Specifies a drawable ID which indicates which screen the pixmap is to be used on.

data Specifies the data in bitmap format.

width Specify the width and height in pixels of the pixmap to create.

height

fg Specify the foreground and background pixel values to use.

depth Specifies the depth of the pixmap. Must be valid on the screen specified by

drawable.

Description

XCreatePixmapFromBitmapData creates a pixmap of the given depth using bitmap data and foreground and background pixel values.

The following format for the data is assigned, where the variables are members of the XImage structure described in Volume One, Chapter 6, Drawing Graphics and Text:

format=XYP ixmap

bit_order=LSBFirst

byte_order=LSBFirst

bitmap_unit=8

bitmap_pad=8

xoffset=0

no extra bytes per line

XCreatePixmapFromBitmapData creates an image from the data and uses XPutlmage to place the data into the pixmap. For example:

XCreatePixmapFromBitmapData (continued)

Xlib - Pixmaps and Bitmaps

#define gray_width 16

#define gray_height 16

#define gray_x_hot 8

#define gray_y_hot 8

static char gray_bits[] = • Oxf8, Oxlf, Oxe3, Oxc7, Oxfd, 0x33, Oxcc, Ox7f, Ox7f, Oxfe, 0x37, Oxec, Oxf3, Oxe3, Oxc7, Oxf8,

Oxcf, Oxfe, Oxbb,

Oxlf}

Oxf3, Ox7f, Oxdd,

Ox9f, Oxfe, Ox9c,

Oxf9, Ox7e, 0x39,

Oxbf, Ox7e, Oxcf,

unsigned long foreground, background; unsigned int depth;

/* open display, determine colors and depth */

Pixmap XCreatePixmapFromBitmapData(display, window, gray_bits,

gray_width, gray_height, foreground, background, depth);

If you want to use data of a different format, it is straightforward to write a routine that does this yourself, using images.

Pixmaps should be considered a precious resource, since many servers have limits on the amount of off-screen memory available.

Errors

BadAlloc BadDrawable

BadValue The width or height of pixmap are zero, or depth is not a valid depth on the screen specified by drawable.

Related Commands

XCreateBitmapFromData,XCreateFontCursor,XCreatePixmap, XCreate-PixmapCursor,XDefineCursor,XFreeCursor,XFreePixmap, XListPixmap-Formats,XQueryBestCursor,XQueryBestSize, XReadBitmapFile, XRecolor-Cursor,XUndefineCursor.

120

Xlib Reference Manual

— Xlib- Regions-

J XCreateRegion

Name

XCreateRegion — create a new empty region.

Synopsis

Region XCreateRegion ()

Description

XCreateRegion creates a new region of undefined size. XPolygonRegion can be used to create a region with a defined shape and size. Many of the functions that perform operations on regions can also create regions.

For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XDestroyRegion,XEmptyRegion, XEqualRegion,Xlntersect-Region, XOffsetRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSetRegion,XShrinkRegion,XSubtractRegion, XUnionRectWithRegion, XUnionRegion,XXorRegion.

XCreateSimpleWindow . vr .

v Xlib - Window Existence—

Name

XCreateSimpleWindow —create an unmapped InputOutput window.

Synopsis

Window XCreateSimpleWindow(display, parent, x, y, width, height, border_width, border, background)

Display * display;

Window parent;

int x, y;

unsigned int width, height, border_width;

unsigned long border;

unsigned long background;

Arguments

di spl ay Specifies a pointer to the Di spl ay structure; returned from XOpenDi spl ay.

parent Specifies the parent window ID. Must be an InputOutput window.

x Specify the x and y coordinates of the upper-left pixel of the new window's

y border relative to the origin of the parent (inside the parent window's border).

width Specify the width and height, in pixels, of the new window. These are the

height inside dimensions, not including the new window's borders, which are entirely

outside of the window. Must be nonzero. Any part of the window that extends

outside its parent window is clipped.

border_wi dth

Specifies the width, in pixels, of the new window's border.

border Specifies the pixel value for the border of the window.

background Specifies the pixel value for the background of the window.

Description

XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified parent window. Use XCreateWindow if you want to set the window attributes while creating a window. (After creation, XChangeWindowAttributes can be used.)

XCreateSimpleWindow returns the ID of the created window. The new window is placed on top of the stacking order relative to its siblings. Note that the window is unmapped when it is created—use Mapwindow to display it. This function generates a XCreateNotify event.

The initial conditions of the window are as follows:

The window inherits its depth, class, and visual from its parent. All other window attributes have their default values.

All properties have undefined values.

The new window will not have a cursor defined; the cursor will be that of the window's parent until the cursor attribute is set with XDefineCursor or XChangeWindowAttributes.

Xlib-Window Existence (continued) XCreateSimpleWindOW

If no background or border is specified, CopyFromParent is implied.

For more information, see Volume One, Chapter 2, X Concepts, and Volume One, Chapter 3, Basic Window Program.

Errors

BadAlloc

BadMatch

BadValue width or height is zero.

Badwindow Specified parent is an Input Only window.

Related Commands

XCreateWindow,XDestroySubwindows,XDestroyWindow.

XCreateWindow "\

v Xlib - Window Existence—

Name

XCreateWindow — create a window and set attributes.

Synopsis

Window XCreateWindow (display, parent, x, y, width, height, border_width, depth, class, visual, valuemask, attributes)

Display * display;

Window parent;

int x, y;

unsigned int width, height;

unsigned int border_width;

int depth;

unsigned int class;

Visual ^visual

unsigned long valuemask;

XSetWindowAttributes * attributes;

Arguments

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

parent Specifies the parent window. Parent must be inputOutput if class of win

dow created is to be InputOutput.

x Specify the x and y coordinates of the upper-left pixel of the new window's

y border relative to the origin of the parent (upper left inside the parent's border).

width Specify the width and height, in pixels, of the window. These are the new win-

height dow's inside dimensions. These dimensions do not include the new window's

borders, which are entirely outside of the window. Must be nonzero, otherwise

the server generates a BadValue error.

border_ width

Specifies the width, in pixels, of the new window's border. Must be 0 for inputOnly windows, otherwise a BadMatch error is generated.

depth Specifies the depth of the window, which is less than or equal to the parent's

depth. A depth of CopyFromParent means the depth is taken from the par ent. Use XListDepths is choosing an unusual depth. The specified depth paired with the visual argument must be supported on the screen.

class Specifies the new window's class. Pass one of these constants: Input-

Output, InputOnly, or CopyFromParent.

visual Specifies a connection to an visual structure describing the style of colormap to

be used with this window. CopyFromParent is valid.

valuemask Specifies which window attributes are defined in the attributes argument. If valuemask is 0, attributes is not referenced. This mask is the bitwise OR of the valid attribute mask bits listed in the Structures section below.

Xlib - Window Existence (continued) XCreateWindOW

attributes Attributes of the window to be set at creation time should be set in this struc ture. The value/nasJt should have the appropriate bits set to indicate which attributes have been set in the structure.

Description

To create an unmapped subwindow for a specified parent window use XCreateWindow or XCreateSimpleWindow. XCreateWindow is a more general function that allows you to set specific window attributes when you create the window. If you do not want to set specific attributes when you create a window, use XCreateSimpleWindow, which creates a window that inherits its attributes from its parent. XCreateSimpleWindow creates only Input-Output windows that use the default depth and visual.

XCreateWindow returns the ID of the created window. XCreateWindow causes the X server to generate a CreateNotif y event. The newly created window is placed on top of its siblings in the stacking order.

Extension packages may define other classes of windows.

The visual should be Def aultvisual or one returned by XGetvisuallnf o or XMatch-Visuallnfo. The depth should be DefaultDepth, 1, or a depth returned by XList-Depths. In current implementations of Xlib, if you specify a visual other than the one used by the parent, you must first find (using XGetRGBColormaps) or create a colormap matching this visual and then set the colormap window attribute in the attributes and valuemask arguments. Otherwise, you will get a BadMatch error.

For more information, see Volume One, Chapter 4, Window Attributes.

Structures

* Data structure for setting window attributes.

*/ typedef struct {

Pixmap background_pixmap; /* background or None or ParentRelative */

unsigned long background_pixel; /* background pixel */

Pixmap border_pixmap; /* border of the window */

unsigned long border_pixel; /* border pixel value */

int bit_gravity; /* one of bit gravity values */

int win gravity; /* one of the window gravity values */

int backing store; /* NotUseful, WhenMapped, Always */

unsigned long backing_planes; /* planes to be preseved if possible */

unsigned long backing_pixel; /* value to use in restoring planes */

Bool save_under; /* should bits under be saved (popups) */

long event mask; /* set of events that should be saved */

long do not propagate_mask; /* set of events that should not propagate i

Bool override_redirect; /* boolean value for override-redirect */

Colormap colormap; /* colormap to be associated with window */

Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes;

XCreateWindOW (continued) Xlib - Window Existence

/* Definitions for valuemask argument */

tdefine CWBackPixmap (1L«0)

tdefine CWBackPixel (1L«1)

tdefine CWBorderPixmap (1L«2)

#define CWBorderPixel (1L«3)

#define CWBitGravity (1L«4)

#define CWWinGravity (1L«5)

#define CWBackingStore (1L«6)

tdefine CWBackingPlanes (1L«7)

#define CWBackingPixel (1L«8)

tdefine CWOverrideRedirect (1L«9)

tdefine CWSaveUnder (1L«10)

#define CWEventMask (1L«11)

tdefine CWDontPropagate (1L«12)

tdefine CWColormap (1L«13)

tdefine CWCursor (1L«14)

Errors

BadAlloc Attribute besides win_gravity, event_mask, do_not_propagate mask, override_redirect or cursor specified for InputOnly win dow.

BadColormap depth nonzero for InputOnly. BadCursor Parent of InputOutput is InputOnly. BadMatch border_width is nonzero for InputOnly. BadPixmap depth not supported on screen for InputOutput. BadValue width or height is 0. Badwindow visual not supported on screen.

Related Commands

XCreateSimpleWindow,XDestroySubwindows,XDestroyWindow,XList-Depths.

-x,,b - cursors / XDefineCursor

Name

XDefineCursor — assign a cursor to a window.

Synopsis

XDefineCursor(display, w, cursor) Display *display; Window w; Cursor cursor;

Arguments

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

w Specifies the ID of the window in which the cursor is to be displayed.

cursor Specifies the cursor to be displayed when the pointer is in the specified win

dow. Pass None to have the parent's cursor displayed in the window, or for the root window, to have the default cursor displayed.

Description

Sets the cursor attribute of a window, so that the specified cursor is shown whenever this win dow is visible and the pointer is inside. If XDefineCursor is not called, the parent's cursor is used by default.

For more information on available cursors, see Appendix I, The Cursor Font. Errors

BadCursor BadWindow

Related Commands

XCreateFontCursor,XCreateGlyphCursor,XCreatePixmapCursor,XFree-Cursor,XQueryBestCursor,XQueryBestSize,XRecolorCursor,XUndefine-Cursor.

XDeleteAssoc , vr .

v Xlib - Association Tables-Name

XDeleteAssoc — delete an entry from an association table.

Synopsis

XDeleteAssoc( display, table, x_id) Display * display ; XAssocTable * table; XID x_id;

Arguments

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

table Specifies one of the association tables created by XCreateAssocTable.

x_i d Specifies the X resource ID of the association to be deleted.

Description

This function is provided for compatibility with X Version 10. To use it you must include the file <XlllX10.h> and link with the library -loldX.

XDeleteAssoc deletes an association in an XAssocTable keyed on its XID. Redundant deletes (and deletes of nonexistent X ID'S) are meaningless and cause no problems. Deleting associations in no way impairs the performance of an XAssocTable.

For more information on association tables, see Volume One, Appendix R,X10 Compatibility. Structures

typedef struct {

XAssoc ^buckets; /* pointer to first bucket in array */ int size; /* table size (number of buckets) */

} XAssocTable;

Related Commands

XCreateAssocTable,XDestroyAssocTable,XLookUpAssoc,XMakeAssoc.

-XHb - Conttxt Manager - /

Name

XDeleteContext — delete a context entry for a given window and type.

Synopsis

int XDeleteContext { display, w r context) Display * display; Window w; XContext context;

Arguments

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

w Specifies the window with which the data is associated.

context Specifies the context type to which the data belongs.

Description

XDeleteContext deletes the entry for the given window and type from the context data structure defined in <Xll/Xutil.h>. This function returns XCNOENT if the context could not be found, or zero if it succeeds. XDeleteContext does not free the memory allocated for the data whose address was saved.

See Volume One, Chapter 13, Other Programming Techniques, for a description of context management.

Structures

typedef int XContext;

Related Commands

XFindContext, XSaveContext, XUniqueContext.

XDeleteModifiermapEntry \ X|lb _ ResourM Manager _

Name

XDeleteModifiermapEntry — delete an entry from an XModif ierKeymap structure.

Synopsis

XModif ierKeymap *XDeleteModif iermapEntry (/nod/nap,

keysym_entry, modifier) XModif ierKeymap *modmap; KeyCode keysym_entry; int modifier;

Arguments

modmap Specifies a pointer to an XModif ierKeymap structure.

k eysym_ entry

Specifies the keycode of the key to be deleted from modmap.

modifier Specifies the modifier you no longer want mapped to the keycode specified in keysym_entry. This should be one of the constants: Shif tMaplndex, LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2Map-Index, ModSMapIndex, Mod4MapIndex, or ModSMapIndex.

Description

XDeleteModifiermapEntry returns an XModif ierKeymap structure suitable for cal ling XSetModif ierMapping, in which the specified keycode is deleted from the set of key-codes that is mapped to the specified modifier (like Shift or Control). XDelete ModifiermapEntry itself does not change the mapping.

This function is normally used by calling XGetModif ierMapping to get a pointer to the current XModif ierKeymap structure for use as the modmap argument to XDelete ModifiermapEntry.

Note that the structure pointed to by modmap is freed by XDeleteModifiermapEntry. It should not be freed or otherwise used by applications after this call.

For a description of the modifier map, see XSetModif ierMapping. Structures

typedef struct {

int max_keypermod; /* server's max number of keys per modifier */ KeyCode *modifiermap; /* an 8 by max_keypermod array of

* keycodes to be used as modifiers */

} XModifierKeymap;

#define ShiftMapIndex 0

#define LockMapIndex 1

tdefine ControlMapIndex 2

#define ModlMapIndex 3

#define Mod2MapIndex 4

tdefine ModSMapIndex 5

Xlib - Resource Manager (continued) XDeleteModif iermapEntry

tdefine Mod4MapIndex 6 tdefine ModSMapIndex

Related Commands

XFreeModif iermap, XGetKeyboardMapping, XGetModif ierMapping, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString,XNewModifiermap,XQueryKeymap,XRebindKeySym, XRefreshKeyboardMapping,XSetModifierMapping, XStringToKeysym, InsertModifiermapEntry.

Name

XDeleteProperty — delete a window property.

Synopsis

XDeleteProperty( display, w, property) Display * display ; Window w; Atom property;

Arguments

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

w Specifies the ID of the window whose property you want to delete.

property Specifies the atom of the property to be deleted.

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

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

Start your free trial

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

Don’t leave empty-handed

It’s yours, free.

Check it out now on O’Reilly