O'Reilly logo

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

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

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

Start Free Trial

No credit card required

An application should go through the standard colormap creation process only if it needs the special qualities of the standard colormaps. For one, they allow the application to convert RGB values into pixel values quickly because the mapping is predictable. Given an XStandard Colormap structure for an XA_RGB_BEST_MAP colormap, and floating point RGB coefficients in the range 0.0 to 1.0, you can compose pixel values with the following C expression:

246 Xlib Reference Manual

xiib - coiormaps (continued) XGetStandardColormap

pixel = base_pixel

+ ((unsigned long) (0.5 + r * red_max)) * red_mult

+ ((unsigned long) (0.5 + g * green_max)) * greenjmult

+ ((unsigned long) (0.5 + b * blue_max)) * blue_mult;

The use of addition rather than logical-OR for composing pixel values permits allocations where the RGB value is not aligned to bit boundaries.

XGetStandardColormap returns zero if it fails, or nonzero if it succeeds.

See Volume One, Chapter 7, Color, for a complete description of standard coiormaps.

Structures

typedef struct {

Colormap colormap; /* ID of colormap created by XCreateColormap */

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;

/* new fields here in R4 */ } XStandardColormap;

Errors

BadAtom BadWindow

Related Commands

Def aultColormap, Display-Cells, XCopyColormapAndFree, XCreate Colormap, XFreeColormap,XInstallColormap, XListlnstalledColormaps, XSetStandardColormap, XSetWindowColormap, XUninstallColormap.

XGetSublmage \ xnt >. tmages -

Name

XGetSublmage — copy a rectangle in drawable to a location within the pre-existing image. Synopsis

Xlmage *XGetSubImage( display, drawable, x, y, width, height,

plane_mask, format, dest_image, dest_x, dest_y) Display * display; Drawable drawable; int x, y;

unsigned int width, height; unsigned long plane_mask; int format; Xlmage *dest_image; int dest_x, dest_y;

Arguments

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

drawabl e Specifies the drawable from which the rectangle is to be copied.

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

y live to the origin of the drawable.

width Specify the width and height in pixels of the subimage taken.

height

plane_mask Specifies which planes of the drawable are transferred to the image. format Specifies the format for the image. Either XYPixmap or ZPixmap.

dest_image Specifies the the destination image.

dest_x Specify the x and y coordinates of the destination rectangle's upper left cor-

dest_y ner, relative to the image's origin.

Description

XGetSublmage updates the dest_image with the specified subimage in the same manner as XGet image, except that it does not create the image or necessarily fill the entire image. If format is XYPixmap, the function transmits only the bit planes you specify in plane_mask. If format is ZPixmap, the function transmits as zero the bits in all planes not specified in plane_mask. The function performs no range checking on the values in plane_mask and ignores extraneous bits.

The depth of the destination x image structure must be the same as that of the drawable. Otherwise, a BadMatch error is generated. If the specified subimage does not fit at the speci fied location on the destination image, the right and bottom edges are clipped. If the drawable is a window, the window must be mapped or held in backing store, and it must be the case that, if there were no inferiors or overlapping windows, the specified rectangle of the window would be fully visible on the screen. Otherwise, a BadMatch error is generated.

Xlib - Images (continued) XGetSublmage

If the window has a backing store, the backing store contents are returned for regions of the window that are obscured by noninferior windows. Otherwise, the return contents of such obscured regions are undefined. Also undefined are the returned contents of visible regions of inferiors of different depth than the specified window.

XSubImage extracts a subimage from an image, instead of from a drawable like XGetSub lmage.

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

Errors

BadDrawable

BadMatch Depth of dest_i/nage is not the same as depth of drawable. BadValue

Related Commands

ImageByteOrder, XAddPixel, XCreateImage, XDestroyImage, XGet Image, XGetPixel,XPutlmage,XPutPixel,XSublmage.

XGetTeXtPrOperty \ x,,b-W,ndowManager H,n,s-

Name

XGetTextProperty — read one of a window's text properties.

Synopsis

Status XGetTextProperty ( display, w r text_prop f property) Display ^display; Window w;

XTextProperty *text_prop; /* RETURN */ Atom property;

Arguments

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

w Specifies the window.

text_prop Returns the XTextProperty structure.

property Specifies the property name.

Availability

Release 4 and later.

Description

XGetTextProperty reads the specified property from the window and stores the data in the returned XTextProperty structure. It stores the data in the value field, the type of the data in the encoding field, the format of the data in the format field, and the number of items of data in the nit ems field. The particular interpretation of the property's encoding and data as "text" is left to the calling application. If the specified property does not exist on the window, XGetTextProperty sets the value field to NULL, the encoding field to None, the format field to zero, and the nit ems field to zero.

If it was able to set these files in the XTextProperty structure, XGetTextProperty returns a non-zero status; otherwise, it returns a zero status.

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

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */ } XTextProperty;

Errors

BadAtom BadWindow

Xlib - Window Manager Hints (continued) XGetTextPfOperty

Related Commands

XFreeStringList,XSetTextProperty, XStringListToTextProperty, XText-PropertytoStringList.

XGetTransientForHint

Name

XGetTransientForHint — get the XA_WM_TRANSIENT_FOR property of a window.

Synopsis

Status XGetTransientForHint ( display, w, prop_window) Display * display; Window w; Window *prop_nrindow; /* RETURN */

Arguments

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

w Specifies the ID of the window to be queried.

prop_window Returns the window contained in the XA_WM_TRANSIENT_FOR property of the specified window.

Description

XGetTransientForHint obtains the XA_WM_TRANSIENT_FOR property for the specified window. This function is normally used by a window manager. This property should be set for windows that are to appear only temporarily on the screen, such as pop-up dialog boxes. The window returned is the main window to which this popup window is related. This lets the win dow manager decorate the popup window appropriately.

XGetTransientForHint returns a Status of zero on failure, and nonzero on success. For more information on using hints, see Volume One, Chapter W,Interclient Communication.

Errors

BadWindow

Related Commands

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal-Hints, XGetSizeHints, XGetWMHints, XGetZoomHints, XSetClassHint, XSet-Command, XSetlconName, XSetlconSizes, XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStoreName.

-xiib-visuais / XGetVisuallnfo

Name

XGetVisuallnfo — find the visual information structures that match the specified template.

Synopsis

XVisuallnfo *XGetVisualInfo(display, vinfo_mask,

vinfo_template, nitems) Display *display; long vinfo_mask; XVisuallnfo *vinfo_template; int * nitems; /* RETURN */

Arguments

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

vinfo_mask Specifies the visual mask value. Indicates which elements in template are to be matched.

vi n f o_ t empl a t e

Specifies the visual attributes that are to be used in matching the visual struc tures.

nitems Returns the number of matching visual structures.

Description

XGetVisuallnfo returns a list of visual structures that describe visuals supported by the server and that match the attributes specified by the vinfo_template argument. If no visual structures match the template, XGetVisuallnfo returns a NULL. To free the data returned by this function, use XFree.

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

typedef struct {

Visual *visuai;

VisuallD visualid;

int screen;

unsigned int depth;

int class;

unsigned long red_mask;

unsigned long green_mask;

unsigned long blue_mask;

int colormap_size;

int bits_per_rgb; } XVisuallnfo";

/* The symbols for the vinfo_mask argument are: */

tdefine VisualNoMask 0x0

#define VisuallDMask Oxl

tfdefine VisualScreenMask 0x2

Xlib Reference Manual

XGetViSUallnfO (continued) Xlib-Visuals

#define VisualDepthMask 0x4

#define VisualClassMask 0x8

#define VisualRedMaskMask 0x10

tdefine VisualGreenMaskMask 0x20

#define VisualBlueMaskMask 0x40

#define VisualColormapSizeMask 0x80

#define VisualBitsPerRGBMask 0x100

tdefine VisualAllMask OxlFF

Related Commands

DefaultVisual,XVisuallDFromVisual,XMatchVisuallnfo,XListDepths.

-Xlib- Window Manager Hints ' XGetWMICOnName

Name

XGetWMIconName — read a window's XA_WM_ICON_NAME property.

Synopsis

Status XGetWMIconName ( display, w, text_prop) Display *display; Window w; XTextProperty *text_prop; /* RETURN */

Arguments

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

w Specifies the window.

text_prop Returns the XTextProperty structure.

Availability

Release 4 and later.

Description

XGetWMIconName performs an XGet Text Property on the XA_WM_ICON_NAME property of the specified window. XGetWMIconName supersedes XGetlconName.

This function is primarily used by window managers to get the name to be written in a win dow's icon when they need to display that icon.

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

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */ } XTextProperty;

Related Commands

XGetWMName, XSetWMIconName, XSetWMName, XSetWMProperties.

XGetWMName V

v Xlib - Window Manager Hints-Name

XGetWMName — read a window's XA_WM_NAME property.

Synopsis

Status XGetWMName ( display r w, text_prop) Display * display; Window w; XTextProperty *text_prop;/* RETURN */

Arguments

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

w Specifies the window.

text_prop Returns the XTextProperty structure.

Availability

Release 4 and later.

Description

XGetWMName performs an XGetTextProperty on the XA_WM_NAME property of the speci fied window. XGetWMName supersedes XFetchName.

XGetWMName returns nonzero if it succeeds, and zero if the property has not been set for the argument window.

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

typedef struct {

unsigned char *value; /* same as Property routines */

Atom encoding; /* prop type */

int format; /* prop data format: 8, 16, or 32 */

unsigned long nitems; /* number of data items in value */ } XTextProperty;

Related Commands

XGetWMIconName, XSetWMIconName, XSetWMName, XSetWMProperties.

-XHb-WindowManager Hints ' XGetWMNormalHintS

Name

XGetWMNormalHintS — read a window's XA_WM_NORMAL_HINTS property.

Synopsis

Status XGetWMNormalHintS(display, w, hints, supplied) Display *display; Window w;

XSizeHints *hints;/* RETURN */ long * supplied;

Arguments

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

w Specifies the window.

hints Returns the size hints for the window in its normal state.

supplied Returns the hints that were supplied by the user.

Availability

Release 4 and later.

Description

XGetWMNormalHintS returns the size hints stored in the XA_WM_NORMAL_HINTS property on the specified window. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long enough to contain either an old (pre-ICCCM) or new size hints structure, XGetWMNormal HintS sets the various fields of the XSizeHints structure, sets the supplied argument to the list of fields that were supplied by the user (whether or not they contained defined values) and returns a non-zero status. XGetWMNormalHintS returns a zero status if the application specified no normal size hints for this window.

XGetWMNormalHintS supersedes XGetNormalHints.

If XGetWMNormalHintS returns successfully and a pre-ICCCM size hints property is read, the supplied argument will contain the following bits:

(USPosition|USSize|PPosition|PSize|PMinSize| PMaxSizeIPResizelncIPAspect)

If the property is large enough to contain the base size and window gravity fields as well, the supplied argument will also contain the following bits:

(PBaseSize|PWinGravity)

This function is normally used only by a window manager.

For more information, see Volume One, Chapter lOJnterclient Communication.

Structures

typedef struct {

long flags; /* marks which fields in this structure are defined */ int x, y; /* obsolete for new window mgrs, but clients */

XGetWMNormalHintS (continued) Xlib - Window Manager Hints

int width, height; /* should set so old wm's don't mess up */ int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct {

int x; /* numerator */

int y; /* denominator */ } min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version I */

int win_gravity; /* added by ICCCM

version 1 */ } XSizeHints;

Errors

BadWindow

Related Commands

XAllocSizeHints, XGetWMSizeHints, XSetWMNormalHints, XSet-WMProperties,XSetWMSizeHints.

-Xllb- Window Manager Hints / XGetWMSizeHintS

Name

XGetWMSizeHintS —read a window's XA_WM_SIZE_HINTS property.

Synopsis

Status XGetWMSizeHintS(display, w, hints, supplied, property) Display *display; Window w;

XSizeHints *hints; /* RETURN */

long * supplied; /*RETURN */

Atom property;

Arguments

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

w Specifies the window.

hints Returns the XSizeHints structure.

supplied Returns the hints that were supplied by the user.

property Specifies the property name.

Availability

Release 4 and later.

Description

XGetWMSizeHintS returns the size hints stored in the specified property on the named win dow. If the property is of type XA_WM_SIZE_HINTS, of format 32, and is long enough to con tain either an old (pre-ICCCM) or new size hints structure, XGetWMSizeHintS sets the vari ous fields of the XSizeHints structure, sets the supplied argument to the list of fields that were supplied by the user (whether or not they contained defined values), and returns a non zero status. If the hint was not set, it returns a zero status. To get a window's normal size hints, you can use the XGetWMNormalHints function instead.

XGetWMSizeHintS supersedes XGetSizeHints.

If XGetWMSizeHintS returns successfully and a pre-ICCCM size hints property is read, the supplied argument will contain the following bits:

(USPositionIUSSizeIPPositionIPSizeIPMinSizeI PMaxSizeIPResizelncIPAspect)

If the property is large enough to contain the base size and window gravity fields as well, the supplied argument will also contain the following bits:

(PBaseSizeIPWinGravity)

This function is used almost exclusively by window managers.

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

XGetWMSizeHintS (continued) Xlib - Window Manager Hints

