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.
Get Xlib Reference Manual for Version 11 Volume 2, 5th Editon now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
