tutorial (xcb.freedesktop.org)

Introduction

Most application developers will want to use a much higher-level GUI toolkit, like Motif, LessTiff, GTK, Qt, EWL, or ETK or perhaps use the higher-level drawing library Cairo. However, knowing about the layers those other libraries are built on top of is not a bad idea.

What is XCB and why does it exists?

XCB ("X C Binding") is an low-level API for the X window server. XCB is an alternative to Xlib, which has been the standard C binding for the X window system protocol for many years now.

Small platforms: Xlib is difficult to make it smaller

Latency hiding: Xlib requests block until the reply appears, whether the result is needed immediately or not.

Direct access to th protocol: Xlib does quite a bit of caching, layering, and similar optimization.

Threaded applications: While Xlib does attempt to support multithreading, the API makes this difficult and error-prone.

New extensions: The Xlib provides limited support for the new creation of X extension client side code.

XCB has been designed to solve the above problems and thus provide a base for:

• Toolkit implementation.
• Direct protocol-level programming.
• Lightweight emulation of commonly used portions of the Xlib API

The client and server model of the X window system

The design goal of the X window system is flexibility. The way things look is one thing, but the way things work is another matter. The X window system is separated into two parts, clients and a server.

The server controls the screens, mouse and keyboard. The server actually draws on the screen and reads user input in order to send it to the client for processing.Several clients may connect to a single X server. When input is sent by the user to some window, the server sends a message to the client. The client decides what to do with this input, and sends the server requests for drawing in the window.

The whole session between client and server is carried out using the X message protocol. This protocol is carried over the TCP/IP protocol, the shared memory or Unixdomain sockets. X protocol message may be several hundreds of KB in size.

GUI programming: the asynchronous model

A GUI program usually uses an asynchronous programming model, also known as "event-driven programming". This means that client program mostly sits idle, waiting for events sent by the X server, and then acts upon these events. In order for the client program to be responsive to the user input, it needs to handle each event in a rather short period of time. Less that 200 ms, as a rule of thumb.

The client program may not perform operations that might take a long time while handling an event. Such as, opening a network connection, or connecting to a database, or even performing a large file copy operation. This may be done by performing them in a different process or thread.

So the way a client GUI program looks is something like that:

1. Perform initialization routines.
2. Connect to the X server.
3. Perform X-related initialization.
4. while not finished:
   1. Receive the next event from the X server.
   2. Handle the event, possibly sending various drawing requests to the X server.
   3. If the event was a quit message, exit the loop.
5. Close down the connection to the X server.
6. Perform cleanup operations.

Basic XCB notions

XCB library gives a client program a very low-level access to any X server.

1. The X Connection

The struct "xcb_connection_t" hides:

• a queue of message coming from the server.
• a queue of pending requests that client intends to send to the server.

when we open connection to an X server, a pointer to the struct "xcb_connection_t" is returned. Later we supply this pointer to other XCB function that should send requests to the X server or receive messages from this server.

2. Requests and replies: the Xlib killers

To ask for information from the X server, we have to make a request and ask for a reply. When the client send a request, XCB library returns a cookied, which is an identifier. Then, later, we ask for a reply using this cookies and XCB returns a pointer to that reply. Hence, the client can send a lot of requests, and later, ask for all the replies when we need them.

3. The Graphics Context

The client program set the various drawing options in a graphical context structure, and then pass a pointer to this structure to any drawing routined.  When we often need to perform several drawing requests with the same options, we should initialize a graphical context, set the desired options, and pass it to all drawing functions.

Note: graphic contexts have no client-side structure in XCB, they are XIDs.

4. Events

A structure is used to pass events received from the X server.This structure contains event type and the data associated with the event. The way to read the event's data depends on the event type.

• position on the screen where the event was generated
• mouse button associated with the event
• region of the screen associated with a "redraw"

5. Screen

Once the client has connected to an X server, some basic information about screen should be checked by the structure "xcb_screen_t". 

• the size of the screen, width_in_pixels/millimeters and height_in_pixels/millimeters