Structures

typedef struct {

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

int x, y; /* obsolete for new window mgrs, but clients */

int width, height; /* should set so old wm's don't mess up */

int min_width, min_height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */ } min_aspect, max_aspect;

int base_width, base_height; /* added by ICCCM version 1 */

int win_gravity; /* added by ICCCM version 1 */

} XSizeHints;

Errors

BadAtom BadWindow

Related Commands

XAllocSizeHints, XGetWMNormalHints, XSetWMNormalHints, XSetWMSize-Hints.

/

XGetWindowAtlributes

Name

XGetWindow Attributes — obtain the current attributes of window. Synopsis

Status XGetWindowAt tributes (display, w, window_attributes) Display *display; Window w; XWindowAttributes *window_attributes ; /* RETURN */

Arguments

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

w Specifies the window whose current attributes you want.

window_at tributes

Returns a filled XWindowAttributes structure, containing the current attri butes for the specified window.

Description

XGetwindowAttributes returns the XWindowAttributes structure containing the cur rent window attributes.

While w is defined as type window, a Pixmap can also be used, in which case all the returned members will be zero except width, height, depth, and screen.

XGetwindowAttributes returns a Status of zero on failure, or nonzero on success. However, it will only return zero if you have defined an error handler that does not exit, using xSetErrorHandler. The default error handler exits, and therefore XGetwindow Attributes never gets a chance to return. (This is relevant only if you are writing a window manager or other application that deals with windows that might have been destroyed.)

The following list briefly describes each member of the XWindowAttributes structure. For more information, see Volume One, Chapter 4, Window Attributes.

x, y The current position of the upper-left pixel of the window's border, relative

to the origin of its parent.

width, height The current dimensions in pixels of this window.

border_width The current border width of the window.

depth The number of bits per pixel in this window.

visual The visual structure.

root The root window ID of the screen containing the window.

class The window class. One of these constants: InputOutput or Input-

Only.

bit_gravity The new position for existing contents after resize. One of the constants ForgetGravity, StaticGravity, or CenterGravity, or one of the compass constants (NorthWestGravity, NorthGravity, etc.).

X Get Window Attributes (continued) Xlib - Window Attributes

win_gravity The new position for this window after its parent is resized. One of the constants CenterGravity, UnmapGravity, StaticGravity, or one of the compass constants.

backing_store When to maintain contents of the window. One of these constants: Not-Usef ul, WhenMapped, or Always.

backing_jplanes

The bit planes to be preserved in a backing store.

backing_jpixel The pixel value used when restoring planes from a partial backing store.

save_under A boolean value, indicating whether saving bits under this window would be useful.

colormap The colormap ID being used in this window, or None.

map_installed A boolean value, indicating whether the colormap is currently installed. If True, the window is being displayed in its chosen colors.

map_state The window's map state. One of these constants: isUnmapped, Is-

Unviewable, or IsViewable. IsUnviewable indicates that the specified window is mapped but some ancestor is unmapped.

a1l_event_ma s k s

The set of events any client have selected. This member is the bitwise inclusive OR of all event masks selected on the window by all clients.

your_event_mask

The bitwise inclusive OR of all event mask symbols selected by the query ing client.

do_not_propagate_mask

The bitwise inclusive OR of the event mask symbols that specify the set of events that should not propagate. This is global across all clients.

override_redirect

A boolean value, indicating whether this window will override structure control facilities. This is usually only used for temporary pop-up windows such as menus. Either True or False.

screen A pointer to the Screen structure for the screen containing this window.

Errors

BadWindow

Structures

The xwindowAttributes structure contains:

typedef struct {

int x, y; /* location of window */

int width, height; /* width and height of window */

int border_width; /* border width of window */

int depth; /* depth of window */

Xlib - Window Attributes

(continued)

XGetWindowAttributes

Visual *visual; /*

Window root; /*

int class; /*

int bit_gravity; /*

int win_gravity; /*

int backing_store; /* unsigned long backing_planes;/*

unsigned long backing_pixel; /*

Bool save_under; /*

Colormap colormap; /*

Bool map_installed; /*

int map_state; /*

long all_event_masks; /*

long your_event_mask; /*

long do_not_propagate_mask; /*

Bool override_redirect; /*

Screen *screen; /* } XWindowAttributes;

the associated visual structure */ root of screen containing window */ InputOutput, InputOnly*/ one of bit gravity values */ one of the window gravity values */ NotUseful, WhenMapped, Always */ planes to be preserved if possible */ value to be used when restoring planes */ boolean, should bits under be saved */ colormap to be associated with window */ boolean, is colormap currently installed*/ IsUnmapped, IsUnviewable, IsViewable */ set of events all people have interest in*/ my event mask */

set of events that should not propagate */ boolean value for override-redirect */ pointer to correct screen */

Related Commands

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

Xlib Reference Manual

XGetWindowProperty \ X)|b _ Propartl8s _

Name

XGetWindowProperty — obtain the atom type and property format for a window.

Synopsis

int XGetWindowProperty( display, w, property, long_offset,

long_length, delete, req_type, actual_type, actual_for-mat, nit ems, bytes_after, prop) Display *display; Window w; Atom property;

long long_offset, long_length; Bool delete; Atom req_type;

Atom *actual_type; /* RETURN */

int *actual_format; /* RETURN */

unsigned long *nitems; /* RETURN */

unsigned long *bytes_after; /* RETURN */ unsigned char **prop; /* RETURN */

Arguments

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

w Specifies the ID of the window whose atom type and property format you

want to obtain.

property Specifies the atom of the desired property.

1 ong_offset Specifies the offset in 32-bit quantities where data will be retrieved.

1 ong_length Specifies the length in 32-bit multiples of the data to be retrieved.

delete Specifies a boolean value of True or False. If you pass True and a prop

erty is returned, the property is deleted from the window after being read and a PropertyNotif y event is generated on the window.

req_type Specifies an atom describing the desired format of the data. If Any-Proper tyType is specified, returns the property from the specified window regardless of its type. If a type is specified, the function returns the property only if its type equals the specified type.

actual_type Returns the actual type of the property.

actual_for/nat

Returns the actual data type of the returned data.

ni terns Returns the actual number of 8-, 16-, or 32-bit items returned in prop.

bytes_after Returns the number of bytes remaining to be read in the property if a partial read was performed.

xiib - Properties (continued) XGetWindowProperty

prop Returns a pointer to the data actually returned, in the specified format.

XGetWindowProperty always allocates one extra byte after the data and sets it to NULL. This byte is not counted in nit ems.

Description

XGetWindowProperty gets the value of a property if it is the desired type. XGetwindow-P rope rty sets the return arguments acccording to the following rules:

If the specified property does not exist for the specified window, then: act ual_type is None; act ual_format = 0; and bytes_after = 0. delete is ignored in this case, and nit ems is empty.

If the specified property exists, but its type does not match req_type, then: actual_type is the actual property type; actual_format is the actual property format (never zero); and bytes_after is the property length in bytes (even if actual_format is 16 or 32). delete is ignored in this case, and ni terns is empty.

If the specified property exists, and either recj_type is AnyPropertyType or the specified type matches the actual property type, then: actual_type is the actual prop erty type; and actual_format is the actual property format (never zero). jbytes_ar"ter and nit ems are defined by combining the following values:

N = actual length of stored property in bytes (even if act ual_format is 16 or 3 2) 1 = 4* 1 ong_offset (convert offset from longs into bytes) L = MINIMUM*(N - I), 4 * long_length) (BadValue if L < 0) bytes_after = N - (I + L) (number of trailing unread bytes in stored property)

The returned data (in prop) starts at byte index I in the property (indexing from 0). The actual length of the returned data in bytes is L. L is converted into the number of 8-, 16-, or 32-bit items returned by dividing by 1,2, or 4 respectively and this value is returned in nitems. The number of trailing unread bytes is returned in by t es_aft er.

If delete == True and bytes_after == 0 the function deletes the property from the window and generates a PropertyNotif y event on the window.

When XGetWindowProperty executes successfully, it returns Success. The Success return value and the undocumented value returned on failure are the opposite of all other rou tines that return int or Status. The value of Success is undocumented, but is zero (0) in the current sample implementation from MIT. The failure value, also undocumented, is cur rently one (1). Therefore, comparing either value to True or False, or using the syntax "if (! XGetWindowProperty ( . . . ))" is not allowed.

To free the resulting data, use XFree.

For more information, see Volume One, Chapter WJnterdient Communication.

XGetWindOwProperty (continued) Xlib - Properties

Errors

BadAtom

BadVa lue Value of I ong_offset caused L to be negative above. BadWindow

Related Commands

XChangeProperty,XGetAtomName,XGetFontProperty, XListProperties, XRotateWindowProperties,XSetStandardProperties.

Xlib Reference Manual

-Xllb- Window Manager Hints / XGetWMHintS

Name

XGetWMHintS — read the window manager hints property.

Synopsis

XWMHints *XGetWMHints(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 to be queried.

Description

This function is primarily for window managers. XGetWMHintS returns NULL if no XA_WM_HINTS property was set on window w, and returns a pointer to an XWMHints structure if it succeeds. Programs must free the space used for that structure by calling XFree.

For more information on using hints, see Volume One, Chapter 10, Inter-client Communication. Structures

typedef struct {

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

Bool input; /* does application need window manager for input */

int initial_state; /* see below */

Pixmap icon_pixmap; /* pixmap to be used as icon */

Window icon_window; /* window to be used as icon */

int icon x, icon y; /* initial position of icon */

Pixmap icon_mask; /* icon mask bitmap */

XID window group; /* ID of related window group */

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

/* initial state flag: */

#define DontCareState 0

#define NormalState 1

#define ZoomState 2

#define IconicState 3

#define InactiveState 4

Errors

BadWindow

Related Commands

XAllocWMHints,XFetchName,XGetClassHint, XGetlconName, XGetlcon-Sizes, XGetNormalHints,XGetSizeHints, XGetTransientForHint,XGet-ZoomHints,XSetClassHint,XSetCommand,XSetlconName,XSetlconSizes, XSetNormalHints,XSetSizeHints,XSetTransientForHint, XSetWMHints, XSetZoomHints,XStoreName,XSetWMProperties.

N Xlib - Window Manager Hints-Name

XGetZoomHints — read the size hints property of a zoomed window.

Synopsis

Status XGetZoomHints(display, w, zhints) Display *display; Window w; XSizeHints *zhints; /* RETURN */

Arguments

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

w Specifies the ID of the window to be queried.

zhints Returns a pointer to the zoom hints.

Description

XGetZoomHints is obsolete beginning in Release 4, because zoom hints are no longer defined in the ICCCM.

XGetZoomHints is primarily for window managers. XGetZoomHints returns the size hints for a window in its zoomed state (not normal or iconified) read from the XA_WM_ZOOM_HINTS property. It returns a nonzero Status if it succeeds, and zero if the application did not specify zoom size hints for this window.

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

typedef struct {

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

int x, y;

int width, height;

int min_width, min__height;

int max_width, max_height;

int width_inc, height_inc;

struct {

int x; /* numerator */

int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints;

/* flags argument in size hints */

tdefine USPosition (1L « 0) /* user specified x, y */

#define USSize (1L « 1) /* user specified width, height */

#define PPosition (1L « 2) /* program specified position */

tdefine PSize (1L « 3) /* program specified size */

tdefine PMinSize (1L « 4) /* program specified minimum size */

#define PMaxSize (1L « 5) /* program specified maximum size */

#define PResizelnc (1L « 6) /* program specified resize increments */

268 Xlib Reference Manual

Xlib - Window Manager Hints (continued) XGetZoomHints

#define PAspect (1L « 7) /* program specified min/max aspect ratios */ #define PAllHints (PPositionIPSizeIPMinSize|PMaxSizeIPResizelncIPAspect)

Errors

BadWindow

Related Commands

XFetchName,XGetClassHint,XGetlconName,XGetlconSizes,XGetNormal-Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints, XSetClass-Hint, XSetCommand,XSetlconName,XSetlconSizes,XSetNormalHints,XSet-SizeHints, XSetTransientForHint,XSetWMHints,XSetZoomHints,XStore-Name.

Xlib Reference Manual

Name

XGrabButton — grab a pointer button.

Synopsis

XGrabButton( display, button, modifiers, grab_window,

owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor)

Display *display;

unsigned int button;

unsigned int modifiers;

Window grab_window;

Bool owner_events;

unsigned int event_mask;

int pointer_mode, keyboard_mode;

Window confine_to;

Cursor cursor;

Arguments

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

button Specifies the mouse button. May be Buttonl, Button2, Buttons, But-

ton4, Buttons, or AnyButton. The constant AnyButton is equivalent to issuing the grab request for all possible buttons. The button symbols can not be ORed.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, ModSMask, Mod4Mask, ModSMask, or AnyModifier. AnyModif ier is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers).

grab_window Specifies the ID of the window you want to the grab to occur in.

owner_events

Specifies a boolean value of either True or False. See Description below.

event_mask Specifies the event mask to take effect during the grab. This mask is the bit wise OR of one or more of the event masks listed on the reference page for XSelectlnput.

pointer_mode

Controls processing of pointer events during the grab. Pass one of these con stants: GrabModeSync or GrabModeAsync.

keyboard_mode

Controls processing of keyboard events during the grab. Pass one of these constants: GrabModeSync or GrabModeAsync.

confine_to Specifies the ID of the window to confine the pointer. One possible value is the constant None, in which case the pointer is not confined to any window.

270 Xlib Reference Manual

Xlib-Grabbing (continued) XGrabButton

cursor Specifies the cursor to be displayed during the grab. One possible value you

can pass is the constant None, in which case the existing cursor is used.

Description

XGrabButton establishes a passive grab, such that an active grab may take place when the specified key/button combination is pressed in the specified window. After this call, if

1) the specified button is pressed when the specified modifier keys are down (and no other buttons or modifier keys are down),

2) grab_window contains the pointer,

3) the conf±ne_to window (if any) is viewable, and

