Xlib Reference Manual for Version 11 of the X Window System

C

Macros

Once you have successfully connected your application to an X server, you can obtain data from the Display structure associated with that display. The Xlib interface provides a number of useful C language macros and corresponding functions for other language bindings which return data from the Display structure.

The function versions of these macros have the same names as the macros except that the function forms begin with the letter “X.” They use the same arguments. Using the macro versions is slightly more efficient in C because it eliminates function call overhead.

For the purposes of this appendix, the macros are divided into four categories: Display macros, Image Format macros, Keysym Classification macros, and Resource Manager macros. The macros are listed alphabetically within each category.

Note that some macros take as arguments an integer screen (scr_num) or pointer to a screen structure (scr_pnt). scr_num is returned by the DefaultScreen macro and scr_pnt is returned by the DefaultScreenOfDisplay macro.

Display Macros

AllPlanes ()	Return a value with all bits set suitable for use as a plane mask argument.
BlackPixel(display, scr_num)	Return the black pixel value in the default colormap that is created by XOpenDisplay.
BlackPixelOfScreen(scr_pnt)	Return the black pixel value in the default colormap of the specified screen.
CellsOfScreen(scr_pnt)	Return the number of colormap cells in the default colormap of the specified screen.
ConnectionNumber(display)	Return a connection number for the specified display. On a UNIX system, this is the file descriptor of the connection.
DefaultColormap(display, scr_num)	Return the default colormap for the specified screen. Most routine allocations of color should be made out of this colormap.
DefaultColormapOfScreen(scr_pnt)	Return the default colormap of the specified screen.
DefaultDepth(display,scr_num)	Return the depth (number of planes) of the root window for the specified screen. Other depths may also be supported on this screen. See Volume One, Chapter 7, Color, or the reference pages for XMatchVisualInfo and XGetVisualInfo to find out how to determine what depths are available.
DefaultDepthOfScreen(scr_pnt)	Return the default depth of the specified screen.
DefaultGC(display,scr_num)	Return the default graphics context for the specified screen.
DefaultGCOfScreen(scr_pnt)	Return the default graphics context (GC) of the specified screen.
DefaultRootWindow(display)	Return the ID of the root window on the default screen. Most applications should use RootWindow instead so that screen selection is supported.
DefaultScreen(display)	Return the integer that was specified in the last segment of the string passed to XOpenDisplay, or from the DISPLAY environment variable if NULL was used. For example, if the DISPLAY environment were Ogre:0.1 then DefaultScreen would return 1.
DefaultScreenOfDisplay(display)	Return the default screen of the specified display.
DefaultVisual(display,scr_num)	Return a pointer to the default visual structure for the specified screen.
DefaultVisualOfScreen(scr_pnt)	Return the default visual of the specified screen.
DisplayCells (display,scr_num)	Return the maximum possible number of colormap cells on the specified screen. This macro is misnamed: it should have been ScreenCells.
DisplayHeight(display,scr_num)	Return the height in pixels of the screen. This macro is misnamed: it should have been ScreenHeight.
DisplayHeightMM(display,scr_num)	Return the height in millimeters of the specified screen. This macro is misnamed: it should have been ScreenHeightMM.
DisplayOfScreen(scr_pnt)	Return the display associated with the specified screen.
DisplayPlanes(display,scr_num)	Return the number of planes on the specified screen. This macro is misnamed: it should have been ScreenPlanes.
DisplayString(display)	Return the string that was passed to XOpenDisplay when the current display was opened (or, if that was NULL, the value of the DISPLAY environment variable). This macro is useful in applications which invoke the fork system call and want to open a new connection to the same display from the child process.
DisplayWidth(display,scr_num)	Return the width in pixels of the screen. This macro is misnamed: it should have been ScreenWidth.
DisplayWidthMM(display,scr_num)	Return the width in millimeters of the specified screen. This macro is misnamed: it should have been ScreenWidthMM.
DoesBackingStore(scr_pnt)	Return a value indicating whether the screen supports backing stores. Values are whenMapped, NotUseful, or Always. See Volume One, Section 4.3.5 for a discussion of the backing store.
DoesSaveUnders(scr_pnt)	Return a Boolean value indicating whether the screen supports save unders. If True, the screen supports save unders. If False, the screen does not support save unders. See Volume One, Section 4.3.6 for a discussion of the save under.
dpyno(display)	Return the file descriptor of the connected display. On a UNIX system, you can then pass this returned file descriptor to the select(3) system call when your application program is driving more than one display at a time.
EventMaskOfScreen(scr_pnt)	Return the initial event mask for the root window of the specified screen.
HeightOfScreen(scr_pnt)	Return the height in pixels of the specified screen.
HeightMMOfScreen(scr_pnt)	Return the height in millimeters of the specified screen.
Keyboard(display)	Return the device ID for the main keyboard connected to the display.
LastKnownRequestProcessed (display)	Return the serial ID of the last known protocol request to have been issued. This can be useful in processing errors, since the serial number of failing requests are provided in the XErrorEvent structure.
MaxCmapsOfScreen(scr_pnt)	Return the maximum number of installed (hardware) colormaps supported by the specified screen.
MinCmapsOfScreen(scr_pnt)	Return the minimum number of installed (hardware) colormaps supported by the specified screen.
NextRequest(display)	Return the serial ID of the next protocol request to be issued. This can be useful in processing errors, since the serial number of failing requests are provided in the XErrorEvent structure.
PlanesOfScreen(scr_pnt)	Return the number of planes in the specified screen.
ProtocolRevision(display)	Return the minor protocol revision number of the X server.
ProtocolVersion(display)	Return the version number of the X protocol associated with the connected display. This is currently 11.
QLength(display)	Return the number of events that can be queued by the specified display.
RootWindow(display,scr_num)	Return the ID of the root window. This macro is necessary for routines that reference the root window or create a top-level window for an application.
RootWindowOfScreen(scr_pnt)	Return the ID of the root window of the specified screen.
ScreenCount(display)	Return the number of available screens on a specified display.
ScreenOfDisplay(display,scr_num)	Return the specified screen of the specified display.
ServerVendor(display)	Return a pointer to a null terminated string giving some identification of the owner of the X server implementation.
VendorRelease(display)	Return a number related to the release of the X server by the vendor.
whitePixel(display,scr_num)	Return the white pixel value in the default colormap that is created by XOpenDisplay.
WhitePixelOfScreen(scr_pnt)	Return the white pixel value in the default colormap of the specified screen.
WidthOfScreen(scr_pnt)	Return the width of the specified screen.
WidthMMOfScreen(scr_pnt)	Return the width of the specified screen in millimeters.

