git.demorecorder.com Git - free-sw/xcb/libxcb/blob - doc/tutorial/index.html

   1 <!DOCTYPE html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5
   6 <head>
   7   <title>Basic Graphics Programming With The XCB Library</title>
   8   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
   9   <link href="xcb.css" rel="stylesheet" type="text/css">
  10 </head>
  11
  12 <body>
  13   <div class="title">
  14     Basic Graphics Programming With The XCB Library
  15   </div>
  16   <div class="toc">
  17   <ol>
  18     <li><a class="section" href="#intro">Introduction</a>
  19     <li><a class="section" href="#Xmodel">The client and server model of the X window system</a>
  20     <li><a class="section" href="#asynch">GUI programming: the asynchronous model</a>
  21     <li><a class="section" href="#notions">Basic XCB notions</a>
  22       <ol>
  23         <li><a class="subsection" href="#conn">The X Connection</a>
  24         <li><a class="subsection" href="#requestsreplies">Requests and replies: the Xlib killers</a>
  25         <li><a class="subsection" href="#gc">The Graphics Context</a>
  26         <li>Object handles
  27         <li>Memory allocation for XCB structures
  28         <li><a class="subsection" href="#events">Events</a>
  29       </ol>
  30     <li><a class="section" href="#use">Using XCB-based programs</a>
  31       <ol>
  32         <li><a class="subsection" href="#inst">Installation of XCB</a>
  33         <li><a class="subsection" href="#comp">Compiling XCB-based programs</a>
  34       </ol>
  35     <li><a class="section" href="#openconn">Opening and closing the connection to an X server</a>
  36     <li><a class="section" href="#screen">Checking basic information about a connection</a>
  37     <li><a class="section" href="#helloworld">Creating a basic window - the "hello world" program</a>
  38     <li><a class="section" href="#drawing">Drawing in a window</a>
  39       <ol>
  40         <li><a class="subsection" href="#allocgc">Allocating a Graphics Context</a>
  41         <li><a class="subsection" href="#changegc">Changing the attributes of a Graphics Context</a>
  42         <li><a class="subsection" href="#drawingprim">Drawing primitives: point, line, box, circle,...</a>
  43       </ol>
  44     <li><a class="section" href="#xevents">X Events</a>
  45       <ol>
  46         <li><a class="subsection" href="#register">Registering for event types using event masks</a>
  47         <li><a class="subsection" href="#loop">Receiving events: writing the events loop</a>
  48         <li><a class="subsection" href="#expose">Expose events</a>
  49         <li><a class="subsection" href="#userinput">Getting user input</a>
  50           <ol>
  51             <li><a class="subsubsection" href="#mousepressrelease">Mouse button press and release events</a>
  52             <li><a class="subsubsection" href="#mousemvnt">Mouse movement events</a>
  53             <li><a class="subsubsection" href="#mouseenter">Mouse pointer enter and leave events</a>
  54             <li><a class="subsubsection" href="#focus">The keyboard focus</a>
  55             <li><a class="subsubsection" href="#keypress">Keyboard press and release events</a>
  56           </ol>
  57         <li><a class="subsection" href="#eventex">X events: a complete example</a>
  58       </ol>
  59     <li><a class="section" href="#font">Handling text and fonts</a>
  60       <ol>
  61         <li><a class="subsection" href="#fontstruct">The Font structure</a>
  62         <li>Loading a Font
  63         <li>Assigning a Font to a Graphic Context
  64         <li>Drawing text in a window
  65       </ol>
  66     <li>Windows hierarchy
  67       <ol>
  68         <li>Root, parent and child windows
  69         <li>Events propagation
  70       </ol>
  71     <li><a class="section" href="#wm">Interacting with the window manager</a>
  72       <ol>
  73         <li><a class="subsection" href="#wmprop">Window properties</a>
  74         <li><a class="subsection" href="#wmname">Setting the window name and icon name</a>
  75         <li>Setting preferred window size(s)
  76         <li>Setting miscellaneous window manager hints
  77         <li>Setting an application's icon
  78         <li>Obeying the delete-window protocol
  79       </ol>
  80     <li><a class="section" href="#winop">Simple window operations</a>
  81       <ol>
  82         <li><a class="subsection" href="#winmap">Mapping and unmapping a window</a>
  83         <li><a class="subsection" href="#winconf">Configuring a window</a>
  84         <li><a class="subsection" href="#winmove">Moving a window around the screen</a>
  85         <li><a class="subsection" href="#winsize">Resizing a window</a>
  86         <li><a class="subsection" href="#winstack">Changing windows stacking order: raise and lower</a>
  87         <li>Iconifying and de-iconifying a window
  88         <li><a class="subsection" href="#wingetinfo">Getting informations about a window</a>
  89       </ol>
  90     <li><a class="section" href="#usecolor">Using colors to paint the rainbow</a>
  91       <ol>
  92         <li><a class="subsection" href="#colormap">Color maps</a>
  93         <li><a class="subsection" href="#colormapalloc">Allocating and freeing Color Maps</a>
  94         <li><a class="subsection" href="#alloccolor">Allocating and freeing a color entry</a>
  95         <li>Drawing with a color
  96       </ol>
  97     <li><a class="section" href="#pixmaps">X Bitmaps and Pixmaps</a>
  98       <ol>
  99         <li><a class="subsection" href="#pixmapswhat">What is a X Bitmap ? An X Pixmap ?</a>
 100         <li>Loading a bitmap from a file
 101         <li>Drawing a bitmap in a window
 102         <li><a class="subsection" href="#pixmapscreate">Creating a pixmap</a>
 103         <li><a class="subsection" href="#pixmapsdraw">Drawing a pixmap in a window</a>
 104         <li><a class="subsection" href="#pixmapsfree">Freeing a pixmap</a>
 105       </ol>
 106     <li><a class="subsection" href="#mousecursor">Messing with the mouse cursor</a>
 107       <ol>
 108         <li><a class="subsection" href="#mousecursorcreate">Creating and destroying a mouse cursor</a>
 109         <li><a class="subsection" href="#mousecursorset">Setting a window's mouse cursor</a>
 110         <li><a class="subsection" href="#mousecursorexample">Complete example</a>
 111       </ol>
 112     <li><a class="subsection" href="#translation">Translation of basic Xlib functions and macros</a>
 113       <ol>
 114         <li><a class="subsection" href="#displaystructure">Members of the Display structure</a>
 115           <ol>
 116             <li><a class="subsection" href="#ConnectionNumber">ConnectionNumber</a>
 117             <li><a class="subsection" href="#DefaultScreen">DefaultScreen</a>
 118             <li><a class="subsection" href="#QLength">QLength</a>
 119             <li><a class="subsection" href="#ScreenCount">ScreenCount</a>
 120             <li><a class="subsection" href="#ServerVendor">ServerVendor</a>
 121             <li><a class="subsection" href="#ProtocolVersion">ProtocolVersion</a>
 122             <li><a class="subsection" href="#ProtocolRevision">ProtocolRevision</a>
 123             <li><a class="subsection" href="#VendorRelease">VendorRelease</a>
 124             <li><a class="subsection" href="#DisplayString">DisplayString</a>
 125             <li><a class="subsection" href="#BitmapUnit">BitmapUnit</a>
 126             <li><a class="subsection" href="#BitmapBitOrder">BitmapBitOrder</a>
 127             <li><a class="subsection" href="#BitmapPad">BitmapPad</a>
 128             <li><a class="subsection" href="#ImageByteOrder">ImageByteOrder</a>
 129           </ol>
 130         <li><a class="subsection" href="#screenofdisplay">ScreenOfDisplay related functions</a>
 131           <ol>
 132             <li><a class="subsection" href="#ScreenOfDisplay">ScreenOfDisplay</a>
 133             <li><a class="subsection" href="#DefaultScreenOfDisplay">DefaultScreenOfDisplay</a>
 134             <li><a class="subsection" href="#RootWindow">RootWindow / RootWindowOfScreen</a>
 135             <li><a class="subsection" href="#DefaultRootWindow">DefaultRootWindow</a>
 136             <li><a class="subsection" href="#DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
 137             <li><a class="subsection" href="#DefaultGC">DefaultGC / DefaultGCOfScreen</a>
 138             <li><a class="subsection" href="#BlackPixel">BlackPixel / BlackPixelOfScreen</a>
 139             <li><a class="subsection" href="#WhitePixel">WhitePixel / WhitePixelOfScreen</a>
 140             <li><a class="subsection" href="#DisplayWidth">DisplayWidth / WidthOfScreen</a>
 141             <li><a class="subsection" href="#DisplayHeight">DisplayHeight / HeightOfScreen</a>
 142             <li><a class="subsection" href="#DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
 143             <li><a class="subsection" href="#DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
 144             <li><a class="subsection" href="#DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
 145             <li><a class="subsection" href="#DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
 146             <li><a class="subsection" href="#MinCmapsOfScreen">MinCmapsOfScreen</a>
 147             <li><a class="subsection" href="#MaxCmapsOfScreen">MaxCmapsOfScreen</a>
 148             <li><a class="subsection" href="#DoesSaveUnders">DoesSaveUnders</a>
 149             <li><a class="subsection" href="#DoesBackingStore">DoesBackingStore</a>
 150             <li><a class="subsection" href="#EventMaskOfScreen">EventMaskOfScreen</a>
 151           </ol>
 152         <li><a class="subsection" href="#misc">Miscellaneaous macros</a>
 153           <ol>
 154             <li><a class="subsection" href="#DisplayOfScreen">DisplayOfScreen</a>
 155             <li><a class="subsection" href="#DisplayCells">DisplayCells / CellsOfScreen</a>
 156           </ol>
 157       </ol>
 158   </ol>
 159   </div>
 160   <div class="section">
 161     <ol>
 162       <li class="title"><a name="intro">Introduction</a>
 163       <p>
 164       This tutorial is based on the
 165       <a href="http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html">Xlib Tutorial</a>
 166       written by <a href="mailto:choor at atcom dot co dot il">Guy Keren</a>. The
 167       author allowed me to take some parts of his text, mainly the text which
 168       deals with the X Windows generality.
 169       </p>
 170       <p>
 171       This tutorial is intended for people who want to start to program
 172       with the <a href="http://xcb.freedesktop.org">XCB</a>
 173       library. keep in mind that XCB, like the
 174       <a href="http://tronche.com/gui/x/xlib/introduction">Xlib</a>
 175       library, isn't what post programmers wanting to write X
 176       applications are looking for. They should use a much higher
 177       level GUI toolkit like Motif,
 178       <a href="http://www.lesstif.org">LessTiff</a>,
 179       <a href="http://www.gtk.org">GTK</a>,
 180       <a href="http://www.trolltech.com">QT</a> or
 181       <a href="http://www.enlightenment.org">EWL</a>, or use
 182       <a href="http://cairographics.org">Cairo</a>.
 183       However,
 184       we need to start somewhere. More than this, knowing how things
 185       work down below is never a bad idea.
 186       </p>
 187       <p>
 188       After reading this tutorial, one should be able to write very
 189       simple graphical programs, but not programs with decent user
 190       interfaces. For such programs, one of the previously mentioned
 191       libraries should be used.
 192       </p>
 193       <p>
 194       But what is XCB? Xlib has been
 195       the standard C binding for the <a href="http://www.x.org">X
 196       Window System</a> protocol for many years now. It is an
 197       excellent piece of work, but there are applications for which it
 198       is not ideal, for example:
 199       </p>
 200       <ul>
 201         <li><b>Small platforms</b>: Xlib is a large piece of code, and
 202         it's difficult to make it smaller
 203         <li><b>Latency hiding</b>: Xlib requests requiring a reply are
 204         effectively synchronous: they block until the reply appears,
 205         whether the result is needed immediately or not.
 206         <li><b>Direct access to the protocol</b>: Xlib does quite a
 207         bit of caching, layering, and similar optimizations. While this
 208         is normally a feature, it makes it difficult to simply emit
 209         specified X protocol requests and process specific
 210         responses.
 211         <li><b>Threaded applications</b>: While Xlib does attempt to
 212         support multithreading, the API makes this difficult and
 213         error-prone.
 214         <li><b>New extensions</b>: The Xlib infrastructure provides
 215         limited support for the new creation of X extension client side
 216         code.
 217       </ul>
 218       <p>
 219       For these reasons, among others, XCB, an X C binding, has been
 220       designed to solve the above problems and thus provide a base for
 221       </p>
 222       <ul>
 223         <li>Toolkit implementation.
 224         <li>Direct protocol-level programming.
 225         <li>Lightweight emulation of commonly used portions of the
 226         Xlib API.
 227       </ul>
 228       <br>
 229       <li class="title"><a name="Xmodel">The client and server model of the X window system</a>
 230       <p>
 231       The X Window System was developed with one major goal:
 232       flexibility. The idea was that the way things look is one thing,
 233       but the way things work is another matter. Thus, the lower
 234       levels provide the tools required to draw windows, handle user
 235       input, allow drawing graphics using colors (or black and white
 236       screens), etc. To this point, a decision was made to separate
 237       the system into two parts. A client that decides what to do, and
 238       a server that actually draws on the screen and reads user input
 239       in order to send it to the client for processing.
 240       </p>
 241       <p>
 242       This model is the complete opposite of what is used to when
 243       dealing with clients and servers. In our case, the user sits
 244       near the machine controlled by the server, while the client
 245       might be running on a remote machine. The server controls the
 246       screens, mouse and keyboard. A client may connect to the server,
 247       request that it draws a window (or several windows), and ask the
 248       server to send it any input the user sends to these
 249       windows. Thus, several clients may connect to a single X server
 250       (one might be running mail software, one running a WWW
 251       browser, etc). When input is sent by the user to some window,
 252       the server sends a message to the client controlling this window
 253       for processing. The client decides what to do with this input,
 254       and sends the server requests for drawing in the window.
 255       </p>
 256       <p>
 257       The whole session is carried out using the X message
 258       protocol. This protocol was originally carried over the TCP/IP
 259       protocol suite, allowing the client to run on any machine
 260       connected to the same network that the server is. Later on, the
 261       X servers were extended to allow clients running on the local
 262       machine with more optimized access to the server (note that an X
 263       protocol message may be several hundreds of KB in size), such as
 264       using shared memory, or using Unix domain sockets (a method for
 265       creating a logical channel on a Unix system between two processes).
 266       </p>
 267       <li class="title"><a name="asynch">GUI programming: the asynchronous model</a>
 268       <p>
 269       Unlike conventional computer programs, that carry some serial
 270       nature, a GUI program usually uses an asynchronous programming
 271       model, also known as "event-driven programming". This means that
 272       that program mostly sits idle, waiting for events sent by the X
 273       server, and then acts upon these events. An event may say "The
 274       user pressed the 1st button mouse in spot (x,y)", or "The window
 275       you control needs to be redrawn". In order for the program to be
 276       responsive to the user input, as well as to refresh requests, it
 277       needs to handle each event in a rather short period of time
 278       (e.g. less that 200 milliseconds, as a rule of thumb).
 279       </p>
 280       <p>
 281       This also implies that the program may not perform operations
 282       that might take a long time while handling an event (such as
 283       opening a network connection to some remote server, or
 284       connecting to a database server, or even performing a long file
 285       copy operation). Instead, it needs to perform all these
 286       operations in an asynchronous manner. This may be done by using
 287       various asynchronous models to perform the longish operations,
 288       or by performing them in a different process or thread.
 289       </p>
 290       <p>
 291       So the way a GUI program looks is something like that:
 292       </p>
 293       <ol>
 294         <li>Perform initialization routines.
 295         <li>Connect to the X server.
 296         <li>Perform X-related initialization.
 297         <li>While not finished:
 298           <ol>
 299             <li>Receive the next event from the X server.
 300             <li>Handle the event, possibly sending various drawing
 301             requests to the X server.
 302             <li>If the event was a quit message, exit the loop.
 303           </ol>
 304         <li>Close down the connection to the X server.
 305         <li>Perform cleanup operations.
 306       </ol>
 307       <br>
 308       <li class="title"><a name="notions">Basic XCB notions</a>
 309       <p>
 310       XCB has been created to eliminate the need for
 311       programs to actually implement the X protocol layer. This
 312       library gives a program a very low-level access to any X
 313       server. Since the protocol is standardized, a client using any
 314       implementation of XCB may talk with any X server (the same
 315       occurs for Xlib, of course). We now give a brief description of
 316       the basic XCB notions. They will be detailed later.
 317       </p>
 318       <ol>
 319         <li class="subtitle"><a name="conn">The X Connection</a>
 320         <p>
 321         The major notion of using XCB is the X Connection. This is a
 322         structure representing the connection we have open with a
 323         given X server. It hides a queue of messages coming from the
 324         server, and a queue of pending requests that our client
 325         intends to send to the server. In XCB, this structure is named
 326         'xcb_connection_t'. It is analogous to the Xlib Display.
 327         When we open a connection to an X server, the
 328         library returns a pointer to such a structure. Later, we
 329         supply this pointer to any XCB function that should send
 330         messages to the X server or receive messages from this server.
 331         </p>
 332         <li class="subtitle"><a name="requestsreplies">Requests and
 333         replies: the Xlib killers</a>
 334         <p>
 335         To ask for information from the X server, we have to make a request
 336         and ask for a reply. With Xlib, these two tasks are
 337         automatically done: Xlib locks the system, sends a request,
 338         waits for a reply from the X server and unlocks. This is
 339         annoying, especially if one makes a lot of requests to the X
 340         server. Indeed, Xlib has to wait for the end of a reply
 341         before asking for the next request (because of the locks that
 342         Xlib sends). For example, here is a time-line of N=4
 343         requests/replies with Xlib, with a round-trip latency
 344         <b>T_round_trip</b> that is 5 times long as the time required
 345         to write or read a request/reply (<b>T_write/T_read</b>):
 346         </p>
 347         <pre class="text">
 348   W-----RW-----RW-----RW-----R
 349 </pre>
 350         <ul>
 351           <li>W: Writing request
 352           <li>-: Stalled, waiting for data
 353           <li>R: Reading reply
 354         </ul>
 355         <p>
 356         The total time is N * (T_write + T_round_trip + T_read).
 357         </p>
 358         <p>
 359         With XCB, we can suppress most of the round-trips as the
 360         requests and the replies are not locked. We usually send a
 361         request, then XCB returns to us a <b>cookie</b>, which is an
 362         identifier. Then, later, we ask for a reply using this
 363         <b>cookie</b> and XCB returns a
 364         pointer to that reply. Hence, with XCB, we can send a lot of
 365         requests, and later in the program, ask for all the replies
 366         when we need them. Here is the time-line for 4
 367         requests/replies when we use this property of XCB:
 368         </p>
 369         <pre class="text">
 370   WWWW--RRRR
 371 </pre>
 372         <p>
 373         The total time is N * T_write + max (0, T_round_trip - (N-1) *
 374         T_write) + N * T_read. Which can be considerably faster than
 375         all those Xlib round-trips.
 376         </p>
 377         <p>
 378         Here is a program that computes the time to create 500 atoms
 379         with Xlib and XCB. It shows the Xlib way, the bad XCB way
 380         (which is similar to Xlib) and the good XCB way. On my
 381         computer, XCB is 25 times faster than Xlib.
 382         </p>
 383       <pre class="code">
 384 #include &lt;stdlib.h&gt;
 385 #include &lt;stdio.h&gt;
 386 #include &lt;string.h&gt;
 387 #include &lt;sys/time.h&gt;
 388
 389 #include &lt;xcb/xcb.h&gt;
 390
 391 #include &lt;X11/Xlib.h&gt;
 392
 393 double
 394 get_time(void)
 395 {
 396   struct timeval timev;
 397
 398   gettimeofday(&amp;timev, NULL);
 399
 400   return (double)timev.tv_sec + (((double)timev.tv_usec) / 1000000);
 401 }
 402
 403 int
 404 main ()
 405 {
 406   xcb_connection_t         *c;
 407   xcb_atom_t               *atoms;
 408   xcb_intern_atom_cookie_t *cs;
 409   char                    **names;
 410   int                       count;
 411   int                       i;
 412   double                    start;
 413   double                    end;
 414   double                    diff;
 415
 416   /* Xlib */
 417   Display *disp;
 418   Atom    *atoms_x;
 419   double   diff_x;
 420
 421   c = xcb_connect (NULL, NULL);
 422
 423   count = 500;
 424   atoms = (xcb_atom_t *)malloc (count * sizeof (atoms));
 425   names = (char **)malloc (count * sizeof (char *));
 426
 427   /* init names */
 428   for (i = 0; i &lt; count; ++i) {
 429     char buf[100];
 430
 431     sprintf (buf, "NAME%d", i);
 432     names[i] = strdup (buf);
 433   }
 434
 435   /* bad use */
 436   start = get_time ();
 437
 438   for (i = 0; i &lt; count; ++i)
 439     atoms[i] = xcb_intern_atom_reply (c,
 440                                       xcb_intern_atom (c,
 441                                                        0,
 442                                                        strlen(names[i]),
 443                                                        names[i]),
 444                                       NULL)->atom;
 445
 446   end = get_time ();
 447   diff = end - start;
 448   printf ("bad use time  : %f\n", diff);
 449
 450   /* good use */
 451   start = get_time ();
 452
 453   cs = (xcb_intern_atom_cookie_t *) malloc (count * sizeof(xcb_intern_atom_cookie_t));
 454   for(i = 0; i &lt; count; ++i)
 455     cs[i] = xcb_intern_atom (c, 0, strlen(names[i]), names[i]);
 456
 457   for(i = 0; i &lt; count; ++i) {
 458     xcb_intern_atom_reply_t *r;
 459
 460     r = xcb_intern_atom_reply(c, cs[i], 0);
 461     if(r)
 462       atoms[i] = r->atom;
 463     free(r);
 464   }
 465
 466   end = get_time ();
 467   printf ("good use time : %f\n", end - start);
 468   printf ("ratio         : %f\n", diff / (end - start));
 469   diff = end - start;
 470
 471   /* free var */
 472   for (i = 0; i &lt; count; ++i)
 473     free (names[i]);
 474   free (atoms);
 475   free (cs);
 476
 477   xcb_disconnect (c);
 478
 479   /* Xlib */
 480   disp = XOpenDisplay (getenv("DISPLAY"));
 481
 482   atoms_x = (Atom *)malloc (count * sizeof (atoms_x));
 483
 484   start = get_time ();
 485
 486   for (i = 0; i &lt; count; ++i)
 487     atoms_x[i] = XInternAtom(disp, names[i], 0);
 488
 489   end = get_time ();
 490   diff_x = end - start;
 491   printf ("Xlib use time : %f\n", diff_x);
 492   printf ("ratio         : %f\n", diff_x / diff);
 493
 494   free (atoms_x);
 495   free (names);
 496
 497   XCloseDisplay (disp);
 498
 499   return 0;
 500 }
 501 </pre>
 502         <li class="subtitle"><a name="gc">The Graphic Context</a>
 503         <p>
 504         When we perform various drawing operations (graphics, text,
 505         etc), we may specify various options for controlling how the
 506         data will be drawn (what foreground and background colors to
 507         use, how line edges will be connected, what font to use when
 508         drawing some text, etc). In order to avoid the need to supply
 509         hundreds of parameters to each drawing function, a graphical
 510         context structure is used. We set the various drawing options
 511         in this structure, and then we pass a pointer to this
 512         structure to any drawing routines. This is rather handy, as we
 513         often need to perform several drawing requests with the same
 514         options. Thus, we would initialize a graphical context, set
 515         the desired options, and pass this structure to all drawing
 516         functions.
 517         </p>
 518         <p>
 519         Note that graphic contexts have no client-side structure in
 520         XCB, they're just XIDs. Xlib has a client-side structure
 521         because it caches the GC contents so it can avoid making
 522         redundant requests, but of course XCB doesn't do that.
 523         </p>
 524         <li class="subtitle"><a name="events">Events</a>
 525         <p>
 526         A structure is used to pass events received from the X
 527         server. XCB supports exactly the events specified in the
 528         protocol (33 events). This structure contains the type
 529         of event received (including a bit for whether it came
 530         from the server or another client), as well as the data associated with the
 531         event (e.g. position on the screen where the event was
 532         generated, mouse button associated with the event, region of
 533         the screen associated with a "redraw" event, etc). The way to
 534         read the event's data depends on the event type.
 535         </p>
 536       </ol>
 537       <br>
 538       <li class="title"><a name="use">Using XCB-based programs</a>
 539       <br>
 540       <ol>
 541         <li class="subtitle"><a name="inst">Installation of XCB</a>
 542         <p>
 543         <b>TODO:</b> These instructions are out of date.
 544         Just reference the <a href="http://xcb.freedesktop.org/">main XCB page</a>
 545         so we don't have to maintain these instructions in more than
 546         one place.
 547         </p>
 548         <p>
 549         To build XCB from source, you need to have installed at
 550         least:
 551         </p>
 552         <ul>
 553           <li>pkgconfig 0.15.0
 554           <li><a href="http://www.gnu.org/software/automake/">automake 1.7</a>
 555           <li><a href="http://www.gnu.org/software/autoconf/">autoconf 2.50</a>
 556           <li><a href="http://www.check.org">check</a>
 557           <li><a href="http://xmlsoft.org/XSLT/">xsltproc</a>
 558           <li><a href="http://www.gnu.org/software/gperf/">gperf 3.0.1</a>
 559         </ul>
 560         <p>
 561         You have to checkout in the git repository the following modules:
 562         </p>
 563         <ul>
 564           <li>Xau from xlibs
 565           <li>xcb-proto
 566           <li>xcb
 567         </ul>
 568         <p>
 569         Note that xcb-proto exists only to install header
 570         files, so typing 'make' or 'make all' will produce the message
 571         "Nothing to be done for 'all'". That's normal.
 572         </p>
 573         <li class="subtitle"><a name="comp">Compiling XCB-based programs</a>
 574         <p>
 575         Compiling XCB-based programs requires linking them with the XCB
 576         library. This is easily done thanks to pkgconfig:
 577         </p>
 578         <pre class="text">
 579 gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb`
 580 </pre>
 581       </ol>
 582       <li class="title"><a name="openconn">Opening and closing the connection to an X server</a>
 583       <p>
 584       An X program first needs to open the connection to the X
 585       server. There is a function that opens a connection. It requires
 586       the display name, or NULL. In the latter case, the display name
 587       will be the one in the environment variable DISPLAY.
 588       </p>
 589       <pre class="code">
 590 <span class="type">xcb_connection_t</span> *xcb_connect (<span class="keyword">const</span> <span class="type">char</span> *displayname,
 591                                <span class="type">int</span>        *screenp);
 592 </pre>
 593       <p>
 594       The second parameter returns the screen number used for the
 595       connection. The returned structure describes an XCB connection
 596       and is opaque. Here is how the connection can be opened:
 597       </p>
 598       <pre class="code">
 599 #<span class="include">include</span> <span class="string">&lt;xcb/xcb.h&gt;</span>
 600
 601 <span class="type">int</span>
 602 <span class="function">main</span> ()
 603 {
 604   <span class="type">xcb_connection_t</span> *c;
 605
 606   /* Open the connection to the X server. Use the DISPLAY environment variable as the default display name */
 607   c = xcb_connect (NULL, NULL);
 608
 609   <span class="keyword">return</span> 0;
 610 }
 611 </pre>
 612       <p>
 613       To close a connection, it suffices to use:
 614       </p>
 615       <pre class="code">
 616 <span class="type">void</span> xcb_disconnect (<span class="type">xcb_connection_t</span> *c);
 617 </pre>
 618       <div class="comp">
 619         <div class="title">
 620         Comparison Xlib/XCB
 621         </div>
 622         <div class="xlib">
 623         <ul>
 624           <li>XOpenDisplay ()
 625         </ul>
 626         </div>
 627         <div class="xcb">
 628         <ul>
 629           <li>xcb_connect ()
 630         </ul>
 631         </div>
 632         <div class="xlib">
 633         <ul>
 634           <li>XCloseDisplay ()
 635         </ul>
 636         </div>
 637         <div class="xcb">
 638         <ul>
 639           <li>xcb_disconnect ()
 640         </ul>
 641         </div>
 642       </div>
 643       <br>
 644       <li class="title"><a name="screen">Checking basic information about a connection</a>
 645       <p>
 646       Once we have opened a connection to an X server, we should check some
 647       basic information about it: what screens it has, what is the
 648       size (width and height) of the screen, how many colors it
 649       supports (black and white ? grey scale ?, 256 colors ? more ?),
 650       and so on. We get such information from the xcb_screen_t
 651       structure:
 652       </p>
 653       <pre class="code">
 654 typedef struct {
 655     xcb_window_t   root;
 656     xcb_colormap_t default_colormap;
 657     uint32_t       white_pixel;
 658     uint32_t       black_pixel;
 659     uint32_t       current_input_masks;
 660     uint16_t       width_in_pixels;
 661     uint16_t       height_in_pixels;
 662     uint16_t       width_in_millimeters;
 663     uint16_t       height_in_millimeters;
 664     uint16_t       min_installed_maps;
 665     uint16_t       max_installed_maps;
 666     xcb_visualid_t root_visual;
 667     uint8_t        backing_stores;
 668     uint8_t        save_unders;
 669     uint8_t        root_depth;
 670     uint8_t        allowed_depths_len;
 671 } xcb_screen_t;
 672 </pre>
 673       <p>
 674       We could retrieve the first screen of the connection by using the
 675       following function:
 676       </p>
 677       <pre class="code">
 678 xcb_screen_iterator_t xcb_setup_roots_iterator (xcb_setup_t *R);
 679 </pre>
 680       <p>
 681       Here is a small program that shows how to use this function:
 682       </p>
 683       <pre class="code">
 684 #include &lt;stdio.h&gt;
 685
 686 #include &lt;xcb/xcb.h&gt;
 687
 688 int
 689 main ()
 690 {
 691   xcb_connection_t     *c;
 692   xcb_screen_t         *screen;
 693   int                   screen_nbr;
 694   xcb_screen_iterator_t iter;
 695
 696   /* Open the connection to the X server. Use the DISPLAY environment variable */
 697   c = xcb_connect (NULL, &amp;screen_nbr);
 698
 699   /* Get the screen #screen_nbr */
 700   iter = xcb_setup_roots_iterator (xcb_get_setup (c));
 701   for (; iter.rem; --screen_nbr, xcb_screen_next (&amp;iter))
 702     if (screen_nbr == 0) {
 703       screen = iter.data;
 704       break;
 705     }
 706
 707   printf ("\n");
 708   printf ("Informations of screen %ld:\n", screen-&gt;root);
 709   printf ("  width.........: %d\n", screen-&gt;width_in_pixels);
 710   printf ("  height........: %d\n", screen-&gt;height_in_pixels);
 711   printf ("  white pixel...: %ld\n", screen-&gt;white_pixel);
 712   printf ("  black pixel...: %ld\n", screen-&gt;black_pixel);
 713   printf ("\n");
 714
 715   return 0;
 716 }
 717 </pre>
 718       <li class="title"><a name="helloworld">Creating a basic window - the "hello world" program</a>
 719       <p>
 720       After we got some basic information about our screen, we can
 721       create our first window. In the X Window System, a window is
 722       characterized by an Id. So, in XCB, a window is of type:
 723       </p>
 724       <pre class="code">
 725 typedef uint32_t xcb_window_t;
 726 </pre>
 727       <p>
 728       We first ask for a new Id for our window, with this function:
 729       </p>
 730       <pre class="code">
 731 xcb_window_t xcb_generate_id(xcb_connection_t *c);
 732 </pre>
 733       <p>
 734       Then, XCB supplies the following function to create new windows:
 735       </p>
 736       <pre class="code">
 737 xcb_void_cookie_t xcb_create_window (xcb_connection_t *c,             /* Pointer to the xcb_connection_t structure */
 738                                      uint8_t           depth,         /* Depth of the screen */
 739                                      xcb_window_t      wid,           /* Id of the window */
 740                                      xcb_window_t      parent,        /* Id of an existing window that should be the parent of the new window */
 741                                      int16_t           x,             /* X position of the top-left corner of the window (in pixels) */
 742                                      int16_t           y,             /* Y position of the top-left corner of the window (in pixels) */
 743                                      uint16_t          width,         /* Width of the window (in pixels) */
 744                                      uint16_t          height,        /* Height of the window (in pixels) */
 745                                      uint16_t          border_width,  /* Width of the window's border (in pixels) */
 746                                      uint16_t          _class,
 747                                      xcb_visualid_t    visual,
 748                                      uint32_t          value_mask,
 749                                      const uint32_t   *value_list);
 750 </pre>
 751       <p>
 752       The fact that we created the window does not mean that it will
 753       be drawn on screen. By default, newly created windows are not
 754       mapped on the screen (they are invisible). In order to make our
 755       window visible, we use the function <span class="code">xcb_map_window()</span>, whose
 756       prototype is
 757       </p>
 758       <pre class="code">
 759 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
 760                                   xcb_window_t      window);
 761 </pre>
 762       <p>
 763       Finally, here is a small program to create a window of size
 764       150x150 pixels, positioned at the top-left corner of the screen:
 765       </p>
 766       <pre class="code">
 767 #include &lt;unistd.h&gt;      /* pause() */
 768
 769 #include &lt;xcb/xcb.h&gt;
 770
 771 int
 772 main ()
 773 {
 774   xcb_connection_t *c;
 775   xcb_screen_t     *screen;
 776   xcb_window_t      win;
 777
 778   /* Open the connection to the X server */
 779   c = xcb_connect (NULL, NULL);
 780
 781   /* Get the first screen */
 782   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
 783
 784   /* Ask for our window's Id */
 785   win = xcb_generate_id(c);
 786
 787   /* Create the window */
 788   xcb_create_window (c,                             /* Connection          */
 789                      XCB_COPY_FROM_PARENT,          /* depth (same as root)*/
 790                      win,                           /* window Id           */
 791                      screen-&gt;root,                  /* parent window       */
 792                      0, 0,                          /* x, y                */
 793                      150, 150,                      /* width, height       */
 794                      10,                            /* border_width        */
 795                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
 796                      screen-&gt;root_visual,           /* visual              */
 797                      0, NULL);                      /* masks, not used yet */
 798
 799   /* Map the window on the screen */
 800   xcb_map_window (c, win);
 801
 802   /* Make sure commands are sent before we pause, so window is shown */
 803   xcb_flush (c);
 804
 805   pause ();    /* hold client until Ctrl-C */
 806
 807   return 0;
 808 }
 809 </pre>
 810       <p>
 811       In this code, you see one more function - <span class="code">xcb_flush()</span>, not explained
 812       yet. It is used to flush all the pending requests. More
 813       precisely, there are 2 functions that do such things. The first
 814       one is <span class="code">xcb_flush()</span>:
 815       </p>
 816       <pre class="code">
 817 int xcb_flush (xcb_connection_t *c);
 818 </pre>
 819       <p>
 820       This function flushes all pending requests to the X server (much
 821       like the <span class="code">fflush()</span> function is used to
 822       flush standard output). The second function is
 823       <span class="code">xcb_aux_sync()</span>:
 824       </p>
 825       <pre class="code">
 826 int xcb_aux_sync (xcb_connection_t *c);
 827 </pre>
 828       <p>
 829       This functions also flushes all pending requests to the X
 830       server, and then waits until the X server finishing processing
 831       these requests. In a normal program, this will not be necessary
 832       (we'll see why when we get to write a normal X program), but for
 833       now, we put it there.
 834       </p>
 835       <p>
 836       The window that is created by the above code has a non defined
 837       background. This one can be set to a specific color,
 838       thanks to the two last parameters of
 839       <span class="code">xcb_create_window()</span>, which are not
 840       described yet. See the subsections
 841       <a href="#winconf">Configuring a window</a> or
 842       <a href="#winconf">Registering for event types using event masks</a>
 843       for examples on how to use these parameters. In addition, as no
 844       events are handled, you have to make a Ctrl-C to interrupt the
 845       program.
 846       </p>
 847       <p>
 848       <b>TODO</b>: one should tell what these functions return and
 849       about the generic error
 850       </p>
 851       <div class="comp">
 852         <div class="title">
 853         Comparison Xlib/XCB
 854         </div>
 855         <div class="xlib">
 856         <ul>
 857           <li>XCreateWindow ()
 858         </ul>
 859         </div>
 860         <div class="xcb">
 861         <ul>
 862           <li>xcb_generate_id ()
 863           <li>xcb_create_window ()
 864         </ul>
 865         </div>
 866       </div>
 867       <br>
 868       <li class="title"><a name="drawing">Drawing in a window</a>
 869       <p>
 870       Drawing in a window can be done using various graphical
 871       functions (drawing pixels, lines, rectangles, etc). In order to
 872       draw in a window, we first need to define various general
 873       drawing parameters (what line width to use, which color to draw
 874       with, etc). This is done using a graphical context.
 875       </p>
 876       <ol>
 877         <li class="subtitle"><a name="allocgc">Allocating a Graphics Context</a>
 878         <p>
 879         As we said, a graphical context defines several attributes to
 880         be used with the various drawing functions. For this, we
 881         define a graphical context. We can use more than one graphical
 882         context with a single window, in order to draw in multiple
 883         styles (different colors, different line widths, etc). In XCB,
 884         a Graphics Context is, as a window, characterized by an Id:
 885         </p>
 886         <pre class="code">
 887 typedef uint32_t xcb_gcontext_t;
 888 </pre>
 889         <p>
 890         We first ask the X server to attribute an Id to our graphic
 891         context with this function:
 892         </p>
 893         <pre class="code">
 894 xcb_gcontext_t xcb_generate_id (xcb_connection_t *c);
 895 </pre>
 896         <p>
 897         Then, we set the attributes of the graphic context with this function:
 898         </p>
 899         <pre class="code">
 900 xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c,
 901                                  xcb_gcontext_t    cid,
 902                                  xcb_drawable_t    drawable,
 903                                  uint32_t          value_mask,
 904                                  const uint32_t   *value_list);
 905 </pre>
 906         <p>
 907         We give now an example on how to allocate a graphic context
 908         that specifies that each drawing function that uses it will
 909         draw in foreground with a black color.
 910         </p>
 911         <pre class="code">
 912 #include &lt;xcb/xcb.h&gt;
 913
 914 int
 915 main ()
 916 {
 917   xcb_connection_t *c;
 918   xcb_screen_t     *screen;
 919   xcb_drawable_t    win;
 920   xcb_gcontext_t    black;
 921   uint32_t          mask;
 922   uint32_t          value[1];
 923
 924   /* Open the connection to the X server and get the first screen */
 925   c = xcb_connect (NULL, NULL);
 926   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
 927
 928   /* Create a black graphic context for drawing in the foreground */
 929   win = screen-&gt;root;
 930   black = xcb_generate_id (c);
 931   mask = XCB_GC_FOREGROUND;
 932   value[0] = screen-&gt;black_pixel;
 933   xcb_create_gc (c, black, win, mask, value);
 934
 935   return 0;
 936 }
 937 </pre>
 938         <p>
 939         Note should be taken regarding the role of "value_mask" and
 940         "value_list" in the prototype of <span class="code">xcb_create_gc()</span>. Since a
 941         graphic context has many attributes, and since we often just
 942         want to define a few of them, we need to be able to tell the
 943         <span class="code">xcb_create_gc()</span> which attributes we
 944         want to set. This is what the "value_mask" parameter is
 945         for. We then use the "value_list" parameter to specify actual
 946         values for the attribute we defined in "value_mask". Thus, for
 947         each constant used in "value_list", we will use the matching
 948         constant in "value_mask". In this case, we define a graphic
 949         context with one attribute: when drawing (a point, a line,
 950         etc), the foreground color will be black. The rest of the
 951         attributes of this graphic context will be set to their
 952         default values.
 953         </p>
 954         <p>
 955         See the next Subsection for more details.
 956         </p>
 957         <div class="comp">
 958           <div class="title">
 959           Comparison Xlib/XCB
 960           </div>
 961           <div class="xlib">
 962           <ul>
 963             <li>XCreateGC ()
 964           </ul>
 965           </div>
 966           <div class="xcb">
 967           <ul>
 968             <li>xcb_generate_id ()
 969             <li>xcb_create_gc ()
 970           </ul>
 971           </div>
 972         </div>
 973         <br>
 974         <li class="subtitle"><a name="changegc">Changing the attributes of a Graphics Context</a>
 975         <p>
 976         Once we have allocated a Graphic Context, we may need to
 977         change its attributes (for example, changing the foreground
 978         color we use to draw a line, or changing the attributes of the
 979         font we use to display strings. See Subsections Drawing with a
 980         color and Assigning a Font to a Graphic Context). This is done
 981         by using this function:
 982         </p>
 983         <pre class="code">
 984 xcb_void_cookie_t xcb_change_gc (xcb_connection_t *c,           /* The XCB Connection */
 985                                  xcb_gcontext_t    gc,          /* The Graphic Context */
 986                                  uint32_t          value_mask,  /* Components of the Graphic Context that have to be set */
 987                                  const uint32_t   *value_list); /* Value as specified by value_mask */
 988 </pre>
 989         <p>
 990         The <span class="code">value_mask</span> parameter could take
 991         any combination of these masks from the xcb_gc_t enumeration:
 992         </p>
 993         <ul>
 994           <li>XCB_GC_FUNCTION
 995           <li>XCB_GC_PLANE_MASK
 996           <li>XCB_GC_FOREGROUND
 997           <li>XCB_GC_BACKGROUND
 998           <li>XCB_GC_LINE_WIDTH
 999           <li>XCB_GC_LINE_STYLE
1000           <li>XCB_GC_CAP_STYLE
1001           <li>XCB_GC_JOIN_STYLE
1002           <li>XCB_GC_FILL_STYLE
1003           <li>XCB_GC_FILL_RULE
1004           <li>XCB_GC_TILE
1005           <li>XCB_GC_STIPPLE
1006           <li>XCB_GC_TILE_STIPPLE_ORIGIN_X
1007           <li>XCB_GC_TILE_STIPPLE_ORIGIN_Y
1008           <li>XCB_GC_FONT
1009           <li>XCB_GC_SUBWINDOW_MODE
1010           <li>XCB_GC_GRAPHICS_EXPOSURES
1011           <li>XCB_GC_CLIP_ORIGIN_X
1012           <li>XCB_GC_CLIP_ORIGIN_Y
1013           <li>XCB_GC_CLIP_MASK
1014           <li>XCB_GC_DASH_OFFSET
1015           <li>XCB_GC_DASH_LIST
1016           <li>XCB_GC_ARC_MODE
1017         </ul>
1018         <p>
1019         It is possible to set several attributes at the same
1020         time (for example setting the attributes of a font and the
1021         color which will be used to display a string), by OR'ing these
1022         values in <span class="code">value_mask</span>. Then
1023         <span class="code">value_list</span> has to be an array which
1024         lists the value for the respective attributes.  <b>These values
1025         must be in the same order as masks listed above.</b> See Subsection
1026         Drawing with a color to have an example.
1027         </p>
1028         <p>
1029         <b>TODO</b>: set the links of the 3 subsections, once they will
1030         be written :)
1031         </p>
1032         <p>
1033         <b>TODO</b>: give an example which sets several attributes.
1034         </p>
1035         <li class="subtitle"><a name="drawingprim">Drawing primitives: point, line, box, circle,...</a>
1036         <p>
1037         After we have created a Graphic Context, we can draw on a
1038         window using this Graphic Context, with a set of XCB
1039         functions, collectively called "drawing primitives". Let see
1040         how they are used.
1041         </p>
1042         <p>
1043         To draw a point, or several points, we use
1044         </p>
1045         <pre class="code">
1046 xcb_void_cookie_t xcb_poly_point (xcb_connection_t  *c,               /* The connection to the X server */
1047                                   uint8_t            coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1048                                   xcb_drawable_t     drawable,        /* The drawable on which we want to draw the point(s) */
1049                                   xcb_gcontext_t     gc,              /* The Graphic Context we use to draw the point(s) */
1050                                   uint32_t           points_len,      /* The number of points */
1051                                   const xcb_point_t *points);         /* An array of points */
1052 </pre>
1053         <p>
1054         The <span class="code">coordinate_mode</span> parameter
1055         specifies the coordinate mode.  Available values are
1056         </p>
1057         <ul>
1058           <li><span class="code">XCB_COORD_MODE_ORIGIN</span>
1059           <li><span class="code">XCB_COORD_MODE_PREVIOUS</span>
1060         </ul>
1061         <p>
1062         If XCB_COORD_MODE_PREVIOUS is used, then all points but the first one
1063         are relative to the immediately previous point.
1064         </p>
1065         <p>
1066         The <span class="code">xcb_point_t</span> type is just a
1067         structure with two fields (the coordinates of the point):
1068         </p>
1069         <pre class="code">
1070 typedef struct {
1071     int16_t x;
1072     int16_t y;
1073 } xcb_point_t;
1074 </pre>
1075         <p>
1076         You could see an example in xpoints.c. <b>TODO</b> Set the link.
1077         </p>
1078         <p>
1079         To draw a line, or a polygonal line, we use
1080         </p>
1081         <pre class="code">
1082 xcb_void_cookie_t xcb_poly_line (xcb_connection_t  *c,               /* The connection to the X server */
1083                                  uint8_t            coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1084                                  xcb_drawable_t     drawable,        /* The drawable on which we want to draw the line(s) */
1085                                  xcb_gcontext_t     gc,              /* The Graphic Context we use to draw the line(s) */
1086                                  uint32_t           points_len,      /* The number of points in the polygonal line */
1087                                  const xcb_point_t *points);         /* An array of points */
1088 </pre>
1089         <p>
1090         This function will draw the line between the first and the
1091         second points, then the line between the second and the third
1092         points, and so on.
1093         </p>
1094         <p>
1095         To draw a segment, or several segments, we use
1096         </p>
1097         <pre class="code">
1098 xcb_void_cookie_t xcb_poly_segment (xcb_connection_t    *c,              /* The connection to the X server */
1099                                     xcb_drawable_t       drawable,       /* The drawable on which we want to draw the segment(s) */
1100                                     xcb_gcontext_t       gc,             /* The Graphic Context we use to draw the segment(s) */
1101                                     uint32_t             segments_len,   /* The number of segments */
1102                                     const xcb_segment_t *segments);      /* An array of segments */
1103 </pre>
1104         <p>
1105         The <span class="code">xcb_segment_t</span> type is just a
1106         structure with four fields (the coordinates of the two points
1107         that define the segment):
1108         </p>
1109         <pre class="code">
1110 typedef struct {
1111     int16_t x1;
1112     int16_t y1;
1113     int16_t x2;
1114     int16_t y2;
1115 } xcb_segment_t;
1116 </pre>
1117         <p>
1118         To draw a rectangle, or several rectangles, we use
1119         </p>
1120         <pre class="code">
1121 xcb_void_cookie_t xcb_poly_rectangle (xcb_connection_t      *c,              /* The connection to the X server */
1122                                       xcb_drawable_t         drawable,       /* The drawable on which we want to draw the rectangle(s) */
1123                                       xcb_gcontext_t         gc,             /* The Graphic Context we use to draw the rectangle(s) */
1124                                       uint32_t               rectangles_len, /* The number of rectangles */
1125                                       const xcb_rectangle_t *rectangles);    /* An array of rectangles */
1126 </pre>
1127         <p>
1128         The <span class="code">xcb_rectangle_t</span> type is just a
1129         structure with four fields (the coordinates of the top-left
1130         corner of the rectangle, and its width and height):
1131         </p>
1132         <pre class="code">
1133 typedef struct {
1134     int16_t  x;
1135     int16_t  y;
1136     uint16_t width;
1137     uint16_t height;
1138 } xcb_rectangle_t;
1139 </pre>
1140         <!-- There's no coordinate_mode. Is it normal? -->
1141         <!-- [iano] Yes, it's not in the protocol. -->
1142         <p>
1143         To draw an elliptical arc, or several elliptical arcs, we use
1144         </p>
1145         <pre class="code">
1146 xcb_void_cookie_t xcb_poly_arc (xcb_connection_t *c,          /* The connection to the X server */
1147                                 xcb_drawable_t    drawable,   /* The drawable on which we want to draw the arc(s) */
1148                                 xcb_gcontext_t    gc,         /* The Graphic Context we use to draw the arc(s) */
1149                                 uint32_t          arcs_len,   /* The number of arcs */
1150                                 const xcb_arc_t  *arcs);      /* An array of arcs */
1151 </pre>
1152         <p>
1153         The <span class="code">xcb_arc_t</span> type is a structure with
1154         six fields:
1155         </p>
1156         <pre class="code">
1157 typedef struct {
1158     int16_t  x;       /* Top left x coordinate of the rectangle surrounding the ellipse */
1159     int16_t  y;       /* Top left y coordinate of the rectangle surrounding the ellipse */
1160     uint16_t width;   /* Width of the rectangle surrounding the ellipse */
1161     uint16_t height;  /* Height of the rectangle surrounding the ellipse */
1162     int16_t  angle1;  /* Angle at which the arc begins */
1163     int16_t  angle2;  /* Angle at which the arc ends */
1164 } xcb_arc_t;
1165 </pre>
1166         <div class="emph">
1167         <p>
1168         Note: the angles are expressed in units of 1/64 of a degree,
1169         so to have an angle of 90 degrees, starting at 0,
1170         <span class="code">angle1 = 0</span> and
1171         <span class="code">angle2 = 90 &lt;&lt; 6</span>. Positive angles
1172         indicate counterclockwise motion, while  negative angles
1173         indicate clockwise motion.
1174         </p>
1175         </div>
1176         <!-- I think that (x,y) should be the center of the
1177         ellipse, and (width, height) the radius. It's more logical. -->
1178         <!-- iano: Yes, and I bet some toolkits do that.
1179          But the protocol (and many other graphics APIs) define arcs
1180          by bounding rectangles. -->
1181         <p>
1182         The corresponding function which fill inside the geometrical
1183         object are listed below, without  further explanation, as they
1184         are used as the above functions.
1185         </p>
1186         <p>
1187         To Fill a polygon defined by the points given as arguments ,
1188         we use
1189         </p>
1190         <pre class="code">
1191 xcb_void_cookie_t xcb_fill_poly (xcb_connection_t  *c,
1192                                  xcb_drawable_t     drawable,
1193                                  xcb_gcontext_t     gc,
1194                                  uint8_t            shape,
1195                                  uint8_t            coordinate_mode,
1196                                  uint32_t           points_len,
1197                                  const xcb_point_t *points);
1198 </pre>
1199         <p>
1200         The <span class="code">shape</span> parameter specifies a
1201         shape that helps the server to improve performance. Available
1202         values are
1203         </p>
1204         <ul>
1205           <li><span class="code">XCB_POLY_SHAPE_COMPLEX</span>
1206           <li><span class="code">XCB_POLY_SHAPE_NONCONVEX</span>
1207           <li><span class="code">XCB_POLY_SHAPE_CONVEX</span>
1208         </ul>
1209         <p>
1210         To fill one or several rectangles, we use
1211         </p>
1212         <pre class="code">
1213 xcb_void_cookie_t xcb_poly_fill_rectangle (xcb_connection_t      *c,
1214                                            xcb_drawable_t         drawable,
1215                                            xcb_gcontext_t         gc,
1216                                            uint32_t               rectangles_len,
1217                                            const xcb_rectangle_t *rectangles);
1218 </pre>
1219         <p>
1220         To fill one or several arcs, we use
1221         </p>
1222         <pre class="code">
1223 xcb_void_cookie_t xcb_poly_fill_arc (xcb_connection_t *c,
1224                                      xcb_drawable_t    drawable,
1225                                      xcb_gcontext_t    gc,
1226                                      uint32_t          arcs_len,
1227                                      const xcb_arc_t  *arcs);
1228 </pre>
1229         <br>
1230         <a name="points.c"></a>
1231         <p>
1232         To illustrate these functions, here is an example that draws
1233         four points, a polygonal line, two segments, two rectangles
1234         and two arcs. Remark that we use events for the first time, as
1235         an introduction to the next section.
1236         </p>
1237         <p>
1238         <b>TODO:</b> Use screen-&gt;root_depth for depth parameter.
1239         </p>
1240         <pre class="code">
1241 #include &lt;stdlib.h&gt;
1242 #include &lt;stdio.h&gt;
1243
1244 #include &lt;xcb/xcb.h&gt;
1245
1246 int
1247 main ()
1248 {
1249   xcb_connection_t    *c;
1250   xcb_screen_t        *screen;
1251   xcb_drawable_t       win;
1252   xcb_gcontext_t       foreground;
1253   xcb_generic_event_t *e;
1254   uint32_t             mask = 0;
1255   uint32_t             values[2];
1256
1257   /* geometric objects */
1258   xcb_point_t          points[] = {
1259     {10, 10},
1260     {10, 20},
1261     {20, 10},
1262     {20, 20}};
1263
1264   xcb_point_t          polyline[] = {
1265     {50, 10},
1266     { 5, 20},     /* rest of points are relative */
1267     {25,-20},
1268     {10, 10}};
1269
1270   xcb_segment_t        segments[] = {
1271     {100, 10, 140, 30},
1272     {110, 25, 130, 60}};
1273
1274   xcb_rectangle_t      rectangles[] = {
1275     { 10, 50, 40, 20},
1276     { 80, 50, 10, 40}};
1277
1278   xcb_arc_t            arcs[] = {
1279     {10, 100, 60, 40, 0, 90 &lt;&lt; 6},
1280     {90, 100, 55, 40, 0, 270 &lt;&lt; 6}};
1281
1282   /* Open the connection to the X server */
1283   c = xcb_connect (NULL, NULL);
1284
1285   /* Get the first screen */
1286   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1287
1288   /* Create black (foreground) graphic context */
1289   win = screen-&gt;root;
1290
1291   foreground = xcb_generate_id (c);
1292   mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
1293   values[0] = screen-&gt;black_pixel;
1294   values[1] = 0;
1295   xcb_create_gc (c, foreground, win, mask, values);
1296
1297   /* Ask for our window's Id */
1298   win = xcb_generate_id(c);
1299
1300   /* Create the window */
1301   mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1302   values[0] = screen-&gt;white_pixel;
1303   values[1] = XCB_EVENT_MASK_EXPOSURE;
1304   xcb_create_window (c,                             /* Connection          */
1305                      XCB_COPY_FROM_PARENT,          /* depth               */
1306                      win,                           /* window Id           */
1307                      screen-&gt;root,                  /* parent window       */
1308                      0, 0,                          /* x, y                */
1309                      150, 150,                      /* width, height       */
1310                      10,                            /* border_width        */
1311                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
1312                      screen-&gt;root_visual,           /* visual              */
1313                      mask, values);                 /* masks */
1314
1315   /* Map the window on the screen */
1316   xcb_map_window (c, win);
1317
1318
1319   /* We flush the request */
1320   xcb_flush (c);
1321
1322   while ((e = xcb_wait_for_event (c))) {
1323     switch (e-&gt;response_type &amp; ~0x80) {
1324     case XCB_EXPOSE: {
1325       /* We draw the points */
1326       xcb_poly_point (c, XCB_COORD_MODE_ORIGIN, win, foreground, 4, points);
1327
1328       /* We draw the polygonal line */
1329       xcb_poly_line (c, XCB_COORD_MODE_PREVIOUS, win, foreground, 4, polyline);
1330
1331       /* We draw the segements */
1332       xcb_poly_segment (c, win, foreground, 2, segments);
1333
1334       /* We draw the rectangles */
1335       xcb_poly_rectangle (c, win, foreground, 2, rectangles);
1336
1337       /* We draw the arcs */
1338       xcb_poly_arc (c, win, foreground, 2, arcs);
1339
1340       /* We flush the request */
1341       xcb_flush (c);
1342
1343       break;
1344     }
1345     default: {
1346       /* Unknown event type, ignore it */
1347       break;
1348     }
1349     }
1350     /* Free the Generic Event */
1351     free (e);
1352   }
1353
1354   return 0;
1355 }
1356 </pre>
1357       </ol>
1358       <li class="title"><a name="xevents">X Events</a>
1359       <p>
1360       In an X program, everything is driven by events. Event painting
1361       on the screen is sometimes done as a response to an event (an
1362       <span class="code">Expose</span> event). If part of a program's
1363       window that was hidden, gets exposed (e.g. the window was raised
1364       above other widows), the X server will send an "expose" event to
1365       let the program know it should repaint that part of the
1366       window. User input (key presses, mouse movement, etc) is also
1367       received as a set of events.
1368       </p>
1369       <ol>
1370         <li class="subtitle"><a name="register">Registering for event types using event masks</a>
1371         <p>
1372         During the creation of a window, you should give it what kind
1373         of events it wishes to receive. Thus, you may register for
1374         various mouse (also called pointer) events, keyboard events,
1375         expose events, and so on. This is done for optimizing the
1376         server-to-client connection (i.e. why send a program (that
1377         might even be running at the other side of the globe) an event
1378         it is not interested in ?)
1379         </p>
1380         <p>
1381         In XCB, you use the "value_mask" and "value_list" data in the
1382         <span class="code">xcb_create_window()</span> function to
1383         register for events. Here is how we register for
1384         <span class="code">Expose</span> event when creating a window:
1385         </p>
1386         <pre class="code">
1387   mask = XCB_CW_EVENT_MASK;
1388   valwin[0] = XCB_EVENT_MASK_EXPOSURE;
1389   win = xcb_generate_id (c);
1390   xcb_create_window (c, depth, win, root-&gt;root,
1391                      0, 0, 150, 150, 10,
1392                      XCB_WINDOW_CLASS_INPUT_OUTPUT, root-&gt;root_visual,
1393                      mask, valwin);
1394 </pre>
1395         <p>
1396         <span class="code">XCB_EVENT_MASK_EXPOSURE</span> is a constant defined
1397         in the xcb_event_mask_t enumeration in the "xproto.h" header file. If we wanted to register for several
1398         event types, we can logically "or" them, as follows:
1399         </p>
1400         <pre class="code">
1401   mask = XCB_CW_EVENT_MASK;
1402   valwin[0] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS;
1403   win = xcb_generate_id (c);
1404   xcb_create_window (c, depth, win, root-&gt;root,
1405                      0, 0, 150, 150, 10,
1406                      XCB_WINDOW_CLASS_INPUT_OUTPUT, root-&gt;root_visual,
1407                      mask, valwin);
1408 </pre>
1409         <p>
1410         This registers for <span class="code">Expose</span> events as
1411         well as for mouse button presses inside the created
1412         window. You should note that a mask may represent several
1413         event sub-types.
1414         </p>
1415         <p>
1416         The values that a mask could take are given
1417         by the <span class="code">xcb_cw_t</span> enumeration:
1418         </p>
1419         <pre class="code">
1420 typedef enum {
1421     XCB_CW_BACK_PIXMAP       = 1L<<0,
1422     XCB_CW_BACK_PIXEL        = 1L<<1,
1423     XCB_CW_BORDER_PIXMAP     = 1L<<2,
1424     XCB_CW_BORDER_PIXEL      = 1L<<3,
1425     XCB_CW_BIT_GRAVITY       = 1L<<4,
1426     XCB_CW_WIN_GRAVITY       = 1L<<5,
1427     XCB_CW_BACKING_STORE     = 1L<<6,
1428     XCB_CW_BACKING_PLANES    = 1L<<7,
1429     XCB_CW_BACKING_PIXEL     = 1L<<8,
1430     XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
1431     XCB_CW_SAVE_UNDER        = 1L<<10,
1432     XCB_CW_EVENT_MASK        = 1L<<11,
1433     XCB_CW_DONT_PROPAGATE    = 1L<<12,
1434     XCB_CW_COLORMAP          = 1L<<13,
1435     XCB_CW_CURSOR            = 1L<<14
1436 } xcb_cw_t;
1437 </pre>
1438         <div class="emph">
1439         <p>Note: we must be careful when setting the values of the valwin
1440         parameter, as they have to follow the order the
1441         <span class="code">xcb_cw_t</span> enumeration. Here is an
1442         example:
1443         </p>
1444         </div>
1445         <pre class="code">
1446   mask = XCB_CW_EVENT_MASK | XCB_CW_BACK_PIXMAP;
1447   valwin[0] = XCB_NONE;                                              /* for XCB_CW_BACK_PIXMAP (whose value is 1)     */
1448   valwin[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; /* for XCB_CW_EVENT_MASK, whose value (2048)     */
1449                                                                      /* is greater than the one of XCB_CW_BACK_PIXMAP */
1450 </pre>
1451         <p>
1452         If the window has already been created, we can use the
1453         <span class="code">xcb_configure_window()</span> function to set
1454         the events that the window will receive. The subsection
1455         <a href="#winconf">Configuring a window</a> shows its
1456         prototype. As an example, here is a piece of code that
1457         configures the window to receive the
1458         <span class="code">Expose</span> and
1459         <span class="code">ButtonPress</span> events:
1460         </p>
1461         <pre class="code">
1462 const static uint32_t values[] = { XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS };
1463
1464 /* The connection c and the window win are supposed to be defined */
1465
1466 xcb_configure_window (c, win, XCB_CW_EVENT_MASK, values);
1467 </pre>
1468         <div class="emph">
1469         <p>
1470         Note: A common bug programmers do is adding code to handle new
1471         event types in their program, while forgetting to add the
1472         masks for these events in the creation of the window. Such a
1473         programmer then should sit down for hours debugging his
1474         program, wondering "Why doesn't my program notice that I
1475         released the button?", only to find that they registered for
1476         button press events but not for button release events.
1477         </p>
1478         </div>
1479         <li class="subtitle"><a name="loop">Receiving events: writing the events loop</a>
1480         <p>
1481         After we have registered for the event types we are interested
1482         in, we need to enter a loop of receiving events and handling
1483         them. There are two ways to receive events: a blocking way and
1484         a non-blocking way:
1485         </p>
1486         <ul>
1487           <li>
1488           <span class="code">xcb_wait_for_event (xcb_connection_t *c)</span>
1489           is the blocking way. It waits (so blocks...) until an event is
1490           queued in the X server. Then it retrieves it into a newly
1491           allocated structure (it dequeues it from the queue) and returns
1492           it. This structure has to be freed. The function returns
1493           <span class="code">NULL</span> if an error occurs.
1494
1495           <br>
1496           <li>
1497           <span class="code">xcb_poll_for_event (xcb_connection_t *c, int
1498           *error)</span> is the non-blocking way. It looks at the event
1499           queue and returns (and dequeues too) an existing event into
1500           a newly allocated structure. This structure has to be
1501           freed. It returns <span class="code">NULL</span> if there is
1502           no event. If an error occurs, the parameter <span
1503           class="code">error</span> will be filled with the error
1504           status.
1505         </ul>
1506         <p>
1507         There are various ways to write such a loop. We present two
1508         ways to write such a loop, with the two functions above. The
1509         first one uses <span class="code">xcb_wait_for_event_t</span>, which
1510         is similar to an event Xlib loop using only <span
1511         class="code">XNextEvent</span>:
1512         </p>
1513         <pre class="code">
1514   xcb_generic_event_t *e;
1515
1516   while ((e = xcb_wait_for_event (c))) {
1517     switch (e-&gt;response_type &amp; ~0x80) {
1518     case XCB_EXPOSE: {
1519       /* Handle the Expose event type */
1520       xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1521
1522       /* ... */
1523
1524       break;
1525     }
1526     case XCB_BUTTON_PRESS: {
1527       /* Handle the ButtonPress event type */
1528       xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1529
1530       /* ... */
1531
1532       break;
1533     }
1534     default: {
1535       /* Unknown event type, ignore it */
1536       break;
1537     }
1538     }
1539     /* Free the Generic Event */
1540     free (e);
1541   }
1542 </pre>
1543         <p>
1544         You will certainly want to use <span
1545         class="code">xcb_poll_for_event(xcb_connection_t *c, int
1546         *error)</span> if, in Xlib, you use <span
1547         class="code">XPending</span> or
1548         <span class="code">XCheckMaskEvent</span>:
1549         </p>
1550         <pre class="code">
1551   while (XPending (display)) {
1552     XEvent ev;
1553
1554     XNextEvent(d, &amp;ev);
1555
1556     /* Manage your event */
1557   }
1558 </pre>
1559         <p>
1560         Such a loop in XCB looks like:
1561         </p>
1562         <pre class="code">
1563   xcb_generic_event_t *ev;
1564
1565   while ((ev = xcb_poll_for_event (conn, 0))) {
1566     /* Manage your event */
1567   }
1568 </pre>
1569         <p>
1570         The events are managed in the same way as with <span
1571         class="code">xcb_wait_for_event_t</span>.
1572         Obviously, we will need to give the user some way of
1573         terminating the program. This is usually done by handling a
1574         special "quit" event, as we will soon see.
1575         </p>
1576         <div class="comp">
1577           <div class="title">
1578             Comparison Xlib/XCB
1579           </div>
1580           <div class="xlib">
1581             <ul>
1582               <li>XNextEvent ()
1583               </ul>
1584           </div>
1585           <div class="xcb">
1586             <ul>
1587               <li>xcb_wait_for_event ()
1588             </ul>
1589           </div>
1590           <div class="xlib">
1591             <ul>
1592               <li>XPending ()
1593               <li>XCheckMaskEvent ()
1594             </ul>
1595           </div>
1596           <div class="xcb">
1597             <ul>
1598               <li>xcb_poll_for_event ()
1599             </ul>
1600           </div>
1601         </div>
1602         <br>
1603         <li class="subtitle"><a name="expose">Expose events</a>
1604         <p>
1605         The <span class="code">Expose</span> event is one of the most
1606         basic (and most used) events an application may receive. It
1607         will be sent to us in one of several cases:
1608         </p>
1609         <ul>
1610           <li>A window that covered part of our window has moved
1611               away, exposing part (or all) of our window.
1612           <li>Our window was raised above other windows.
1613           <li>Our window mapped for the first time.
1614           <li>Our window was de-iconified.
1615         </ul>
1616         <p>
1617         You should note the implicit assumption hidden here: the
1618         contents of our window is lost when it is being obscured
1619         (covered) by either windows. One may wonder why the X server
1620         does not save this contents. The answer is: to save
1621         memory. After all, the number of windows on a display at a
1622         given time may be very large, and storing the contents of all
1623         of them might require a lot of memory. Actually, there is a
1624         way to tell the X server to store  the contents of a window in
1625         special cases, as we will see later.
1626         </p>
1627         <p>
1628         When we get an <span class="code">Expose</span> event, we
1629         should take the event's data from the members of the following
1630         structure:
1631         </p>
1632         <pre class="code">
1633 typedef struct {
1634     uint8_t      response_type; /* The type of the event, here it is XCB_EXPOSE */
1635     uint8_t      pad0;
1636     uint16_t     sequence;
1637     xcb_window_t window;        /* The Id of the window that receives the event (in case */
1638                                 /* our application registered for events on several windows */
1639     uint16_t     x;             /* The x coordinate of the top-left part of the window that needs to be redrawn */
1640     uint16_t     y;             /* The y coordinate of the top-left part of the window that needs to be redrawn */
1641     uint16_t     width;         /* The width of the part of the window that needs to be redrawn */
1642     uint16_t     height;        /* The height of the part of the window that needs to be redrawn */
1643     uint16_t     count;
1644 } xcb_expose_event_t;
1645 </pre>
1646         <li class="subtitle"><a name="userinput">Getting user input</a>
1647         <p>
1648         User input traditionally comes from two sources: the mouse
1649         and the keyboard. Various event types exist to notify us of
1650         user input (a key being presses on the keyboard, a key being
1651         released on the keyboard, the mouse moving over our window,
1652         the mouse entering (or leaving) our window, and so on.
1653         </p>
1654         <ol>
1655             <li class="subsubtitle"><a name="mousepressrelease">Mouse button press and release events</a>
1656           <p>
1657           The first event type we will deal with is a mouse
1658           button-press (or button-release) event in our window. In
1659           order to register to such an event type, we should add one
1660           (or more) of the following masks when we create our window:
1661           </p>
1662           <ul>
1663             <li><span class="code">XCB_EVENT_MASK_BUTTON_PRESS</span>: notify us
1664             of any button that was pressed in one of our windows.
1665             <li><span class="code">XCB_EVENT_MASK_BUTTON_RELEASE</span>: notify us
1666             of any button that was released in one of our windows.
1667           </ul>
1668           <p>
1669           The structure to be checked for in our events loop is the
1670           same for these two events, and is the following:
1671           </p>
1672           <pre class="code">
1673 typedef struct {
1674     uint8_t         response_type; /* The type of the event, here it is xcb_button_press_event_t or xcb_button_release_event_t */
1675     xcb_button_t    detail;
1676     uint16_t        sequence;
1677     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1678     xcb_window_t    root;
1679     xcb_window_t    event;
1680     xcb_window_t    child;
1681     int16_t         root_x;
1682     int16_t         root_y;
1683     int16_t         event_x;       /* The x coordinate where the mouse has been pressed in the window */
1684     int16_t         event_y;       /* The y coordinate where the mouse has been pressed in the window */
1685     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1686     uint8_t         same_screen;
1687 } xcb_button_press_event_t;
1688
1689 typedef xcb_button_press_event_t xcb_button_release_event_t;
1690 </pre>
1691           <p>
1692           The <span class="code">time</span> field may be used to calculate "double-click"
1693           situations by an application (e.g. if the mouse button was
1694           clicked two times in a duration shorter than a given amount
1695           of time, assume this was a double click).
1696           </p>
1697           <p>
1698           The <span class="code">state</span> field is a mask of the buttons held down during
1699           the event. It is a bitwise OR of any of the following (from the xcb_button_mask_t and
1700           xcb_mod_mask_t enumerations):
1701           </p>
1702           <ul>
1703             <li><span class="code">XCB_BUTTON_MASK_1</span>
1704             <li><span class="code">XCB_BUTTON_MASK_2</span>
1705             <li><span class="code">XCB_BUTTON_MASK_3</span>
1706             <li><span class="code">XCB_BUTTON_MASK_4</span>
1707             <li><span class="code">XCB_BUTTON_MASK_5</span>
1708             <li><span class="code">XCB_MOD_MASK_SHIFT</span>
1709             <li><span class="code">XCB_MOD_MASK_LOCK</span>
1710             <li><span class="code">XCB_MOD_MASK_CONTROL</span>
1711             <li><span class="code">XCB_MOD_MASK_1</span>
1712             <li><span class="code">XCB_MOD_MASK_2</span>
1713             <li><span class="code">XCB_MOD_MASK_3</span>
1714             <li><span class="code">XCB_MOD_MASK_4</span>
1715             <li><span class="code">XCB_MOD_MASK_5</span>
1716           </ul>
1717           <p>
1718           Their names are self explanatory, where the first 5 refer to
1719           the mouse buttons that are being pressed, while the rest
1720           refer to various "special keys" that are being pressed (Mod1
1721           is usually the 'Alt' key or the 'Meta' key).
1722           </p>
1723           <p>
1724           <b>TODO:</b> Problem: it seems that the state does not
1725           change when clicking with various buttons.
1726           </p>
1727             <li class="subsubtitle"><a name="mousemvnt">Mouse movement events</a>
1728           <p>
1729           Similar to mouse button press and release events, we also
1730           can be notified of various mouse movement events. These can
1731           be split into two families. One is of mouse pointer
1732           movement while no buttons are pressed, and the second is a
1733           mouse pointer motion while one (or more) of the buttons are
1734           pressed (this is sometimes called "a mouse drag operation",
1735           or just "dragging"). The following event masks may be added
1736           during the creation of our window:
1737           </p>
1738           <ul>
1739             <li><span class="code">XCB_EVENT_MASK_POINTER_MOTION</span>: events of
1740             the pointer moving in one of the windows controlled by our
1741             application, while no mouse button is held pressed.
1742             <li><span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>: Events of
1743             the pointer moving while one or more of the mouse buttons
1744             is held pressed.
1745             <li><span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>: same as
1746             <span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>, but only when
1747             the 1st mouse button is held pressed.
1748             <li><span class="code">XCB_EVENT_MASK_BUTTON_2_MOTION</span>,
1749             <span class="code">XCB_EVENT_MASK_BUTTON_3_MOTION</span>,
1750             <span class="code">XCB_EVENT_MASK_BUTTON_4_MOTION</span>,
1751             <span class="code">XCB_EVENT_MASK_BUTTON_5_MOTION</span>: same as
1752             <span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>, but
1753             respectively for 2nd, 3rd, 4th and 5th mouse button.
1754           </ul>
1755           <p>
1756           The structure to be checked for in our events loop is the
1757           same for these events, and is the following:
1758           </p>
1759           <pre class="code">
1760 typedef struct {
1761     uint8_t         response_type; /* The type of the event */
1762     uint8_t         detail;
1763     uint16_t        sequence;
1764     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1765     xcb_window_t    root;
1766     xcb_window_t    event;
1767     xcb_window_t    child;
1768     int16_t         root_x;
1769     int16_t         root_y;
1770     int16_t         event_x;       /* The x coordinate of the mouse when the  event was generated */
1771     int16_t         event_y;       /* The y coordinate of the mouse when the  event was generated */
1772     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1773     uint8_t         same_screen;
1774 } xcb_motion_notify_event_t;
1775 </pre>
1776             <li class="subsubtitle"><a name="mouseenter">Mouse pointer enter and leave events</a>
1777           <p>
1778           Another type of event that applications might be interested
1779           in, is a mouse pointer entering a window the program
1780           controls, or leaving such a window. Some programs use these
1781           events to show the user that the application is now in
1782           focus. In order to register for such an event type, we
1783           should add one (or more) of the following masks when we
1784           create our window:
1785           </p>
1786           <ul>
1787             <li><span class="code">xcb_event_enter_window_t</span>: notify us
1788             when the mouse pointer enters any of our controlled
1789             windows.
1790             <li><span class="code">xcb_event_leave_window_t</span>: notify us
1791             when the mouse pointer leaves any of our controlled
1792             windows.
1793           </ul>
1794           <p>
1795           The structure to be checked for in our events loop is the
1796           same for these two events, and is the following:
1797           </p>
1798           <pre class="code">
1799 typedef struct {
1800     uint8_t         response_type; /* The type of the event */
1801     uint8_t         detail;
1802     uint16_t        sequence;
1803     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1804     xcb_window_t    root;
1805     xcb_window_t    event;
1806     xcb_window_t    child;
1807     int16_t         root_x;
1808     int16_t         root_y;
1809     int16_t         event_x;       /* The x coordinate of the mouse when the  event was generated */
1810     int16_t         event_y;       /* The y coordinate of the mouse when the  event was generated */
1811     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1812     uint8_t         mode;          /* The number of mouse button that was clicked */
1813     uint8_t         same_screen_focus;
1814 } xcb_enter_notify_event_t;
1815
1816 typedef xcb_enter_notify_event_t xcb_leave_notify_event_t;
1817 </pre>
1818           <li class="subsubtitle"><a name="focus">The keyboard focus</a>
1819           <p>
1820           There may be many windows on a screen, but only a single
1821           keyboard attached to them. How does the X server then know
1822           which window should be sent a given keyboard input ? This is
1823           done using the keyboard focus. Only a single window on the
1824           screen may have the keyboard focus at a given time. There
1825           is a XCB function that allows a program to set the keyboard
1826           focus to a given window. The user can usually set the
1827           keyboard focus using the window manager (often by clicking
1828           on the title bar of the desired window). Once our window
1829           has the keyboard focus, every key press or key release will
1830           cause an event to be sent to our program (if it regsitered
1831           for these event types...).
1832           </p>
1833           <li class="subsubtitle"><a name="keypress">Keyboard press and release events</a>
1834           <p>
1835           If a window controlled by our program currently holds the
1836           keyboard focus, it can receive key press and key release
1837           events. So, we should add one (or more) of the following
1838           masks when we create our window:
1839           </p>
1840           <ul>
1841             <li><span class="code">XCB_EVENT_MASK_KEY_PRESS</span>: notify us when
1842             a key was pressed while any of our controlled windows had
1843             the keyboard focus.
1844             <li><span class="code">XCB_EVENT_MASK_KEY_RELEASE</span>: notify us
1845             when a key was released while any of our controlled
1846             windows had the keyboard focus.
1847           </ul>
1848           <p>
1849           The structure to be checked for in our events loop is the
1850           same for these two events, and is the following:
1851           </p>
1852           <pre class="code">
1853 typedef struct {
1854     uint8_t         response_type; /* The type of the event */
1855     xcb_keycode_t   detail;
1856     uint16_t        sequence;
1857     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1858     xcb_window_t    root;
1859     xcb_window_t    event;
1860     xcb_window_t    child;
1861     int16_t         root_x;
1862     int16_t         root_y;
1863     int16_t         event_x;
1864     int16_t         event_y;
1865     uint16_t        state;
1866     uint8_t         same_screen;
1867 } xcb_key_press_event_t;
1868
1869 typedef xcb_key_press_event_t xcb_key_release_event_t;
1870 </pre>
1871         <p>
1872         The <span class="code">detail</span> field refers to the
1873         physical key on the keyboard.
1874         </p>
1875         <p>
1876         <b>TODO:</b> Talk about getting the ASCII code from the key code.
1877         </p>
1878         </ol>
1879         <li class="subtitle"><a name="eventex">X events: a complete example</a>
1880         <p>
1881         As an example for handling events, we show a program that
1882         creates a window, enters an events loop and checks for all the
1883         events described above, and writes on the terminal the relevant
1884         characteristics of the event. With this code, it should be
1885         easy to add drawing operations, like those which have been
1886         described above.
1887         </p>
1888         <pre class="code">
1889 #include &lt;stdlib.h&gt;
1890 #include &lt;stdio.h&gt;
1891
1892 #include &lt;xcb/xcb.h&gt;
1893
1894 void
1895 print_modifiers (uint32_t mask)
1896 {
1897   const char **mod, *mods[] = {
1898     "Shift", "Lock", "Ctrl", "Alt",
1899     "Mod2", "Mod3", "Mod4", "Mod5",
1900     "Button1", "Button2", "Button3", "Button4", "Button5"
1901   };
1902   printf ("Modifier mask: ");
1903   for (mod = mods ; mask; mask &gt;&gt;= 1, mod++)
1904     if (mask &amp; 1)
1905       printf(*mod);
1906   putchar ('\n');
1907 }
1908
1909 int
1910 main ()
1911 {
1912   xcb_connection_t    *c;
1913   xcb_screen_t        *screen;
1914   xcb_window_t         win;
1915   xcb_generic_event_t *e;
1916   uint32_t             mask = 0;
1917   uint32_t             values[2];
1918
1919   /* Open the connection to the X server */
1920   c = xcb_connect (NULL, NULL);
1921
1922   /* Get the first screen */
1923   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1924
1925   /* Ask for our window's Id */
1926   win = xcb_generate_id (c);
1927
1928   /* Create the window */
1929   mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1930   values[0] = screen-&gt;white_pixel;
1931   values[1] = XCB_EVENT_MASK_EXPOSURE       | XCB_EVENT_MASK_BUTTON_PRESS   |
1932               XCB_EVENT_MASK_BUTTON_RELEASE | XCB_EVENT_MASK_POINTER_MOTION |
1933               XCB_EVENT_MASK_ENTER_WINDOW   | XCB_EVENT_MASK_LEAVE_WINDOW   |
1934               XCB_EVENT_MASK_KEY_PRESS      | XCB_EVENT_MASK_KEY_RELEASE;
1935   xcb_create_window (c,                             /* Connection          */
1936                      0,                             /* depth               */
1937                      win,                           /* window Id           */
1938                      screen-&gt;root,                  /* parent window       */
1939                      0, 0,                          /* x, y                */
1940                      150, 150,                      /* width, height       */
1941                      10,                            /* border_width        */
1942                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
1943                      screen-&gt;root_visual,           /* visual              */
1944                      mask, values);                 /* masks */
1945
1946   /* Map the window on the screen */
1947   xcb_map_window (c, win);
1948
1949   xcb_flush (c);
1950
1951   while ((e = xcb_wait_for_event (c))) {
1952     switch (e-&gt;response_type &amp; ~0x80) {
1953     case XCB_EXPOSE: {
1954       xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1955
1956       printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
1957               ev-&gt;window, ev-&gt;x, ev-&gt;y, ev-&gt;width, ev-&gt;height);
1958       break;
1959     }
1960     case XCB_BUTTON_PRESS: {
1961       xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1962       print_modifiers(ev-&gt;state);
1963
1964       switch (ev-&gt;detail) {
1965       case 4:
1966         printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
1967                 ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1968         break;
1969       case 5:
1970         printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
1971                 ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1972         break;
1973       default:
1974         printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
1975                 ev-&gt;detail, ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1976       }
1977       break;
1978     }
1979     case XCB_BUTTON_RELEASE: {
1980       xcb_button_release_event_t *ev = (xcb_button_release_event_t *)e;
1981       print_modifiers(ev-&gt;state);
1982
1983       printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
1984               ev-&gt;detail, ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1985       break;
1986     }
1987     case XCB_MOTION_NOTIFY: {
1988       xcb_motion_notify_event_t *ev = (xcb_motion_notify_event_t *)e;
1989
1990       printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
1991               ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1992       break;
1993     }
1994     case XCB_ENTER_NOTIFY: {
1995       xcb_enter_notify_event_t *ev = (xcb_enter_notify_event_t *)e;
1996
1997       printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
1998               ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
1999       break;
2000     }
2001     case XCB_LEAVE_NOTIFY: {
2002       xcb_leave_notify_event_t *ev = (xcb_leave_notify_event_t *)e;
2003
2004       printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
2005               ev-&gt;event, ev-&gt;event_x, ev-&gt;event_y);
2006       break;
2007     }
2008     case XCB_KEY_PRESS: {
2009       xcb_key_press_event_t *ev = (xcb_key_press_event_t *)e;
2010       print_modifiers(ev-&gt;state);
2011
2012       printf ("Key pressed in window %ld\n",
2013               ev-&gt;event);
2014       break;
2015     }
2016     case XCB_KEY_RELEASE: {
2017       xcb_key_release_event_t *ev = (xcb_key_release_event_t *)e;
2018       print_modifiers(ev-&gt;state);
2019
2020       printf ("Key released in window %ld\n",
2021               ev-&gt;event);
2022       break;
2023     }
2024     default:
2025       /* Unknown event type, ignore it */
2026       printf("Unknown event: %d\n", e-&gt;response_type);
2027       break;
2028     }
2029     /* Free the Generic Event */
2030     free (e);
2031   }
2032
2033   return 0;
2034 }
2035 </pre>
2036       </ol>
2037       <li class="title"><a name="font">Handling text and fonts</a>
2038       <p>
2039       Besides drawing graphics on a window, we often want to draw
2040       text. Text strings have two major properties: the characters to
2041       be drawn and the font with which they are drawn. In order to
2042       draw text, we need to first request the X server to load a
2043       font. We then assign a font to a Graphic Context, and finally, we
2044       draw the text in a window, using the Graphic Context.
2045       </p>
2046       <ol>
2047         <li class="subtitle"><a name="fontstruct">The Font structure</a>
2048         <p>
2049         In order to support flexible fonts, a font structure is
2050         defined. You know what ? It's an Id:
2051         </p>
2052         <pre class="code">
2053 typedef uint32_t xcb_font_t;
2054 </pre>
2055         <p>
2056         It is used to contain information about a font, and is passed
2057         to several functions that handle fonts selection and text drawing.
2058         </p>
2059         <p>
2060         <b>TODO:</b> example for picking a font and displaying some text.
2061         Even better, also demonstrate translating keypresses to text.
2062         </p>
2063       </ol>
2064       <li class="title"><a name="wm">Interacting with the window manager</a>
2065       <p>
2066       After we have seen how to create windows and draw on them, we
2067       take one step back, and look at how our windows are interacting
2068       with their environment (the full screen and the other
2069       windows). First of all, our application needs to interact with
2070       the window manager. The window manager is responsible to
2071       decorating drawn windows (i.e. adding a frame, an iconify
2072       button, a system menu, a title bar, etc), as well as handling
2073       icons shown when windows are being iconified. It also handles
2074       ordering of windows on the screen, and other administrative
2075       tasks. We need to give it various hints as to how we want it to
2076       treat our application's windows.
2077       </p>
2078       <ol>
2079         <li class="subtitle"><a name="wmprop">Window properties</a>
2080         <p>
2081         Many of the parameters communicated to the window manager are
2082         passed using data called "properties". These properties are
2083         attached by the X server to different windows, and are stored
2084         in a format that makes it possible to read them from different
2085         machines that may use different architectures (remember that
2086         an X client program may run on a remote machine).
2087         </p>
2088         <p>
2089         The property and its type (a string, an integer, etc) are
2090         Id. Their type are <span class="code">xcb_atom_t</span>:
2091         </p>
2092         <pre class="code">
2093 typedef uint32_t xcb_atom_t;
2094 </pre>
2095         <p>
2096         To change the property of a window, we use the following
2097         function:
2098         </p>
2099         <pre class="code">
2100 xcb_void_cookie_t xcb_change_property (xcb_connection_t *c,       /* Connection to the X server */
2101                                        uint8_t          mode,     /* Property mode */
2102                                        xcb_window_t     window,   /* Window */
2103                                        xcb_atom_t       property, /* Property to change */
2104                                        xcb_atom_t       type,     /* Type of the property */
2105                                        uint8_t          format,   /* Format of the property (8, 16, 32) */
2106                                        uint32_t         data_len, /* Length of the data parameter */
2107                                        const void      *data);    /* Data */
2108 </pre>
2109         <p>
2110         The <span class="code">mode</span> parameter coud be one of
2111         the following values (defined in enumeration xcb_prop_mode_t in
2112         the xproto.h header file):
2113         </p>
2114         <ul>
2115           <li>XCB_PROP_MODE_REPLACE
2116           <li>XCB_PROP_MODE_PREPEND
2117           <li>XCB_PROP_MODE_APPEND
2118         </ul>
2119         <br>
2120         <li class="subtitle"><a name="wmname">Setting the window name and icon name</a>
2121         <p>
2122         The first thing we want to do would be to set the name for our
2123         window. This is done using the
2124         <span class="code">xcb_change_property()</span> function. This
2125         name may be used by the window manager as the title of the
2126         window (in the title bar), in a task list, etc. The property
2127         atom to use to set the name of a window is
2128         <span class="code">WM_NAME</span> (and
2129         <span class="code">WM_ICON_NAME</span> for the iconified
2130         window) and its type is <span class="code">STRING</span>. Here
2131         is an example of utilization:
2132         </p>
2133         <pre class="code">
2134 #include &lt;string.h&gt;
2135
2136 #include &lt;xcb/xcb.h&gt;
2137 #include &lt;xcb/xcb_atom.h&gt;
2138
2139 int
2140 main ()
2141 {
2142   xcb_connection_t *c;
2143   xcb_screen_t     *screen;
2144   xcb_window_t      win;
2145   char             *title = "Hello World !";
2146   char             *title_icon = "Hello World ! (iconified)";
2147
2148
2149
2150   /* Open the connection to the X server */
2151   c = xcb_connect (NULL, NULL);
2152
2153   /* Get the first screen */
2154   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2155
2156   /* Ask for our window's Id */
2157   win = xcb_generate_id (c);
2158
2159   /* Create the window */
2160   xcb_create_window (c,                             /* Connection          */
2161                      0,                             /* depth               */
2162                      win,                           /* window Id           */
2163                      screen-&gt;root,                  /* parent window       */
2164                      0, 0,                          /* x, y                */
2165                      250, 150,                      /* width, height       */
2166                      10,                            /* border_width        */
2167                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
2168                      screen-&gt;root_visual,           /* visual              */
2169                      0, NULL);                      /* masks, not used     */
2170
2171   /* Set the title of the window */
2172   xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2173                        WM_NAME, STRING, 8,
2174                        strlen (title), title);
2175
2176   /* Set the title of the window icon */
2177   xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2178                        WM_ICON_NAME, STRING, 8,
2179                        strlen(title_icon), title_icon);
2180
2181   /* Map the window on the screen */
2182   xcb_map_window (c, win);
2183
2184   xcb_flush (c);
2185
2186   while (1) {}
2187
2188   return 0;
2189 }
2190 </pre>
2191         <div class="emph">
2192         <p>Note: the use of the atoms needs our program to be compiled
2193         and linked against xcb_atom, so that we have to use
2194         </p>
2195         </div>
2196         <pre class="text">
2197 gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`
2198 </pre>
2199         <div class="emph">
2200         <p>
2201         for the program to compile fine.
2202         </p>
2203         </div>
2204       </ol>
2205       <li class="title"><a name="winop">Simple window operations</a>
2206       <p>
2207       One more thing we can do to our window is manipulate them on the
2208       screen (resize them, move them, raise or lower them, iconify
2209       them, and so on). Some window operations functions are supplied
2210       by XCB for this purpose.
2211       </p>
2212       <ol>
2213         <li class="subtitle"><a name="winmap">Mapping and un-mapping a window</a>
2214         <p>
2215         The first pair of operations we can apply on a window is
2216         mapping it, or un-mapping it. Mapping a window causes the
2217         window to appear on the screen, as we have seen in our simple
2218         window program example. Un-mapping it causes it to be removed
2219         from the screen (although the window as a logical entity still
2220         exists). This gives the effect of making a window hidden
2221         (unmapped) and shown again (mapped). For example, if we have a
2222         dialog box window in our program, instead of creating it every
2223         time the user asks to open it, we can create the window once,
2224         in an un-mapped mode, and when the user asks to open it, we
2225         simply map the window on the screen. When the user clicked the
2226         'OK' or 'Cancel' button, we simply un-map the window. This is
2227         much faster than creating and destroying the window, however,
2228         the cost is wasted resources, both on the client side, and on
2229         the X server side.
2230         </p>
2231         <p>
2232         To map a window, you use the following function:
2233         </p>
2234         <pre class="code">
2235 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
2236                                   xcb_window_t      window);
2237 </pre>
2238         <p>
2239         To have a simple example, see the <a href="#helloworld">example</a>
2240         above. The mapping operation will cause an
2241         <span class="code">Expose</span> event to be sent to our
2242         application, unless the window is completely covered by other
2243         windows.
2244         </p>
2245         <p>
2246         Un-mapping a window is also simple. You use the function
2247         </p>
2248         <pre class="code">
2249 xcb_void_cookie_t xcb_unmap_window (xcb_connection_t *c,
2250                                     xcb_window_t      window);
2251 </pre>
2252         <p>
2253         The utilization of this function is the same as
2254         <span class="code">xcb_map_window()</span>.
2255         </p>
2256         <li class="subtitle"><a name="winconf">Configuring a window</a>
2257         <p>
2258         As we have seen when we have created our first window, in the
2259         X Events subsection, we can set some attributes for the window
2260         (that is, the position, the size, the events the window will
2261         receive, etc). If we want to modify them, but the window is
2262         already created, we can change them by using the following
2263         function:
2264         </p>
2265         <pre class="code">
2266 xcb_void_cookie_t xcb_configure_window (xcb_connection_t *c,            /* The connection to the X server*/
2267                                         xcb_window_t      window,       /* The window to configure */
2268                                         uint16_t          value_mask,   /* The mask */
2269                                         const uint32_t   *value_list);  /* The values to set */
2270 </pre>
2271         <p>
2272         We set the <span class="code">value_mask</span> to one or
2273         several mask values that are in the xcb_config_window_t enumeration in the xproto.h header:
2274         </p>
2275         <ul>
2276           <li><span class="code">XCB_CONFIG_WINDOW_X</span>: new x coordinate of the window's top left corner
2277           <li><span class="code">XCB_CONFIG_WINDOW_Y</span>: new y coordinate of the window's top left corner
2278           <li><span class="code">XCB_CONFIG_WINDOW_WIDTH</span>: new width of the window
2279           <li><span class="code">XCB_CONFIG_WINDOW_HEIGHT</span>: new height of the window
2280           <li><span class="code">XCB_CONFIG_WINDOW_BORDER_WIDTH</span>: new width of the border of the window
2281           <li><span class="code">XCB_CONFIG_WINDOW_SIBLING</span>
2282           <li><span class="code">XCB_CONFIG_WINDOW_STACK_MODE</span>: the new stacking order
2283         </ul>
2284         <p>
2285         We then give to <span class="code">value_mask</span> the new
2286         value. We now describe how to use
2287         <span class="code">xcb_configure_window_t</span> in some useful
2288         situations.
2289         </p>
2290         <li class="subtitle"><a name="winmove">Moving a window around the screen</a>
2291         <p>
2292         An operation we might want to do with windows is to move them
2293         to a different location. This can be done like this:
2294         </p>
2295         <pre class="code">
2296 const static uint32_t values[] = { 10, 20 };
2297
2298 /* The connection c and the window win are supposed to be defined */
2299
2300 /* Move the window to coordinates x = 10 and y = 20 */
2301 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y, values);
2302 </pre>
2303         <p>
2304         Note that when the window is moved, it might get partially
2305         exposed or partially hidden by other windows, and thus we
2306         might get <span class="code">Expose</span> events due to this
2307         operation.
2308         </p>
2309         <li class="subtitle"><a name="winsize">Resizing a window</a>
2310         <p>
2311         Yet another operation we can do is to change the size of a
2312         window. This is done using the following code:
2313         </p>
2314         <pre class="code">
2315 const static uint32_t values[] = { 200, 300 };
2316
2317 /* The connection c and the window win are supposed to be defined */
2318
2319 /* Resize the window to width = 10 and height = 20 */
2320 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2321 </pre>
2322         <p>
2323         We can also combine the move and resize operations using one
2324         single call to <span class="code">xcb_configure_window_t</span>:
2325         </p>
2326         <pre class="code">
2327 const static uint32_t values[] = { 10, 20, 200, 300 };
2328
2329 /* The connection c and the window win are supposed to be defined */
2330
2331 /* Move the window to coordinates x = 10 and y = 20 */
2332 /* and resize the window to width = 10 and height = 20 */
2333 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y | XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2334 </pre>
2335         <li class="subtitle"><a name="winstack">Changing windows stacking order: raise and lower</a>
2336         <p>
2337         Until now, we changed properties of a single window. We'll see
2338         that there are properties that relate to the window and other
2339         windows. One of them is the stacking order. That is, the order
2340         in which the windows are layered on top of each other. The
2341         front-most window is said to be on the top of the stack, while
2342         the back-most window is at the bottom of the stack. Here is
2343         how to manipulate our windows stack order:
2344         </p>
2345         <pre class="code">
2346 const static uint32_t values[] = { XCB_STACK_MODE_ABOVE };
2347
2348 /* The connection c and the window win are supposed to be defined */
2349
2350 /* Move the window on the top of the stack */
2351 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2352 </pre>
2353         <pre class="code">
2354 const static uint32_t values[] = { XCB_STACK_MODE_BELOW };
2355
2356 /* The connection c and the window win are supposed to be defined */
2357
2358 /* Move the window on the bottom of the stack */
2359 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2360 </pre>
2361         <li class="subtitle"><a name="wingetinfo">Getting information about a window</a>
2362         <p>
2363         Just like we can set various attributes of our windows, we can
2364         also ask the X server supply the current values of these
2365         attributes. For example, we can check where a window is
2366         located on the screen, what is its current size, whether it is
2367         mapped or not, etc. The structure that contains some of this
2368         information is
2369         </p>
2370         <pre class="code">
2371 typedef struct {
2372     uint8_t      response_type;
2373     uint8_t      depth;         /* depth of the window */
2374     uint16_t     sequence;
2375     uint32_t     length;
2376     xcb_window_t root;          /* Id of the root window *>
2377     int16_t      x;             /* X coordinate of the window's location */
2378     int16_t      y;             /* Y coordinate of the window's location */
2379     uint16_t     width;         /* Width of the window */
2380     uint16_t     height;        /* Height of the window */
2381     uint16_t     border_width;  /* Width of the window's border */
2382 } xcb_get_geometry_reply_t;
2383 </pre>
2384         <p>
2385         XCB fill this structure with two functions:
2386         </p>
2387         <pre class="code">
2388 xcb_get_geometry_cookie_t  xcb_get_geometry       (xcb_connection_t         *c,
2389                                                    xcb_drawable_t            drawable);
2390 xcb_get_geometry_reply_t  *xcb_get_geometry_reply (xcb_connection_t         *c,
2391                                                    xcb_get_geometry_cookie_t cookie,
2392                                                    xcb_generic_error_t     **e);
2393 </pre>
2394         <p>
2395         You use them as follows:
2396         </p>
2397         <pre class="code">
2398   xcb_connection_t         *c;
2399   xcb_drawable_t            win;
2400   xcb_get_geometry_reply_t *geom;
2401
2402   /* You initialize c and win */
2403
2404   geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2405
2406   /* Do something with the fields of geom */
2407
2408   free (geom);
2409 </pre>
2410         <p>
2411         Remark that you have to free the structure, as
2412         <span class="code">xcb_get_geometry_reply_t</span> allocates a
2413         newly one.
2414         </p>
2415         <p>
2416         One problem is that the returned location of the window is
2417         relative to its parent window. This makes these coordinates
2418         rather useless for any window manipulation functions, like
2419         moving it on the screen. In order to overcome this problem, we
2420         need to take a two-step operation. First, we find out the Id
2421         of the parent window of our window. We then translate the
2422         above relative coordinates to the screen coordinates.
2423         </p>
2424         <p>
2425         To get the Id of the parent window, we need this structure:
2426         </p>
2427         <pre class="code">
2428 typedef struct {
2429     uint8_t      response_type;
2430     uint8_t      pad0;
2431     uint16_t     sequence;
2432     uint32_t     length;
2433     xcb_window_t root;
2434     xcb_window_t parent;       /* Id of the parent window */
2435     uint16_t     children_len;
2436     uint8_t      pad1[14];
2437 } xcb_query_tree_reply_t;
2438 </pre>
2439         <p>
2440         To fill this structure, we use these two functions:
2441         </p>
2442         <pre class="code">
2443 xcb_query_tree_cookie_t xcb_query_tree       (xcb_connection_t        *c,
2444                                               xcb_window_t             window);
2445 xcb_query_tree_reply_t *xcb_query_tree_reply (xcb_connection_t        *c,
2446                                               xcb_query_tree_cookie_t  cookie,
2447                                               xcb_generic_error_t    **e);
2448 </pre>
2449         <p>
2450         The translated coordinates will be found in this structure:
2451         </p>
2452         <pre class="code">
2453 typedef struct {
2454     uint8_t      response_type;
2455     uint8_t      same_screen;
2456     uint16_t     sequence;
2457     uint32_t     length;
2458     xcb_window_t child;
2459     uint16_t     dst_x;        /* Translated x coordinate */
2460     uint16_t     dst_y;        /* Translated y coordinate */
2461 } xcb_translate_coordinates_reply_t;
2462 </pre>
2463         <p>
2464         As usual, we need two functions to fill this structure:
2465         </p>
2466         <pre class="code">
2467 xcb_translate_coordinates_cookie_t xcb_translate_coordinates       (xcb_connection_t                  *c,
2468                                                                     xcb_window_t                       src_window,
2469                                                                     xcb_window_t                       dst_window,
2470                                                                     int16_t                            src_x,
2471                                                                     int16_t                            src_y);
2472 xcb_translate_coordinates_reply_t *xcb_translate_coordinates_reply (xcb_connection_t                  *c,
2473                                                                     xcb_translate_coordinates_cookie_t cookie,
2474                                                                     xcb_generic_error_t              **e);
2475 </pre>
2476         <p>
2477         We use them as follows:
2478         </p>
2479         <pre class="code">
2480   xcb_connection_t                  *c;
2481   xcb_drawable_t                     win;
2482   xcb_get_geometry_reply_t          *geom;
2483   xcb_query_tree_reply_t            *tree;
2484   xcb_translate_coordinates_reply_t *trans;
2485
2486   /* You initialize c and win */
2487
2488   geom  = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2489   if (!geom)
2490     return 0;
2491
2492   tree  = xcb_query_tree_reply (c, xcb_query_tree (c, win), NULL);
2493   if (!tree)
2494     return 0;
2495
2496   trans = xcb_translate_coordinates_reply (c,
2497                                            xcb_translate_coordinates (c,
2498                                                                       win,
2499                                                                       tree-&gt;parent,
2500                                                                       geom-&gt;x, geom-&gt;y),
2501                                            NULL);
2502   if (!trans)
2503     return 0;
2504
2505   /* the translated coordinates are in trans-&gt;dst_x and trans-&gt;dst_y */
2506
2507   free (trans);
2508   free (tree);
2509   free (geom);
2510 </pre>
2511         <p>
2512         Of course, as for <span class="code">geom</span>,
2513         <span class="code">tree</span> and
2514         <span class="code">trans</span> have to be freed.
2515         </p>
2516         <p>
2517         The work is a bit hard, but XCB is a very low-level library.
2518         </p>
2519         <p>
2520         <b>TODO:</b> the utilization of these functions should be a
2521         prog, which displays the coordinates of the window.
2522         </p>
2523         <p>
2524         There is another structure that gives informations about our window:
2525         </p>
2526         <pre class="code">
2527 typedef struct {
2528     uint8_t        response_type;
2529     uint8_t        backing_store;
2530     uint16_t       sequence;
2531     uint32_t       length;
2532     xcb_visualid_t visual;                /* Visual of the window */
2533     uint16_t       _class;
2534     uint8_t        bit_gravity;
2535     uint8_t        win_gravity;
2536     uint32_t       backing_planes;
2537     uint32_t       backing_pixel;
2538     uint8_t        save_under;
2539     uint8_t        map_is_installed;
2540     uint8_t        map_state;             /* Map state of the window */
2541     uint8_t        override_redirect;
2542     xcb_colormap_t colormap;              /* Colormap of the window */
2543     uint32_t       all_event_masks;
2544     uint32_t       your_event_mask;
2545     uint16_t       do_not_propagate_mask;
2546 } xcb_get_window_attributes_reply_t;
2547 </pre>
2548         <p>
2549         XCB supplies these two functions to fill it:
2550         </p>
2551         <pre class="code">
2552 xcb_get_window_attributes_cookie_t xcb_get_window_attributes       (xcb_connection_t                  *c,
2553                                                                     xcb_window_t                       window);
2554 xcb_get_window_attributes_reply_t *xcb_get_window_attributes_reply (xcb_connection_t                  *c,
2555                                                                     xcb_get_window_attributes_cookie_t cookie,
2556                                                                     xcb_generic_error_t              **e);
2557 </pre>
2558         <p>
2559         You use them as follows:
2560         </p>
2561         <pre class="code">
2562   xcb_connection_t                  *c;
2563   xcb_drawable_t                     win;
2564   xcb_get_window_attributes_reply_t *attr;
2565
2566   /* You initialize c and win */
2567
2568   attr = xcb_get_window_attributes_reply (c, xcb_get_window_attributes (c, win), NULL);
2569
2570   if (!attr)
2571     return 0;
2572
2573   /* Do something with the fields of attr */
2574
2575   free (attr);
2576 </pre>
2577         <p>
2578         As for <span class="code">geom</span>,
2579         <span class="code">attr</span> has to be freed.
2580         </p>
2581       </ol>
2582       <li class="title"><a name="usecolor">Using colors to paint the rainbow</a>
2583       <p>
2584       Up until now, all our painting operation were done using black
2585       and white. We will (finally) see now how to draw using colors.
2586       </p>
2587       <ol>
2588         <li class="subtitle"><a name="colormap">Color maps</a>
2589         <p>
2590         In the beginning, there were not enough colors. Screen
2591         controllers could only support a limited number of colors
2592         simultaneously (initially 2, then 4, 16 and 256). Because of
2593         this, an application could not just ask to draw in a "light
2594         purple-red" color, and expect that color to be available. Each
2595         application allocated the colors it needed, and when all the
2596         color entries (4, 16, 256 colors) were in use, the next color
2597         allocation would fail.
2598         </p>
2599         <p>
2600         Thus, the notion of "a color map" was introduced. A color map
2601         is a table whose size is the same as the number of
2602         simultaneous colors a given screen controller. Each entry
2603         contained the RGB (Red, Green and Blue) values of a different
2604         color (all colors can be drawn using some combination of red,
2605         green and blue). When an application wants to draw on the
2606         screen, it does not specify which color to use. Rather, it
2607         specifies which color entry of some color map to be used
2608         during this drawing. Change the value in this color map entry
2609         and the drawing will use a different color.
2610         </p>
2611         <p>
2612         In order to be able to draw using colors that got something to
2613         do with what the programmer intended, color map allocation
2614         functions are supplied. You could ask to allocate entry for a
2615         color with a set of RGB values. If one already existed, you
2616         would get its index in the table. If none existed, and the
2617         table was not full, a new cell would be allocated to contain
2618         the given RGB values, and its index returned. If the table was
2619         full, the procedure would fail. You could then ask to get a
2620         color map entry with a color that is closest to the one you
2621         were asking for. This would mean that the actual drawing on
2622         the screen would be done using colors similar to what you
2623         wanted, but not the same.
2624         </p>
2625         <p>
2626         On today's more modern screens where one runs an X server with
2627         support for 16 million colors, this limitation looks a little
2628         silly, but remember that there are still older computers with
2629         older graphics cards out there. Using color map, support for
2630         these screen becomes transparent to you. On a display
2631         supporting 16 million colors, any color entry allocation
2632         request would succeed. On a display supporting a limited
2633         number of colors, some color allocation requests would return
2634         similar colors. It won't look as good, but your application
2635         would still work.
2636         </p>
2637         <li class="subtitle"><a name="colormapalloc">Allocating and freeing Color Maps</a>
2638         <p>
2639         When you draw using XCB, you can choose to use the standard
2640         color map of the screen your window is displayed on, or you
2641         can allocate a new color map and apply it to a window. In the
2642         latter case, each time the mouse moves onto your window, the
2643         screen color map will be replaced by your window's color map,
2644         and you'll see all the other windows on screen change their
2645         colors into something quite bizzare. In fact, this is the
2646         effect you get with X applications that use the "-install"
2647         command line option.
2648         </p>
2649         <p>
2650         In XCB, a color map is (as often in X) an Id:
2651         </p>
2652         <pre class="code">
2653 typedef uint32_t xcb_colormap_t;
2654 </pre>
2655         <p>
2656         In order to access the screen's default color map, you just
2657         have to retrieve the <span class="code">default_colormap</span>
2658         field of the <span class="code">xcb_screen_t</span> structure
2659         (see Section
2660         <a href="#screen">Checking basic information about a connection</a>):
2661         </p>
2662         <pre class="code">
2663 #include &lt;stdio.h&gt;
2664
2665 #include &lt;xcb/xcb.h&gt;
2666
2667 int
2668 main ()
2669 {
2670   xcb_connection_t *c;
2671   xcb_screen_t     *screen;
2672   xcb_colormap_t    colormap;
2673
2674   /* Open the connection to the X server and get the first screen */
2675   c = xcb_connect (NULL, NULL);
2676   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2677
2678   colormap = screen-&gt;default_colormap;
2679
2680   return 0;
2681 }
2682 </pre>
2683         <p>
2684         This will return the color map used by default on the first
2685         screen (again, remember that an X server may support several
2686         different screens, each of which might have its own resources).
2687         </p>
2688         <p>
2689         The other option, that of allocating a new colormap, works as
2690         follows.  We first ask the X server to give an Id to our color
2691         map, with this function:
2692         </p>
2693         <pre class="code">
2694 xcb_colormap_t xcb_generate_id (xcb_connection_t *c);
2695 </pre>
2696         <p>
2697         Then, we create the color map with
2698         </p>
2699         <pre class="code">
2700 xcb_void_cookie_t xcb_create_colormap (xcb_connection_t *c,       /* Pointer to the xcb_connection_t structure */
2701                                        uint8_t           alloc,   /* Colormap entries to be allocated (AllocNone or AllocAll) */
2702                                        xcb_colormap_t    mid,     /* Id of the color map */
2703                                        xcb_window_t      window,  /* Window on whose screen the colormap will be created */
2704                                        xcb_visualid_t    visual); /* Id of the visual supported by the screen */
2705 </pre>
2706         <p>
2707         Here is an example of creation of a new color map:
2708         </p>
2709         <pre class="code">
2710 #include &lt;xcb/xcb.h&gt;
2711
2712 int
2713 main ()
2714 {
2715   xcb_connection_t *c;
2716   xcb_screen_t     *screen;
2717   xcb_window_t      win;
2718   xcb_colormap_t    cmap
2719
2720   /* Open the connection to the X server and get the first screen */
2721   c = xcb_connect (NULL, NULL);
2722   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2723
2724   /* We create the window win here*/
2725
2726   cmap = xcb_generate_id (c);
2727   xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen-&gt;root_visual);
2728
2729   return 0;
2730 }
2731 </pre>
2732         <p>
2733         Note that the window parameter is only used to allow the X
2734         server to create the color map for the given screen. We can
2735         then use this color map for any window drawn on the same screen.
2736         </p>
2737         <p>
2738         To free  a color map, it suffices to use this function:
2739         </p>
2740         <pre class="code">
2741 xcb_void_cookie_t xcb_free_colormap (xcb_connection_t *c,   /* The connection */
2742                                      xcb_colormap_t cmap);  /* The color map */
2743 </pre>
2744         <div class="comp">
2745           <div class="title">
2746             Comparison Xlib/XCB
2747           </div>
2748           <div class="xlib">
2749             <ul>
2750               <li>XCreateColormap ()
2751             </ul>
2752           </div>
2753           <div class="xcb">
2754             <ul>
2755               <li>xcb_generate_id ()
2756               <li>xcb_create_colormap ()
2757             </ul>
2758           </div>
2759           <div class="xlib">
2760             <ul>
2761               <li>XFreeColormap ()
2762             </ul>
2763           </div>
2764           <div class="xcb">
2765             <ul>
2766               <li>xcb_free_colormap ()
2767             </ul>
2768           </div>
2769         </div>
2770         <br>
2771         <li class="subtitle"><a name="alloccolor">Allocating and freeing a color entry</a>
2772         <p>
2773         Once we got access to some color map, we can start allocating
2774         colors. The informations related to a color are stored in the
2775         following structure:
2776         </p>
2777         <pre class="code">
2778 typedef struct {
2779     uint8_t  response_type;
2780     uint8_t  pad0;
2781     uint16_t sequence;
2782     uint32_t length;
2783     uint16_t red;          /* The red component   */
2784     uint16_t green;        /* The green component */
2785     uint16_t blue;         /* The blue component  */
2786     uint8_t  pad1[2];
2787     uint32_t pixel;        /* The entry in the color map, supplied by the X server */
2788 } xcb_alloc_color_reply_t;
2789 </pre>
2790       <p>
2791       XCB supplies these two functions to fill it:
2792       </p>
2793       <pre class="code">
2794 xcb_alloc_color_cookie_t xcb_alloc_color       (xcb_connection_t        *c,
2795                                                 xcb_colormap_t           cmap,
2796                                                 uint16_t                 red,
2797                                                 uint16_t                 green,
2798                                                 uint16_t                 blue);
2799 xcb_alloc_color_reply_t *xcb_alloc_color_reply (xcb_connection_t        *c,
2800                                                 xcb_alloc_color_cookie_t cookie,
2801                                                 xcb_generic_error_t    **e);
2802 </pre>
2803       <p>
2804       The fuction <span class="code">xcb_alloc_color()</span> takes the
2805       3 RGB components as parameters (red, green and blue). Here is an
2806       example of using these functions:
2807       </p>
2808       <pre class="code">
2809 #include &lt;malloc.h&gt;
2810
2811 #include &lt;xcb/xcb.h&gt;
2812
2813 int
2814 main ()
2815 {
2816   xcb_connection_t        *c;
2817   xcb_screen_t            *screen;
2818   xcb_window_t             win;
2819   xcb_colormap_t           cmap;
2820   xcb_alloc_color_reply_t *rep;
2821
2822   /* Open the connection to the X server and get the first screen */
2823   c = xcb_connect (NULL, NULL);
2824   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2825
2826   /* We create the window win here*/
2827
2828   cmap = xcb_generate_id (c);
2829   xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen-&gt;root_visual);
2830
2831   rep = xcb_alloc_color_reply (c, xcb_alloc_color (c, cmap, 65535, 0, 0), NULL);
2832
2833   if (!rep)
2834     return 0;
2835
2836   /* Do something with r-&gt;pixel or the components */
2837
2838   free (rep);
2839
2840   return 0;
2841 }
2842 </pre>
2843       <p>
2844       As <span class="code">xcb_alloc_color_reply()</span> allocates
2845       memory, you have to free <span class="code">rep</span>.
2846       </p>
2847       <p>
2848       <b>TODO</b>: Talk about freeing colors.
2849       </p>
2850       </ol>
2851       <li class="title"><a name="pixmaps">X Bitmaps and Pixmaps</a>
2852       <p>
2853       One thing many so-called "Multi-Media" applications need to do,
2854       is display images. In the X world, this is done using bitmaps
2855       and pixmaps. We have already seen some usage of them when
2856       setting an icon for our application. Lets study them further,
2857       and see how to draw these images inside a window, along side the
2858       simple graphics and text we have seen so far.
2859       </p>
2860       <p>
2861       One thing to note before delving further, is that XCB (nor Xlib)
2862       supplies no means of manipulating popular image formats, such as
2863       gif, png, jpeg or tiff. It is up to the programmer (or to higher
2864       level graphics libraries) to translate these image formats into
2865       formats that the X server is familiar with (x bitmaps and x
2866       pixmaps).
2867       </p>
2868       <ol>
2869         <li class="subtitle"><a name="pixmapswhat">What is a X Bitmap? An X Pixmap?</a>
2870         <p>
2871         An X bitmap is a two-color image stored in a format specific
2872         to the X window system. When stored in a file, the bitmap data
2873         looks like a C source file. It contains variables defining the
2874         width and the height of the bitmap, an array containing the
2875         bit values of the bitmap (the size of the array is
2876         (width+7)/8*height and the bit and byte order are LSB), and
2877         an optional hot-spot location (that will
2878         be explained later, when discussing mouse cursors).
2879         </p>
2880         <p>
2881         An X pixmap is a format used to stored images in the memory of
2882         an X server. This format can store both black and white images
2883         (such as x bitmaps) as well as color images. It is the only
2884         image format supported by the X protocol, and any image to be
2885         drawn on screen, should be first translated into this format.
2886         </p>
2887         <p>
2888         In actuality, an X pixmap can be thought of as a window that
2889         does not appear on the screen. Many graphics operations that
2890         work on windows, will also work on pixmaps. Indeed, the type
2891         of X pixmap in XCB is an Id like a window:
2892         </p>
2893         <pre class="code">
2894 typedef uint32_t xcb_pixmap_t;
2895 </pre>
2896         <p>
2897         Like Xlib, there is no difference between a Drawable, a Window
2898         or a Pixmap:
2899         </p>
2900         <pre class="code">
2901 typedef uint32_t xcb_drawable_t;
2902 </pre>
2903         <p>
2904         in order to avoid confusion between a window and a pixmap. The
2905         operations that will work the same on a window or a pixmap
2906         will require a <span class="code">xcb_drawable_t</span>
2907         </p>
2908         <div class="emph">
2909         <p>
2910         Remark: In Xlib, there is no specific difference between a
2911         <span class="code">Drawable</span>, a
2912         <span class="code">Pixmap</span> or a
2913         <span class="code">Window</span>: all are 32 bit long
2914         integer.  XCB wraps all these different IDs in structures to
2915         provide some measure of type-safety.
2916         </p>
2917         </div>
2918         <li class="subtitle"><a name="pixmapscreate">Creating a pixmap</a>
2919         <p>
2920         Sometimes we want to create an un-initialized pixmap, so we
2921         can later draw into it. This is useful for image drawing
2922         programs (creating a new empty canvas will cause the creation
2923         of a new pixmap on which the drawing can be stored). It is
2924         also useful when reading various image formats: we load the
2925         image data into memory, create a pixmap on the server, and
2926         then draw the decoded image data onto that pixmap.
2927         </p>
2928         <p>
2929         To create a new pixmap, we first ask the X server to give an
2930         Id to our pixmap, with this function:
2931         </p>
2932         <pre class="code">
2933 xcb_pixmap_t xcb_generate_id (xcb_connection_t *c);
2934 </pre>
2935         <p>
2936          Then, XCB supplies the following function to create new pixmaps:
2937         </p>
2938         <pre class="code">
2939 xcb_void_cookie_t xcb_create_pixmap (xcb_connection_t *c,         /* Pointer to the xcb_connection_t structure */
2940                                      uint8_t           depth,     /* Depth of the screen */
2941                                      xcb_pixmap_t      pid,       /* Id of the pixmap */
2942                                      xcb_drawable_t    drawable,
2943                                      uint16_t          width,     /* Width of the window (in pixels) */
2944                                      uint16_t          height);   /* Height of the window (in pixels) */
2945 </pre>
2946         <p>
2947         <b>TODO</b>: Explain the drawable parameter, and give an
2948         example (like <a href="xpoints.c">xpoints.c</a>)
2949         </p>
2950         <li class="subtitle"><a name="pixmapsdraw"></a>Drawing a pixmap in a window
2951         <p>
2952         Once we got a handle to a pixmap, we can draw it on some
2953         window, using the following function:
2954         </p>
2955         <pre class="code">
2956 xcb_void_cookie_t xcb_copy_area (xcb_connection_t *c,             /* Pointer to the xcb_connection_t structure */
2957                                  xcb_drawable_t    src_drawable,  /* The Drawable we want to paste */
2958                                  xcb_drawable_t    dst_drawable,  /* The Drawable on which we copy the previous Drawable */
2959                                  xcb_gcontext_t    gc,            /* A Graphic Context */
2960                                  int16_t           src_x,         /* Top left x coordinate of the region we want to copy */
2961                                  int16_t           src_y,         /* Top left y coordinate of the region we want to copy */
2962                                  int16_t           dst_x,         /* Top left x coordinate of the region where we want to copy */
2963                                  int16_t           dst_y,         /* Top left y coordinate of the region where we want to copy */
2964                                  uint16_t          width,         /* Width of the region we want to copy */
2965                                  uint16_t          height);       /* Height of the region we want to copy */
2966 </pre>
2967         <p>
2968         As you can see, we could copy the whole pixmap, as well as
2969         only a given rectangle of the pixmap. This is useful to
2970         optimize the drawing speed: we could copy only what we have
2971         modified in the pixmap.
2972         </p>
2973         <p>
2974         <b>One important note should be made</b>: it is possible to
2975         create pixmaps with different depths on the same screen. When
2976         we perform copy operations (a pixmap onto a window, etc), we
2977         should make sure that both source and target have the same
2978         depth. If they have a different depth, the operation would
2979         fail. The exception to this is if we copy a specific bit plane
2980         of the source pixmap using the
2981         <span class="code">xcb_copy_plane_t</span> function. In such an
2982         event, we can copy a specific plane to the target window (in
2983         actuality, setting a specific bit in the color of each pixel
2984         copied). This can be used to generate strange graphic effects
2985         in a window, but that is beyond the scope of this tutorial.
2986         </p>
2987         <li class="subtitle"><a name="pixmapsfree"></a>Freeing a pixmap
2988         <p>
2989         Finally, when we are done using a given pixmap, we should free
2990         it, in order to free resources of the X server. This is done
2991         using this function:
2992         </p>
2993         <pre class="code">
2994 xcb_void_cookie_t xcb_free_pixmap (xcb_connection_t *c,        /* Pointer to the xcb_connection_t structure */
2995                                    xcb_pixmap_t      pixmap);  /* A given pixmap */
2996 </pre>
2997         <p>
2998         Of course, after having freed it, we must not try accessing
2999         the pixmap again.
3000         </p>
3001         <p>
3002         <b>TODO</b>: Give an example, or a link to xpoints.c
3003         </p>
3004       </ol>
3005       <li class="title"><a name="mousecursor">Messing with the mouse cursor</a>
3006       <p>
3007       It it possible to modify the shape of the mouse pointer (also
3008       called the X pointer) when in certain states, as we otfen see in
3009       programs. For example, a busy application would often display
3010       the sand clock over its main window, to give the user a visual
3011       hint that he should wait. Let's see how we can change the mouse
3012       cursor of our windows.
3013       </p>
3014       <ol>
3015         <li class="subtitle"><a name="mousecursorcreate">Creating and destroying a mouse cursor</a>
3016         <p>
3017         There are two methods for creating cursors. One of them is by
3018         using a set of predefined cursors, that are supplied by the X
3019         server, the other is by using a user-supplied bitmap.
3020         </p>
3021         <p>
3022         In the first method, we use a special font named "cursor", and
3023         the function <span class="code">xcb_create_glyph_cursor</span>:
3024         </p>
3025         <pre class="code">
3026 xcb_void_cookie_t xcb_create_glyph_cursor (xcb_connection_t *c,
3027                                            xcb_cursor_t      cid,
3028                                            xcb_font_t        source_font, /* font for the source glyph */
3029                                            xcb_font_t        mask_font,   /* font for the mask glyph or XCB_NONE */
3030                                            uint16_t          source_char, /* character glyph for the source */
3031                                            uint16_t          mask_char,   /* character glyph for the mask */
3032                                            uint16_t          fore_red,    /* red value for the foreground of the source */
3033                                            uint16_t          fore_green,  /* green value for the foreground of the source */
3034                                            uint16_t          fore_blue,   /* blue value for the foreground of the source */
3035                                            uint16_t          back_red,    /* red value for the background of the source */
3036                                            uint16_t          back_green,  /* green value for the background of the source */
3037                                            uint16_t          back_blue)   /* blue value for the background of the source */
3038 </pre>
3039         <p>
3040         <b>TODO</b>: Describe <span class="code">source_char</span>
3041         and <span class="code">mask_char</span>, for example by giving
3042         an example on how to get the values. There is a list there:
3043         <a href="http://tronche.com/gui/x/xlib/appendix/b/">X Font Cursors</a>
3044         </p>
3045         <p>
3046         So we first open that font (see <a href="#loadfont">Loading a Font</a>)
3047         and create the new cursor. As for every X ressource, we have to
3048         ask for an X id with <span class="code">xcb_generate_id</span>
3049         first:
3050         </p>
3051         <pre class="code">
3052 xcb_font_t           font;
3053 xcb_cursor_t         cursor;
3054
3055 /* The connection is set */
3056
3057 font = xcb_generate_id (conn);
3058 xcb_open_font (conn, font, strlen ("cursor"), "cursor");
3059
3060 cursor = xcb_generate_id (conn);
3061 xcb_create_glyph_cursor (conn, cursor, font, font,
3062                          58, 58 + 1,
3063                          0, 0, 0,
3064                          0, 0, 0);
3065 </pre>
3066         <p>
3067         We have created the cursor "right hand" by specifying 58 to
3068         the <span class="code">source_fon</span>t argument and 58 + 1
3069         to the <span class="code">mask_font</span>.
3070         </p>
3071         <p>
3072         The cursor is destroyed by using the function
3073         </p>
3074         <pre class="code">
3075 xcb_void_cookie_t xcb_free_cursor (xcb_connection_t *c,
3076                                    xcb_cursor_t      cursor);
3077 </pre>
3078         <p>
3079         In the second method, we create a new cursor by using a pair
3080         of pixmaps, with depth of one (that is, two colors
3081         pixmaps). One pixmap defines the shape of the cursor, while
3082         the other works as a mask, specifying which pixels of the
3083         cursor will be actually drawn. The rest of the pixels will be
3084         transparent.
3085         </p>
3086         <p>
3087         <b>TODO</b>: give an example.
3088         </p>
3089         <li class="subtitle"><a name="mousecursorset">Setting a window's mouse cursor</a>
3090         <p>
3091         Once the cursor is created, we can modify the cursor of our
3092         window by using <span class="code">xcb_change_window_attributes</span>
3093         and using the <span class="code">XCB_CWCURSOR</span> attribute:
3094         </p>
3095         <pre class="code">
3096 uint32_t mask;
3097 uint32_t value_list;
3098
3099 /* The connection and window are set */
3100 /* The cursor is already created */
3101
3102 mask = XCB_CWCURSOR;
3103 value_list = cursor;
3104 xcb_change_window_attributes (conn, window, mask, &amp;value_list);
3105 </pre>
3106         <p>
3107         Of course, the cursor and the font must be freed.
3108         </p>
3109         <li class="subtitle"><a name="mousecursorexample">Complete example</a>
3110         <p>
3111         The following example displays a window with a
3112         button. When entering the window, the window cursor is changed
3113         to an arrow. When clicking once on the button, the cursor is
3114         changed to a hand. When clicking again on the button, the
3115         cursor window gets back to the arrow. The Esc key exits the
3116         application.
3117         </p>
3118         <pre class="code">
3119 #include &lt;stdlib.h&gt;
3120 #include &lt;stdio.h&gt;
3121 #include &lt;string.h&gt;
3122
3123 #include &lt;xcb/xcb.h&gt;
3124
3125 #define WIDTH 300
3126 #define HEIGHT 150
3127
3128
3129
3130 static xcb_gc_t gc_font_get (xcb_connection_t *c,
3131                              xcb_screen_t     *screen,
3132                              xcb_window_t      window,
3133                              const char       *font_name);
3134
3135 static void button_draw (xcb_connection_t *c,
3136                          xcb_screen_t     *screen,
3137                          xcb_window_t      window,
3138                          int16_t           x1,
3139                          int16_t           y1,
3140                          const char       *label);
3141
3142 static void text_draw (xcb_connection_t *c,
3143                        xcb_screen_t     *screen,
3144                        xcb_window_t      window,
3145                        int16_t           x1,
3146                        int16_t           y1,
3147                        const char       *label);
3148
3149 static void cursor_set (xcb_connection_t *c,
3150                         xcb_screen_t     *screen,
3151                         xcb_window_t      window,
3152                         int               cursor_id);
3153
3154
3155 static void
3156 button_draw (xcb_connection_t *c,
3157              xcb_screen_t     *screen,
3158              xcb_window_t      window,
3159              int16_t           x1,
3160              int16_t           y1,
3161              const char       *label)
3162 {
3163   xcb_point_t          points[5];
3164   xcb_void_cookie_t    cookie_gc;
3165   xcb_void_cookie_t    cookie_line;
3166   xcb_void_cookie_t    cookie_text;
3167   xcb_generic_error_t *error;
3168   xcb_gcontext_t       gc;
3169   int16_t              width;
3170   int16_t              height;
3171   uint8_t              length;
3172   int16_t              inset;
3173
3174   length = strlen (label);
3175   inset = 2;
3176
3177   gc = gc_font_get(c, screen, window, "7x13");
3178
3179   width = 7 * length + 2 * (inset + 1);
3180   height = 13 + 2 * (inset + 1);
3181   points[0].x = x1;
3182   points[0].y = y1;
3183   points[1].x = x1 + width;
3184   points[1].y = y1;
3185   points[2].x = x1 + width;
3186   points[2].y = y1 - height;
3187   points[3].x = x1;
3188   points[3].y = y1 - height;
3189   points[4].x = x1;
3190   points[4].y = y1;
3191   cookie_line = xcb_poly_line_checked (c, XCB_COORD_MODE_ORIGIN,
3192                                        window, gc, 5, points);
3193
3194   error = xcb_request_check (c, cookie_line);
3195   if (error) {
3196     fprintf (stderr, "ERROR: can't draw lines : %d\n", error->error_code);
3197     xcb_disconnect (c);
3198     exit (-1);
3199   }
3200
3201   cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3202                                           x1 + inset + 1,
3203                                           y1 - inset - 1, label);
3204   error = xcb_request_check (c, cookie_text);
3205   if (error) {
3206     fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3207     xcb_disconnect (c);
3208     exit (-1);
3209   }
3210
3211   cookie_gc = xcb_free_gc (c, gc);
3212   error = xcb_request_check (c, cookie_gc);
3213   if (error) {
3214     fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3215     xcb_disconnect (c);
3216     exit (-1);
3217   }
3218 }
3219
3220 static void
3221 text_draw (xcb_connection_t *c,
3222            xcb_screen_t     *screen,
3223            xcb_window_t      window,
3224            int16_t           x1,
3225            int16_t           y1,
3226            const char       *label)
3227 {
3228   xcb_void_cookie_t    cookie_gc;
3229   xcb_void_cookie_t    cookie_text;
3230   xcb_generic_error_t *error;
3231   xcb_gcontext_t       gc;
3232   uint8_t              length;
3233
3234   length = strlen (label);
3235
3236   gc = gc_font_get(c, screen, window, "7x13");
3237
3238   cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3239                                           x1,
3240                                           y1, label);
3241   error = xcb_request_check (c, cookie_text);
3242   if (error) {
3243     fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3244     xcb_disconnect (c);
3245     exit (-1);
3246   }
3247
3248   cookie_gc = xcb_free_gc (c, gc);
3249   error = xcb_request_check (c, cookie_gc);
3250   if (error) {
3251     fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3252     xcb_disconnect (c);
3253     exit (-1);
3254   }
3255 }
3256
3257 static xcb_gc_t
3258 gc_font_get (xcb_connection_t *c,
3259              xcb_screen_t     *screen,
3260              xcb_window_t      window,
3261              const char       *font_name)
3262 {
3263   uint32_t             value_list[3];
3264   xcb_void_cookie_t    cookie_font;
3265   xcb_void_cookie_t    cookie_gc;
3266   xcb_generic_error_t *error;
3267   xcb_font_t           font;
3268   xcb_gcontext_t       gc;
3269   uint32_t             mask;
3270
3271   font = xcb_generate_id (c);
3272   cookie_font = xcb_open_font_checked (c, font,
3273                                        strlen (font_name),
3274                                        font_name);
3275
3276   error = xcb_request_check (c, cookie_font);
3277   if (error) {
3278     fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3279     xcb_disconnect (c);
3280     return -1;
3281   }
3282
3283   gc = xcb_generate_id (c);
3284   mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3285   value_list[0] = screen->black_pixel;
3286   value_list[1] = screen->white_pixel;
3287   value_list[2] = font;
3288   cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list);
3289   error = xcb_request_check (c, cookie_gc);
3290   if (error) {
3291     fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3292     xcb_disconnect (c);
3293     exit (-1);
3294   }
3295
3296   cookie_font = xcb_close_font_checked (c, font);
3297   error = xcb_request_check (c, cookie_font);
3298   if (error) {
3299     fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3300     xcb_disconnect (c);
3301     exit (-1);
3302   }
3303
3304   return gc;
3305 }
3306
3307 static void
3308 cursor_set (xcb_connection_t *c,
3309             xcb_screen_t     *screen,
3310             xcb_window_t      window,
3311             int               cursor_id)
3312 {
3313   uint32_t             values_list[3];
3314   xcb_void_cookie_t    cookie_font;
3315   xcb_void_cookie_t    cookie_gc;
3316   xcb_generic_error_t *error;
3317   xcb_font_t           font;
3318   xcb_cursor_t         cursor;
3319   xcb_gcontext_t       gc;
3320   uint32_t             mask;
3321   uint32_t             value_list;
3322
3323   font = xcb_generate_id (c);
3324   cookie_font = xcb_open_font_checked (c, font,
3325                                        strlen ("cursor"),
3326                                        "cursor");
3327   error = xcb_request_check (c, cookie_font);
3328   if (error) {
3329     fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3330     xcb_disconnect (c);
3331     exit (-1);
3332   }
3333
3334   cursor = xcb_generate_id (c);
3335   xcb_create_glyph_cursor (c, cursor, font, font,
3336                            cursor_id, cursor_id + 1,
3337                            0, 0, 0,
3338                            0, 0, 0);
3339
3340   gc = xcb_generate_id (c);
3341   mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3342   values_list[0] = screen->black_pixel;
3343   values_list[1] = screen->white_pixel;
3344   values_list[2] = font;
3345   cookie_gc = xcb_create_gc_checked (c, gc, window, mask, values_list);
3346   error = xcb_request_check (c, cookie_gc);
3347   if (error) {
3348     fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3349     xcb_disconnect (c);
3350     exit (-1);
3351   }
3352
3353   mask = XCB_CW_CURSOR;
3354   value_list = cursor;
3355   xcb_change_window_attributes (c, window, mask, &amp;value_list);
3356
3357   xcb_free_cursor (c, cursor);
3358
3359   cookie_font = xcb_close_font_checked (c, font);
3360   error = xcb_request_check (c, cookie_font);
3361   if (error) {
3362     fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3363     xcb_disconnect (c);
3364     exit (-1);
3365   }
3366 }
3367
3368 int main ()
3369 {
3370   xcb_screen_iterator_t screen_iter;
3371   xcb_connection_t     *c;
3372   const xcb_setup_t    *setup;
3373   xcb_screen_t         *screen;
3374   xcb_generic_event_t  *e;
3375   xcb_generic_error_t  *error;
3376   xcb_void_cookie_t     cookie_window;
3377   xcb_void_cookie_t     cookie_map;
3378   xcb_window_t          window;
3379   uint32_t              mask;
3380   uint32_t              values[2];
3381   int                   screen_number;
3382   uint8_t               is_hand = 0;
3383
3384   /* getting the connection */
3385   c = xcb_connect (NULL, &amp;screen_number);
3386   if (!c) {
3387     fprintf (stderr, "ERROR: can't connect to an X server\n");
3388     return -1;
3389   }
3390
3391   /* getting the current screen */
3392   setup = xcb_get_setup (c);
3393
3394   screen = NULL;
3395   screen_iter = xcb_setup_roots_iterator (setup);
3396   for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&amp;screen_iter))
3397     if (screen_number == 0)
3398       {
3399         screen = screen_iter.data;
3400         break;
3401       }
3402   if (!screen) {
3403     fprintf (stderr, "ERROR: can't get the current screen\n");
3404     xcb_disconnect (c);
3405     return -1;
3406   }
3407
3408   /* creating the window */
3409   window = xcb_generate_id (c);
3410   mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
3411   values[0] = screen->white_pixel;
3412   values[1] =
3413     XCB_EVENT_MASK_KEY_RELEASE |
3414     XCB_EVENT_MASK_BUTTON_PRESS |
3415     XCB_EVENT_MASK_EXPOSURE |
3416     XCB_EVENT_MASK_POINTER_MOTION;
3417   cookie_window = xcb_create_window_checked (c,
3418                                              screen->root_depth,
3419                                              window, screen->root,
3420                                              20, 200, WIDTH, HEIGHT,
3421                                              0, XCB_WINDOW_CLASS_INPUT_OUTPUT,
3422                                              screen->root_visual,
3423                                              mask, values);
3424   cookie_map = xcb_map_window_checked (c, window);
3425
3426   /* error managing */
3427   error = xcb_request_check (c, cookie_window);
3428   if (error) {
3429     fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code);
3430     xcb_disconnect (c);
3431     return -1;
3432   }
3433   error = xcb_request_check (c, cookie_map);
3434   if (error) {
3435     fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code);
3436     xcb_disconnect (c);
3437     return -1;
3438   }
3439
3440   cursor_set (c, screen, window, 68);
3441
3442   xcb_flush(c);
3443
3444   while (1) {
3445     e = xcb_poll_for_event(c);
3446     if (e) {
3447       switch (e->response_type) {
3448       case XCB_EXPOSE: {
3449         char *text;
3450
3451         text = "click here to change cursor";
3452         button_draw (c, screen, window,
3453                      (WIDTH - 7 * strlen(text)) / 2,
3454                      (HEIGHT - 16) / 2, text);
3455
3456         text = "Press ESC key to exit...";
3457         text_draw (c, screen, window, 10, HEIGHT - 10, text);
3458         break;
3459       }
3460       case XCB_BUTTON_PRESS: {
3461         xcb_button_press_event_t *ev;
3462         int                       length;
3463
3464         ev = (xcb_button_press_event_t *)e;
3465         length = strlen ("click here to change cursor");
3466
3467         if ((ev->event_x &gt;= (WIDTH - 7 * length) / 2) &amp;&amp;
3468             (ev->event_x &lt;= ((WIDTH - 7 * length) / 2 + 7 * length + 6)) &amp;&amp;
3469             (ev->event_y &gt;= (HEIGHT - 16) / 2 - 19) &amp;&amp;
3470             (ev->event_y &lt;= ((HEIGHT - 16) / 2)))
3471           is_hand = 1 - is_hand;
3472
3473         is_hand ? cursor_set (c, screen, window, 58) : cursor_set (c, screen, window, 68);
3474       }
3475       case XCB_KEY_RELEASE: {
3476         xcb_key_release_event_t *ev;
3477
3478         ev = (xcb_key_release_event_t *)e;
3479
3480         switch (ev->detail) {
3481           /* ESC */
3482         case 9:
3483           free (e);
3484           xcb_disconnect (c);
3485           return 0;
3486         }
3487       }
3488       }
3489       free (e);
3490     }
3491   }
3492
3493   return 0;
3494 }
3495 </pre>
3496       </ol>
3497       <li class="title"><a name="translation">Translation of basic Xlib functions and macros</a>
3498       <p>
3499       The problem when you want to port an Xlib program to XCB is that
3500       you don't know if the Xlib function that you want to "translate"
3501       is a X Window one or an Xlib macro. In that section, we describe
3502       a way to translate the usual functions or macros that Xlib
3503       provides. It's usually just a member of a structure.
3504       </p>
3505       <ol>
3506         <li class="subtitle"><a name="displaystructure">Members of the Display structure</a>
3507         <p>
3508         In this section, we look at how to translate the macros that
3509         return some members of the <span class="code">Display</span>
3510         structure. They are obtained by using a function that requires a
3511         <span class="code">xcb_connection_t *</span> or a member of the
3512         <span class="code">xcb_setup_t</span> structure
3513         (via the function <span class="code">xcb_get_setup</span>), or
3514         a function that requires that structure.
3515         </p>
3516         <ol>
3517           <li class="subtitle"><a name="ConnectionNumber">ConnectionNumber</a>
3518           <p>
3519           This number is the file descriptor that connects the client
3520           to the server. You just have to use that function:
3521           </p>
3522           <pre class="code">
3523 int xcb_get_file_descriptor (xcb_connection_t *c);
3524 </pre>
3525           <li class="subtitle"><a name="DefaultScreen"></a>DefaultScreen
3526           <p>
3527           That number is not stored by XCB. It is returned in the
3528           second parameter of the function <span class="code"><a href="#openconn">xcb_connect</a></span>.
3529           Hence, you have to store it yourself if you want to use
3530           it. Then, to get the <span class="code">xcb_screen_t</span>
3531           structure, you have to iterate on the screens.
3532           The equivalent function of the Xlib's
3533           <span class="code">ScreenOfDisplay</span> function can be
3534           found <a href="#ScreenOfDisplay">below</a>. This is also provided in the
3535           xcb_aux_t library as <span class="code">xcb_aux_get_screen()</span>. OK, here is the
3536           small piece of code to get that number:
3537           </p>
3538           <pre class="code">
3539 xcb_connection_t *c;
3540 int               screen_default_nbr;
3541
3542 /* you pass the name of the display you want to xcb_connect_t */
3543
3544 c = xcb_connect (display_name, &amp;screen_default_nbr);
3545
3546 /* screen_default_nbr contains now the number of the default screen */
3547 </pre>
3548           <li class="subtitle"><a name="QLength"></a>QLength
3549           <p>
3550           Not documented yet.
3551           </p>
3552           <p>
3553           However, this points out a basic difference in philosophy between
3554           Xlib and XCB.  Xlib has several functions for filtering and
3555           manipulating the incoming and outgoing X message queues.  XCB
3556           wishes to hide this as much as possible from the user, which
3557           allows for more freedom in implementation strategies.
3558           </p>
3559           <li class="subtitle"><a name="ScreenCount"></a>ScreenCount
3560           <p>
3561           You get the count of screens with the functions
3562           <span class="code">xcb_get_setup</span>
3563           and
3564           <span class="code">xcb_setup_roots_iterator</span>
3565           (if you need to iterate):
3566           </p>
3567           <pre class="code">
3568 xcb_connection_t *c;
3569 int               screen_count;
3570
3571 /* you init the connection */
3572
3573 screen_count = xcb_setup_roots_iterator (xcb_get_setup (c)).rem;
3574
3575 /* screen_count contains now the count of screens */
3576 </pre>
3577           <p>
3578           If you don't want to iterate over the screens, a better way
3579           to get that number is to use
3580           <span class="code">xcb_setup_roots_length_t</span>:
3581           </p>
3582           <pre class="code">
3583 xcb_connection_t *c;
3584 int               screen_count;
3585
3586 /* you init the connection */
3587
3588 screen_count = xcb_setup_roots_length (xcb_get_setup (c));
3589
3590 /* screen_count contains now the count of screens */
3591 </pre>
3592           <li class="subtitle"><a name="ServerVendor"></a>ServerVendor
3593           <p>
3594           You get the name of the vendor of the server hardware with
3595           the functions <span class="code">xcb_get_setup</span>
3596           and
3597           <span
3598           class="code">xcb_setup_vendor</span>. Beware
3599           that, unlike Xlib, the string returned by XCB is not
3600           necessarily null-terminaled:
3601           </p>
3602           <pre class="code">
3603 xcb_connection_t *c;
3604 char             *vendor = NULL;
3605 int               length;
3606
3607 /* you init the connection */
3608 length = xcb_setup_vendor_length (xcb_get_setup (c));
3609 vendor = (char *)malloc (length + 1);
3610 if (vendor)
3611 memcpy (vendor, xcb_setup_vendor (xcb_get_setup (c)), length);
3612 vendor[length] = '\0';
3613
3614 /* vendor contains now the name of the vendor. Must be freed when not used anymore */
3615 </pre>
3616           <li class="subtitle"><a name="ProtocolVersion"></a>ProtocolVersion
3617           <p>
3618           You get the major version of the protocol in the
3619           <span class="code">xcb_setup_t</span>
3620           structure, with the function <span class="code">xcb_get_setup</span>:
3621           </p>
3622           <pre class="code">
3623 xcb_connection_t *c;
3624 uint16_t          protocol_major_version;
3625
3626 /* you init the connection */
3627
3628 protocol_major_version = xcb_get_setup (c)-&gt;protocol_major_version;
3629
3630 /* protocol_major_version contains now the major version of the protocol */
3631 </pre>
3632           <li class="subtitle"><a name="ProtocolRevision"></a>ProtocolRevision
3633           <p>
3634           You get the minor version of the protocol in the
3635           <span class="code">xcb_setup_t</span>
3636           structure, with the function <span class="code">xcb_get_setup</span>:
3637           </p>
3638           <pre class="code">
3639 xcb_connection_t *c;
3640 uint16_t          protocol_minor_version;
3641
3642 /* you init the connection */
3643
3644 protocol_minor_version = xcb_get_setup (c)-&gt;protocol_minor_version;
3645
3646 /* protocol_minor_version contains now the minor version of the protocol */
3647 </pre>
3648           <li class="subtitle"><a name="VendorRelease"></a>VendorRelease
3649           <p>
3650           You get the number of the release of the server hardware in the
3651           <span class="code">xcb_setup_t</span>
3652           structure, with the function <span class="code">xcb_get_setup</span>:
3653           </p>
3654           <pre class="code">
3655 xcb_connection_t *c;
3656 uint32_t          release_number;
3657
3658 /* you init the connection */
3659
3660 release_number = xcb_get_setup (c)-&gt;release_number;
3661
3662 /* release_number contains now the number of the release of the server hardware */
3663 </pre>
3664           <li class="subtitle"><a name="DisplayString"></a>DisplayString
3665           <p>
3666           The name of the display is not stored in XCB. You have to
3667           store it by yourself.
3668           </p>
3669           <li class="subtitle"><a name="BitmapUnit"></a>BitmapUnit
3670           <p>
3671           You get the bitmap scanline unit in the
3672           <span class="code">xcb_setup_t</span>
3673           structure, with the function <span class="code">xcb_get_setup</span>:
3674           </p>
3675           <pre class="code">
3676 xcb_connection_t *c;
3677 uint8_t           bitmap_format_scanline_unit;
3678
3679 /* you init the connection */
3680
3681 bitmap_format_scanline_unit = xcb_get_setup (c)-&gt;bitmap_format_scanline_unit;
3682
3683 /* bitmap_format_scanline_unit contains now the bitmap scanline unit */
3684 </pre>
3685           <li class="subtitle"><a name="BitmapBitOrder"></a>BitmapBitOrder
3686           <p>
3687           You get the bitmap bit order in the
3688           <span class="code">xcb_setup_t</span>
3689           structure, with the function <span class="code">xcb_get_setup</span>:
3690           </p>
3691           <pre class="code">
3692 xcb_connection_t *c;
3693 uint8_t           bitmap_format_bit_order;
3694
3695 /* you init the connection */
3696
3697 bitmap_format_bit_order = xcb_get_setup (c)-&gt;bitmap_format_bit_order;
3698
3699 /* bitmap_format_bit_order contains now the bitmap bit order */
3700 </pre>
3701           <li class="subtitle"><a name="BitmapPad"></a>BitmapPad
3702           <p>
3703           You get the bitmap scanline pad in the
3704           <span class="code">xcb_setup_t</span>
3705           structure, with the function <span class="code">xcb_get_setup</span>:
3706           </p>
3707           <pre class="code">
3708 xcb_connection_t *c;
3709 uint8_t           bitmap_format_scanline_pad;
3710
3711 /* you init the connection */
3712
3713 bitmap_format_scanline_pad = xcb_get_setup (c)-&gt;bitmap_format_scanline_pad;
3714
3715 /* bitmap_format_scanline_pad contains now the bitmap scanline pad */
3716 </pre>
3717           <li class="subtitle"><a name="ImageByteOrder"></a>ImageByteOrder
3718           <p>
3719           You get the image byte order in the
3720           <span class="code">xcb_setup_t</span>
3721           structure, with the function <span class="code">xcb_get_setup</span>:
3722           </p>
3723           <pre class="code">
3724 xcb_connection_t *c;
3725 uint8_t           image_byte_order;
3726
3727 /* you init the connection */
3728
3729 image_byte_order = xcb_get_setup (c)-&gt;image_byte_order;
3730
3731 /* image_byte_order contains now the image byte order */
3732 </pre>
3733         </ol>
3734       <li class="subtitle"><a name="screenofdisplay">ScreenOfDisplay related functions</a>
3735       <p>
3736       in Xlib, <span class="code">ScreenOfDisplay</span> returns a
3737       <span class="code">Screen</span> structure that contains
3738       several characteristics of your screen. XCB has a similar
3739       structure (<span class="code">xcb_screen_t</span>),
3740       but the way to obtain it is a bit different. With
3741       Xlib, you just provide the number of the screen and you grab it
3742       from an array. With XCB, you iterate over all the screens to
3743       obtain the one you want. The complexity of this operation is
3744       O(n). So the best is to store this structure if you use
3745       it often. See <a href="#ScreenOfDisplay">screen_of_display</a> just below.
3746       </p>
3747       <p>
3748       Xlib provides generally two functions to obtain the characteristics
3749       related to the screen. One with the display and the number of
3750       the screen, which calls <span class="code">ScreenOfDisplay</span>,
3751       and the other that uses the <span class="code">Screen</span> structure.
3752       This might be a bit confusing. As mentioned above, with XCB, it
3753       is better to store the <span class="code">xcb_screen_t</span>
3754       structure. Then, you have to read the members of this
3755       structure. That's why the Xlib functions are put by pairs (or
3756       more) as, with XCB, you will use the same code.
3757       </p>
3758         <ol>
3759           <li class="subtitle"><a name="ScreenOfDisplay">ScreenOfDisplay</a>
3760           <p>
3761           This function returns the Xlib <span class="code">Screen</span>
3762           structure. With XCB, you iterate over all the screens and
3763           once you get the one you want, you return it:
3764           </p>
3765           <pre class="code"><a name="ScreenOfDisplay"></a>
3766 xcb_screen_t *screen_of_display (xcb_connection_t *c,
3767                                  int               screen)
3768 {
3769   xcb_screen_iterator_t iter;
3770
3771   iter = xcb_setup_roots_iterator (xcb_get_setup (c));
3772   for (; iter.rem; --screen, xcb_screen_next (&amp;iter))
3773     if (screen == 0)
3774       return iter.data;
3775
3776   return NULL;
3777 }
3778 </pre>
3779           <p>
3780           As mentioned above, you might want to store the value
3781           returned by this function.
3782           </p>
3783           <p>
3784           All the functions below will use the result of that
3785           function, as they just grab a specific member of the
3786           <span class="code">xcb_screen_t</span> structure.
3787           </p>
3788           <li class="subtitle"><a name="DefaultScreenOfDisplay"></a>DefaultScreenOfDisplay
3789           <p>
3790           It is the default screen that you obtain when you connect to
3791           the X server. It suffices to call the <a href="#ScreenOfDisplay">screen_of_display</a>
3792           function above with the connection and the number of the
3793           default screen.
3794           </p>
3795           <pre class="code">
3796 xcb_connection_t *c;
3797 int               screen_default_nbr;
3798 xcb_screen_t     *default_screen;  /* the returned default screen */
3799
3800 /* you pass the name of the display you want to xcb_connect_t */
3801
3802 c = xcb_connect (display_name, &amp;screen_default_nbr);
3803 default_screen = screen_of_display (c, screen_default_nbr);
3804
3805 /* default_screen contains now the default root window, or a NULL window if no screen is found */
3806 </pre>
3807           <li class="subtitle"><a name="RootWindow">RootWindow / RootWindowOfScreen</a>
3808           <br>
3809           <pre class="code">
3810 xcb_connection_t *c;
3811 xcb_screen_t     *screen;
3812 int               screen_nbr;
3813 xcb_window_t      root_window = { 0 };  /* the returned window */
3814
3815 /* you init the connection and screen_nbr */
3816
3817 screen = screen_of_display (c, screen_nbr);
3818 if (screen)
3819   root_window = screen-&gt;root;
3820
3821 /* root_window contains now the root window, or a NULL window if no screen is found */
3822 </pre>
3823           <li class="subtitle"><a name="DefaultRootWindow">DefaultRootWindow</a>
3824           <p>
3825           It is the root window of the default screen. So, you call
3826           <a name="ScreenOfDisplay">ScreenOfDisplay</a> with the
3827           default screen number and you get the
3828           <a href="#RootWindow">root window</a> as above:
3829           </p>
3830           <pre class="code">
3831 xcb_connection_t *c;
3832 xcb_screen_t     *screen;
3833 int               screen_default_nbr;
3834 xcb_window_t      root_window = { 0 };  /* the returned root window */
3835
3836 /* you pass the name of the display you want to xcb_connect_t */
3837
3838 c = xcb_connect (display_name, &amp;screen_default_nbr);
3839 screen = screen_of_display (c, screen_default_nbr);
3840 if (screen)
3841   root_window = screen-&gt;root;
3842
3843 /* root_window contains now the default root window, or a NULL window if no screen is found */
3844 </pre>
3845           <li class="subtitle"><a name="DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
3846           <p>
3847           While a Visual is, in Xlib, a structure, in XCB, there are
3848           two types: <span class="code">xcb_visualid_t</span>, which is
3849           the Id of the visual, and <span class="code">xcb_visualtype_t</span>,
3850           which corresponds to the Xlib Visual. To get the Id of the
3851           visual of a screen, just get the
3852            <span class="code">root_visual</span>
3853            member of a <span class="code">xcb_screen_t</span>:
3854           </p>
3855           <pre class="code">
3856 xcb_connection_t *c;
3857 xcb_screen_t     *screen;
3858 int               screen_nbr;
3859 xcb_visualid_t    root_visual = { 0 };    /* the returned visual Id */
3860
3861 /* you init the connection and screen_nbr */
3862
3863 screen = screen_of_display (c, screen_nbr);
3864 if (screen)
3865   root_visual = screen-&gt;root_visual;
3866
3867 /* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
3868 </pre>
3869           <p>
3870           To get the <span class="code">xcb_visualtype_t</span>
3871           structure, it's a bit less easy. You have to get the
3872           <span class="code">xcb_screen_t</span> structure that you want,
3873           get its <span class="code">root_visual</span> member,
3874           then iterate over the <span class="code">xcb_depth_t</span>s
3875           and the <span class="code">xcb_visualtype_t</span>s, and compare
3876           the <span class="code">xcb_visualid_t</span> of these <span class="code">xcb_visualtype_t</span>s:
3877           with <span class="code">root_visual</span>:
3878           </p>
3879           <pre class="code">
3880 xcb_connection_t *c;
3881 xcb_screen_t     *screen;
3882 int               screen_nbr;
3883 xcb_visualid_t    root_visual = { 0 };
3884 xcb_visualtype_t  *visual_type = NULL;    /* the returned visual type */
3885
3886 /* you init the connection and screen_nbr */
3887
3888 screen = screen_of_display (c, screen_nbr);
3889 if (screen) {
3890   xcb_depth_iterator_t depth_iter;
3891
3892   depth_iter = xcb_screen_allowed_depths_iterator (screen);
3893   for (; depth_iter.rem; xcb_depth_next (&amp;depth_iter)) {
3894     xcb_visualtype_iterator_t visual_iter;
3895
3896     visual_iter = xcb_depth_visuals_iterator (depth_iter.data);
3897     for (; visual_iter.rem; xcb_visualtype_next (&amp;visual_iter)) {
3898       if (screen-&gt;root_visual == visual_iter.data-&gt;visual_id) {
3899         visual_type = visual_iter.data;
3900         break;
3901       }
3902     }
3903   }
3904 }
3905
3906 /* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */
3907 </pre>
3908           <li class="subtitle"><a name="DefaultGC">DefaultGC / DefaultGCOfScreen</a>
3909           <p>
3910           This default Graphic Context is just a newly created Graphic
3911           Context, associated to the root window of a
3912           <span class="code">xcb_screen_t</span>,
3913           using the black white pixels of that screen:
3914           </p>
3915           <pre class="code">
3916 xcb_connection_t *c;
3917 xcb_screen_t     *screen;
3918 int               screen_nbr;
3919 xcb_gcontext_t    gc = { 0 };    /* the returned default graphic context */
3920
3921 /* you init the connection and screen_nbr */
3922
3923 screen = screen_of_display (c, screen_nbr);
3924 if (screen) {
3925   xcb_drawable_t draw;
3926   uint32_t       mask;
3927   uint32_t       values[2];
3928
3929   gc = xcb_generate_id (c);
3930   draw = screen-&gt;root;
3931   mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND;
3932   values[0] = screen-&gt;black_pixel;
3933   values[1] = screen-&gt;white_pixel;
3934   xcb_create_gc (c, gc, draw, mask, values);
3935 }
3936
3937 /* gc contains now the default graphic context */
3938 </pre>
3939           <li class="subtitle"><a name="BlackPixel">BlackPixel / BlackPixelOfScreen</a>
3940           <p>
3941           It is the Id of the black pixel, which is in the structure
3942           of an <span class="code">xcb_screen_t</span>.
3943           </p>
3944           <pre class="code">
3945 xcb_connection_t *c;
3946 xcb_screen_t     *screen;
3947 int               screen_nbr;
3948 uint32_t          black_pixel = 0;    /* the returned black pixel */
3949
3950 /* you init the connection and screen_nbr */
3951
3952 screen = screen_of_display (c, screen_nbr);
3953 if (screen)
3954   black_pixel = screen-&gt;black_pixel;
3955
3956 /* black_pixel contains now the value of the black pixel, or 0 if no screen is found */
3957 </pre>
3958           <li class="subtitle"><a name="WhitePixel">WhitePixel / WhitePixelOfScreen</a>
3959           <p>
3960           It is the Id of the white pixel, which is in the structure
3961           of an <span class="code">xcb_screen_t</span>.
3962           </p>
3963           <pre class="code">
3964 xcb_connection_t *c;
3965 xcb_screen_t     *screen;
3966 int               screen_nbr;
3967 uint32_t          white_pixel = 0;    /* the returned white pixel */
3968
3969 /* you init the connection and screen_nbr */
3970
3971 screen = screen_of_display (c, screen_nbr);
3972 if (screen)
3973   white_pixel = screen-&gt;white_pixel;
3974
3975 /* white_pixel contains now the value of the white pixel, or 0 if no screen is found */
3976 </pre>
3977           <li class="subtitle"><a name="DisplayWidth">DisplayWidth / WidthOfScreen</a>
3978           <p>
3979           It is the width in pixels of the screen that you want, and
3980           which is in the structure of the corresponding
3981           <span class="code">xcb_screen_t</span>.
3982           </p>
3983           <pre class="code">
3984 xcb_connection_t *c;
3985 xcb_screen_t     *screen;
3986 int               screen_nbr;
3987 uint32_t          width_in_pixels = 0;    /* the returned width in pixels */
3988
3989 /* you init the connection and screen_nbr */
3990
3991 screen = screen_of_display (c, screen_nbr);
3992 if (screen)
3993   width_in_pixels = screen-&gt;width_in_pixels;
3994
3995 /* width_in_pixels contains now the width in pixels, or 0 if no screen is found */
3996 </pre>
3997           <li class="subtitle"><a name="DisplayHeight">DisplayHeight / HeightOfScreen</a>
3998           <p>
3999           It is the height in pixels of the screen that you want, and
4000           which is in the structure of the corresponding
4001           <span class="code">xcb_screen_t</span>.
4002           </p>
4003           <pre class="code">
4004 xcb_connection_t *c;
4005 xcb_screen_t     *screen;
4006 int               screen_nbr;
4007 uint32_t          height_in_pixels = 0;    /* the returned height in pixels */
4008
4009 /* you init the connection and screen_nbr */
4010
4011 screen = screen_of_display (c, screen_nbr);
4012 if (screen)
4013   height_in_pixels = screen-&gt;height_in_pixels;
4014
4015 /* height_in_pixels contains now the height in pixels, or 0 if no screen is found */
4016 </pre>
4017           <li class="subtitle"><a name="DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
4018           <p>
4019           It is the width in millimeters of the screen that you want, and
4020           which is in the structure of the corresponding
4021           <span class="code">xcb_screen_t</span>.
4022           </p>
4023           <pre class="code">
4024 xcb_connection_t *c;
4025 xcb_screen_t     *screen;
4026 int               screen_nbr;
4027 uint32_t          width_in_millimeters = 0;    /* the returned width in millimeters */
4028
4029 /* you init the connection and screen_nbr */
4030
4031 screen = screen_of_display (c, screen_nbr);
4032 if (screen)
4033   width_in_millimeters = screen-&gt;width_in_millimeters;
4034
4035 /* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */
4036 </pre>
4037           <li class="subtitle"><a name="DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
4038           <p>
4039           It is the height in millimeters of the screen that you want, and
4040           which is in the structure of the corresponding
4041           <span class="code">xcb_screen_t</span>.
4042           </p>
4043           <pre class="code">
4044 xcb_connection_t *c;
4045 xcb_screen_t     *screen;
4046 int               screen_nbr;
4047 uint32_t          height_in_millimeters = 0;    /* the returned height in millimeters */
4048
4049 /* you init the connection and screen_nbr */
4050
4051 screen = screen_of_display (c, screen_nbr);
4052 if (screen)
4053   height_in_millimeters = screen-&gt;height_in_millimeters;
4054
4055 /* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */
4056 </pre>
4057           <li class="subtitle"><a name="DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
4058           <p>
4059           It is the depth (in bits) of the root window of the
4060           screen. You get it from the <span class="code">xcb_screen_t</span> structure.
4061           </p>
4062           <pre class="code">
4063 xcb_connection_t *c;
4064 xcb_screen_t     *screen;
4065 int               screen_nbr;
4066 uint8_t           root_depth = 0;  /* the returned depth of the root window */
4067
4068 /* you init the connection and screen_nbr */
4069
4070 screen = screen_of_display (c, screen_nbr);
4071 if (screen)
4072   root_depth = screen-&gt;root_depth;
4073
4074 /* root_depth contains now the depth of the root window, or 0 if no screen is found */
4075 </pre>
4076           <li class="subtitle"><a name="DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
4077           <p>
4078           This is the default colormap of the screen (and not the
4079           (default) colormap of the default screen !). As usual, you
4080           get it from the <span class="code">xcb_screen_t</span> structure:
4081           </p>
4082           <pre class="code">
4083 xcb_connection_t *c;
4084 xcb_screen_t     *screen;
4085 int               screen_nbr;
4086 xcb_colormap_t    default_colormap = { 0 };  /* the returned default colormap */
4087
4088 /* you init the connection and screen_nbr */
4089
4090 screen = screen_of_display (c, screen_nbr);
4091 if (screen)
4092   default_colormap = screen-&gt;default_colormap;
4093
4094 /* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */
4095 </pre>
4096           <li class="subtitle"><a name="MinCmapsOfScreen"></a>MinCmapsOfScreen
4097           <p>
4098           You get the minimum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4099           </p>
4100           <pre class="code">
4101 xcb_connection_t *c;
4102 xcb_screen_t     *screen;
4103 int               screen_nbr;
4104 uint16_t          min_installed_maps = 0;  /* the returned minimum installed colormaps */
4105
4106 /* you init the connection and screen_nbr */
4107
4108 screen = screen_of_display (c, screen_nbr);
4109 if (screen)
4110   min_installed_maps = screen-&gt;min_installed_maps;
4111
4112 /* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */
4113 </pre>
4114           <li class="subtitle"><a name="MaxCmapsOfScreen"></a>MaxCmapsOfScreen
4115           <p>
4116           You get the maximum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4117           </p>
4118           <pre class="code">
4119 xcb_connection_t *c;
4120 xcb_screen_t     *screen;
4121 int               screen_nbr;
4122 uint16_t          max_installed_maps = 0;  /* the returned maximum installed colormaps */
4123
4124 /* you init the connection and screen_nbr */
4125
4126 screen = screen_of_display (c, screen_nbr);
4127 if (screen)
4128   max_installed_maps = screen-&gt;max_installed_maps;
4129
4130 /* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */
4131 </pre>
4132           <li class="subtitle"><a name="DoesSaveUnders"></a>DoesSaveUnders
4133           <p>
4134           You know if <span class="code">save_unders</span> is set,
4135           by looking in the <span class="code">xcb_screen_t</span> structure:
4136           </p>
4137           <pre class="code">
4138 xcb_connection_t *c;
4139 xcb_screen_t     *screen;
4140 int               screen_nbr;
4141 uint8_t           save_unders = 0;  /* the returned value of save_unders */
4142
4143 /* you init the connection and screen_nbr */
4144
4145 screen = screen_of_display (c, screen_nbr);
4146 if (screen)
4147   save_unders = screen-&gt;save_unders;
4148
4149 /* save_unders contains now the value of save_unders, or FALSE if no screen is found */
4150 </pre>
4151           <li class="subtitle"><a name="DoesBackingStore"></a>DoesBackingStore
4152           <p>
4153           You know the value of <span class="code">backing_stores</span>,
4154           by looking in the <span class="code">xcb_screen_t</span> structure:
4155           </p>
4156           <pre class="code">
4157 xcb_connection_t *c;
4158 xcb_screen_t     *screen;
4159 int               screen_nbr;
4160 uint8_t           backing_stores = 0;  /* the returned value of backing_stores */
4161
4162 /* you init the connection and screen_nbr */
4163
4164 screen = screen_of_display (c, screen_nbr);
4165 if (screen)
4166   backing_stores = screen-&gt;backing_stores;
4167
4168 /* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */
4169 </pre>
4170           <li class="subtitle"><a name="EventMaskOfScreen"></a>EventMaskOfScreen
4171           <p>
4172           To get the current input masks,
4173           you look in the <span class="code">xcb_screen_t</span> structure:
4174           </p>
4175           <pre class="code">
4176 xcb_connection_t *c;
4177 xcb_screen_t     *screen;
4178 int               screen_nbr;
4179 uint32_t          current_input_masks = 0;  /* the returned value of current input masks */
4180
4181 /* you init the connection and screen_nbr */
4182
4183 screen = screen_of_display (c, screen_nbr);
4184 if (screen)
4185   current_input_masks = screen-&gt;current_input_masks;
4186
4187 /* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
4188 </pre>
4189         </ol>
4190       <li class="subtitle"><a name="misc">Miscellaneous macros</a>
4191         <ol>
4192           <li class="subtitle"><a name="DisplayOfScreen"></a>DisplayOfScreen
4193           <p>
4194           in Xlib, the <span class="code">Screen</span> structure
4195           stores its associated <span class="code">Display</span>
4196           structure. This is not the case in the X Window protocol,
4197           hence, it's also not the case in XCB. So you have to store
4198           it by yourself.
4199           </p>
4200           <li class="subtitle"><a name="DisplayCells"></a>DisplayCells / CellsOfScreen
4201           <p>
4202           To get the colormap entries,
4203           you look in the <span class="code">xcb_visualtype_t</span>
4204           structure, that you grab like <a class="subsection" href="#DefaultVisual">here</a>:
4205           </p>
4206           <pre class="code">
4207 xcb_connection_t *c;
4208 xcb_visualtype_t *visual_type;
4209 uint16_t          colormap_entries = 0;  /* the returned value of the colormap entries */
4210
4211 /* you init the connection and visual_type */
4212
4213 if (visual_type)
4214   colormap_entries = visual_type-&gt;colormap_entries;
4215
4216 /* colormap_entries contains now the value of the colormap entries, or FALSE if no screen is found */
4217 </pre>
4218         </ol>
4219       </ol>
4220     </ol>
4221   </div>
4222 </body>
4223
4224 </html>