4) these constraints are not satisfied for any ancestor,

then the pointer is actively grabbed as described in XGrabPointer, the last pointer grab time is set to the time at which the button was pressed, and the ButtonPress event is reported.

The interpretation of the remaining arguments is as for XGrabPointer. The active grab is terminated automatically when all buttons are released (independent of the state of modifier keys).

A modifier of AnyModif ier is equivalent to issuing the grab request for all possible modifier combinations (including no modifiers). A button of AnyButton is equivalent to issuing the request for all possible buttons (but at least one).

XGrabButton overrides all previous passive grabs by the same client on the same key/button combination on the same window, but has no effect on an active grab. The request fails if some other client has already issued an XGrabButton with the same button/key combination on the same window. When using AnyModif ier or AnyButton, the request fails completely (no grabs are established) if there is a conflicting grab for any combination.

The owner_events argument specifies whether the grab window should receive all events (False) or whether the grabbing application should receive all events normally (True).

The pointer_mode and keyboard_mode control the processing of events during the grab. If either is GrabModeSync, events for that device are not sent from the server to Xlib until XAllowEvent s is called to release the events. If either is GrabModeAsync, events for that device are sent normally.

An automatic grab takes place between a ButtonPress event and the corresponding ButtonRelease event, so this call is not necessary in some of the most common situations. But this call is necessary for certain styles of menus.

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

XGrabButton

(continued)

Xlib- Grabbing

Errors

BadAccess When using AnyModif ier or AnyButton and there is a conflicting grab by another client. No grabs are established.

Another client has already issued an XGrabButton request with the same key/button combination on the same window.

BadCursor

BadValue

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabKey, XGrabKeyboard, XGrabPointer, XGrabServer,XUngrabButton,XUngrabKey, XUngrabKeyboard,XUngrab-Pointer, XUngrabServer.

272

Xlib Reference Manual

-xiib- Grabbing / XGrabKey

Name

XGrabKey — grab a key.

Synopsis

XGrabKey(display, keycode, modifiers, grab_window, owner_events, pointer_mode, keyboard_mode) Display *display; int keycode ; unsigned int modifiers; Window grab_window; Bool owner_events; int pointer_mode, keyboard_mode;

Arguments

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

keycode Specifies the keycode to be grabbed. It may be a modifier key. Specifying

AnyKey is equivalent to issuing the request for all key codes.

modifiers Specifies a set of keymasks. This is a bitwise OR of one or more of the fol lowing symbols: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, Mod3Mask, Mod4Mask, ModSMask, or AnyModifier. AnyModif ier is equivalent to issuing the grab key request for all possible modifier combinations (including no modifiers). All specified modifiers do not need to have currently assigned keycodes.

gr a £>_ window Specifies the window in which the specified key combination will initiate an active grab.

owner_events

Specifies whether the grab window should receive all events (True) or whether the grabbing application should receive all events normally (False).

point er_mode

Controls processing of pointer events during the grab. Pass one of these con stants: GrabModeSync or GrabModeAsync.

keyboard_mode

Controls processing of keyboard events during the grab. Pass one of these constants: GrabModeSync or GrabModeAsync.

Description

XGrabKey establishes a passive grab on the specified keys, such that when the specified key/modifier combination is pressed, the keyboard may be grabbed, and all keyboard events sent to this application. More formally, once an XGrabKey call has been issued on a particular key/button combination:

XGrabKey (continued) Xlib - Grabbing

• IF the keyboard is not already actively grabbed,

• AND the specified key, which itself can be a modifier key, is logically pressed when the specified modifier keys are logically down,

AND no other keys or modifier keys are logically down,

AND EITHER the grab window is an ancestor of (or is) the focus window OR the grab window is a descendent of the focus window and contains the pointer,

• AND a passive grab on the same key combination does not exist on any ancestor of the grab window,

THEN the keyboard is actively grabbed, as for XGrabKeyboard, the last keyboard grab time is set to the time at which the key was pressed (as transmitted in the KeyPress event), and the KeyPress event is reported.

The active grab is terminated automatically when the specified key is released (independent of the state of the modifier keys).

The pointer_mode and keyboard_mode control the processing of events during the grab. If either is GrabModeSync, events for that device are not sent from the server to Xlib until XAllowEvents is called to send the events. If either is GrabModeAsync, events for that device are sent normally.

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

Errors

BadAccess When using AnyModif ier or AnyKey and another client has grabbed any overlapping combinations. In this case, no grabs are established.

Another client has issued XGrabKey for the same key combination in

grab_window.

BadValue key code is not in the range between min_keycode and max_keycode as returned by XDisplayKeycodes.

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKeyboard, XGrabPointer, XGrabServer,XUngrabButton,XUngrabKey, XUngrabKeyboard,XUngrab-Pointer,XUngrabServer.

— Xlib-Grabbing-

J XGrabKeyboard

Name

XGrabKeyboard — grab the keyboard.

Synopsis

int XGrabKeyboard(display, grab_window, owner_events,

pointer_mode, keyboard_mode, time) Display *display; Window grab_window; Bool owner_events; int pointer_mode, keyboard_mode; Time time;

Arguments

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

grab_window Specifies the ID of the window that requires continuous keyboard input.

owner_events

Specifies a boolean value of either True or False. See Description below.

point er_mode

Controls processing of pointer events during the grab. Pass either Grab-ModeSync or GrabModeAsync.

keyboard_mode

Controls processing of keyboard events during the grab. Pass either Grab-ModeSync or GrabModeAsync.

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

expressed in milliseconds, or the constant Cur rent Time.

Description

XGrabKeyboard actively grabs control of the main keyboard. Further key events are reported only to the grabbing client. This request generates Focus In and FocusOut events.

XGrabKeyboard processing is controlled by the value in the cw/jer_events argument: If owner_events is False, all generated key events are reported to grab_window.

If owner_events is True, then if a generated key event would normally be reported to this client, it is reported normally. Otherwise the event is reported to grab_window.

Both KeyPress and KeyRelease events are always reported, independent of any event selection made by the client.

XGrabKeyboard processing of pointer events and keyboard events are controlled by poir7ter_modeand A:eyboard_/node:

• If the pointer_mode or keyboard_mode is GrabModeAsync, event processing for the respective device continues normally.

For keyboard_mode GrabModeAsync only: if the keyboard was currently frozen by this client, then processing of keyboard events is resumed.

Xlib Reference Manual 275

XGrabKeyboard (continued) Xlib - Grabbing

If the po±nter_mode or keyboard_mode is GrabModeSync, events for the respective device are queued by the server until a releasing XAllowEvents request occurs or until the keyboard grab is released as described above.

If the grab is successful, XGrabKeyboard returns the constant GrabSuccess. XGrab Keyboard fails under the following conditions and returns the following:

If the keyboard is actively grabbed by some other client, it returns AlreadyGrabbed. • If grab_window is not viewable, it returns GrabNotViewable.

If time is earlier than the last keyboard grab time or later than the current server time, it returns GrablnvalidTime.

If the pointer is frozen by an active grab of another client, the request fails with a status GrabFrozen.

If the grab succeeds, the last keyboard grab time is set to the specified time, with Current-Time replaced by the current X server time.

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

Errors

BadValue Badwindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabPointer, XGrab-Server, XUngrabButton,XUngrabKey,XUngrabKeyboard, XUngrabPointer, XUngrabServer.

-x»-tabbing / XGrabPointer

Name

XGrabPointer — grab the pointer.

Synopsis

int XGrabPointer (display, grab_window, owner_events,

event_mask r pointer_mode, keyboard_mode, confine_to, cursor, time) Display *display; Window grab_window; Bool owner_events; unsigned int event_mask; int point er_mode, keyboard_mode; Window confine_to; Cursor cursor; Time time;

Arguments

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

grab_window Specifies the ID of the window that should grab the pointer input independent of pointer location.

owner_events

Specifies if the pointer events are to be reported normally within this applica tion (pass True) or only to the grab window (pass False).

event_mask Specifies the event mask symbols that can be ORed together. Only events selected by this mask, plus ButtonPress and ButtonRelease, will be delivered during the grab. See XSelect Input for a complete list of event masks.

point er_mode

Controls further processing of pointer events. Pass either GrabModeSync

or GrabModeAsync.

keyboard_mode

Controls further processing of keyboard events. Pass either GrabModeSync or GrabModeAsync.

confine_to Specifies the ID of the window to confine the pointer. One option is None, in which case the pointer is not confined to any window.

cursor Specifies the ID of the cursor that is displayed with the pointer during the

grab. One option is None, which causes the cursor to keep its current pattern.

time Specifies the time when the grab request took place. Pass either a timestamp,

expressed in milliseconds (from an event), or the constant Cur rent Time.

XGrabPointer (continued) Xlib- Grabbing

Description

XGrabPointer actively grabs control of the pointer. Further pointer events are only reported to the grabbing client until XUngrabPointer is called.

event_mask is always augmented to include ButtonPressMask and ButtonRelease-Mask. If owner_events is False, all generated pointer events are reported to grab_window, and are only reported if selected by event_mask. If owner_e vents is True, then if a generated pointer event would normally be reported to this client, it is reported normally; otherwise the event is reported with respect to the grrab_window, and is only reported if selected by event_mask. For either value of owner_events, unreported events are discarded.

point er_mode controls processing of pointer events during the grab, and keyboard_mode controls further processing of main keyboard events. If the mode is GrabModeAsync, event processing continues normally. If the mode is GrabModeSync, events for the device are queued by the server but not sent to clients until the grabbing client issues a releasing XAllowE vents request or an XUngrabPo inter request.

If a cursor is specified, then it is displayed regardless of which window the pointer is in. If no cursor is specified, then when the pointer is in gra£>_window or one of its subwindows, the normal cursor for that window is displayed. When the pointer is outside grab_window, the cursor for grab_window is displayed.

If a con fin e_ to window is specified, then the pointer will be restricted to that window. The confine_to window need have no relationship to the graJb_window. If the pointer is not initially in the confine_to window, then it is warped automatically to the closest edge (and enter/leave events generated normally) just before the grab activates. If the conf~ine_to window is subsequently reconfigured, the pointer will be warped automatically as necessary to keep it contained in the window.

The time argument lets you avoid certain circumstances that come up if applications take a long while to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applica tions specify the timestamp from the ButtonPress event, the second application will suc cessfully grab the pointer, while the first will get a return value of AlreadyGrabbed, indicat ing that the other application grabbed the pointer before its request was processed. This is the desired response because the latest user action is most important in this case.

XGrabPointer generates EnterNotif y and LeaveNotif y events.

If the grab is successful, it returns the constant GrabSuccess. The XGrabPointer func tion fails under the following conditions, with the following return values:

• If grab_window or conf~ine_to window is not viewable, or if the conf ine_to window is completely off the screen, GrabNotviewable is returned.

If the pointer is actively grabbed by some other client, the constant AlreadyGrabbed is returned.

If the pointer is frozen by an active grab of another client, GrabFrozen is returned.

Xllb - Grabbing (continued) XGrabPointer

If the specified time is earlier than the last-pointer-grab time or later than the current X server time, GrablnvalidTime is returned. (If the call succeeds, the last pointer grab time is set to the specified time, with the constant CurrentTime replaced by the cur rent X server time.)

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

Errors

BadCursor

BadValue

BadWindow

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabServer,XUngrabButton,XUngrabKey, XUngrabKeyboard,XUngrab-Pointer,XUngrabServer.

XGrabServer

Xllb - Grabbing —

Name

XGrabServer — grab the server.

Synopsis

XGrabServer (display) Display * display ;

Arguments

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

Description

Grabbing the server means that only requests by the calling client will be acted on. All others will be queued in the server until the next XUngrabServer call. The X server should not be grabbed any more than is absolutely necessary.

Related Commands

XChangeActivePointerGrab, XGrabButton, XGrabKey, XGrabKeyboard, XGrabPointer,XUngrabButton,XUngrabKey,XUngrabKeyboard,XUngrab-Pointer, XUngrabServer.

Xlib Reference Manual

-Xlib - Window Manager Hints / XlCOPify WindOW

Name

XlconifyWindow — request that a top-level window be iconified.

Synopsis

Status XlconifyWindow(display, w, screen_number) Display * display; Window w; int screen_number;

Arguments

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

w Specifies the window.

screen_number

Specifies the appropriate screen number on the server.

Availability

Release 4 and later.

Description

