| Page: | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
|---|
Before your program can use a display, you must establish a connection to the X server. Once you have established a connection, you then can use the Xlib macros and functions discussed in this chapter to return information about the display. This chapter discusses how to:
The chapter concludes with a general discussion of what occurs when the connection to the X server is closed.
| Home |
|---|
To open a connection to the X server that controls a display, use XOpenDisplay.
Display *XOpenDisplay (display_name) char *display_name;
The encoding and interpretation of the display name is implementation dependent. Strings in the Host Portable Character Encoding are supported; support for other characters is implementation dependent. On POSIX-conformant systems, the display name or DISPLAY environment variable can be a string in the format:
hostname:number.screen_number
The XOpenDisplay function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server. XOpenDisplay connects your application to the X server through TCP or DECnet communications protocols, or through some local inter-process communication protocol. If the hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects using TCP streams. If the hostname is not specified, Xlib uses whatever it believes is the fastest transport. If the hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay connects using DECnet. A single X server can support any or all of these transport mechanisms simultaneously. A particular Xlib implementation can support many more of these transport mechanisms.
If successful, XOpenDisplay returns a pointer to a Display structure, which is defined in <X11/Xlib.h>. If XOpenDisplay does not succeed, it returns NULL. After a successful call to XOpenDisplay, all of the screens in the display can be used by the client. The screen number specified in the display_name argument is returned by the DefaultScreen macro (or the XDefaultScreen function). You can access elements of the Display and Screen structures only by using the information macros or functions. For information about using macros and functions to obtain information from the Display structure, see section 2.2.1.
X servers may implement various types of access control mechanisms (see section 9.8).
| Home |
|---|
The Xlib library provides a number of useful macros and corresponding functions that return data from the Display structure. The macros are used for C programming, and their corresponding function equivalents are for other language bindings. This section discusses the:
All other members of the Display structure (that is, those for which no macros are defined) are private to Xlib and must not be used. Applications must never directly modify or inspect these private members of the Display structure.
Applications should not directly modify any part of the Display and Screen structures. The members should be considered read-only, although they may change as the result of other operations on the display.
The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both can return.
AllPlanes unsigned long XAllPlanes()
Both return a value with all bits set to 1 suitable for use in a plane argument to a procedure.
Both BlackPixel and WhitePixel can be used in implementing a monochrome application. These pixel values are for permanently allocated entries in the default colormap. The actual RGB (red, green, and blue) values are settable on some screens and, in any case, may not actually be black or white. The names are intended to convey the expected relative intensity of the colors.
BlackPixel(display, screen_number)
unsigned long XBlackPixel(display, screen_number)
Display *display;
int screen_number;
Both return the black pixel value for the specified screen.
WhitePixel(display, screen_number)
unsigned long XWhitePixel(display, screen_number)
Display *display;
int screen_number;
Both return the white pixel value for the specified screen.
ConnectionNumber(display)
int XConnectionNumber(display)
Display *display;
Both return a connection number for the specified display. On a POSIX-conformant system, this is the file descriptor of the connection.
DefaultColormap(display, screen_number)
Colormap XDefaultColormap(display, screen_number)
Display *display;
int screen_number;
Both return the default colormap ID for allocation on the specified screen. Most routine allocations of color should be made out of this colormap.
DefaultDepth(display, screen_number)
int XDefaultDepth(display, screen_number)
Display *display;
int screen_number;
Both return the depth (number of planes) of the default root window for the specified screen. Other depths may also be supported on this screen (see XMatchVisualInfo).
To determine the number of depths that are available on a given screen, use XListDepths.
int *XListDepths(display, screen_number, count_return)
Display *display;
int screen_number;
int *count_return;
The XListDepths function returns the array of depths that are available on the specified screen. If the specified screen_number is valid and sufficient memory for the array can be allocated, XListDepths sets count_return to the number of available depths. Otherwise, it does not set count_return and returns NULL. To release the memory allocated for the array of depths, use XFree.
DefaultGC(display, screen_number)
GC XDefaultGC(display, screen_number)
Display *display;
int screen_number;
Both return the default graphics context for the root window of the specified screen. This GC is created for the convenience of simple applications and contains the default GC components with the foreground and background pixel values initialized to the black and white pixels for the screen, respectively. You can modify its contents freely because it is not used in any Xlib function. This GC should never be freed.
DefaultRootWindow(display)
Window XDefaultRootWindow(display)
Display *display;
Both return the root window for the default screen.
DefaultScreenOfDisplay(display)
Screen *XDefaultScreenOfDisplay(display)
Display *display;
Both return a pointer to the default screen.
ScreenOfDisplay(display, screen_number)
Screen *XScreenOfDisplay(display, screen_number)
Display *display;
int screen_number;
Both return a pointer to the indicated screen.
DefaultScreen(display)
int XDefaultScreen(display)
Display *display;
Both return the default screen number referenced by the XOpcnDisplay function. This macro or function should be used to retrieve the screen number in applications that will use only a single screen.
DefaultVisual(display, screen_number)
Visual * XDefaultVisual(display, screen_number )
Display *display;
int screen_number;
Both return the default visual type for the specified screen. For further information about visual types, see section 3.1.
DisplayCells(display, screen_number)
int XDisplayCells(display, screen_number)
Display *display;
int screen_number;
Both return the number of entries in the default colormap.
DisplayPlanes(display, screen_number)
int XDisplayPlanes(display, screen_number)
Display *display;
int screen_number;
Both return the depth of the root window of the specified screen. For an explanation of depth, see the glossary.
DisplayString(display)
char *XDisplayString(display)
Display *display;
Both return the string that was passed to XOpenDisplay when the current display was opened. On POSIX-conformant systems, if the passed string was NULL, these return the value of the DISPLAY environment variable when the current display was opened. These are useful to applications that invoke the fork system call and want to open a new connection to the same display from the child process as well as for printing error messages.
long XExtendedMaxRequestSize(display)
Display *display;
The XExtendedMaxRequestSize function returns zero if the specified display does not support an extended-length protocol encoding; otherwise, it returns the maximum request size (in 4-byte units) supported by the server using the extended-length encoding. The Xlib functions XDrawLines, XDrawArcs, XFillPolygon, XChangeProperty, XSetClipRectangles, and XSetRegion will use the extended-length encoding as necessary, if supported by the server. Use of the extended-length encoding in other Xlib functions (for example, XDrawPoints, XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, XPutimage) is permitted but not required; an Xlib implementation may choose to split the data across multiple smaller requests instead.
long XMaxRequestSize(display)
Display *display;
The XMaxRequestSize function returns the maximum request size (in 4-byte units) supported by the server without using an extended-length protocol encoding. Single protocol requests to the server can be no larger than this size unless an extended-length protocol encoding is supported by the server. The protocol guarantees the size to be no smaller than 4096 units (16384 bytes). Xlib automatically breaks data up into multiple protocol requests as necessary for the following functions: XDrawPoints, XDrawRectangles, XDrawSegments, XFillArcs, XFillRectangles, and XPutimage.
LastKnownRequestProcessed(display) unsigned long XLastKnownRequestProcessed(display) Display *display;
Both extract the full serial number of the last request known by Xlib to have been processed by the X server. Xlib automatically sets this number when replies, events, and errors are received.
NextRequest(display) unsigned long XNextRequest(display) Display *display;
Both extract the full serial number that is to be used for the next request. Serial numbers are maintained separately for each display connection.
ProtocolVersion(display)
int XProtocolVersion(display)
Display *display;
Both return the major version number (11) of the X protocol associated with the connected display.
ProtocolRevision(display)
int XProtocolRevision(display)
Display *display;
Both return the minor protocol revision number of the X server.
QLength(display)
int XQLength(display)
Display *display;
Both return the length of the event queue for the connected display. Note that there may be more events that have not been read into the queue yet (see XEventsQueued).
RootWindow(display, screen_number) Window XRootWindow(display, screen_number) Display *display; int screen_number;
Both return the root window. These are useful with functions that need a drawable of a particular screen and for creating top-level windows.
ScreenCount(display)
int XScreenCount(display)
Display *display;
Both return the number of available screens.
ServerVendor(display)
char *XServerVendor(display)
Display *display;
Both return a pointer to a null-terminated string that provides some identification of the owner of the X server implementation. If the data returned by the server is in the Latin Portable Character Encoding, then the string is in the Host Portable Character Encoding. Otherwise, the contents of the string are implementation dependent.
VendorRelease (display)
int XVendorRelease(display)
Display *display;
Both return a number related to a vendor's release of the X server.
Applications are required to present data to the X server in a format that the server demands. To help simplify applications, most of the work required to convert the data is provided by Xlib (see sections 8.7 and 16.8).
The XPixmapFormatValues structure provides an interface to the pixmap format information that is returned at the time of a connection setup. It contains:
| typedef struct { | |
| int
depth; int bits_per_pixel; int scanline_pad; | |
| } XPixmapFormatValues; | |
To obtain the pixmap format information for a given display, use XListPixmapFormats.
XPixmapFormatValues *XListPixmapFormats(display, count_return) Display *display; int *count_return;
The XListPixmapFormats function returns an array of XPixmapFormatValues structures that describe the types of Z format images supported by the specified display. If insufficient memory is available, XListPixmapFormats returns NULL. To free the allocated storage for the XPixmapFormatValues structures, use XFree.
The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both return for the specified server and screen. These are often used by toolkits as well as by simple applications.
ImageByteOrder(display)
int XImageByteOrder(display)
Display *display;
Both specify the required byte order for images for each scanline unit in XY format (bitmap) or for each pixel value in Z format. The macro or function can return either LSBFirst or MSBFirst.
BitmapUnit(display)
int XBitmapUnit(display)
Display *display;
Both return the size of a bitmap's scanline unit in bits. The scanline is calculated in multiples of this value.
BitmapBitOrder(display)
int XBitmapBitOrder(display)
Display *display;
Within each bitmap unit, the left-most bit in the bitmap as displayed on the screen is either the least-significant or most-significant bit in the unit. This macro or function can return LSBFirst or MSBFirst.
BitmapPad(display)
int XBitmapPad(display)
Display *display;
Each scanline must be padded to a multiple of bits returned by this macro or function.
DisplayHeight(display, screen_number)
int XDisplayHeight(display, screen_number)
Display *display;
int screen_number;
Both return an integer that describes the height of the screen in pixels.
DisplayHeightMM(display, screen_number)
int XDisplayHeightMM(display, screen_number)
Display *display;
int screen_number;
Both return the height of the specified screen in millimeters.
DisplayWidth(display, screen_number)
int XDisplayWidth(display, screen_number)
Display *display;
int screen_number;
Both return the width of the screen in pixels.
DisplayWidthMM(display, screen_number)
int XDisplayWidthMM(display, screen_number )
Display *display;
int screen_number;
Both return the width of the specified screen in millimeters.
| Home |
|---|
The following lists the C language macros, their corresponding function equivalents that are for other language bindings, and what data they both can return. These macros or functions all take a pointer to the appropriate screen structure.
BlackPixelOfScreen(screen)
unsigned long XBlackPixelOfScreen(screen)
Screen *screen;
Both return the black pixel value of the specified screen.
WhitePixelOfScreen(screen)
unsigned long XWhitePixelOfScreen(screen)
Screen *screen;
Both return the white pixel value of the specified screen.
CellsOfScreen(screen)
int XCellsOfScreen(screen)
Screen *screen;
Both return the number of colormap cells in the default colormap of the specified screen.
DefaultColormapOfScreen(screen) Colormap XDefaultColormapOfScreen(screen) Screen *screen;
Both return the default colormap of the specified screen.
DefaultDepthOfScreen(screen)
int XDefaultDepthOfScreen(screen)
Screen *screen;
Both return the depth of the root window.
DefaultGCOfScreen (screen) GC XDefaultGCOfScreen(screen) Screen *screen;
Both return a default graphics context (GC) of the specified screen, which has the same depth as the root window of the screen. The GC must never be freed.
DefaultVisualOfScreen (screen) Visual *XDefaultVisualOfScreen(screen) Screen *screen;
Both return the default visual of the specified screen. For information on visual types, see section 3.1.
DoesBackingStore(screen)
int XDoesBackingStore(screen)
Screen *screen;
Both return a value indicating whether the screen supports backing stores. The value returned can be one of WhenMapped, NotUseful, or Always (see section 3.2.4).
DoesSaveUnders(screen) Bool XDoesSaveUnders(screen) Screen *screen;
Both 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 section 3.2.5).
DisplayOfScreen (screen)
Display *XDisplayOfScreen(screen)
Screen *screen;
Both return the display of the specified screen.
int XScreenNumberOfScreen(screen)
Screen *screen;
The XScreenNumberOfScreen function returns the screen index number of the specified screen.
EventMaskOfScreen(screen) long XEventMaskOfScreen(screen) Screen *screen;
Both return the event mask of the root window for the specified screen at connection setup time.
WidthOfScreen(screen)
int XWidthOfScreen(screen)
Screen *screen;
Both return the width of the specified screen in pixels.
HeightOfScreen(screen)
int XHeightOfScreen(screen)
Screen *screen;
Both return the height of the specified screen in pixels.
WidthMMOfScreen(screen)
int XWidthMMOfScreen(screen)
Screen *screen;
Both return the width of the specified screen in millimeters.
HeightMMOfScreen(screen)
int XHeightMMOfScreen (screen)
Screen *screen;
Both return the height of the specified screen in millimeters.
MaxCmapsOfScreen(screen)
int XMaxCmapsOfScreen(screen)
Screen *screen;
Both return the maximum number of installed colormaps supported by the specified screen (see section 9.3).
MinCmapsOfScreen(screen)
int XMinCmapsOfScreen(screen)
Screen *screen;
Both return the minimum number of installed colormaps supported by the specified screen (see section 9.3).
PlanesOfScreen(screen)
int XPlanesOfScreen(screen)
Screen *screen;
Both return the depth of the root window.
RootWindowOfScreen(screen)
Window XRootWindowOfScreen(screen)
Screen *screen;
Both return the root window of the specified screen.
| Home |
|---|
To execute a NoOperation protocol request, use XNoOp.
XNoOp(display) Display *display;
The XNoOp function sends a NoOperation protocol request to the X server, thereby exercising the connection.
| Home |
|---|
To free in-memory data that was created by an Xlib function, use XFree.
XFree(dara) void *data;
The XFree function is a general-purpose Xlib routine that frees the specified data. You must use it to free any objects that were allocated by Xlib, unless an alternate function is explicitly specified for the object. A NULL pointer cannot be passed to this function.
| Home |
|---|
To close a display or disconnect from the X server, use XCloseDisplay.
XCloseDisplay(display) Display *display;
The XCloseDisplay function closes the connection to the X server for the display specified in the Display structure and destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources that the client has created on this display, unless the close-down mode of the resource has been changed (see XSetCloseDownMode). Therefore, these windows, resource IDs, and other resources should never be referenced again or an error will be generated. Before exiting, you should call XCloseDisplay explicitly so that any pending errors are reported as XCloseDisplay performs a final XSync operation.
XCloseDisplay can generate a BadGC error.
Xlib provides a function to permit the resources owned by a client to survive after the client's connection is closed. To change a client's close-down mode, use XSetCloseDownMode.
XSetCloseDownMode(display, close_mode) Display *display; int close_mode;
The XSetCloseDownMode defines what will happen to the client's resources at connection close. A connection starts in DestroyAll mode. For information on what happens to the client's resources when the close_mode argument is RetainPermanent or RetainTemporary, see section 2.6.
XSetCloseDownMode can generate a BadValue error.
| Home |
|---|
When the X server's connection to a client is closed either by an explicit call to XCloseDisplay or by a process that exits, the X server performs the following automatic operations:
It disowns all selections owned by the client (see XSetSelectionOwner).
When the close-down mode is DestroyAll, the X server destroys all of a client's resources as follows:
Additional processing occurs when the last connection to the X server closes. An X server goes through a cycle of having no connections and having some connections. When the last connection to the X server closes as a result of a connection closing with the close_mode of DestroyAll, the X server does the following:
It resets its state as if it had just been started. The X server begins by destroying all lingering resources from clients that have terminated in RetainPermanent or RetainTemporary mode.
However, the X server does not reset if you close a connection with a close-down mode set to RetainPermanent or RetainTemporary.
| Home |
|---|
On systems that have threads, support may be provided to permit multiple threads to use Xlib concurrently.
To initialize support for concurrent threads, use XInitThreads.
Status XInitThreads( );
The XInitThreads function initializes Xlib support for concurrent threads. This function must be the first Xlib function a multi-threaded program calls, and it must complete before any other Xlib call is made. This function returns a nonzero status if initialization was successful; otherwise, it returns zero. On systems that do not support threads, this function always returns zero.
It is only necessary to call this function if multiple threads might use Xlib concurrently. If all calls to Xlib functions are protected by some other access mechanism (for example, a mutual exclusion lock in a toolkit or through explicit client programming), Xlib thread initialization is not required. It is recommended that single-threaded programs not call this function.
To lock a display across several Xlib calls, use XLockDisplay.
void XLockDisplay(display) Display *display;
The XLockDisplay function locks out all other threads from using the specified display. Other threads attempting to use the display will block until the display is unlocked by this thread. Nested calls to XLockDisplay work correctly; the display will not actually be unlocked until XUnlockDisplay has been called the same number of times as XLockDisplay. This function has no effect unless Xlib was successfully initialized for threads using XlnitThreads.
To unlock a display, use XUnlockDisplay.
void XUnlockDisplay(display) Display *display;
The XUnlockDisplay function allows other threads to use the specified display again. Any threads that have blocked on the display are allowed to continue. Nested locking works correctly; if XLockDisplay has been called multiple times by a thread, then XUnlockDisplay must be called an equal number of times before the display is actually unlocked. This function has no effect unless Xlib was successfully initialized for threads using XInitThreads.
| Home |
|---|
In addition to the connection to the X server, an Xlib implementation may require connections to other kinds of servers (for example, to input method servers as described in Chapter 13). Toolkits and clients that use multiple displays, or that use displays in combination with other inputs, need to obtain these additional connections to correctly block until input is available and need to process that input when it is available. Simple clients that use a single display and block for input in an Xlib event function do not need to use these facilities.
To track internal connections for a display, use XAddConnectionWatch.
typedef void (*XConnectionWatchProc)(display, client_data, fd, opening, watch_data)
Display *display;
XPointer client_data;
int fd;
Bool opening;
XPointer *watch_data;
Status XAddConnectionWatch(display, procedure, client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;
The XAddConnectionWatch function registers a procedure to be called each time Xlib opens or closes an internal connection for the specified display. The procedure is passed the display, the specified client_data, the file descriptor for the connection, a Boolean indicating whether the connection is being opened or closed, and a pointer to a location for private watch data. If opening is True, the procedure can store a pointer to private data in the location pointed to by watch_data; when the procedure is later called for this same connection and opening is False, the location pointed to by watch_data will hold this same private data pointer.
This function can be called at any time after a display is opened. If internal connections already exist, the registered procedure will immediately be called for each of them, before XAddConnectionWatch returns. XAddConnectionWatch returns a nonzero status if the procedure is successfully registered; otherwise, it returns zero.
The registered procedure should not call any Xlib functions. If the procedure directly or indirectly causes the state of internal connections or watch procedures to change, the result is not defined. If Xlib has been initialized for threads, the procedure is called with the display locked and the result of a call by the procedure to any Xlib function that locks the display is not defined unless the executing thread has externally locked the display using XLockDisplay.
To stop tracking internal connections for a display, use XRemoveConnectionWatch.
Status XRemoveConnectionWatch(display, procedure,
client_data)
Display *display;
XWatchProc procedure;
XPointer client_data;
The XRemoveConnectionWatch function removes a previously registered connection watch procedure. The client_data must match the client_data used when the procedure was initially registered.
To process input on an internal connection, use XProcesslnternalConnection.
void XProcessInternalConnection(display, fd) Display *display; int fd;
The XProcesslnternalConnection function processes input available on an internal connection. This function should be called for an internal connection only after an operating system facility (for example, select or poll) has indicated that input is available; otherwise, the effect is not defined.
To obtain all of the current internal connections for a display, use XInternalConnectionNumbers .
Status XInternalConnectionNumbers(display, fd_return,
count_return)
Display *display;
int **fd_return;
int *count_ return;
The XInternalConnectionNumbers function returns a list of the file descriptors for all internal connections currently open for the specified display. When the allocated list is no longer needed, free it by using XFree. This functions returns a nonzero status if the list is successfully allocated; otherwise, it returns zero.
| Home |
|---|
| Contents | Previous Chapter | Next Chapter |