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 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*(2^nreds) independent red entries, ncolors*(2^ngreens) independent green entries, and ncolors*(2^nblues) independent blue entries in the colormap. This is true even for Pseudocolor. This does not cause problems, though, because when the colormap entry for a pixel value is changed using XStoreColors 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.

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.

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.

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.

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.

images

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

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

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.

images

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

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

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.

images

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.

images

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

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.

images

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.

images

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

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.

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.

images

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

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.

images

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

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

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.

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.

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.

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. If hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects the hardware display to TCP streams. If hostname is “unix” and a single colon (:) separates it from the display number, XOpenDisplay connects the hardware display to UNIX domain IPC streams. If hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay connects the hardware display to DECnet streams. To use DECnet, however, you must build all software for DECnet. A single X server will accept both TCP and DECnet connections if it has been built for DECnet.
server	Specifies the number of the server on its host machine. This display number may be followed by a period (.). A single CPU can have more than one display; the displays are 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.

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.

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.

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

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.

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 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 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: on
```
because 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.

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 3ⁿ, 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.

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.

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.

images

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.

images

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.

images

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.

images

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:

images

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.

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.

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.

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

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.

Start your free trial