XlconifyWindow sends a WM_CHANGE_STATE ClientMessage event with a format of 32 and a first data element of Iconicstate (as described in Section 4.1.4 of the Inter-Client Communication Conventions Manual in Volume Zero, X Protocol Reference Manual), to the root window of the specified screen. Window managers may elect to receive this message and, if the window is in its normal state, may treat it as a request to change the window's state from normal to iconic. If the WM_CHANGE_STATE property cannot be interned, XlconifyWindow does not send a message and returns a zero status. It returns a nonzero status if the client mes sage is sent successfully; otherwise, it returns a zero status.

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

Errors

BadWindow

Related Commands

XReconfigureWindow,XWithdrawWindow.

Name

XlfEvent — wait for event matched in predicate procedure.

Synopsis

XlfEvent( display, event, predicate, args) Display *d±splay;

XEvent * event; /* RETURN */

Bool (*predicate) () ; char *args;

Arguments

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

event Returns the matched event.

predicate Specifies the procedure to be called to determine if the next event satisfies your criteria.

args Specifies the user-specified arguments to be passed to the predicate proce

dure.

Description

XlfEvent checks the event queue for events, uses the user-supplied routine to check if one meets certain criteria, and removes the matching event from the input queue. XlfEvent returns only when the specified predicate procedure returns True for an event. The specified predicate is called once for each event on the queue until a match is made, and each time an event is added to the queue, with the arguments display, event, and arg.

If no matching events exist on the queue, XlfEvent flushes the request buffer and waits for an appropriate event to arrive. Use XChecklfEvent if you don't want to wait for an event.

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

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

282 Xlib Reference Manual

—Xlib - Resource Manager-

J XlnsertModifiermapEntry

Name

XlnsertModifiermapEntry — add a new entry to an XModif ierKeymap structure. Synopsis

XModif ierKeymap *XInsertModif iermapEntry (modmap,

keysym_entry, modifier) XModifierKeymap * modmap; KeyCode keysym_entry; int modifier;

Arguments

modmap Specifies a pointer to an XModif ierKeymap structure.

£ ey sym_ entry

Specifies the keycode of the key to be added to modmap.

modifier Specifies the modifier you 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

XlnsertModifiermapEntry 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). Xlnsert ModifiermapEntry does not change the mapping itself.

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 Xlnsert-

Modi f ie rmapEnt ry.

Note that the structure pointed to by modmap is freed by XlnsertModifiermapEntry. It

should not be freed or otherwise used by applications.

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

#define ControlMapIndex 2 #define ModlMapIndex

#define Mod2MapIndex 4

#define ModSMapIndex 5

Xlib Reference Manual

XlnsertModif iermapEntry (continued) Xlib - Resource Manager

fdefine Mod4MapIndex 6

tdefine ModSMapIndex 7

Related Commands

XDeleteModifiermapEntry,XFreeModifiermap, XGetKeyboardMapping, XGetModif ierMapping, XKeycodeToKeysym, XKeysymToKeycode, XKeysymTo-String, XLookupKeysym, XLookupString, XNewModifierMap, XQueryKeymap, XRebindKeySym, XRefreshKeyboardMapping, XSetModifierMapping, XStringToKeysym.

—Xlib-Colormaps-

j XlnstallColormap

Name

XlnstallColormap — install a colormap.

Synopsis

XlnstallColormap (display, cmap) Display * display; Colormap cmap;

Arguments

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

cmap Specifies the colormap to install.

Description

XlnstallColormap installs a virtual colormap into a hardware company. If there is only one hardware colormap, XlnstallColormap loads a virtual colormap into the hardware colormap. All windows associated with this colormap immediately display with their chosen colors. Other windows associated with the old colormap will display with false colors.

If additional hardware colormaps are possible, XlnstallColormap loads the new hardware map and keeps the existing ones. Other windows will then remain in their true colors unless the limit for colormaps has been reached. If the maximum number of allowed hardware colormaps is already installed, an old colormap is swapped out The MinCmapsOf Screen (screen) and MaxCmapsOf Screen (screen) macros can be used to determine how many hardware colormaps are supported.

If cmap is not already an installed map, a ColormapNotify event is generated on every window having cmap as an attribute. If a colormap is uninstalled as a result of the install, a ColormapNotify event is generated on every window having that colormap as an attribute.

Colormaps are usually installed and uninstalled by the window manager, not by clients.

At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the "required list." The length of the required list is at most the min_maps specified for each screen in the Display structure. When a colormap is installed with XlnstallColormap it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at mim_maps. When a colormap is uninstalled with XUninstallColormap and it is in the required list, it is removed from the list. No other actions by the server or the client change the required list. It is important to realize that on all but high-performance workstations, min_maps is likely to be 1.

If the hardware colormap is immutable, and therefore installing any colormap is impossible, XlnstallColormap will work but not do anything.

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

BadColormap

XlnstallColormap (continued) Xlib - Colormaps

Related Commands

DefaultColormap,DisplayCells, XCopyColormapAndFree, XCreate-Colormap,XFreeColormap,XGetStandardColormap,XListlnstalled-Colormaps, XSetStandardColormap,XSetWindowColormap,XUninstall-Colormap.

286

Xlib Reference Manual

-Xllb - Properties / XlntelTlAtOm

Name

XInternAtom — return an atom for a given property name string.

Synopsis

Atom XInternAtom (display, property_name, only_if_exists) Display * display; char *property_name ; Bool only_if_exists ;

Arguments

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

property_name

Specifies the string name of the property for which you want the atom. Upper or lower case is important. 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.

only_if_exists

Specifies a boolean value: if no such property_name exists Xlntern-Atom will return None if this argument is set to True or will create the atom if it is set to False.

Description

XInternAtom returns the atom identifier corresponding to string property_name.

If the atom does not exist, then XInternAtom either returns None (if only_if_exists is True) or creates the atom and returns its ID (if only_if_exists is False).

The string name should be a null-terminated. Case matters: the strings "thing," "Thing," and "thinG" all designate different atoms.

The atom will remain defined even after the client that defined it has exited. It will become undefined only when the last connection to the X server closes. Therefore, the number of atoms interned should be kept to a minimum.

This function is the opposite of XGetAtomName, which returns the atom name when given an atom ID.

Predefined atoms require no call to XInternAtom. Predefined atoms are defined in <Xll/Xatom.h> and begin with the prefix "XA_". Predefined atoms are the only ones that do not require a call to XInternAtom.

Errors

BadAlloc BadValue

XlnternAtom (continued) Xlib - Properties

Related Commands

XChangeProperty,XDeleteProperty,XGetAtomName, XGetFontProperty, XGetWindowProperty,XListProperties, XRotateWindowProperties,XSet-StandardProperties.

Xlib Reference Manual

— Xlib-Regions-

/ XlntersectRegion

Name

XlntersectRegion — compute the intersection of two regions. Synopsis

XlntersectRegion (sra, srb, dr) Region sra, srb; Region dr; /* RETURN */

Arguments

sra Specify the two regions with which to perform the computation.

srb

dr Returns the result of the computation.

Description

XlntersectRegion generates a region that is the intersection of two regions.

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion,XDestroyRegion,XEmptyRegion,XEqualRegion, XOffsetRegion,XPointlnRegion,XPolygonRegion,XRectlnRegion,XSet-Region, XShrinkRegion,XSubtractRegion, XUnionRectWithRegion,XUnion-Region,XXorRegion.

XKeycodeToKeysym \ X||b Keyboard _

Name

XKeycodeToKeysym — convert a key code to a keysym.

Synopsis

KeySym XKeycodeToKeysym(display, keycode, index) Display *display; KeyCode keycode ; int index;

Arguments

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

keycode Specifies the keycode.

index Specifies which keysym in the list for the keycode to return.

Description

XKeycodeToKeysym returns one of the keysyms defined for the specified keycode. XKeycodeToKeysym uses internal Xlib tables, index specifies which keysym in the array of keysyms corresponding to a keycode should be returned. If no symbol is defined, XKeycodeToKeysym returns NoSymbol.

Related Commands

IsCursorKey,IsFunctionKey, IsKeypadKey, IsMiscFunctionKey, Is-Modif ierKey, IsPFKey, XChangeKeyboardMapping, XDeleteModifiermap-Entry,XDisplayKeycodes,XFreeModifiermap, XGetKeyboardMapping,XGet-ModifierMapping, XInsertModifiermapEntry,XKeysymToKeycode, XKeysym-ToString, XLookupKeysym, XLookupString, XNewModifierMap,XQuery-Keymap,XRebindKeySym, XRefreshKeyboardMapping,XSetModifierMapping, XStringToKeysym.

— Xlib-Keyboard-

J XKeysymToKeycode

Name

XKeysymToKeycode — convert a keysym to the appropriate keycode.

Synopsis

KeyCode XKeysymToKeycode(display, keysym) Display *display; Keysym keysym;

Arguments

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

keysym Specifies the keysym that is to be searched for.

Description

XKeysymToKeycode returns the keycode corresponding to the specified keysym in the cur rent mapping. If the specified keysym is not defined for any keycode, XKeysymToKeycode returns zero.

Related Commands

IsCursorKey,IsFunctionKey,IsKeypadKey, IsMiscFunctionKey,Is-ModifierKey,IsPFKey, XChangeKeyboardMapping, XDeleteModifiermap-Entry, XDisplayKeycodes,XFreeModifiermap, XGetKeyboardMapping, XGet-ModifierMapping,XInsertModifiermapEntry,XKeycodeToKeysym, XKeysym-ToString, XLookupKeysym, XLookupString, XNewModifierMap,XQuery-Keymap, XRebindKeySym, XRefreshKeyboardMapping, XSetModifierMapping, XStringToKeysym.

XKeysymToString \ XB> _ Keyboard _

Name

XKeysymToString — convert a keysym symbol to a string.

Synopsis

char *XKeysymToString (keysym) KeySym keysym;

Arguments

keysym Specifies the keysym that is to be converted.

Description

XKeysymToString converts a keysym symbol (a number) into a character string. The returned string is in a static area and must not be modified. If the specified keysym is not defined, XKeysymToString returns NULL. For example, XKeysymToString converts XK_Shift to "Shift".

Note that XKeysymString does not return the string that is mapped to the keysym, but only a string version of the keysym itself. In other words, even if the Fl key is mapped to the string "-STOP" using XRebindKeysym, XKeysymToString still returns "Fl". XLookupString, however, would return "STOP".

In Release 4, XKeysymToString can process keysyms that are not defined by the Xlib stan dard. Note that the set of keysyms that are available in this manner and the mechanisms by which Xlib obtains them is implementation dependent. (In the MIT sample implementation, the resource file lusrlliblXl 1 IXKeysymDB is used starting in Release 4. The keysym name is used as the resource name, and the resource value is the keysym value in uppercase hexade cimal.)

Related Commands

IsCursorKey, IsFunctionKey,IsKeypadKey, IsMiscFunctionKey,Is-ModifierKey,IsPFKey, XChangeKeyboardMapping,XDeleteModifiermap-Entry,XFreeModifiermap, XGetKeyboardMapping, XGetModifierMapping, XInsertModifiermapEntry,XKeycodeToKeysym, XKeysymToKeycode, XLookupKeysym, XLookupString,XNewModifierMap, XQueryKeymap, XRebind Keysym, XRefreshKeyboardMapping,XSetModifierMapping, XStringTo-Keysym.

/

XKIIICIient

Name

XKillClient — destroy a client or its remaining resources.

Synopsis

XKillClient (display, resource) Display * display; XID resource;

Arguments

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

resource Specifies any resource created by the client you want to destroy, or the con stant AllTemporary.

Description

If a valid resource is specified, XKillClient forces a close-down of the client that created the resource. If the client has already terminated in either RetainPermanent or Retain-Temporary mode, all of the client's resources are destroyed. If AllTemporary is specified in the resource argument, then the resources of all clients that have terminated in Retain-Temporary are destroyed.

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

Errors

BadValue

Related Commands

XSetCloseDownMode.

XLiStDepthS \ x,ib-W,ndowM a na g erH,ms-

Name

XListDepths — determine the depths available on a given screen.

Synopsis

int *XListDepths(display, screen_number, count) Display *display; int screen_number; int * count; /* RETURN */

Arguments

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

screen_number

Specifies the appropriate screen number on the host server.

count Returns the number of depths.

Availability

Release 4 and later.

Description

XListDepths returns the array of depths that are available on the specified screen. If the specified screen_number is valid and sufficient memory for the array can be allocated, XListDepths sets count to the number of available depths. Otherwise, it does not set count and returns NULL. To release the memory allocated for the array of depths, use XFree.

Related Commands

DefaultDepthOf Screen macro, Def aultDepth macro, XListPixmapFormats.

-Xlib- Extensions / XLiStExtensiOHS

Name

XListExtensions — return a list of all extensions to X supported by Xlib and the server.

Synopsis

char **XListExtensions (display, nextensions) Display *disp_Zay; int *nextensions; /* RETURN */

Arguments

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

nextensions Returns the number of extensions in the returned list.

Description

XListExtensions lists all the X extensions supported by Xlib and the current server. The returned strings will 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 west ern languages other than English.

For more information on extensions, see Volume One, Chapter 13, Other Programming Tech niques.

