F
Structure Reference
This appendix describes the contents of the include files for Xlib.
Description of Contents
All include files are normally located in /usr/include/X11. All Xlib programs require <X11/Xlib.h>, which includes <X11/X.h>. <X11/Xlib.h> contains most of the structure declarations, while <X11/X.h> contains most of the defined constants. Virtually all programs will also require <X11/Xutil.h>, which include structure types and declarations applicable to window manager hints, colors, visuals, regions, standard geometry strings, and images.
Here is a summary of the contents of the include files:
| <X11/Xlib.h> | structure declarations for core Xlib functions. |
| <X11/X.h> | constant definitions for Xlib functions. |
| <X11/Xutil.h> | additional structure types and constant definitions for miscellaneous Xlib functions. |
| <X11/Xatom.h> | the predefined atoms for properties, types, and font characteristics. |
| <X11/cursorfont.h> | the constants used to select a cursor shape from the standard cursor font. |
| <X11/keysym.h> | predefined key symbols corresponding to keycodes. It includes <X11/keysymdef.h>. |
| <X11/Xresource.h> | resource manager structure definitions and function declarations. |
Resource Types
The following types are defined in <X11/X.h>:
unsigned long XID XID Colormap XID Cursor XID Drawable XID Font XID GContext XID KeySym XID Pixmap XID Window unsigned long Atom unsigned char KeyCode unsigned long Mask unsigned long Time unsigned long VisualID
Structure Definitions
This section lists all Xlib structure definitions in Xlib.h and Xutil.h, in alphabetical order, except the event structures which are listed separately in the next section.
Note that the first few structure types do not begin with X. These structures are intended to be opaque, so that Xlib's authors are free to change them in later releases. You are discouraged from accessing their members directly. However, only the GC structure is dangerous to access, because of the way GCs are implemented.
Before each structure is a description of what the structure is used for and a list of the Xlib routines that use the structure.
Depth
Depth defines a valid depth and list of associated visuals. A list of these structures is contained in the Screen structure, which is itself a member of the Display structure. Not used directly in any Xlib function. This structure should not be accessed directly, but instead through XGetVisualInfo and XMatchVisualInfo.
typedef struct {
int depth; /* this depth (Z) of the depth */
int nvisuals; /* number of Visual types at this depth */
Visual *visuals; /* list of visuals possible at this depth */
} Depth;
Display
Display describes the connection to the X server. A pointer to a structure of this type is returned by XOpenDisplay, and is subsequently the first argument to nearly every Xlib routine. Macros are provided to access most members of this structure.
/*
* 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 servers 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 Keymap notify */
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;
GC
GC describes a graphics context. A pointer to a structure of this type is returned by XCreateGC and subsequently used in all routines that draw or modify the GC. The members of this structure must not be accessed directly.
typedef struct _XGC {
XExtData *ext_data; /* hook for extension to hang data */
GContext gid; /* protocol ID for graphics context */
Bool rects; /* Boolean: TRUE if clipmask is list of rectangles */
Bool dashes; /* Boolean: TRUE if dash-list is really a list */
unsigned long dirty; /* cache dirty bits */
XGCValues values; /* shadow structure of values */
} *GC;
Screen
Screen describes the characteristics of a screen. A pointer to a list of these structures is a member of the Display structure. A pointer to a structure of this type is returned by XGetwindowAttributes. Macros are provided to access most members of this structure.
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;
ScreenFormat
ScreenFormat is a member of the Display structure. This structure is used internally for image operations. It is not used as an argument to or returned by any Xlib function. Macros are provided to access the members of this structure.
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 scan line_pad; /* scan line must be padded to this multiple*/
} ScreenFormat;
Visual
Visual describes a way of using color resources on a particular screen. A pointer to a visual structure is an argument to XCreateColormap, XCreateImage, and XCreateWindow. The valid visual structures for a screen can be determined with XGetVisualInfo or XMatchVisualInfo, or with the Defaultvisual (screen) macro. The visual used to create a window is returned by XGetwindowAttributes.
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
VisualID visualid; /* visual ID of this visual */
int class; /* class of screen (Pseudocolor, etc.) */
unsigned long red_mask; /* TrueColor, DirectColor only */
unsigned long green_mask; /* TrueColor, DirectColor only */
unsigned long blue_mask; /* TrueColor, DirectColor only */
int bits_per_rgb; /* log base 2 of distinct color values */
int map_entries; /* number of colormap entries */
} Visual;
XArc
XArc specifies the bounding box for an arc and two angles indicating the extent of the arc within the box. A list of these structures is used in XDrawArcs and XFillArcs.
typedef struct {
short x, y;
unsigned short width, height;
short angle1, angle2;
} XArc;
XChar2b
XChar2b specifies a character in a two-byte font. A list of structures of this type is an argument to XDrawImageString16, XDrawString16, XDrawText16, XQueryTextExtents16, XTextExtents16, and XTextWidth16. The only two-byte font currently available is Kanji (Japanese).
typedef struct { /* normal 16 bit characters are two bytes */
unsigned char byte1;
unsigned char byte2;
} XChar2b;
XCharStruct
XCharStruct describes the metrics of a single character in a font, or the overall characteristics of a font. This structure is the type of several of members of XFontStruct, and is used to return the overall characteristics of a string in XQueryTextExtents* and XTextExtents*.
typedef struct {
short lbearing; /* origin to left edge of raster */
short rbearing; /* origin to right edge of raster */
short width; /* advance to next char's origin */
short ascent; /* baseline to top edge of raster */
short descent; /* baseline to bottom edge of raster */
unsigned short attributes; /* per char flags (not predefined) */
} XCharStruct;
XClassHint
XClassHint is used to set or get the XA_WM_CLASS_HINT property for an application's top-level window, as arguments to XSetClassHint or XGetClassHint.
typedef struct {
char *res_name;
char *res_class;
} XClassHint;
XColor
XColor describes a single colorcell. This structure is used to specify and return the pixel value and RGB values for a colorcell. The flags indicate which of the RGB values should be changed when used in XStoreColors, XAllocNamedColor or XAllocColor. Also used in XCreateGlyphCursor, XCreatePixmapCursor, XLookupColor, XParseColor, XQueryColor, XQueryColors, and XRecolorCursor.
typedef struct {
unsigned long pixel;
unsigned short red, green, blue;
char flags; /* DoRed, DoGreen, DoBlue */
char pad;
} XColor;
XComposeStatus
XComposeStatus describes the current state of a multikey character sequence. Used in calling XLookupSt ring. This processing is not implemented in the Release 2 sample servers.
typedef struct _XComposeStatus {
char *compose_ptr; /* state table pointer */
int chars_matched; /* match state */
} XComposeStatus;
XExtCodes
XExtCodes is a structure used by the extension mechanism. This structure is returned by XInitExtension which is not a standard Xlib routine but should be called within the extension code. Its contents are not normally accessible to the application.
typedef struct { /* public to extension, cannot be changed */
int extension; /* extension number */
int major_opcode; /* major opcode assigned by server */
int first_event; /* first event number for the extension */
int first_error; /* first error number for the extension */
} XExtCodes;
XExtData
XExtData provides a way for extensions to attach private data to the existing structure types GC, Visual, Screen, Display, and XFontStruct. This structure is not used in normal Xlib programming.
typedef struct _XExtData {
int number; /* number returned by XRegisterExtension */
struct _XExtData *next; /* next item on list of data for structure */
int (*free_private)(); /* called to free private storage */
char *private_data; /* data private to this extension */
} XExtData;
XFontProp
XFontProp is used in XFontStruct. This structure allows the application to find out the names of additional font properties beyond the predefined set, so that they too can be accessed with XGetFontProperty. This structure is not used as an argument or return value for any core Xlib function.
typedef struct {
Atom name;
unsigned long card32;
} XFontProp;
XFontStruct
XFontStruct specifies metric information for an entire font. This structure is filled with the XLoadQueryFont and XQueryFont routines. ListFontsWithInfo also fills it but with metric information for the entire font only, not for each character. A pointer to this structure is used in the routines XFreeFont, XFreeFontInfo, XGetFontProp, XTextExtents*, and XTextWidth*.
typedef struct {
XExtData *ext_data; /* hook for extension to hang data */
Font fid; /* font ID for this font */
unsigned direction; /* 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;
XGCValues
XGCValues is used to set or change members of the GC by the routines XCreateGC and XChangeGC.
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 stippling */
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;
XHostAddress
XHostAddress specifies the address of a host machine that is to be added or removed from the host access list for a server. Used in XAddHost, XAddHosts, XListHosts, XRemoveHost, and XRemoveHosts.
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;
XIconSize
XIconSize is used to set or read the XA_WM_ICON_SIZE property. This is normally set by the window manager with XSetIconSizes and read by each application with XGetIconSizes.
typedef struct {
int min_width, min_height;
int max_width, max_height;
int width_inc, height_inc;
} XIconSize;
XImage
XImage describes an area of the screen. As you can tell from the funcs member, this structure is used in XCreateImage, XDestroyImage, XGetPixel, XPutPixel, XSubImage, and XAddPixel. It is also used in XGetImage, XGetSubImage and XPutImage.
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 arrangement */
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;
XKeyboardControl
XKeyboardControl is used to set user preferences with XChangeKeyboardControl.
typedef struct {
int key_click_percent;
int bell_percent;
int bell_pitch;
int bell_duration;
int led;
int led_mode;
int key;
int auto_repeat_mode; /* AutoRepeatModeOn, AutoRepeatModeOff,
* AutoRepeatModeDefault */
} XKeyboardControl;
XKeyboardState
XKeyboardState is used to return the current settings of user preferences with XGetKeyboardControl.
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;
XModifierKeymap
XModifierKeymap specifies which physical keys are mapped to modifier functions. This structure is returned by XGetModifierMapping, and is an argument to XDeleteModifiermapEntry, XFreeModifiermap, InsertModifiermapEntry, XNewModifiermap, and XSetModifierMapping.
typedef struct {
int max_keypermod; /* server's max # of keys per modifier */
KeyCode *modifiermap; /* an 8 by max_keypermod array of modifiers */
} XModifierKeymap;
XPoint
XPoint specifies the coordinates of a point. Used in XDrawPoints, XDrawLines, XFillPolygon, and XPolygonRegion.
typedef struct {
short x, y;
} XPoint;
XRectangle
XRectangle specifies a rectangle. Used in XClipBox, XDrawRectangles, XFillRectangles, XSetClipRectangles, and XUnionRectWithRegion.
typedef struct {
short x, y;
unsigned short width, height;
} XRectangle;
XSegment
XSegment specifies two points. Used in XDrawSegments.
typedef struct {
short x1, y1, x2, y2;
} XSegment;
XSetWindowAttributes
XSetWindowAttributes contains all the attributes that can be set without window manager intervention. Used in XChangeWindowAttributes and XCreateWindow.
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 preserved 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;
XSizeHints
XSizeHints describes a range of preferred sizes and aspect ratios. Used to set the XA_WM_NORMAL_HINTS and XA_WM_ZOOM_HINTS properties for the window manager with XSetNormalHints, XSetZoomHints, XSetStandardProperties or XSetSizeHints. Also used in reading these properties with XGetSizeHints, XGetNormalHints, or XGetZoomHints.
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;
} XSizeHints;
XStandardColormap
XStandardColormap describes a standard colormap, giving its ID and its color characteristics. This is the format of the standard colormap properties set on the root window, which can be changed with XSetStandardProperties and changed with XGetStandardProperties.
typedef struct {
Colormap colormap;
unsigned long red_max;
unsigned long red_mult;
unsigned long green_max;
unsigned long green_mult;
unsigned long blue_max;
unsigned long blue_mult;
unsigned long base_pixel;
} XStandardColormap;
XTextItem
XTextItem describes a string, the font to print it in, and the horizontal offset from the previous string drawn or from the location specified by the drawing command. Used in XDrawText.
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;
XTextItem16
XTextItem16 describes a string in a two-byte font, the font to print it in, and the horizontal offset from the previous string drawn or from the location specified by the drawing command. Used in XDrawText16.
typedef struct {
XChar2b *chars; /* two-byte characters */
int nchars; /* number of characters */
int delta; /* delta between strings */
Font font; /* font to print it in, None don't change */
} XTextItem16;
XTimeCoord
XTimeCoord specifies a time and position pair, for use in tracking the pointer with XGetMotionEvents. This routine is not supported on all systems.
typedef struct {
Time time;
unsigned short x, y;
} XTimeCoord;
XVisualInfo
XVisualInfo is used in XGetVisualInfo; and XMatchVisualInfo to specify the desired visual type. The visual member of XVisualInfo is used for the visual argument of XCreateWindow or XCreateColormap.
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;
XWMHints
XWMHints describes various application preferences for communication to the window manager via the XA_WM_HINTS property. Used in XSetWMHints and XGetWMHints.
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 */
/* this structure may be extended in the future */
} XWMHints;
XWindowAttributes
XWindowAttributes describes the complete set of window attributes, including those that can't be set without window manager interaction. This structure is returned by XGetwindowAttributes. It is not used by XChangeWindowAttributes or XCreateWindow.
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; /* 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;
} XWindowAttributes;
XWindowChanges
XWindowChanges describes a configuration for a window. Used in XConfigureWindow, which can change the screen layout and therefore can be intercepted by the window manager. This sets some of the remaining members of XWindowAttributes that cannot be set with XChangeWindowAttributes or XCreateWindow.
typedef struct {
int x, y;
int width, height;
int border_width;
Window sibling;
int stack_mode;
} XWindowChanges;
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.