Image Format Macros

BitmapBitOrder(display)	Within each BitmapUnit, the leftmost bit in the bitmap as displayed on the screen is either the least or most significant bit in the unit. Values are LeastSignificant or MostSignificant.
BitmapPad(display)	Each scan line must be padded to a multiple of bits specified by the value returned by this macro.
BitmapUnit(display)	Return the size of a bitmap's unit. The scan line is quantized (calculated) in multiples of this value.
ByteOrder(display)	Specifies the required byte order for images for each scan line unit in XYFormat (bitmap) or for each pixel value in ZFormat. Values are LSBFirst or MSBFirst.
ImageByteOrder(display)	Specifies the required byte order for images for each scan line unit in XYFormat (bitmap) or for each pixel value in ZFormat. Values are LSBFirst or MSBFirst.

Keysym Classification Macros

You may want to test if a keysym of the defined set (XK_MISCELLANY) is, for example, on the key pad or the function keys. You can use the keysym macros to perform the following tests:

IsCursorKey(keysym)	Return True if the keysym represents a cursor key.
IsFunctionKey(keysym)	Return True if the keysym represents a function key.
IsKeypadKey(keysym)	Return True if the keysym represents a key pad.
IsMiscFunctionKey(keysym)	Return True if the keysym represents a miscellaneous function key.
IsModifierKey(keysym)	Return True if the keysym represents a modifier key.
IsPFKey(keysym)	Return True if the keysym represents a PF key.

Resource Manager Macros

These macros convert from strings to quarks and quarks to strings. They are used by the resource manager. Note that they do not follow the normal naming conventions for macros, since they begin with an X.

XrmStringToName(string)	Convert string to XrmName. Same as XStringToQuark.
XrmStringToClass(string)	Convert string to XrmClass. Same as XStringToQuark.
XrmStringToRepresentation(string)	Convert string to XrmRepresentation. Same as XStringToQuark.
XrmNameToString(name)	Convert XrmName to string. Same as XrmQuarkToString.
XrmClassToString(class)	Convert XrmClass to string. Same as XrmQuarkToString.
XrmRepresentationToString(type)	Convert XrmRepresentation to string. Same as XrmQuarkToString.