Related Commands

XFreeExtensionList,XQueryExtension.

Xlib Reference Manual 295

XListFonts "\

•Xlib-Fonts-

Name

XListFonts — return a list of the available font names.

Synopsis

char **XListFonts( display, pattern, maxnames, actual_count) Display * display; char * pattern; int maxnames; int * actual_count ; /* RETURN */

Arguments

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

pattern Specifies the string associated with the font names you want returned. You

can specify any string, including asterisks (*), and question marks. The aster isk indicates a wildcard for any number of characters and the question mark indicates a wildcard for a single character. Upper or lower case is not impor tant. 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.

maxnames Specifies the maximum number of names that are to be in the returned list.

actual_count

Returns the actual number of font names in the list.

Description

XListFonts returns a list of font names that match the string pattern. Each returned font name string is terminated by NULL and is lower case. The maximum number of names returned in the list is the value you passed to maxnames. The function returns the actual number of font names in actual_count.

If no fonts match the specified names, XListFonts returns NULL.

The client should call XFreeFontNames when done with the font name list.

The font search path (the order in which font names in various directories are compared to pat tern) is set by XSetFontPath.

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

XCreateFontCursor,XFreeFont,XFreeFontlnfo,XFreeFontNames,XFree-FontPath,XGetFontPath,XGetFontProperty, XListFontsWithlnfo, XLoad-Font, XLoadQueryFont,XQueryFont,XSetFont, XSetFontPath, XUnloadFont.

-xnb- Fonts J XListFontsWithlnfo

Name

XListFontsWithlnfo — obtain the names and information about loaded fonts.

Synopsis

char **XListFontsWithInfo( display, pattern, maxnames,

count, info) Display *disp_Zay;

char *pattern; /* null-terminated */

int maxnames;

int * count; /* RETURN */

XFontStruct **info; /* RETURN */

Arguments

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

pattern Specifies the string associated with the font names you want returned. You

can specify any string, including asterisks (*) and question marks. The aster isk indicates a wildcard on any number of characters and the question mark indicates a wildcard on a single character. Upper or lower case is not impor tant. 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.

maxnames Specifies the maximum number of names that are to be in the returned list. count Returns the actual number of matched font names.

info Returns a pointer to a list of font information structures. XListFonts

Withlnfo provides enough space for maxnames pointers.

Description

XListFontsWithlnfo returns a list of font names that match the specified pattern and a also returns limited information about each font that matches. The list of names is limited to the size specified by the maxnames argument The list of names is in lower case.

XListFontsWithlnfo returns NULL if no matches were found.

To free the allocated name array, the client should call XFreeFontNames. To free the font information array, the client should call XFreeFont Info.

The information returned for each font is identical to what XQueryFont would return, except that the per-character metrics (Ibearing, rbearing, width, ascent, descent for single characters) are not returned.

The font search path (the order in which font names in various directories are compared to pattern) is set by XSetFontPath. XListFonts returns NULL if no matches were found.

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

XListFontsWithlnfo

(continued)

Xlib - Fonts

Structures

