Xlib Function Reference
Introduction
—Xlib - Function Group
This page describes the format of each reference page in this volume.
Name
FunctionName — brief description of the function.
Synopsis
The Synopsis section presents the calling syntax for the routine, including the declarations of the arguments and return type. For example:
returntype XFunctionName (arg1, arg2, arg3); type1 arg1; type2 *arg2; /* RETURN */ type3 *arg3; /* SEND and RETURN */
The return type Status is of type int; it returns either True or False to indicate whether the routine was successful.
Arguments
The Arguments section describes each of the arguments used by the function. There are three sorts of arguments: arguments that specify data to the function, arguments that return data from the function, and arguments that do both. An example of each type is shown below:
| arg1 | Specifies information for XFunctionName. The description of arguments that pass data to the function always begins with the word “Specifies,” as shown in this example. |
| arg2 | Returns a pointer to data to be filled in by XFunctionName. The description of arguments that return data from the function always begins with the word “Returns.” |
| arg3 | Specifies information for XFunctionName, and returns data from the function. The description of arguments that both pass data to the function and return data from the function uses both the words “Specifies” and “Returns.” |
Description
The Description section describes what the function does, what it returns, and what events or side-effects it causes. It also contains miscellaneous information such as examples of usage, special error cases, and pointers to related information in both volumes of this manual.
Structures
The Structures section contains the C definitions of the X-specific data types used by FunctionName as arguments or return values. It also contains definitions of important constants used by the function. Additional structures not shown can be found in Appendix F, Structure Reference.
Errors
The Errors section contains a list of the error event types that XFunctionName can generate. The general description of the error types is contained in Appendix B, Error Messages and Protocol Requests. Some functions generate errors due to function-specific interpretation of arguments. Where appropriate, these function-specific causes have been listed along with the error event types they generate.
Related Commands
The Related Commands section lists the Xlib functions and macros related to XFunctionName.
XActivateScreenSaver
—Xlib - Screen Saver
Name
XActivateScreenSaver — activate screen blanking.
Synopsis
XActivateScreenSaver (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XActivateScreenSaver turns on the screen saver using the parameters set with XSetScreenSaver. The screen saver blanks the screen or makes random changes to the display in order to save the phosphors from burnout if it is left unattended for an extended period of time. The interval to wait before starting screen save activity can be set with XSetScreenSaver. Exactly how the screen saver works is server-dependent.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XForceScreenSaver, XResetScreenSaver, XGetScreenSaver, XSetScreenSaver.
XAddHost
Xlib - Host Access—
Name
XAddHost — add a host to the access control list.
Synopsis
XAddHost (display, host) Display *display; XHostAddress *host;
Arguments
| display | Specifies a pointer to the Display structure returned from XOpenDisplay. |
| host | Specifies the network address of the host machine to be added. |
Description
XAddHost adds the specified host to the access control list for the server specified by display. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX systems, this file is called /etc/X?.hosts, where ? is the number of the display.
The application that calls XAddHost and the server whose list is being updated must be running on the same host machine.
The address data must be a valid address for the type of network in which the server operates, as specified in the family member. Internet, DECnet and ChaosNet networks are currently supported.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte.
For more information on access control, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
int family; /* for example FamilyInternet */
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the bytes */
} XHostAddress;
/* The following constants for family member */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
Related Commands
XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccessControl, XEnableAccessControl, XSetAccessControl.
XAddHosts
Xlib - Host Access—
Name
XAddHosts — add multiple hosts to the access control list.
Synopsis
XAddHosts (display, hosts, num_hosts) Display *display; XHostAddress *hosts; int num_hosts;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| hosts | Specifies each host that is to be added. |
| num_hosts | Specifies the number of hosts that are to be added. |
Description
XAddHosts adds each specified host to the access control list for the server specified by display. The access control list is a primitive security feature that allows access to the server only by other machines listed in a file on the machine running the server. On UNIX systems, this file is /etc/X?.hosts, where ? is the number of the display.
The application that calls XAddHost and the server whose list is being updated must be running on the same host machine.
The address data must be a valid address for the type of network in which the server operates, as specified by the family member. Internet, DECnet and ChaosNet networks are currently supported.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte.
For more information on access control, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
int family; /* for example Family Internet */
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the bytes */
} XHostAddress;
/* The following constants for family member */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
Related Commands
XAddHost, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccessControl, XEnableAccessControl, XSetAccessControl.
XAddPixel
Xlib - Images—
Name
XAddPixel — add a constant value to every pixel value in an image.
Synopsis
int XAddPixel(ximage, value) XImage *ximage; unsigned long value;
Arguments
| ximage | Specifies a pointer to the image to be modified. |
| value | Specifies the constant value that is to be added. Valid pixel value ranges depend on the visual used to create the image. If this value added to the existing value causes an overflow, extra bits in the result are truncated. |
Description
XAddPixel adds a constant value to every pixel value in an image. This function is useful when you have a base pixel value derived from the allocation of color resources and need to manipulate an image so that the pixel values are in the same range.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct _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; /* quantity of scan line 8, 16, 32 */
int bitmap_bit_order; /* LSBFirst, MSBFirst */
int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */
int depth; /* depth of image */
int bytes_per_line; /* accelerator to next line */
int bits_per_pixel; /* bits per pixel (ZPixmap) */
unsigned long red_mask; /* bits in z arrangment */
unsigned long green_mask;
unsigned long blue_mask;
char *obdata; /* hook for object routines to hang on */
struct funcs { /* image manipulation routines */
struct _XImage *(*create_image)();
int (*destroy_image)();
unsigned long (*get_pixel)();
int (*put_pixel)();
struct _XImage *(*sub_image)();
int (*add_pixel)();
} f;
} XImage;
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSubImage, XPutPixel, XGetPixel, ImageByteOrder.
XAddToSaveSet
Xlib - Save Set—
Name
XAddToSaveSet — add a window's children to the client's save-set.
Synopsis
XAddToSaveSet (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose children you want to add to the client's save-set. |
Description
XAddToSaveSet adds the children of the specified window to the client's save-set.
The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a shadow or other background for each window. When the window manager dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so that they remain alive. See Volume One, Chapter 13, Other Programming Techniques, for more information about save-sets.
Use XRemoveFromSaveSet to remove a window's children from the client's save-set.
Errors
| BadMatch | w not created by some other client. |
| BadWindow |
Related Commands
XRemoveFromSaveSet, XChangeSaveSet.
XAllocColor
— Xlib - Color Cells
Name
XAllocColor — allocate a read-only colormap cell with closest hardware-supported color.
Synopsis
Status XAllocColor (display, cmap, colorcell_def) Display *display; Colormap cmap; XColor *colorcell_def; /* SENDs and RETURNs */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the ID of the colormap in which the colorcell is to be allocated. |
| colorcell_def | Specifies desired RGB values, and also returns the pixel value and the RGB values actually used in the colormap. |
Description
XAllocColor returns in the XColor structure the pixel value of a read-only (shareable) colorcell with the closest RGB values available in cmap. XAllocColor also returns the red, green, and blue values actually used.
If the display hardware has an immutable hardware colormap, the entire colormap will be read-only, and the closest cell that exists will be returned. Otherwise, the colormap is read/write, and may have some read/write cells, some read-only cells, and some unallocated. If a read-only cell exists that matches the requested RGB values, that cell is returned. If no matching cell exists but there are unallocated cells, a cell is allocated to match the specified RGB values. If no matching cell exists and there are no unallocated cells, the closest available colorcell that has already been allocated (by this or any other client) is returned. Note that colorcell_def stores both the requested color when XAllocColor is called and the result when XAllocColor returns.
XAllocColor does not use or affect the flags member of the XColor structure.
XAllocColor returns 0 if there was some problem (typically all cells are allocated and read/write), or 1 if it succeeds.
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
BadColor
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XAllocColorCells
— Xlib - Color Cells
Name
XAllocColorCells — allocate read/write (nonshared) colorcells.
Synopsis
Status XAllocColorCells (display, cmap, contig, plane_masks, nplanes, pixels, ncolors) Display *display; Colormap cmap; Bool contig; unsigned long plane_masks[nplanes] ; /* RETURN */ unsigned int nplanes; unsigned long pixels[ncolors]; /* RETURN pixel values */ unsigned int ncolors;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the ID of the colormap in which the colorcell is to be allocated. |
| contig | Specifies a boolean value. Pass True if the planes must be contiguous or False if the planes need not be contiguous. |
| plane_mask | Returns an array of plane masks. |
| nplanes | Specifies the number of plane masks returned in the plane masks array. Must be nonnegative. |
| pixels | Returns an array of pixel values. |
| ncolors | Specifies the number of pixel values returned in the pixels array. Must be positive. |
Description
XAllocColorCells allocates read/write colorcells in a read/write colormap. If ncolors and nplanes are requested, then ncolors pixels and nplanes plane masks are returned. No mask will have any bits in common with any other mask, or with any of the pixels. By ORing together each of the pixels with any combination of the plane_masks, ncolors * distinct pixels can be produced. For GrayScale or Pseudocolor, each mask will have exactly one bit, and for DirectColor each will have exactly three bits. If contig is True, then if all plane masks are ORed together, a single contiguous set of bits will be formed for GrayScale or Pseudocolor and three contiguous sets of bits (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined until set with XStoreColor, XStoreColors, or XStoreNamedColor.
Status is 0 on failure.
For more information, see Volume One, Chapter 7, Color.
Errors
| BadColor | |
| BadValue | nplanes is negative. |
| ncolors is not positive. |
Related Commands
XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XAllocColorPlanes
— Xlib - Color Cells
Name
XAllocColorPlanes — allocate read/write (nonshareable) color planes.
Synopsis
Status XAllocColorPlanes (display, cmap, contig, pixels, ncolors, nreds, ngreens, nblues, rmask, gmask, bmask) Display *display; Colormap cmap; Bool contig; unsigned long pixels[ncolors] ; /* RETURN */ int ncolors; int nreds, ngreens, nblues; unsigned long *rmask, *gmask, *bmask; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the ID of the colormap to be used. |
| contig | Specifies a boolean value. Pass True if the planes must be contiguous or False if the planes do not need to be contiguous. |
| pixels | Returns an array of pixel values. |
| ncolors | Specifies the number of pixel values returned in the pixels array. Must be positive. |
| nreds
ngreens nblues |
Specify the number of red, green, and blue planes (shades). Must be nonnegative. |
| rmask
gmask bmask |
Return bit masks for the red, green, and blue planes. |
Description
If ncolors, nreds, ngreens, and nblues are requested, then ncolors pixels are returned, and the masks have nreds, ngreens, and nblues bits set to 1 respectively. Unique pixel values are generated by by ORing together subsets of masks with each item in the pixels list (pixels does not by itself contain pixel values). In doing this, ncolors* (2(nreds+ngreens+nblues)) distinct pixel values are allocated.
If contig is True, then each mask will have a contiguous set of bits. No mask will have any bits in common with any other mask, or with any of the pixels. For DirectColor, each mask will lie within the corresponding pixel subfield.
Note, however, that there are only ncolors*(2nreds) independent red entries, ncolors*(2ngreens) independent green entries, and ncolors*(2nblues) independent blue entries in the colormap. This is true even for Pseudocolor. This does not cause problems, though, because when the colormap entry for a pixel value is changed using XStoreColors or XStoreNamedColor, the pixel is decomposed according to rmask, gmask, and bmask and the corresponding pixel subfield entries are updated.
Status is 0 on failure.
For more information, see Volume One, Chapter 7, Color.
Errors
| BadColor | |
| BadValue | ncolors is not positive.
At least one of nreds, ngreens, nblues is negative. |
Related Commands
XAllocColorCells, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XAllocNamedColor
—Xlib - Color Cells
Name
XAllocNamedColor — allocate a read-only colorcell from color name.
Synopsis
Status XAllocNamedColor (display, cmap, colorname, colorcell_def, rgb_db_def) Display *display;, Colormap cmap; char *colorname; XColor *colorcell_def; /* RETURN */ XColor *rgb_db_def; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the ID of the colormap in which the colorcell will be allocated. |
| colorname | Specifies the color name string (for example, “red”) you want. Upper or lower case does not matter. The string should be in ISO LATIN-1 encoding, which means that the first 128 character codes are ASCII, and the second 128 character codes are for special characters needed in western languages other than English. |
| colorcell_def | Returns the pixel value and RGB values actually used in the colormap. This is the closest color supported by the hardware. |
| rgb_db_def | Returns the exact RGB values from the database corresponding to the colorname supplied. |
Description
XAllocNamedColor determines the RGB values for the specified colorname from the color database, and then allocates a read-only colorcell with the closest color available, as described under XAllocColor. Both the ‘exact’ database definition of the color, and the color actually allocated are returned. If the colormap is not full, the RGB values allocated are the closest supported by the hardware. If the colormap is full, XAllocNamedColor returns the closest read-only colorcell already allocated, and does not actually create or set any new colorcell.
XAllocNamedColor returns a Status of 0 when it encounters an error or 1 when it succeeds.
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
BadColor
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XAllowEvents
—Xlib - Input Handling
Name
XAllowEvents — control the behavior of keyboard and pointer events when these resources are grabbed.
Synopsis
XAllowEvents (display, event_mode, time) Display *display; int event_mode; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event_mode | Specifies the event mode. Pass one of these constants: AsyncPointer, SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, ReplayKeyboard, AsyncBoth, or SyncBoth. |
| time | Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. |
Description
XAllowEvents releases the events queued in the server since the last XAllowEvents call for the same device and by the same client. Events are queued in the server (not released to Xlib to propagate into Xlib's queues) only when the client has caused a device to “freeze” (by grabbing the device with mode GrabModeSync). The request has no effect if time is earlier than the last-grab time or later than the current server time.
The event_mode argument controls what device events are released for and just how and when they are released. The event_mode is interpreted as follows:
| AsyncPointer | If XAllowEvents is called with AsyncPointer while the pointer is frozen by the client, pointer event processing resumes normally, even if the pointer is frozen twice by the client on behalf of two separate grabs. AsyncPointer has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client. |
| AsyncKeyboard | If XAllowEvents is called with AsyncKeyboard while the keyboard is frozen by the client, keyboard event processing resumes normally, even if the keyboard is frozen twice by the client on behalf of two separate grabs. AsyncKeyboard has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client |
| SyncPointer | If XAllowEvents is called with SyncPointer while the pointer is frozen by the client, normal pointer event processing continues until the next ButtonPress or ButtonRelease event is reported to the client. At this time, the pointer again appears to freeze. However, if the reported event causes the pointer grab to be released, then the pointer does not freeze, which is the case when an automatic grab is released by a ButtonRelease or when XGrabButton or XGrabKey has been called and the specified key or button is released. SyncPointer has no effect if the pointer is not frozen or not grabbed by the client. |
| SyncKeyboard | If XAllowEvents is called with SyncKeyboard while the keyboard is frozen by the client, normal keyboard event processing continues until the next KeyPress or KeyRelease event is reported to the client. At this time, the keyboard again appears to freeze. However, if the reported event causes the keyboard grab to be released, then the keyboard does not freeze, which is the case when an automatic grab is released by a ButtonRelease or when XGrabButton or XGrabKey has been called and the specified key or button is released. SyncKeyboard has no effect if the keyboard is not frozen or not grabbed by the client. |
| ReplayPointer | This symbol has an effect only if the pointer is grabbed by the client and thereby frozen as the result of an event. In other words, XGrabButton must have been called and the selected button/key combination pressed, or an automatic grab (initiated by a ButtonPress) must be in effect, or a previous XAllowEvents must have been called with mode SyncPointer. If the pointer_mode of the XGrabPointer was GrabModeSync, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root) on the grab-window of the grab just released. |
| ReplayKeyboard | This symbol has an effect only if the keyboard is grabbed by the client and if the keyboard is frozen as the result of an event. In other words, XGrabKey must have been called and the selected key combination pressed, or a previous XAllowEvents must have been called with mode SyncKeyboard. If the pointer_mode or keyboard_mode of the XGrabKey was GrabModeSync, then the grab is released and the releasing event is processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root). |
| SyncBoth | SyncBoth has the effect described for both SyncKeyboard and SyncPointer. SyncBoth has no effect unless both pointer and keyboard are frozen by the client. If the pointer or keyboard is frozen twice by the client on behalf of two separate grabs, SyncBoth “thaws” for both (but a subsequent freeze for SyncBoth will only freeze each device once). |
| AsyncBoth | AsyncBoth has the effect described for both AsyncKeyboard and AsyncPointer. AsyncBoth has no effect unless both pointer and keyboard are frozen by the client. If the pointer and the keyboard were frozen by the client, or if both are frozen twice by two separate grabs, event processing (for both devices) continues normally. If a device is frozen twice by the client on behalf of the two separate grabs, AsyncBoth releases events for both. |
AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of keyboard events. AsyncKeyboard, SyncKeyboard, and ReplayKeyboard have no effect on the processing of pointer events.
It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is performed for the device. It is also possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed.
For more information on event handling, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
| BadValue | Invalid mode constant. |
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XAutoRepeatOff
Xlib - User Preferences—
Name
XAutoRepeatOff — turn off the keyboard auto-repeat keys.
Synopsis
XAutoRepeatOff (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XAutoRepeatOff turns off auto-repeat for the keyboard. It sets the keyboard so that holding any non-modal key down will not result in multiple events. Keys such as Shift Lock will still not repeat.
Related Commands
XGetDefault, XAutoRepeatOn, XBell, XGetKeyboardControl, XChangeKeyboardControl, XGetPointerControl.
XAutoRepeatOn
—Xlib - User Preferences
Name
XAutoRepeatOn — turn on the keyboard auto-repeat keys.
Synopsis
XAutoRepeatOn (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XAutoRepeatOn sets the keyboard to auto-repeat; that is, holding any non-modal key down will result in multiple KeyPress and KeyRelease event pairs with the same keycode member. Keys such as Shift Lock will still not repeat.
Related Commands
XGetDefault, XAutoRepeatOff, XBell, XGetKeyboardControl, XChangeKeyboardControl, XGetPointerControl.
XBell
Xlib - User Preferences—
Name
XBell — ring the bell (Control G).
Synopsis
XBell (display, percent) Display *display; int percent;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| percent | Specifies the volume for the bell, relative to the base volume set with XChangeKeyboardControl. Possible values are −100 (off), through 0 (base volume), to 100 (loudest) inclusive. |
Description
Rings the bell on the keyboard at a volume relative to the base volume for the keyboard, if possible, percent can range from −100 to 100 inclusive (else a BadValue error). The volume at which the bell is rung when percent is nonnegative is:
volume = base - [(base * percent) / 100] + percent
and when percent is negative:
volume = base + [(base * percent) / 100]
To change the base volume of the bell, set the bell_percent variable of XChangeKeyboardControl.
Errors
| BadValue | percent < −100 or percent >100. |
Related Commands
XGetDefault, XAutoRepeatOff, XAutoRepeatOn, XGetKeyboardControl, XChangeKeyboardControl, XGetPointerControl.
XChangeActivePointerGrab
—Xlib - Pointer
Name
XChangeActivePointerGrab — change the parameters of an active pointer grab.
Synopsis
XChangeActivePointerGrab (display, event_mask, cursor, time) Display *display; unsigned int event_mask; Cursor cursor; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event_mask | Specifies which pointer events are reported to the client. This mask is the bitwise OR of one or more of these pointer event masks: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWindowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeymapStateMask. |
| cursor | Specifies the cursor that is displayed. A value of None will keep the current cursor. |
| time | Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. |
Description
XChangeActivePointerGrab changes the specified dynamic parameters if the pointer is actively grabbed by the client and the specified time is no earlier than the last pointer grab time and no later than the current X server time. XChangeActivePointerGrab has no effect on the passive parameters of XGrabButton, or the automatic grab that occurs between ButtonPress and ButtonRelease.
event_mask is always augmented to include ButtonPress and ButtonRelease.
For more information on pointer grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadCursor
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, XChangePointerControl.
XChangeGC
Xlib - Graphics Context—
Name
XChangeGC — change the components of a given graphics context.
Synopsis
XChangeGC (display, gc, valuemask, values) Display *display; GC gc; unsigned long valuemask; XGCValues *values;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| valuemask | Specifies the components in the graphics context that you want to change. This argument is the bitwise OR of one or more of the GC component masks. |
| values | Specifies a pointer to the XGCValues structure. |
Description
XChangeGC changes any or all of the components of a GC. The valuemask specifies which components are to be changed; it is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (|). The values structure contains the values to be set. These two arguments operate just like they do in XCreateGC. Changing the clip_mask overrides any previous XSetClipRectangles request for this GC. Changing the dash_offset or dash_list overrides any previous XSetDashes request on this GC.
Since consecutive changes to the same GC are buffered, there is no performance advantage to using this routine over the routines that set individual members of the GC.
Even if an error occurs, a subset of the components may have already been altered.
For more information, see Volume One: Chapter 5, The Graphics Context; and Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
int function; /* logical operation */
unsigned long plane_mask; /* plane mask */
unsigned long foreground; /* foreground pixel */
unsigned long background; /* background pixel */
int line_width; /* line width */
int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */
int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */
int join_style; /* JoinMiter, JoinRound, JoinBevel */
int fill_style; /* FillSolid, FillTiled, FillStippled */
int fill_rule; /* EvenOddRule, WindingRule */
int arc_mode; /* ArcChord, ArcPieSlice */
Pixmap tile; /* tile pixmap for tiling operations */
Pixmap stipple; /* stipple 1 plane pixmap for stipping */
int ts_x_origin; /* offset for tile or stipple operations */
int ts_y_origin;
Font font; /* default text font for text operations */
int subwindow_mode; /* ClipByChildren, IncludeInferiors */
Bool graphics_exposures; /* generate events on XCopy, Area, XCopyPlane */
int clip_x_origin; /* origin for clipping */
int clip_y_origin;
Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */
char dashes;
} XGCValues;
#define GCFunction (1L«0)
#define GCPlaneMask (1L«1)
#define GCForeground (1L«2)
#define GCBackground (1L«3)
#define GCLineWidth (1L«4)
#define GCLineStyle (1L«5)
#define GCCapStyle (1L«6)
#define GCJoinStyle (1L«7)
#define GCFillStyle (1L«8)
#define GCFillRule (1L«9)
#define GCTile (1L«10)
#define GCStipple (1L«11)
#define GCTileStipXOrigin (1L«12)
#define GCTileStipYOrigin (1L«13)
#define GCFont (1L«14)
#define GCSubwindowMode (1L«15)
#define GCGraphicsExposures (1L«16)
#define GCClipXOrigin (1L«17)
#define GCClipYOrigin (1L«18)
#define GCClipMask (1L«19)
#define GCDashOffset (1L«20)
#define GCDashList (1L«21)
#define GCArcMode (1L«22)
Errors
BadAlloc
BadFont
BadGC
BadMatch
BadPixmap
BadValue
Related Commands
XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetRegion, XSetState, XSetSubwindowMode, DefaultGC.
XChangeKeyboardControl
—Xlib - User Preferences
Name
XChangeKeyboardControl — change the keyboard preferences such as key click.
Synopsis
XChangeKeyboardControl (display, value_mask, values) Display *display; unsigned long value_mask; XKeyboardControl *values;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| value_mask | Specifies a mask composed of ORed symbols from the table shown in the Structures section below, specifying which fields to set. |
| values | Specifies the settings for the keyboard preferences. |
Description
XChangeKeyboardControl sets user preferences such as key click, bell volume and duration, light state, and keyboard auto-repeat. Changing some or all these settings may not be possible on all servers.
The value_mask argument specifies which values are to be changed; it is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (|).
The values structure contains the values to be set, as follows:
key_click_percent sets the volume for key clicks between 0 (off) and 100 (loud) inclusive. Setting to −1 restores the default.
The bell_percent sets the base volume for the bell between 0 (off) and 100 (loud) inclusive. Setting to −1 restores the default.
The bell_pitch sets the pitch (specified in Hz) of the bell. Setting to −1 restores the default.
The bell_duration sets the duration (specified in milliseconds) of the bell. Setting to −1 restores the default.
led_mode is either LedModeOn or LedModeOff. led is a number between 1 and 32 inclusive which specifies which light's state is to be changed. If both led_mode and led are specified, then the state of the LED specified in led is changed to the state specified in led_mode. If only led_mode is specified, then all the LEDs assume the value specified by led_mode.
auto_repeat_mode is either AutoRepeatModeOn, AutoRepeatModeOn, or AutoRepeatModeDefault. key is a keycode between 7 and 255 inclusive. If both auto_repeat_mode and key are specified, then the auto-repeat mode of the key specified by key is set as specified by auto_repeat_mode. If only auto_repeat_mode is specified, then the global auto_repeat mode for the entire keyboard is changed, without affecting the settings for each key. If the auto_repeat_mode is AutoRepeatModeDefault for either case, the key or the entire keyboard is returned to its default setting for the server, which is normally to have all non-modal keys repeat.
The order in which the changes are performed is server-dependent, and some may be completed when another causes an error.
For more information on user preferences, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
/* masks for ChangeKeyboardControl */
#define KBKeyClickPercent (1L«0)
#define KBBellPercent (1L«1)
#define KBBellPitch (1L«2)
#define KBBellDuration (1L«3)
#define KBLed (1L«4)
#define KBLedMode (1L«5)
#define KBKey (1L«6)
#define KBAutoRepeatMode (1L«7)
/* structure for ChangeKeyboardControl */
typedef struct {
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell_duration;
int led;
int led_mode; /* LedModeOn or LedModeOff */
int key;
int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn,
AutoRepeatModeDefault */
} XKeyboardControl;
Errors
| BadMatch | values.key specified but values.auto.repeat.mode not specified.
values.led specified but values.led_mode not specified. |
| BadValue | values.key_click_percent <−1.
values.bell_percent < −1. values.bell_pitch < −1. values.bell_duration < −1. |
Related Commands
XGetDefault, XAutoRepeatOff, XAutoRepeatOn, XBell, XGetKeyboardControl, XGetPointerControl.
XChangeKeyboardMapping
—Xlib - Keyboard
Name
XChangeKeyboardMapping — change the keyboard mapping.
Synopsis
XChangeKeyboardMapping (display, first_code, keysyms_per_code, keysyms, num_codes) Display *display; int first_keycode; int keysyms_per_keycode; KeySym *keysyms; int num_keycodes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| first_keycode | Specifies the first keycode that is to be changed. |
| keysyms_per_keycode | Specifies the number of keysyms that the caller is supplying for each keycode. |
| keysyms | Specifies a pointer to the list of keysyms. |
| num_keycodes | Specifies the number of keycodes that are to be changed. |
Description
Starting with first_keycode, XChangeKeyboardMapping defines the symbols for the specified number of keycodes. The symbols for keycodes outside this range remained unchanged. The number of elements in the keysyms list must be a multiple of keysyms_per_keycode (else a BadLength error). The specified first_keycode must be greater than or equal to min_keycode supplied at connection setup and stored in the display structure (else a BadValue error). In addition, the following expression must be less than or equal to max_keycode as returned in the connection setup (else a BadValue error):
max_keycode >= first_keycode + (num_keycodes / keysyms_per_keycode) - 1
The keysym number N (counting from 0) for keycode K has an index (counting from 0) of the following (in keysyms):
index = (K - first_keycode) * keysyms_per_keycode + N
The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired symbols. A special keysym value of NoSymbol should be used to fill in unused elements for individual keycodes. It is legal for NoSymbol to appear in nontrailing positions of the effective list for a keycode.
XChangeKeyboardMapping generates a MappingNotify event.
Errors
| BadAlloc | |
| BadValue | first.keycode less than display->min_keycode.
display->max_keycode exceeded (see above). |
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XChangePointerControl
—Xlib - Pointers
Name
XChangePointerControl — change the pointer preferences.
Synopsis
XChangePointerControl (display, do_accel, do_threshold, accel_numerator, accel_denominator, threshold) Display *display; Bool do_accel, do_threshold; int accel_numerator, accel_denominator; int threshold;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| do_accel | Specifies a boolean value that controls whether the values for the accel_numerator or accel_denominator are set. You can pass one of these constants: True or False. |
| do_threshold | Specifies a boolean value that controls whether the value for the threshold is set. You can pass one of these constants: True or False. |
| accel_numerator | Specifies the numerator for the acceleration multiplier. |
| accel_denominator | Specifies the denominator for the acceleration multiplier. |
| threshold | Specifies the acceleration threshold. |
Description
XChangePointerControl defines how the pointing device moves. The acceleration is a fraction (accel_numerator/accel_denominator) which specifies how many times faster than normal the pointer moves compared to how fast it normally moves. Acceleration takes effect only when a particular pointer motion is greater than threshold pixels at once, and only applies to the motion beyond threshold pixels. The values for do_accel and do_threshold must be nonzero for the pointer values to be set; otherwise, the parameters will be unchanged. Setting any argument to −1 restores the default for that argument.
The fraction may be rounded arbitrarily by the server.
Errors
| BadValue | accel_denominator is 0.
Negative value for do_accel or do_threshold. |
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl.
XChangeProperty
—Xlib - Properties
Name
XChangeProperty — change a property associated with a window.
Synopsis
XChangeProperty (display, w, property, type, format, mode, data, nelements) Display *display; Window w; Atom property, type; int format; int mode; unsigned char *data; int nelements;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose property you want to change. |
| property | Specifies the property atom. |
| type | Specifies the type of the property. X does not interpret the type, but simply passes it back to an application that later calls XGetProperty. |
| format | Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. This information allows the X server to correctly perform byte-swap operations as necessary. If the format is 16-bit or 32-bit, you must explicitly cast your data pointer to a (char *) in the call to XChangeProperty. Possible values are 8, 16, and 32. |
| mode | Specifies the mode of the operation. Possible values are PropModeReplace, PropModePrepend, PropModeAppend, or no value. |
| data | Specifies the property data. |
| nelements | Specifies the number of elements in the property. |
Description
XChangeProperty changes a property and generates PropertyNotify events if they have been selected.
XChangeProperty does the following according to the mode argument:
- PropModeReplace
Discards the previous property value and stores the new data.
- PropModePrepend
Inserts the data before the beginning of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data, type and format arguments must match the existing property value; otherwise a BadMatch error occurs.
- PropModeAppend
Appends the data onto the end of the existing data. If the property is undefined, it is treated as defined with the correct type and format with zero-length data, type and format arguments must match the existing property value; otherwise a BadMatch error occurs.
The property may remain defined even after the client which defined it exits. The property becomes undefined only if the application calls XDeleteProperty, destroys the specified window, or closes the last connection to the X server.
The maximum size of a property is server-dependent and can vary dynamically if the server has sufficient memory.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadAtom
BadMatch
BadValue
BadWindow
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XGetWindowProperty, XListProperties, XGetAtomName, XInternAtom.
XChangeSaveSet
—Xlib - Window Save Set
Name
XChangeSaveSet — add or remove a subwindow from the client's save-set.
Synopsis
XChangeSaveSet (display, w, change_mode) Display *display; Window w; int change_mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose children you want to add or remove from the client's save-set; it must have been created by some other client. |
| change_mode | Specifies the mode. Pass one of these constants: SetModeInsert (adds the window to this client's save-set) or SetModeDelete (deletes the window from this client's save-set). |
Description
XChangeSaveSet controls the longevity of subwindows, which are normally destroyed when the parent is destroyed.
The save-set of a client is a list of other client's windows which, if they are inferiors of one of the client's windows at connection close, should not be destroyed and should be remapped if they are unmapped. For example, a window manager which wants to add decoration to a window by adding a “frame,” might reparent an application's window to the “frame window.” When the frame is destroyed, the application's window should not also be destroyed, but should be returned to its previous place in the window hierarchy.
Windows are removed automatically from the save-set by the server when they are destroyed. For each window in the client's save-set, if the window is an inferior of a window created by the client, the save-set window is reparented to the closest ancestor such that the save-set window is not an inferior of a window created by the client. If the save-set window is unmapped, a MapWindow request is performed on it. After save-set processing, all windows created by the client are destroyed. For each nonwindow resource created by the client, the appropriate Free request is performed. All colors and colormap entries allocated by the client are freed.
For more information on save-sets, see Volume One, Chapter 13, Other Programming Techniques.
Errors
| BadMatch | w not created by some other client. |
| BadValue | |
| BadWindow |
Related Commands
XAddToSaveSet, XRemoveFromSaveSet.
XChangeWindowAttributes
Xlib - Window Attributes—
Name
XChangeWindowAttributes — set window attributes.
Synopsis
XChangeWindowAttributes (display, w, valuemask, attributes) Display *display; Window w; unsigned long valuemask; XSetWindowAttributes *attributes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| valuemask | Specifies which window attributes are defined in the attributes argument. The mask is made by combining the appropriate mask symbols listed in the Structures section using bitwise OR (|). If valuemask is 0, the rest is ignored, and attributes is not referenced. The values and restrictions are the same as for XCreateWindow. |
| attributes | Window attributes to be changed. The valuemask indicates which members in this structure are referenced. |
Description
XChangeWindowAttributes changes any or all of the window attributes that can be changed. For descriptions of the window attributes, see Volume One, Chapter 4, Window Attributes.
Changing the background does not cause the window contents to be changed. Use XClearWindow to cause the background to be repainted. Setting the border or changing the background such that the border tile origin changes causes the border to be repainted. Changing the background of a root window to None or ParentRelative restores the default background pixmap. Changing the border of a root window to CopyFromParent restores the default border pixmap.
Changing the win_gravity does not affect the current position of the window. Changing the backing_store of an obscured window to WhenMapped or Always may have no immediate effect. Also changing the backing_planes, backing_pixel, or save_under of a mapped window may have no immediate effect.
Multiple clients can select input on the same window; the event_mask passed are disjoint. When an event is generated it will be reported to all interested clients. Therefore, the setting of the event_mask attribute by one client will not affect the event_mask of others on the same window. However, at most, one client at a time can select each of SubstructureRedirectMask, ReSizeRedirectMask, and ButtonPressMask on any one window. If a client attempts to select on SubtructureRedirectMask, ResizeRedirectMask, or ButtonPressMask and some other client has already selected it on the same window, the X server generates a BadAccess error.
There is only one do_not_propagate_mask for a window, not one per client.
Changing the colormap attribute of a window generates a ColormapNotify event. Changing the colormap attribute of a visible window may have no immediate effect on the screen (because the map may not be installed until the window manager or client calls XInstallColormap).
Changing the cursor of a root window to None restores the default cursor.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 4, Window Attributes.
Structures
/*
* Data structure for setting window attributes.
*/
typedef struct {
Pixmap background_pixmap; /* pixmap, None, or ParentRelative */
unsigned long background_pixel; /* background pixel */
Pixmap border_pixmap; /* pixmap, None, or CopyFromParent */
unsigned long border_pixel; /* border pixel value */
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes; /* planes to be preseved if possible */
unsigned long backing_pixel; /* value to use in restoring planes */
Bool save_under; /* should bits under be saved (popups) */
long event_mask; /* set of events that should be saved */
long do_not_propagate_mask; /* set of events that should not propagate */
Bool override_redirect; /* override redirected config request */
Colormap colormap; /* colormap to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
/* Definitions for valuemask argument of CreateWindow and ChangeWindowAttributes *,
#define CWBackPixmap (1L«0)
#define CWBackPixel (1L«1)
#define CWBorderPixmap (1L«2)
#define CWBorderPixel (1L«3)
#define CWBitGravity (1L«4)
#define CWWinGravity (1L«5)
#define CWBackingStore (1L«6)
#define CWBackingPlanes (1L«7)
#define CWBackingPixel (1L«8)
#define CWOverrideRedirect (1L«9)
#define CWSaveUnder (1L«10)
#define CWEventMask (1L«11)
#define CWDontPropagate (1L«12)
#define CWColormap (1L«13)
#define CWCursor (1L«14)
Errors
BadAccess
BadColor
BadCursor
BadMatch
BadPixmap
BadValue
BadWindow
Related Commands
XGetWindowAttributes, XSetWindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGetGeometry.
XCheckIfEvent
—Xlib - Input Handling
Name
XCheckIfEvent — check the event queue for a matching event.
Synopsis
Bool XCheckIfEvent (display, event, predicate, args) Display *display; XEvent *event; /* RETURN */ Bool (*predicate) () ; char *args;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event | Returns the matched event. |
| predicate | Specifies the procedure that is called to determine if the next event matches your criteria. |
| arg | Specifies the user-specified argument that will be passed to the predicate procedure. |
Description
XCheckIfEvent returns the next event in the queue that is matched by the specified predicate procedure. If found, that event is removed from the queue, and True is returned. If no match is found, XCheckIfEvent returns False and flushes the output buffer. No other events are removed from the queue. Later events in the queue are not searched.
The predicate procedure is called with the arguments display, event, and arg.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XCheckMaskEvent
Xlib - Input Handling—
Name
XCheckMaskEvent — remove the next event that matches mask; don't wait.
Synopsis
Bool XCheckMaskEvent (display, mask_event, event) Display *display; unsigned long mask_event; XEvent *event; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event_mask | Specifies the event types to be returned. See list under XSelectInput. |
| event | Returns a copy of the matched event's XEvent structure. |
Description
XCheckMaskEvent removes the next event in the queue that matches the passed mask. The event is copied into an XEvent supplied by the caller and XCheckMaskEvent returns True. Other events earlier in the queue are not discarded. If no such event has been queued, XCheckMaskEvent flushes the output buffer and immediately returns False, without waiting.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XCheckTypedEvent
—Xlib - Input Handling
Name
XCheckTypedEvent — return the next event in queue that matches event type; don't wait.
Synopsis
Bool XCheckTypedEvent (display, event_type, report) Display *display; int event_type; XEvent *report; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event_type | Specifies the event type to be compared. |
| report | Returns a copy of the matched event structure. |
Description
XCheckTypedEvent searches first the event queue, then the events available on the server connection, for the specified event_type. If there is a match, it returns the associated event structure. Events searched but not matched are not discarded. XCheckTypedEvent returns True if the event is found. If the event is not found, XCheckTypedEvent flushes the output buffer and returns False.
This command is similar to XCheckMaskEvent, but it searches through the queue instead of inspecting only the last item on the queue. It also matches only a single event type instead of multiple event types as specified by a mask.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XCheckTypedWindowEvent
Xlib - Input Handling—
Name
XCheckTypedWindowEvent — return the next event in queue matching type and window.
Synopsis
Bool XCheckTypedWindowEvent (display, w, event_type, report) Display *display; Window w; int event_type; XEvent *report; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| event_type | Specifies the event type to be compared. |
| report | Returns the matched event's associated structure into this client-supplied structure. |
Description
XCheckTypedWindowEvent searches first the event queue, then any events available on the server connection, for an event that matches the specified window and the specified event type. Events searched but not matched are not discarded.
XCheckTypedWindowEvent returns True if the event is found; it flushes the output buffer and returns False if the event is not found.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XCheckWindowEvent
—Xlib - Input Handling
Name
XCheckWindowEvent — remove the next event matching both passed window and passed mask; don't wait.
Synopsis
Bool XCheckWindowEvent (display, w, event_mask, event) Display *display; Window w; int event_mask; XEvent *event; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. The event must match both the passed window and the passed event mask. |
| event_mask | Specifies the event mask. See XSelectInput for a list of mask elements. |
| event | Returns the XEvent structure. |
Description
XCheckWindowEvent removes the next event in the queue that matches both the passed window and the passed mask. If such an event exists, it is copied into an XEvent supplied by the caller. Other events earlier in the queue are not discarded.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
If a matching event is found, XCheckWindowEvent returns True. If no such event has been queued, it flushes the output buffer and returns False, without waiting.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XCirculateSubwindows
Xlib - Window Manipulation—
Name
XCirculateSubwindows — circulate the stacking order of children up or down.
Synopsis
XCirculateSubwindows (display, w, direction) Display *display; Window w; int direction;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID of the parent of the subwindows to be circulated. |
| direction | Specifies the direction (up or down) that you want to circulate the children. Pass either RaiseLowest or LowerHighest. |
Description
XCirculateSubwindows circulates the children of the specified window in the specified direction, either RaiseLowest or LowerHighest. If some other client has selected SubstructureRedirectMask on the specified window, then a CirculateRequest event is generated, and no further processing is performed. If you specify RaiseLowest, this function raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, this function lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is performed on formerly obscured windows.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadValue
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XCirculateSubwindowsDown
—Xlib - Window Manipulation
Name
XCirculateSubwindowsDown — circulate the bottom child to the top of the stacking order.
Synopsis
XCirculateSubwindowsDown (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID of the parent of the windows to be circulated. |
Description
XCirculateSubwindowsDown lowers the highest mapped child of the specified window that partially or completely obscures another child. The lowered child goes to the bottom of the stack. Completely unobscured children are not affected.
This function generates exposure events on any window formerly obscured. Repeated executions lead to round-robin lowering. This is equivalent to XCirculateSubwindows (display, w, LowerHighest).
If some other client has selected SubstructureRedirectMask on the window, then a CirculateRequest event is generated, and no further processing is performed.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XCirculateSubwindowsUp
Xlib - Window Manipulation—
Name
XCirculateSubwindowsUp — circulate the top child to the bottom of the stacking order.
Synopsis
XCirculateSubwindowsUp (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID of the parent of the windows to be circulated. |
Description
XCirculateSubwindowsUp raises the lowest mapped child of the specified window that is partially or completely obscured by another child. The raised child goes to the top of the stack. Completely unobscured children are not affected. This generates exposure events on the raised child (and its descendents, if any). Repeated executions lead to round robin-raising. This is equivalent to XCirculateSubwindows (display, w, RaiseLowest).
If some other client has selected SubstructureRedirectMask on the window, then a CirculateRequest event is generated, and no further processing is performed.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XClearArea
—Xlib - Drawing Primitives
Name
XClearArea — clear a rectangular area in a window.
Synopsis
XClearArea (display, w, x, y, width, height, exposures) Display *display; Window w; int x, y; unsigned int width, height; Bool exposures;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of an InputOutput window. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle to be cleared, relative to the origin of the window. |
| width
height |
Specify the dimensions in pixels of the rectangle to be cleared. |
| exposures | Specifies whether exposure events are generated. Must be either True or False. |
Description
XClearArea clears a rectangular area in a window.
If width is 0, the window is cleared from x to the right edge of the window. If height is 0, the window is cleared from y to the bottom of the window.
If the window has a defined background tile or it is ParentRelative, the rectangle is tiled with a plane_mask of all 1's and function of GXcopy. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, then one or more exposure events are generated for regions of the rectangle that are either visible or are being retained in a backing store.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
| BadMatch | Window is an InputOnly class window. |
| BadValue | |
| BadWindow |
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearWindow.
XClearWindow
—Xlib - Drawing Primitives
Name
XClearWindow — clear an entire window.
Synopsis
XClearWindow (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be cleared. |
Description
XClearWindow clears a window, but does not cause exposure events. This function is equivalent to XClearArea (display, w, 0, 0, 0, 0, False).
If the window has a defined background tile or it is ParentRelative, the rectangle is tiled with a plane_mask of all 1's and function of GXcopy. If the window has background None, the contents of the window are not changed.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
| BadMatch | If w is an InputOnly class window. |
| BadValue | |
| BadWindow |
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea.
XClipBox
Xlib - Regions—
Name
XClipBox — generate the smallest rectangle enclosing a region.
Synopsis
XClipBox (r, rect) Region r; XRectangle *rect; /* RETURN */
Arguments
| r | Specifies the region. |
| rect | Returns the smallest rectangle enclosing region r. |
Description
XClipBox returns the smallest rectangle that encloses the given region.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
} XRectangle;
/*
* opaque reference to Region data type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion.
XCloseDisplay
—Xlib - HouseKeeping
Name
XCloseDisplay — disconnect a client program from an X server and display.
Synopsis
XCloseDisplay (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XCloseDisplay closes the connection between the current client and the X server specified by the Display argument.
The XCloseDisplay routine destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources (GCs) that the client application has created on this display, unless the CloseDownMode of the client's resources has been changed by XSetCloseDownMode. Therefore, these windows, resource IDs, and other resources should not be referenced again. In addition, this routine discards any output that has been buffered but not yet sent.
Although these operations automatically (implicitly) occur when a process exits, you should call XCloseDisplay anyway.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XFree, XOpenDisplay, XNoOp, DefaultScreen.
XConfigureWindow
Xlib - Window Manipulation—
Name
XConfigureWindow — change the window position, size, border width, or stacking order.
Synopsis
XConfigureWindow (display, w, value_mask, values) Display *display; Window w; unsigned int value_mask; XWindowChanges *values;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be reconfigured. |
| value mask | Specifies which values are to be set using information in the values structure. value_mask is the bitwise OR of any number of symbols listed in the Structures section below. |
| values | Specifies a pointer to the XWindowChanges structure containing new configuration information. See the Structures section below. |
Description
XConfigureWindow changes the window position, size, border width, and/or the stacking order. This call should not be made without preparing for interaction with the window manager. A ConfigureNotify event is generated to announce any changes.
If the override_redirect attribute of the window is False, and if some other client has selected SubstructureRedirectMask on the parent, then the X server generates a ConfigureRequest event, and no further processing is performed. If some other client has selected ResizeRedirectMask on the window and width or height is being changed, then a ResizeRequest event is generated and the actual size of the window is not changed. The ResizeRequest event will be received by the other client (the window manager) and some action taken. The client should wait for the ConfigureNotify event to find out the size of the window. Note that the override_redirect attribute of the window has no effect on ResizeRedirectMask and that SubstructureRedirectMask on the parent has precedence over ResizeRedirectMask on the window.
When the geometry of the window is changed as specified, the window is restacked among siblings, and a ConfigureNotify event is generated if the state of the window actually changes. X generates GravityNotify events after generating ConfigureNotify events.
If a window's size actually changes, the window's subwindows may move according to their window gravity. Depending on the window's bit gravity, the contents of the window also may be moved. See Volume One, Chapter 4, Window Attributes for further information.
Exposure processing is performed on formerly obscured windows, including the window itself and its inferiors, if regions of them were obscured but now are not. As a result of increasing the width or height, exposure processing is also performed on any new regions of the window and any regions where window contents are lost.
The members of XWindowChanges that you specify in values are:
| x
y |
Specify the x and y coordinates of the upper-left outer corner of the window relative to the parent's origin. |
| width
height |
Specify the inside size of the window in pixels, not including the border. These arguments must be positive. |
| border_width | Specifies the width of the border in pixels. |
| sibling | Specifies the sibling window for stacking operations. If not specified, no change in the stacking order will be made. If specified, stack_mode must also be specified. |
| stack_mode | The stack mode can be any of these constants: Above, Below, TopIf, BottomIf, or Opposite. |
The computation for the BottomIf, TopIf, and Opposite stacking modes is performed with respect to window w's final size and position (as controlled by the other arguments to XConfigureWindow, not its initial position.) It is an error if sibling is specified without stack_mode. If sibling and stack_mode are specified, the window is restacked as follows:
| Stacking Flag | Position |
| Above | w is placed just above sibling |
| Below | w is placed just below sibling |
| TopIf | if sibling obscures w, then w is placed at the top of the stack |
| BottomIf | if w obscures sibling, then w is placed at the bottom of the stack |
| Opposite | if sibling occludes w, then w is placed at the top of the stack, else if w occludes sibling, then w is placed at the bottom of the stack |
If a stack_mode is specified but no sibling is specified, the window is restacked as follows:
| Stacking Flag | Position |
| Above | w is placed at the top of the stack |
| Below | w is placed at the bottom of the stack |
| TopIf | if any sibling obscures w, then w is placed at the top of the stack |
| BottomIf | if w obscures any sibling, then window is placed at the bottom of the stack |
| Opposite | if any sibling occludes w, then w is placed at the top of the stack, else if w occludes any sibling, then w is placed at the bottom of the stack |
Structures
typedef struct {
int x, y;
int width, height;
int border_width;
Window sibling;
int stack_mode;
} XWindowChanges;
/* ConfigureWindow structure */
/* ChangeWindow value bits definitions for valuemask */
#define CWX (1«0)
#define CWY (1«1)
#define CWWidth (1«2)
#define CWHeight (1«3)
#define CWBorderWidth (1«4)
#define CWSibling (1«5)
#define CWStackMode (1«6)
Errors
| BadMatch | Nonzero border_width of InputOnly window.
sibling specified without a stack_mode. The sibling window is not actually a sibling. |
| BadValue | width or height is 0. |
| BadWindow |
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XQueryTree.
XConvertSelection
—Xlib - Selections
Name
XConvertSelection — use the value of a selection.
Synopsis
XConvertSelection (display, selection, target, property, requestor, time) Display *display; Atom selection, target; Atom property; /* may be None */ Window requestor; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| selection | Specifies the selection atom. XA_PRIMARY and XA_SECONDARY are the standard selection atoms. |
| target | Specifies the atom of the type property that specifies the desired format for the data. |
| property | Specifies the property in which the requested data is to be placed. None is also valid, but current conventions specify that the requestor is in a better position to select a property than the selection owner. |
| requestor | Specifies the requesting window. |
| time | Specifies the time when the conversion should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. |
Description
XConvertSelection causes a SelectionRequest event to be sent to the current selection owner if there is one, specifying the property to store the data in (selection), the format to convert that data into before storing it (target), the property to place the information in (property), the window that wants the information (requestor), and the time to make the conversion (time).
The selection owner responds by sending a SelectionNotify event, which confirms the selected atom and type. If no owner for the specified selection exists, or if the owner could not convert to the type specified by requestor, the X server generates a SelectionNotify event to the requestor with property None. Whether or not the owner exists, the arguments are passed unchanged. See Volume One, Chapter 10, Interclient Communication, for a description of selection events and selection conventions.
Errors
BadAtom
BadWindow
Related Commands
XSetSelectionOwner, XGetSelectionOwner.
XCopyArea
—Xlib - Drawing Primitives
Name
XCopyArea — copy an area of a drawable.
Synopsis
XCopyArea (display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| src
dest |
Specify the source and destination rectangles to be combined, src and dest must have the same root and depth. |
| gc | Specifies the graphics context. |
| src_x
src_y |
Specify the x and y coordinates of the upper-left corner of the source rectangle relative to the origin of the source drawable. |
| width
height |
Specify the dimensions in pixels of both the source and destination rectangles. |
| dest_x dest_y | Specify the x and y coordinates within the destination window. |
Description
XCopyArea combines the specified rectangle of src with the specified rectangle of dest.src and dest must have the same root and depth.
If regions of the source rectangle are obscured and have not been retained in backing_store, or if regions outside the boundaries of the source drawable are specified, then those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing_store. If dest is a window with a background other than None, the corresponding regions of the destination are tiled (with plane_mask of all 1's and function GXcopy) with that background. Regardless of tiling, if the destination is a window and graphics_exposure in gc is True, then GraphicsExpose events for all corresponding destination regions are generated. If graphics_exposure is True but no regions are exposed, then a NoExpose event is generated.
If regions of the source rectangle are not obscured and graphics_exposure is False, one NoExpose event is generated on the destination.
XCopyArea uses these graphics context components: function, plane_mask, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and clip_mask.
Errors
| BadDrawable | |
| BadGC | |
| BadMatch | The src and dest rectangles do not have the same root and depth. |
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XCopyColormapAndFree
—Xlib - Colormaps
Name
XCopyColormapAndFree — copy a colormap and return a new colormap ID.
Synopsis
Colormap XCopyColormapAndFree (display, cmap) Display *display; Colormap cmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap you are moving out of. |
Description
XCopyColormapAndFree is used to obtain a new virtual colormap when allocating colorcells out of a previous colormap has failed due to resource exhaustion (that is, too many cells or planes were in use in the original colormap).
XCopyColormapAndFree moves all of the client's existing allocations from cmap to the returned Colormap and frees those entries in cmap. Values in other entries of the new colormap are undefined. The visual type and screen for the new colormap is the same as for the old.
If cmap was created by the client with the alloc argument set to AllocAll, the new colormap is also created with AllocAll, all color values for all entries are copied from cmap, and then all entries in cmap are freed.
If cmap was created by the client with AllocNone, the allocations to be moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes and that have not been freed since they were allocated.
For more information, see Volume One, Chapter 7, Color.
Errors
BadAlloc
BadColor
Related Commands
XCreateColormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XCopyGC
Xlib - Graphics Context—
Name
XCopyGC — copy a graphics context.
Synopsis
XCopyGC (display, src, valuemask, dest) Display *display; GC src, dest; unsigned long valuemask;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| src | Specifies the components of the source graphics context. |
| valuemask | Specifies the components in the source GC structure to be copied into the destination GC. valuemask is made by combining any number of the mask symbols listed in the Structures section using bitwise OR (|). |
| dest | Specifies the destination graphics context. |
Description
XCopyGC copies the selected elements of one graphics context to another. See Volume One, Chapter 5, The Graphics Context, for a description of the graphics context.
Structures
The GC structure contains the following elements:
/*
* Data structure for setting graphics context.
*/
typedef struct {
int function; /* logical operation */
unsigned long plane_mask; /* plane mask */
unsigned long foreground; /* foreground pixel */
unsigned long background; /* background pixel */
int line_width; /* line width */
int line_style; /* Solid, OnOffDash, DoubleDash */
int cap_style; /* NotLast, Butt, Round, Projecting */
int join_style; /* Miter, Round, Bevel */
int fill_style; /* Solid, Tiled, Stippled */
int fill_rule; /* EvenOdd, Winding */
int arc_mode; /* PieSlice */
Pixmap tile; /* tile pixmap for tiling operations */
Pixmap stipple; /* stipple 1 plane pixmap for stipping */
int ts_x_origin; /* offset for tile or stipple operations */
int ts_y_origin;
Font font; /* default text font for text operations */
int subwindow_mode; /* ClipByChildren, IncludeInferiors */
Bool graphics_exposures; /* boolean, should exposures be generated */
int clip_x_origin; /* origin for clipping */
int clip_y_origin;
Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */
char dashes;
} XGCValues;
/* GC components: masks used in XCreateGC, XCopyGC, XChangeGC, OR'ed into
GC.stateChanges */
#define GCFunction (1L«0)
#define GCPlaneMask (1L«1)
#define GCForeground (1L«2)
#define GCBackground (1L«3)
#define GCLineWidth (1L«4)
#define GCLineStyle (1L«5)
#define GCCapStyle (1L«6)
#define GCJoinStyle (1L«7)
#define GCFillStyle (1L«8)
#define GCFillRule (1L«9)
#define GCTile (1L«10)
#define GCStipple (1L«11)
#define GCTileStipXOrigin (1L«12)
#define GCTileStipYOrigin (1L«13)
#define GCFont (1L«14)
#define GCSubwindowMode (1L«15)
#define GCGraphicsExposures (1L«16)
#define GCClipXOrigin (1L«17)
#define GCClipYOrigin (1L«18)
#define GCClipMask (1L«19)
#define GCDashOffset (1L«20)
#define GCDashList (1L«21)
#define GCArcMode (1L«22)
Errors
| BadAlloc | |
| BadGC | |
| BadMatch | src and dest do not have the same root and depth. |
Related Commands
XChangeGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XCopyPlane
Xlib - Drawing Primitives—
Name
XCopyPlane — copy a single plane of a drawable into a drawable with depth, applying pixel values.
Synopsis
XCopyPlane (display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y, plane) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y; unsigned long plane;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| src
dest |
Specify the source and destination drawables. |
| gc | Specifies the graphics context. |
| src_x
src_y |
Specify the x and y coordinates of the upper-left corner of the source rectangle relative to the origin of the drawable. |
| width
height |
Specify the width and height in pixels. These are the dimensions of both the source and destination rectangles. |
| dest_x
dest_y |
Specify the x and y coordinates at which the copied area will be placed relative to the origin of the destination drawable. |
| plane | Specifies the source bit-plane. You must set exactly one bit. |
Description
XCopyPlane copies a single plane of a rectangle in the source into the entire depth of a corresponding rectangle in the destination. The plane of the source drawable and the foreground/background pixel values in gc are combined to form a pixmap of the same depth as the destination drawable, and the equivalent of an XCopyArea is performed, with all the same exposure semantics.
XCopyPlane uses these graphics context components: function, plane_mask, foreground, background, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and clip_mask.
src and dest must have the same root, but need not have the same depth.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
| BadDrawable | |
| BadGC | |
| BadMatch | src and dest do not have the same root. |
| BadValue | plane does not have exactly one bit set. |
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XCreateAssocTable
Xlib - Association Tables—
Name
XCreateAssocTable — create a new association table (X10).
Synopsis
XAssocTable *XCreateAssocTable (size) int size;
Arguments
| size | Specifies the number of buckets in the hashed association table. |
Description
XCreateAssocTable creates an association table, which allows you to associate your own structures with X resources in a fast lookup table. This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
The size argument specifies the number of buckets in the hash system of XAssocTable. For reasons of efficiency the number of buckets should be a power of two. Some size suggestions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per buckets is 8.
If there is an error allocating memory for the XAssocTable, a NULL pointer is returned.
For more information on association tables, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
XAssoc *buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */
}XAssocTable;
Related Commands
XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.
XCreateBitmapFromData
—Xlib - Pixmaps and Tiles
Name
XCreateBitmapFromData — create a bitmap from X11 bitmap format data.
Synopsis
Pixmap XCreateBitmapFromData (display, drawable, data, width, height) Display *display; Drawable drawable; char *data; unsigned int width, height;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. This determines which screen to create the bitmap on. |
| data | Specifies the location of the bitmap data. |
| width
height |
Specify the dimensions in pixels of the created bitmap. If smaller than the original bitmap, the upper-left corner is used. |
Description
XCreateBitmapFromData creates a single-plane pixmap from an array of hexadecimal data. This data may be defined in the program or included. The bitmap data must be in X version 11 format as shown below (it cannot be in X10 format). The following format is assumed for the data, where the variables are members of the XImage structure described in Volume One, Chapter 6, Drawing Graphics and Text:
format=XYPixmap
bit_order=LSBFirst
byte_order=LSBFirst
bitmap_unit=8
bitmap_pad=8
xoffset=0
no extra bytes per line
XCreateBitmapFromData creates an image with the specified data and copies it into the created pixmap. The following is an example of creating a bitmap:
#define gray_width 16
#define gray_height 16
#define gray_x_hot 8
#define gray_y_hot 8
static char gray_bits[] =
{
0xf81f, 0xe3c7, 0xcff3, 0x9ff9,
0xbffd, 0x33cc, 0x7ffe, 0x7ffe,
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd,
0x9c39, 0xcff3, 0xe3c7, 0xf81f,
};
Pixmap XCreateBitmapFromData(display, window, gray_bits,
gray_width, gray_height);
If insufficient working storage was allocated, XCreateBitmapFromData returns NULL. The user should free the bitmap using XFreePixmap when it is no longer needed.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadAlloc
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreatePixmapFromBitmapData.
XCreateColormap
—Xlib - Colormaps
Name
XCreateColormap — create a colormap.
Synopsis
Colormap XCreateColormap (display, w, visual, alloc) Display *display; Window w; Visual *visual; int alloc;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies a window ID. The colormap created will be associated with the same screen as the window. |
| visual | Specifies a pointer to the Visual structure for the colormap. The visual class and depth must be supported by the screen. |
| alloc | Specifies how many colormap entries to allocate. Pass either AllocNone or AllocAll. |
Description
XCreateColormap creates a colormap of the specified visual type and allocates either none or all of its entries, and returns the colormap ID.
It is legal to specify any visual class in the structure pointed to by the visual argument. If the class is StaticColor, StaticGray, or TrueColor, the colorcells will have pre-allocated read-only values defined by the individual server but unspecified by the X11 protocol. In these cases, alloc must be specified as AllocNone (else a BadMatch error).
For the other visual classes, Pseudocolor, DirectColor, and GrayScale, you can pass either AllocAll or AllocNone to the alloc argument. If you pass AllocNone, the colormap has no allocated entries. This allows your client programs to allocate read-only colorcells with XAllocColor or read/write cells with XAllocColorCells, AllocColorPlanes and XStoreColors. If you pass the constant AllocAll, the entire colormap is allocated writable (all the entries are read/write, nonshareable and have undefined initial values), and the colors can be set with XStoreColors. However, you cannot free these entries with XFreeColors, and no relationships between the entries are defined.
If the visual class is Pseudocolor or GrayScale and alloc is AllocAll, this function simulates many calls to the function XAllocColor returning all pixel values from 1 to (map_entries - 1). For a visual class of DirectColor, the processing for AllocAll simulates a call to the function XAllocColorPlanes, returning a pixel value of 0 and mask values the same as the red_mask, green_mask, and blue_mask members in visual.
The visual structure should be as returned from the Defaultvisual macro, XMatchVisualInfo, or XGetVisualInfo. The red_mask, green_mask, and blue_mask members specify which bits of the pixel value are allocated to each primary color. The map_entries member specifies the number of colormap entries.
For more information on creating colormaps, see Volume One, Chapter 7, Color.
Errors
| BadAlloc | |
| BadMatch | Didn't use AllocNone for StaticColor, StaticGray, or TrueColor. |
| visual type not supported on screen. | |
| BadValue | |
| BadWindow |
Related Commands
XCopyColormapAndFree, XFreeColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XCreateFontCursor
—Xlib - Cursors
Name
XCreateFontCursor — create a cursor from the standard cursor font.
Synopsis
#include <X11/cursorfont.h> Cursor XCreateFontCursor (display, shape) Display *display; unsigned int shape;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| shape | Specifies which character in the standard cursor font should be used for the cursor. |
Description
X provides a set of standard cursor shapes in a special font named “cursor.” Programs are encouraged to use this interface for their cursors, since the font can be customized for the individual display type and swapped between clients.
The hotspot comes from the information stored in the font. The initial colors of the cursor are black for the foreground and white for the background. XRecolorCursor can be used to change the colors of the cursor to those desired.
For more information about cursors and their shapes in fonts, see Appendix I, The Cursor Font.
Errors
BadAlloc
BadMatch
BadValue
Related Commands
XDefineCursor, XUndefineCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBestSize.
XCreateGC
—Xlib - Graphics Context
Name
XCreateGC — create a new graphics context for a given screen with the depth of the specified drawable.
Synopsis
GC XCreateGC (display, drawable, valuemask, values) Display *display; Drawable drawable; unsigned long valuemask; XGCValues *values;
Arguments
| display | Specifies a pointer to the Display structure, returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| valuemask | Specifies which members of the GC are to be set using information in the values structure. valuemask is made by combining any number of the mask symbols listed in the Structures section. |
| values | Specifies a pointer to an XGCValues structure which will provide components for the new GC. |
Description
This function creates a new GC, replacing the old one if there was one. The specified components of the new graphics context in valuemask are set to the values passed in the values argument. Unset components default as follows:
| Component | Value |
| function | GXcopy |
| plane_mask | all 1's |
| foreground | 0 |
| background | 1 |
| line_width | 0 |
| line_style | LineSolid |
| cap_style | CapButt |
| join_style | JoinMiter |
| fill_style | FillSolid |
| fill_rule | EvenOddRule |
| arc_mode | ArcPieSlice |
| tile | Pixmap filled with foreground pixel |
| stipple | Pixmap filled with 1's |
| ts_x_origin | 0 |
| ts_y_origin | 0 |
| font | (implementation dependent) |
| subwindow_mode | ClipByChildren |
| graphics_exposures | True |
| clip_x_origin | 0 |
| clip_y_origin | 0 |
| clip_mask | None |
| dash_offset | 0 |
| dash_list | 4 (i.e., the list [4, 4]) |
For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
int function; /* logical operation */
unsigned long plane_mask; /* plane mask */
unsigned long foreground; /* foreground pixel */
unsigned long background; /* background pixel */
int line_width; /* line width */
int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */
int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */
int join_style; /* JoinMiter, JoinRound, JoinBevel */
int fill_style; /* FillSolid, FillTiled, FillStippled */
int fill_rule; /* EvenOddRule, WindingRule */
int arc_mode; /* ArcPieSlice, ArcChord */
Pixmap tile; /* tile pixmap for tiling operations */
Pixmap stipple; /* stipple 1 plane pixmap for stipping */
int ts_x_origin; /* offset for tile or stipple operations */
int ts_y_origin;
Font font; /* default text font for text operations */
int subwindow_mode; /* ClipByChildren, IncludeInferiors */
Bool graphics_exposures; /* generate events on XCopyArea, XCopyPlane */
int clip_x_origin; /* origin for clipping */
int clip_y_origin;
Pixmap clip_mask; /* bitmap clipping; other calls for rects */
int dash_offset; /* patterned/dashed line information */
char dashes;
} XGCValues;
#define GCFunction (1L«0)
#define GCPlaneMask (1L«1)
#define GCForeground (1L«2)
#define GCBackground (1L«3)
#define GCLineWidth (1L«4)
#define GCLineStyle (1L«5)
#define GCCapStyle (1L«6)
#define GCJoinStyle (1L«7)
#define GCFillStyle (1L«8)
#define GCFillRule (1L«9)
#define GCTile (1L«10)
#define GCStipple (1L«11)
#define GCTileStipXOrigin (1L«12)
#define GCTileStipYOrigin (1L«13)
#define GCFont (1L«14)
#define GCSubwindowMode (1L«15)
#define GCGraphicsExposures (1L«16)
#define GCClipXOrigin (1L«17)
#define GCClipYOrigin (1L«18)
#define GCClipMask (1L«19)
#define GCDashOffset (1L«20)
#define GCDashList (1L«21)
#define GCArcMode (1L«22)
Errors
BadAlloc
BadDrawable
BadFont
BadMatch
BadPixmap
BadValue
Related Commands
XChangeGC, XCopyGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XCreateGlyphCursor
Xlib - Cursors—
Name
XCreateGlyphCursor — create a cursor from font glyphs.
Synopsis
Cursor XCreateGlyphCursor (display, source_font, mask_font, source_char, mask_char, foreground_color, background_color) Display *display; Font source_font, mask_font; unsigned int source_char, mask_char; XColor *foreground_color; XColor *background_color;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| source_font | Specifies the font from which a character is to be used for the cursor. |
| mask_font | Specifies the mask font. Optional; specify 0 if not needed. |
| source_char | Specifies the index into the cursor shape font. |
| mask_char | Specifies the index into the mask shape font. Optional; specify 0 if not needed. |
| foreground_color | Specifies the red, green, and blue (RGB) values for the foreground. |
| background_color | Specifies the red, green, and blue (RGB) values for the background. |
Description
XCreateGlyphCursor is similar to XCreatePixmapCursor, but the source and mask bitmaps are obtained from separate font characters, perhaps in separate fonts. The mask font and character are optional. If mask_char is not specified, all pixels of the source are displayed.
The x offset for the hotspot of the created cursor is the left-bearing for the source character, and the y offset is the ascent, each measured from the upper-left corner of the bounding rectangle of the character.
The origins of the source and mask (if it is defined) characters are positioned coincidently and define the hotspot. The source and mask need not have the same bounding box metrics, and there is no restriction on the placement of the hotspot relative to the bounding boxes.
Note that source_char and mask_char are of type unsigned int, not of type XChar2b. For two-byte matrix fonts, the 16-bit value should be formed with the byte1 member in the most significant byte and the byte2 member in the least significant byte.
You can free the fonts with XFreeFont if they are no longer needed after creating the glyph cursor.
For more information on fonts and cursors, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
| BadAlloc | |
| BadFont | |
| BadValue | source_char not defined in source_font.
mask_char not defined in mask_font (if mask_font defined). |
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBestSize.
XCreateImage
Xlib - Images—
Name
XCreateImage — allocate memory for an XImage structure.
Synopsis
#include <X11/Xutil.h> XImage *XCreateImage (display, visual, depth, format, offset, data, width, height, bitmap_pad, bytes_per_line) Display *display; Visual *visual; unsigned int depth; int format; int offset; char *data; unsigned int width; unsigned int height; int bitmap_pad; int bytes_per_line;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| visual | Specifies a pointer to a visual that should match the visual of the window the image is to be displayed in. |
| depth | Specifies the depth of the image. |
| format | Specifies the format for the image. Pass one of these constants: XYPixmap, or ZPixmap. |
| offset | Specifies the number of pixels beyond the beginning of the data (pointed to by data) where the image actually begins. This is useful if the image is not aligned on an even addressable boundary. |
| data | Specifies a pointer to the image data. |
| width
height |
Specify the width and height in pixels of the image. |
| bitmap_pad | Specifies the quantum of a scan line. In other words, the start of one scan line is separated in client memory from the start of the next scan line by an integer multiple of this many bits. You must pass one of these values: 8, 16, or 32. |
| bytes_per_line | Specifies the number of bytes in the client image between the start of one scan line and the start of the next. If you pass a value of 0 here, Xlib assumes that the scan lines are contiguous in memory and thus calculates the value of bytes_per_line itself. |
Description
XCreateImage allocates the memory needed for an XImage structure for the specified display and visual.
This function does not allocate space for the image itself. It initializes the structure with byte order, bit order, and bitmap unit values, and returns a pointer to the XImage structure. The red, green, and blue mask values are defined for ZPixmap format images only and are derived from the Visual structure passed in.
For a description of images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XDestroyImage, XPutImage, XGetImage, XSubImage, XGetSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XCreatePixmap
Xlib - Pixmaps and Tiles—
Name
XCreatePixmap — create a pixmap.
Synopsis
Pixmap XCreatePixmap (display, drawable, width, height, depth) Display *display; Drawable drawable; unsigned int width, height; unsigned int depth;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. May be an InputOnly window. |
| width
height |
Specify the width and height in pixels of the pixmap. The values must be nonzero. |
| depth | Specifies the depth of the pixmap. The depth must be supported by the screen of the specified drawable. |
Description
XCreatePixmap creates a pixmap resource and returns its pixmap ID. The initial contents of the pixmap are undefined.
The server uses the drawable argument to determine which screen the pixmap is stored on. The pixmap can only be used on this screen. The pixmap can only be used with other drawables of the same depth, except in XCopyPlane.
A bitmap is a single-plane pixmap. There is no separate bitmap type in X Version 11.
Pixmaps should be considered a precious resource, since many systems have limits on the amount of off-screen memory available.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
| BadAlloc | |
| BadDrawable | |
| BadValue | width or height is 0.
depth is not supported by root window. |
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XCreatePixmapCursor
—Xlib - Pixmaps and Tiles
Name
XCreatePixmapCursor — create a cursor from two bitmaps.
Synopsis
Cursor XCreatePixmapCursor (display, source, mask, foreground_color, background_color, x_hot, y_hot) Display *display; Pixmap source; Pixmap mask; XColor *foreground_color; XColor *background_color; unsigned int x_hot, y_hot;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| source | Specifies the shape of the source cursor. A pixmap of depth 1. |
| mask | Specifies the bits of the cursor that are to be displayed (the mask or stipple). A pixmap of depth 1. |
| foreground_color | Specifies the red, green, and blue (RGB) values for the foreground. |
| background_color | Specifies the red, green, and blue (RGB) values for the background. |
| x_hot | Specify the coordinates of the cursor's hotspot relative to the source's origin. |
| y_hot | Must be a point within the source. |
Description
XCreatePixmapCursor creates a cursor and returns a cursor ID. Foreground and background RGB values must be specified using foreground_color and background_color, even if the server only has a monochrome screen. The foreground_color is used for the 1 bits in the source, and the background is used for the 0 bits. Both source and mask (if specified) must have depth 1, but can have any root. The mask pixmap defines the shape of the cursor; that is, the 1 bits in the mask define which source pixels will be displayed. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the source.
The pixmaps can be freed immediately if no further explicit references to them are to be made.
For more information on the cursor font, see Appendix I, The Cursor Font. See also the description of cursors in Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XCreatePixmapFromBitmapData
—Xlib - Pixmaps and Bitmaps
Name
XCreatePixmapFromBitmapData — create a pixmap with depth from bitmap data.
Synopsis
Pixmap XCreatePixmapFromBitmapData (display, drawable, data, width, height, fg, bg, depth) Display *display; Drawable drawable; char *data; unsigned int width, height; unsigned long fg, bg; unsigned int depth;
Arguments
| display | Specifies a pointer to the Display structure, returned from XOpenDisplay. |
| drawable | Specifies a drawable ID which indicates which screen the pixmap is to be used on. |
| data | Specifies the data in bitmap format. |
| width
height |
Specify the width and height in pixels of the pixmap to create. |
| fg
bg |
Specify the foreground and background pixel values to use. |
| depth | Specifies the depth of the pixmap. Must be valid on the screen specified by drawable. |
Description
XCreatePixmapFromBitmapData creates a pixmap of the given depth using bitmap data and foreground and background pixel values.
The following format for the data is assigned by default, where the variables are members of the XImage structure described in Volume One, Chapter 6, Drawing Graphics and Text:
format=XYPixmap
bit_order=LSBFirst
byte_order=LSBFirst
bitmap_unit=8
bitmap_pad=8
xoffset=0
no extra bytes per line
XCreatePixmapFromBitmapData creates an image from the data and uses XPutImage to place the data into the pixmap. For example:
#define gray_width 16
#define gray_height 16
#define gray_x_hot 8
#define gray_y_hot 8
static char gray_bits[] =
{
0xf81f, 0xe3c7, 0xcff3, 0x9ff9,
0xbffd, 0x33cc, 0x7ffe, 0x7ffe,
0x7e7e, 0x7ffe, 0x37ec, 0xbbdd,
0x9c39, 0xcff3, 0xe3c7, 0xf81f/* example data */
};
unsigned long foreground, background;
unsigned int depth;
/* open display, determine colors and depth */
Pixmap XCreatePixmapFromBitmapData(display, window, gray_bits,
gray_width, gray_height, foreground, background, depth);
If you want to use data of a different format, it is straightforward to write a routine that does this yourself, using images.
Pixmaps should be considered a precious resource, since many systems have limits on the amount of off-screen memory available.
Errors
BadAlloc
BadMatch
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XCreateRegion
—Xlib - Regions
Name
XCreateRegion — create a new empty region.
Synopsis
Region XCreateRegion ()
Description
XCreateRegion creates a new region of undefined size. XPolygonRegion can be used to create a region with a defined shape and size. Many of the functions that perform operations on regions can also create regions.
For a description of regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct _XREGION *Region;/* opaque reference to region type */
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XDestroyRegion, XEqualRegion, XClipBox.
XCreateSimpleWindow
Xlib - Window Existence—
Name
XCreateSimpleWindow — create an unmapped InputOutput window.
Synopsis
Window XCreateSimpleWindow (display, parent, x, y, width, height, border_width, border, background) Display *display; Window parent; int x, y; unsigned int width, height, border_width; unsigned long border; unsigned long background;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| parent | Specifies the parent window ID. Must be an InputOutput window. |
| x
y |
Specify the x and y coordinates of the upper-left pixel of the new window's border relative to the origin of the parent (inside the parent window's border). |
| width
height |
Specify the width and height, in pixels, of the new window. These are the inside dimensions, not including the new window's borders, which are entirely outside of the window. Must be nonzero. Any part of the window that extends outside its parent window is clipped. |
| border_width | Specifies the width, in pixels, of the new window's border. |
| border | Specifies the pixel value for the border of the window. |
| background | Specifies the pixel value for the background of the window. |
Description
XCreateSimpleWindow creates an unmapped InputOutput subwindow of the specified parent window. Use XCreateWindow to set the attributes to create an InputOnly window while creating a window.
XCreateSimpleWindow returns the ID of the created window. The new window is placed on top of the stacking order relative to its siblings. Note that the window is unmapped when it is created—use XMapWindow to display it. This function generates a CreateNotify event.
The initial conditions of the window are as follows:
The window inherits its depth, class, and visual from its parent. All other window attributes have their default values.
All properties have undefined values.
The new window will not have a cursor defined; the cursor will be that of the window's parent until the cursor attribute is set with XDefineCursor.
If no background or border is specified, CopyFromParent is implied.
For more information, see Volume One, Chapter 2, X Concepts and Volume One, Chapter 3, Basic Window Program.
Errors
| BadAlloc | |
| BadMatch | |
| BadValue | width or height is 0. |
| BadWindow | Specified parent is an InputOnly window. |
Related Commands
XCreateWindow, XDestroySubwindows, XDestroyWindow.
XCreateWindow
Xlib - Window Existence—
Name
XCreateWindow — create a window and set attributes.
Synopsis
Window XCreateWindow (display, parent, x, y, width, height, border_width, depth, class, visual, valuemask, attributes) Display *display; Window parent; int x, y; unsigned int width, height; unsigned int border_width; int depth; unsigned int class; Visual *visual unsigned long valuemask; XSetWindowAttributes *attributes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| parent | Specifies the parent window. Parent must be InputOutput if class of window created is to be InputOutput. |
| x
y |
Specify the x and y coordinates of the upper-left pixel of the new window's border relative to the origin of the parent (upper left inside the parent's border). |
| width
height |
Specify the width and height, in pixels, of the window. These are the new window's inside dimensions. These dimensions do not include the new window's borders, which are entirely outside of the window. Must be nonzero, otherwise XCreateWindow generates a BadValue error. |
| border_width | Specifies the width, in pixels, of the new window's border. Must be 0 for InputOnly windows, otherwise a BadMatch error is returned. |
| depth | Specifies the depth of the window, which is not necessarily the same as the parent's depth. A depth of 0 for class InputOutput or CopyFromParent means the depth is taken from the parent. |
| class | Specifies the new window's class. Pass one of these constants: InputOutput, InputOnly, or CopyFromParent. |
| visual | Specifies a pointer to the visual structure describing the colormaps to be used with this window. CopyFromParent is valid. |
| valuemask | Specifies which window attributes are defined in the attributes argument. If valuemask is 0, the rest is ignored, and attributes is not referenced. This mask is the inclusive OR of the valid attribute mask bits. |
| attributes | Attributes of the window to be set at creation time should be set in this structure. The valuemask should have the appropriate bits set to indicate which attributes have been set in the structure. |
Description
To create an unmapped subwindow for a specified parent window from an application, you can use XCreateWindow or XCreateSimpleWindow. XCreateWindow is a more general function that allows you to set specific window attributes when you create it. If you do not want to set specific attributes when you create a window, use XCreateSimpleWindow, which creates a window that inherits its attributes from its parent. XCreateSimpleWindow creates InputOutput windows only.
XCreateWindow returns the ID of the created window. XCreateWindow causes the X server to generate a CreateNotify event. The newly created window is placed on top of its siblings in the stacking order.
Extension packages may define other classes of windows.
The visual should be Defaultvisual or one returned by XGetVisualInfo or XMatchVisualInfo.
For more information, see Volume One, Chapter 4, Window Attributes.
Structures
/*
* Data structure for setting window attributes.
*/
typedef struct {
Pixmap background_pixmap; /* background or None or ParentRelative */
unsigned long background_pixel; /* background pixel */
Pixmap border_pixmap; /* border of the window */
unsigned long border_pixel; /* border pixel value */
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes; /* planes to be preseved if possible */
unsigned long backing_pixel; /* value to use in restoring planes */
Bool save_under; /* should bits under be saved (popups) */
long event_mask; /* set of events that should be saved */
long do_not_propagate_mask; /* set of events that should not propagate */
Bool override_redirect; /* boolean value for override-redirect */
Colormap colormap; /* colormap to be associated with window */
Cursor cursor; /* cursor to be displayed (or None) */
} XSetWindowAttributes;
/* Window attributes for CreateWindow and ChangeWindowAttributes */
/* Definitions for valuemask argument */
#define CWBackPixmap (1L«0)
#define CWBackPixel (1L«1)
#define CWBorderPixmap (1L«2)
#define CWBorderPixel (1L«3)
#define CWBitGravity (1L«4)
#define CWWinGravity (1L«5)
#define CWBackingStore (1L«6)
#define CWBackingPlanes (1L«7)
#define CWBackingPixel (1L«8)
#define CWOverrideRedirect (1L«9)
#define CWSaveUnder (1L«10)
#define CWEventMask (1L«11)
#define CWDontPropagate (1L«12)
#define CWColormap (1L«13)
#define CWCursor (1L«14)
Errors
| BadAlloc | Attribute besides win_gravity, event_mask, do_not_propagate_mask, override_redirect or cursor specified for InputOnly. |
| BadColor | depth nonzero for InputOnly. |
| BadCursor | Parent of InputOutput is InputOnly. |
| BadMatch | border_width is nonzero for InputOnly. |
| BadPixmap | depth not supported on screen for InputOutput. |
| BadValue | width or height is 0. |
| BadWindow | visual type not supported on screen (either InputOnly or InputOutput). |
Related Commands
XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow.
XDefineCursor
—Xlib - Cursors
Name
XDefineCursor — assign a cursor to a window.
Synopsis
XDefineCursor (display, w, cursor) Display *display; Window w; Cursor cursor;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which the cursor is to be assigned. |
| cursor | Specifies the cursor to be displayed when the pointer is in the specified window. Pass None to have the parent's cursor displayed in the window, or for the root window, to have the default cursor displayed. |
Description
Sets the cursor attribute of a window, so that the specified cursor is shown whenever this window is visible and the pointer is inside. If XDefineCursor is not called, the parent's cursor is used by default.
For more information on available cursors, see Appendix I, The Cursor Font.
Errors
BadCursor
BadWindow
Related Commands
XUndefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBestSize.
XDeleteAssoc
Xlib - Association Tables—
Name
XDeleteAssoc — delete an entry from an association table.
Synopsis
XDeleteAssoc (display, table, x_id) Display *display; XAssocTable *table; XID x_id;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| table | Specifies one of the association tables created by XCreateAssocTable. |
| x_id | Specifies the X resource ID of the association to be deleted. |
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
XDeleteAssoc deletes an association in an XAssocTable keyed on its XID. Redundant deletes (and deletes of nonexistent XID's) are meaningless and cause no problems. Deleting associations in no way impairs the performance of an XAssocTable.
For more information on association tables, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
XAssoc *buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */
}XAssocTable;
Related Commands
XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc.
XDeleteContext
—Xlib - Context Manager
Name
XDeleteContext — delete a context entry for a given window and type.
Synopsis
int XDeleteContext (display, w, context) Display *display; Window w; XContext context;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window with which the data is associated. |
| context | Specifies the context type to which the data belongs. |
Description
XDeleteContext deletes the entry for the given window and type from the context data structure defined in <X11/Xutil.h>. This function returns XCNOENT if the context could not be found, or 0 if it succeeds. XDeleteContext does not free the data whose address was saved.
See Volume One, Chapter 13, Other Programming Techniques, for a description of context management.
Structures
typedef int XContext;
Related Commands
XFindContext, XSaveContext, XUniqueContext.
XDeleteModifiermapEntry
Xlib - Resource Manager—
Name
XDeleteModifiermapEntry — delete an entry from an XModifierKeymap structure.
Synopsis
XModifierKeymap *XDeleteModifiermapEntry(modmap, keysym_entry, modifier) XModifierKeymap *modmap; KeyCode keysym_entry; int modifier;
Arguments
| modmap | Specifies a pointer to an XModifierKeymap structure. |
| keysym_entry | Specifies the KeyCode of the key to be deleted from modmap. |
| modifier | Specifies the modifier you no longer want mapped to the keycode specified in keysym_entry. This should be one of the constants: ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex. |
Description
XDeleteModifiermapEntry returns an XModifierKeymap structure suitable for calling XSetModifierMapping, in which the specified keycode is deleted from the set of keycodes that is mapped to the specified modifier (like Shift or Control). XDeleteModifiermapEntry does not change the mapping itself.
This function is normally used by calling XGetModifierMapping to get a pointer to the current XModifierKeymap structure for use as the modmap argument to XDeleteModifiermapEntry.
Note that the structure pointed to by modmap is freed by XDeleteModifiermapEntry. It should not be freed or otherwise used by applications.
For a description of the modifier map, see XSetModifierMapping.
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 Mod1MapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Related Commands
InsertModifiermapEntry, XGetModifierMapping, XSetModifierMapping, XNewModifiermap, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XRefreshKeyboardMapping, XLookupString.
XDeleteProperty
Xlib - Properties—
Name
XDeleteProperty — delete a window property.
Synopsis
XDeleteProperty (display, w, property) Display *display; Window w; Atom property;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose property you want to delete. |
| property | Specifies the atom of the property to be deleted. |
Description
XDeleteProperty deletes a window property, so that it no longer contains any data. Its atom, specified by property, still exists after the call so that it can be used again later by any application that knows the ID of the window the property is defined on. If the property was defined on the specified window, XDeleteProperty generates a PropertyNotify event.
See the introduction to properties in Volume One, Chapter 2, X Concepts, or more detailed information in Volume One, Chapter 10, Interclient Communication.
Errors
BadAtom
BadWindow
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName, XInternAtom.
XDestroyAssocTable
—Xlib - Association Tables
Name
XDestroyAssocTable — free the memory allocated for an association table.
Synopsis
XDestroyAssocTable(table) XAssocTable *table;
Arguments
| table | Specifies the association table whose memory is to be freed. |
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
Using an XAssocTable after it has been destroyed will have unpredictable and probably disastrous consequences.
For more information on association tables, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
XAssoc *buckets; /* pointer to first bucket in array */
int size; /* table size (number of buckets) */
}XAssocTable;
Related Commands
XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc.
XDestroyImage
Xlib - Images—
Name
XDestroyImage — deallocate memory associated with an image.
Synopsis
int XDestroyImage(ximage) XImage *ximage;
Arguments
| ximage | Specifies a pointer to the image. |
Description
XDestroyImage deallocates the memory associated with an XImage structure. This memory includes both the memory holding the XImage structure, and the memory holding the actual image data.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XPutImage, XGetImage, XCreateImage, XSubImage, XGetSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XDestroyRegion
—Xlib - Regions
Name
XDestroyRegion — deallocate storage associated with a region.
Synopsis
XDestroyRegion(r) Region r;
Arguments
| r | Specifies the region to be destroyed. |
Description
XDestroyRegion frees the memory associated with a region.
See Volume One, Chapter 6, Drawing Graphics and Text, for a description of regions.
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XEqualRegion, XClipBox.
XDestroySubwindows
Xlib - Window Existence—
Name
XDestroySubwindows — destroy all subwindows of a window.
Synopsis
XDestroySubwindows (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose subwindows are to be destroyed. |
Description
This function destroys all descendants of the specified window, in bottom to top stacking order.
XDestroySubwindows generates exposure events on window w, if any mapped subwindows were actually destroyed. This is much more efficient than deleting many subwindows one at a time, since much of the work need only be performed once for all of the windows rather than for each window. It also saves multiple exposure events on the windows about to be destroyed. The subwindows should never again be referenced.
XCloseDisplay automatically destroys all windows that have been created by that client on the specified display (unless called after a fork system call).
Errors
BadWindow
Related Commands
XCreateSimpleWindow, XCreateWindow, XDestroyWindow.
XDestroyWindow
—Xlib - Window Existence
Name
XDestroyWindow — unmap and destroy a window and all subwindows.
Synopsis
XDestroyWindow (display, window) Display *display; Window window;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| window | Specifies the ID of the window to be destroyed. |
Description
If window is mapped, an UnmapWindow request is performed automatically. The window and all inferiors are then destroyed, and a DestroyNotify event is generated for each window. The ordering of the DestroyNotify events is such that for any given window, DestroyNotify is generated on all inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained.
The windows should never again be referenced.
Destroying a mapped window will generate exposure events on other windows that were obscured by the windows being destroyed. XDestroyWindow may also generate EnterWindow events if window was mapped and contained the pointer.
No windows are destroyed if you try to destroy the root window.
Errors
BadWindow
Related Commands
XCreateSimpleWindow, XCreateWindow, XDestroySubwindows.
XDisableAccessControl
Xlib - Host Access—
Name
XDisableAccessControl — allow access from any host.
Synopsis
XDisableAccessControl (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XDisableAccessControl instructs the server to allow access from clients on any host. This overrides the host access list.
This routine can only be called from a client running on the same host as the server.
For more information on access control, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadAccess
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XEnableAccessControl, XSetAccessControl.
XDisplayName
—Xlib - Error Handling
Name
XDisplayName — report the display name when connection to a display fails.
Synopsis
char *XDisplayName (string) char *string;
Arguments
| string | Specifies the character string. |
Description
XDisplayName is normally used to report the name of the display the program attempted to open with OpenDisplay. This is necessary because X error handling begins only after the connection to the server succeeds. If a NULL string is specified, XDisplayName looks in the environment for the display and returns the display name that the user was requesting. Otherwise, XDisplayName returns its own argument. This makes it easier to report to the user precisely which display the program attempted to open.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XGetErrorDatabaseText, XGetErrorText, XSetErrorHandler, XSetIOErrorHandler, XSynchronize, XSetAfterFunction.
XDraw
Xlib - Drawing Primitives—
Name
XDraw — draw a polyline or curve between vertex list (from X10).
Synopsis
Status XDraw (display, drawable, gc, vlist, vcount) Display *display; Drawable drawable; GC gc; Vertex *vlist; int vcount;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| vlist | Specifies a pointer to the list of vertices that indicates what to draw. |
| vcount | Specifies how many vertices are in vlist. |
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
XDraw achieves the effects of the X10 XDraw, XDrawDashed, and XDrawPatterned functions.
XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of vertices (vlist). The points are connected by lines as specified in the flags each the Vertex structure.
The Vertex structure contains an x,y coordinate and a bitmask called flags that specifies the drawing parameters.
The x and y elements of Vertex are the coordinates of the vertex that are relative to either the previous vertex (if VertexRelative is 1) or the upper-left inside corner of the drawable (if VertexRelative is 0). If VertexRelative is 0 the coordinates are said to be absolute. The first vertex must be an absolute vertex.
If the VertexDontDraw bit is 1, no line or curve is drawn from the previous vertex to this one. This is analogous to picking up the pen and moving to another place before drawing another line.
If the VertexCurved bit is 1, a spline algorithm is used to draw a smooth curve from the previous vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the previous vertex to this one. It makes sense to set VertexCurved to 1 only if a previous and next vertex are both defined (either explicitly in the array, or through the definition of a closed curve—see below.)
It is permissible for VertexDontDraw bits and VertexCurved bits to both be 1. This is useful if you want to define the previous point for the smooth curve, but you do not want an actual curve drawing to start until this point.
If VertexStartClosed bit is 1, then this point marks the beginning of a closed curve. This vertex must be followed later in the array by another vertex whose absolute coordinates are identical and which has VertexEndClosed bit of 1. The points in between form a cycle for the purpose of determining predecessor and successor vertices for the spline algorithm.
XDraw uses the following graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
A Status of 0 is returned on failure.
For more information, see Volume One, Appendix B, X10 Compatibility.
Structures
typedef struct _Vertex {
short x,y;
unsigned short flags;
} Vertex;
/* defined constants for use as flags */
#define VertexRelative 0x0001 /* else absolute */
#define VertexDontDraw 0x0002 /* else draw */
#define VertexCurved 0x0004 /* else straight */
#define VertexStartClosed 0x0008 /* else not */
#define VertexEndClosed 0x0010 /* else not */
Related Commands
XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawArc
Xlib - Drawing Primitives—
Name
XDrawArc — draw an arc fitting inside a rectangle.
Synopsis
XDrawArc (display, drawable, gc, x, y, width, height, angle1, angle2) Display *display; Drawable drawable; GC gc; int x, y; unsigned int width, height; int angle1, angle2;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle that contains the arc, relative to the origin of the specified drawable. |
| width
height |
Specify the width and height in pixels of the major and minor axes of the arc. |
| angle1 | Specifies the start of the arc relative to the three-o'clock position from the center. Angles are specified in 64ths of a degree, (360 * 64 is a complete circle). |
| angle2 | Specifies the path and extent of the arc relative to the start of the arc. Angles are specified in 64ths of a degree, (360 * 64 is a complete circle). |
Description
XDrawArc draws a circular or elliptical arc. An arc is specified by a rectangle and two angles. The x and y coordinates are relative to the origin of the drawable, and define the upper-left corner of the rectangle. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height, respectively. The angles are signed integers in 64ths of a degree, with positive values indicating counter-clockwise motion and negative values indicating clockwise motion, truncated to a maximum of 360 degrees. The start of the arc is specified by angle1 relative to the three-o'clock position from the center, and the path and extent of the arc is specified by angle2 relative to the start of the arc.
By specifying one axis to be 0, a horizontal or vertical line can be drawn.
Angles are computed based solely on the coordinate system and ignore the aspect ratio. In other words, if the bounding rectangle of the arc is not square and angle1 is 0 and angle2 is (45×64), a point drawn from the center of the bounding box through the endpoint of the arc will not pass through the corner of the rectangle.
XDrawArc uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list. XDrawArc is not affected by the tile or stipple in the GC.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawArcs
—Xlib - Drawing Primitives
Name
XDrawArcs — draw multiple arcs.
Synopsis
XDrawArcs (display, drawable, gc, arcs, narcs) Display *display; Drawable drawable; GC gc; XArc *arcs; int narcs;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| arcs | Specifies a pointer to an array of arcs. |
| narcs | Specifies the number of arcs in the array. |
Description
This is the plural version of XDrawArc. See XDrawArc for details of drawing a single arc.
The arcs are drawn in the order listed in the arcs array. For any given arc, no pixel is drawn more than once. If arcs intersect, pixels will be drawn multiple times. If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly according to the GC. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly according to the join_style specified in the GC. By specifying one axis to be 0, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system, ignoring the aspect ratio.
By specifying one axis to be 0, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio.
For any given arc, no pixel is drawn more than once. If two arcs join correctly and if line_width is greater than 0 and the arcs intersect, no pixel is drawn more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins.
If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly.
XDrawArcs uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list. XDrawArcs is not affected by the tile or stipple in the GC.
The following is a technical explanation of the points drawn by XDrawArcs. For an arc specified as [x, y, width, height, angle1, angle2], the origin of the major and minor axes is at [x+ (width/2), y+(height/2) ], and the infinitely thin path describing the entire circle or ellipse intersects the horizontal axis at [x, y+(height/2)] and [x+width, y+(height/2)] and intersects the vertical axis at [x+(width/2), y] and [x+(width/2), y+height]. These coordinates can be fractional. That is, they are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line width line_width, the bounding outlines for filling are given by the infinitely thin paths describing the arcs:
[x+dx/2, y+dy/2, width-dx, height-dy, angle1, angle2]
and
[x-line_width/2, y-line_width/2, width+line_width, height+line_width, angle1, angle2]
where
dx=min(line_width,width) dy=min(line_width,height)
If (height != width) the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows:
skewed-angle = atan(tan(normal-angle) * width/height) + adjust
The skewed-angle and normal-angle are expressed in radians (rather than in 64ths of a degree) in the range [0,2*PI], and where atan returns a value in the range [-PI/2, PI/2], and where adjust is:
0 for normal-angle in the range [0,PI/2] PI for normal-angle in the range [PI/2,(3*PI)/2] 2*PI for normal-angle in the range [(3*PI)/2,2*PI]
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short x, y;
unsigned short width, height;
short angle1, angle2; /* Degrees *64 */
} XArc;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawFilled
Xlib - Drawing Primitives—
Name
XDrawFilled — draw a filled polygon or curve from vertex list (from X10).
Synopsis
Status XDrawFilled (display, drawable, gc, vlist, vcount) Display *display; Drawable drawable; GC gc; Vertex *vlist; int vcount;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| vlist | Specifies a pointer to the list of vertices. |
| vcount | Specifies how many vertices are in vlist. |
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX. XDrawFilled achieves the effects of the X Version 10 XDrawTiled and XDrawFilled functions.
XDrawFilled draws arbitrary polygons or curves, according to the same rules as XDraw, and then fills them.
XDrawFilled uses the following graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, dash_list, fill_style and fill_rule.
XDrawFilled returns a Status of 0 on failure.
For more information, see Volume One, Appendix B, X10 Compatibility.
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawImageString
—Xlib - Text
Name
XDrawImageString — draw 8-bit image text characters.
Synopsis
XDrawImageString (display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x, y; char *string; int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the image text character, relative to the origin of the specified drawable. |
| string | Specifies the character string. |
| length | Specifies the number of characters in the string argument. |
Description
XDrawImageString draws a string, but unlike XDrawString it can draw both the foreground and the background of the characters, if the GC is set accordingly.
XDrawImageString uses these graphics context components: plane_mask, foreground, background, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The function and fill_style defined in gc are ignored; the effective function is GXcopy and the effective fill_style is FillSolid.
XDrawImageString first fills a destination rectangle with the background pixel defined in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled rectangle is at [x, y - font_ascent], the width is overall->width and the height is Xascent + descent.
The overall->width, ascent, and descent are as would be returned by XQueryTextExtents using gc and string.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XDrawImageString16
—Xlib - Text
Name
XDrawImageString16 — draw 16-bit image text characters.
Synopsis
XDrawImageString16 (display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x, y; XChar2b *string; int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the image text character, relative to the origin of the specified drawable. |
| string | Specifies the character string. |
| length | Specifies the number of characters in the string argument. |
Description
XDrawImageString16 draws a string, but unlike XDrawString16 it can draw both the foreground and the background of the characters, if the GC is set accordingly.
XDrawImageString16 uses these graphics context components: plane_mask, foreground, background, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The function and fill_style defined in gc are ignored; the effective function is GXcopy and the effective fill_style is FillSolid.
XDrawImageString16 first fills a destination rectangle with the background pixel defined in gc, and then paints the text with the foreground pixel. The upper-left corner of the filled rectangle is at [x, y - font_ascent], the width is overall->width and the height is ascent + descent.
The overall->width, ascent, and descent are as would be returned by XQueryTextExtents16 using gc and string.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
unsigned char byte1;
unsigned char byte2;
} XChar2b;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XDrawLine
—Xlib - Drawing Primitives
Name
XDrawLine — draw a line between two points.
Synopsis
XDrawLine (display, drawable, gc, x1, y1, x2, y2) Display *display; Drawable drawable; GC gc; int x1, y1, x2, y2;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x1
y1 |
Specify the coordinates of the endpoints of the line relative to the drawable origin. XLine connects point (x1, y1) to point (x2, y2). |
| x2
y2 |
Description
XDrawLine uses the components of the specified graphics context to draw a line between two points in the specified drawable. No pixel is drawn more than once.
XDrawLine uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawLine also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
XDrawLine is not affected by tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawLines
Xlib - Drawing Primitives—
Name
XDrawLines — draw multiple connected lines.
Synopsis
XDrawLines (display, drawable, gc, points, npoints, mode) Display *display; Drawable drawable; GC gc; XPoint *points; int npoints; int mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| points | Specifies a pointer to an array of points. |
| npoints | Specifies the number of points in the array. |
| mode | Specifies the coordinate mode. Pass either CoordModeOrigin or CoordModePrevious. |
Description
XDrawLines does the following:
- Draws lines connecting each point in the list (points array) to the next point in the list. The lines are drawn in the order listed in the points array. For any given line, no pixel is drawn more than once. If thin (zero line width) lines intersect, pixels will be drawn multiple times. If the first and last points coincide, the first and last lines will join correctly. If wide lines intersect, the intersecting pixels are drawn only once, as though the entire multiline request were a single filled shape.
- Uses the components of the specified graphics context to draw multiple connected lines in the specified drawable. Specifically, XDrawLines uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
The mode argument may have two values:
- CoordModeOrigin indicates that all points are relative to the drawable's origin.
- CoordModePrevious indicates that all points after the first are relative to the previous point. (The first point is always relative to the drawable's origin.)
XDrawLines is not affected by the tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
} XPoint;
Errors
BadDrawable
BadGC
BadMatch
BadValue
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawPoint
Xlib - Drawing Primitives—
Name
XDrawPoint — draw a point
Synopsis
XDrawPoint (display, drawable, gc, x, y) Display *display; Drawable drawable; GC gc; int x, y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the point, relative to the corner of the drawable. |
Description
XDrawPoint uses the foreground pixel and function components of the graphics context to draw a single point into the specified drawable. XDrawPoint uses these graphics context components: function, plane_mask, foreground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. Use XDrawPoints to draw multiple points.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawPoints
—Xlib - Drawing Primitives
Name
XDrawPoints — draw multiple points.
Synopsis
XDrawPoints (display, drawable, gc, points, npoints, mode) Display *display; Drawable drawable; GC gc; XPoint *points; int npoints; int mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| points | Specifies a pointer to an array of XPoint structures containing the positions of the points. |
| npoints | Specifies the number of points to be drawn. |
| mode | Specifies the coordinate mode. CoordModeOrigin treats all coordinates as relative to the origin, while CoordModePrevious treats all coordinates after the first as relative to the previous point, while the first is still relative to the origin. |
Description
XDrawPoints uses the foreground pixel and function components of the graphics context to draw one or more points into the specified drawable.
XDrawPoints uses these graphics context components: function, plane_mask, foreground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
} XPoint;
Errors
BadDrawable
BadGC
BadMatch
BadValue
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawRectangle
—Xlib - Drawing Primitives
Name
XDrawRectangle — draw an outline of a rectangle.
Synopsis
XDrawRectangle (display, drawable, gc, x, y, width, height) Display *display; Drawable drawable; GC gc; int x, y unsigned int width, height;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the drawable's origin. |
| width
height |
Specify the width and height in pixels. These dimensions define the outline of the rectangle. |
Description
XDrawRectangle draws the outline of the rectangle by using the x and y coordinates, width and height, and graphics context you specify. Specifically, XDrawRectangle uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
XDrawRectangle is not affected by the tile or stipple in the GC. For the specified rectangle, no pixel is drawn more than once.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text', and Chapter 5, The Graphics Context.
Structure
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawRectangles
—Xlib - Drawing Primitives
Name
XDrawRectangles — draw the outlines of multiple rectangles.
Synopsis
XDrawRectangles (display, drawable, gc, rectangles, nrectangles) Display *display; Drawable drawable; GC gc; XRectangle rectangles[]; int nrectangles;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| rectangles | Specifies a pointer to an array of rectangles containing position and size information. |
| nrectangles | Specifies the number of rectangles in the array. |
Description
XDrawRectangles draws the outlines of the specified rectangles by using the position and size values in the array of rectangles. The x and y coordinates of each rectangle are relative to the drawable's origin, and define the upper-left corner of the rectangle. This function uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawRectangles also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, pixels are drawn multiple times.
XDrawRectangles is not affected by tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
} XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawSegments
—Xlib - Drawing Primitives
Name
XDrawSegments — draw multiple disjoint lines.
Synopsis
XDrawSegments (display, drawable, gc, segments, nsegments) Display *display; Drawable drawable; GC gc; XSegment *segments; int nsegments;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| segments | Specifies a pointer to an array of line segments. |
| nsegments | Specifies the number of segments in the array. |
Description
XDrawSegments draws multiple line segments into the specified drawable. Each line is specified by a pair of points, so the line may be connected or disjoint.
For each segment, XDrawSegments draws a line between (x1, y1) and (x2, y2). The lines are drawn in the order listed in segments. For any given line, no pixel is drawn more than once. If lines intersect, pixels will be drawn multiple times. The lines will be drawn separately, without regard to the join_style.
XDrawSegments uses these graphics context components: function, plane_mask, line_width, line_style, cap_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. XDrawSegments also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list.
XDrawSegments is not affected by the tile or stipple in the GC.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x1, y1, x2, y2;
} XSegment;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XDrawString
—Xlib - Text
Name
XDrawString — draw an 8-bit text string, foreground only.
Synopsis
XDrawString (display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x, y; char *string; int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the character, relative to the origin of the specified drawable. |
| string | Specifies the character string. |
| length | Specifies the number of characters in the string argument. |
Description
XDrawString draws the given string into a drawable using the foreground only to draw set bits in the font. It does not affect any other pixels in the bounding box for each character.
The y coordinate defines the baseline row of pixels while the x coordinate is the point for measuring the lbearing, rbearing, and width from.
XDrawString uses these graphics context components: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character image, as defined by the font in gc, is treated as an additional mask for a fill operation on the drawable.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XDrawString16
—Xlib - Text
Name
XDrawString16 — draw two-byte text strings.
Synopsis
XDrawString16 (display, drawable, gc, x, y, string, length) Display *display; Drawable drawable; GC gc; int x, y; XChar2b *string; int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the character, relative to the origin of the specified drawable. |
| string | Specifies the character string. Characters are two bytes wide. |
| length | Specifies the number of characters in the string argument. |
Description
XDrawString16 draws a string in the foreground pixel value without drawing the surrounding pixels.
The y coordinate defines the baseline row of pixels while the x coordinate is the point for measuring the lbearing, rbearing, and width from. For more information on text placement, see Volume One, Chapter 6, Drawing Graphics and Text.
XDrawString16 uses these graphics context components: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin. Each character image, as defined by the font in gc, is treated as an additional mask for a fill operation on the drawable.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
unsigned char byte1;
unsigned char byte2;
} XChar2b;
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XDrawText
—Xlib - Text
Name
XDrawText — draw 8-bit polytext strings.
Synopsis
XDrawText (display, drawable, gc, x, y, items, nitems) Display *display; Drawable drawable; GC gc; int x, y; XTextItem *items; int nitems;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the initial string, relative to the origin of the specified drawable. |
| items | Specifies a pointer to an array of text items. |
| nitems | Specifies the number of text items in the items array. |
Description
XDrawText is capable of drawing multiple strings and changing fonts between strings. Each XTextItem structure contains a string, the number of characters in the string, the delta offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each XTextItem is stored in the specified GC and used for subsequent text. If the XTextItem.font is None, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is permitted.
The delta in each XTextItem specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the draw direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8, the string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The delta for the second string begins at the rbearing of the last character in the first string. A negative delta would tend to overlay subsequent strings on the end of the previous string.
Only the pixels selected in the font are drawn (the background member of the GC is not used).
XDrawText uses the following elements in the specified GC: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
char *chars; /* pointer to string */
int nchars; /* number of characters */
int delta; /* delta between strings */
Font font; /* font to print it in, None don't change */
} XTextItem;
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XDrawText16
—Xlib - Text
Name
XDrawText16 — draw 16-bit polytext strings.
Synopsis
XDrawText16 (display, drawable, gc, x, y, items, nitems) Display *display; Drawable drawable; GC gc; int x, y; XTextItem16 *items; int nitems;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the baseline starting position for the initial string, relative to the origin of the specified drawable. |
| items | Specifies a pointer to an array of text items using two-byte characters. |
| nitems | Specifies the number of text items in the array. |
Description
XDrawText16 is capable of drawing multiple strings and changing fonts between strings. Each XTextItem structure contains a string, the number of characters in the string, the delta offset from the starting position for the string, and the font. Each text item is processed in turn. The font in each XTextItem is stored in the specified GC and used for subsequent text. If the XTextItem16.font is None, the font in the GC is used for drawing and is not changed. Switching between fonts with different drawing directions is permitted.
The delta in each XTextItem specifies the change in horizontal position before the string is drawn. The delta is always added to the character origin and is not dependent on the drawing direction of the font. For example, if x = 40, y = 20, and items [0] .delta = 8, the string specified by items [0] .chars would be drawn starting at x = 48, y = 20. The delta for the second string begins at the rbearing of the last character in the first string. A negative delta would tend to overlay subsequent strings on the end of the previous string.
Only the pixels selected in the font are drawn (the background member of the GC is not used).
XDrawText16 uses the following elements in the specified GC: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin.
Note that the chars member of the XTextItem16 structure is of type XChar2b, rather than of type char as it is in the XTextItem structure. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server will interpret each member of the XChar2b structure as a 16-bit number that has been transmitted most significant byte first. In other words, the byte1 member of the XChar2b structure is taken as the most significant byte.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
XChar2b *chars; /* 2 byte characters */
int nchars; /* number of characters */
int delta; /* delta between strings */
Font font; /* font to print it in, None don't change */
} XTextItem16;
typedef struct { /* normal 16 bit characters are two bytes */
unsigned char byte1;
unsigned char byte2;
} XChar2b;
Errors
BadDrawable
BadFont
BadGC
BadMatch
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XEmptyRegion
—Xlib - Regions
Name
XEmptyRegion — determine if a region is empty.
Synopsis
int XEmptyRegion (r) Region r;
Arguments
| r | Specifies the region to be checked. |
Description
XEmptyRegion will return True if the specified region is empty.
Structures
/* * opaque reference to Region data type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XEnableAccessControl
Xlib - Host Access—
Name
XEnableAccessControl — use access control list to allow or deny connection requests.
Synopsis
XEnableAccessControl (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XEnableAccessControl instructs the server to use the host access list to determine whether access should be granted to clients seeking a connection with the server.
By default, the host access list is used. If access has not been disabled with XDisableAccessControl or XSetAccessControl, this routine does nothing.
This routine can only be called by clients running on the same host as the server.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccessControl, XSetAccessControl.
XEqualRegion
—Xlib - Regions
Name
XEqualRegion — determine if two regions have the same size, offset, and shape.
Synopsis
int XEqualRegion(rl, r2) Region r1, r2;
Arguments
| r1 | Specify the two regions you want to compare. |
| r2 |
Description
XEqualRegion returns True if the two regions are identical; i.e., they have the same offset, size and shape.
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, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XClipBox.
XEventsQueued
Xlib - Resource Manager—
Name
XEventsQueued — check the number of events in the event queue.
Synopsis
int XEventsQueued (display, mode) Display *display; int mode;
Arguments
| display | Specifies a pointer to the Display structure, returned from XOpenDisplay. |
| mode | Specifies whether the output buffer is flushed if there are no events in Xlib's queue. You can specify one of these constants: QueuedAlready, QueuedAfterFlush, QueuedAfterReading. |
Description
XEventsQueued checks whether events are queued. If there are events in Xlib's queue, the routine returns immediately to the calling routine. Its return value is the number of events regardless of mode.
mode specifies what happens if no events are found on Xlib's queue.
- If mode is QueuedAlready, and there are no events in the queue, XEventsQueued returns 0 (it does not flush the output buffer or attempt to read more events from the connection).
- If mode is QueuedAfterFlush, and there are no events in the queue, XEventsQueued flushes the output buffer, attempts to read more events out of the application's connection, and returns the number read.
- If mode is QueuedAfterReading, and there are no events in the queue, XEventsQueued attempts to read more events out of the application's connection without flushing the output buffer and returns the number read.
Note that XEventsQueued always returns immediately without I/O if there are events already in the queue.
XEventsQueued with mode QueuedAfterFlush is identical in behavior to XPending. XEventsQueued with mode QueuedAlready is identical to the QLength macro (see Appendix C, Macros).
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XSynchronize, XSendEvent, QLength, XPending.
XFetchBufFer
—Xlib - Cut Buffers
Name
XFetchBuffer — return data from a cut buffer.
Synopsis
char *XFetchBuffer (display, nbytes, buffer) Display *display; int *nbytes; /* RETURN */ int buffer;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| nbytes | Returns the number of bytes in buffer returned by XFetchBuffer. If there is no data in the buffer, nbytes is set to 0. |
| buffer | Specifies which buffer you want data from. Specify an integer from 0 to 7. |
Description
XFetchBuffer returns data from one of the 8 buffers provided for interclient communication. If the buffer contains data, XFetchBuffer returns the number of bytes in nbytes, otherwise it returns NULL and sets nbytes to 0. The appropriate amount of storage is allocated and the pointer returned; the client must free this storage when finished with it. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte.
Selections are the preferred communication scheme.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadValue
Related Commands
XStoreBuffer, XStoreBytes, XFetchBytes, XRotateBuffers.
XFetchBytes
Xlib - Cut Buffers—
Name
XFetchBytes — return data from cut buffer 0.
Synopsis
char *XFetchBytes (display, nbytes) Display *display; int *nbytes; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| nbytes | Returns the number of bytes in the string returned by XFetchBytes. If there is no data in the buffer, nbytes is set to 0. |
Description
XFetchBytes returns data from cut buffer 0 of the 8 buffers provided for interclient communication. If the buffer contains data, XFetchBytes returns the number of bytes in nbytes, otherwise it returns NULL and sets nbytes to 0. The appropriate amount of storage is allocated and the pointer returned; the client must free this storage when finished with it by calling XFree. Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte.
Use XFetchBuffer to fetch data from any specified cut buffer.
Selections are the preferred communication method.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XStoreBuffer, XStoreBytes, XFetchBuffer, XRotateBuffers.
XFetchName
—Xlib - Window Manager Hints
Name
XFetchName — get a window's name (XA_WM_NAME property).
Synopsis
Status XFetchName (display, w, window_name) Display *display; Window w; char **window_name; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose name you want a pointer set to. |
| window_name | Returns a pointer to the window name, which will be a null-terminated string. If the XA_WM_NAME property has not been set for this window, XFetchName sets windowname to NULL. When finished with it, a client must free the name string using XFree. |
Description
XFetchName returns the current value of the XA_WM_NAME property for the specified window. XFetchName return value is nonzero if it succeeds, and 0 if the property has not been set for the argument window.
For more information, see Volume One: Chapter 10, Interclient Communication; and Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XFillArc
Xlib - Drawing Primitives—
Name
XFillArc — fill an arc.
Synopsis
XFillArc (display, drawable, gc, x, y, width, height, angle1, angle2) Display *display; Drawable drawable; GC gc; int x, y; unsigned int width, height; int angle1, angle2;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the bounding box containing the arc, relative to the origin of the drawable. |
| width height | Specify the width and height in pixels. These are the major and minor axes of the arc. |
| angle1 | Specifies the start of the arc relative to the three-o'clock position from the center. Angles are specified in degrees, multiplied by 64. |
| angle2 | Specifies the path and extent of the arc relative to the start of the arc. Angles are specified in degrees, multiplied by 64. |
Description
XFillArc fills an arc according to the arc_mode in the GC. The x, y, width, and height arguments specify the bounding box for the arc. See XDrawArc for the description of how this bounding box is used to compute the arc. Some, but not all, of the pixels drawn with XDrawArc will be drawn by XFillArc with the same arguments.
The arc forms one boundary of the area to be filled. The other boundary is determined by the arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used.
XFillArc uses these graphics context components: function, plane_mask, fill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XFillArcs
Xlib - Drawing Primitives—
Name
XFillArcs — fill multiple arcs.
Synopsis
XFillArcs (display, drawable, gc, arcs, narcs) Display *display; Drawable drawable; GC gc; XArc *arcs; int narcs;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| arcs | Specifies a pointer to an array of arc definitions. |
| narcs | Specifies the number of arcs in the array. |
Description
For each arc, XFillArcs fills the region closed by the specified arc and one or two line segments, depending on the arc_mode specified in the GC. It does not draw the complete outlines of the arcs, but some pixels may overlap.
The arc forms one boundary of the area to be filled. The other boundary is determined by the arc_mode in the GC. If the arc_mode in the GC is ArcChord, the single line segment joining the endpoints of the arc is used. If ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. The arcs are filled in the order listed in the array. For any given arc, no pixel is drawn more than once. If regions intersect, pixels will be drawn multiple times.
XFillArcs use these graphics context components: function, plane_mask, fill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
short angle1, angle2; /* Degrees * 64 */
} XArc;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XFillPolygon
Xlib - Drawing Primitives—
Name
XFillPolygon — fill a polygon.
Synopsis
XFillPolygon (display, drawable, gc, points, npoints, shape, mode) Display *display; Drawable drawable; GC gc; XPoint *points; int npoints; int shape; int mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| points | Specifies a pointer to an array of points. |
| npoints | Specifies the number of points in the array. |
| shape | Specifies an argument that helps the server to improve performance. Pass the last constant in this list that is valid for the polygon to be filled: Complex, Nonconvex, or Convex. |
| mode | Specifies the coordinate mode. Pass either CoordModeOrigin or CoordModePrevious. |
Description
XFillPolygon fills the region closed by the specified path. Some but not all of the path itself will be drawn. The path is closed automatically if the last point in the list does not coincide with the first point. No pixel of the region is drawn more than once.
The mode argument affects the interpretation of the points that define the polygon:
- CoordModeOrigin indicates that all points are relative to the drawable's origin.
- CoordModePrevious indicates that all points after the first are relative to the previous point. (The first point is always relative to the drawable's origin.)
The shape argument allows the fill routine to optimize its performance given tips on the configuration of the area.
- Complex indicates the path may self-intersect. The fill_rule of the GC must be consulted to determine which areas are filled. See Volume One, Chapter 5, The Graphics Context, for a discussion of the fill rules EvenOddRule and WindingRule.
- Nonconvex indicates the path does not self-intersect, but the shape is not wholly convex. If known by the client, specifying Nonconvex instead of Complex may improve performance. If you specify Nonconvex for a self-intersecting path, the graphics results are undefined.
- Convex indicates the path is wholly convex. This can improve performance even more, but if the path is not convex, the graphics results are undefined.
XFillPolygon uses these graphics context components when filling the polygon area: function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these mode-dependent components of the GC: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
} XPoint;
Errors
BadDrawable
BadGC
BadMatch
BadValue
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XFillRectangle
Xlib - Drawing Primitives—
Name
XFillRectangle — fill a rectangular area.
Synopsis
XFillRectangle (display, drawable, gc, x, y, width, height) Display *display; Drawable drawable; GC gc; int x, y; unsigned int width, height;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. |
| width height | Specify the dimensions in pixels of the rectangle to be filled. |
Description
XFillRectangle fills the rectangular area in the specified drawable using the x and y coordinates, width and height dimensions, and graphics context you specify. XFillRectangle draws some but not all of the path drawn by XDrawRectangle with the same arguments.
XFillRectangle uses these graphics context components: function, plane_mask, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context components depending on the fill_style: foreground, background tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangles, XClearArea, XClearWindow.
XFillRectangles
Xlib - Drawing Primitives—
Name
XFillRectangles — fill multiple rectangular areas.
Synopsis
XFillRectangles (display, drawable, gc, rectangles, nrectangles) Display *display; Drawable drawable; GC gc; XRectangle *rectangles; int nrectangles;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| gc | Specifies the graphics context. |
| rectangles | Specifies a pointer to an array of rectangles. |
| nrectangles | Specifies the number of rectangles in the array. |
Description
XFillRectangles fills multiple rectangular areas in the specified drawable using the graphics context.
The x and y coordinates of each rectangle are relative to the drawable's origin, and define the upper left corner of the rectangle. The rectangles are drawn in the order listed. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, the intersecting pixels will be drawn multiple times.
XFillRectangles uses these graphics context components: function, plane_mask, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context components depending on the fill_style: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin.
For more information, see Volume One: Chapter 6, Drawing Graphics and Text; and Chapter 5, The Graphics Context.
Structures
typedef struct {
short x, y;
unsigned short width, height;
unsigned short width, height;
} XRectangle;
Errors
BadDrawable
BadGC
BadMatch
Related Commands
XDraw, XDrawArc, XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, XDrawRectangles, XDrawSegments, XCopyArea, XCopyPlane, XFillArc, XFillArcs, XFillPolygon, XFillRectangle, XFillRectangles, XClearArea, XClearWindow.
XFindContext
Xlib - Context Manager—
Name
XFindContext — get data from the context manager (not graphics context).
Synopsis
int XFindContext (display, w, context, data) Display *display; Window w; XContext context; caddr_t *data; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window with which the data is associated. |
| context | Specifies the context type to which the data corresponds. |
| data | Returns the data. |
Description
XFindContext gets data that has been assigned to the specified window and context ID. The context manager is used to associate data with windows for use within an application.
This application should have called XUniqueContext to get a unique ID, and then XSaveContext to save the data into the array. The meaning of the data is indicated by the context ID, but is completely up to the client.
XFindContext returns XCNOENT (a nonzero error code) if the context could not be found and zero (0) otherwise.
For more information on the context manager, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef int XContext
Related Commands
XDeleteContext, XSaveContext, XUniqueContext.
XFlush
—Xlib - Output Buffer
Name
XFlush — flush the output buffer (display all queued requests).
Synopsis
XFlush (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XFlush sends to the display (“flushes”) all output requests that have been buffered but not yet sent.
Flushing is done automatically when input is read if no matching events are in Xlib's queue (with XPending, XNextEvent, or XWindowEvent), or when a call is made that gets information from the server (such as XQueryPointer, XGetFontInfo) so XFlush is seldom needed. It is used when the buffer must be flushed before any of these calls are reached.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 3, Basic Window Program.
Related Commands
XSync
XForceScreenSaver
Xlib - Screen Saver—
Name
XForceScreenSaver — turn the screen saver on or off.
Synopsis
XForceScreenSaver (display, mode) Display *display; int mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| mode | Specifies whether the screen saver is active or reset. The possible modes are: ScreenSaverActive or ScreenSaverReset. |
Description
XForceScreenSaver resets or activates the screen saver.
If the specified mode is ScreenSaverActive and the screen saver currently is disabled, the screen saver is activated, even if the screen saver had been disabled by calling XSetScreenSaver with a timeout of zero (0). This means that the screen may go blank or have some random change take place to save the phosphors.
If the specified mode is ScreenSaverReset and the screen saver currently is enabled, the screen is returned to normal, the screen saver is deactivated and the activation timer is reset to its initial state (as if device input had been received). Expose events may be generated on all visible windows if the server cannot save the entire screen contents.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadValue
Related Commands
XActivateScreenSaver, XResetScreenSaver, XGetScreenSaver, XSetScreenSaver.
XFree
—Xlib - HouseKeeping
Name
XFree — free specified in-memory data created by an Xlib function.
Synopsis
XFree (data) caddr_t data;
Arguments
| data | Specifies a pointer to the data that is to be freed. |
Description
XFree is a general purpose routine for freeing data allocated by Xlib calls.
Related Commands
XOpenDisplay, XCloseDisplay, XNoOp, DefaultScreen.
XFreeColormap
Xlib - Colormaps—
Name
XFreeColormap — delete a colormap and install the default colormap.
Synopsis
XFreeColormap (display, cmap) Display *display; Colormap cmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap to delete. |
Description
XFreeColormap destroys the specified colormap, unless it is the default colormap for a screen. That is, it not only uninstalls cmap from the hardware colormap if it is installed, but also frees the associated memory including the colormap ID.
XFreeColormap performs the following processing:
- If cmap is an installed map for a screen, it uninstalls the colormap and installs the default if not already installed.
- If cmap is defined as the colormap attribute for a window (by XCreateWindow or XChangeWindowAttributes), it changes the colormap associated with the window to the constant None, generates a ColormapNotify event, and frees the colormap. The colors displayed with a colormap of None are server-dependent, since the default colormap is normally used.
For more information, see Volume One, Chapter 7, Color.
Errors
BadColor
Related Commands
XCopyColormapAndFree, XCreateColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XFreeColors
—Xlib - Color Cells
Name
XFreeColors — free colormap cells or planes.
Synopsis
XFreeColors (display, cmap, pixels, npixels, planes) Display *display; Colormap cmap; unsigned long pixels[]; int npixels; unsigned long planes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap. |
| pixels | Specifies an array of pixel values. These pixel values map to the cells in the specified colormap. |
| npixels | Specifies the number of pixels. |
| planes | Specifies the planes you want to free. |
Description
XFreeColors frees the cells whose values are computed by ORing together subsets of the planes argument with each pixel value in the pixels array.
If the cells are read/write, they become available for reuse, unless they were allocated with XAllocColorPlanes, in which case all the related pixels may need to be freed before any become available.
If the cells were read-only, they become available only if this is the last client to have allocated those shared cells.
For more information, see Volume One, Chapter 7, Color.
Errors
| BadAccess | A colorcell allocated by client (either unallocated or allocated by another client). |
| BadColor | |
| BadValue | A pixel value is not a valid index into cmap. |
Note: if more than one pixel value is in error, the one reported is arbitrary.
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XStoreNamedColor, BlackPixel, WhitePixel.
XFreeCursor
Xlib - Cursors—
Name
XFreeCursor — destroy a cursor.
Synopsis
XFreeCursor (display, cursor) Display *display; Cursor cursor;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cursor | Specifies the ID of the cursor to be affected. |
Description
XFreeCursor deletes the association between the cursor ID and the specified cursor. The cursor storage is freed when all other clients have freed it. Windows with their cursor attribute set to this cursor will be changed to None (which implies CopyFromParent). The specified cursor ID should not be referred to again.
Errors
BadCursor
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XRecolorCursor, XQueryBestCursor, XQueryBestSize.
XFreeExtensionList
—Xlib - Extensions
Name
XFreeExtensionList — free memory allocated for a list of installed extensions to X.
Synopsis
XFreeExtensionList (list) char **list;
Arguments
| list | Specifies a pointer to the list of extensions returned from XListExtensions. |
Description
XFreeExtensionList frees the memory allocated by XListExtensions.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XListExtensions, XQueryExtension.
XFreeFont
Xlib - Fonts—
Name
XFreeFont — unload a font and free storage for the font structure.
Synopsis
XFreeFont (display, font_struct) Display *display; XFontStruct *font_struct;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| font_struct | Specifies the storage associated with the font. |
Description
XFreeFont frees the memory allocated for the font_struct font information structure (XFontStruct) filled by XQueryFont or XLoadQueryFont. XFreeFont frees all storage associated with the font_struct argument. Neither the data nor the font should be referenced again.
The font itself is unloaded if no other client has loaded it.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* Font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* 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;
Errors
BadFont
Related Commands
XLoadFont, XLoadQueryFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XFreeFontInfo
—Xlib - Fonts
Name
XFreeFontInfo — free multiple font information arrays.
Synopsis
XFreeFontInfo (names, info, actual_count) char **names; XFontStruct *info; int actual_count;
Arguments
| names | Specifies a pointer to the list of font names that were returned by XListFontsWithInfo. |
| info | Specifies a pointer to the list of font information that was returned by XListFontWithInfo. |
| actual_count | Specifies the number of matched font names returned by XListFontwithInfo. |
Description
XFreeFontInfo frees the list of font information structures allocated by XListFontsWithInfo. It does not unload the specified fonts themselves.
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_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XListFonts, XListFontsWithInfo, XFreeFontNames, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XFreeFontNames
Xlib - Fonts—
Name
XFreeFontNames — free the font name array.
Synopsis
XFreeFontNames (list) char *list [ ] ;
Arguments
| list | Specifies the array of font name strings to be freed. |
Description
XFreeFontNames frees the array of strings returned by XListFonts.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XFreeFontPath
—Xlib - Fonts
Name
XFreeFontPath — free the memory allocated by XGetFontPath.
Synopsis
XFreeFontPath (list) char **list;
Arguments
| list | Specifies an array of strings allocated by XGetFontPath. |
Description
XFreeFontPath frees the data used by the array of pathnames returned by XGetFontPath.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XFreeGC
Xlib - Graphics Context—
Name
XFreeGC — free a graphics context.
Synopsis
XFreeGC (display, gc) Display *display; GC gc;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context to be freed. |
Description
XFreeGC frees all memory associated with a graphics context, and removes the GC from the server and display hardware.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XFreeModifiermap
—Xlib - Keyboard
Name
XFreeModifiermap — destroy and free a keyboard modifier mapping structure.
Synopsis
XFreeModifiermap(modmap) XModifierKeymap *modmap;
Arguments
| modmap | Specifies a pointer to the XModifierKeymap structure to be freed. |
Description
XFreeModifiermap frees the specified XModifierKeymap structure.
For more information, 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
* keycodes to be used as modifiers */
} XModifierKeymap;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XFreePixmap
Xlib - Pixmaps and Tiles—
Name
XFreePixmap — free a pixmap ID.
Synopsis
XFreePixmap (display, pixmap) Display *display; Pixmap pixmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| pixmap | Specifies the pixmap whose ID should be freed. |
Description
XFreePixmap disassociates a pixmap ID from its resource. If no other client has an ID for that resource, it is freed. The Pixmap should never be referenced again by this client. If it is, the ID will be unknown and a BadPixmap error will result.
Errors
BadPixmap
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XGContextFromGC
—Xlib - Graphics Context
Name
XGContextFromGC — obtain the GContext (resource ID) associated with the specified graphics context.
Synopsis
GContext XGContextFromGC(gc) GC gc;
Arguments
| gc | Specifies the graphics context of the desired resource ID. |
Description
XGContextFromGC extracts the resource ID from the GC structure. Using the gc argument, gc−>gid does the same thing, except that applications shouldn't reference members of the gc structure directly.
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XGeometry
Xlib - Standard Geometry—
Name
XGeometry — calculate window geometry given user geometry string and default geometry.
Synopsis
int XGeometry (display, screen, user_geom, default_geom, bwidth, fwidth, fheight, xadder, yadder, x, y, width, height) Display *display; int screen; char *user_geom, *default_geom; unsigned int bwidth; unsigned int fwidth, fheight; int xadder, yadder; int *x, *y, *width, *height;/* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| screen | Specifies which screen the window is on. |
| user_geom | Specifies the user or program supplied geometry string, perhaps incomplete. |
| default_geom | Specifies the default geometry string and must be complete. |
| bwidth | Specifies the border width. |
| fheight | Specify the font height and width in pixels (increment size). |
| fwidth | |
| xadder
yadder |
Specify additional interior padding in pixels needed in the window. |
| width
height |
Return the window dimensions in pixels. |
| x
y |
Return the user-specified or default coordinates of the window. |
Description
XGeometry returns the position and size of a window given a user-supplied geometry (allowed to be partial) and a default geometry. Each user-supplied specification is copied into the appropriate returned argument, unless it is not present, in which case the default specification is used. The default geometry should be complete while the user-supplied one may not be.
XGeometry is useful for processing command line options and user preferences. These geometry strings are of the form:
=<width>x<height>{+−}<xoffset>{+−)<yoffset>
The “=” at the beginning of the string is now optional. (Items enclosed in <> are integers, and items enclosed in {} are a set from which one item is to be chosen. Note that the brackets should not appear in the actual string.)
The XGeometry return value is a bitmask that indicates which values were present in user_geom. This bitmask is composed of the exclusive OR of the symbols XValue, YValue, WidthValue, HeightValue, XNegative, or YNegative.
If the function returns either XValue or YValue, you should place the window at the requested position. The border width (bwidth), size of the width and height increments (typically fwidth and fheight), and any additional interior space (xadder and yadder) are passed in to make it easy to compute the resulting size.
Related Commands
XParseGeometry, XTranslateCoordinates.
XGetAtomName
Xlib - Properties—
Name
XGetAtomName — get a name for a given atom.
Synopsis
char *XGetAtomName (display, atom) Display *display; Atom atom;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| atom | Specifies the atom whose string name you want returned. |
Description
An atom is a symbol (actually a number) identifying a property. XGetAtomName returns a string version of the atom name. If the specified atom is not defined, XGetAtomName returns NULL. XA_WM_CLASS (a symbol) is returned as “XA_WM_CLASS” (a string).
XInternAtom performs the inverse function. To free the resulting string, call XFree.
Errors
BadAtom
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XGetWindowProperty, XListProperties, XInternAtom.
XGetClassHint
—Xlib - Window Manager Hints
Name
XGetClassHint — get the XA_WM_CLASS property of a window.
Synopsis
Status XGetClassHint (display, w, class_hints) Display *display; Window w; XClassHint *class_hints; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which the property is desired. |
| class_hints | Returns the XClassHints structure. |
Description
XGetClassHint obtains the XA_WM_CLASS property for the specified window.
XGetClassHint returns a Status of 0 on failure, nonzero on success.
The XClassHint structure returned contains res_class, which is the name of the client such as “emacs”, and res_name, which is the first of the following that applies:
- command line option (–rn name)
- a specific environment variable (e.g., RESOURCE_NAME)
- the trailing component of argv [0] (after the last /)
To free res_name and res_class when finished with the strings, use XFree.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
char *res_name;
char *res_class;
} XClassHint;
Errors
BadWindow
Related Commands
XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetDefault
Xlib - User Preferences—
Name
XGetDefault — scan the user preferences for program name and options.
Synopsis
char *XGetDefault (display, program, option) Display *display; char *program; char *option;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| program | Specifies the program name to be looked for in the user's resource database. The program name is usually argv [0], the first argument on the UNIX command line. |
| option | Specifies the option name or keyword. Lines containing both the program name and the option name will be matched. |
Description
XGetDefault returns a character string containing the user's default value for the specified program name and option name. XGetDefault returns NULL if no key can be found that matches option and program. For a description of the matching rules, see XrmGetResource.
The strings returned by XGetDefault are owned by Xlib and should not be modified or freed by the client.
Lines in the user's resource database look like this:
xterm.foreground: #c0c0ff
xterm.geometry: =81x28
xterm.saveLines: 256
xterm.font: 8x13
xterm.keyMapFile: /usr/back/.keymap
xterm.activeIcon: on
xmh.header.font 9x15
The portion on the left is known as a key; the portion on the right is the value. Upper or lower case is important in keys. In some programs the standard is to capitalize only the second and successive words in each option, if any. In others, the first word is also capitalized.
Defaults are usually loaded into the XA_RESOURCE_MANAGER property on the root window at login. If no such property exists, a resource file in the user's home directory is loaded. On a UNIX system, this file is $HOME/.Xdefaults. After loading these defaults, XGetDefault merges additional defaults specified by the XENVIRONMENT environment variable. If XENVIRONMENT is defined, it contains a full path name for the additional resource file. If XENVIRONMENT is not defined, XGetDefault looks for $HOME/.Xdefaults-name, where name specifies the name of the machine on which the application is running.
The first invocation of XGetDefault reads the defaults into memory so that subsequent requests are fast. Therefore, changes to the defaults files from the program will not be felt until the next invocation.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands
XAutoRepeatOff, XAutoRepeatOn, XBell, XGetKeyboardControl, XChangeKeyboardControl, XGetPointerControl.
XGetErrorDatabaseText
Xlib - Error Handling—
Name
XGetErrorDatabaseText — obtain error messages from the error database.
Synopsis
XGetErrorDatabaseText (display, name, message, default_string, buffer, length) Display display; char *name, *message; char *default_string; char *buffer; /*RETURN */ int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| name | Specifies the name of the application. |
| message | Specifies the type of the error message. One of XProtoError, XlibMessage, or XRequestMajor (see Description below). |
| default_string | Specifies the default error message. |
| buffer | Returns the error description. |
| length | Specifies the size of the return buffer. |
Description
XGetErrorDatabaseText returns a message from the error message database. Given name and message as keys, XGetErrorDatabaseText uses the resource manager to look up a string and returns it in the buffer argument. Xlib uses this function internally to look up its error messages. On a UNIX system, the error message database is /usr/lib/XerrorDB.
The name argument should generally be the name of your application. The message argument should indicate which type of error message you want. Three predefined message types are used by Xlib to report errors:
- XProtoError
The protocol error number is used as a string for the message argument.
- XlibMessage
These are the message strings that are used internally by the library.
- XRequestMajor
The major request protocol number is used for the message argument.
If no string is found in the error database, XGetErrorDatabaseText returns the default_string that you specify to the buffer.
The string in buffer will be of length length.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName, XGetErrorText, XSetErrorHandler, XSetIOErrorHandler, XSynchronize, XSetAfterFunction.
XGetErrorText
Xlib - Error Handling—
Name
XGetErrorText — obtain a description of error code.
Synopsis
XGetErrorText (display, code, buffer, length) Display *display; int code; char *buffer; /* RETURN */ int length;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| code | Specifies the error code for which you want to obtain a description. |
| buffer | Returns a pointer to the error description text. |
| length | Specifies the size of the buffer. |
Description
XGetErrorText obtains textual descriptions of errors. XGetErrorText returns a pointer to a null-terminated string describing the specified error code with length length. This string is copied from static data and therefore may be freed. This routine allows extensions to the Xlib library to define their own error codes and error strings, which can be accessed easily.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName, XGetErrorDatabaseText, XSetErrorHandler, XSetIOErrorHandler, XSynchronize, XSetAfterFunction.
XGetFontPath
—Xlib - Fonts
Name
XGetFontPath — get the current font search path.
Synopsis
char **XGetFontPath (display, npaths) Display *display; int *npaths; /* RETURN number of elements */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| npaths | Returns the number of strings in the font path array. |
Description
XGetFontPath allocates and returns an array of strings containing the search path for fonts. The data in the font path should be freed when no longer needed.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XGetFontProperty
Xlib - Properties—
Name
XGetFontProperty — get a font property given its atom.
Synopsis
Bool XGetFontProperty (font_struct, atom, value) XFontStruct *font_struct; Atom atom; unsigned long *value; /* RETURN */
Arguments
| font_struct | Specifies the storage associated with the font. |
| atom | Specifies the atom associated with the property name you want returned. |
| value | Returns the value of the font property. |
Description
XGetFontProperty returns the value of the specified font property, given the atom for that property. The function returns 0 if the atom was not defined, or 1 if was defined.
There are a set of predefined atoms for font properties which can be found in <X11/Xatom.h>. These atoms are listed and described in Volume One, Chapter 6, Drawing Graphics and Text. This set contains the standard properties associated with a font. The predefined font properties are likely but not guaranteed to be present on any given server.
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_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XSetStandardProperties, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName, XInternAtom.
XGetGeometry
—Xlib - Window Attributes
Name
XGetGeometry — obtain the current geometry of drawable.
Synopsis
Status XGetGeometry (display, drawable, root, x, y, width, height, border_width, depth) Display *display; Drawable drawable; Window *root; /* RETURN */ int *x, *y; /* RETURN */ unsigned int *width, *height; /* RETURN */ unsigned int *border_width; /* RETURN */ unsigned int *depth; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable, either a window or a pixmap. |
| root | Returns the root window ID of the specified window. |
| x
y |
Return the coordinates of the upper-left pixel of the window's border, relative to its parent's origin. For pixmaps, these coordinates are always 0. |
| width height | Return the dimensions of the drawable. For a window, these return the inside size (not including the border). For a pixmap, they just return the size. |
| border_width | Returns the borderwidth, in pixels, of the window's border, if the drawable is a window. Returns 0 if the drawable is a pixmap. |
| depth | Returns the depth of the pixmap (bits per pixel for the object). The depth must be supported by the root of the specified drawable. |
Description
This, function gets complete information about the root window and the current geometry of a drawable.
XGetGeometry returns a Status of 0 on failure, or 1 on success.
Errors
BadDrawable
Related Commands
XGetWindowAttributes, XMoveWindow, XMoveResizeWindow, XResizeWindow, XConfigureWindow.
XGetIconName
Xlib - Window Manager Hints—
Name
XGetIconName — get the name to be displayed in an icon.
Synopsis
Status XGetIconName (display, w, icon_name) Display *display; Window w; char **icon_name; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose icon name you want to learn. |
| icon_name | Returns a pointer to the name to be displayed in the window's icon. The name should be a null-terminated string. If a name hasn't been assigned to the window, XGetIconName sets this argument to NULL. When finished with it, a client must free the icon name string using XFree. |
Description
XGetIconName reads the icon name property of a window. This function is primarily used by window managers to get the name to be written in that window's icon when they need to display that icon.
XGetIconName returns a nonzero Status if it succeeds, and 0 if no icon name has been set for the argument window.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetIconSizes
—Xlib - Window Manager Hints
Name
XGetIconSizes — get preferred icon sizes.
Synopsis
Status XGetIconSizes (display, w, size_list, count) Display *display; Window w; XIconSize **size_list; /* RETURN */ int *count; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID (usually of the root window). |
| size_list | Returns a pointer to the size list. |
| count | Returns the number of items in the size list. |
Description
XGetIconSizes reads the XA_WM_ICON_SIZE property that should be set by the window manager to specify its desired icon sizes. XGetIconSizes returns a Status of 0 if a window manager has not set icon sizes, and a nonzero Status otherwise. This function should be called by all programs to find out what icon sizes are preferred by the window manager. The application should then use XSetWMHints to supply the window manager with an icon pixmap or window in one of the supported sizes. To free the data allocated in size_list, use XFree.
For more information, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
/* width_inc and height_inc provide the preferred
* increment of sizes in the range from min_width
* to max_width and min_height to max_height. */
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XStoreName, XSetIconSizes, XSetCommand.
XGetImage
Xlib - Images—
Name
XGetImage — place contents of a rectangle from drawable into an image.
Synopsis
XImage *XGet Image (display, drawable, x, y, width, height, plane_mask, format) Display *display; Drawable drawable; int x, y; unsigned int width, height; unsigned long plane_mask; int format;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable to get the data from. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. |
| width height | Specify the width and height in pixels of the image. |
| plane_mask | Specifies a plane mask that indicates which planes are represented in the image. |
| format | Specifies the format for the image. Pass either XYPixmap or ZPixmap. |
Description
XGetImage provides a mechanism to perform a rudimentary screen dump.
XGetImage returns an XImage structure. This structure provides you with the contents of the specified rectangle of the drawable in the format you specify. Depending on which format you pass to the format argument, the function does the following:
- If the format is XYPixmap
Gets only the bit planes you passed to the plane_mask argument.
- If the format is ZPixmap
Sets to 0 the bits in all planes not specified in the plane_mask argument. The function performs no range checking on the values in plane_mask, and ignores extraneous bits.
XGetImage returns the depth of the image to the depth member of the XImage structure. The depth of the image is as specified when the drawable was created.
If the drawable is a pixmap, the specified rectangle must be completely inside the pixmap, or a BadMatch error will occur. If XGetImage fails, it returns NULL.
If the drawable is a window, the window must be mapped, 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 will occur. The returned image will include any visible portions of inferiors or overlapping windows contained in the rectangle. The specified area can include the borders. The returned contents of visible regions of inferiors of different depth than the specified window are undefined.
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.
For XYFormat format data, the bit_order member of XImage specifies the bit order in which your server expects the data.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
| BadDrawable | |
| BadMatch | See Description above. |
| BadValue |
Related Commands
XDestroyImage, XPutImage, XCreateImage, XSubImage, XGetSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XGetInputFocus
Xlib - Input Handling—
Name
XGetInputFocus — return the current keyboard focus window.
Synopsis
XGetInputFocus (display, focus, revert_to) Display *display; Window *focus; /* RETURN */ int *revert_to; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| focus | Returns the ID of the focus window, or one of the constants PointerRoot or None. |
| revert_to | Returns the window to which the focus would revert if the focus window became invisible. This is one of these constants: RevertToParent, RevertToPointerRoot, or RevertToNone. Must not be a window ID. |
Description
XGetInputFocus returns the current focus window and the window to which the focus would revert if the focus window became invisible.
XGetInputFocus does not report the last focus change time. This is available only from events.
Related Commands
XSelectInput, XSetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XGetKeyboardControl
—Xlib - User Preferences
Name
XGetKeyboardControl — obtain a list of the current keyboard preferences.
Synopsis
XGetKeyboardControl (display, values) Display *display; XKeyboardState *values; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| values | Returns filled XKeyboardState structure. |
Description
XGetKeyboardControl returns the current control values for the keyboard. For the LEDs, the least significant bit of led_mask corresponds to LED 1, and each bit that is set to 1 in led_mask indicates an LED that is lit. auto_repeats is a bit vector; each bit that is set to 1 indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the least significant bit in the byte representing key 8N. global_auto_repeat is either AutoRepeatModeOn or AutoRepeatModeOff.
For the ranges of each member of XKeyboardState, see the description of the routine that sets that value.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
typedef struct {
int key_click_percent;
int bell_percent;
unsigned int bell_pitch, bell_duration;
unsigned long led_mask;
int global_auto_repeat;
char auto_repeats[32];
} XKeyboardState;
Related Commands
XGetDefault, XAutoRepeatOff, XAutoRepeatOn, XBell, XChangeKeyboardControl, XGetPointerControl.
XGetKeyboardMapping
Xlib - Keyboard—
Name
XGetKeyboardMapping — return symbols for keycodes.
Synopsis
KeySym *XGetKeyboardMapping (display, first_keycode, keycode_count, keysyms_per_keycode) Display *display; KeyCode first_keycode; int keycode_count; int *keysyms_per_keycode; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| first_keycode | Specifies the first keycode that is to be returned. |
| keycode_count | Specifies the number of keycodes that are to be returned. |
| keysyms_per_keycode | Returns the number of keysyms per keycode. |
Description
Starting with first_keycode, XGetKeyboardMapping returns the symbols for the specified number of keycodes. The specified first_keycode must be greater than or equal to min_keycode as returned in the Display structure, otherwise a BadValue error occurs. In addition, the following expression must be less than or equal to max_keycode as returned in the Display structure, otherwise a BadValue error occurs:
first_keycode + keycode_count − 1
The number of elements in the keysyms list is:
keycode_count * keysyms_per_keycode
Then, keysym number N (counting from 0) for keycode K has an index (counting from 0) of the following (in keysyms):
(K − first_keycode) * keysyms_per_keycode + N
The keysyms_per_keycode value is chosen arbitrarily by the server to be large enough to report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused elements for individual keycodes.
Use XFree to free the returned keysym list when you no longer need it.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
| BadValue | first_keycode less than display−>min_keycode. |
| display−>max_keycode exceeded. |
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XGetModifierMapping
X Programming Library—
Name
XGetModifierMapping — obtain a mapping of modifier keys (Shift, Control, etc.).
Synopsis
XModifierKeymap *XGetModifierMapping (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XGetModifierMapping returns the keycodes of the keys being used as modifiers.
There are eight modifiers, represented by the symbols ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIndex, Mod4MapIndex, and Mod5MapIndex. The modifiermap member of the XModifierKeymap structure contains eight sets of keycodes, each set containing max_keypermod keycodes. Zero keycodes are not meaningful. If an entire modifiermap is filled with 0's, the corresponding modifier is disabled. No keycode will appear twice anywhere in the map.
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;
/* modifier names. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. These correspond to the
masks defined above. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define Mod1MapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping.
XGetMotionEvents
—Xlib - Input Handling
Name
XGetMotionEvents — get pointer motion events.
Synopsis
XTimeCoord *XGetMotionEvents (display, w, start, stop, nevents) Display *display; Window w; Time start, stop; int *nevents; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose associated pointer motion events will be returned. |
| start
stop |
Specify the time interval in which the events are returned from the motion history buffer. Pass a time stamp (in milliseconds) or CurrentTime. |
| nevents | Returns the number of events returned from the motion history buffer. |
Description
XGetMotionEvents returns all events in the motion history buffer that fall between the specified start and stop times (inclusive) and that have coordinates that lie within (including borders) the specified window at its present placement. The x and y coordinates of the XTimeCoord return structure are reported relative to the origin of w. If XGetMotionEvent fails, it returns NULL.
If the start time is later than the stop time, or if the start time is in the future, no events are returned. If the stop time is in the future, it is equivalent to specifying the constant CurrentTime.
The motion history buffer may not be available on all servers. If display.motion_buffer > 0, it exists. The pointer position at each pointer hardware interrupt may then be stored for later retrieval.
Use XFree to free the returned XTimeCoord structures when they are no longer needed.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
typedef struct _XTimeCoord {
Time time;
unsigned short x, y;
} XTimeCoord;
Errors
BadWindow
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XGetNormalHints
—Xlib - Window Manager Hints
Name
XGetNormalHints — get the size hints property of a window in normal state (not zoomed or iconified).
Synopsis
Status XGetNormalHints (display, w, hints) Display *display; Window w; XSizeHints *hints; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be queried. |
| hints | Returns the sizing hints for the window in its normal state. |
Description
XGetNormalHints returns the size hints for a window in its normal state by reading the XA_WM_NORMAL_HINTS property. This function is normally used only by a window manager. It returns a nonzero Status if it succeeds, and 0 if it fails (e.g., the application specified no normal size hints for this window.)
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetPixel
—Xlib - Images
Name
XGetPixel — obtain a single pixel value from an image.
Synopsis
unsigned long XGetPixel(ximage, x, y) XImage *ximage; int x; int y;
Arguments
| ximage | Specifies a pointer to the image. |
| x
y |
Specify the x and y coordinates of the pixel whose value is to be returned. |
Description
XGetPixel returns the specified pixel from the named image. The x and y coordinates are relative to the origin (upper left [0,0]) of the image). The pixel value is returned in normalized format; that is, the least significant byte (LSB) of the long is the least significant byte of the pixel. The x and y coordinates must be contained in the image.
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
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;
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSubImage, XAddPixel, XPutPixel, ImageByteOrder.
XGetPointerControl
—Xlib - Pointer
Name
XGetPointerControl — get the current pointer preferences.
Synopsis
XGetPointerControl (display, accel_numerator, accel_denominator, threshold) Display *display; int *accel_numerator, *accel_denominator; /* RETURN */ int *threshold; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| accel_numerator | Returns the numerator for the acceleration multiplier. |
| accel_denominator | Returns the denominator for the acceleration multiplier. |
| threshold | Returns the acceleration threshold in pixels. The pointer must move more than this amount before acceleration takes effect. |
Description
XGetPointerControl gets the pointer acceleration parameters.
accel_numerator/accel_denominator is the number of pixels the cursor moves per unit of motion of the pointer, applied only to the amount of movement over threshold.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XChangePointerControl.
XGetPointerMapping
Xlib - Pointer—
Name
XGetPointerMapping — get the pointer button mapping.
Synopsis
int XGetPointerMapping (display, map, nmap) Display *display; unsigned char map[]; /* RETURN */ int nmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| map | Returns the mapping list. Array begins with map []. |
| nmap | Specifies the number of items in mapping list. |
Description
XGetPointerMapping returns the current mapping of the pointer buttons. Information is returned in both the arguments and the function's return value, map is an array of the numbers of the buttons as they are currently mapped. Elements of the list are indexed starting from 1. The nominal mapping for a pointer is the identity mapping: map[i]=i. If map [3]=2, it means that the third physical button triggers the second logical button.
nmap indicates the desired number of button mappings.
The return value of the function is the actual number of elements in the pointer list, which may be greater or less than nmap.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XSetPointerMapping, XGetPointerControl, XChangePointerControl.
XGetScreenSaver
—Xlib - Screen Saver
Name
XGetScreenSaver — get the current screen saver parameters.
Synopsis
XGetScreenSaver (display, timeout, interval, prefer_blanking, allow_exposures) Display *display; int *timeout, *interval; /* RETURN */ int *prefer_blanking; /* RETURN */ int *allow_exposures; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| timeout | Returns the timeout, in seconds, until the screen saver turns on. |
| interval | Returns the interval between screen saver invocations, in seconds. |
| prefer_blanking | Returns the current screen blanking preference, one of these constants: DontPreferBlanking, PreferBlanking, or DefaultBlanking. |
| allow_exposures | Returns the current screen save control value, either DontAllowExposures, AllowExposures, or DefaultExposures. |
Description
XGetScreenSaver returns the current settings of the screen saver, which may be set with XSetScreenSaver.
A positive timeout indicates that the screen saver is enabled. A timeout of 0 indicates that the screen saver is disabled. If no input from devices (keyboard, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is activated.
If the server-dependent screen saver method supports periodic change, interval serves as a hint about the length of the change period, and 0 serves as a hint that no periodic change should be made. Examples of ways to change the screen include scrambling the colormap periodically, moving an icon image about the screen periodically, or tiling the screen with the root window background tile, randomly reoriginated periodically. An interval of 0 indicates that random pattern motion is disabled.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XSetScreenSaver.
XGetSelectionOwner
Xlib - Selections—
Name
XGetSelectionOwner — return the owner of a selection.
Synopsis
Window XGetSelectionOwner (display, selection) Display *display; Atom selection;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| selection | Specifies the selection atom whose owner you want returned. |
Description
XGetSelectionOwner returns the window ID of the current owner of the specified selection. If no selection was specified, or there is no owner, the function returns the constant None.
For more information on selections, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAtom
Related Commands
XSetSelectionOwner, XConvertSelection.
XGetSizeHints
—Xlib - Window Manager Hints
Name
XGetSizeHints — read any property of type XA_SIZE_HINTS.
Synopsis
Status XGetSizeHints (display, w, hints, property) Display *display; Window w; XSizeHints *hints; /* RETURN */ Atom property;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which size hints will be returned. |
| hints | Returns the size hints structure. |
| property | Specifies a property atom of type XA_WM_SIZE_HINTS. May be XA_WM_NORMAL_HINTS, XA_WM_ZOOM_HINTS, or a property defined by an application. |
Description
XGetSizeHints returns the XSizeHints structure for the named property and the specified window. This is used by XGetNormalHints and XGetZoomHints, and can be used to retrieve the value of any property of type XA_WM_SIZE_HINTS; thus, it is useful if other properties of that type get defined. This function is used almost exclusively by window managers.
XGetSizeHints returns a nonzero Status if a size hint was defined, and 0 otherwise.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadAtom
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetStandardColormap
—Xlib - Colormaps
Name
XGetStandardColormap — get the standard colormap property.
Synopsis
Status XGetStandardColormap (display, w, cmap_info, property) Display *display; Window w; XStandardColormap *cmap_info; /* RETURN */ Atom property;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window on which the property is set. This is normally the root window. |
| cmap_info | Returns the filled colormap information structure. |
| property | Specifies the atom indicating the type of standard colormap desired. The predefined standard colormap atoms are XA_RGB_BEST_MAP, XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP. |
Description
XGetStandardColormap gets a property on a window (normally the root window) that describes a standard colormap.
This call does not load the colormap into the hardware colormap, it does not allocate entries, and it does not even create a virtual colormap. It just provides information about one design of colormap. The application can then attempt to create a virtual colormap of the appropriate type, and allocate its entries according to the information in the XStandardColormap structure. Installing the colormap must then be done with XInstallColormap, in cooperation with the window manager. Any of these steps could fail, and the application should be prepared.
If the server has already created a standard colormap of this type, then its ID will be returned in the colormap member of the XStandardColormap structure. Some servers, particular on high-performance workstations, will create some or all of the standard colormaps so they can be quickly installed when needed by applications.
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 XStandardColormap 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:
pixel = base_pixel
+ ((unsigned long) (0.5 + r * red_max)) * red_mult
+ ((unsigned long) (0.5 + g * green_max)) * green_mult
+ ((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.
See Volume One, Chapter 7, Color, for a complete description of standard colormaps.
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;
} XStandardColormap;
Errors
BadAtom
BadWindow
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XGetSubImage
—Xlib - Images
Name
XGetSubImage — copy a rectangle in drawable to a location within the pre-existing image.
Synopsis
XImage *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; XImage *dest_image; int dest_x, dest_y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable from which the rectangle is to be copied. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the origin of the drawable. |
| width height | Specify the width and height in pixels of the subimage taken. |
| plane_mask | Specifies which planes of the drawable are transferred to 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 |
| dest_y | corner, relative to the image's origin. |
Description
XGetSubImage 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 0 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 XImage 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 specified 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.
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 XGetSubImage.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
| BadDrawable | |
| BadGC | |
| BadMatch | Depth of dest_image is not the same as depth of drawable. See also Description. |
| BadValue |
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XGetTransientForHint
—Xlib - Window Manager Hints
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_window; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be queried. |
| prop_window | Returns 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 menus and dialog boxes.
XGetTransientForHint returns a Status of 0 on failure, and nonzero on success.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetVisualInfo
Xlib - Visuals—
Name
XGetVisualInfo — find a visual information structure that matches the specified template.
Synopsis
XVisualInfo *XGetVisualInfo (display, vinfo_mask, vinfo_template, nitems) Display *display; long vinfo_mask; XVisualInfo *vinfo_template; int *nitems; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| vinfo_mask | Specifies the visual mask value. Indicates which elements in template are to be matched. |
| vinfo_template | Specifies the visual attributes that are to be used in matching the visual structures. |
| nitems | Returns the number of matching visual structures. |
Description
XGetVisualInfo returns a list of visual structures that match the attributes specified by the vinfo_template argument. If no visual structures match the template, XGetVisualInfo 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 *visual;
VisualID 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;
} XVisualInfo;
/* The symbols for the vinfo_mask argument are: */
#define VisualNoMask 0x0
#define VisualIDMask 0x1
#define VisualScreenMask 0x2
#define VisualDepthMask 0x4
#define VisualClassMask 0x8
#define VisualRedMaskMask 0x10
#define VisualGreenMaskMask 0x20
#define VisualBlueMaskMask 0x40
#define VisualColormapSizeMask 0x80
#define VisualBitsPerRGBMask 0x100
#define VisualAllMask 0x1FF
Related Commands
XMatchVisualInfo, DefaultVisual.
XGetWindowAttributes
Xlib - Window Attributes—
Name
XGetWindowAttributes — obtain the current attributes of window.
Synopsis
Status XGetWindowAttributes (display, w, window_attributes) Display *display; Window w; XWindowAttributes *window_attributes; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window whose current attributes you want. |
| window_attributes | Returns a filled XWindowAttributes structure, containing the current attributes for the specified window. |
Description
XGetWindowAttributes returns the XWindowAttributes structure containing the current window attributes.
While w is defined as type Window, a Pixmap can also be used, in which case all the returned members will be 0 except width, height, depth, and screen.
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 InputOnly. |
| bit_gravity | The new position for existing contexts on resize. One of the constants ForgetGravity, StaticGravity, or CenterGravity, or one of the compass constants (NorthWestGravity, NorthGravity, etc.). |
| win_gravity | The new position for subwindow on parent resize. 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: NotUseful, WhenMapped, or Always. |
| backing_planes | The bit planes to be preserved in a backing store. |
| backing_pixel | 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 to be 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, IsUnviewable, or IsViewable. IsUnviewable indicates that the specified window is mapped but some ancestor is unmapped. |
| all_event_masks | 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 querying 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. Either True or False. |
| screen | A pointer to the Screen structure for the screen containing this window. |
| XGetwindowAttributes | returns a Status of 0 on failure, or 1 on success. |
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 */
Visual *visual; /* the associated visual structure */
Window root; /* root of screen containing window */
int class; /* InputOutput, InputOnly*/
int bit_gravity; /* one of bit gravity values */
int win_gravity; /* one of the window gravity values */
int backing_store; /* NotUseful, WhenMapped, Always */
unsigned long backing_planes; /* planes to be preserved if possible */
unsigned long backing_pixel; /* value to be used when restoring planes */
Bool save_under; /* boolean, should bits under be saved */
Colormap colormap; /* colormap to be associated with window */
Bool map_installed; /* boolean, is colormap currently installed*/
int map_state; /* IsUnmapped, IsUnviewable, IsViewable */
long all_event_masks; /* set of events all people have interest in*/
long your_event_mask; /* my event mask */
long do_not_propagate_mask; /* set of events that should not propagate */
Bool override_redirect; /* boolean value for override-redirect */
Screen *screen; /* pointer to correct screen */
} XWindowAttributes;
Related Commands
XChangeWindowAttributes, XSetWindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGetGeometry.
XGetWindowProperty
—Xlib - Properties
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_format, nitems, 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 pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose atom type and property format you want to obtain. |
| property | Specifies the property atom. |
| long_offset | Specifies the offset in 32-bit quantities where data will be retrieved. |
| long_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 property is returned, the property is deleted from the window and a PropertyNotify event is generated on the window. |
| req_type | If AnyPropertyType 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_format | Returns the actual data type of the returned data. |
| nitems | 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. |
| 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 ASCII Null. This byte is not counted in nitems. |
Description
XGetWindowProperty gets the value of a property if it is the desired type. XGetWindowProperty sets the return arguments acccording to the following rules:
- If the specified property does not exist for the specified window, then: actual_type is None; actual_format = 0; and bytes_after = 0. delete is ignored in this case, and nitems 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 0); and bytes_after is the property length in bytes (even if actual_format is 16 or 32). delete is ignored in this case, and nitems is empty.
- If the specified property exists, and either req_type is AnyPropertyType or the specified type matches the actual property type, then: actual_type is the actual property type; and actual_format is the actual property format (never 0). bytes_after and nitems are defined by combining the following values:
N = actual length of stored property in bytes (even if actual_format is 16 or 32)
I = 4 * long_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 bytes_after.
If delete == True and bytes_after == 0 the function deletes the property from the window and generates a PropertyNotify event on the window.
When XGetWindowProperty executes successfully, it returns Success. If it fails, it returns 1. Note that these return values are the opposite values of routines that return int or Status. To free the resulting data, use XFree. If the specified window did not exist, it generates a Badwindow error. If the type you passed in req_type did not exist or did not match the property type returned in actual_type, the function generates a BadMatch error.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
| BadAtom | |
| BadMatch | |
| BadValue | Value of long_offset caused L to be negative above. |
| BadWindow |
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XListProperties, XGetAtomName, XInternAtom.
XGetWMHints
Xlib - Window Manager Hints—
Name
XGetWMHints — read the window manager hints property.
Synopsis
XWMHints *XGetWMHints (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; 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, Interclient 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
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGetZoomHints
—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
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be queried. |
| zhints | Returns a pointer to the zoom hints. |
Description
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 0 if the application did not specify zoom size hints for this window.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XGrabButton
—Xlib - Grabbing
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 pointer to the Display structure; returned from XOpenDisplay. |
| button | Specifies the mouse button. May be Button1, Button2, Button3, Button4, Button5, or AnyButton. The constant AnyButton is equivalent to issuing the grab request for all possible buttons. The button symbols cannot be ORed. |
| modifiers | Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols; ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. AnyModifier 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 grab. |
| owner_events | Specifies a boolean value of either True or False. See Description below. |
| event_mask | Specifies the event mask. This mask is the bitwise OR of one or more of the event masks listed on the reference page for XSelectInput. |
| pointer_mode | Controls further processing of pointer events. Pass one of these constants: GrabModeSync or GrabModeAsync. |
| keyboard_mode | Controls further processing of keyboard events. 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. |
| cursor | Specifies the cursor to be displayed during the grab. One possible value you can pass is the constant None. |
Description
XGrabButton establishes a passive grab, such that an active grab may take place when the specified key/button combination is pressed. 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 confine_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 GrabPointer, 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 AnyModifier 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).
The request fails if some other client has already issued a GrabButton with the same button/key combination on the same window. When using AnyModifier or AnyButton, the request fails completely (no grabs are established) if there is a conflicting grab for any combination. The request has no effect on an active grab.
The owner_events argument specifies whether the grab window should receive all events (True) or whether the grabbing application should receive all events normally (False).
The pointer_mode and keyboard_mode control the processing of events during the grab. If either is GrabModeSync, events for that device are not queued for applications until XAllowEvents is called to release the events. If either is GrabModeAsync, events for that device are processed normally.
An automatic grab takes place between a ButtonPress and a ButtonRelease, so this call is not necessary in some of the most common situations.
For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
| BadAccess | When using AnyModifier 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. | |
| BadAlloc | |
| BadCursor | |
| BadValue | |
| BadWindow |
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer XUngrabServer.
XGrab Key
Xlib - Grabbing—
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 pointer to the Display structure; 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 following symbols: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. AnyModifier 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. |
| grab_window | Specifies the window from which you want to receive input from the grabbed key combination. |
| owner_events | Specifies whether the grab window should receive all events (True) or whether the grabbing application should receive all events normally (False). |
| pointer_mode | Controls further processing of pointer events. Pass one of these constants: GrabModeSync or GrabModeAsync. |
| keyboard_mode | Controls further processing of keyboard events. 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 is grabbed, and all keyboard events are sent to this application. More formally:
- IF the keyboard is not grabbed and the specified key, which itself can be a modifier key, is logically pressed when the specified modifier keys logically are down (and no other keys are down),
- AND no other modifier keys logically are 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 queued for applications until XAllowEvents is called to release the events. If either is GrabModeAsync, events for that device are processed normally.
For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
| BadAccess | When using AnyModifier 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 | keycode is not in the range between min_keycode and max_keycode in the display structure. |
| BadWindow |
Related Commands
XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XGrabKeyboard
Xlib - Grabbing—
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 pointer to the Display structure; 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. |
| pointer_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. |
| time | Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. |
Description
XGrabKeyboard actively grabs control of the main keyboard. Further key events are reported only to the grabbing client. This request generates FocusIn and FocusOut events.
XGrabKeyboard processing is controlled by the value in the owner_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 pointer_mode and keyboard_mode:
- 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.
- If the pointer_mode or keyboard_mode is GrabModeSync, events for the respective device are queued until a releasing XAllowEvents request occurs or until the keyboard grab is released as described above.
If the grab is successful, it returns the constant GrabSuccess. XGrabKeyboard processing 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 GrabInvalidTime.
- 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 CurrentTime 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
XGrabKey, XUngrabKey, XUngrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XGrabPointer
Xlib - Grabbing—
Name
XGrabPointer — grab the pointer.
Synopsis
int XGrabPointer (display, grab_window, owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor, time) Display *display; Window grab_window; Bool owner_events; unsigned int event_mask; int pointer_mode, keyboard_mode; Window confine_to; Cursor cursor; Time time;
Arguments
| display | Specifies a pointer to the Display structure; 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 application (pass True) or only to the grab window if selected by the event mask (pass False). |
| event_mask | Specifies the event mask. See XSelectInput for a complete list of event masks. |
| pointer_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 CurrentTime. |
Description
XGrabPointer actively grabs control of the pointer. Further pointer events are only reported to the grabbing client.
event_mask is always augmented to include ButtonPressMask and ButtonReleaseMask. If owner_events is False, all generated pointer events are reported with respect to grab_window, and are only reported if selected by event_mask. If owner_events 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 grab_window, and is only reported if selected by event_mask. For either value of owner_events, unreported events are discarded.
pointer_mode controls further processing of pointer events, 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 but not sent to clients until the grabbing client issues a releasing XAllowEvents request or an XUngrabPointer request.
If a cursor is specified, then it is displayed regardless of what window the pointer is in. If no cursor is specified, then when the pointer is in grab_window or one of its subwindows, the normal cursor for that window is displayed. Otherwise, the cursor for grab_window is displayed.
If a confine_to window is specified, then the pointer will be restricted to that window. The confine_to window need have no relationship to the grab_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 confine_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 applications specify the timestamp from the ButtonPress event, the second application will successfully grab the pointer, while the first will get a return value of AlreadyGrabbed, indicating 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 EnterNotify and LeaveNotify events.
If the grab is successful, it returns the constant GrabSuccess. The XGrabPointer function fails under the following conditions, with the following return values:
- If grab_window or confine_to window is not viewable, 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.
- If the specified time is earlier than the last-pointer-grab time or later than the current X server time, GrabInvalidTime is returned. (If the call succeeds, the last pointer grab time is set to the specified time, with the constant CurrentTime replaced by the current X server time.)
For more information on grabbing, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadCursor
BadValue
BadWindow
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XGrabServer
—Xlib - Grabbing
Name
XGrabServer — grab the server.
Synopsis
XGrabServer (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; 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
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XUngrabServer.
XIfEvent
Xlib - Input Handling—
Name
XIfEvent — wait for event matched in predicate procedure.
Synopsis
XIfEvent (display, event, predicate, args) Display *display; XEvent *event; /* RETURN */ Bool (*predicate) () ; char *args;
Arguments
| display | Specifies a pointer to the Display structure; 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 procedure. |
Description
XIfEvent checks the event queue for events, uses the user-supplied routine to check if they meet certain criteria, and removes the matching event from the input queue. XIfEvent returns only when the specified predicate procedure returns True for an event. The specified predicate is called each time an event is added to the queue, with the arguments display, event, and arg.
If no matching events exist on the queue, XIfEvent flushes the output buffer and waits for an appropriate event to arrive. Use XCheckIfEvent if you don't want to wait for an event.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XInsertModifiermapEntry
—Xlib - Resource Manager
Name
XInsertModifiermapEntry — add a new entry to an XModifierKeymap structure.
Synopsis
XModifierKeymap *XInsertModifiermapEntry (modmap, keysym_entry, modifier) XModifierKeymap *modmap; KeyCode keysym_entry; int modifier;
Arguments
| modmap | Specifies a pointer to an XModifierKeymap structure. |
| keysym_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: ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIndex, Mod4MapIndex, or Mod5MapIndex. |
Description
XInsertModifiermapEntry returns an XModifierKeymap structure suitable for calling XSetModifierMapping, in which the specified keycode is deleted from the set of keycodes that is mapped to the specified modifier (like Shift or Control). XInsertModifiermapEntry does not change the mapping itself.
This function is normally used by calling XGetModifierMapping to get a pointer to the current XModifierKeymap structure for use as the modmap argument to XInsertModifiermapEntry.
Note that the structure pointed to by modmap is freed by XInsertModifiermapEntry. It should not be freed or otherwise used by applications.
For a description of the modifier map, see XSetModifierMapping.
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 Mod1MapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Related Commands
XDeleteModifiermapEntry, XGetModifierMapping, XSetModifierMapping, XNewModifierMap, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookupeysym, XRebindKeySym, XGetKeyboardMapping, XRefreshKeyboardMapping, XLookupString.
XInstallColormap
—Xlib - Colormaps
Name
XInstallColormap — install a colormap.
Synopsis
XInstallColormap (display, cmap) Display *display; Colormap cmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap to install. |
Description
If there is only one hardware colormap, XInstallColormap 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, XInstallColormap 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 color-maps is already installed, an old colormap is swapped out. The MinCmapsOfScreen (screen) and MaxCmapsOfScreen (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 XInstallColormap it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at 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.
For more information, see Volume One, Chapter 7, Color.
Errors
BadColor
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandardColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XInternAtom
—Xlib - Properties
Name
XInternAtom — return an atom for a given name string.
Synopsis
Atom XInternAtom (display, property_name, only_if_exists) Display *display; char *property_name; Bool only_if_exists;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| property_name | Specifies the name associated with the property you want the atom for. 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 that indicates whether XInternAtom should return None or should create the atom if no such property_name exists. |
Description
XInternAtom returns the atom identifier corresponding to 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 ASCII string. 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.
This, function is the opposite of XGetAtomName, which returns the atom name when given an atom ID.
Predefined atoms are defined in <X11/Xatom.h> and begin with the prefix “XA_”.
Errors
BadAlloc
BadValue
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName.
XIntersectRegion
Xlib - Regions—
Name
XIntersectRegion — compute the intersection of two regions.
Synopsis
XIntersectRegion (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
XIntersectRegion generates a region that is the intersection of two regions.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XKeycodeToKeysym
—Xlib - Keyboard
Name
XKeycodeToKeysym — convert a keycode to a keysym.
Synopsis
KeySym XKeycodeToKeysym (display, keycode, index) Display *display; KeyCode keycode; int index;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| keycode | Specifies the keycode. |
| index | Specifies which keysym to return. |
Description
XKeycodeToKeysym returns the keysym 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
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey, IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey.
XKeysymToKeycode
Xlib - Keyboard—
Name
XKeysymToKeycode — convert a keysym to the appropriate keycode.
Synopsis
KeyCode XKeysymToKeycode (display, keysym_kcode) Display *display; Keysym keysym_kcode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| keysym_kcode | Specifies the keysym that is to be searched for. |
Description
XKeysymToKeycode returns the keycode corresponding to the specified keysym symbol in the current mapping. If the specified keysym is not defined for any keycode, XKeysymToKeycode returns 0.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey, IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey.
XKeysymToString
—Xlib - Keyboard
Name
XKeysymToString — convert a keysym symbol to a string.
Synopsis
char *XKeysymToString(keysym_str) KeySym keysym_str;
Arguments
| keysym_str | 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 F1 key is mapped to the string “STOP” using XRebindKeysym, XKeysymToString still returns “F1”. XLookupString, however, would return “STOP”.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping, IsKeypadKey, IsCursorKey, IsPFKey, IsFunctionKey, IsMiscFunctionKey, IsModifierKey.
XKillClient
Xlib - Client Connections—
Name
XKillClient — destroy a client or its remaining resources.
Synopsis
XKillClient (display, resource) Display *display; XID resource;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| resource | Specifies any resource created by the client you want to destroy, or the constant 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 RetainTemporary 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 RetainTemporary are destroyed.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadValue
Related Commands
XSetCloseDownMode
XListExtensions
—Xlib - Extensions
Name
XListExtensions — return a list of all extensions to X supported by the server.
Synopsis
char **XListExtensions (display, nextensions) Display *display; int *nextensions; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| nextensions | Returns the number of extensions in the returned list. |
Description
XListExtensions lists all the X extensions supported by the current server. Upper or lower case is important. 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 arc for special characters needed in western languages other than English.
For more information on extensions, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XQueryExtension, XFreeExtensionList.
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 pointer to the Display structure; returned from XOpenDisplay. |
| pattern | Specifies the string associated with the font names you want returned. You can specify any string, an asterisk (*), or a question mark. The asterisk 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 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. |
| 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 string is terminated by NULL. The maximum number of names returned in the list depends on the value you passed to maxnames. The function returns the actual number of font names in actual_count. The client should call XFreeFontNames when done with this list to free the memory.
The font search path (the order in which font names are compared to pattern) is set by XSetFontPath.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XListFontsWithInfo
—Xlib - Fonts
Name
XListFontsWithInfo — obtain the names and information about loaded fonts.
Synopsis
char **XListFontsWithInfo (display, pattern, maxnames, count, info) Display *display; char *pattern; /* null-terminated */ int maxnames; int *count; /* RETURN */ XFontStruct **info; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| pattern | Specifies the string associated with the font names you want returned. You can specify any string, an asterisk (*), or a question mark. The asterisk indicates a wildcard on any number of characters and the question mark indicates a wildcard on a single character. |
| 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 the font information. XListFontsWithInfo provides enough space for maxnames pointers. |
Description
XListFontsWithInfo returns a list of font names that match the specified pattern and a list of their associated font information. The list of names is limited to a size specified by the maxnames argument. To free the allocated name array, the client should call XFreeFontNames. To free the font information array, the client should call XFreeFontInfo.
The information returned for each font is identical to what XQueryFont would return, except that the per-character metrics (lbearing, rbearing, width, ascent, descent for single characters) are not returned.
XListFontsWithInfo returns NULL on failure.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* Font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XListHosts
—Xlib - Host Access
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
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| nhosts | Returns the number of hosts currently in the access control list. |
| state | Returns the state of access to the control list at connection setup. True if enabled, False if disabled. |
Description
XListHosts returns the current access control list as well as whether the use of the list was enabled or disabled when this client connected to the display. XListHosts allows a program to find out what machines can make connections, by looking at the list of host structures. This XHostAddress list should be freed with XFree 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, XRemoveHost, XRemoveHosts, XDisableAccessControl, XEnableAccessControl, XSetAccessControl.
XListInstalledColormaps
Xlib - Colormaps—
Name
XListInstalledColormaps — get a list of installed colormaps.
Synopsis
Colormap *XListInstalledColormaps (display, w, num) display *display; Window w; int *num; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; 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
XListInstalledColormaps returns a list of the currently installed colormaps for the screen of the specified window. The order in the list is not significant. There is no distinction in the list between colormaps actually being used by windows and colormaps no longer in use which have not yet been freed or destroyed. The allocated list should be freed using XFree when it is no longer needed. XListInstalledColormaps returns None on failure and sets num to 0.
For more information on installing colormaps, see Volume One, Chapter 7, Color.
Errors
BadWindow
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XSetWindowColormap, DefaultColormap, DisplayCells.
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_prop; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| 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 atom properties that are defined for the specified window. To free the memory allocated by this function, use XFree. XListProperties returns NULL on failure and sets num_prop to 0.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadWindow
Related Commands
XSetStandardProperties, XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XGetWindowProperty, XGetAtomName, XInternAtom.
XLoadFont
Xlib - Fonts—
Name
XLoadFont — load a font if not already loaded; get font ID.
Synopsis
Font XLoadFont (display, name) Display *display; char *name;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| name | Specifies the name of the font in a null terminated string. 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, returns a 0 and 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 XLoadFontwithInfo 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 | |
| BadName | name specifies an unavailable font. |
Related Commands
XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XLoadQueryFont
—Xlib - Fonts
Name
XLoadQueryFont — load a font and fill information structure.
Synopsis
XFontStruct *XLoadQueryFont (display, name) Display *display; char *name;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| name | Specifies the name of the font. This name is a null terminated string. |
Description
XLoadQueryFont performs a XLoadFont and XQueryFont in a single operation. XLoadQueryFont 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 | |
| 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_byte1; /* first row that exists */
unsigned max_byte1; /* 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;
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Errors
BadAlloc
Related Commands
XLoadFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XLookUpAssoc
—Xlib - 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
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| table | Specifies the association table. |
| x_id | Specifies the X resource ID. |
Description
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
Association tables provide a way of storing data and accessing by ID. This information is available to all clients. XLookUpAssoc 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_id cannot be found in the table the routine returns NULL.
For more information on association tables, see Volume One, Chapter 13, Other Programming Techniques.
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.
XLookupColor
Xlib - Color Cells—
Name
XLookupColor — get database RGB values and closest hardware-supported RGB values from color name.
Synopsis
Status XLookupColor (display, cmap, colorname, rgb_db_def, hardware_def) Display *display; Colormap cmap; char *colorname; XColor *rgb_db_def, *hardware_def; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap. |
| colorname | Specifies the color name string (for example “red”). Upper or lower case does not matter. The string should be in ISO LATIN1 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 /usr/lib/rgb database. |
| hardware_def | Returns the closest RGB values possible on the hardware. |
Description
XLookupColor looks up the string name of a color with respect to the screen associated with the specified cmap and returns both the exact color values and the closest values possible on that screen.
XLookupColor returns 1 if colorname exists in the RGB database or 0 if it does not exist.
To determine the exact RGB values, XLookupColor uses a database on the X server. On UNIX, this database is /usr/lib/rgb. To read the colors provided by the database on a UNIX system, see /usr/lib/rgb.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 Database, in this volume.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XLookupKeysym
Xlib - Keyboard—
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 ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIndex, Mod4MapIndex, and Mod5MapIndex can be used. |
Description
Given a keyboard event and the index into the list of keysyms for that keycode, XLookupKeysym 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 interpret 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 specified event structure.
Note that some hardware can't support KeyRelease events for every key. You may wish to avoid using them in your code.
Structures
typedef struct {
int type; /* of event */
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;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XLookupString
Xlib - Keyboard—
Name
XLookupString — map a key event to ASCII 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 information 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 Release 1 or 2. |
Description
XLookupString gets an ASCII string and a keysym that are currently mapped to the key-code 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 the user's 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 Release 1 or 2.
Structures
/*
* Compose sequence status structure, used in calling XLookupString.
*/
typedef struct _XComposeStatus {
char *compose_ptr; /* state table pointer */
int chars_matched; /* match state */
} XComposeStatus;
typedef struct {
int type; /* of event */
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;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeySym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XSetModifierMapping, XGetModifierMapping.
XLowerWindow
Xlib - Window Manipulation—
Name
XLowerWindow — lower a window in the stacking order.
Synopsis
XLowerWindow (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; 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 some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing 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 EnterNotify events are sent to the window which was immediately below the lowered window at the pointer position.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XMakeAssoc
—Xlib - Association Tables
Name
XMakeAssoc — create an entry in an association table.
Synopsis
XMakeAssoc (display, table, x_id, data) Display *display; XAssocTable *table; XID x_id; caddr_t data;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| table | Specifies the association table in which an entry is to be made. |
| x_id | 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 by any application.
This function is provided for compatibility with X Version 10. To use it you must include the file <X11/X10.h> and link with the library -loldX.
Data is inserted into the table only once. Redundant inserts are meaningless and cause no problems. The queue in each association bucket is sorted from the lowest XID to the highest XID.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
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.
XMapRaised
Xlib - Window Mapping—
Name
XMapRaised — map a window on top of its siblings.
Synopsis
XMapRaised (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
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 windows. 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.
XMapSubwindows
—Xlib - Window Mapping
Name
XMapSubwindows — map all subwindows.
Synopsis
XMapSubwindows (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; 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.
For more information, see Volume One, Chapter 14, Window Management.
Errors
BadWindow
Related Commands
XMapRaised, XMapWindow, XUnmapSubwindows, XUnmapWindow.
XMapWindow
Xlib - Window Mapping—
Name
XMapWindow — map a window.
Synopsis
XMapWindow (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; 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 windows. 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 sub windows 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).
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:
- Map the window, call XSelectInput for exposure events, wait for the first Expose event, and repaint each window explicitly.
- Call XSelectInput 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 managers that intercept the request.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XUnmapSubwindows, XUnmapWindow.
XMaskEvent
—Xlib - Input Handling
Name
XMaskEvent — remove the next event that matches mask.
Synopsis
XMaskEvent (display, event_mask, rep) Display *display; unsigned long event_mask; XEvent *rep; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event_mask | Specifies the event mask. See XSelectInput for a complete list of event masks. |
| 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 output buffer and waits until one is received. Use XCheckMaskEvent if you do not wish to wait.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XMatchVisualInfo
Xlib - Visuals—
Name
XMatchVisualInfo — obtain the visual information that matches the desired depth and class.
Synopsis
Status XMatchVisualInfo (display, screen, depth, class, vinfo) Display *display; int screen; int depth; int class; XVisualInfo *vinfo; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; 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 TrueColor. |
| vinfo | Returns the matched visual information. |
Description
XMatchVisualInfo returns the visual information for a visual that matches the specified depth and class for a screen. Because multiple visuals that match the specified depth and class can exist, 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 0.
For more information on visuals, see Volume One, Chapter 7, Color.
Structures
typedef struct {
Visual *visual;
VisualID 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;
} XVisualInfo;
Related Commands
XGetVisualInfo, DefaultVisual.
XMoveResizeWindow
—Xlib - Window 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 pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be reconfigured. |
| x
y |
Specify the new x and y coordinates of the upper-left pixel of the window's border, relative to the window's parent. |
| width height | Specify the width and height in pixels. These arguments define the interior size of the window. |
Description
XMoveResizeWindow moves or resizes a window or both. XMoveResizeWindow does not raise the window. Configuring a mapped window may lose its contents and generate an Expose event on that window depending on the bit_gravity and backing store attributes. Configuring a window 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 some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing is performed.
If some other client has selected StructureNotifyMask on the window, then a ConfigureNotify event is generated after the move and resize takes place, and the event will contain the final position and size of the window.
Errors
BadMatch
BadValue
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XMoveWindow
Xlib - Window Manipulation—
Name
XMoveWindow — move a window.
Synopsis
XMoveWindow (display, w, x, y) Display *display; Window w; int x, y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be moved. |
| x
y |
Specify the new x and y coordinates of the upper-left pixel of the window's border (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 parent. 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 nonchildrcn 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 some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing is performed.
If some other client has selected StructureNotifyMask on the window, then a ConfigureNotify event is generated after the move takes place, and the event will contain the final position of the window.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XNewModifiermap
—Xlib - Keyboard
Name
XNewModifiermap — create a keyboard modifier mapping structure.
Synopsis
XModifierKeymap *XNewModifiermap(max_keys_per_mod) int max_keys_per_mod;
Arguments
| max_keys_per_mod | Specifies the maximum number of keycodes assigned to any of the modifiers in the map. |
Description
XNewModifiermap returns a XModifierKeymap structure and allocates the needed space. This function is used when more than one XModifierKeymap structure is needed. max_keys_per_mod depends on the server and should be gotten from the XModifierKeymap returned by XGetModifierMapping.
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
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XNextEvent
Xlib - Input Handling—
Name
XNextEvent — get the next event of any type or window.
Synopsis
XNextEvent (display, report) Display *display; XEvent *report; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| report | Returns the event removed from the input queue. |
Description
XNextEvent removes an input event from the head of the event queue and copies it into an XEvent supplied by the caller. If the event queue is empty, XNextEvent flushes the output buffer and waits (blocks) until an event is received. Use XCheckNextEvent if you do not want to wait.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XNoOp
—Xlib - HouseKeeping
Name
XNoOp — send a NoOp to exercise connection with the server.
Synopsis
XNoOp (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; 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 output buffer.
Related Commands
XFree, XOpenDisplay, XCloseDisplay, DefaultScreen.
XOffsetRegion
Xlib - Regions—
Name
XOffsetRegion — change offset of a region.
Synopsis
XOffsetRegion (r, dx, dy) Region r; int dx, dy;
Arguments
| r | Specifies the region. |
| dx
dy |
Specify the amount to move the specified region relative to the origin of all regions. |
Description
XOffsetRegion changes the offset of the region the specified amounts in the x and y directions.
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 clip_mask by calling XSetRegion, the upper-left corner of the region relative to the drawable used in the graphics request will be at (xoffset + clip_x_origin, yoffset + clip_y_origin), where xoffset and yoffset are the offset of the region and clip_x_origin and clip_y_origin are elements of the GC used in the graphics request.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XOpenDisplay
—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 hardware display and communications domain to be used. See Description below. |
Description
The XOpenDisplay routine connects the client to the server controlling the hardware display through TCP, UNIX, or DECnet streams.
If display_name is NULL, the value defaults to the contents of the DISPLAY environment variable on UNIX systems. On non-UNIX 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 hostname: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 connected. 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 support them.
|
| 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 usually numbered starting from 0. |
| 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 display by a single user, screen merely sets an internal variable that is returned by the DefaultScreen 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 DefaultScreen macro. After opening the display, 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.
For more information, see Volume One: Chapter 2, X Concepts; and Chapter 3, Basic Window Program.
Structures
/*
* Display datatype maintaining display specific data.
*/
typedef struct _XDisplay {
XExtData *ext_data; /* hook for extension to hang data */
struct _XDisplay *next; /* next open Display on list */
int fd; /* network socket */
int lock; /* is someone in critical section */
int proto_major_version; /* major version of server's X protocol */
int proto_minor_version; /* minor version of server's X protocol */
char *vendor; /* vendor of the server hardware */
long resource_base; /* resource ID base */
long resource_mask; /* resource ID mask bits */
long resource_id; /* allocator current ID */
int resource_shift; /* allocator shift to correct bits */
XID (*resource_alloc)(); /* allocator function */
int byte_order; /* screen byte order, LSBFirst, MSBFirst */
int bitmap_unit; /* padding and data requirements */
int bitmap_pad; /* padding requirements on bitmaps */
int bitmap_bit_order; /* LeastSignificant or MostSignificant */
int nformats; /* number of pixmap formats in list */
ScreenFormat *pixmap_format; /* pixmap format list */
int vnumber; /* Xlib's X protocol version number */
int release; /* release of the server */
struct _XSQEvent *head, *tail; /* input event queue */
int qlen; /* length of input event queue */
int last_request_read; /* sequence number of last event read */
int request; /* sequence number of last request */
char *last_req; /* beginning of last request, or dummy */
char *buffer; /* output buffer starting address */
char *bufptr; /* output buffer index pointer */
char *bufmax; /* output buffer maximum+1 address */
unsigned max_request_size; /* maximum number 32 bit words in request */
struct _XrmHashBucketRec *db;
int (*synchandler)(); /* synchronization handler */
char *display_name; /* "host:display" string used on this connect */
int default_screen; /* default screen for operations */
int nscreens; /* number of screens on this server*/
Screen *screens; /* pointer to list of screens */
int motion_buffer; /* size of motion buffer */
Window current; /* for use internally for KeymapNotify */
int min_keycode; /* minimum defined keycode */
int max_keycode; /* maximum defined keycode */
KeySym *keysyms; /* this server's keysyms */
XModifierKeymap *modifiermap; /* this server's modifier keymap */
int keysyms_per_keycode; /* number of rows */
char *xdefaults; /* contents of defaults from server */
char *scratch_buffer; /* place to hang scratch buffer */
unsigned long scratch_length; /* length of scratch buffer */
int ext_number; /* extension number on this display */
_XExtension *ext_procs; /* extensions initialized on this display */
/*
* The following can be fixed size, as the protocol defines how much
* address space is available. While this could be done using the
* extension vector, there may be MANY events processed, so a search
* through the extension list to find the right procedure for each
* event might be expensive if many extensions are being used.
*/
Bool (*event_vec [128])(); /* vector for wire to event */
Status (*wire_vec[128])(); /* vector for event to wire */
} Display;
/*
* Information about the screen
*/
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
struct _XDisplay *display; /* back pointer to display structure */
Window root; /* root window ID */
int width, height; /* width and height of screen */
int mwidth, mheight; /* width and height of in millimeters */
int ndepths; /* number of depths possible */
Depth *depths; /* list of allowable depths on the screen */
int root_depth; /* bits per pixel */
Visual *root_visual; /* root visual */
GC default_gc; /* GC for the root root visual */
Colormap cmap; /* default colormap */
unsigned long white_pixel;
unsigned long black_pixel; /* white and black pixel values */
int max_maps, min_maps; /* max and min colormaps */
int backing_store; /* Never, WhenMapped, Always */
Bool save_unders;
long root_input_mask; /* initial root input mask */
} Screen;
/*
/* Format structure; describes ZFormat data the screen will understand
*/
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
int depth; /* depth of this image format */
int bits per_pixel; /* bits/pixel at this depth */
int scanline_pad; /* scan line must padded to this multiple */
} ScreenFormat;
Related Commands
XFree, XCloseDisplay, XNoOp, DefaultScreen.
XParseColor
—Xlib - Color Cells
Name
XParseColor — look up or translate RGB values from ASCII color name or 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 pointer to the Display structure; returned from XOpenDisplay. |
| cmap | 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 actual values from the 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 character 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 hexadecimal specification, and sets its DoRed, DoGreen and DoBlue flags. |
Description
XParseColor returns the RGB values corresponding to the English color name or hexadecimal 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 significant bits of the value. For example, #3a7 is the same as #3000a0007000. The colormap is used to determine which screen to look up the color on. The screen's default colormap is a reliable choice.
This routine will fail and return a Status of 0 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 0 on failure, 1 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
BadColor
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XQueryColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XParseGeometry
—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 | |
| width | Return the width and height in pixels from the string. |
| height |
Description
By convention, X applications use a standard string 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 <> 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, WidthValue, HeightValue, XNegative, and YNegative, and are defined in <X11/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.
XPeekEvent
Xlib - 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 pointer to the Display structure; 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 output 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 XPeekIfEvent. In Release 2, XEventsQueued can perform the function of either QLength or XPending and more.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XPeekIfEvent
—Xlib - Input Handling
Name
XPeekIfEvent — get an event without removing it from the queue; do not wait.
Synopsis
XPeekIfEvent (display, event, predicate, args) Display *display; XEvent *event; /* RETURN */ Bool (*predicate) () ; char *args;
Arguments
| display | Specifies a pointer to the Display structure; 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
XPeekIfEvent 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.
XPeekIfEvent flushes the output buffer if no matching events could be found on the queue, and then waits for the next matching event.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XPending
Xlib - Input Handling—
Name
XPending — flush the output buffer and return the number of pending input events.
Synopsis
int XPending (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XPending returns the number of input events that have been received from the server, but not yet removed from the queue. If there are no events on the queue, XPending flushes the output 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 output buffer first.
For more information, see Volume One, Chapter 8, Events.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XSynchronize, XSendEvent, QLength.
Xpermalloc
—Xlib - Resource Manager
Name
Xpermalloc — allocate memory never to be freed.
Synopsis
char *Xpermalloc (size) unsigned int size;
Arguments
| size | 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. Xpermalloc is used by some toolkits for permanently allocated storage and allows some performance and space savings over the completely general memory allocator.
XPointInRegion
Xlib - Regions—
Name
XPointInRegion — determine if a point is inside a region.
Synopsis
int XPointInRegion (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
XPointInRegion 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
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct_XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XPolygonRegion
—Xlib - Regions
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 location 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 (xoffset + clip_x_origin, yoffset + clip_y_origin), where xoffset and yoffset 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
typedef struct {
short x,y;
} XPoint;
/*
* opaque reference to Regiondata type.
* user won't need contents, only pointer.
*/
typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XPutBackEvent
—Xlib - Input Handling
Name
XPutBackEvent — push an event back on the input queue.
Synopsis
XPutBackEvent (display, event) Display *display; XEvent *event;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| event | 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 next 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
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPending, XSynchronize, XSendEvent, QLength.
XPutImage
Xlib - Images—
Name
XPutImage — draw a rectangular image on a window or pixmap.
Synopsis
XPutImage (display, drawable, gc, image, src_x, src_y, dst_x, dst_y, width, height) Display *display; Drawable drawable; GC gc; XImage *image; int src_x, src_y; int dst_x, dst_y; unsigned int width, height;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| 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, relative to the origin of the image. |
| src_y | |
| dst_x | Specify the x and y coordinates, relative to the origin of the drawable, where the upper-left corner of the copied rectangle will be placed. |
| dst_y | |
| width
height |
Specify the width and height in pixels of the rectangular area to be copied. |
Description
XPutImage 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.
XPutImage uses these graphics context components: function, plane_mask, subwindow_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 and the image must be XYFormat, otherwise a BadMatch error is generated. The foreground pixel in gc defines the source for set bits in the image, and the background pixel defines the source for the bits set to 0.
For XYPixmap and ZPixmap format images, the depth of the image must match the depth of drawable. For XYPixmap, the image must be sent in XYFormat. For ZPixmap, the image must be sent in the ZFormat defined for the given depth.
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
XDestroyImage, XGetImage, XCreateImage, XSubImage, XGetSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XPutPixel
Xlib - Images—
Name
XPutPixel — set a pixel value in an image.
Synopsis
int XPutPixel (ximage, x, y, pixel) XImage *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 the image. |
| y | |
| 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 (upper left [0,0]) of the image. The input pixel value must be in normalized format (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;
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XSubImage, XGetSubImage, XAddPixel, XGetPixel, ImageByteOrder.
XQueryBestCursor
Xlib - Cursors—
Name
XQueryBestCursor — get the closest supported cursor sizes.
Synopsis
Status XQueryBestCursor (display, drawable, width, height, rwidth, rheight) Display *display; Drawable drawable; unsigned int width, height; unsigned int *rwidth, *rheight; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies a drawable that indicates which screen the cursor is to be used on. The best cursor may be different on different screens. |
| width
height |
Specify the preferred width and height, in pixels. |
| rwidth
rheight |
Return pointers to the closest supported cursor dimensions, in pixels, on the display 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 1 if the call succeeded in getting a supported size (may be the same or different from the specified size), or 0 if the call failed.
Errors
BadDrawable
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFreeCursor, XRecolorCursor, XQueryBestSize.
XQueryBestSize
—Xlib - Pixmaps and Tiles
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
| display | Specifies a pointer to the Display structure; 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
height |
Specify the preferred width and height in pixels. |
| rwidth
rheight |
Return the closest supported width and height, in pixels, available for the 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 TileShape 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 1 if the call succeeded in getting a supported size (may be the same or different from the specified size), or 0 if the call failed.
Errors
| BadDrawable | |
| BadMatch | InputOnly drawable for class TileShape or StippleShape. |
| BadValue |
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XQueryBestStipple
—Xlib - Pixmaps and Tiles
Name
XQueryBestStipple — obtain the best 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 pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies a drawable that tells the server which screen you want the best size for. |
| width
height |
Specify the preferred width and height in pixels. |
| rwidth
rheight |
Return the width and height, in pixels, of the stipple best supported by the 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 1 if the call succeeded in getting a supported size (may be the same or different from the specified size), or 0 if the call failed.
For more information on stipples, see Volume One, Chapter 5, The Graphics Context.
Errors
| BadDrawable | |
| BadMatch | InputOnly window. |
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XQueryBestTile
Xlib - Pixmaps and Tiles—
Name
XQueryBestTile — obtain the best 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 pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies a drawable that tells the server which screen you want the best size for. |
| width
height |
Specify the preferred width and height in pixels. |
| rwidth
rheight |
Return the width and height, in pixels, of the tile best supported by the display 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 InputOnly window cannot be used as the drawable.
XQueryBestTile returns 1 if the call succeeded in getting a supported size (may be the same or different from the specified size), or 0 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
XSetTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XQueryColor
—Xlib - Color Cells
Name
XQueryColor — obtain the RGB values and flags for a specified pixel value.
Synopsis
XQueryColor (display, cmap, colorcell_def) Display *display; Colormap cmap; XColor *colorcell_def; /* SEND and RETURN */
Arguments
| display | Specifies a pointer to the Display structure; 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 same structure, and the flags member of that structure is set to (DoRed | 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
| BadColor | |
| BadValue | Pixel not valid index into cmap. |
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColors, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XQueryColors
Xlib - Color Cells—
Name
XQueryColors — obtain RGB values for an array of pixel values.
Synopsis
XQueryColors (display, cmap, colorcell_defs, ncolors) Display *display; Colormap cmap; XColor colorcell_defs[ncolors]; /* SEND and RETURN */ int ncolors;
Arguments
| display | Specifies a pointer to the Display structure; 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 indicate which colorcell in the colormap to return, and the RGB values in that colorcell are returned in red, green, and blue. |
| ncolors | 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 | 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
| BadColor | |
| BadValue | Pixel not valid index into cmap. |
Note: if more than one pixel value is in error, the one reported is arbitrary.
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XStoreColor, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XQueryExtension
—Xlib - Extensions
Name
XQueryExtension — get extension information.
Synopsis
Bool XQueryExtension (display, name, major_opcode, first_event, first_error) Display *display; char *name; int *major_opcode; /* RETURN */ int *first_event; /* RETURN */ int *first_error; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| name | Specifies the name of the desired extension. 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. |
| 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. |
| first_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, 0 is returned. This opcode will appear in errors generated in the extension.
If the extension involves additional event types, the base event type code is returned in first_event. Otherwise, 0 is returned in first_event. The format of the events is specific to the extension.
If the extension involves additional error codes, the base error code is returned in first_error. Otherwise, 0 is returned. The format of additional data in the errors is specific to the extension.
See Volume One, Chapter 13, Other Programming Techniques, for more information on using extensions, and Volume One, Appendix C, Writing Extensions to X, for information on writing them.
Related Commands
XListExtensions, XFreeExtensionList.
XQueryFont
—Xlib - Fonts
Name
XQueryFont — return information about a loaded font.
Synopsis
XFontStruct *XQueryFont (display, font_ID) Display *display; XID font_ID;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| font_ID | Specifies either the font ID or the graphics context ID. You can declare the data type for this argument as either Font or GContext (both X IDs). |
Description
XQueryFont returns a pointer to the XFontStruct structure information associated with the font. This call is needed if you loaded the font with XLoadFont, but need the font information to place text. If the font hasn't been loaded, XQueryFont returns NULL.
If font_ID is declared as data type GContext (also a resource ID), this function queries the font stored in the GC specified by this ID. However, in this case the GContext ID will be the ID stored in the returned XFontStruct, and you can't use that ID in XSetFont or XUnloadFont, since it is not itself the ID of the font.
Use XFreeFontInfo to free this data. Use XLoadQueryFont to both load and get information about a font.
For more information on fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadAlloc
BadfFont
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* hint about direction font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XSetFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XQueryKeymap
—Xlib - Keyboard
Name
XQueryKeymap — obtain a bit vector for the current state of the keyboard.
Synopsis
XQueryKeymap (display, keys) Display *display; char keys [32]; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| keys | Returns an array of bytes that identifies which keys are pressed down. Each bit represents one key of the keyboard. |
Description
XQueryKeymap returns a bit vector for the logical state of the keyboard, where each bit set to 1 indicates that the corresponding key is currently pressed down. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the least significant bit in the byte representing key 8N. Note that the logical state may lag the physical state if device event processing is frozen due to a grab.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XQueryPointer
Xlib - Pointer—
Name
XQueryPointer — get the current pointer location.
Synopsis
Bool XQueryPointer (display, w, root, child, root_x, root_y, win_x, win_y, keys_buttons) Display *display; Window w; Window *root, *child; /* RETURN */ int *root_x, *root_y /* RETURN */ int *win_x, *win_y; /* RETURN */ unsigned int *keys_buttons; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies a window which indicates which screen the pointer position is returned for, and child will be a child of this window if pointer is inside a child. |
| root | Returns the root window ID the pointer is currently on. |
| child | Returns the ID of the child of w the pointer is located in, or 0 if it not in a child. |
| root_x
root_y |
Return the x and y coordinates of the pointer relative to the root's origin. |
| win_x
win_y |
Return the x and y coordinates of the pointer relative to the origin of window w. |
| keys_buttons | Returns the current state of the modifier keys and pointer buttons. This is a mask composed of the OR of any number of the following symbols: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask. |
Description
XQueryPointer gets the pointer coordinates relative to a window and relative to the root window, the root window ID and the child window ID (if any) the pointer is currently in, and the current state of modifier keys and buttons.
If XQueryPointer returns False, then the pointer is not on the same screen as w, child is None, and win_x and win_y are zero. However, root, root_x, and root_y are still valid. If XQueryPointer returns True, then the pointer is on the same screen as the window w, and all return values are valid.
The logical state of the pointer buttons and modifier keys can lag behind their physical state if device event processing is frozen due to a grab.
Errors
BadWindow
Related Commands
XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, XChangePointerControl.
XQueryTextExtents
Xlib - Text—
Name
XQueryTextExtents — query the server for string and font metrics.
Synopsis
int XQueryTextExtents (display, font_ID, string, nchars, direction, ascent, descent, overall) Display *display; XID font_ID; char *string; int nchars; int *direction; /* RETURN */ int *ascent, *descent; /* RETURN */ XCharStruct *overall; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| font_ID | Specifies the appropriate font ID previously returned by XLoadFont, or the GContext that specifies the font. |
| string | Specifies the character string for which metrics are to be returned. |
| nchars | Specifies the number of characters in the character string. |
| direction | Returns the direction the string would be drawn using the specified font. Either FontLeftToRight or FontRightToLeft. |
| ascent | Returns the maximum ascent for the specified font. |
| descent | Returns the maximum descent for the specified font. |
| overall | Returns the overall characteristics of the string. These are the sum of the width measurements for each character, the maximum ascent and descent, the minimum lbearing added to the width of all characters up to the character with the smallest lbearing, and the maximum rbearing added to the width of all characters up to the character with the largest rbearing. |
Description
XQueryTextExtents returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by XTextExtents, but it does not require a filled XFontInfo structure.
The returned ascent and descent should usually be used to calculate the line spacing, while the width, rbearing, and lbearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
overall. ascent is the maximum of the ascent metrics of all characters in the string. The overall.descent is the maximum of the descent metrics. The overall.width is the sum of the character-width metrics of all characters in the string. The overall.lbearing is the lbearing of the character in the string with the smallest lbearing plus the width of all the characters up to but not including that character. The overall. rbearing is the rbearing of the character in the string with the largest lbearing plus the width of all the characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
XQueryTextExtents returns 1 on success, 0 on failure.
Structures
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Errors
BadFont
BadGC
Related Commands
XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XQueryTextExtents16
Xlib - Text—
Name
XQueryTextExtents16 — query the server for string and font metrics of a 16-bit character string.
Synopsis
int XQueryTextExtents16 (display, font_ID, string, nchars, direction, ascent, descent, overall) Display *display; XID font_ID; XChar2b *string; int nchars; int *direction; /* RETURN */ int *ascent, *descent; /* RETURN */ XCharStruct *overall; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| font_ID | Specifies the appropriate font ID previously returned by XLoadFont, or the GContext that specifies the font. |
| string | Specifies the character string for which metrics are to be returned. |
| nchars | Specifies the number of characters in the character string. |
| direction | Returns the direction of painting in the specified font. Either FontLefttoRight or FontRighttoLeft. |
| ascent | Returns the maximum ascent in pixels for the specified font. |
| descent | Returns the maximum descent in pixels for the specified font. |
| overall | Returns the overall characteristics of the string. These are the sum of the width measurements for each character, the maximum ascent and descent, the minimum lbearing added to the width of all characters up to the character with the smallest lbearing, and the maximum rbearing added to the width of all characters up to the character with the largest rbearing. |
Description
XQueryTextExtents16 returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function queries the server and, therefore, suffers the round trip overhead that is avoided by XTextExtents16, but it does not require a filled XFontInfo structure.
The returned ascent and descent should usually be used to calculate the line spacing, while the width, rbearing, and lbearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
overall.ascent is the maximum of the ascent metrics of all characters in the string. The overall.descent is the maximum of the descent metrics. The overall.width is the sum of the character-width metrics of all characters in the string. The overall.lbearing is the lbearing of the character in the string with the smallest lbearing plus the width of all the characters up to but not including that character. The overall.rbearing is the rbearing of the character in the string with the largest lbearing plus the width of all the characters up to but not including that character.
For fonts defined with linear indexing rather than two-byte matrix indexing, the server interprets each XChar2b as a 16-bit number that has been transmitted with the most significant byte first. That is, byte 1 of the XChar2b is taken as the most significant byte.
If the font has no defined default character, then undefined characters in the string are taken to have all 0 metrics. XQueryTextExtents16 returns 1 on success, 0 on failure.
Structures
typedef struct { /* normal 16-bit characters are two bytes */
unsigned char byte1;
unsigned char byte2;
} XChar2b;
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Errors
BadFont
BadGC
Related Commands
XQueryTextExtents, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth, XTextWidth16.
XQueryTree
Xlib - Window Manipulation—
Name
XQueryTree — return a list of children, parent, and root.
Synopsis
Status XQueryTree (display, w, root, parent, children, nchildren) Display *display; Window w; Window *root; /* RETURN */ Window *parent; /* RETURN */ Window **children; /* RETURN */ unsigned int *nchildren; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be queried. For this window, XQueryTree will list its children, its root, its parent, and the number of children. |
| root | Returns the root ID for the specified window. |
| parent | Returns the parent window of the specified window. |
| children | Returns the list of children associated with the specified window. |
| nchildren | Returns the number of children associated with the specified window. |
Description
XQueryTree uses its last four arguments to return the root ID, the parent ID, a pointer to a list of children and the number of children in that list, all for the specified window w. The children are listed in current stacking order, from bottommost (first) to topmost (last). XQueryTree returns 0 if it fails, 1 if it succeeds.
You should deallocate the list of children with XFree when it is no longer needed.
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow.
XRaiseWindow
—Xlib - Window Manipulation
Name
XRaiseWindow — raise a window to the top of the stacking order.
Synopsis
XRaiseWindow (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be raised to the top of the stack. |
Description
XRaiseWindow moves a window to the top of the stacking order among its siblings. If the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack, while leaving its x and y location on the desk constant.
Raising a mapped window may generate exposure events for that window and any mapped subwindows of that window that were formerly obscured.
If the override_redirect attribute of the window (see Volume One, Chapter 4, Window Attributes) is False and some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing is performed.
Errors
BadWindow
Related Commands
XLowerWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XReadBitmapFile
Xlib - Pixmaps and Tiles—
Name
XReadBitmapFile — read a bitmap from disk.
Synopsis
int XReadBitmapFile (display, drawable, filename, width, height, bitmap, x_hot, y_hot) Display *display; Drawable drawable; char *filename; unsigned int *width, *height; /* RETURN */ Pixmap *bitmap; /* RETURN */ int *x_hot, *y_hot; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| drawable | Specifies the drawable. |
| filename | Specifies the filename to use. The format of the filename is operating system specific. |
| width
height |
Return the dimensions in pixels of the bitmap that is read. |
| bitmap | Returns the pixmap resource ID that is created. |
| x_hot
y_hot |
Return the hotspot coordinates in the file (or −1,−1 if none present). |
Description
XReadBitmapFile reads in a file containing a pixmap of depth 1 (a bitmap). The file can be either in the standard X Version 10 format or in the newer X Version 11 bitmap format (which is only slightly different).
XReadBitmapFile creates a pixmap of the appropriate size, reads the bitmap data from the file into the pixmap. The caller must free the bitmap using XFreePixmap when done.
If the file cannot be opened, XReadBitmapFile returns BitmapOpenFailed. If the file can be opened but does not contain valid bitmap data, XReadBitmapFile returns BitmapFileInvalid. If insufficient working storage is allocated, XReadBitmapFile returns BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns BitmapSuccess.
Here is an X Version 11 example bitmap file:
#define name_width 16
#define name_height 16
#define name_x_hot 8
#define name_y_hot 8
static char name_bits[] = {
0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc,
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd,
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f};
For more information, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XCreateBitmapFromData.
XRebindKeysym
Xlib - Keyboard—
Name
XRebindKeysym — rebind a keysym to a string for client.
Synopsis
XRebindKeysym (display, keysym, mod_list, mod_count, string, num_bytes) Display *display; KeySym keysym; KeySym *mod_list; int mod_count; unsigned char *string; int num_bytes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| keysym | Specifies the keysym to be rebound. |
| mod_list | Specifies a pointer to an array of keysyms that are being used as modifiers. |
| mod_count | Specifies the number of modifiers in the modifier list. |
| string | Specifies a pointer to the string that is to be copied and returned by XLookupString. |
| num_bytes | Specifies the length of the string. |
Description
XRebindKeysym binds the ASCII string to the specified keysym, so that string and keysym are returned when that key is pressed and the modifiers specified in mod_list are also being held down. This function rebinds the meaning of a keysym for a client. It does not redefine the keycode in the server but merely provides an easy way for long strings to be attached to keys. Note that you are allowed to rebind a keysym that may not exist.
See Volume One, Chapter 9, The Keyboard and Pointer, for a description of keysyms and keyboard mapping.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XRecolorCursor
—Xlib - Cursors
Name
XRecolorCursor — change the color of a cursor.
Synopsis
XRecolorCursor (display, cursor, foreground_color, background_color) Display *display Cursor cursor; XColor *foreground_color, *background_color;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cursor | Specifies the cursor ID. |
| foreground_color | Specifies the red, green, and blue (RGB) values for the foreground. |
| background_color | Specifies the red, green, and blue (RGB) values for the background. |
Description
XRecolorCursor applies a foreground and background color to a cursor. Cursors are normally created using a single plane pixmap, composed of 0's and 1's, with one pixel value assigned to 1's and another assigned to 0's. XRecolorCursor changes these pixel values. If the cursor is being displayed on a screen, the change is visible immediately. On some servers, these color selections are read/write cells from the colormap, and can't be shared by applications.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
BadCursor
Related Commands
XDefineCursor, XUndefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFreeCursor, XQueryBestCursor, XQueryBestSize.
XRectInRegion
Xlib - Regions—
Name
XRectInRegion — determine if a rectangle resides in a region.
Synopsis
int XRectInRegion (r, x, y, width, height) Region r; int x, y; unsigned int width, height;
Arguments
| r | Specifies the region. |
| x
y |
Specify the x and y coordinates of the upper-left corner of the rectangle, relative to the region's origin. |
| width
height |
Specify the width and height in pixels of the rectangle. |
Description
XRectInRegion returns RectangleIn if the rectangle is completely contained in the region r, RectangleOut if it is completely outside, and RectanglePart if it is partially inside.
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 clip_mask by calling XSetRegion, the upper-left corner of region relative to the drawable used in the graphics request will be at (xoffset + clip_x_origin, yoffset + clip_y_origin), where xoffset and yoffset are the offset of the region and clip_x_origin and clip_y_origin are the clip origin in the GC used.
For this function, the x and y arguments are interpreted relative to the region origin, not the drawable origin.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XRefreshKeyboardMapping
—Xlib - Keyboard
Name
XRefreshKeyboardMapping — update the stored modifier and keymap information.
Synopsis
XRefreshKeyboardMapping(event) XMappingEvent *event;
Arguments
| event | Specifies the mapping event that is to be used. |
Description
XRefreshKeyboardMapping causes the library to update the mapping between keycodes and keysyms. This updates the client application's knowledge of the keyboard.
You usually want to call XRefreshKeyboardMapping when a MappingNotify event occurs. MappingNotify events occur when some client has called XChangeKeyboardMapping.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Structures
typedef struct {
int type;
Display *display; /* display the event was read from */
Window window; /* unused */
int request; /* one of MappingModifier, MappingKeyboard,
MappingPointer */
int first_keycode; /* first keycode */
int count; /* defines range of change with first_keycode*/
} XMappingEvent;
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XRemoveFromSaveSet
Xlib - Save Set—
Name
XRemoveFromSaveSet — remove a window's children from the client's save-set.
Synopsis
XRemoveFromSaveSet (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window whose children you want to remove from this client's save-set. This window must have been created by a client other than the client making this call. |
Description
XRemoveFromSaveSet removes a window's children from the save-set of the calling application. Usually, this call is invoked by a window manager, using the Rootwindow macro for w, to remove all top-level windows on a screen from the save-set.
The save-set is a safety net for windows that have been reparented by the window manager, usually to provide a shadow or other background for each window. When the window manager dies unexpectedly, the windows in the save-set are reparented to their closest living ancestor, so that they remain alive.
This call is not necessary when a window is destroyed since destroyed windows are automatically removed from the save-set. See Volume One, Chapter 14, Window Management, for more information about save-sets.
Errors
| BadMatch | w not created by some other client. |
| BadWindow |
Related Commands
XAddToSaveSet, XChangeSaveSet.
XRemoveHost
—Xlib - Host Access
Name
XRemoveHost — remove a host from the access control list.
Synopsis
XRemoveHost (display, host) Display *display; XHostAddress *host;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| host | Specifies the network address of the machine to be removed. |
Description
XRemoveHost removes the specified host from the access control list on the host running the server controlling the current display. The display hardware must be on the same host as the calling process in order to change the access control list.
If you remove your own machine from the access control list, you can no longer connect to that server, and there is no way back from this call other than to log out and reset the server.
The address data must be a valid address for the type of network in which the server operates, as specified in the family member.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte.
For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
int family; /* for example Family Internet */
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the bytes */
} XHostAddress;
/* constants used for family member of XHostAddress */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHosts, XDisableAccessControl, XEnableAccessControl, XSetAccessControl.
XRemoveHosts
—Xlib - Host Access
Name
XRemoveHosts — remove multiple hosts from the access control list.
Synopsis
XRemoveHosts (display, hosts, num_hosts) Display *display XHostAddress *hosts; int num_hosts;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| hosts | Specifies the list of hosts that are to be removed. |
| num_hosts | Specifies the number of hosts that are to be removed. |
Description
XRemoveHosts removes each specified host from the access control list on the local machine running the server. The display hardware must be on the same host as the client process, in order to change the access control list.
If you remove your machine from the access control list, you can no longer connect to that server, and there is no way back from this call except to log out and reset the server.
The address data must be a valid address for the type of network in which the server operates, as specified in the family member.
For TCP/IP, the address should be in network byte order. For the DECnet family, the server performs no automatic swapping on the address bytes. A Phase IV address is two bytes long. The first byte contains the least significant eight bits of the node number. The second byte contains the most significant two bits of the node number in the least significant two bits of the byte, and the area in the most significant six bits of the byte.
For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef struct {
int family; /* for example Family Internet */
int length; /* length of address, in bytes */
char *address; /* pointer to where to find the bytes */
} XHostAddress;
/* constants used for family member of XHostAddress */
#define FamilyInternet 0
#define FamilyDECnet 1
#define FamilyChaos 2
Errors
BadAccess
BadValue
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XDisableAccessControl, XEnableAccessControl, XSetAccessControl.
XReparentWindow
—Xlib - Window Manipulation
Name
XReparentWindow — insert a window between another window and its parent.
Synopsis
XReparentWindow (display, win, parent, x, y) Display *display; Window win; Window parent; int x, y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| win | Specifies the ID of the window to be reparented. |
| parent | Specifies the window ID of the new parent window. |
| x
y |
Specify the coordinates of the window relative to the new parent. |
Description
XReparentWindow modifies the window hierarchy by placing window win as a child of window parent. This function is usually used by a window manager to put a decoration window behind application windows. In the case of the window manager, the new parent window must first be created as a child of the root window.
If win is mapped, an XUnmapWindow request is performed on it automatically, win is then removed from its current position in the hierarchy, and is inserted as a child of the specified parent, win is placed on top in the stacking order with respect to siblings.
A ReparentNotify event is then generated. The override_redirect member of the structure returned by this event is set to either True or False. Window manager clients normally should ignore this event if this member is set to True.
Finally, if the window was originally mapped, an XMapwindow request is performed automatically.
Descendants of win remain descendants of win; they are not reparented to the old parent of win.
Normal exposure processing on formerly obscured windows is performed. The server might not generate exposure events for regions from the initial unmap that are immediately obscured by the final map. The request fails if the new parent is not on the same screen as the old parent, or if the new parent is the window itself or an inferior of the window.
Errors
| BadMatch | parent not on same screen as old parent of win. |
| win has a ParentRelative background and parent is not the same depth as win. | |
| parent is win or an inferior of win. | |
| BadWindow |
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XConfigureWindow, XQueryTree.
XResetScreenSaver
—Xlib - Screen Saver
Name
XResetScreenSaver — reset the screen saver.
Synopsis
XResetScreenSaver (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XResetScreenSaver redisplays the screen if the screen saver was activated. This may result in exposure events to all visible windows if the server cannot save the screen contents. If the screen is already active, nothing happens.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XForceScreenSaver, XActivateScreenSaver, XGetScreenSaver, XSetScreenSaver.
XResizeWindow
Xlib - Window Manipulation—
Name
XResizeWindow — change a window's size.
Synopsis
XResizeWindow (display, w, width, height) Display *display; Window w; unsigned int width, height;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to be resized. |
| width
height |
Specify the new dimensions of the window in pixels. |
Description
XResizeWindow changes the inside dimensions of the window. The border is resized to match but its width is not changed. XResizeWindow does not raise the window, or change its origin. Changing the size of a mapped window may lose its contents and generate an Expose event, depending on the bit_gravity attribute (see Volume One, Chapter 4, Window Attributes). If a mapped window is made smaller, exposure events will be generated on windows that it formerly obscured.
If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing is performed.
If some other client has selected StructureNotifyMask on the window, then a ConfigureNotify event is generated after the move takes place, and the event will contain the final size of the window.
Errors
BadValue
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XRestackWindows
—Xlib - Window Manipulation
Name
XRestackWindows — change the stacking order of siblings.
Synopsis
XRestackWindows (display, windows, nwindows); Display *display; Window windows[]; int nwindows;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| windows | Specifies an array containing the windows to be restacked. All the windows must have a common parent. |
| nwindows | Specifies the number of windows to be restacked. |
Description
XRestackWindows restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the windows array will be on top, and the other windows will be stacked underneath it in the order of the array. Note that other siblings may not be included in the windows array and so the top window in that array will not move relative to these other siblings.
For each window in the window array that is not a child of the specified window, a BadMatch error will be generated. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, then ConfigureRequest events are generated for each window whose override_redirect is not set, and no further processing is performed. Otherwise, the windows will be restacked in top to bottom order.
Errors
BadMatch
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XrmGetFileDatabase
Xlib - Resource Manager—
Name
XrmGetFileDatabase — retrieve a database from a file.
Synopsis
XrmDatabase XrmGetFileDatabase(filename) char *filename;
Arguments
filename Specifies the resource database filename.
Description
XrmGetFileDatabase opens the specified file, creates a new resource database, and loads it with the data read in from the file. The return value of the function is subsequently used as a pointer to the created database.
The specified file must contain lines in the format accepted by XrmPutLineResource. If it cannot open the specified file, XrmGetFileDatabase returns NULL.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmGetResource
—Xlib - Resource Manager
Name
XrmGetResource — get a resource from name and class as strings.
Synopsis
Bool XrmGetResource (database, str_name, str_class, str_type, value) XrmDatabase database; char *str_name; char *str_class; char **str_type; /* RETURN */ XrmValue *value; /* RETURN */
Arguments
| database | Specifies the database that is to be used. |
| str_name | Specifies the fully qualified name of the value being retrieved (as a string). str_name is an instance of a name retrieval key as described below. |
| str_class | Specifies the fully qualified class of the value being retrieved (as a string). str_class is an instance of a class retrieval key as described below. |
| str_type | Returns a pointer to the representation type of the destination. In this function, the representation type is itself represented as a string, not as an XrmRepresentation. |
| value | Returns the value in the database. Do not modify or free this data. |
Description
The resource manager manages databases of resources consisting of lines containing resource name/class strings followed by a colon and the value of the resource. XrmGetResource retrieves a resource from the specified database. It takes fully qualified name and class strings, and returns the representation and value of the matching resource. The value returned points into database memory; therefore, you must not modify that data. If a resource was found, XrmGetResource returns True. Otherwise, it returns False.
Currently, the database only frees or overwrites entries when new data is stored with XrmMergeDatabases, or XrmPutResource and related routines. A client that avoids these functions should be safe using the address passed back at any time until it exits.
XrmGetResource is very similar to XrmQGetResource, except that in XrmQGetResource, the equivalent arguments to str_name, str_class, and str_type are quarks instead of strings.
To understand how data is stored and retrieved from the database, you must understand:
1) The basic components that make up the storage key and retrieval keys.
2) How keys are made up from components.
3) The two ways that components can be bound together.
4) What sort of keys are used to store and retrieve data.
5) How the storage key and retrieval keys are compared to determine whether they match.
6) If there are multiple matches, how the best match is chosen so only that corresponding value is returned.
Each will be covered in turn.
1) The storage key and retrieval keys are composed of a variable number of components, bound together. There are two types of components: names and classes. By convention, names begin with a lower case character and classes begin with an upper case character. Therefore, xmh, background, and toc are examples of names, while Xmh, Box, and Command are examples of classes. A name key (like str_name) consists purely of name components. A class key (like str_class) consists purely of class components. The retrieval keys are a pair of keys, one composed of purely name components, the other of purely class components. A storage key (like specifier in XrmPutResource) consists of a mixture of name and class components.
2) A key is composed of multiple components bound together in sequence. This allows you to build logical keys for your application. For example, at the top level, the application might consist of a paned window (that is, a window divided into several sections) named toc. One pane of the paned window is a button box window named buttons filled with command buttons. One of these command buttons is used to retrieve (include) new mail and has the name include. This window has a fully qualified name xmh.toc.buttons.include and a fully qualified class Xmh.VPaned.Box.Command. Its fully qualified name is the name of its parent, xmh.toc.buttons, followed by its name include. Its class is the class of its parent, Xmh.VPaned.Box, followed by its particular class, Command.
3) The components in a key can be bound together in two ways: by a tight binding (a dot “.”) or by a loose binding (an asterisk “*”). Thus xmhtoc.background has three name components tightly bound together, while Xmh*Command.foreground uses both a loose and a tight binding. Bindings can also precede the first component (but may not follow the last component). By convention, if no binding is specified before the first component, a tight binding is assumed. For example, xmh.background and .xmh.background both begin with tight bindings before the xmh, while *xmh.background begins with a loose binding.
The difference between tight and loose bindings comes when comparing two keys. A tight binding means that the components on either side of the binding must be sequential. A loose binding is a sort of wildcard, meaning that there may be unspecified components between the two components that are loosely bound togehter. For example, xmh.toc.background would match xmh*background and *background but not xmh.background or background.
4) A key used to store data into the database can use both loose and tight bindings. This allows you to specify a data value which can match to many different retrieval keys. In contrast, keys used to retrieve data from the database can use only tight bindings. You can only look up one item in the database at a time. Remember also that a storage key can mix name and class components, while the retrieval keys are a pair of keys, one consisting purely of name (first character lower case) components and one consisting purely of class (capitalized) components.
5) The resource manager must solve the problem of how to compare the pair of retrieval keys to a single storage key. (Actually, to many single storage keys, since the resource manager will compare the retrieval keys against every key in the database, but one at a time.) The solution of comparing a pair of keys to a single key is simple. The resource manager compares component by component, comparing a component from the storage key against both the corresponding component from the name retrieval key, and the corresponding component from the class retrieval key. If the storage key component matches either retrieval key component, then that component is considered to match. For example, the storage key xmh.toc.Foreground matches the name key xmh.toc.foreground with the class key Xmh.Box.Foreground. This is why storage keys can mix name and class components, while retrieval keys cannot.
6) Because the resource manager allows loose bindings (wildcards) and mixing names and classes in the storage key, it is possible for many storage keys to match a single name/class retrieval key pair. To solve this problem, the resource manager uses the following precedence rules to determine which is the best match (and only the value from that match will be returned). The precedence rules arc, in order of preference:
- The attribute of the name and class must match. For example, queries for
xterm.scrollbar.background (name) XTerm.Scrollbar.Background (class)
will not match the following database entry:
xterm.scrollbar: onbecause background does not appear in the database entry.
- Database entries with name or class prefixed by a dot (.) are more specific than those prefixed by an asterisk (*). For example, the entry xterm.geometry is more specific than the entry xterm*geometry.
- Names are more specific than classes. For example, the entry *scrollbar.background is more specific than the entry *Scrollbar. Background.
- A name or class is more specific than omission. For example, the entry Scrollbar*Background is more specific than the entry *Background.
- Left components are more specific than right components. For example, to query for .xterm.scrollbar.background, the entry xterm*background is more specific than the entry scrollbar*background.
Names and classes can be mixed. As an example of these rules, assume the following user preference specification:
xmh*background: red
*command.font: 8x13
*command.background: blue
*Command.Foreground: green
xmh.toc*Command.activeForeground: black
A query for the name xmh.toc.messagefunctions.include.activeForeground and class Xmh.VPaned.Box.Command.Foreground would match xmh.toc*Command.activeForeground and return black. However, it also matches *Command.Foreground but with lower preference, so it would not return green.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue;
Related Commands
XrmGetFileDatabase, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmGetStringDatabase
—Xlib - Resource Manager
Name
XrmGetStringDatabase — create a database from a string.
Synopsis
XrmDatabase XrmGetStringDatabase (data) char *data;
Arguments
| data | Specifies the database contents using a string. |
Description
XrmGetStringDatabase creates a new database and stores in it the resources specified in data. The return value is subsequently used to refer to the created database. XrmGetStringDatabase is similar to XrmGetFileDatabase, except that it reads the information out of a string instead of a file. Each line is separated by a new line character in the format accepted by XrmPutLineResource.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmInitialize
Xlib - Resource Manager—
Name
XrmInitialize — initialize the resource manager.
Synopsis
void XrmInitialize ( );
Description
XrmInitialize initializes the resource manager, and should be called once before using any other resource manager functions. All it does is to create a representation type of “String” for values defined as strings. This representation type is used by XrmPutStringResource and XrmQPutStringResource, which require a value as a string. See XrmQPutResource for a description of representation types.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmMergeDatabases
—Xlib - Resource Manager
Name
XrmMergeDatabases — merge the contents of one database with another.
Synopsis
void XrmMergeDatabases (source_db, target_db) XrmDatabase source_db, *target_db;
Arguments
| source_db | Specifies the descriptor of the resource database to be merged into the existing database. |
| target_db | Specifies a pointer to the descriptor of the resource database into which the source_db database will be merged. |
Description
XrmMergeDatabases overwrites entries in the destination database. This procedure is used to combine databases, for example, an application specific database of defaults and a database of user preferences. The merge is destructive; it destroys the original source_db database and modifies the original target_db.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmParseCommand
Xlib - Resource Manager—
Name
XrmParseCommand — load a resource database from command line arguments.
Synopsis
void XrmParseCommand (db, table, table_count, name, argc, argv) XrmDatabase *db; XrmOptionDescList table; int table_count; char *name; int *argc; /* SEND and RETURN */ char **argv; /* SEND and RETURN */
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| table | Specifies table of command line arguments to be parsed. |
| table_count | Specifies the number of entries in the table. |
| name | Specifies the application name. |
| argc | Before the call, specifies the number of arguments. After the call, returns the number of arguments not parsed. |
| argv | Before the call, specifies a pointer to the command line arguments. After the call, returns a pointer to a string containing the command line arguments that could not be parsed. |
Description
XrmParseCommand parses an (argc, argv) pair according to the specified option table, loads recognized options into the specified database, and modifies the (argc, argv) pair to remove all recognized options.
The specified table is used to parse the command line. Recognized entries in the table are removed from argv, and entries are made in the specified resource database. The table entries contain information on the option string, the option name, which style of option and a value to provide if the option kind is XrmoptionNoArg. See the example table below.
argc specifies the number of arguments in argv and is set to the remaining number of arguments that were not parsed. name should be the name of your application for use in building the database entry, name is prepended to the resourceName in the option table before storing the specification. No separating (binding) character is inserted. The table must contain either a dot (“.”) or an asterisk (“*”) as the first character in each resourceName entry. The resourceName entry can contain multiple components.
The following is a typical options table:
static XrmOptionDescRec opTable[ ] = {
{"-background", "*background", XrmoptionSepArg, (caddr_t) NULL},
{"-bd", "*borderColor", XrmoptionSepArg, (caddr_t) NULL},
{"-bg", "*background", XrmoptionSepArg, (caddr_t) NULL},
{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (caddr_t) NULL},
{"-bordercolor", "*borderColor", XrmoptionSepArg, (caddr_t) NULL},
{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (caddr_t) NULL},
{"-display", ".display", XrmoptionSepArg, (caddr_t) NULL},
{"-fg", "*foreground", XrmoptionSepArg, (caddr_t) NULL},
{"-fn", "*font", XrmoptionSepArg, (caddr_t) NULL},
{"-font", "*font", XrmoptionSepArg, (caddr_t) NULL},
{"-foreground", "*foreground", XrmoptionSepArg, (caddr_t) NULL},
{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (caddr_t) NULL},
{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (caddr_t) "on"),
{"-name ", ".name", XrmoptionSepArg, (caddr_t) NULL},
{"-reverse", "*reverseVideo", XrmoptionNoArg, (caddr_t) "on"},
{"-rv", "*reverseVideo", XrmoptionNoArg, (caddr_t) "on"},
{"-synchronous", ".synchronous". XrmoptionNoArg, (caddr_t) "on"},
{"-title", ".TopLevelShell.title", XrmoptionSepArg, (caddr_t) NULL},
{"-xrm", NULL, XrmoptionResArg, (caddr_t) NULL},
};
In this table, if the -background (or -bg) option is used to set background colors, the stored resource specifier will match all resources of attribute background. If the -borderwidth option is used, the stored resource specifier applies only to border width attributes of class TopLevelShell (that is, outermost windows, including pop-up windows). If the -title option is used to set a window name, only the topmost application windows receive the resource.
When parsing the command line, any unique unambiguous abbreviation for an option name in the table is considered a match for the option. Note that upper case and lower case matter.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef enum {
XrmoptionNoArg, /* value is specified in OptionDescRec.value */
XrmoptionIsArg, /* value is the option string itself */
XrmoptionStickyArg, /* value is chars immediately following option */
XrmoptionSepArg, /* value is next argument in argv */
XrmoptionResArg, /* resource and value in next argument in argv */
XrmoptionSkipArg, /* ignore this option and next argument in argv */
XrmoptionSkipLine /* ignore this option and the rest of argv */
} XrmOptionKind;
typedef struct {
char *option; /* option specification string in argv */
char *resourceName; /* binding & resource name (w/out application name) */
XrmOptionKind argKind; /* which style of option it is */
caddr_t value; /* value to provide if XrmoptionNoArg */
} XrmOptionDescRec, *XrmOptionDescList;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmPutFileDatabase
—Xlib - Resource Manager
Name
XrmPutFileDatabase — store a database in a file.
Synopsis
void XrmPutFileDatabase (database, stored_db) XrmDatabase database; char *stored_db;
Arguments
| database | Specifies the database that is to be saved. |
| stored_db | Specifies the filename for the stored database. |
Description
XrmPutFileDatabase stores a copy of the application's current database in the specified file. The file is an ASCII text file that contains lines in the format that is accepted by XrmPutLineResource.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmPutLineResource
Xlib - Resource Manager—
Name
XrmPutLineResource — add a resource entry given as a string of name and value.
Synopsis
void XrmPutLineResource (database, line) XrmDatabase *database; /* SEND, and if NULL, RETURN */ char *line;
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| line | Specifies the resource name and value pair as a single string, in the format resource: value. A single colon (“:”) separates the resource name from the value, for example, xterm*background: green\n. |
Description
XrmPutLineResource adds a single resource entry to the specified database.
XrmPutLineResource is similar to XrmPutStringResource, except that instead of having separate string arguments for the resource and its value, XrmPutLineResource takes a single string argument (line) which consists of the resource name, a colon, then the value. Since the value is a string, it is stored into the database with representation type String.
Any whitespace before or after the name or colon in the line argument is ignored. The value is terminated by a new-line or a NULL character. The value may contain embedded new-line characters represented by the “\” and “n” two character pair (not the single “\n” character), which are converted into a single linefeed character. In addition, the value may run over onto the next line, this is indicated by a “\” character at the end of the line immediately preceding the “\n” character.
Null-terminated strings without a new line are also permitted. XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPutStringResource and XrmPutLineResource all store data into a database. See XrmQPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmPutResource
Xlib - Resource Manager—
Name
XrmPutResource — store a resource into a database.
Synopsis
void XrmPutResource (database, specifier, type, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ char *specifier; char *type; XrmValue *value;
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| specifier | Specifies a complete or partial specification of the resource. |
| type | Specifies the type of the resource. |
| value | Specifies the value of the resource. |
Description
XrmPutResource is one of several functions which store data into a database.
XrmQPutResource first converts specifier into a binding list and a quark list by calling XrmStringToBindingQuarkList, and converts type into an XrmRepresentation by calling XrmStringToRepresentation. Finally, it puts the data into the database.
XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPutStringResource and XrmPutLineResource all store data into a database. See the description of XrmQPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, *XrmValuePtr;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmPutStringResource
Xlib - Resource Manager—
Name
XrmPutStringResource — add a resource that is specified as a string.
Synopsis
void XrmPutStringResource (database, resource, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ char *resource; char *value;
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| resource | Specifies the resource as a string. |
| value | Specifies the value of the resource. The value is specified as a string. |
Description
XrmPutStringResource adds a resource with the specified value to the specified database. The resource string may contain both names and classes, bound with either loose (*) or tight (.) bindings. See the description of XrmGetResource for more information about bindings.
The representation type used in the database is String.
XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPutStringResource and XrmPutLineResource all store data into a database. See XrmQPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQGetResource
—Xlib - Resource Manager
Name
XrmQGetResource — get a resource from name and class as quarks.
Synopsis
Bool XrmQGetResource (database, quark_name, quark_class, quark_type, value) XrmDatabase database; XrmNameList quark_name; XrmClassList quark_class; XrmRepresentation *quark_type; /* RETURN */ XrmValue *value; /* RETURN */
Arguments
| database | Specifies the database that is to be used. |
| quark_name | Specifies the fully qualified name of the value being retrieved (as a list of quarks). |
| quark_class | Specifies the fully qualified class of the value being retrieved (as a list of quarks). |
| quark_type | Returns a pointer to the representation type of the destination. In this function, the representation type is itself represented as a quark. |
| value | Returns a pointer to the value in the database. Do not modify or free this data. |
Description
XrmQGetResource retrieves a resource from the specified database. It takes fully qualified name and class strings, and returns the representation and value of the matching resource. The value returned points into database memory; therefore, you must not modify that data. If a resource was found, XrmQGetResource returns True. Otherwise, it returns False.
Currently, the database only frees or overwrites entries when new data is stored with XrmMergeDatabases, or XrmPutResource and related routines. A client that avoids these functions should be safe using the address passed back at any time until it exits.
XrmQGetResource is very similar to XrmGetResource, except that in XrmGetResource, the equivalent arguments to quark_name, quark_class, and quark_type arguments are strings instead of quarks.
See XrmGetResource for a full description of how data is looked up in the database.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef XrmQuarkList XrmNameList;
typedef XrmQuarkList XrmClassList;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, *XrmValuePtr;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQGetSearchList
—Xlib - Resource Manager
Name
XrmQGetSearchList — return a list of database levels.
Synopsis
Bool XrmQGetSearchList (database, names, classes, search_list, list_length) XrmDatabase database; XrmNameList names; XrmClassList classes; XrmSearchList search_list; /* RETURN */ int list_length;
Arguments
| database | Specifies the database that is to be used. |
| names | Specifies a list of resource names. |
| classes | Specifies a list of resource classes. |
| search_list | Returns a search list for further use. The caller must allocate sufficient space for the list before calling XrmQGetSearchList. |
| list_length | Specifies the number of entries (not the byte size) allocated for list. |
Description
XrmQGetSearchList is a tool for searching the database more efficiently. It is used in combination with XrmGetSearchResource. Often, one searches the database for many similar resources which differ only in their final component (e.g. xmh.toc.foreground, xmh.toc.background, etc). Rather than looking for each resource in its entirety, XrmGetSearchList searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the search list. This search list is then used by XrmQGetSearchList, which searches for the last components one at a time. In this way, the common work of searching for similar resources is done only once, and the specific part of the search is done on the much shorter search list.
XrmQGetSearchList takes a list of names and classes and returns a list of database levels where a match might occur. The returned list is in best-to-worst order and uses the same algorithm as XrmGetResource for determining precedence. If search_list was large enough for the search list, XrmQGetSearchList returns True. Otherwise, it returns False.
The size of the search list that must be allocated by the caller is dependent upon the number of levels and wildcards in the resource specifiers that are stored in the database. The worst case length is 3n, where n is the number of name or class components in names or classes.
Only the common prefix of a resource name should be specified in the name and class list to XrmQGetSearchList. In the example above, the common prefix would be xmh.toc. However, note that XrmQGetSearchResource requires that name represent a single component only. Therefore, the common prefix must be all but the last component of the name and class.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef XrmQuarkList XrmNameList; typedef XrmQuarkList XrmClassList; typedef XrmQuark XrmRepresentation;
XrmSearchList is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQGetSearchResource
—Xlib - Resource Manager
Name
XrmQGetSearchResource — search resource database levels for a given resource.
Synopsis
Bool XrmQGetSearchResource (search_list, name, class, type, value) XrmSearchList search_list; XrmName name; XrmClass class; XrmRepresentation *type; /* RETURN */ XrmValue *value; /* RETURN */
Arguments
| search_list | Specifies the search list returned by XrmQGetSearchList. |
| name | Specifies the resource name. |
| class | Specifies the resource class. |
| type | Returns the data representation type. |
| value | Returns the value in the database. |
Description
XrmQGetSearchResource is a tool for searching the database more efficiently. It is used in combination with XrmGetSearchList. Often, one searches the database for many similar resources which differ only in their final component (e.g., xmh.toc.foreground, xmh.toc.background, etc). Rather than looking for each resource in its entirety, XrmGetSearchList searches the database for the common part of the resource name, returning a whole list of items in the database that match it. This list is called the search list. XrmQGetSearchResource searches the search list for the resource that is fully identified by name and class. The search stops with the first match. XrmQGetSearchResource returns True if the resource was found; otherwise, it returns False.
A call to XrmQGetSearchList with a name and class list containing all but the last component of a resource name followed by a call to XrmQGetSearchResource with the last component name and class returns the same database entry as XrmGetResource or XrmQGetResource would with the fully qualified name and class.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef XrmQuark XrmName;
typedef XrmQuark XrmClass;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, *XrmValuePtr;
XrmSearchList is a pointer to an opaque data type.
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQPutResource
—Xlib - Resource Manager
Name
XrmQPutResource — store a resource into a database using quarks.
Synopsis
void XrmQPutResource (database, bindings, quarks, type, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ XrmBindingList bindings; XrmQuarkList quarks; XrmRepresentation type; XrmValue *value;
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| bindings | Specifies a list of bindings for binding together the quarks argument. |
| quarks | Specifies the complete or partial name or class list of the resource to be stored. |
| type | Specifies the type of the resource. |
| value | Specifies the value of the resource. |
Description
XrmQPutResource stores a resource into the database.
database can be a previously defined database, as returned by XrmGetStringDatabase, XrmGetFileDatabase, or from XrmMergeDatabases. If database is NULL, a new database is created and a pointer to it returned in database.
bindings and quarks together specify where the value should be stored in the database. See XrmStringToBindingQuarkList for a brief description of binding and quark lists. See XrmGetResource for a description of the resource manager naming conventions and lookup rules.
type. is the representation type of value. This provides a way to distinguish between different representations of the same information. Representation types are user defined character strings describing the way the data is represented. For example, a color may be specified by a color name (“red”), or be coded in a hexadecimal string (“#4f6c84”) (if it is to be used as an argument to XParseColor.) The representation type would distinguish between these two. Representation types are created from simple character strings by using the macro XrmStringToRepresentation. The type XrmRepresentation is actually the same type as XrmQuark, since it is an ID for a string. The representation is stored along with the value in the database, and is returned when the database is accessed.
value is the value of the resource, specified as an XrmValue.
XrmGetResource contains the complete description of how data is accessed from the database, and so provides a good perspective on how it is stored.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList
typedef int XrmQuark, *XrmQuarkList;
typedef XrmQuarkList XrmNameList;
typedef XrmQuark XrmRepresentation;
typedef struct {
unsigned int size;
caddr_t addr;
} XrmValue, *XrmValuePtr;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseComrnand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQPutStringResource
—Xlib - Resource Manager
Name
XrmQPutStringResource — add a string resource value to a database using quarks.
Synopsis
void XrmQPutStringResource (database, bindings, quarks, value) XrmDatabase *database; /* SEND, and if NULL, RETURN */ XrmBindingList bindings; XrmQuarkList quarks; char *value;
Arguments
| database | Specifies a pointer to the resource database. If database contains NULL, a new resource database is created and a pointer to it is returned in database. |
| bindings | Specifies a list of bindings for binding together the quarks argument. |
| quarks | Specifies the complete or partial name or class list of the resource to be stored. |
| value | Specifies the value of the resource as a string. |
Description
XrmQPutStringResource stores a resource into the specified database.
XrmQPutStringResource is a cross between XrmQPutResource and XrmPutStringResource. Like XrmQPutResource, it specifies the resource by quarks and bindings, two lists that together make a name/class list with loose and tight bindings. Like XrmPutStringResource, it specifies the value to be stored as a string, that value is converted into an XrmValue, and the default representation type String is used.
XrmPutResource, XrmQPutResource, XrmPutStringResource, XrmQPutStringResource and XrmPutLineResource all store data into a database. See XrmQPutResource for the most complete description of this process.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
XrmDatabase is a pointer to an opaque data type.
typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList
typedef int XrmQuark, *XrmQuarkList;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmQuarkToString
Xlib - Resource Manager—
Name
XrmQuarkToString — convert a quark to a string.
Synopsis
char *XrmQuarkToString (quark) XrmQuark quark;
Arguments
| quark | Specifies the quark for which the equivalent string is desired. |
Description
XrmQuarkToString returns the string for which the quark is serving as a shorthand symbol. The quark was earlier set to represent the string by XrmStringToQuark. The string pointed to by the return value must not be modified or freed, because that string is in the data structure used by the resource manager for assigning quarks. If no string exists for that quark, these routines return NULL.
Quarks are used by the resource manager to represent strings. Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are presently represented by integers, comparing quarks is trivial.
The three #define statements in the Structures section provide an extra level of abstraction. They define macros so that names, classes and representations can also be represented as quarks.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark; /* macro definitions from <X11/resource.h> */ #define XrmNameToString(name) XrmQuarkToString(name) #define XrmClassToString(class) XrmQuarkToString(class) #define XrmRepresentationToString(type) XrmQuarkToString(type)
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmStringToBindingQuarkList
—Xlib - Resource Manager
Name
XrmStringToBindingQuarkList — convert a key string to a binding list and a quark list.
Synopsis
XrmStringToBindingQuarkList (string, bindings, quarks) char *string; XrmBindingList bindings; /* RETURN */ XrmQuarkList quarks; /* RETURN */
Arguments
| string | Specifies the string for which the list of quarks and list of bindings are to be generated. Must be NULL terminated. |
| bindings | Returns the binding list. The caller must allocate sufficient space for the binding list before the call. |
| quark | Returns the list of quarks. The caller must allocate sufficient space for the quarks list before the call. |
Description
XrmStringToBindingQuarkList converts the string into two lists—one of quarks and one of bindings. Component names in the list are separated by a dot (“.”) indicating a tight binding or an asterisk (“*”) indicating a loose binding. If the string does not start with dot or asterisk, a dot (“.”) is assumed.
A tight binding means that the quarks on either side of the binding are consecutive in the key. A loose binding, on the other hand, is a wildcard that can match any number of unspecified components in between the two quarks separated by the binding. Tight and loose bindings are used in the match rules, which compare multicomponent strings to find matches and determine the best match. See XrmGetResource for a full description of lookup rules.
For example, *a.b*c becomes:
| quarks | bindings |
| “a” | XrmBindLoosely |
| “b” | XrmBindTightly |
| “c” | XrmBindLoosely |
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark, *XrmQuarkList;
typedef enum (XrmBindLoosely, XrmBindTightly) XrmBinding, *XrmBindingList;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmStringToQuark
—Xlib - Resource Manager
Name
XrmStringToQuark — convert a string to a quark.
Synopsis
XrmQuark XrmStringToQuark (string) char *string;
Arguments
| string | Specifies the string for which a quark is to be allocated. |
Description
XrmStringToQuark returns a quark that is equivalent to the specified string. If a quark already exists for the string, that previously existing quark is returned. If no quark exists for the string, then a new quark is created, assigned to the string, and string is copied into the quark table. (Since string is copied, it may be freed. However, the copy of the string in the quark table must not be modified or freed.) XrmQuarkToString performs the inverse function.
Quarks are used by the resource manager to represent strings. Since the resource manager needs to make many comparisons of strings when it gets data from the database, it is more efficient to convert these strings into quarks, and to compare quarks instead. Since quarks are presently represented by integers, comparing quarks is trivial.
The three #define statements in the Structures section provide an extra level of abstraction. They define macros so that names, classes, and representations can also be represented as quarks.
For more information, see Volume 1, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark; /* macro definitions from <X11/resource.h> */ #define XrmStringToName (string) XrmStringToQuark(string) #define XrmStringToClass(string) XrmStringToQuark(string) #define XrmStringToRepresentation(string) XrmStringToQuark(string)
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmUniqueQuark.
XrmStringToQuarkList
Xlib - Resource Manager—
Name
XrmStringToQuarkList — convert a key string to a quark list.
Synopsis
void XrmStringToQuarkList (string, quarks) char *string; XrmQuarkList quarks; /* RETURN */
Arguments
| string | Specifies the string for which a list of quarks is to be generated. Must be null-terminated. The components may be separated by the “.” character (tight binding) or the “*” character (loose binding). |
| quarks | Returns the list of quarks. |
Description
XrmStringToQuarkList converts string (generally a fully qualified name/class string) to a list of quarks. Components of the string may be separated by a tight binding (the “.” character) or a loose binding (“*”). Use XrmStringToBindingQuarkList for lists which contain both tight and loose bindings. See XrmGetResource for a description of tight and loose binding.
Each component of the string is individually converted into a quark. See XrmStringToQuark for information about quarks and converting strings to quarks, quarks is a null-terminated list of quarks.
For example, xmh.toc.command.background is converted into a list of four quarks: the quarks for xmh, toc, command, and background, in that order. A NULLQUARK is appended to the end of the list.
Note that XrmStringToNameList and XrmStringToClassList are macros that perform exactly the same function as XrmStringToQuarkList. These may be used in cases where they clarify the code.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark *XrmQuarkList; #define XrmStringToNameList(str, name) XrmStringToQuarkList((str), (name)) #define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark, XrmUniqueQuark.
XrmUniqueQuark
Xlib - Resource Manager—
Name
XrmUniqueQuark — allocate a new quark.
Synopsis
XrmQuark XrmUniqueQuark ( )
Description
XrmUniqueQuark allocates a quark that is guaranteed not to represent any existing string. For most applications, XrmStringToQuark is more useful, as it binds a quark to a string. However, on some occasions, you may want to allocate a quark that has no string equivalent.
The shorthand name for a string is called a quark and is the type XrmQuark. Quarks are used to improve performance of the resource manager, which must make many string comparisons. Quarks are presently represented as ints. Simple comparisons of quarks can be performed rather than lengthy string comparisons.
A quark is to a string what an atom is to a property name in the server, but its use is entirely local to your application.
For more information, see Volume One, Chapter 11, Managing User Preferences.
Structures
typedef int XrmQuark;
Related Commands
XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, XrmInitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark.
XRotateBuffers
—Xlib - Cut Buffers
Name
XRotateBuffers — rotate the cut buffers.
Synopsis
XRotateBuffers (display, rotate) Display *display int rotate;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| rotate | Specifies how many positions to rotate the cut buffers. |
Description
XRotateBuffers rotates the 8 cut buffers the amount specified by rotate. Buffer 0 becomes buffer rotate, buffer 1 becomes buffer rotate+1 mod 8, buffer 2 becomes buffer rotate+2 mod 8, and so on. This cut buffer numbering is global to the display. This routine will not work if any of the buffers have not been stored into with XStoreBuffer.
See the description of cut buffers in Volume One, Chapter 13, Other Programming Techniques.
Errors
BadAtom
BadMatch
BadWindow
Related Commands
XStoreBuffer, XStoreBytes, XFetchBuffer, XFetchBytes.
XRotateWindowProperties
Xlib - Properties—
Name
XRotateWindowProperties — rotate properties in the properties array.
Synopsis
XRotateWindowProperties (display, w, properties, num_prop, npositions) Display *display; Window w; Atom properties[]; int num_prop; int npositions;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose properties are to be rearranged. |
| properties | Specifies the property list. |
| num_prop | Specifies the length of the properties array. |
| npositions | Specifies the number of positions to rotate the property list. The sign controls the direction of rotation. |
Description
XRotateWindowProperties rotates the contents of an array of properties on a window. If the property names in the properties array are viewed as if they were numbered starting from 0 and if there are num_prop property names in the list, then the value associated with property name I becomes the value associated with property name (I + npositions) mod num_prop, for all I from 0 to num_prop − 1. Therefore, the sign of npositions controls the direction of rotation. The effect is to rotate the states by npositions places around the virtual ring of property names (right for positive npositions, left for negative nposition).
If npositions mod num_prop is nonzero, a PropertyNotify event is generated for each property, in the order listed.
If a BadAtom or BadMatch error is generated, no properties are changed.
Error
| BadAtom | Atom occurs more than once in list for the window. |
| No property with that name for the window. | |
| BadMatch | |
| BadWindow |
Related Commands
XSetStandardProperties, XGetFontProperty, XDeleteProperty, XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName, XInternAtom.
XSaveContext
Xlib - Context Manager—
Name
XSaveContext — save a data value corresponding to a window and context type (not graphics context).
Synopsis
int XSaveContext (display, w, context, data) Display *display Window w; XContext context; caddr_t data;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window with which the data is associated. |
| context | Specifies the context type to which the data corresponds. |
| data | Specifies the data to be associated with the window and type. |
Description
XSaveContext saves data to the context manager database, according to the specified window and context ID. The context manager is used for associating data with windows within an application. The client must have called XUniqueContext to get the context ID before calling this function. The meaning of the data is indicated by the context ID, but is completely up to the client.
If an entry with the specified window and context ID already exists, XSaveContext writes over it with the specified data.
The XSaveContext function returns XCNOMEM (a nonzero error code) if an error has occurred and zero (0) otherwise. For more information, see the description of the context manager in Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef int XContext;
Related Commands
XDeleteContext, XFindContext, XUniqueContext.
XSelectInput
—Xlib - Input Handling
Name
XSelectInput — select the event types to be sent to a window.
Synopsis
XSelectInput (display w, event_mask) Display *display; Window w; unsigned long event_mask;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window interested in the input events. |
| event_mask | Specifies the event mask. This mask is the bitwise OR of one or more of the valid event mask bits (see below). |
Description
XSelectInput defines which input events the window is interested in. If a window' is not interested in an event, it propagates up to the closest ancestor unless otherwise specified in the do_not_propagate_mask attribute.
The bits of the mask are defined in <X11/X.h>:
ButtonPressMask NoEventMask
ButtonReleaseMask KeyPressMask
EnterWindowMask KeyReleaseMask
LeaveWindowMask ExposureMask
PointerMotionMask VisibilityChangeMask
PointerMotionHintMask StructureNotifyMask
Button1MotionMask ResizeRedirectMask
Button2MotionMask SubstructureNotifyMask
Button3MotionMask SubstructureRedirectMask
Button4MotionMask FocusChangeMask
Button5MotionMask PropertyChangeMask
ButtonMotionMask ColormapChangeMask
KeymapStateMask OwnerGrabButtonMask
A call on XSelectInput overrides any previous call on XSelectInput for the same window from the same client but not for other clients. Multiple clients can select input on the same window; their event_masks are disjoint. When an event is generated it will be reported to all interested clients. However, only one client at a time can select for each of SubstructureRedirectMask, ResizeRedirectMask, and ButtonPress.
If a window has both ButtonPressMask and ButtonReleaseMask selected, then a ButtonPress event in that window will automatically grab the mouse until all buttons are released, with events sent to windows as described for XGrabPointer. This ensures that a window will see the ButtonRelease event corresponding to the ButtonPress event, even though the mouse may have exited the window in the meantime.
If PointerMotionMask is selected, events will be sent independent of the state of the mouse buttons. If instead, one or more of Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask is selected, MotionNotify events will be generated only when one or more of the specified buttons is depressed.
XOpenDisplay sets the event_mask attribute; this attribute can also be set directly with XChangeWindowAttributes.
For more information, see Volume One, Chapter 8, Events.
Errors
BadValue
BadWindow
Related Commands
XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XSendEvent
—Xlib - Input Handling
Name
XSendEvent — send an event.
Synopsis
Status XSendEvent (display, w, propagate, event_mask, event) Display *display; Window w; Bool propagate; unsigned long event_mask; XEvent *event;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window where you want to send the event. Pass the window resource ID, PointerWindow, or InputFocus. |
| propagate | Specifies how the sent event should propagate depending on event_mask. See description below. May be True or False. |
| event_mask | Specifies the event mask. See XSelectInput for a detailed list of the event masks. |
| event | Specifies a pointer to the event to be sent. |
Description
XSendEvent sends an event from one client to another (or conceivably to itself). This function is used for communication between clients using selections, for simulating user actions in demos, and for other purposes.
The specified event is sent to the window indicated by w regardless of active grabs.
If w is set to PointerWindow, the destination of the event will be the window that the pointer is in. If w is InputFocus is specified, then the destination is the focus window, regardless of pointer position.
If propagate is False, then the event is sent to every client selecting on the window specified by w any of the event types in event_mask. If propagate is True and no clients have been selected on w any of the event types in event_mask, then the event propagates like any other event.
The event code must be one of the core events, or one of the events defined by a loaded extension, so that the server can correctly byte swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the server except that in Release 1 the most significant bit of XEvent.type is set to 1. In Release 2, the high bit is no longer set. Instead, a new flag send_event has been added to each event, which if True indicates that the event was sent with XSendEvent.
Under Release 1, if a client wants to read events sent by XSendEvent as normal events, it must ignore the high bit by ORing the event type with the following expression:
XEvent report; XNextEvent(display, Sreport); report.type &= 0x7f; /* now sent event looks like any other */
This function is often used in selection processing. For example, the owner of a selection should use XSendEvent to send a SelectionNotify event to a requestor when a selection has been converted and stored as a property. See Volume One, Chapter 10, Interclient Communication for more information.
The status returned by XSendEvent indicates whether or not the given XEvent structure was successfully converted into a wire event. Along with changes in the extensions mechanism, this makes merging of two wire events into a single user-visible event possible.
Structures
See Appendix F, Structure Reference, for the contents of specific event structures.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, QLength.
XSetAccessControl
—Xlib - Host Access
Name
XSetAccessControl — disable or enable access control.
Synopsis
XSetAccessControl (display, mode) Display *display; int mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| mode | Specifies whether you want to enable or disable the access control. Pass one of these constants: EnableAccess or DisableAccess. |
Description
XSetAccessControl specifies whether to check the host access list before allowing access to clients running on remote hosts. If the constant used is DisableAccess, clients from any host have access unchallenged.
This routine can only be called from a client running on the same host as the server.
For more information on access control lists, see Volume One, Chapter 13, Other Programming Techniques.
Errors
BadAccess
BadValue
Related Commands
XAddHost, XAddHosts, XListHosts, XRemoveHost, XRemoveHosts, XDisableAccessControl, XEnableAccessControl.
XSetAfterFunction
Xlib - Error Handling—
Name
XSetAfterFunction — set a function called after all Xlib functions.
Synopsis
int (*XSetAfterFunction (display, func))() Display *display; int (*func) ();
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| func | Specifies the user-defined function to be called after each Xlib function. This function is called with one argument, the display pointer. |
Description
All Xlib functions that generate protocol requests can call what is known as an after function after completing their work (normally, they don't). XSetAfterFunction allows you to write a function to be called.
XSynchronize sets an after function to make sure that the input and output buffers are flushed after every Xlib routine.
For more information, see Volume One, Chapter 13, Other Programming Techniques.
Related Commands
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetErrorHandler, XSetIOErrorHandler, XSynchronize.
XSetArcMode
—Xlib - Graphics Context
Name
XSetArcMode — set the arc mode in a graphics context.
Synopsis
XSetArcMode (display, gc, arc_mode) Display *display; GC gc; int arc_mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| arc_mode | Specifies the arc mode for the specified graphics context. Possible values are ArcChord or ArcPieSlice. |
Description
XSetArcMode sets the arc_mode member of the GC, which controls filling in the XFillArcs function. ArcChord specifies that the area between the arc and a line segment joining the endpoints of the arc is filled. ArcPieSlice specifies that the area filled is delimited by the arc and two line segments connecting the ends of the arc to the center point of the rectangle defining the arc.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetBackground
—Xlib - Graphics Context
Name
XSetBackground — set the background pixel value in a graphics context.
Synopsis
XSetBackground (display, gc, background) Display *display; GC gc; unsigned long background;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| background | Specifies the background you want to set for the specified graphics context. |
Description
XSetBackground sets the background pixel value for graphics requests. Note that this is different from the background of a window, which can be set with either XSetwindowBackground or XSetWindowBackgroundPixmap.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetClassHint
Xlib - Window Manager Hints—
Name
XSetClassHint — set the XA_WM_CLASS property of a window.
Synopsis
XSetClassHint (display, w, class_hints) Display *display; Window w; XClassHint *class_hints;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which the class hint is to be set. |
| class_hints | Specifies the XClassHint structure that is to be used. |
Description
XSetClassHint sets the XA_WM_CLASS property for the specified window.
XSetClassHint returns a Status of 0 on failure, and nonzero on success.
The XClassHint structure set contains res_class, which is the name of the client such as “emacs”, and res_name, which is the first of the following that applies:
- command line option (-rn name)
- a specific environment variable (e.g., RESOURCE_NAME)
- the trailing component of argv [0] (after the last /)
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadWindow
Structures
typedef struct {
char *res_name;
char *res_class;
} XClassHint;
Related Commands
XGetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetClipMask
—Xlib - Graphics Context
Name
XSetClipMask — set clip_mask pixmap in a graphics context.
Synopsis
XSetClipMask (display, gc, clip_mask) Display *display; GC gc; Pixmap clip_mask;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| clip_mask | Specifies a pixmap of depth 1 to be used as the clip mask. Pass the constant None if no clipping is desired. |
Description
XSetClipMask sets the clip_mask member of a GC to a pixmap. The clip_mask filters which pixels in the destination are drawn. If clip_mask is set to None, the pixels are always drawn, regardless of the clip origin. Use XSetClipRectangles to set clip_mask to a set of rectangles, or XSetRegion to set clip_mask to a region.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadMatch
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetClipOrigin
Xlib - Graphics Context—
Name
XSetClipOrigin — set the clip origin in a graphics context.
Synopsis
XSetClipOrigin (display, gc, clip_x_origin, clip_y_origin) Display *display; GC gc; int clip_x_origin, clip_y_origin;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| clip_x_origin | Specify the coordinates of the clip origin relative to the window |
| clip_y_origin | specified in the GC. |
Description
XSetClipOrigin sets the clip_x_origin and clip_y_origin members of the GC. The clip origin controls the position of the clip_mask in the GC, which filters which pixels in the destination are drawn.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetClipRectangles
—Xlib - Graphics Context
Name
XSetClipRectangles — change clip_mask in a graphics context to the list of rectangles.
Synopsis
XSetClipRectangles (display, gc, clip_x_origin, clip_y_origin, rectangles, nrects, ordering) Display *display; GC gc; int clip_x_origin, clip_y_origin; XRectangle rectangles[]; int nrects; int ordering;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| clip_x_origin | Specify the x and y coordinates of the clip origin, relative to the window |
| clip_y_origin | specified in the drawing request. |
| rectangles | Specifies an array of rectangles. These are the rectangles you want output clipped to. |
| nrects | Specifies the number of rectangles. |
| ordering | Specifies the ordering relations on the rectangles. Possible values are Unsorted, YSorted, YXSorted, or YXBanded. |
Description
XSetClipRectangles changes the clip_mask in the specified GC to the specified list of rectangles and sets the clip origin to clip_x_origin and clip_y_origin. The rectangle coordinates are interpreted relative to the clip origin. The output from drawing requests using that GC are henceforth clipped to remain contained within the rectangles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This is the opposite of a clip_mask of None in XCreateGC, XChangeGC, or XSetClipMask.
If known by the client, ordering relations on the rectangles can be specified with the ordering argument. This may provide faster operation by the server. If an incorrect ordering is specified, the X server may generate a BadMatch error, but it is not required to do so. If no error is generated, the graphics results are undefined. Unsorted means the rectangles are in arbitrary order. YSorted means that the rectangles are nondecreasing in their y origin. YXSorted additionally constrains YSorted order in that all rectangles with an equal y origin are nondecreasing in their x origin. YXBanded additionally constrains YXSorted by requiring that, for every possible horizontal y scan line, all rectangles that include that scan line have identical y origins and y extents.
To cancel the effect of this command, so that there is no clipping, pass None as the clip_mask in XChangeGC or XSetClipMask.
For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
short x,y;
unsigned short width, height;
} XRectangle;
Errors
BadAlloc
BadGC
BadMatch Incorrect ordering (error message server-dependent).
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetState, XSetSubwindowMode, DefaultGC.
XSetCloseDownMode
—Xlib - Client Connections
Name
XSetCloseDownMode — change the close down mode of a client.
Synopsis
XSetCloseDownMode (display, close_mode) Display *display; int close_mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| close_mode | Specifies the client close down mode you want. Pass one of these constants: DestroyAll, RetainPermanent, or RetainTemporary. |
Description
XSetCloseDownMode defines what will happen to the client's resources at connection close. A connection between a client and the server starts in DestroyAll mode, and all resources associated with that connection will be freed when the client process dies. If the close down mode is RetainTemporary or RetainPermanent when the client dies, its resources live on until a call to XKillClient. The resource argument of XKillClient can be used to specify which client to kill, or it may be the constant AllTemporary, in which case XKillClient kills all resources of all clients that have terminated in RetainTemporary mode.
One use of RetainTemporary or RetainPermanent might be to allow an application to recover from a failure of the network connection to the display server. After restarting, the application would need to be able to identify its own resources and reclaim control of them.
Errors
BadValue
Related Commands
XKillClient
XSetCommand
Xlib - Window Manager Hints—
Name
XSetCommand — set the XA_WM_COMMAND atom (command line arguments).
Synopsis
XSetCommand (display, w, argv, argc) Display *display; Window w; char **argv; int argc;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose atom is to be set. |
| argv | Specifies a pointer to the command and arguments used to start the application. The application is an array of pointers to null-terminated strings. |
| argc | Specifies the number of arguments. |
Description
XSetCommand is used by the application to set the XA_WM_COMMAND property for the window manager with the UNIX shell command and its arguments used to invoke the application.
Use this command only if not calling XSetStandardProperties.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes.
XSetDashes
—Xlib - Graphics Context
Name
XSetDashes — set dash_offset and dashes (for lines) in a graphics context.
Synopsis
XSetDashes (display, gc, dash_offset, dash_list, n) Display *display; GC gc; int dash_offset; char dash_list[]; int n;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| dash_offset | Specifies the phase of the pattern for the dashed line style. |
| dash_list | Specifies the dash list for the dashed line style. An odd-length list is equivalent to the same list concatenated with itself to produce an even-length list. |
| n | Specifies the length of the dash list argument. |
Description
XSetDashes sets the dashes member of the GC. The initial and alternating elements of the dash_list are the dashes, the others are the gaps. All of the elements must be nonzero. The dash_offset defines the phase of the pattern, specifying how many pixels into the dash_list the pattern should actually begin in the line drawn by the request.
n specifies the length of dash_list. An odd value for n is interpreted as specifying the dash_list concatenated with itself to produce twice as long a list.
The unit of measure for dashes is the same as in the ordinary coordinate system. Ideally, a dash length is measured along the slope of the line, but server implementors are only required to match this ideal for horizontal and vertical lines. Failing the ideal semantics, it is suggested that the length be measured along the major axis of the line. The major axis is defined as the x axis for lines drawn at an angle of between −45 and +45 degrees or between 315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis.
See Volume One, Chapter 5, The Graphics Context, for further information.
Errors
| BadAlloc | |
| BadGC | |
| BadValue | No values in dash_list. |
| Element in dash_list is 0. |
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetErrorHandler
—Xlib - Error Handling
Name
XSetErrorHandler — set a nonfatal error event handler.
Synopsis
XSetErrorHandler(handler) int (* handler) (Display *, XErrorEvent *)
Arguments
| handler | The user-defined function to be called to handle error events. If a NULL pointer, reinvoke the default handler, which prints a message and exits. |
Description
The error handler function specified in handler will be called by Xlib whenever an XError event is received. These are nonfatal conditions, such as unexpected values for arguments. It is acceptable for this procedure to return, though the default handler simply prints a message and exits. However, the error handler should NOT perform any operations (directly or indirectly) on the Display.
The function is called with two arguments, the display variable and a pointer to the XErrorEvent structure. Here is a trivial example of a user-defined error handler:
int myhandler (display, myerr)
Display *display;
XErrorEvent *myerr;
{
char msg[80];
XGetErrorText(display, myerr->error_code, msg, 80);
fprintf(stderr, "Error code %s\n", msg);
}
This is how the example routine would be used in XSetErrorHandler.
XSetErrorHandler(myhandler);
Note that XSetErrorHandler is one of the few routines that does not require a display argument. The routine that calls the error handler gets the display variable from the XErrorEvent structure.
The error handler is not called on BadName errors from OpenFont, LookupColor, AllocNamedColor, protocol requests, on BadFont errors from a QueryFont protocol request, or on BadAlloc or BadAccess errors. These errors are all indicated by a 0 return value in the corresponding Xlib routines, and can be caught and handled by the application.
Use XIOErrorHandler to to provide a handler for fatal errors.
In the XErrorEvent structure shown below, the serial member is the number of requests (starting from 1) sent over the network connection since it was opened. It is the number that was the value of the request sequence number immediately after the failing call was made. The request_code member is a protocol representation of the name of the procedure that failed and is defined in <X11/X.h>.
For more information, see Volume One, Chapter 3, Basic Window Program.
Structures
typedef struct {
int type
Display *display; /* display the event was read from */
unsigned long serial; /* serial number of failed request */
char error_code; /* error code of failed request */
char request_code; /* major opcode of failed request */
char minor_code; /* minor opcode of failed request */
XID resourceid; /* resource ID */
} XErrorEvent;
Related Commands
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetIOErrorHandler, XSynchronize, XSetAfterFunction.
XSetFillRule
—Xlib - Graphics Context
Name
XSetFillRule — set the fill rule in a graphics context.
Synopsis
XSetFillRule (display, gc, fill_rule) Display *display; GC gc; int fill_rule;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| fill_rule | Specifies the fill rule you want to set for the specified graphics context. Possible values are EvenOddRule or WindingRule. |
Description
XSetFillRule sets the fill_rule member of a GC. The fill_rule member of the GC determines what pixels are drawn in XFillPolygon requests. Simply put, WindingRule fills overlapping areas of the polygon, while EvenOddRule does not fill areas that overlap an odd number of times. Technically, EvenOddRule means that the point is drawn if an arbitrary ray drawn from the point would cross the path determined by the request an odd number of times. WindingRule indicates that a point is drawn if a point crosses an unequal number of clockwise and counterclockwise path segments, as seen from the point.
A clockwise-directed path segment is one which crosses the ray from left to right as observed from the point. A counterclockwise segment is one which crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a segment.
All calculations are performed on infinitely small points, so that if any point within a pixel is considered inside, the entire pixel is drawn. Pixels with centers exactly on boundaries are considered inside only if the filled area is to the right, except that on horizontal boundaries, the pixel is considered inside only if the filled area is below the pixel.
See Volume One, Chapter 5, The Graphics Context, for more information.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetFillStyle
—Xlib - Graphics Context
Name
XSetFillStyle — set the fill style in a graphics context.
Synopsis
XSetFillStyle (display, gc, fill_style) Display *display; GC gc; int fill_style;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| fill_style | Specifies the fill style for the specified graphics context. Possible values are FillSolid, FillTiled, FillStippled, or FillOpaqueStippled. |
Description
XSetFillStyle sets the fill_style member of the GC. The fill_style defines the contents of the source for line, text, and fill requests. FillSolid indicates that the pixels represented by set bits in the source are drawn in the foreground pixel value, and unset bits in the source are not drawn. FillTiled uses the tile specified in the GC to determine the pixel values for set bits in the source. FillOpaqueStippled specifies that bits set in the stipple are drawn in the foreground pixel value and unset bits are drawn in the background. FillStippled draws bits set in the source and set in the stipple in the foreground color, and leaves unset bits alone.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetFont
—Xlib - Fonts
Name
XSetFont — set the current font in a graphics context
Synopsis
XSetFont (display, gc, font) Display *display; GC gc; Font font;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| font | Specifies the ID of the font to be used. |
Description
XSetFont sets the font in the GC. Text drawing requests using this GC will use this font only if it is loaded. Otherwise, the text will not be drawn.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadFont
BadGC
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFontPath, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XSetFontPath
Xlib - Fonts—
Name
XSetFontPath — set the font search path.
Synopsis
XSetFontPath (display, directories, ndirs) Display *display; char **directories; int ndirs;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| directories | Specifies the directory path used to look for the font. Setting the path to the empty list restores the default path defined for the X server. |
| ndirs | Specifies the number of directories in the path. |
Description
XSetFontPath defines the directory search path for font lookup for all clients. Therefore the user should construct a new directory search path carefully by adding to the old directory search path obtained by XGetFontPath. Passing an invalid path can result in preventing the server from accessing any fonts. Also avoid restoring the default path, since some other client may have changed the path on purpose.
The interpretation of the strings is operating system dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system specific and are not intended to be used by client applications.
As a side-effect of executing this request, the server is guaranteed to flush all cached information about fonts for which there are currently no explicit resource IDs allocated. The meaning of errors from this request is system specific.
Errors
BadValue
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XUnloadFont, XGetFontProperty, XCreateFontCursor.
XSetForeground
—Xlib - Graphics Context
Name
XSetForeground — set the foreground pixel value in a graphics context.
Synopsis
XSetForeground (display, gc, foreground) Display *display; GC gc; unsigned long foreground;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| foreground | Specifies the foreground pixel value you want for the specified graphics context. |
Description
XSetForeground sets the foreground member in a GC. This pixel value is used for set bits in the source according to the fill_style.
See Volume One, Chapter 5, The Graphics Context, for more information on the GC.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetFunction
Xlib - Graphics Context—
Name
XSetFunction — set the bitwise logical operation in a graphics context.
Synopsis
XSetFunction (display, gc, function) Display *display; GC gc; int function;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| function | Specifies the logical operation you want for the specified graphics context. See Description for the choices and their meanings. |
Description
XSetFunction sets the logical operation applied between the source pixel values (generated by the drawing request) and existing destination pixel values (already in the window or pixmap) to generate the final destination pixel values in a drawing request (what is actually drawn to the window or pixmap). Of course, the plane_mask and clip_mask in the GC also affect this operation by preventing drawing to planes and pixels respectively.
See Volume One, Chapter 5, The Graphics Context, for more information about the logical function.
The function symbols and their logical definitions are:
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetGraphicsExposures
Xlib - Graphics Context—
Name
XSetGraphicsExposures — set graphics_exposures in a graphics context.
Synopsis
XSetGraphicsExposures (display, gc, graphics_exposures) Display *display; GC gc; Bool graphics_exposures;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| graphics_exposures | Specifies whether you want GraphicsExpose and NoExpose events when calling XCopyArea and XCopyPlane with this graphics context. |
Description
XSetGraphicsExposure sets the graphics_exposures member of the GC. If graphics_exposures is True, GraphicsExpose events will be generated when XCopyArea and XCopyPlane requests cannot be completely satisfied because a source region is obscured, and NoExpose events are generated when they can be completely satisfied. If graphics_exposures is False, these events are not generated.
These events are not selected in the normal way with XSelectInput. Setting the graphics_exposures member of the GC used in the CopyArea or CopyPlane request is the only way to select these events.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetIconName
—Xlib - Window Manager Hints
Name
XSetIconName — set the name to be displayed in a window's icon.
Synopsis
XSetIconName (display, w, icon_name) Display *display; Window w; char *icon_name;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose icon name is being set. |
| icon_name | Specifies the name to be displayed in the window's icon. The name should be a null-terminated string. This name is returned by any subsequent call to XGetIconName. |
Description
XSetIconName sets the XA_WM_ICON_NAME property for a window. This is usually set by an application for the window manager. The name should be short, since it is to be displayed in association with an icon.
XSetStandardProperties also sets this property.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetIconSizes
Xlib - Window Manager Hints—
Name
XSetIconSizes — set the value of the XA_WM_ICON_SIZE property.
Synopsis
XSetIconSizes (display, w, size_list, count) Display *display; Window w; XIconSize *size_list; int count;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose icon size property is to be set. Normally the root window. |
| size_list | Specifies a pointer to the size list. |
| count | Specifies the number of items in the size list. |
Description
XSetIconSizes is normally used by a window manager to set the range of preferred icon sizes in the XA_WM_ICON_SIZE property of the root window.
Applications can then read the property with XGetIconSizes.
Structures
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetCommand.
XSetInputFocus
—Xlib - Input Handling
Name
XSetInputFocus — set the keyboard focus window.
Synopsis
XSetInputFocus (display, focus, revert_to, time) Display *display; Window focus; int revert_to; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| focus | Specifies the ID of the window you want to be the keyboard focus. Pass the window ID, PointerRoot, or None. |
| revert_to | Specifies which window the keyboard focus reverts to if the focus window becomes not viewable. Pass one of these constants: RevertToParent, RevertToPointerRoot, or RevertToNone. Must not be a window ID. |
| time | Specifies the time when the focus change should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. Also returns the time of the focus change when CurrentTime is specified. |
Description
XSetInputFocus changes the keyboard focus and the last-focus-change time. The function has no effect if time is earlier than the current last-focus-change time or later than the current X server time. Otherwise, the last-focus-change time is set to the specified time, with CurrentTime replaced by the current X server time.
XSetInputFocus generates FocusIn and FocusOut events if focus is different from the current focus.
XSetInputFocus executes as follows, depending on what value you assign to the focus argument:
- If you assign None, all keyboard events are discarded until you set a new focus window. In this case, revert_to is ignored.
- If you assign a window ID, it becomes the main keyboard's focus window. If a generated keyboard event would normally be reported to this window or one of its inferiors, the event is reported normally; otherwise, the event is reported with respect to the focus window.
- If you assign PointerRoot, the focus window is dynamically taken to be the root window of whatever screen the pointer is on at each keyboard event. In this case, revert_to is ignored.
The specified focus window must be viewable at the time of the request (else a BadMatch error). If the focus window later becomes not viewable, the focus window will change to the revert_to argument.
If the focus window later becomes not viewable, XSetInputFocus evaluates the revert_to argument to determine the new focus window:
- If you assign RevertToParent, the focus reverts to the parent (or the closest viewable ancestor) automatically with a new revert_to argument of RevertToName.
- If you assign RevertToPointerRoot or RevertToNone, the focus reverts to that value automatically. FocusIn and FocusOut events are generated when the focus reverts, but the last_focus_change_time is not affected.
Errors
| BadMatch | focus window not viewable when XSetInputFocus called. |
| BadValue | |
| BadWindow |
Related Commands
XSelectInput, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XSetIOErrorHandler
—Xlib - Error Handling
Name
XSetIOErrorHandler — handle fatal I/O errors.
Synopsis
XSetIOErrorHandler (handler) int (*handler) (Display *);
Arguments
| handler | Specifies a pointer to a user-defined fatal error handling routine. If NULL, reinvoke the default fatal error handler. |
Description
XSetIOErrorHandler specifies a user-defined error handling routine for fatal errors. This error handler will be called by Xlib if any sort of system call error occurs, such as the connection to the server being lost. The called routine should not return. If the I/O error handler does return, the client process will exit.
If handler is a NULL pointer, the default error handler is reinvoked. The default I/O error handler prints an error message and exits.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetErrorHandler, XSynchronize, XSetAfterFunction.
XSetLineAttributes
Xlib - Graphics Context—
Name
XSetLineAttributes — set the line drawing components in a graphics context.
Synopsis
XSetLineAttributes (display, gc, line_width, line_style, cap_style, join_style) Display *display; GC gc; unsigned int line_width; int line_style; int cap_style; int join_style;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context.
|
| line_width | Specifies the line width you want to set for the specified graphics context. |
| line_style | Specifies the line style you want to set for the specified graphics context. Possible values are LineSolid, LineOnOffDash, or LineDoubleDash. |
| cap_style | Specifies the line and cap style you want to set for the specified graphics context. Possible values are CapNotLast, CapButt, CapRound, or CapProjecting. |
| join_style | Specifies the line-join style you want to set for the specified graphics context. Possible values are JoinMiter, JoinRound, or JoinBevel. |
Description
XSetLineAttributes sets four types of line characteristics in the GC: line_width, line_style, cap_style, and join_style.
See the description of line and join styles in Volume One, Chapter 5, The Graphics Context. See also XSetDashes.
A line_width of zero (0) means to use the fastest algorithm for drawing a line of one pixel width. These lines may not meet properly with lines specified as width 1 or more.
Errors
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetModifierMapping
Xlib - Keyboard—
Name
XSetModifierMapping — set keycodes to be used as modifiers (Shift, Control, etc.).
Synopsis
int XSetModifierMapping (display, mod_map) Display *display; XModifierKeymap *mod_map;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| mod_map | Specifies a pointer to the XModifierKeymap structure. |
Description
XSetModifierMapping is one of two ways to specify the keycodes of the keys that are to be used as modifiers (like Shift, Control, etc.). XSetModifierMapping specifies all the keycodes for all the modifiers at once. The other, easier, way is to use XInsertModifiermapEntry and XDeleteModifiermapEntry, which add or delete a single keycode for a single modifier key. XSetModifierMapping does the work in a single call, but the price of this call is that you need to manually set up the XModifierKeymap structure pointed to by mod_map. This requires you to know how the XModifierKeymap structure is defined and organized, as described in the next three paragraphs.
The XModifierKeymap structure for the mod_map argument should be created using XNewModifierMap or XGetModifierMapping. The max_keypermod element of the structure specifies the maximum number of keycodes that can be mapped to each modifier. You define this number but there may be an upper limit on a particular server.
The modifiermap element of the structure is an array of keycodes. There are eight by max_keypermod keycodes in this array: eight because there are eight modifiers, and max_keypermod because that is the number of keycodes that must be reserved for each modifier.
The eight modifiers are represented by the constants ShiftMapIndex, LockMapIndex, ControlMapIndex, Mod1MapIndex, Mod2MapIndex, Mod3MapIndex, Mod4MapIndex, and Mod5MapIndex. These are not actually used as arguments, but they are convenient for referring to each row in the modifiermap structure while filling it. The definitions of these constants are shown in the Structures section below.
Now you can interpret the modifiermap array. For each modifier in a given modifiermap, the keycodes which correspond are from modifiermap [index * max_keypermod] to modifiermap[[(index + 1) * max_keyspermod] -1] where index is the appropriate modifier index definition (ShiftMapIndex, LockMapIndex, etc.). You must set the mod_map array up properly before calling XSetModifierMapping. Now you know why XInsertModifierMapEntry and XDeleteModifierMapEntry were created!
Zero keycodes are ignored. No keycode may appear twice anywhere in the map (otherwise, a BadValue error is generated). In addition, all of the nonzero keycodes must be in the range specified by min_keycode and max_keycode in the Display structure (otherwise a BadValue error occurs).
A server can impose restrictions on how modifiers can be changed. For example, certain keys may not generate up transitions in hardware, or multiple modifier keys may not be supported. If a restriction is violated, then the status reply is MappingFailed, and none of the modifiers are changed.
If the new keycodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the down state, then the status reply is MappingBusy, and none of the modifiers are changed.
XSetModifierMapping generates a MappingNotify event on a MappingSuccess status.
A value of 0 for modifiermap indicates that no keys are valid as any modifier.
Structures
typedef struct {
int max_keypermod; /* server's max # of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array */
} XModifierKeymap;
/* modifier names. Used to build a SetModifierMapping request or
to read a GetModifierMapping request. These correspond to the
masks defined above. */
#define ShiftMapIndex 0
#define LockMapIndex 1
#define ControlMapIndex 2
#define Mod1MapIndex 3
#define Mod2MapIndex 4
#define Mod3MapIndex 5
#define Mod4MapIndex 6
#define Mod5MapIndex 7
Errors
| BadAlloc | |
| BadValue | Keycode appears twice in the map. |
| Keycode < display->min_keycode or | |
| keycode > display->max_keycode. |
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XStringToKeysym, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XGetModifierMapping, XInsertModifiermapEntry, XDeleteModifiermapEntry.
XSetNormalHints
Xlib - Window Manager Hints—
Name
XSetNormalHints — set the size hints property of a window in normal state (not zoomed or iconified).
Synopsis
void XSetNormalHints (display, w, hints) Display *display; Window w; XSizeHints *hints;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| hints | Specifies a pointer to the sizing hints for the window in its normal state. |
Description
XSetNormalHints sets the XA_WM_NORMAL_HINTS property for the specified window. Applications use XSetNormalHints to inform the window manager of the size or position desirable for that window. In addition, an application wanting to move or resize itself should call XSetNormalHints specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead.
To set size hints, an application must not only assign values to the appropriate elements in the hints structure, but also must set the flags field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetPlaneMask
Xlib - Graphics Context—
Name
XSetPlaneMask — set the plane mask in a graphics context.
Synopsis
XSetPlaneMask (display, gc, plane_mask) Display *display; GC gc; unsigned long plane_mask;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| plane_mask | Specifies the plane mask. You can use the macro AllPlanes if desired. |
Description
XSetPlaneMask sets the plane_mask member of the specified GC. The plane_mask determines which planes of the destination drawable are affected by a graphics request.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetPointerMapping
—Xlib - Pointer
Name
XSetPointerMapping — set the pointer button mapping.
Synopsis
int XSetPointerMapping (display, map, nmap) Display *display; unsigned char map[] ; int nmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| map | Specifies the mapping list. |
| nmap | Specifies the number of items in the mapping list. |
Description
XSetPointerMapping sets the mapping of the pointer. Elements of the map list are indexed starting from 1. The length of the list nmap must be the same as XGetPointerMapping returns (you must call that first). The index is a physical button number, and the element of the list defines the effective button number. In other words, if map [2] is set to 1, when the second physical button is pressed, a ButtonPress event will be generated if Button1Mask was selected but not if Button2Mask was selected. The button member in the event will read Button1.
No two elements can have the same nonzero value. A value of 0 for an element of map disables a button, and values for elements are not restricted in value by the number of physical buttons. If any of the buttons to be altered are currently in the down state, the status reply is MappingBusy and the mapping is not changed.
This function returns either MappingSuccess or MappingBusy. XSetPointerMapping generates a MappingNotify event on a status of MappingSuccess.
Errors
| BadValue | Two elements of map [ ] have same nonzero value. |
| nmap not equal to XGetPointerMapping return value. |
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XGetPointerMapping, XGetPointerControl, XChangePointerControl.
XSetRegion
Xlib - Regions—
Name
XSetRegion — set clip_mask of the graphics context to the specified region.
Synopsis
XSetRegion (display, gc, r) Display *display; GC gc; Region r;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| r | Specifies the region. |
Description
XSetRegion sets the clip_mask of the GC to the specified region. Thereafter, all output requests made with gc will be confined to 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. When the region is to be used as a clip_mask by calling XSetRegion, the upper-left corner of region relative to the drawable used in the graphics request will be at (xoffset + clip_x_origin, yoffset + clip_y_origin), where xoffset and yoffset are the offset of the region and clip_x_origin and clip_y_origin are elements of the GC used in the graphics request.
For more information on regions, see Volume One: Chapter 5, The Graphics Context; and Chapter 6, Drawing Graphics and Text.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XSetScreenSaver
—Xlib - Screen Saver
Name
XSetScreenSaver — set the parameters of the screen saver.
Synopsis
XSetScreenSaver (display, timeout, interval, prefer_blanking, allow_exposures) Display *display; int timeout, interval; int prefer_blanking; int allow_exposures;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| timeout | Specifies the time of inactivity, in seconds, before the screen saver turns on. |
| interval | Specifies the interval, in seconds, between screen saver invocations. This is for intermittent changes to the display, not blanking. |
| prefer_blanking | Specifies whether to enable screen blanking. Possible values are DontPreferBlanking, PreferBlanking, or DefaultBlanking. |
| allow_exposures | Specifies the current screen saver control values. Possible values are DontAllowExposures, AllowExposures, or DefaultExposures. |
Description
XSetScreenSaver sets the parameters that control the screen saver, timeout and interval are specified in seconds. A positive timeout enables the screen saver. A timeout of 0 disables the screen saver, while a timeout of −1 restores the default. An interval of 0 disables the random pattern motion. If no input from devices (keyboard, mouse, etc.) is generated for the specified number of timeout seconds, the screen saver is activated.
For each screen, if blanking is preferred and the hardware supports video blanking, the screen will simply go blank. Otherwise, if either exposures are allowed or the screen can be regenerated without sending exposure events to clients, the screen is tiled with the root window background tile, with a random origin, each interval seconds. Otherwise, the state of the screen does not change. All screen states are restored at the next input from a device.
If the server-dependent screen saver method supports periodic change, interval serves as a hint about how long the change period should be, and a value of 0 hints that no periodic change should be made. Examples of ways to change the screen include scrambling the color map periodically, moving an icon image about the screen periodically, or tiling the screen with the root window background tile, randomly reoriginated periodically.
For more information on the screen saver, see Volume One, Chapter 13, Other Programming Techniques.
Errors
| BadValue | timeout <-1. |
Related Commands
XForceScreenSaver, XActivateScreenSaver, XResetScreenSaver, XGetScreenSaver.
XSetSelectionOwner
—Xlib - Selections
Name
XSetSelectionOwner — set the owner of a selection.
Synopsis
XSetSelectionOwner (display, selection, owner, time) Display *display; Atom selection; Window owner; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| selection | Specifies the selection atom. Predefined atoms are XA_PRIMARY and XA_SECONDARY. |
| owner | Specifies the present owner of the specified selection atom. This value is either a window ID or None. |
| time | Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. |
Description
XSetSelectionOwner sets the owner and last-change time of a selection property. This should be called by an application that supports cutting and pasting between windows (or at least cutting), when the user has made a selection of any kind of text, graphics, or data. This makes the information available so that other applications can request the data from the new selection owner using XConvertSelection, which generates a SelectionRequest event specifying the desired type and format of the data. Then the selection owner sends a SelectionNotify using XSendEvent, which notes that the information is stored in the selection property in the desired format or indicates that it couldn't do the conversion to the desired type.
If owner is specified as None, then the new owner of the selection is None. Otherwise, the new owner is the client executing the request.
If the new owner is not the same as the current owner of the selection, and the current owner is a window, then the current owner is sent a SelectionClear event. This indicates to that window that the selection should be unhighlighted.
If the selection owner window is later destroyed, the owner of the selection automatically reverts to None.
The value you pass to the time argument must be no earlier than the last-change time of the specified selection, and no later than the current time, or the selection is not affected. The new last-change time recorded is the specified time, with CurrentTime replaced by the current server time. If the X server reverts a selection owner to None, the last-change time is not affected.
For more information on selections, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAtom
BadWindow
Related Commands
XGetSelectionOwner, XConvertSelection.
XSetSizeHints
—Xlib - Window Manager Hints
Name
XSetSizeHints — set the value of any property of type XA_SIZE_HINTS.
Synopsis
XSetSizeHints (display, w, hints, property) Display *display; Window w; XSizeHints *hints; Atom property;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| hints | Specifies a pointer to the size hints. |
| property | Specifies the property atom. |
Description
XSetSizeHints sets the named property on the specified window to the specified XSizeHints structure. This routine is useful if new properties of type XA_WM_SIZE_HINTS are defined. The predefined properties of that type have their own set and get functions, XSetNormalHints and XSetZoomHints.
The flags member of XSizeHints must be set to the OR of the symbols representing each member to be set.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;,
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadAlloc
BadAtom
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetStandardColormap
—Xlib - Colormaps
Name
XSetStandardColormap — change the standard colormap property.
Synopsis
void XSetStandardColormap (display, w, cmap, property) Display *display; Window w; XStandardColormap *cmap; Atom property;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window with which this colormap will be associated. |
| cmap | Specifies the filled colormap information structure. |
| property | Specifies the standard colormap property to set. The predefined standard colormaps are: XA_RGB_BEST_MAP, XA_RGB_RED_MAP, XA_RGB_GREEN_MAP, XA_RGB_BLUE_MAP, XA_RGB_DEFAULT_MAP, and XA_RGB_GRAY_MAP. |
Description
XSetStandardColormap defines or changes a colormap property. It is usually used only by window managers. To create a standard colormap, follow this procedure:
- Open a new connection to the same server.
- Grab the server.
- See if property is on the property list of the root window for the display, using XGetStandardColormap. If it is, the colormap already exists.
- If the desired property is not present, do the following:
- Create a colormap (not required for XA_RGB_DEFAULT_MAP).
- Determine the color capabilities of the display.
- Call XAllocColorPlanes or XAllocColorCells to allocate cells in the colormap.
- Call XStoreColors to store appropriate color values in the colormap.
- Fill in the descriptive fields in the structure.
- Call XSetStandardColormap to set the property on the root window.
- Use XSetCloseDownMode to make the resource permanent.
- Ungrab the server.
See description of predefined standard colormap atoms in Volume One, Chapter 7, Color.
Errors
BadAlloc
BadAtom
BadWindow
Structures
typedef struct {
Colormap colormap; /* ID of colormap made 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;
} XStandardColormap;
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XSetStandardProperties
—Xlib - Properties
Name
XSetStandardProperties — set the minimum set of properties for the window manager.
Synopsis
XSetStandardProperties (display, w, window_name, icon_name, icon_pixmap, argv, argc, hints) Display *display; Window w; char *window_name; char *icon_name; Pixmap icon_pixmap; char **argv; int argc; XSizeHints *hints
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| window_name | Specifies the name of the window. |
| icon_name | Specifies the name to be displayed in the window's icon. |
| icon_pixmap | Specifies the pixmap that is to be used for the icon, or None. This pixmap should normally be of depth 1. |
| argv | Specifies a pointer to the command and arguments used to start the application. The application is an array of pointers to null-terminated strings. |
| argc | Specifies the number of arguments. |
| hints | Specifies a pointer to the size hints for the window in its normal state. |
Description
XSetStandardProperties sets in a single call the most essential properties for a quickie application. XSetStandardProperties gives a window manager some information about your program's preferences; it probably will not be sufficient for complex programs. See Volume One, Chapter 10, Interclient Communication for a description of standard properties.
Structures
typedef struct {
long flags; /* which fields in structure are defined */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
} XSizeHints;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min and max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
Errors
BadAlloc
BadWindow
Related Commands
XGetFontProperty, XRotateWindowProperties, XDeleteProperty, XChangeProperty, XGetWindowProperty, XListProperties, XGetAtomName, XInternAtom.
XSetState
—Xlib - Graphics Context
Name
XSetState — set the foreground, background, logical function, and plane mask in a graphics context.
Synopsis
XSetState (display, gc, foreground, background, function, plane_mask) Display *display; GC gc; unsigned long foreground, background; int function; unsigned long plane_mask;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| foreground | Specifies the foreground you want for the specified graphics context. |
| background | Specifies the background you want for the specified graphics context. |
| function | Specifies the function you want for the specified graphics context. |
| plane_mask | Specifies the plane mask you want for the specified graphics context. |
Description
XSetState sets the foreground and background pixel values, the logical function, and the plane_mask in a GC. See XSetForeground, XSetBackground, XSetFunction, and XSetPlaneMask for what these members do and appropriate values.
See Volume One, Chapter 5, The Graphics Context, for more information.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetSubwindowMode, DefaultGC.
XSetStipple
Xlib - Graphics Context—
Name
XSetStipple — set the stipple in a graphics context.
Synopsis
XSetStipple (display, gc, stipple) Display *display; GC gc; Pixmap stipple;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| stipple | Specifies the stipple you want to set for the specified graphics context. |
Description
XSetStipple sets the stipple member of the GC. The stipple is a pixmap of depth 1. It is laid out like a tile. Set bits in the stipple determine which pixels in an area are drawn in the foreground pixel value. Unset bits in the stipple determine which pixels are drawn in the background pixel value if the fill_style is FillOpaqueStippled. If fill_style is FillStippled, pixels overlayed with unset bits in the stipple are not drawn. If fill_style is FillTiled or FillSolid, the stipple is not used.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadMatch
BadPixmap
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetSubwindowMode
—Xlib - Graphics Context
Name
XSetSubwindowMode — set the subwindow mode in a graphics context.
Synopsis
XSetSubwindowMode (display, gc, subwindow_mode) Display *display; GC gc; int subwindow_mode;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| subwindow_mode | Specifies the subwindow mode you want to set for the specified graphics context. Possible values are ClipByChildren or IncludeInferiors. |
Description
XSetSubwindowMode sets the subwindow_mode member of the GC. ClipByChildren means that graphics requests will be clipped by all viewable children. IncludeInferiors means draw through all subwindows.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadValue
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetTSOrigin, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, DefaultGC.
XSetTile
Xlib - Pixmaps and Tiles—
Name
XSetTile — set the fill tile in a graphics context.
Synopsis
XSetTile (display, gc, tile) Display *display; GC gc; Pixmap tile;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| tile | Specifies the desired tile for the specified graphics context. |
Description
XSetTile sets the tile member of the GC. This member of the GC determines the pixmap used to tile areas. The tile must have the same depth as the destination drawable.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
BadMatch
BadPixmap
Related Commands
XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XSetTransientForHint
—Xlib - Window Manager Hints
Name
XSetTransientForHint — set the XA_WM_TRANSIENT_FOR property for a window.
Synopsis
XSetTransientForHint (display, w, prop_window) Display *display; Window w; Window prop_window;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
| prop_window | Specifies the window ID that the XA_WM_TRANSIENT_FOR property is to be set to. |
Description
XSetTransientForHint sets the XA_WM_TRANSIENT_FOR property of the specified window. This should be done when the window w is a temporary child (for example, a dialog box) and the main top-level window of its application is prop_window. Some window managers may use this information to unmap an application's dialog boxes (for example, when the main application window gets iconified).
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetTSOrigin
Xlib - Graphics Context—
Name
XSetTSOrigin — set the tile/stipple origin in a graphics context.
Synopsis
XSetTSOrigin (display, gc, ts_x_origin, ts_y_origin) Display *display; GC gc; int ts_x_origin, ts_y_origin;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| gc | Specifies the graphics context. |
| ts_x_origin
ts_y_origin |
Specify the x and y coordinates of the tile/stipple origin. |
Description
XSetTSOrigin sets the ts_x_origin and ts_y_origin in the GC, which are measured relative to the origin of the drawable specified in the drawing request that uses the GC. This controls the placement of the tile or the stipple pattern that patterns an area. To tile or stipple a child so that the pattern matches the parent, you need to subtract the current position of the child window from ts_x_origin and ts_y_origin.
For more information, see Volume One, Chapter 5, The Graphics Context.
Errors
BadAlloc
BadGC
Related Commands
XChangeGC, XCopyGC, XCreateGC, XFreeGC, XGContextFromGC, XSetStipple, XSetPlaneMask, XSetDashes, XSetLineAttributes, XSetFillRule, XSetFillStyle, XSetForeground, XSetBackground, XSetFunction, XSetGraphicsExposures, XSetArcMode, XSetClipMask, XSetClipOrigin, XSetClipRectangles, XSetState, XSetSubwindowMode, DefaultGC.
XSetWindowBackground
—Xlib - Window Attributes
Name
XSetWindowBackground — set the background pixel attribute of a window.
Synopsis
XSetWindowBackground (display, w, background_pixel) Display *display; Window w; unsigned long background_pixel;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. Must be an InputOutput window. |
| background_pixel | Specifies which entry in the colormap is used as the background. |
Description
XSetWindowBackground sets the background attribute of a window, setting the pixel value to be used to fill the background. The current window contents are not changed. The background is automatically repainted after Expose events, in the area affected by the exposure.
When XSetWindowBackground and XSetWindowBackgroundPixmap are both used on a window, whichever is called last will control the current background. Trying to change the background of an InputOnly window will generate a BadMatch error.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadWindow
Related Commands
XGetWindowAttributes, XChangeWindowAttributes, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGetGeometry.
XSetWindowBackgroundPixmap
Xlib - Pixmaps and Tiles—
Name
XSetWindowBackgroundPixmap — change the background tile attribute of a window.
Synopsis
XSetWindowBackgroundPixmap (display, w, background_tile) Display *display; Window w; Pixmap background_tile;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. Must be an InputOutput class window. |
| background_tile | Specifies a pixmap ID, None, or ParentRelative to be used as a background. |
Description
XSetWindowBackgroundPixmap sets the background_pixmap attribute of a window. If no background pixmap is specified, the background pixmap of the window's parent is used. On the root window, the default background will be restored. The old, unused background pixmap can immediately be freed if no further explicit references to it are to be made.
XSetWindowBackgroundPixmap can only be performed on an InputOutput window. An error will result otherwise.
This does not change the current contents of the window, so you may wish to call XClearwindow to repaint the window after this function.
XSetWindowBackground may be used if a solid color instead of a tile is desired. If background_tile is specified as ParentRelative, the windows will get an Expose event when it is moved and its background will be repainted. When XSetWindowBackground and XSetWindowBackgroundPixmap are both used on a window, whichever is called last will control the current background.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadPixmap
BadWindow
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XSetWindowBorder
—Xlib - Window Attributes
Name
XSetWindowBorder — change a window border attribute to the specified pixel value and repaint the border.
Synopsis
XSetWindowBorder (display, w, border_pixel) Display *display; Window w; unsigned long border_pixel;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. Must be an InputOutput window. |
| border_pixel | Specifies the entry in the colormap. XSetWindowBorder uses this entry to paint the border. |
Description
XSetWindowBorder sets the border_pixel attribute of window w to a pixel value, and repaints the border. The border is also automatically repainted after Expose events.
Use XSetWindowBorderPixmap to create a tiled border.
For more information, see Volume One, Chapter 4, Window Attributes.
Errors
BadMatch
BadWindow
Related Commands
XGetWindowAttributes, XChangeWindowAttributes, XSetWindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, XGetGeometry.
XSetWindowBorderPixmap
Xlib - Pixmaps and Tiles—
Name
XSetWindowBorderPixmap — change a window border tile attribute and repaint the border.
Synopsis
XSetWindowBorderPixmap (display, w, border_tile) Display *display; Window w; Pixmap border_tile;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of an InputOutput window whose border is to be changed. |
| border_tile | Specifies any pixmap or None. |
Description
XSetWindowBorderPixmap sets the border_pixmap attribute of a window and repaints the border. The border_tile can be freed immediately after the call if no further explicit references to it are to be made.
This function can only be performed on an InputOutput window.
Errors
BadMatch
BadPixmap
BadWindow
Related Commands
XSetTile, XQueryBestTile, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XWriteBitmapFile, XReadBitmapFile, XCreateBitmapFromData.
XSetWindowBorderWidth
—Xlib - Window Manipulation
Name
XSetWindowBorderWidth — change the border width of a window.
Synopsis
XSetWindowBorderWidth (display, w, width) Display *display; Window w; unsigned int width;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose border is to be changed. |
| width | Specifies the width of the window border. |
Description
XSetWindowBorderWidth changes the border width of a window. This request is often used by the window manager as an indication of the current input focus window, so other clients should not change it.
Errors
BadWindow
Related Commands
XLowerWindow, XRaiseWindow, XCirculateSubwindows, XCirculateSubwindowsDown, XCirculateSubwindowsUp, XRestackWindows, XMoveWindow, XResizeWindow, XMoveResizeWindow, XReparentWindow, XConfigureWindow, XQueryTree.
XSetWindowColormap
Xlib - Window Attributes—
Name
XSetWindowColormap — set the colormap for a specified window.
Synopsis
XSetWindowColormap (display, w, cmap) Display *display; Window w; Colormap cmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which you want to set the colormap. |
| cmap | Specifies the colormap. |
Description
XSetWindowColormap sets the colormap attribute of the specified window. The colormap need not be installed to be set as an attribute, cmap will be used to translate pixel values drawn into this window when cmap is installed in the hardware.
Eventually, window managers will install and uninstall the proper colormaps according to this attribute and the pointer position or some other convention. For now, applications must install their own colormaps if they cannot use the default colormap.
The colormap must have the same visual as the window.
Errors
BadColor
BadMatch
BadWindow
Related Commands
XGetWindowAttributes, XChangeWindowAttributes, XSetWindowBackground, XSetWindowBackgroundPixmap, XSetWindowBorder, XSetWindowBorderPixmap, XGetGeometry.
XSetWMHints
—Xlib - Window Manager Hints
Name
XSetWMHints — set a window manager hints property.
Synopsis
XSetWMHints (display, w, wmhints) Display *display; Window w; XWMHints *wmhints;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID for which window manager hints are to be set. |
| wmhints | Specifies a pointer to the window manager hints. |
Description
XSetWMHints sets the window manager hints that include icon information and location, the initial state of the window, and whether the application relies on the window manager to get keyboard input. See Volume One, Chapter 10, Interclient Communication, for a description of each XWMHints structure member.
Structures
typedef struct {
long flags; /* marks defined fields in structure */
Bool input; /* does application need window manager for
* keyboard input */
int initial_state; /* see below */
Pixmap icon_pixmap; /* pixmap to be used as icon */
Window icon_window; /* window to be used as icon */
int icon_x, icon_y; /* initial position of icon */
Pixmap icon_mask; /* icon mask bitmap */
XID window_group; /* ID of related window group */
/* this structure may be extended in the future */
} XWMHints;
/* definitions for the flags field: */
#define InputHint (1L « 0)
#define StateHint (1L « 1)
#define IconPixmapHint (1L « 2)
#define IconWindowHint (1L « 3)
#define IconPositionHint (1L « 4)
#define IconMaskHint (1L « 5)
#define WindowGroupHint (1L « 6)
#define AllHints (InputHint|StateHint|IconPixmapHint|IconWindowHint| \
IconPositionHint|IconMaskHint|WindowGroupHint)
/* definitions for the initial state flag: */
#define DontCareState 0 /* don't know or care */
#define NormalState 1 /* most applications want to start this way */
#define ZoomState 2 /* application wants to start zoomed */
#define IconicState 3 /* application wants to start as an icon */
#define InactiveState 4 /* application believes it is seldom used;
some wm's may put it on inactive menu */
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XSetZoomHints
—Xlib - Window Manager Hints
Name
XSetZoomHints — set the size hints property of a zoomed window.
Synopsis
XSetZoomHints (display, w, zhints) Display *display; Window w; XSizeHints *zhints;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window for which zoom hints are to be set. |
| zhints | Specifies a pointer to the zoom hints. |
Description
XSetZoomHints sets the XA_WM_ZOOM_HINTS property for an application's top-level window in its zoomed state. Many window managers think of windows in three states: iconified, normal, or zoomed, corresponding to small, medium, and large. Applications use XSetZoomHints to inform the window manager of the size or position desirable for the zoomed window.
In addition, an application wanting to move or resize its zoomed window should call XSetZoomHints specifying its new desired location and size, in addition to making direct X calls to move or resize. This is because some window managers may redirect window configuration requests, but ignore the resulting events and pay attention to property changes instead.
To set size hints, an application must not only assign values to the appropriate elements in the hints structure, but also must set the flags field of the structure to indicate which members have assigned values and the source of the assignment. These flags are listed in the Structures section below.
For more information on using hints, see Volume One, Chapter 10, Interclient Communication.
Structures
typedef struct {
long flags; /* marks defined fields in structure */
int x, y;
int width, height;
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
struct {
int x; /* numerator */
int y; /* denominator */
} min_aspect, max_aspect;
/* flags argument in size hints */
#define USPosition (1L « 0) /* user specified x, y */
#define USSize (1L « 1) /* user specified width, height */
#define PPosition (1L « 2) /* program specified position */
#define PSize (1L « 3) /* program specified size */
#define PMinSize (1L « 4) /* program specified minimum size */
#define PMaxSize (1L « 5) /* program specified maximum size */
#define PResizeInc (1L « 6) /* program specified resize increments */
#define PAspect (1L « 7) /* program specified min/max aspect ratios */
#define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect)
} XSizeHints;
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XStoreName, XGetIconSizes, XSetIconSizes, XSetCommand.
XShrinkRegion
—Xlib - Regions
Name
XShrinkRegion — reduce or expand the size of a region.
Synopsis
XShrinkRegion (r, dx, dy) Region r; int dx, dy;
Arguments
| r | Specifies the region. |
| dx
dy |
Specify the amounts by which you want to shrink or expand the specified region. Positive values expand the region while negative values shrink the region. |
Description
XShrinkRegion changes the width of the specified region by the ratio:
(currentwidth + dx)/currentwidth
and the height by the ratio:
(currentheight + dy)/currentheight.
Counter to the name of the routine and the MIT documentation, the code seems to show that positive values expand the region; negative values shrink the region. The offset of the region is changed to keep the center of the resized region near its original position.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XStoreBuffer
Xlib - Cut BUffers—
Name
XStoreBuffer — store data in a cut buffer.
Synopsis
XStoreBuffer (display, bytes, nbytes, buffer) Display *display; char bytes[] ; int nbytes; int buffer;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| bytes | Specifies the string of bytes you want stored. The byte string is not necessarily ASCII or null-terminated. |
| nbytes | Specifies the number of bytes in the string. |
| buffer | Specifies the cut buffer in which to store the byte string. Must be in the range 0-7. |
Description
XStoreBuffer stores the specified data into one of the eight cut buffers. All eight buffers must be stored into before they can be circulated with XRotateBuffers. The cut buffers are numbered 0 through 7. Use XFetchBuffer to recover data from any cut buffer.
Note that selections are the preferred method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Techniques. For more information on selections, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadAtom
Related Commands
XStoreBytes, XFetchBuffer, XFetchBytes, XRotateBuffers.
XStoreBytes
—Xlib - Cut Buffers
Name
XStoreBytes — store data in cut buffer 0.
Synopsis
XStoreBytes (display, bytes, nbytes) Display *display; char bytes[]; int nbytes;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| bytes | Specifies the string of bytes you want stored. The byte string is not necessarily ASCII or null-terminated. |
| nbytes | Specifies the number of bytes that you want stored. |
Description
XStoreBytes stores data in cut buffer 0, usually for reading by another client that already knows the meaning of the contents. Note that the cut buffer's contents need not be text, so null bytes are not special.
The cut buffer's contents may be retrieved later by any client calling XFetchBytes.
Use XStoreBuffer to store data in buffers 1-7. Note that selections are the preferred method of transferring data between applications.
For more information on cut buffers, see Volume One, Chapter 13, Other Programming Techniques. For more information on selections, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
Related Commands
XStoreBuffer, XFetchBuffer, XFetchBytes, XRotateBuffers.
XStoreColor
Xlib - Color Cells—
Name
XStoreColor — set or change a read/write entry of a colormap to the closest available hardware color.
Synopsis
XStoreColor (display, cmap, colorcell_def) Display *display; Colormap cmap; XColor *colorcell_def;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap. |
| colorcell_def | Specifies a pixel value and the desired RGB values. |
Description
XStoreColor changes the RGB values of a colormap entry specified by colorcell_def.pixel to the closest values available on the hardware. This pixel value must be a read/write cell and a valid index into cmap. XStoreColor changes the red, green, and/or blue color components in the cell according to the colorcell_def.flags member, which you set by ORing the constants DoRed, DoGreen, and/or DoBlue.
If the colormap is an installed map for its screen, the changes are visible immediately.
For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
| BadColor | |
| BadValue | pixel not valid index into cmap. |
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColors, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XStoreColors
—Xlib - Color Cells
Name
XStoreColors — set or change read/write colorcells to the closest available hardware colors.
Synopsis
XStoreColors (display, cmap, colorcell_defs, ncolors) Display *display; Colormap cmap; XColor colorcell_defs [ncolors]; int ncolors;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap. |
| colorcell_defs | Specifies an array of color definition structures. |
| ncolors | Specifies the number of XColor structures in colorcell_defs. |
Description
XStoreColors changes the RGB values of each colormap entry specified by colorcell_defs[].pixel to the closest available hardware colors. Each pixel value must be a read/write cell and a valid index into cmap. XStoreColors changes the red, green, and/or blue color components in each cell according to the colorcell_defs[].flags member, which you set by ORing the constants DoRed, DoGreen, and/or DoBlue. The specified pixels are changed if they are writable by any client, even if one or more pixels generates an error.
If the colormap is an installed map for its screen, the changes are visible immediately. For more information, see Volume One, Chapter 7, Color.
Structures
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
Errors
| BadAccess | A specified pixel is unallocated or read-only. |
| BadColor | |
| BadValue | A specified pixel is not a valid entry into cmap. |
Related Commands
XAllocColorCells, XAllocColorPlanes, XAllocColor, XAllocNamedColor, XLookupColor, XParseColor, XQueryColor, XQueryColors, XStoreColor, XFreeColors, XStoreNamedColor, BlackPixel, WhitePixel.
XStoreName
Xlib - Window Manager Hints—
Name
XStoreName — assign a name to a window for the window manager.
Synopsis
XStoreName (display, w, window_name) Display *display; Window w; char *window_name;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window to which you want to assign a name. |
| window_name | Specifies the name of the window. The name should be a null-terminated string. This name is returned by any subsequent call to XFetchName. |
Description
XStoreName sets the XA_WM_NAME property, which should be used by the application to communicate the following information to the window manager, according to current conventions:
- To permit the user to identify one of a number of instances of the same client.
- To provide the user with noncritical state information.
Clients can assume that at least the beginning of this string is visible to the user.
The XA_WM_CLASS property, on the other hand, has two members which should be used to identify the client in general and each instance in particular. It is used for obtaining resources. See XSetClassHint for details.
For more information, see Volume One, Chapter 10, Interclient Communication.
Errors
BadAlloc
BadWindow
Related Commands
XGetClassHint, XSetClassHint, XGetSizeHints, XSetSizeHints, XGetWMHints, XSetWMHints, XGetZoomHints, XSetZoomHints, XGetNormalHints, XSetNormalHints, XGetTransientForHint, XSetTransientForHint, XFetchName, XGetIconName, XSetIconName, XGetIconSizes, XSetIconSizes, XSetCommand.
XStoreNamedColor
—Xlib - Window Manager Hints
Name
XStoreNamedColor — allocate a read/write colorcell by English color name.
Synopsis
XStoreNamedColor (display, cmap, colorname, pixel, flags) Display *display; Colormap cmap; char *colorname; unsigned long pixel; int flags;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap. |
| colorname | Specifies the color name string (for example, “red”). This cannot be in hex format (as used in XParseColor). Upper or lower case is not important. The string should be in ISO LATIN-1 encoding, which means that the first 128 character codes are ASCII, and the second 128 character codes are for special characters needed in western languages other than English. |
| pixel | Specifies the entry in the colormap to store color in. |
| flags | Specifies which red, green, and blue indexes are set. |
Description
XStoreNamedColor looks up the named color in the database, with respect to the screen associated with cmap, then stores the result in the cell of cmap specified by pixel. Upper or lower case in name does not matter. The flags argument, a bitwise OR of the constants DoRed, DoGreen, and DoBlue, determines which subfields within the pixel value in the cell are written.
For more information, see Volume One, Chapter 7, Color.
Errors
| BadAccess | pixel is unallocated or read-only. |
| BadColor | |
| BadName | |
| BadValue | pixel is not a valid index into cmap. |
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XUninstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XStringToKeysym
Xlib - Keyboard—
Name
XStringToKeysym — convert a keysym name string to a keysym.
Synopsis
KeySym XStringToKeysym (string) char *string;
Arguments
| string | Specifies the name of the keysym that is to be converted. |
Description
XStringToKeysym translates the character string version of a keysym name (“Shift”) to the matching keysym which is a constant (XK_Shift). Valid keysym names are listed in <X11/keysymdef.h>. If the specified string does not match a valid keysym, XStringToKeysym returns NoSymbol.
This string is not the string returned in the buffer argument of XLookupString, which can be set with XRebindKeysym. If that string is used, XStringToKeysym will return NoSymbol except by coincidence.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands
XDeleteModifiermapEntry, XInsertModifiermapEntry, XFreeModifiermap, XKeycodeToKeysym, XKeysymToKeycode, XKeysymToString, XNewModifierMap, XQueryKeymap, XLookupKeysym, XRebindKeysym, XGetKeyboardMapping, XChangeKeyboardMapping, XRefreshKeyboardMapping, XLookupString, XSetModifierMapping, XGetModifierMapping.
XSubImage
—Xlib - Images
Name
XSubImage — create a subimage from part of an image.
Synopsis
XImage *XSubImage (ximage, x, y, subimage_width, subimage_height) XImage *ximage; int x; int y; unsigned int subimage_width; unsigned int subimage_height;
Arguments
| ximage | Specifies a pointer to the image. |
| x | Specify the x and y coordinates of the origin of the subimage. |
| y | |
| subimage_width | |
| subimage_height | Specify the width and height (in pixels) of the new subimage. |
Description
XSubImage creates a new image that is a subsection of an existing one. It allocates the memory necessary for the new XImage structure and returns a pointer to the new image. The data is copied from the source image, and the rectangle defined by x, y, subimage_width, and subimage_height must by contained in the image.
XSubImage extracts a subimage from an image, while XGetSubImage extracts an image from a drawable.
For more information on images, see Volume One, Chapter 6, Drawing Graphics and Text.
Related Commands
XDestroyImage, XPutImage, XGetImage, XCreateImage, XGetSubImage, XAddPixel, XPutPixel, XGetPixel, ImageByteOrder.
XSubtractRegion
Xlib - Regions—
Name
XSubtractRegion — subtract one region from another.
Synopsis
XSubtractRegion (sra, srb, dr) Region sra, srb; Region dr; /* RETURN */
Arguments
| sra | Specify the two regions in which you want to perform the computation. |
| srb | |
| dr | Returns the result of the computation. |
Description
XSubtractRegion calculates the difference between the two regions specified (sra – srb) and puts the result in dr.
This function returns a region which contains all parts of sra that are not also in srb.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRegion, XUnionRectWithRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XSync
—Xlib - Output Buffer
Name
XSync — flush the output buffer and wait for all events and errors to be processed by the server.
Synopsis
XSync (display, discard) Display *display; int discard;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| discard | Specifies whether XSync discards all events on the input queue. This argument is either True or False. |
Description
XSync flushes the output buffer, then waits until all events and errors resulting from previous calls have been received and processed by the X server. Events (and errors) are placed on the input queue. The client's XError routine is called once for each error received.
If discard is True, XSync discards all events on the input queue (including those events that were on the queue before XSync was called).
XSync is sometimes used with window manipulation functions (by the window manager) to wait for all resulting exposure events. Very few clients need to use this function.
Related Commands
XFlush
XSynchronize
Xlib - Input Handling—
Name
XSynchronize — enable or disable synchronization for debugging.
Synopsis
int (*XSynchronize (display, onoff)) () Display *display; int onoff;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| onoff | Specifies whether to enable or disable synchronization. You can pass 0 (disable synchronization) or nonzero (enable synchronization). |
Description
XSynchronize turns on or off synchronous mode for debugging. If onoff is nonzero, it turns on synchronous behavior; 0 resets the state to off.
When events are synchronized, they are reported as they occur instead of at some later time, but server performance is many times slower. This can be useful for debugging complex event handling routines. Under UNIX, the same result can be achieved without hardcoding by setting the global variable _xdebug to True.
If synchronous mode was off before the call, XSynchronize returns NULL.
For more information, see Volume One, Chapter 3, Basic Window Program.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XWindowEvent, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSendEvent, QLength.
XTextExtents
—Xlib - Text
Name
XTextExtents — get string and font metrics.
Synopsis
XTextExtents(font_struct, string, nchars, direction, ascent, descent, overall) XFontStruct *font_struct; char *string; int nchars; int *direction; /* RETURN */ int *ascent, *descent; /* RETURN */ XCharStruct *overall; /* RETURN */
Arguments
| font_struct | Specifies a pointer to the XFontStruct structure. |
| string | Specifies the character string for which metrics are to be returned. |
| nchars | Specifies the number of characters in the character string. |
| direction | Returns the value of the direction element of the XFontStruct. Either FontRightToLeft or FontLeftToRight. |
| ascent | Returns the font ascent element of the XFontStruct. This is the overall maximum ascent for the font. |
| descent | Returns the font descent element of the XFontStruct. This is the overall maximum descent for the font. |
| overall | Returns the overall characteristics of the string. These are the sum of the width measurements for each character, the maximum ascent and descent, the minimum lbearing added to the width of all characters up to the character with the smallest lbearing, and the maximum rbearing added to the width of all characters up to the character with the largest rbearing. |
Description
XTextExtents returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function performs the size computation locally and, thereby, avoids the roundtrip overhead of XQueryTextExtents, but it requires a filled XFontStruct.
ascent and descent return information about the font, while overall returns information about the given string. The returned ascent and descent should usually be used to calculate the line spacing, while the width, rbearing, and lbearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
overall.ascent is the maximum of the ascent metrics of all characters in the string. The overall.descent is the maximum of the descent metrics. The overall.width is the sum of the character-width metrics of all characters in the string. The overall.lbearing is the lbearing of the character in the string with the smallest lbearing plus the width of all the characters up to but not including that character. The overall.rbearing is the rbearing of the character in the string with the largest rbearing plus the width of all the characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* 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_byte1; /* first row that exists */
unsigned max_byte1; /* 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;
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents16, XTextWidth, XTextWidth16.
XTextExtents16
—Xlib - Text
Name
XTextExtents16 — get string and font metrics of a 16-bit character string.
Synopsis
XTextExtents16(font_struct, string, nchars, direction, ascent, descent, overall) XFontStruct *font_struct; XChar2b *string; int nchars; int *direction; /* RETURN */ int *ascent, *desent; /* RETURN */ XCharStruct *overall; /* RETURN */
Arguments
| font_struct | Specifies a pointer to the XFontStruct structure. |
| string | Specifies the character string made up of XChar26 structures. |
| nchars | Specifies the number of characters in the character string. |
| direction | Returns the value of the direction element of the XFontStruct. FontRightToLeft of FontLeftToRight. |
| ascent | Returns the font ascent element of the XFontStruct. This is the overall maximum ascent for the font. |
| descent | Returns the font descent element of the XFontStruct. This is the overall maximum descent for the font. |
| overall | Returns the overall characteristics of the string. These are the sum of the width measurements for each character, the maximum ascent and descent, the minimum lbearing added to the width of all characters up to the character with the smallest lbearing, and the maximum rbearing added to the width of all characters up to the character with the largest rbearing. |
Description
XTextExtents16 returns the dimensions in pixels that specify the bounding box of the specified string of characters in the named font, and the maximum ascent and descent for the entire font. This function performs the size computation locally and, thereby, avoids the roundtrip overhead of XQueryTextExtents16, but it requires a filled XFontStruct.
ascent and descent return information about the font, while overall returns information about the given string. The returned ascent and descent should usually be used to calculate the line spacing, while the width, rbearing, and lbearing members of overall should be used for horizontal measures. The total height of the bounding rectangle, good for any string in this font, is ascent + descent.
overall.ascent is the maximum of the ascent metrics of all characters in the string. The overall. descent is the maximum of the descent metrics. The overall.width is the sum of the character-width metrics of all characters in the string. The overall.lbearing is the lbearing of the character in the string with the smallest lbearing plus the width of all the characters up to but not including that character. The overall. rbearing is the rbearing of the character in the string with the largest rbearing plus the width of all the characters up to but not including that character.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short lbearing; /* origin to left edge of character */
short rbearing; /* origin to right edge of character */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of character */
short descent; /* baseline to bottom edge of character */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
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_byte1; /* first row that exists */
unsigned max_byte1; /* 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;
typedef struct { /* normal 16 bit characters are two bytes */
unsigned char byte1;
unsigned char byte2;
} XChar2b;
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextWidth, XTextWidth16.
XTextWidth
—Xlib - Text
Name
XTextWidth — get the width in pixels of an 8-bit character string.
Synopsis
int XTextWidth(font_struct, string, count) XFontStruct *font_struct; char *string; int count;
Arguments
| font_struct | Specifies the font description structure of the font in which you want to draw the string. |
| string | Specifies the character string whose width is to be returned. |
| count | Specifies the character count in string. |
Description
XTextWidth returns the width in pixels of the specified string using the specified font. This is the sum of the XCharStruct.width for each character in the string. This is also equivalent to the value of overall.width returned by XQueryTextExtents or XTextExtents. The characters in string are 8-bit characters.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
} XFontStruct;
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth16.
XTextWidth16
Xlib - Text—
Name
XTextWidth16 — get the width in pixels of a 16-bit character string.
Synopsis
int XTextWidth16(font_struct, string, count) XFontStruct *font_struct; XChar2b *string; int count;
Arguments
| font_struct | Specifies the font description structure of the font in which you want to draw the string. |
| string | Specifies a character string made up of XChar2b structures. |
| count | Specifies the character count in string. |
Description
XTextWidth16 returns the width in pixels of the specified string using the specified font. This is the sum of the XCharStruct.width for each character in the string. This is also equivalent to the value of overall.width returned by XQueryTextExtents16 or XTextExtents16.
The characters in string are 16-bit characters.
For more information on drawing text, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* hint about direction the font is painted */
unsigned min_char_or_byte2; /* first character */
unsigned max_char_or_byte2; /* last character */
unsigned min_byte1; /* first row that exists */
unsigned max_byte1; /* last row that exists */
Bool all_chars_exist; /* flag if all characters have nonzero size*/
unsigned default_char; /* char to print for undefined character */
int n_properties; /* how many properties there are */
XFontProp *properties; /* pointer to array of additional properties*/
XCharStruct min_bounds; /* minimum bounds over all existing char*/
XCharStruct max_bounds; /* minimum bounds over all existing char*/
XCharStruct *per_char; /* first_char to last_char information */
int ascent; /* logical extent above baseline for spacing */
int descent; /* logical descent below baseline for spacing */
}XFontStruct;
Related Commands
XQueryTextExtents, XQueryTextExtents16, XDrawImageString, XDrawImageString16, XDrawString, XDrawString16, XDrawText, XDrawText16, XTextExtents, XTextExtents16, XTextWidth.
XTranslateCoordinates
—Xlib - Standard Geometry
Name
XTranslateCoordinates — change the coordinate system from one window to another.
Synopsis
Bool XTranslateCoordinates (display, src_w, dest_w, src_x, src_y, dest_x, dest_y, child) Display *display; Window src_w, dest_w; int src_x, src_y; int *dest_x, *dest_y; /* RETURN */ Window *child; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| src_w | Specifies the ID of the source window. |
| dest_w | Specifies the ID of the destination window. |
| src_x
src_y |
Specify the x and y coordinates within the source window. |
| dest_x
dest_y |
Return the translated x and y coordinates within the destination window. |
| child | If the point is contained in a mapped child of the destination window, then that child ID is returned in child. |
Description
XTranslateCoordinates translates coordinates from the frame of reference of one window to another. This should be avoided in most applications since it requires a roundtrip request to the server. Most applications benefit from the window-based coordinate system anyway and don't need global coordinates.
XTranslateCoordinates returns False and *dest_x and *dest_y are set to 0 if src_w and dest_w are on different screens. In addition, if the coordinates are contained in a mapped child of dest_w, then that child is returned in the child argument. Otherwise, XTranslateCoordinates returns True, sets *dest_x and *dest_y to the location of the point relative to dest_w, and sets child to None.
Window managers often need to perform a coordinate transformation from the coordinate space of one window to another, or unambiguously determine which subwindow a coordinate lies in. XTranslateCoordinates fulfills this need, while avoiding any race conditions by asking the server to perform this operation.
Errors
BadWindow
Related Commands
XGeometry, XParseGeometry.
XUndefineCursor
Xlib - Cursors—
Name
XUndefineCursor — disassociate a cursor from a window.
Synopsis
XUndefineCursor (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose cursor is to be undefined. |
Description
XUndefineCursor sets the cursor for a window to its parent's cursor, undoing the effect of a previous XDefineCursor for this window. On the root window, with no cursor specified, the default cursor is restored.
Errors
BadWindow
Related Commands
XDefineCursor, XCreateFontCursor, XCreateGlyphCursor, XCreatepixmapCursor, XFreeCursor, XRecolorCursor, XQueryBestCursor, XQueryBestSize.
XUngrabButton
—Xlib - Grabbing
Name
XUngrabButton — release a button from grab.
Synopsis
XUngrabButton (display, button, modifiers, w) Display *display; unsigned int button; unsigned int modifiers; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| button | Specifies the mouse button to be released from grab. Specify Button1, Button2, Button3, Button4, Button5, or the constant AnyButton, which is equivalent to issuing the ungrab request for all possible buttons. |
| modifiers | Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. AnyModifier is equivalent to issuing the ungrab button request for all possible modifier combinations (including no modifiers). |
| w | Specifies the ID of the window you want to release the button grab. |
Description
XUngrabButton cancels the passive grab on a button/key combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations (including the combination of no modifiers). A button of AnyButton is equivalent to issuing the request for all possible buttons. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadWindow
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XUngrabKey
Xlib - Grabbing—
Name
XUngrabKey — release a key from grab.
Synopsis
XUngrabKey (display, keycode, modifiers, w) Display *display; int keycode; unsigned int modifiers; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| keycode | Specifies the keycode. This keycode maps to the specific key you want to ungrab. Pass either a keycode or AnyKey. |
| modifiers | Specifies a set of keymasks. This is a bitwise OR of one or more of the following symbols: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask, or AnyModifier. AnyModifier is equivalent to issuing the ungrab key request for all possible modifier combinations (including no modifiers). |
| w | Specifies the ID of the window for which you want to ungrab the specified keys. |
Description
XUngrabKey cancels the passive grab on the key combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A keycode of AnyKey is equivalent to issuing the request for all possible nonmodifier key codes. This call has no effect on an active grab.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Errors
BadWindow
Related Commands
XGrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XUngrabKeyboard
—Xlib - Grabbing
Name
XUngrabKeyboard — release the keyboard from grab.
Synopsis
XUngrabKeyboard (display, time) Display *display; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| time | Specifies the time. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. If this time is earlier than the last-keyboard-grab time or later than the current server time, the keyboard will not be ungrabbed. |
Description
XUngrabKeyboard releases any active grab on the keyboard by this client. It executes as follows:
- Releases the keyboard and any queued events if this client has it actively grabbed from either XGrabKeyboard or XGrabKey.
- Does not release the keyboard and any queued events if time is earlier than the last-keyboard-grab time or is later than the current X server time.
- Generates FocusIn and FocusOut events.
The X server automatically performs an UngrabKeyboard if the event_window that initiated an active keyboard grab becomes unviewable.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer, XUngrabServer.
XUngrabPointer
Xlib - Pointer—
Name
XUngrabPointer — release the pointer from grab.
Synopsis
XUngrabPointer (display, time) Display *display; Time time;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| time | Specifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime. If this time is earlier than the last-pointer-grab time or later than current server time, the pointer will not be grabbed. |
Description
XUngrabPointer releases an active grab on the pointer by the calling client. It executes as follows:
- Releases the pointer and any queued events, if this client has actively grabbed the pointer from XGrabPointer, XGrabButton, or from a normal button press.
- Does not release the pointer if the specified time is earlier than the last-pointer-grab time or is later than the current X server time.
- Generates EnterNotify and LeaveNotify events.
The X server performs an XUngrabPointer automatically if the event_window or confine_to window for an active pointer grab becomes not viewable.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands
XQueryPointer, XWarpPointer, XGrabPointer, XChangeActivePointerGrab, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, XChangePointerControl.
XUngrabServer
—Xlib - Grabbing
Name
XUngrabServer — release the server from grab.
Synopsis
XUngrabServer (display) Display *display;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
Description
XUngrabServer releases the grabbed server, and begins execution of all the graphics requests queued during the grab. XUngrabServer is called automatically when a client closes its connection.
For more information, see Volume One, Chapter 9, The Keyboard and Pointer.
Related Commands
XGrabKey, XUngrabKey, XGrabKeyboard, XUngrabKeyboard, XGrabButton, XUngrabButton, XGrabPointer, XUngrabPointer, XChangeActivePointerGrab, XGrabServer.
XUninstallColormap
Xlib - Colormaps—
Name
XUninstallColormap — uninstall a colormap; install default if not already installed.
Synopsis
XUninstallColormap (display, cmap) Display *display; Colormap cmap;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| cmap | Specifies the colormap to be uninstalled. |
Description
If cmap is an installed map for its screen, it is uninstalled. If the screen's default colormap is not installed, it is installed.
If cmap is an installed map, a ColormapNotify event is generated on every window having this colormap as an attribute. If a colormap is installed as a result of the uninstall, a ColormapNotify event is generated on every window having that colormap as an attribute.
At any time, there is a subset of the installed colormaps, viewed as an ordered list, called the required list. The length of the required list is at most the min_maps specified for each screen in the Display structure. When a colormap is installed with XInstallColormap it is added to the head of the required list and the last colormap in the list is removed if necessary to keep the length of the list at min_maps. When a colormap is uninstalled with 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.
For more information on installing and uninstalling colormaps, see Volume One, Chapter 7, Color.
Related Commands
XCopyColormapAndFree, XCreateColormap, XFreeColormap, XGetStandardColormap, XInstallColormap, XSetStandardColormap, XListInstalledColormaps, XSetWindowColormap, DefaultColormap, DisplayCells.
XUnionRectWithRegion
—Xlib - Resource Manager
Name
XUnionRectWithRegion — add a rectangle to a region.
Synopsis
XUnionRectWithRegion(rectangle, src_region, dest_region) XRectangle *rectangle; Region src_region; Region dest_region;
Arguments
| rectangle | Specifies the rectangle to add to the region. |
| src_region | Specifies the source region to be used. |
| dest_region | Specifies the resulting region. May be the same as src_region. |
Description
XUnionRectWithRegion computes the destination region from a union of the specified rectangle and the specified source region. The source and destination regions may be the same.
One common application of this function is to simplify the combining of the rectangles specified in Expose events into a clip_mask in the GC, thus restricting the redrawn areas to the exposed rectangles. Use XUnionRectWithRegion to combine the rectangle in each Expose event into a region, then call XSetRegion. XSetRegion sets the clip_mask in a GC to the region. In this case, src_region and dest_region would be the same region.
If src_region and dest_region are not the same region, src_region is copied to dest_region before the rectangle is added to dest_region.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
The Region type is a pointer to an opaque data type. Its definition is not needed by programs.
Related Commands
XClipBox, XDestroyRegion, XEmptyRegion, XEqualRegion, XIntersectRegion, XOffsetRegion, XPointInRegion, XPolygonRegion, XRectInRegion, XSetRegion, XShrinkRegion, XSubtractRegion, XUnionRegion, XXorRegion.
XUnionRegion
Xlib - Regions—
Name
XUnionRegion — compute the union of two regions.
Synopsis
XUnionRegion (sra, srb, dr) Region sra, srb; Region dr;
Arguments
| sra | Specify the two regions in which you want to perform the computation. |
| srb | |
| dr | Returns the result of the computation. |
Description
XUnionRegion computes the union of two regions and places the result in dr. The resulting region will contain all the area of both the source regions.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XXorRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
XUniqueContext
—Xlib - Context Manager
Name
XUniqueContext — create a new context ID (not graphics context).
Synopsis
XContext XUniqueContext()
Description
The context manager allows association of arbitrary data with a resource ID. This call creates an instance of the XContext structure with a unique resource ID that will be used in subsequent calls to XFindContext, XDeleteContext, and XSaveContext.
For more information on the context manager, see Volume One, Chapter 13, Other Programming Techniques.
Structures
typedef int XContext;
Related Commands
XDeleteContext, XFindContext, XSaveContext.
XUnloadFont
Xlib - Fonts—
Name
XUnloadFont — unload a font.
Synopsis
XUnloadFont (display, font) Display *display; Font font;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| font | Specifies the ID of the font to be unloaded. |
Description
XUnloadFont indicates to the server that this client no longer needs the specified font. The font may be unloaded on the X server if this is the last client that needs the font. In any case, the font should never again be referenced by this client because X destroys the resource ID.
For more information on loading and unloading fonts, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadFont
Related Commands
XLoadFont, XLoadQueryFont, XFreeFont, XFreeFontInfo, XListFonts, XListFontsWithInfo, XFreeFontNames, XFreeFontPath, XGetFontPath, XQueryFont, XSetFont, XSetFontPath, XGetFontProperty, XCreateFontCursor.
XUnmapSubwindows
—Xlib - Mapping
Name
XUnmapSubwindows — unmap all sub windows of a given window.
Synopsis
XUnmapSubwindows (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose subwindows are to be unmapped. |
Description
XUnmapSubwindows performs an XUnmapwindow on all mapped children of w, in bottom to top stacking order.
XUnmapSubwindows also generates an UnmapNotify event on each subwindow and generates exposure events on formerly obscured windows. This is much more efficient than unmapping many subwindows one at a time, since much of the work need only be performed once for all of the subwindows rather than for each subwindow.
For more information on window mapping, see Volume One, Chapter 2, X Concepts.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XMapWindow, XUnmapWindow.
XUnmapWindow
Xlib - Mapping—
Name
XUnmapWindow — unmap a window.
Synopsis
XUnmapWindow (display, w) Display *display; Window w;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the window ID. |
Description
XUnmapWindow removes w and all its descendants from the screen. If w is already unmapped, XUnmapWindow has no effect. Otherwise, w is unmapped and an UnmapNotify event is generated. Normal exposure processing on formerly obscured windows is performed.
Descendants of w will not be visible until w is mapped again. In other words, the subwindows are still mapped, but are not visible because w is unmapped. Unmapping a w will generate exposure events on windows that were formerly obscured by w and its children.
For more information on window mapping, see Volume One, Chapter 2, X Concepts.
Errors
BadWindow
Related Commands
XMapRaised, XMapSubwindows, XMapWindow, XUnmapSubwindows.
XWarpPointer
—Xlib - Pointer
Name
XWarpPointer — move the pointer to another point on the screen.
Synopsis
XWarpPointer (display, src_w, dest_w, src_x, src_y, src_width, src_height, dest_x, dest_y) Display *display; Window src_w, dest_w; int src_x, src_y; unsigned int src_width, src_height; int dest_x, dest_y;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| src_w | Specifies the ID of the source window. You can also pass None. |
| dest_w | Specifies the ID of the destination window. You can also pass None. |
| src_x
src_y |
Specify the x and y coordinates within the source window. These are used with src_width and src_height to determine the rectangle the pointer must be in. They are not the present pointer position. If src_y is None, these coordinates are relative to the root window of src_w. |
| src_width
src_height |
Specify the width and height in pixels of the source window. Used with src_x and src_y. |
| dest_x | Specify the destination x and y coordinates within the destination window. |
| dest_y | If dest_y is None, these coordinates are relative to the root window of dest_w. |
Description
XWarpPointer moves the pointer suddenly from one point on the screen to another.
If dest_w is a window, XWarpPointer moves the pointer to [dest_x, dest_y] relative to the destination window's origin. If dest_w is None, XWarpPointer moves the pointer according to the offsets [dest_x, dest_y] relative to the current position of the pointer.
If src_window is None, the move is independent of the current cursor position (dest_x and dest_y use global coordinates). If the source window is not None, the move only takes place if the pointer is currently contained in a visible portion of the rectangle of the source window (including its inferiors) specified by src_x, src_y, src_width and src_height. If src_width is zero (0), the pointer must be between src_x and the right edge of the window to be moved. If src_height is zero (0), the pointer must be between src_y and the bottom edge of the window to be moved.
XWarpPointer cannot be used to move the pointer outside the confine_to window of an active pointer grab. If this is attempted the pointer will be moved to the point on the border of the confine_to window nearest the requested destination.
XWarpPointer generates events as if the user had (instantaneously) moved the pointer.
This function should not be used unless absolutely necessary, and then only in tightly controlled, predictable situations. It has the potential to confuse the user.
Errors
BadWindow
Related Commands
XQueryPointer, XGrabPointer, XChangeActivePointerGrab, XUngrabPointer, XGetPointerMapping, XSetPointerMapping, XGetPointerControl, XChangePointerControl.
XWindowEvent
—Xlib - Input Handling
Name
XWindowEvent — remove the next event matching mask and window.
Synopsis
XWindowEvent (display, w, event_mask, rep) Display *display; Window w; long event_mask; XEvent *rep; /* RETURN */
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| w | Specifies the ID of the window whose next matched event you want to remove. |
| event_mask | Specifies the event mask. See XSelectInput for a complete list of event masks. |
| rep | Specifies the event removed from the input queue. XWindowEvent returns this event to this argument. |
Description
XWindowEvent searches the event queue for specific event types from the specified window. XWindowEvent removes the next event in the queue which matches both the passed window and the passed mask. The event is copied into an XEvent supplied by the caller. Other events in the queue are not discarded. If no such event has been queued, XWindowEvent flushes the output buffer and waits until one is received.
In Release 1, the output buffer was always flushed by event-getting routines. In Release 2, the output buffer is flushed only if no matching events are found on the queue. This change is compatible with applications written for Release 1.
Structures
See individual event structures described in Volume One, Chapter 8, Events, and Appendix F, Structure Reference in this volume.
Related Commands
XSelectInput, XSetInputFocus, XGetInputFocus, XCheckWindowEvent, XCheckTypedEvent, XCheckTypedWindowEvent, XMaskEvent, XCheckMaskEvent, XNextEvent, XEventsQueued, XAllowEvents, XGetMotionEvents, XIfEvent, XCheckIfEvent, XPeekEvent, XPeekIfEvent, XPutBackEvent, XPending, XSynchronize, XSendEvent, QLength.
XWriteBitmapFile
Xlib - Pixmaps and Tiles—
Name
XWriteBitmapFile — write a bitmap to a file.
Synopsis
int XWriteBitmapFile (display, filename, bitmap, width, height, x_hot, y_hot) Display *display; char *filename; Pixmap bitmap; unsigned int width, height; int x_hot, y_hot;
Arguments
| display | Specifies a pointer to the Display structure; returned from XOpenDisplay. |
| filename | Specifies the filename to use. The format of the filename is operating system specific. |
| bitmap | Specifies the bitmap to be written. |
| width
height |
Specify the width and height in pixels of the bitmap to be written. |
| x_hot
y_hot |
Specify where to place the hotspot coordinates (or −1,−1 if none present) in the file. |
Description
XWriteBitmapFile writes a bitmap to a file. The file is written out in X version 11 bitmap format, which is the format created by the X version 11 bitmap program. Refer to that program's reference pages for details. While XReadBitmapFile can read in either X Version 10 format or X Version 11 format, XWriteBitmapFile always writes out X Version 11 format only. The difference between these formats is slight.
If the file cannot be opened for writing, XWriteBitmapFile returns BitmapOpenFailed. If insufficient memory is allocated XWriteBitmapFile returns BitmapNoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuccess.
If x_hot and y_hot are not −1, −1, then XWriteBitmapFile writes them out as the hotspot coordinates for the bitmap.
The following is an example of the contents of a bitmap file created. The name used (“gray” in this example) is the portion of filename after the last “/”.
#define gray_width 16
#define gray_height 16
#define gray_x_hot 8
#define gray_y_hot 8
static char gray_bits[] = {
0xf8, 0x1f, 0xe3, 0xc7, 0xcf, 0xf3, 0x9f, 0xf9, 0xbf, 0xfd, 0x33, 0xcc,
0x7f, 0xfe, 0x7f, 0xfe, 0x7e, 0x7e, 0x7f, 0xfe, 0x37, 0xec, 0xbb, 0xdd,
0x9c, 0x39, 0xcf, 0xf3, 0xe3, 0xc7, 0xf8, 0x1f};
For more information on bitmaps, see Volume One, Chapter 6, Drawing Graphics and Text.
Errors
BadDrawable
BadMatch
Related Commands
XSetTile, XQueryBestTile, XSetWindowBorderPixmap, XSetWindowBackgroundPixmap, XCreatePixmap, XCreatePixmapFromBitmapData, XFreePixmap, XQueryBestSize, XQueryBestStipple, XReadBitmapFile, XCreateBitmapFromData.
XXorRegion
Xlib - Regions—
Name
XXorRegion — calculate the difference between the union and intersection of two regions.
Synopsis
XXorRegion (sra, srb, dr) Region sra, srb; Region dr; /* RETURN */
Arguments
| sra | Specify the two regions on which you want to perform the computation. |
| srb | |
| dr | Returns the result of the computation. |
Description
XXorRegion calculates the union minus the intersection of two regions, and places it in dr. Xor is short for “Exclusive OR”, meaning that a pixel is included in dr if it is set in either sra or srb but not in both.
For more information on regions, see Volume One, Chapter 6, Drawing Graphics and Text.
Structures
/* * opaque reference to Regiondata type. * user won't need contents, only pointer. */ typedef struct _XRegion *Region;
Related Commands
XUnionRegion, XUnionRectWithRegion, XSubtractRegion, XShrinkRegion, XSetRegion, XRectInRegion, XPolygonRegion, XPointInRegion, XOffsetRegion, XIntersectRegion, XEmptyRegion, XCreateRegion, XDestroyRegion, XEqualRegion, XClipBox.
Get Xlib Reference Manual for Version 11 of the X Window System 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.
