Xlib is an X11 protocol client library (computer science) in the C programming language. It contains functions that allow programmers to write programs that communicate with an X11 server without knowing the details of the protocol (computing). Few application use Xlib directly; rather, they employ other libraries that use Xlib functions to provide widget toolkits:

Xlib appeared around 1985, and is currently used in GUIs for many Unix-like operating systems.

The XCB project is an attempt to provide a lightweight alternative to Xlib.

=Data types=

The main types of data in Xlib are the Display structure and the types of identificators.

Informally, a display is a phisical or virtual device where graphical operations are done. The Display structure of the Xlib library is not exactly a representation of a display, however. Rather, the Display structure represents a channel from the client to the server. For example, in a Unix-like operatating system, the Display structure contains the file handler relative to the socket used to communicate with the server (this number can be retrieved using the ConnectionNumber macro). On the other hand, such a channel must be relative to a single and fixed display. The information relative to the display the channel is about is also stored in the Display structure. Therefore, a Display structure contains the identificator of the channel used by the client to interact with the server about a given display, and also contains information relative to this display.

Data about windows, colormaps, etc. are stored in the server. The client only knows identificators of these objects. In the following description, these identifiers are assumed to be integer numbers. The types Windows, Pixmap, Font, Colormap, etc. are all identifiers, i.e., numbers. For example, creation of a window is done by the client requesting the creation of a window to the server; the server creates the window and returns to the client a number; this number can then be used by the client for doing other requests to the server about the same window.

The identificators are unique to the server. Most of them can be used by different applications to refer to the same objects. For example, two applications can connect to the same server referring to the same display. This creates two different channels; therefore, the two application will have two different Display structures. However, the same number refers to the same windows in the two applications.

=Protocol and events=

Functions that do requests to the server usually do not send these requests immediately but store them in a buffer, called the output buffer . The term output in this case refer to the output from the client that is directed to the server: the output buffer can can contain all kinds of requests to the server, not only those having a visible effect on the screen. The output buffer is guaranteed to be flushed (i.e., all requests done so far are sent to the server) after a call to the functions XSync or XFlush or a function that returns a value from the server (these functions block until the answer is received).

The Xlib library stores the received events in a queue. The client application can inspect and retrieve events from the queue. While the X server sends events asynchronically, applications using the Xlib library are required to call the functions for accessing the queue when they need to access these events. These functions typically flush the output buffer.

Errors are instead received and treated asynchronically: the application can provide an error handler that will be called whenever an error message from the server is received.

The content of a window is not guaranteed to be preserved if the window of one of its parts are made not visible. In this case, the application are sent an Expose event when the window of one part of it is made visible again. The application is then supposed to draw the window content again.

=Functions=

The functions in the Xlib library can be grouped in:

# operations on the connection (XOpenDisplay, XCloseDisplay, ...); # requests to the server, including requests for operations (XCreateWindow, XCreateGC,...) and requests for information (XGetWindowProperty, ...); and # operations that are local to the client: operations on the event queue (XNextEvent, XPeekEvent, ...) and other operations on local data (XLookupKeysym, XParseGeometry, XSetRegion, XCreateImage, XSaveContext, ...)

=Example=

The following program creates a window with a little black square in it.

/* Simple Xlib application showing a box in a window. */ #include int main() { Display *d; int s; Window w; XEvent e; /* open connection with the server */ d=XOpenDisplay(NULL); if(d==NULL) { printf( Cannot open display ); exit(1); } s=DefaultScreen(d); /* create window */ w=XCreateSimpleWindow(d, RootWindow(d, s), 10, 10, 100, 100, 1, BlackPixel(d, s), WhitePixel(d, s)); /* select kind of events we are interested in */ XSelectInput(d, w, ExposureMask | KeyPressMask); /* map (show) the window */ XMapWindow(d, w); /* event loop */ while(1) { XNextEvent(d, &e); /* draw or redraw the window */ if(e.type==Expose) { XFillRectangle(d, w, DefaultGC(d, s), 20, 20, 10, 10); } /* exit on key press */ if(e.type==KeyPress) break; } /* close connection to display */ XCloseDisplay(d); return 0; } Technically, the creation of such a window is realized by a sequence of operations. First a connection with the server is opened, and the request of creation of a window is done. A separate operation is necessary for mapping the window, that is, making it visible on the screen.

The operation of drawing the square cannot be done only once after the window is created. Indeed, the content of the window must be drawn each time the window is (totally or in part) made visible while it was not before. This happens when the window is first made visible and, for example, when the window is de-iconified or when a part of the window that was covered by other windows is made visible. The application is informed that the window or a part of it has to be drawn by the reception of an Expose event.

The drawing of the window content is therefore made inside the loop handling the events. Before entering this loop, the events the application is interested into are selected, in this case with XSelectInput. The event loop waits for an incoming event: if this event is a key press, the application exists; if it is an expose event, the window content is drawn. The function XNextEvent blocks until an event is received. This function flushes the output buffer if there is no event in the queue.

=Other libraries=

Xlib does not provide direct support for buttons, menus, scrollbar, etc. Support for such widgets in general is done by the intrinsics library (Xt), and specific widgets are provided by widget set libraries such as Xaw and Motif (widget toolkit). Applications using these libraries typically specify the content of the window before entering the main loop; redrawing is done by the library automatically.

=See also=

=External links=