typedef struct {

XExtData *ext_data; /*

Font fid; /*

unsigned direction; /* unsigned min_char_or_byte2; /* unsigned max_char_or_byte2; /*

unsigned min bytel; /*

unsigned max_bytel; /*

Bool all_chars exist; /*

unsigned default_char; /*

int n_properties; /*

XFontProp *properties; /*

XCharStruct min bounds; /*

XCharStruct max_bounds; /*

XCharStruct *per_char; /*

int ascent; /*

int descent; /*

} XFontStruct;

hook for extension to hang data */

Font ID for this font */

hint about direction the font is painted */

first character */

last character */

first row that exists */

last row that exists */

flag if all characters have nonzero size*/

char to print for undefined character */

how many properties there are */

pointer to array of additional properties*/

minimum bounds over all existing char*/

minimum bounds over all existing char*/

first_char to last_char information */

logical extent above baseline for spacing */

logical descent below baseline for spacing */

Related Commands

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

298

Xlib Reference Manual

_X,ib - Host Access / XLJStHOStS

Name

XListHosts — obtain a list of hosts having access to this display.

Synopsis

XHostAddress *XListHosts(display, nhosts, state) Display * display;

int *nhosts; /* RETURN */

Bool *state; /* RETURN */

Arguments

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

nhosts Returns the number of hosts currently in the access control list.

state Returns whether the access control list is currently being used by the server to

process new connection requests from clients. True if enabled, False if disabled.

Description

XListHosts returns the current access control list as well as whether the use of the list is enabled or disabled. XListHosts allows a program to find out what machines make connec tions, by looking at a list of host structures. This XHost Address list should be freed when it is no longer needed. XListHosts returns NULL on failure.

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

Structures

typedef struct {

int family;

int length;

char *address; } XHostAddress;

Related Commands

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

XListlnstalledColormaps \ X|lb _ Colormaps _

Name

XListlnstalledColormaps — get a list of installed colormaps.

Synopsis

Colormap *XListInstalledColormaps( display, w, num) display * display ; Window w; int *num; /* RETURN */

Arguments

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

w Specifies the ID of the window for whose screen you want the list of currently

installed colormaps.

num Returns the number of currently installed colormaps in the returned list.

Description

XListlnstalledColormaps returns a list of the currently installed colormaps for the screen containing the specified window. The order in the list is not significant. There is no dis tinction in the list between colormaps actually being used by windows and colormaps no longer in use which have not yet been freed or destroyed.

XListlnstalledColormaps returns None and sets num to zero on failure.

The allocated list should be freed using XFree when it is no longer needed.

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

Errors

BadWindow

Related Commands

DefaultColormap,DisplayCells,XCopyColormapAndFree,XCreate-Colormap,XFreeColormap,XGetStandardColormap,XInstallColormap, XSetStandardColormap,XSetWindowColormap, XUninstallColormap.

-Xllb- Window Manager Hints / XLJStPixmapFormatS

Name

XListPixmapFormats — obtain the supported pixmap formats for a given server.

Synopsis

XPixmapFormatValues *XListPixmapFormats{ display, count) Display ^display; int * count; /* RETURN */

Arguments

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

count Returns the number of pixmap formats that are supported by the server.

Availability

Release 4 and later.

Description

XListPixmapFormats returns an array of XPixmapFormatValues structures that describe the types of Z format images that are supported by the specified server. If insufficient memory is available, XListPixmapFormats returns NULL. To free the allocated storage for the XPixmapFormatValues structures, use XFree.

Structures

typedef struct {

int depth;

int bits_per_pixel;

int scanline_pad; } XPixmapFormatValues;

Related Commands

XListDepths.

XListProperties \,

^ Xlib - Properties-Name

XListProperties — get the property list for a window.

Synopsis

Atom *XListProperties( display, w, num_prop) Display *display; Window w; int *num_jprop; /* RETURN */

Arguments

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

w Specifies the window whose property list you want.

num_prop Returns the length of the properties array.

Description

XListProperties returns a pointer to an array of atoms for properties that are defined for the specified window. XListProperties returns NULL on failure (when window w is inva lid).

To free the memory allocated by this function, use XFree.

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

Errors

BadWindow

Related Commands

XChangeProperty,XDeleteProperty,XGetAtomName,XGetFontProperty, XGetWindowProperty, XInternAtom, XRotateWindowProperties,XSet-StandardProperties.

-xiib - Fonts / XLoadFont

Name

XLoadFont — load a font if not already loaded; get font ID.

Synopsis

Font XLoadFont(display, name) Display *display; char *name;

Arguments

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

name Specifies the name of the font in a null terminated string. As of Release 4, the

* and ? wildcards are allowed and may be supported by the server. Upper or lower case is not important. 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.

Description

XLoadFont loads a font into the server if it has not already been loaded by another client. XLoadFont returns the font ID or, if it was unsuccessful, generates a BadName error. When the font is no longer needed, the client should call xunloadFont. Fonts are not associated with a particular screen. Once the font ID is available, it can be set in the font member of any GC, and thereby used in subsequent drawing requests.

Font information is usually necessary for locating the text. Call XLoadFontwithinf o to get the info at the time you load the font, or call XQueryFont if you used XLoadFont to load the font.

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

Errors

BadAlloc Server has insufficient memory to store font.

BadName name specifies an unavailable font

Related Commands

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

XLoadQueryFont , x,,bF on,s-

Name

XLoadQueryFont — load a font and fill information structure.

Synopsis

XFontStruct *XLoadQueryFont( display, name) Display *display; char *name;

Arguments

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

name Specifies the name of the font. This name is a null terminated string. As of

Release 4, the * and ? wildcards are allowed and may be supported by the server. Upper or lower case is not important.

Description

XLoadQueryFont performs an XLoadFont and XQueryFont in a single operation. XLoad QueryFont provides the easiest way to get character-size tables for placing a proportional font. That is, XLoadQueryFont both opens (loads) the specified font and returns a pointer to the appropriate XFontStruct structure. If the font does not exist, XLoadQueryFont returns NULL.

The XFontStruct structure consists of the font-specific information and a pointer to an array of xcharstruct structures for each character in the font.

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

Errors

BadAlloc server has insufficient memory to store font

BadName name specifies an unavailable font

Structures

typedef struct {

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

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

unsigned direction; /* hint about direction the font is painted */

unsigned min_char_or_byte2; /* first character */

unsigned max_char_or_byte2; /* last character */

unsigned min_bytel; /* first row that exists */

unsigned max_bytel; /* last row that exists */

Bool all_chars_exist; /* flag if all characters have nonzero size*/

unsigned default_char; /* char to print for undefined character */

int n_properties; /* how many properties there are */

XFontProp *properties; /* pointer to array of additional properties*/

XCharStruct min_bounds; /* minimum bounds over all existing char*/

XCharStruct max_bounds; /* minimum bounds over all existing char*/

XCharStruct *per_char; /* first_char to last_char information */

int ascent; /* logical extent above baseline for spacing */

int descent; /* logical descent below baseline for spacing */

} XFontStruct;

304 Xlib Reference Manual

Xlib - Fonts

(continued)

XLoadQueryFont

typedef struct {

short Ibearing; /*

short rbearing; /*

short width; /*

short ascent; /*

short descent; /* unsigned short attributes; /*

} XCharStruct;

origin to left edge of character */ origin to right edge of character */ advance to next char's origin */ baseline to top edge of character */ baseline to bottom edge of character per char flags (not predefined) */

Related Commands

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

Xlib Reference Manual

XLookllpAssoc A

XI ib - Association Tables —

Name

XLookUpAssoc — obtain data from an association table.

Synopsis

caddr_t XLookUpAssoc( display, table, x_id) Display *display; XAssocTable * table; XID x_id;

Arguments

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

t abl e Specifies the association table.

x_i d Specifies the X resource ID.

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.

Association tables provide a way of storing data locally and accessing by ID. XLookUp Assoc retrieves the data stored in an XAssocTable by its XID. If the matching XID can be found in the table, the routine returns the data associated with it. If the x_i d cannot be found in the table the routine returns NULL.

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

typedef struct {

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

} XAssocTable;

typedef struct _XAssoc {

struct _XAssoc *next; /* next object in this bucket */

struct _XAssoc *prev; /* previous object in this bucket */

Display *display; /* display which owns the ID */

XID x_id; /* X Window System ID */

char *data; /* pointer to untyped memory */

} XAssoc;

Related Commands

XCreateAssocTable,XDeleteAssoc,XDestroyAssocTable,XMakeAssoc.

— Xllb-Color Cells-

j XLookupColor

Name

XLookupColor — get database RGB values and closest hardware-supported RGB values from color name.

Synopsis

Status XLookupColor( display, cmap f colorname, rgb_db_def f

hardware_def) Display ^display; Colormap cmap ; char * colorname ; XColor *rgb_db_def r *hardware_def ; /* RETURN */

Arguments

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

cmap Specifies the colormap.

colorname Specifies a color name string (for example "red"). 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.

rgb_db_def Returns the exact RGB values for the specified color name from the lusrlliblXlllrgb database.

hardware_def Returns the closest RGB values possible on the hardware.

Description

XLookupColor looks up RGB values for a color given the colorname string. It returns both the exact color values and the closest values possible on tthe screen specified by cmap.

XLookupColor returns nonzero if colorname exists in the RGB database or zero if it does not exist.

To determine the exact RGB values, XLookupColor uses a database on the X server. On UNIX, this database is lusrlliblXlllrgb, To read the colors provided by the database on a UNIX-based system, see lusrlliblXlllrgb.txt. The location, name, and contents of this file are server-dependent.

For more information see Volume One, Chapter 7, Color, and Appendix D, The Color Data base, in this volume.

Xlib Reference Manual

XLOQkupColor (continued) Xlib - Color Cells

Errors

BadName Color name not in database.

BadColormap Specified colormap invalid. 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, XAllocNamedColor,XFreeColors,XParseColor,XQueryColor, XQueryColors,XStoreColor,XStoreColors, XStoreNamedColor.

— Xlib-Keyboard •

J XLookupKeysym

Name

XLookupKeysym — get the keysym corresponding to a keycode in structure.

Synopsis

KeySym XLookupKeysym( event, index) XKeyEvent * event; int index;

Arguments

event Specifies the KeyPress or KeyRelease event that is to be used.

index Specifies which keysym from the list associated with the keycode in the event to

return. These correspond to the modifier keys, and the symbols ShiftMap-Index, LockMapIndex, ControlMapIndex, ModlMapIndex, Mod2-Maplndex, ModSMapIndex, Mod4MapIndex, and ModSMapIndex can be used.

Description

Given a keyboard event and the index into the list of keysyms for that keycode, XLookup Keysym returns the keysym from the list that corresponds to the keycode in the event. If no keysym is defined for the keycode of the event, XLookupKeysym returns NoSymbol.

Each keycode may have a list of associated keysyms, which are portable symbols representing the meanings of the key. The index specifies which keysym in the list is desired, indicating the combination of modifier keys that are currently pressed. Therefore, the program must inter pret the state member of the XKeyEvent structure to determine the index before calling this function. The exact mapping of modifier keys into the list of keysyms for each keycode is server-dependent beyond the fact that the first keysym corresponds to the keycode without modifier keys, and the second corresponds to the keycode with Shift pressed.

XLookupKeysym simply calls XKeycodeToKeysym, using arguments taken from the speci fied event structure.

Structures

typedef struct {

int type; /* of event */

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

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

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

Window window; /* "event" window it is reported relative to */

Window root; /* root window that the event occured on */

Window subwindow; /* child window */

Time time; /* milliseconds */

int x, y; /* pointer x, y coordinates in event window */

int x root, y root; /* coordinates relative to root */

unsigned int state; /* key or button mask */

unsigned int keycode; /* detail */

Bool same_screen; /* same screen flag */

} XKeyEvent;

XLOQkupKeysym (continued) Xlib - Keyboard

Related Commands

XChangeKeyboardMapping, XDeleteModif iermapEntry, XFreeModif iermap, XGetKeyboardMapping,XGetModifierMapping, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode,XKeysymToString, XLookupString, XNewModifierMap,XQueryKeymap,XRebindKeysym, XRefreshKeyboard-Mapping,XSetModifierMapping,XStringToKeysym.

—Xlib-Keyboard •

J XLookupString

Name

XLookupString — map a key event to ASCH string, keysym, and ComposeStatus.

Synopsis

int XLookupString( event, buffer, num_bytes, keysym, status) XKeyEvent *event;

char * buffer; /* RETURN */

int num_bytes ;

KeySym * keysym; /* RETURN */

XComposeStatus *status; /* not implemented */

Arguments

event Specifies the key event to be used.

buffer Returns the resulting string.

num_bytes Specifies the length of the buffer. No more than num_bytes of translation are returned.

keysym If this argument is not NULL, it specifies the keysym ID computed from the

event.

status Specifies the XCompose structure that contains compose key state informa

tion and that allows the compose key processing to take place. This can be NULL if the caller is not interested in seeing compose key sequences. Not implemented in X Consortium Xlib through Release 4.

Description

XLookupString gets an ASCH string and a keysym that are currently mapped to the keycode in a KeyPress or KeyRelease event, using the modifier bits in the key event to deal with shift, lock and control. The XLookupString return value is the length of the translated string and the string's bytes are copied into buffer. The length may be greater than 1 if the event's keycode translates into a keysym that was rebound with XRebindKeysym.

The compose status is not implemented in any release of the X Consortium version of Xlib through Release 4.

In Release 4, XLookupString implements the new concept of keyboard groups. Keyboard groups support having two complete sets of keysyms for a keyboard. Which set will be used can be toggled using a particular key. This is implemented by using the first two keysyms in the list for a key as one set, and the next two keysyms as the second set. For more information on keyboard groups, see Volume One, Appendix G, Release Notes.

For more information on using XLookupString in general, see Volume One, Chapter 9, The Keyboard and Pointer.

Structures

/*

* Compose sequence status structure, used in calling XLookupString. */

XLOQkupString (continued) Xlib - Keyboard

typedef struct _XComposeStatus {

char *compose_ptr; /* state table pointer */

int chars_matched; /* match state */ } XComposeStatus;

typedef struct {

int type; /* of event */

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

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

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

Window window; /* "event" window it is reported relative to */

Window root; /* roo t window that the event occured on */

Window subwindow; /* child window */

Time time; /* milliseconds */

L x/ y; /* Pointer x, y coordinates in event window */

int x_root, y_root; /* coordinates relative to root */

unsigned int state; /* key or button mask */

unsigned int keycode; /* detail */

Bool same_screen; /* same screen flag */ } XKeyEvent;

Related Commands

XChangeKeyboardMapping,XDeleteModifiermapEntry,XFreeModifiermap

XGetKeyboardMapping,XGetModifierMa P ping,XInsertModifierma P Entry'

<eycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym'

f ierMap, XQueryKeymap, XRebindKeySym, XRefreshKeyboard-Mapping,XSetModifierMapping, XStringToKeysym.

312

Xlib Reference Manual

-Xlib-Window Manipulation ' XLOWerWilldOW

Name

XLowerWindow — lower a window in the stacking order.

Synopsis

XLowerWindow (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 to be lowered.

Description

XLowerWindow lowers a window in the stacking order of its siblings so that it does not obscure any sibling windows. If the windows are regarded as overlapping sheets of paper stacked on a desk, then lowering a window is analogous to moving the sheet to the bottom of the stack, while leaving its x and y location on the desk constant. Lowering a mapped window will generate exposure events on any windows it formerly obscured.

If the override_redirect attribute of the window (see Chapter 4, Window Attributes) is False and the window manager has selected SubstructureRedirectMask on the par ent, then a Conf igureRequest event is sent to the window manager, and no further pro cessing is performed. Otherwise, the window is lowered to the bottom of the stack.

LeaveNotify events are sent to the lowered window if the pointer was inside it, and EnterNotif y events are sent to the window which was immediately below the lowered win dow at the pointer position.

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

Errors

BadWindow

Related Commands

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

XMakeAssoc \ X||b _ Assoc|atlon Tab|es _

Name

XMakeAssoc — create an entry in an association table.

Synopsis

XMakeAssoc( display, table, x_id f data) Display * display; XAssocTable * table; XID x_id; caddr_t data;

Arguments

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

tabl e Specifies the association table in which an entry is to be made.

x_i d Specifies the X resource ID.

data Specifies the data to be associated with the X resource ID.

Description

XMakeAssoc inserts data into an XAssocTable keyed on an XID. Association tables allow you to easily associate data with resource ID's for later retrieval. Association tables are local, accessible only by this client.

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.

Data is inserted into the table only once. Redundant inserts are meaningless and cause no prob lems. The queue in each association bucket is sorted from the lowest XID to the highest XID.

For more information, see Volume One, Appendix B,X70 Compatibility. Structure

typedef struct {

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

} XAssocTable;

typedef struct _XAssoc {

struct _XAssoc *next; /* next object in this bucket */

struct _XAssoc *prev; /* previous object in this bucket */

Display *display; /* display which owns the ID */

XID x_id; /* X Window System ID */

char *data; /* pointer to untyped memory */

} XAssoc;

Related Commands

XCreateAssocTable,XDeleteAssoc,XDestroyAssocTable,XLookUpAssoc.

—Xlib - Window Mapping •

J XMapRaised

Name

XMapRaised — map a window on top of its siblings.

Synopsis

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

Arguments

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

w Specifies the window ID of the window to be mapped and raised.

Description

XMapRaised marks a window as eligible to be displayed. It will actually be displayed if its ancestors are mapped, it is on top of sibling windows, and it is not obscured by unrelated win dows. XMapRaised is similar to XMapWindow, except it additionally raises the specified window to the top of the stack among its siblings. Mapping an already mapped window with XMapRaised raises the window. See XMapWindow for further details.

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

BadWindow

Related Commands

XMapSubwindows, XMapWindow, XUnmapSubwindows, XUnmapWindow.

Xlib Reference Manual

XMapSubwindows

Xlib - Window Mapping-Name

XMapSubwindows — map all subwindows of window.

Synopsis

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

Arguments

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

w Specifies the ID of the window whose subwindows are to be mapped.

Description

XMapSubwindows maps all subwindows of a window in top-to-bottom stacking order. XMapSubwindows also generates an Expose event on each newly displayed window. This is much more efficient than mapping many windows one at a time, as much of the work need only be performed once for all of the windows rather than for each window. XMap Subwindows is not recursive — it does not map the subwindows of the subwindows.

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

BadWindow

Related Commands

XMapRaised, XMapWindow, XUnmapSubwindows, XUnmapWindow.

-Xlib - Window Mapping ' XMapWindOW

Name

XMapWindow — map a window.

Synopsis

XMapWindow (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 to be mapped.

Description

XMapWindow maps a window, making it eligible for display depending on its stacking order among its siblings, the mapping status of its ancestors, and the placement of other visible win dows. If all the ancestors are mapped, and it is not obscured by siblings higher in the stacking order, the window and all of its mapped subwindows are displayed.

Mapping a window that has an unmapped ancestor does not display the window but marks it as eligible for display when its ancestors become mapped. Mapping an already mapped window has no effect (it does not raise the window).

Note that for a top-level window, the window manager may intervene and delay the mapping of the window. The application must not draw until it has received an Expose event on the win dow.

If the window is opaque, XMapWindow generates Expose events on each opaque window that it causes to become displayed. If the client first maps the window, then paints the window, then begins processing input events, the window is painted twice. To avoid this, the client should use either of two strategies:

1. Map the window, call XSelect Input for exposure events, wait for the first Expose event, and repaint each window explicitly.

2. Call XSelect Input for exposure events, map, and process input events normally. Exposure events are generated for each window that has appeared on the screen, and the client's normal response to an Expose event should be to repaint the window.

The latter method is preferred as it usually leads to simpler programs. If you fail to wait for the Expose event in the first method, it can cause incorrect behavior with certain window manag ers that intercept the request.

Errors

BadWindow

Related Commands

XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow.

XMaskEvent \ X|lb _ |nput Hand||ng _

Name

XMaskEvent — remove the next event that matches mask.

Synopsis

XMaskEvent ( display, event_mask, rep) Display *display; long event_mask; XEvent *rep; /* RETURN */

Arguments

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

event_mask Specifies the event mask. See XSelectInput for a complete list of the event mask symbols that can be ORed together.

rep Returns the event removed from the input queue.

Description

XMaskEvent removes the next event in the queue which matches the passed mask. The event is copied into an XEvent supplied by the caller. Other events in the queue are not discarded. If no such event has been queued, XMaskEvent flushes the request buffer and waits until one is received. Use XCheckMaskEvent if you do not wish to wait.

XMaskEvent never returns MappingNotify, SelectionClear, SelectionNotify, or SelectionRequest events. When you specify ExposureMask it will return GraphicsExpose or NoExpose events if those occur.

Related Commands

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

-x,,b-v,,ua, s / XMatchVisuallnfo

Name

XMatchVisuallnfo — obtain the visual information that matches the desired depth and class.

Synopsis

Status XMatchVisuallnfo( display, screen, depth, class, vinfo) Display *display; int screen; int depth; int class; XVisuallnfo *vinfo; /* RETURN */

Arguments

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

screen Specifies the screen.

depth Specifies the desired depth of the visual.

class Specifies the desired class of the visual, such as Pseudocolor or True-

Color.

vinfo Returns the matched visual information.

Description

XMatchVisuallnfo returns the visual information for a visual supported on the screen that matches the specified depth and class. Because multiple visuals that match the specified depth and class may be supported, the exact visual chosen is undefined.

If a visual is found, this function returns a nonzero value and the information on the visual is returned to vinfo. If a visual is not found, it returns zero.

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

typedef struct {

Visual *visual;

VisuallD visualid;

int screen;

unsigned int depth;

int class;

unsigned long red_mask;

unsigned long green_mask;

unsigned long blue_mask;

int colormap_size;

int bits_per_rgb; } XVisuallnfo;

Related Commands

DefaultVisual,XGetVisuallnfo.

Xlib Reference Manual

XMOVeReSizeWindOW . .xpb-«nda. Manipulation-

Name

XMoveResizeWindow — change the size and position of a window.

Synopsis

XMoveResizeWindow( display, w, x, y, width, height) Display *display; Window w; int x, y; unsigned int width, height;

Arguments

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

w Specifies the ID of the window to be reconfigured.

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

y der, relative to the window's parent.

width Specify the new width and height in pixels. These arguments define the interior

height size of the window.

Description

XMoveResizeWindow moves or resizes a window or both. XMoveResizeWindow does not raise the window. Resizing a mapped window may lose its contents and generate an Expose event on that window depending on the bit_gravity attribute. Configuring a win dow may generate exposure events on windows that the window formerly obscured, depending on the new size and location parameters.

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

If the client has selected StructureNotifyMask on the window, then a Configure-Notify event is generated after the move and resize takes place, and the event will contain the final position and size of the window.

Errors

BadValue BadWindow

Related Commands

XCirculateSubwindows,XCirculateSubwindowsDown, XCirculate-SubwindowsUp, XConf igureWindow, XLowerWindow, XMoveWindow, XQuery-Tree, XRaiseWindow, XReparentWindow, XResizeWindow, XRestackWindows.

-Xlib -Window Manipulation ' XMOVeWindOW

Name

XMoveWindow — move a window.

Synopsis

XMoveWindow(display, w, x, y) Display *display; Window w; int x, y;

Arguments

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

w Specifies the ID of the window to be moved.

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

y der (or of the window itself, if it has no border), relative to the window's parent.

Description

XMoveWindow changes the position of the origin of the specified window relative to its par ent. XMoveWindow does not change the mapping state, size, or stacking order of the window, nor does it raise the window. Moving a mapped window will lose its contents if:

Its background_pixmap attribute is ParentRelative.

The window is obscured by nonchildren and no backing store exists.

If the contents are lost, exposure events will be generated for the window and any mapped subwindows. Moving a mapped window will generate exposure events on any formerly obscured windows.

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

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

Errors

BadWindow

Related Commands

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

XNewModifiermap \ m _ Keyboard _

Name

XNewModifiermap — create a keyboard modifier mapping structure.

Synopsis

XModifierKeymap *XNewModifiermap (max_keys_per_mod) int max_keys_per_mod;

Arguments

max_keys_jper_mod

Specifies the maximum number of keycodes assigned to any of the modifiers in the map.

Description

XNewModifiermap returns a XModif ierKeymap structure and allocates the needed space. This function is used when more than one XModif ierKeymap structure is needed. max_keys_per_mod depends on the server and should be gotten from the XModif ier Keymap returned by XGetModif ierMapping.

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

Structures

typedef struct {

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

} XModifierKeymap;

Related Commands

XChangeKeyboardMapping, XDeleteModifiermapEntry, XFreeModif iermap, XGetKeyboardMapping,XGetModifierMapping, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XLookupKeysym, XLookupString, XQueryKeymap, XRebindKeysym, XRef reshKeyboardMapping, XSetModifierMapping, XStringToKeysym.

-Xllb - input HandHng / XNeXtEvent

Name

XNextEvent — get the next event of any type or window.

Synopsis

XNextEvent (display, report) Display * display; XEvent * report; /* RETURN */

Arguments

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

report Returns the event removed from the event queue.

Description

XNextEvent removes an event from the head of the event queue and copies it into an XEvent structure supplied by the caller. If the event queue is empty, XNextEvent flushes the request buffer and waits (blocks) until an event is received. Use XGheckMaskEvent or XChecklf Event if you do not want to wait.

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

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

^ Xlib - HouseKeeping —

Name

XNoOp — send a NoOp to exercise connection with the server.

Synopsis

XNoOp (display)

Display *display;

Arguments

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

Description

XNoOp sends a NoOperation request to the X server, thereby exercising the connection. This request can be used to measure the response time of the network connection. XNoOp does not flush the request buffer.

Related Commands

DefaultScreen,XCloseDisplay, XFree, XOpenDisplay.

—Xlib -Regions-

J XOffsetReglon

Name

XOffsetRegion — change offset of a region.

Synopsis

XOffsetRegion (r, dx, dy) Region r; int dx f dy;

Arguments

r Specifies the region.

dx Specify the amount to move the specified region relative to the origin of all

dy regions.

Description

XOffsetRegion changes the offset of the region the specified amounts in the x and y direc tions.

Regions are located using an offset from a point (the region origin) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable. If the region is to be used as a clipjmask by calling XSetRegion, the upper-left corner of the region relative to the drawable used in the graphics request will be at (xof fset + clip_x_origin, yof f set + clip_y_origin), where xof fset and yof f set are the offset of the region and clip_x_origin and clip_y_origin are components of the GC used in the graphics request.

Structures

Region is a pointer to an opaque structure type.

Related Commands

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

XOpenDisplay

X

Xlib-HouseKeeping —

Name

XOpenDisplay — connect a client program to an X server.

Synopsis

Display *XOpenDisplay( display_name) char *display_name;

Arguments

display_name

Specifies the display name, which determines the server to connect to and the communications domain to be used. See Description below.

Description

The XOpenDisplay routine connects the client to the server controlling the hardware display through TCP, or UNIX or DECnet streams.

If display_name is NULL, the value defaults to the contents of the DISPLAY environment variable on UNIX-based systems. On non-UNIX-based systems, see that operating system's Xlib manual for the default display_name. The display_name or DISPLAY environment variable is a string that has the format hostname: server or host name: server.screen. For example, frog: 0 .2 would specify screen 2 of server 0 on the machine frog.

hostname Specifies the name of the host machine on which the display is physically con nected. You follow the hostname with either a single colon (:) or a double colon (::), which determines the communications domain to use. Any or all of the communication protocols can be used simultaneously on a server built to sup port them (but only one per client).

If hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects the hardware display to TCP streams. In Release 4 and later, the string "unix" is no longer required and the string ":o" connects the local server.

If hostname is "unix" and a single colon (:) separates it from the display number, XOpenDisplay connects the hardware display to UNIX domain IPC streams. In Release 4, the string "unix" should be omitted.

• If hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay connects with the server using DECnet streams. To use DECnet, however, you must build all software for DECnet. A single X server can accept both TCP and DECnet connections if it has been built for DECnet.

server Specifies the number of the server on its host machine. This display number may be followed by a period (.). A single CPU can have more than one display; the displays are numbered starting from 0.

Xlib Reference Manual

Xlib - HouseKeepIng (continued) XOpenDiSplay

screen Specifies the number of the default screen on server. Multiple screens can be connected to (controlled by) a single X server, but they are used as a single dis play by a single user, screen merely sets an internal variable that is returned by the Def aultScreen macro. If screen is omitted, it defaults to 0.

If successful, XOpenDisplay returns a pointer to a Display. This structure provides many of the specifications of the server and its screens. If XOpenDisplay does not succeed, it returns a NULL.

After a successful call to XOpenDisplay, all of the screens on the server may be used by the application. The screen number specified in the display_name argument serves only to specify the value that will be returned by the Def aultScreen macro. After opening the dis play, you can use the ScreenCount macro to determine how many screens are available. Then you can reference each screen with integer values between 0 and the value returned by (ScreenCount -1).

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

Related Commands

Def aultScreen, XCloseDisplay, XFree, XNoOp.

Name

XParseColor — look up RGB values from ASCII color name or translate hexadecimal value.

Synopsis

Status XParseColor( display, colormap, spec, rgb_db_def) Display ^display; Colormap colormap; char *spec; XColor *rgb_db_def; /* RETURN */

Arguments

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

colormap Specifies a colormap. This argument is required but is not used. The same code is used to process XParseColor and XLookupColor, but only XLookupColor returns the closest values physically possible on the screen specified by colormap.

spec Specifies the color specification, either as a color name or as hexadecimal

coded in ASCII (see below). Upper or lower case does not matter. The string must be null-terminated, and should be in ISO LATIN-1 encoding, which means that the first 128 character codes are ASCII, and the second 128 char acter codes are for special characters needed in western languages other than English.

rgb_db_def Returns the RGB values corresponding to the specified color name or hexade cimal specification, and sets its DoRed, DoGreen and DoBlue flags.

Description

XParseColor returns the RGB values corresponding to the English color name or hexade cimal values specified, by looking up the color name in the color database, or translating the hexadecimal code into separate RGB values. It takes a string specification of a color, typically from a command line or XGetDefault option, and returns the corresponding red, green, and blue values, suitable for a subsequent call to XAllocColor or XStoreColor. spec can be given either as an English color name (as in XAllocNamedColor) or as an initial sharp sign character followed by a hexadecimal specification in one of the following formats:

#RGB (one character per color)

#RRGGBB (two characters per color)

#RRRGGGBBB (three characters per color)

#RRRRGGGGBBBB (four characters per color)

where R, G, and B represent single hexadecimal digits (upper or lower case).

The hexadecimal strings must be null-terminated so that XParseColor knows when it has reached the end. When fewer than 16 bits each are specified, they represent the most signifi cant bits of the value. For example, # 3 a 7 is the same as#3000a0007000.

Xlib Reference Manual

Xlib - Color Cells (continued) XParseColor

This routine will fail and return aStatusof zero if the initial character is a sharp sign but the string otherwise fails to fit one of the above formats, or if the initial character is not a sharp sign and the named color does not exist in the server's database.

Status is zero on failure, nonzero on success.

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

Related Commands

BlackPixel,WhitePixel,XAllocColor, XAllocColorCells, XAllocColor-Planes, XAllocNamedColor,XFreeColors, XLookupColor, XQueryColor, XQueryColors,XStoreColor,XStoreColors, XStoreNamedColor.

XParseGeometry . Vll

v Xlib - Standard Geometry—

Name

XParseGeometry — generate position and size from standard window geometry string.

Synopsis

int XParseGeometry (parsestring, x, y, width, height) char *parsestring;

int *x, *y; /* RETURN */

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

Arguments

parsestring Specifies the string you want to parse.

x Return the x and y coordinates (offsets) from the string.

y

wi dth Return the width and height in pixels from the string.

height

Description

By convention, X applications provide a geometry command line option to indicate window size and placement. XParseGeometry makes it easy to conform to this standard because it allows you to parse the standard window geometry string. Specifically, this function lets you parse strings of the form:

= < width>x<height> { +-} <xoffset> {'+-} <yoffset>

The items in this string map into the arguments associated with this function. (Items enclosed in o'are integers and items enclosed in {} are a set from which one item is allowed. Note that the brackets should not appear in the actual string.)

XParseGeometry returns a bitmask that indicates which of the four values (width, height, xoffset, and yoffset) were actually found in the string, and whether the x and y values are negative. The bits are represented by these constants: XValue, YValue, width-Value, Height Value, XNegative, and YNegative, and are defined in <Xll/Xutil.h>. For each value found, the corresponding argument is updated and the corresponding bitmask element set; for each value not found, the argument is left unchanged, and the bitmask element is not set.

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

XGeometry,XTranslateCoordinates,XWMGeometry.

-X.ib - input Handling '

Name

XPeekEvent — get an event without removing it from the queue.

Synopsis

XPeekEvent( display, report) Display * display; XEvent * report; /* RETURN */

Arguments

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

report Returns the event peeked from the input queue.

Description

XPeekEvent peeks at an input event from the head of the event queue and copies it into an XEvent supplied by the caller, without removing it from the input queue. If the queue is empty, XPeekEvent flushes the request buffer and waits (blocks) until an event is received. If you do not want to wait, use the QLength macro to determine if there are any events to peek at, or use XPeeklf Event. XEventsQueued can perform the function of either QLength or XPending and more.

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

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

XPeeklfEvent \ X|lb _ |nput Hand|lng _

Name

XPeeklfEvent — get an event matched by predicate procedure without removing it from the queue.

Synopsis

XPeeklfEvent( display, event, predicate, args) Display *display;

XEvent *event; /* RETURN */

Bool (^predicate) (); char *args;

Arguments

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

event Returns the matched event.

predicate Specifies the procedure to be called to determine if each event that arrives in the queue is the desired one.

args Specifies the user-specified arguments that will be passed to the predicate

procedure.

Description

XPeeklfEvent returns an event only when the specified predicate procedure returns True for the event. The event is copied into event but not removed from the queue. The specified predicate is called each time an event is added to the queue, with the arguments display, event, and arg.

XPeeklfEvent flushes the request buffer if no matching events could be found on the queue, and then waits for the next matching event.

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

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

— Xlib-Input Handling-

J XPending

Name

XPending — flush the request buffer and return the number of pending input events.

Synopsis

int XPending (display) Display *display;

Arguments

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

Description

XPending returns the number of input events that have been received by Xlib from the server, but not yet removed from the queue. If there are no events on the queue, XPending flushes the request buffer, and returns the number of events transferred to the input queue as a result of the flush.

The QLength macro returns the number of events on the queue, but without flushing the request buffer first.

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

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

Xpermalloc \ Vll

v Xlib - Resource Manager—

Name

Xpermalloc — allocate memory never to be freed.

Synopsis

char *Xpermalloc(size) unsigned int size;

Arguments

si ze Specifies the size in bytes of the space to be allocated. This specification is

rounded to the nearest 4-byte boundary.

Description

Xpermalloc allocates some memory that will not be freed until the process exits. Xperm alloc is used by some toolkits for permanently allocated storage and allows some perfor mance and space savings over the completely general memory allocator.

— Xlib -Regions-

J XPointlnRegion

Name

XPointlnRegion — determine if a point is inside a region.

Synopsis

Bool XPointlnRegion(r, x, y) Region r; int x, y;

Arguments

r Specifies the region.

x Specify the x and y coordinates of the point relative to the region's origin.

y

Description

XPointlnRegion returns True if the point x, y is contained in the region r. A point exactly on the boundary of the region is considered inside the region.

Regions are located using an offset from a point (the region origin) which is common to all regions. It is up to the application to interpret the location of the region relative to a drawable.

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

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion,XDestroyRegion,XEmptyRegion,XEqualRegion, XIntersectRegion,XOffsetRegion,XPolygonRegion,XRectlnRegion,XSet-Region, XShrinkRegion,XSubtractRegion, XUnionRectWithRegion,XUnion-Region,XXorRegion.

XPolygonRegion \.

xi|b

Name

XPolygonRegion — generate a region from points.

Synopsis

Region XPolygonRegion (points , n, fill_rule) XPoint points [] ; int n; int fill_rule;

Arguments

points Specifies a pointer to an array of points.

n Specifies the number of points in the polygon.

fill_rule Specifies whether areas overlapping an odd number of times should be part of the region (windingRule) or not part of the region (EvenOddRule). See Volume One, Chapter 5, The Graphics Context, for a description of the fill rule.

Description

XPolygonRegion creates a region defined by connecting the specified points, and returns a pointer to be used to refer to the region.

Regions are located relative to a point (the region origin) which is common to all regions. In XPolygonRegion, the coordinates specified in points are relative to the region origin. By specifying all points relative to the drawable in which they will be used, the region origin can be coincident with the drawable origin. It is up to the application whether to interpret the loca tion of the region relative to a drawable or not.

If the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner of the region relative to the drawable used in the graphics request will be at (xof f set + clip_x_origin, yof f set + clip_y_origin) , where xof f set and yof f set are the offset of the region (if any) and clip_x_origin and clip_y_origin are elements of the GC used in the graphics request. The fill_rule can be either of these values:

• EvenOddRule Areas overlapping an odd number of times are not part of the region.

• windingRule Overlapping areas are always filled.

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

Structures

Region is a pointer to an opaque structure type.

Related Commands

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion, XOf f setRegion, XPointlnRegion, XRectlnRegion, XSet Region, XShrinkRegion, XSubtractRegion, XUnionRectWithRegion, XUnion-Region, XXorRegion.

-XMb - ,npu, Hand,ing

Name

XPutBackEvent — push an event back on the input queue.

Synopsis

XPutBackEvent (display , event) Display ^display; XEvent * event;

Arguments

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

even t Specifies a pointer to the event to be requeued.

Description

XPutBackEvent pushes an event back onto the head of the current display's input queue (so that it would become the one returned by the next XNextEvent call). This can be useful if you have read an event and then decide that you'd rather deal with it later. There is no limit to how many times you can call XPutBackEvent in succession.

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

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped-Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeeklf Event, XPending, XSelectlnput, XSendEvent, XSet-InputFocus, XSynchronize, XWindowEvent.

Name

XPutlmage — draw an image on a window or pixmap.

Synopsis

XPutlmage( display, drawable, gc, image, src_x, src_y,

dst_x, dst_y, width, height) Display ^display; Drawable drawable; GC gc;

Xlmage * image; int src_x, src_y; int dst_x, dst_y; unsigned int width, height;

Arguments

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

drawable Specifies the drawable.

gc Specifies the graphics context.

image Specifies the image you want combined with the rectangle.

src_x Specify the coordinates of the upper-left corner of the rectangle to be copied,

src_y relative to the origin of the image.

dst_x Specify the x and y coordinates, relative to the origin of the drawable, where

dst_y the upper-left corner of the copied rectangle will be placed.

wi dth Specify the width and height in pixels of the rectangular area to be copied.

height

Description

XPutlmage draws a section of an image on a rectangle in a window or pixmap. The section of the image is defined by src_x, src_y, width and height.

There is no limit to the size of image that can be sent to the server using XPutlmage. XPut lmage automatically decomposes the request to make sure that the maximum request size of the server is not exceeded.

XPutlmage uses these graphics context components: function, plane_mask, subwin-dow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground and background.

If an XYBitmap format image is used, then the depth of drawable must be 1, otherwise a BadMatch error is generated. The foreground pixel in gc defines the source for bits set to one in the image, and the background pixel defines the source for the bits set to zero.

For XYPixmap and ZPixmap format images, the depth of the image must match the depth of

drawable.

338 Xlib Reference Manual

Xlib - Images (continued) XPutlmage

Structures

typedef struct _XImage {

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; /* quant, 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) */

char *obdata; /* hook for the 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; } XImage;

Errors

BadDrawable

BadGC

BadMatch See Description above.

BadValue

Related Commands

ImageByteOrder, XAddPixel, XCreatelmage, XDestroyImage, XGet Image, XGetPixel,XGetSublmage,XPutPixel,XSublmage.

XPutPixel "\ v,

v Xlib - Images-Name

XPutPixel — set a pixel value in an image.

Synopsis

int XPutPixel (ximage f x f y, pixel) Xlmage * ximage; int x; int y; unsigned long pixel;

Arguments

ximage Specifies a pointer to the image to be modified.

x Specify the x and y coordinates of the pixel to be set, relative to the origin of

y the image.

pixel Specifies the new pixel value.

Description

XPutPixel overwrites the pixel in the named image with the specified pixel value. The x and y coordinates are relative to the origin of the image. The input pixel value must be in same bit- and byte-order as the machine in which the client is running (that is, the Least Significant Byte (LSB) of the long is the LSB of the pixel). The x and y coordinates must be contained in the image.

Structures

typedef struct Ximage {

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; /* quant, 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 the 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; } Ximage;

Xlib-Images (continued) XPutPixel

Related Commands

ImageByteOrder, XAddPixel, XCreateImage, XDestroyImage, XGetlmage, XGetPixel, XGetSublmage,XPutlmage,XSublmage.

XQueryBestCursor v^

-Xlib-Cursors-

Name

XQueryBestCursor — get the closest supported cursor sizes.

Synopsis

Status XQueryBestCursor (display, draw-able, width, height,

rwidth, rheight) Display * display; Drawable drawable; unsigned int width, height; unsigned int * rwidth, *rheight / /* RETURN */

Arguments

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

draw-able Specifies a drawable that indicates which screen the cursor is to be used on. The best cursor may be different on different screens.

width Specify the preferred width and height, in pixels.

height

rwidth Returns the closest supported cursor dimensions, in pixels, on the display

rh ei gh t hardware.

Description

XQueryBestCursor returns the closest cursor dimensions actually supported by the display hardware to the dimensions you specify.

Call this function if you wish to use a cursor size other than 16 by 16. XQueryBestCursor provides a way to find out what size cursors are actually possible on the display. Applications should be prepared to use smaller cursors on displays which cannot support large ones.

XQueryBestCursor returns nonzero if the call succeeded in getting a supported size (which may be the same or different from the specified size), or zero if the call failed.

Errors

BadDrawable

Related Commands

XCreateFontCursor, XCreateGlyphCursor,XCreatePixmapCursor,XDefine-Cursor,XFreeCursor,XQueryBestSize,XRecolorCursor,XUndefineCursor.

— Xlib - Pixmaps and Tiles-

J XQueryBestSize

Name

XQueryBestSize — obtain the "best" supported cursor, tile, or stipple size.

Synopsis

Status XQueryBestSize(display, class, drawable, width,

height, rwidth, rheight) Display * display; int class; Drawable drawable; unsigned int width, height; unsigned int *rwidth, *rheight; /* RETURN */

Arguments

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

class Specifies the class that you are interested in. Pass one of these constants:

TileShape,CursorShape, or StippleShape.

drawable Specifies a drawable ID that tells the server which screen you want the best size for.

width Specify the preferred width and height in pixels.

height

rwidth Return the closest supported width and height, in pixels, available for the

rheight object on the display hardware.

Description

XQueryBestSize returns the "fastest" or "closest" size to the specified size. For class of CursorShape, this is the closest size that can be fully displayed on the screen. For Tile-Shape and StippleShape, this is the closest size that can be tiled or stippled "fastest."

For CursorShape, the drawable indicates the desired screen. For TileShape and StippleShape, the drawable indicates the screen and possibly the visual class and depth (server-dependent). An inputOnly window cannot be used as the drawable for TileShape or StippleShape (else a BadMatch error occurs).

XQueryBestSize returns nonzero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed.

Errors

BadDrawable

BadMatch InputOnly drawable for class TileShape or StippleShape. BadValue

XQueryBeStSize (continued) Xlib - Pixmaps and Tiles

Related Commands

XCreateBitmapFromData,XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestStipple,XQueryBestTile, XReadBitmapFile, XSetTile,XSetWindowBackgroundPixmap,XSetWindowBorderPixmap, XWriteBitmapFile.

—Xlib - Pixmaps and Tiles-

J XQueryBestStipple

Name

XQueryBestStipple — obtain the fastest supported stipple shape.

Synopsis

Status XQueryBestStipple(display, drawable, width, height,

rwidth, rheight) Display * display; Drawable drawable; unsigned int width, height; unsigned int *rwidth, * rheight; /* RETURN */

Arguments

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

drawable Specifies a drawable that tells the server which screen you want the best size for.

width Specify the preferred width and height in pixels.

height

rwidth Return the width and height, in pixels, of the stipple best supported by the

rhei gh t display hardware.

Description

XQueryBestStipple returns the closest stipple size that can be stippled fastest. The draw-able indicates the screen and possibly the visual class and depth. An inputOnly window cannot be used as the drawable (else a BadMatch error occurs).

XQueryBestStipple returns nonzero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed.

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

Errors

BadDrawable

BadMatch InputOnly window.

Related Commands

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

XQueryBestTile \ X||b _ pixmaps and T||es _

Name

XQueryBestTile — obtain the fastest supported fill tile shape.

Synopsis

Status XQueryBestTile ( display, drawable, width, height,

rwidth, rheight) Display * display; Drawable drawable ; unsigned int width, height; unsigned int *rwidth, *rheight ; /* RETURN */

Arguments

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

drawable Specifies a drawable that tells the server which screen you want the best size for.

wi dth Specify the preferred width and height in pixels.

height

rwidth Return the width and height, in pixels, of the tile best supported by the dis-

rheight play hardware.

Description

XQueryBestTile returns the closest size that can be tiled fastest. The drawable indicates the screen and possibly the visual class and depth. An Input Only window cannot be used as the drawable.

XQueryBestTile returns nonzero if the call succeeded in getting a supported size (may be the same or different from the specified size), or zero if the call failed.

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

BadDrawable

BadMatch InputOnly drawable specified.

Related Commands

XCreateBitmapFromData,XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap,XQueryBestSize,XQueryBestStipple, XReadBitmapFile, XSetTile,XSetWindowBackgroundPixmap,XSetWindowBorderPixmap, XWriteBitmapFile.

— Xlib-Color Cells-

J XQueryColor

Name

XQueryColor — obtain the RGB values and flags for a specified colorcell.

Synopsis

XQueryColor( display f cmap, colorcell_def) Display ^display; Colormap cmap; XColor *colorcell_def; /* SEND and RETURN */

Arguments

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

cmap Specifies the ID of the colormap from which RGB values will be retrieved.

colorcell_def

Specifies the pixel value and returns the RGB contents of that colorcell.

Description

XQueryColor returns the RGB values in colormap cmap for the colorcell corresponding to the pixel value specified in the pixel member of the XColor structure colorcell_def. The RGB values are returned in the red, green, and blue members of that structure, and the flags member of that structure is set to (DoRed I DoGreen | DoBlue). The values returned for an unallocated entry are undefined.

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

BadValue Pixel not valid index into cmap.

Related Commands

BlackPixel, WhitePixel,XAllocColor, XAllocColorCells,XAllocColor-Planes, XAllocNamedColor,XFreeColors,XLookupColor, XParseColor, XQueryColors,XStoreColor,XStoreColors, XStoreNamedColor.

XQueryColors

Xlib-Color Cells-

Name

XQueryColors — obtain RGB values for an array of colorcells.

Synopsis

XQueryColors(display, cmap, colorcell_defs, ncolors) Display *display; Colormap cmap;

XColor colorcell_defs [ncolors] ; /* SEND and RETURN */ int ncolors;

Arguments

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

cmap Specifies the ID of the colormap from which RGB values will be retrieved.

colorcell_defs

Specifies an array of XColor structures. In each one, pixel is set to indi cate which colorcell in the colormap to return, and the RGB values in that colorcell are returned in red, green, and blue.

ncol ors Specifies the number of XColor structures in the color definition array.

Description

XQueryColors is similar to XQueryColor, but it returns an array of RGB values. It returns the RGB values in colormap cmap for the colorcell corresponding to the pixel value specified in the pixel member of the XColor structure colorcell_def. The RGB values are returned in the red, green, and blue members of that same structure, and sets the flags member in each XColor structure to (DoRed I DoGreen | DoBlue).

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 Specified colormap does not exist.

BadValue Pixel not valid index into cmap.

Note: if more than one pixel value is in error, the one reported is arbitrary.

Related Commands

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

—Xlib - Extensions-

J XQueryExtension

Name

XQueryExtension — get extension information.

Synopsis

Bool XQueryExtension( display, name, major_opcode f

first_event r first_error) Display ^display; char *name;

int *major_opcode; /* RETURN */

int *first_event ; /* RETURN */

int *first_error; /* RETURN */

Arguments

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

name Specifies the name of the desired extension. Upper or lower case is impor

tant. 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.

major_opcode

Returns the major opcode of the extension, for use in error handling routines.

first_event Returns the code of the first custom event type created by the extension. f irst_error Returns the code of the first custom error defined by the extension.

Description

XQueryExtension determines if the named extension is present, and returns True if it is. If so, the routines in the extension can be used just as if they were core Xlib requests, except that they may return new types of events or new error codes. The available extensions can be listed with XListExtensions.

The major_opcode for the extension is returned, if it has one. Otherwise, zero is returned. This opcode will appear in errors generated in the extension.

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

Start Free Trial

No credit card required