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;X11/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 <type>xcb_connection_t</type> *xcb_connect (<keyword>const</keyword> <type>char</type> *displayname,
 591                                <type>int</type>        *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 #<include>include</include> <string>&lt;X11/XCB/xcb.h&gt;</string>
 600
 601 <type>int</type>
 602 <function>main</function> ()
 603 {
 604   <type>xcb_connection_t</type> *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   <keyword>return</keyword> 0;
 610 }
 611 </pre>
 612       <p>
 613       To close a connection, it suffices to use:
 614       </p>
 615       <pre class="code">
 616 <type>void</type> xcb_disconnect (<type>xcb_connection_t</type> *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       <p>
 644       </p>
 645       <li class="title"><a name="screen">Checking basic information about a connection</a>
 646       <p>
 647       Once we have opened a connection to an X server, we should check some
 648       basic information about it: what screens it has, what is the
 649       size (width and height) of the screen, how many colors it
 650       supports (black and white ? grey scale ?, 256 colors ? more ?),
 651       and so on. We get such information from the xcb_screen_t
 652       structure:
 653       </p>
 654       <pre class="code">
 655 typedef struct {
 656     xcb_window_t   root;
 657     xcb_colormap_t default_colormap;
 658     uint32_t       white_pixel;
 659     uint32_t       black_pixel;
 660     uint32_t       current_input_masks;
 661     uint16_t       width_in_pixels;
 662     uint16_t       height_in_pixels;
 663     uint16_t       width_in_millimeters;
 664     uint16_t       height_in_millimeters;
 665     uint16_t       min_installed_maps;
 666     uint16_t       max_installed_maps;
 667     xcb_visualid_t root_visual;
 668     uint8_t        backing_stores;
 669     uint8_t        save_unders;
 670     uint8_t        root_depth;
 671     uint8_t        allowed_depths_len;
 672 } xcb_screen_t;
 673 </pre>
 674       <p>
 675       We could retrieve the first screen of the connection by using the
 676       following function:
 677       </p>
 678       <pre class="code">
 679 xcb_screen_iterator_t xcb_setup_roots_iterator (xcb_setup_t *R);
 680 </pre>
 681       <p>
 682       Here is a small program that shows how to use this function:
 683       </p>
 684       <pre class="code">
 685 #include &lt;stdio.h&gt;
 686
 687 #include &lt;X11/XCB/xcb.h&gt;
 688
 689 int
 690 main (int argc, char *argv[])
 691 {
 692   xcb_connection_t     *c;
 693   xcb_screen_t         *screen;
 694   int                   screen_nbr;
 695   xcb_screen_iterator_t iter;
 696
 697   /* Open the connection to the X server. Use the DISPLAY environment variable */
 698   c = xcb_connect (NULL, &amp;screen_nbr);
 699
 700   /* Get the screen #screen_nbr */
 701   iter = xcb_setup_roots_iterator (xcb_get_setup (c));
 702   for (; iter.rem; --screen_nbr, xcb_screen_next (&amp;iter))
 703     if (screen_nbr == 0) {
 704       screen = iter.data;
 705       break;
 706     }
 707
 708   printf ("\n");
 709   printf ("Informations of screen %ld:\n", screen-&gt;root.xid);
 710   printf ("  width.........: %d\n", screen-&gt;width_in_pixels);
 711   printf ("  height........: %d\n", screen-&gt;height_in_pixels);
 712   printf ("  white pixel...: %ld\n", screen-&gt;white_pixel);
 713   printf ("  black pixel...: %ld\n", screen-&gt;black_pixel);
 714   printf ("\n");
 715
 716   return 0;
 717 }
 718 </pre>
 719       <li class="title"><a name="helloworld">Creating a basic window - the "hello world" program</a>
 720       <p>
 721       After we got some basic information about our screen, we can
 722       create our first window. In the X Window System, a window is
 723       characterized by an Id. So, in XCB, a window is of type:
 724       </p>
 725       <pre class="code">
 726 typedef struct {
 727     uint32_t xid;
 728 } xcb_window_t;
 729 </pre>
 730       <p>
 731       We first ask for a new Id for our window, with this function:
 732       </p>
 733       <pre class="code">
 734 xcb_window_t xcb_window_new(xcb_connection_t *c);
 735 </pre>
 736       <p>
 737       Then, XCB supplies the following function to create new windows:
 738       </p>
 739       <pre class="code">
 740 xcb_void_cookie_t xcb_create_window (xcb_connection_t *c,             /* Pointer to the xcb_connection_t structure */
 741                                      uint8_t           depth,         /* Depth of the screen */
 742                                      xcb_window_t      wid,           /* Id of the window */
 743                                      xcb_window_t      parent,        /* Id of an existing window that should be the parent of the new window */
 744                                      int16_t           x,             /* X position of the top-left corner of the window (in pixels) */
 745                                      int16_t           y,             /* Y position of the top-left corner of the window (in pixels) */
 746                                      uint16_t          width,         /* Width of the window (in pixels) */
 747                                      uint16_t          height,        /* Height of the window (in pixels) */
 748                                      uint16_t          border_width,  /* Width of the window's border (in pixels) */
 749                                      uint16_t          _class,
 750                                      xcb_visualid_t     visual,
 751                                      uint32_t          value_mask,
 752                                      const uint32_t   *value_list);
 753 </pre>
 754       <p>
 755       The fact that we created the window does not mean that it will
 756       be drawn on screen. By default, newly created windows are not
 757       mapped on the screen (they are invisible). In order to make our
 758       window visible, we use the function <span class="code">xcb_map_window()</span>, whose
 759       prototype is
 760       </p>
 761       <pre class="code">
 762 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
 763                                   xcb_window_t      window);
 764 </pre>
 765       <p>
 766       Finally, here is a small program to create a window of size
 767       150x150 pixels, positioned at the top-left corner of the screen:
 768       </p>
 769       <pre class="code">
 770 #include &lt;unistd.h&gt;      /* pause() */
 771
 772 #include &lt;X11/XCB/xcb.h&gt;
 773
 774 int
 775 main (int argc, char *argv[])
 776 {
 777   xcb_connection_t *c;
 778   xcb_screen_t     *screen;
 779   xcb_drawable_t    win;
 780
 781   /* Open the connection to the X server */
 782   c = xcb_connect (NULL, NULL);
 783
 784   /* Get the first screen */
 785   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
 786
 787   /* Ask for our window's Id */
 788   win.window = xcb_window_new(c);
 789
 790   /* Create the window */
 791   xcb_create_window (c,                             /* Connection          */
 792                      XCB_COPY_FROM_PARENT,          /* depth (same as root)*/
 793                      win.window,                    /* window Id           */
 794                      screen-&gt;root,                  /* parent window       */
 795                      0, 0,                          /* x, y                */
 796                      150, 150,                      /* width, height       */
 797                      10,                            /* border_width        */
 798                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
 799                      screen-&gt;root_visual,           /* visual              */
 800                      0, NULL);                      /* masks, not used yet */
 801
 802   /* Map the window on the screen */
 803   xcb_map_window (c, win.window);
 804
 805   /* Make sure commands are sent before we pause, so window is shown */
 806   xcb_flush (c);
 807
 808   pause ();    /* hold client until Ctrl-C */
 809
 810   return 0;
 811 }
 812 </pre>
 813       <p>
 814       In this code, you see one more function - <span class="code">xcb_flush()</span>, not explained
 815       yet. It is used to flush all the pending requests. More
 816       precisely, there are 2 functions that do such things. The first
 817       one is <span class="code">xcb_flush()</span>:
 818       </p>
 819       <pre class="code">
 820 int xcb_flush (xcb_connection_t *c);
 821 </pre>
 822       <p>
 823       This function flushes all pending requests to the X server (much
 824       like the <span class="code">fflush()</span> function is used to
 825       flush standard output). The second function is
 826       <span class="code">xcb_sync()</span>:
 827       </p>
 828       <pre class="code">
 829 int xcb_aux_sync (xcb_connection_t *c);
 830 </pre>
 831       <p>
 832       This functions also flushes all pending requests to the X
 833       server, and then waits until the X server finishing processing
 834       these requests. In a normal program, this will not be necessary
 835       (we'll see why when we get to write a normal X program), but for
 836       now, we put it there.
 837       </p>
 838       <p>
 839       The window that is created by the above code has a default
 840       background (gray). This one can be set to a specific color,
 841       thanks to the two last parameters of
 842       <span class="code">xcb_create_window()</span>, which are not
 843       described yet. See the subsections
 844       <a href="#winconf">Configuring a window</a> or
 845       <a href="#winconf">Registering for event types using event masks</a>
 846       for examples on how to use these parameters. In addition, as no
 847       events are handled, you have to make a Ctrl-C to interrupt the
 848       program.
 849       </p>
 850       <p>
 851       <b>TODO</b>: one should tell what these functions return and
 852       about the generic error
 853       </p>
 854       <div class="comp">
 855         <div class="title">
 856         Comparison Xlib/XCB
 857         </div>
 858         <div class="xlib">
 859         <ul>
 860           <li>XCreateWindow ()
 861         </ul>
 862         </div>
 863         <div class="xcb">
 864         <ul>
 865           <li>xcb_window_new ()
 866           <li>xcb_create_window ()
 867         </ul>
 868         </div>
 869       </div>
 870       <br>
 871       <li class="title"><a name="drawing">Drawing in a window</a>
 872       <p>
 873       Drawing in a window can be done using various graphical
 874       functions (drawing pixels, lines, rectangles, etc). In order to
 875       draw in a window, we first need to define various general
 876       drawing parameters (what line width to use, which color to draw
 877       with, etc). This is done using a graphical context.
 878       </p>
 879       <ol>
 880         <li class="subtitle"><a name="allocgc">Allocating a Graphics Context</a>
 881         <p>
 882         As we said, a graphical context defines several attributes to
 883         be used with the various drawing functions. For this, we
 884         define a graphical context. We can use more than one graphical
 885         context with a single window, in order to draw in multiple
 886         styles (different colors, different line widths, etc). In XCB,
 887         a Graphics Context is, as a window, characterized by an Id:
 888         </p>
 889         <pre class="code">
 890 typedef struct {
 891     uint32_t xid;
 892 } xcb_gcontext_t;
 893 </pre>
 894         <p>
 895         We first ask the X server to attribute an Id to our graphic
 896         context with this function:
 897         </p>
 898         <pre class="code">
 899 xcb_gcontext_t xcb_gcontext_new (xcb_connection_t *c);
 900 </pre>
 901         <p>
 902         Then, we set the attributes of the graphic context with this function:
 903         </p>
 904         <pre class="code">
 905 xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c,
 906                                  xcb_gcontext_t    cid,
 907                                  xcb_drawable_t    drawable,
 908                                  uint32_t          value_mask,
 909                                  const uint32_t   *value_list);
 910 </pre>
 911         <p>
 912         We give now an example on how to allocate a graphic context
 913         that specifies that each drawing function that uses it will
 914         draw in foreground with a black color.
 915         </p>
 916         <pre class="code">
 917 #include &lt;X11/XCB/xcb.h&gt;
 918
 919 int
 920 main (int argc, char *argv[])
 921 {
 922   xcb_connection_t *c;
 923   xcb_screen_t     *screen;
 924   xcb_drawable_t    win;
 925   xcb_gcontext_t    black;
 926   uint32_t          mask;
 927   uint32_t          value[1];
 928
 929   /* Open the connection to the X server and get the first screen */
 930   c = xcb_connect (NULL, NULL);
 931   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
 932
 933   /* Create a black graphic context for drawing in the foreground */
 934   win.window = screen-&gt;root;
 935   black = xcb_gcontext_new (c);
 936   mask = XCB_GC_FOREGROUND;
 937   value[0] = screen-&gt;black_pixel;
 938   xcb_create_gc (c, black, win, mask, value);
 939
 940   return 0;
 941 }
 942 </pre>
 943         <p>
 944         Note should be taken regarding the role of "value_mask" and
 945         "value_list" in the prototype of <span class="code">xcb_create_gc()</span>. Since a
 946         graphic context has many attributes, and since we often just
 947         want to define a few of them, we need to be able to tell the
 948         <span class="code">xcb_create_gc()</span> which attributes we
 949         want to set. This is what the "value_mask" parameter is
 950         for. We then use the "value_list" parameter to specify actual
 951         values for the attribute we defined in "value_mask". Thus, for
 952         each constant used in "value_list", we will use the matching
 953         constant in "value_mask". In this case, we define a graphic
 954         context with one attribute: when drawing (a point, a line,
 955         etc), the foreground color will be black. The rest of the
 956         attributes of this graphic context will be set to their
 957         default values.
 958         </p>
 959         <p>
 960         See the next Subsection for more details.
 961         </p>
 962         <div class="comp">
 963           <div class="title">
 964           Comparison Xlib/XCB
 965           </div>
 966           <div class="xlib">
 967           <ul>
 968             <li>XCreateGC ()
 969           </ul>
 970           </div>
 971           <div class="xcb">
 972           <ul>
 973             <li>xcb_gcontext_new ()
 974             <li>xcb_create_gc ()
 975           </ul>
 976           </div>
 977         </div>
 978         <br>
 979         <li class="subtitle"><a name="changegc">Changing the attributes of a Graphics Context</a>
 980         <p>
 981         Once we have allocated a Graphic Context, we may need to
 982         change its attributes (for example, changing the foreground
 983         color we use to draw a line, or changing the attributes of the
 984         font we use to display strings. See Subsections Drawing with a
 985         color and Assigning a Font to a Graphic Context). This is done
 986         by using this function:
 987         </p>
 988         <pre class="code">
 989 xcb_void_cookie_t xcb_change_gc (xcb_connection_t *c,           /* The XCB Connection */
 990                                  xcb_gcontext_t    gc,          /* The Graphic Context */
 991                                  uint32_t          value_mask,  /* Components of the Graphic Context that have to be set */
 992                                  const uint32_t   *value_list); /* Value as specified by value_mask */
 993 </pre>
 994         <p>
 995         The <span class="code">value_mask</span> parameter could take
 996         any combination of these masks from the xcb_gc_t enumeration:
 997         </p>
 998         <ul>
 999           <li>XCB_GC_FUNCTION
1000           <li>XCB_GC_PLANE_MASK
1001           <li>XCB_GC_FOREGROUND
1002           <li>XCB_GC_BACKGROUND
1003           <li>XCB_GC_LINE_WIDTH
1004           <li>XCB_GC_LINE_STYLE
1005           <li>XCB_GC_CAP_STYLE
1006           <li>XCB_GC_JOIN_STYLE
1007           <li>XCB_GC_FILL_STYLE
1008           <li>XCB_GC_FILL_RULE
1009           <li>XCB_GC_TILE
1010           <li>XCB_GC_STIPPLE
1011           <li>XCB_GC_TILE_STIPPLE_ORIGIN_X
1012           <li>XCB_GC_TILE_STIPPLE_ORIGIN_Y
1013           <li>XCB_GC_FONT
1014           <li>XCB_GC_SUBWINDOW_MODE
1015           <li>XCB_GC_GRAPHICS_EXPOSURES
1016           <li>XCB_GC_CLIP_ORIGIN_X
1017           <li>XCB_GC_CLIP_ORIGIN_Y
1018           <li>XCB_GC_CLIP_MASK
1019           <li>XCB_GC_DASH_OFFSET
1020           <li>XCB_GC_DASH_LIST
1021           <li>XCB_GC_ARC_MODE
1022         </ul>
1023         <p>
1024         It is possible to set several attributes at the same
1025         time (for example setting the attributes of a font and the
1026         color which will be used to display a string), by OR'ing these
1027         values in <span class="code">value_mask</span>. Then
1028         <span class="code">value_list</span> has to be an array which
1029         lists the value for the respective attributes.  <b>These values
1030         must be in the same order as masks listed above.</b> See Subsection
1031         Drawing with a color to have an example.
1032         </p>
1033         <p>
1034         <b>TODO</b>: set the links of the 3 subsections, once they will
1035         be written :)
1036         </p>
1037         <p>
1038         <b>TODO</b>: give an example which sets several attributes.
1039         </p>
1040         <li class="subtitle"><a name="drawingprim">Drawing primitives: point, line, box, circle,...</a>
1041         <p>
1042         After we have created a Graphic Context, we can draw on a
1043         window using this Graphic Context, with a set of XCB
1044         functions, collectively called "drawing primitives". Let see
1045         how they are used.
1046         </p>
1047         <p>
1048         To draw a point, or several points, we use
1049         </p>
1050         <pre class="code">
1051 xcb_void_cookie_t xcb_poly_point (xcb_connection_t  *c,               /* The connection to the X server */
1052                                   uint8_t            coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1053                                   xcb_drawable_t     drawable,        /* The drawable on which we want to draw the point(s) */
1054                                   xcb_gcontext_t     gc,              /* The Graphic Context we use to draw the point(s) */
1055                                   uint32_t           points_len,      /* The number of points */
1056                                   const xcb_point_t *points);         /* An array of points */
1057 </pre>
1058         <p>
1059         The <span class="code">coordinate_mode</span> parameter
1060         specifies the coordinate mode.  Available values are
1061         </p>
1062         <ul>
1063           <li><span class="code">XCB_COORD_MODE_ORIGIN</span>
1064           <li><span class="code">XCB_COORD_MODE_PREVIOUS</span>
1065         </ul>
1066         <p>
1067         If XCB_COORD_MODE_PREVIOUS is used, then all points but the first one
1068         are relative to the immediately previous point.
1069         </p>
1070         <p>
1071         The <span class="code">xcb_point_t</span> type is just a
1072         structure with two fields (the coordinates of the point):
1073         </p>
1074         <pre class="code">
1075 typedef struct {
1076     int16_t x;
1077     int16_t y;
1078 } xcb_point_t;
1079 </pre>
1080         <p>
1081         You could see an example in xpoints.c. <b>TODO</b> Set the link.
1082         </p>
1083         <p>
1084         To draw a line, or a polygonal line, we use
1085         </p>
1086         <pre class="code">
1087 xcb_void_cookie_t xcb_poly_line (xcb_connection_t  *c,               /* The connection to the X server */
1088                                  uint8_t            coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1089                                  xcb_drawable_t     drawable,        /* The drawable on which we want to draw the line(s) */
1090                                  xcb_gcontext_t     gc,              /* The Graphic Context we use to draw the line(s) */
1091                                  uint32_t           points_len,      /* The number of points in the polygonal line */
1092                                  const xcb_point_t *points);         /* An array of points */
1093 </pre>
1094         <p>
1095         This function will draw the line between the first and the
1096         second points, then the line between the second and the third
1097         points, and so on.
1098         </p>
1099         <p>
1100         To draw a segment, or several segments, we use
1101         </p>
1102         <pre class="code">
1103 xcb_void_cookie_t xcb_poly_segment (xcb_connection_t    *c,              /* The connection to the X server */
1104                                     xcb_drawable_t       drawable,       /* The drawable on which we want to draw the segment(s) */
1105                                     xcb_gcontext_t       gc,             /* The Graphic Context we use to draw the segment(s) */
1106                                     uint32_t             segments_len,   /* The number of segments */
1107                                     const xcb_segment_t *segments);      /* An array of segments */
1108 </pre>
1109         <p>
1110         The <span class="code">xcb_segment_t</span> type is just a
1111         structure with four fields (the coordinates of the two points
1112         that define the segment):
1113         </p>
1114         <pre class="code">
1115 typedef struct {
1116     int16_t x1;
1117     int16_t y1;
1118     int16_t x2;
1119     int16_t y2;
1120 } xcb_segment_t;
1121 </pre>
1122         <p>
1123         To draw a rectangle, or several rectangles, we use
1124         </p>
1125         <pre class="code">
1126 xcb_void_cookie_t xcb_poly_rectangle (xcb_connection_t      *c,              /* The connection to the X server */
1127                                       xcb_drawable_t         drawable,       /* The drawable on which we want to draw the rectangle(s) */
1128                                       xcb_gcontext_t         gc,             /* The Graphic Context we use to draw the rectangle(s) */
1129                                       uint32_t               rectangles_len, /* The number of rectangles */
1130                                       const xcb_rectangle_t *rectangles);    /* An array of rectangles */
1131 </pre>
1132         <p>
1133         The <span class="code">xcb_rectangle_t</span> type is just a
1134         structure with four fields (the coordinates of the top-left
1135         corner of the rectangle, and its width and height):
1136         </p>
1137         <pre class="code">
1138 typedef struct {
1139     int16_t  x;
1140     int16_t  y;
1141     uint16_t width;
1142     uint16_t height;
1143 } xcb_rectangle_t;
1144 </pre>
1145         <!-- There's no coordinate_mode. Is it normal? -->
1146         <!-- [iano] Yes, it's not in the protocol. -->
1147         <p>
1148         To draw an elliptical arc, or several elliptical arcs, we use
1149         </p>
1150         <pre class="code">
1151 xcb_void_cookie_t xcb_poly_arc (xcb_connection_t *c,          /* The connection to the X server */
1152                                 xcb_drawable_t    drawable,   /* The drawable on which we want to draw the arc(s) */
1153                                 xcb_gcontext_t    gc,         /* The Graphic Context we use to draw the arc(s) */
1154                                 uint32_t          arcs_len,   /* The number of arcs */
1155                                 const xcb_arc_t  *arcs);      /* An array of arcs */
1156 </pre>
1157         <p>
1158         The <span class="code">xcb_arc_t</span> type is a structure with
1159         six fields:
1160         </p>
1161         <pre class="code">
1162 typedef struct {
1163     int16_t  x;       /* Top left x coordinate of the rectangle surrounding the ellipse */
1164     int16_t  y;       /* Top left y coordinate of the rectangle surrounding the ellipse */
1165     uint16_t width;   /* Width of the rectangle surrounding the ellipse */
1166     uint16_t height;  /* Height of the rectangle surrounding the ellipse */
1167     int16_t  angle1;  /* Angle at which the arc begins */
1168     int16_t  angle2;  /* Angle at which the arc ends */
1169 } xcb_arc_t;
1170 </pre>
1171         <div class="emph">
1172         <p>
1173         Note: the angles are expressed in units of 1/64 of a degree,
1174         so to have an angle of 90 degrees, starting at 0,
1175         <span class="code">angle1 = 0</span> and
1176         <span class="code">angle2 = 90 &lt;&lt; 6</span>. Positive angles
1177         indicate counterclockwise motion, while  negative angles
1178         indicate clockwise motion.
1179         </p>
1180         </div>
1181         <!-- I think that (x,y) should be the center of the
1182         ellipse, and (width, height) the radius. It's more logical. -->
1183         <!-- iano: Yes, and I bet some toolkits do that.
1184          But the protocol (and many other graphics APIs) define arcs
1185          by bounding rectangles. -->
1186         <p>
1187         The corresponding function which fill inside the geometrical
1188         object are listed below, without  further explanation, as they
1189         are used as the above functions.
1190         </p>
1191         <p>
1192         To Fill a polygon defined by the points given as arguments ,
1193         we use
1194         </p>
1195         <pre class="code">
1196 xcb_void_cookie_t xcb_fill_poly (xcb_connection_t  *c,
1197                                  xcb_drawable_t     drawable,
1198                                  xcb_gcontext_t     gc,
1199                                  uint8_t            shape,
1200                                  uint8_t            coordinate_mode,
1201                                  uint32_t           points_len,
1202                                  const xcb_point_t *points);
1203 </pre>
1204         <p>
1205         The <span class="code">shape</span> parameter specifies a
1206         shape that helps the server to improve performance. Available
1207         values are
1208         </p>
1209         <ul>
1210           <li><span class="code">XCB_POLY_SHAPE_COMPLEX</span>
1211           <li><span class="code">XCB_POLY_SHAPE_NONCONVEX</span>
1212           <li><span class="code">XCB_POLY_SHAPE_CONVEX</span>
1213         </ul>
1214         <p>
1215         To fill one or several rectangles, we use
1216         </p>
1217         <pre class="code">
1218 xcb_void_cookie_t xcb_poly_fill_rectangle (xcb_connection_t      *c,
1219                                            xcb_drawable_t         drawable,
1220                                            xcb_gcontext_t         gc,
1221                                            uint32_t               rectangles_len,
1222                                            const xcb_rectangle_t *rectangles);
1223 </pre>
1224         <p>
1225         To fill one or several arcs, we use
1226         </p>
1227         <pre class="code">
1228 xcb_void_cookie_t xcb_poly_fill_arc (xcb_connection_t *c,
1229                                      xcb_drawable_t    drawable,
1230                                      xcb_gcontext_t    gc,
1231                                      uint32_t          arcs_len,
1232                                      const xcb_arc_t  *arcs);
1233 </pre>
1234         <br>
1235         <a name="points.c"></a>
1236         <p>
1237         To illustrate these functions, here is an example that draws
1238         four points, a polygonal line, two segments, two rectangles
1239         and two arcs. Remark that we use events for the first time, as
1240         an introduction to the next section.
1241         </p>
1242         <p>
1243         <b>TODO:</b> Use screen-&gt;root_depth for depth parameter.
1244         </p>
1245         <pre class="code">
1246 #include &lt;stdlib.h&gt;
1247 #include &lt;stdio.h&gt;
1248
1249 #include &lt;X11/XCB/xcb.h&gt;
1250
1251 int
1252 main (int argc, char *argv[])
1253 {
1254   xcb_connection_t    *c;
1255   xcb_screen_t        *screen;
1256   xcb_drawable_t       win;
1257   xcb_gcontext_t       foreground;
1258   xcb_generic_event_t *e;
1259   uint32_t             mask = 0;
1260   uint32_t             values[2];
1261
1262   /* geometric objects */
1263   xcb_point_t          points[] = {
1264     {10, 10},
1265     {10, 20},
1266     {20, 10},
1267     {20, 20}};
1268
1269   xcb_point_t          polyline[] = {
1270     {50, 10},
1271     { 5, 20},     /* rest of points are relative */
1272     {25,-20},
1273     {10, 10}};
1274
1275   xcb_segment_t        segments[] = {
1276     {100, 10, 140, 30},
1277     {110, 25, 130, 60}};
1278
1279   xcb_rectangle_t      rectangles[] = {
1280     { 10, 50, 40, 20},
1281     { 80, 50, 10, 40}};
1282
1283   xcb_arc_t            arcs[] = {
1284     {10, 100, 60, 40, 0, 90 &lt;&lt; 6},
1285     {90, 100, 55, 40, 0, 270 &lt;&lt; 6}};
1286
1287   /* Open the connection to the X server */
1288   c = xcb_connect (NULL, NULL);
1289
1290   /* Get the first screen */
1291   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1292
1293   /* Create black (foreground) graphic context */
1294   win.window = screen-&gt;root;
1295
1296   foreground = xcb_gcontext_new (c);
1297   mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
1298   values[0] = screen-&gt;black_pixel;
1299   values[1] = 0;
1300   xcb_create_gc (c, foreground, win, mask, values);
1301
1302   /* Ask for our window's Id */
1303   win.window = xcb_window_new(c);
1304
1305   /* Create the window */
1306   mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1307   values[0] = screen-&gt;white_pixel;
1308   values[1] = XCB_EVENT_MASK_EXPOSURE;
1309   xcb_create_window (c,                             /* Connection          */
1310                      XCB_COPY_FROM_PARENT,          /* depth               */
1311                      win.window,                    /* window Id           */
1312                      screen-&gt;root,                  /* parent window       */
1313                      0, 0,                          /* x, y                */
1314                      150, 150,                      /* width, height       */
1315                      10,                            /* border_width        */
1316                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
1317                      screen-&gt;root_visual,           /* visual              */
1318                      mask, values);                 /* masks */
1319
1320   /* Map the window on the screen */
1321   xcb_map_window (c, win.window);
1322
1323
1324   /* We flush the request */
1325   xcb_flush (c);
1326
1327   while ((e = xcb_wait_for_event (c))) {
1328     switch (e-&gt;response_type &amp; ~0x80) {
1329     case XCB_EXPOSE: {
1330       /* We draw the points */
1331       xcb_poly_point (c, XCB_COORD_MODE_ORIGIN, win, foreground, 4, points);
1332
1333       /* We draw the polygonal line */
1334       xcb_poly_line (c, XCB_COORD_MODE_PREVIOUS, win, foreground, 4, polyline);
1335
1336       /* We draw the segements */
1337       xcb_poly_segment (c, win, foreground, 2, segments);
1338
1339       /* We draw the rectangles */
1340       xcb_poly_rectangle (c, win, foreground, 2, rectangles);
1341
1342       /* We draw the arcs */
1343       xcb_poly_arc (c, win, foreground, 2, arcs);
1344
1345       /* We flush the request */
1346       xcb_flush (c);
1347
1348       break;
1349     }
1350     default: {
1351       /* Unknown event type, ignore it */
1352       break;
1353     }
1354     }
1355     /* Free the Generic Event */
1356     free (e);
1357   }
1358
1359   return 0;
1360 }
1361 </pre>
1362       </ol>
1363       <li class="title"><a name="xevents">X Events</a>
1364       <p>
1365       In an X program, everything is driven by events. Event painting
1366       on the screen is sometimes done as a response to an event (an
1367       <span class="code">Expose</span> event). If part of a program's
1368       window that was hidden, gets exposed (e.g. the window was raised
1369       above other widows), the X server will send an "expose" event to
1370       let the program know it should repaint that part of the
1371       window. User input (key presses, mouse movement, etc) is also
1372       received as a set of events.
1373       </p>
1374       <ol>
1375         <li class="subtitle"><a name="register">Registering for event types using event masks</a>
1376         <p>
1377         During the creation of a window, you should give it what kind
1378         of events it wishes to receive. Thus, you may register for
1379         various mouse (also called pointer) events, keyboard events,
1380         expose events, and so on. This is done for optimizing the
1381         server-to-client connection (i.e. why send a program (that
1382         might even be running at the other side of the globe) an event
1383         it is not interested in ?)
1384         </p>
1385         <p>
1386         In XCB, you use the "value_mask" and "value_list" data in the
1387         <span class="code">xcb_create_window()</span> function to
1388         register for events. Here is how we register for
1389         <span class="code">Expose</span> event when creating a window:
1390         </p>
1391         <pre class="code">
1392   mask = XCB_CW_EVENT_MASK;
1393   valwin[0] = XCB_EVENT_MASK_EXPOSURE;
1394   win.window = xcb_window_new (c);
1395   xcb_create_window (c, depth, win.window, root-&gt;root,
1396                      0, 0, 150, 150, 10,
1397                      XCB_WINDOW_CLASS_INPUT_OUTPUT, root-&gt;root_visual,
1398                      mask, valwin);
1399 </pre>
1400         <p>
1401         <span class="code">XCB_EVENT_MASK_EXPOSURE</span> is a constant defined
1402         in the xcb_event_mask_t enumeration in the "xproto.h" header file. If we wanted to register for several
1403         event types, we can logically "or" them, as follows:
1404         </p>
1405         <pre class="code">
1406   mask = XCB_CW_EVENT_MASK;
1407   valwin[0] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS;
1408   win.window = xcb_window_new (c);
1409   xcb_create_window (c, depth, win.window, root-&gt;root,
1410                      0, 0, 150, 150, 10,
1411                      XCB_WINDOW_CLASS_INPUT_OUTPUT, root-&gt;root_visual,
1412                      mask, valwin);
1413 </pre>
1414         <p>
1415         This registers for <span class="code">Expose</span> events as
1416         well as for mouse button presses inside the created
1417         window. You should note that a mask may represent several
1418         event sub-types.
1419         </p>
1420         <p>
1421         The values that a mask could take are given
1422         by the <span class="code">xcb_cw_t</span> enumeration:
1423         </p>
1424         <pre class="code">
1425 typedef enum {
1426     XCB_CW_BACK_PIXMAP       = 1L<<0,
1427     XCB_CW_BACK_PIXEL        = 1L<<1,
1428     XCB_CW_BORDER_PIXMAP     = 1L<<2,
1429     XCB_CW_BORDER_PIXEL      = 1L<<3,
1430     XCB_CW_BIT_GRAVITY       = 1L<<4,
1431     XCB_CW_WIN_GRAVITY       = 1L<<5,
1432     XCB_CW_BACKING_STORE     = 1L<<6,
1433     XCB_CW_BACKING_PLANES    = 1L<<7,
1434     XCB_CW_BACKING_PIXEL     = 1L<<8,
1435     XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
1436     XCB_CW_SAVE_UNDER        = 1L<<10,
1437     XCB_CW_EVENT_MASK        = 1L<<11,
1438     XCB_CW_DONT_PROPAGATE    = 1L<<12,
1439     XCB_CW_COLORMAP          = 1L<<13,
1440     XCB_CW_CURSOR            = 1L<<14
1441 } xcb_cw_t;
1442 </pre>
1443         <div class="emph">
1444         <p>Note: we must be careful when setting the values of the valwin
1445         parameter, as they have to follow the order the
1446         <span class="code">xcb_cw_t</span> enumeration. Here is an
1447         example:
1448         </p>
1449         </div>
1450         <pre class="code">
1451   mask = XCB_CW_EVENT_MASK | XCB_CW_BACK_PIXMAP;
1452   valwin[0] = XCB_NONE;                                              /* for XCB_CW_BACK_PIXMAP (whose value is 1)     */
1453   valwin[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; /* for XCB_CW_EVENT_MASK, whose value (2048)     */
1454                                                                      /* is greater than the one of XCB_CW_BACK_PIXMAP */
1455 </pre>
1456         <p>
1457         If the window has already been created, we can use the
1458         <span class="code">xcb_configure_window()</span> function to set
1459         the events that the window will receive. The subsection
1460         <a href="#winconf">Configuring a window</a> shows its
1461         prototype. As an example, here is a piece of code that
1462         configures the window to receive the
1463         <span class="code">Expose</span> and
1464         <span class="code">ButtonPress</span> events:
1465         </p>
1466         <pre class="code">
1467 const static uint32_t values[] = { XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS };
1468
1469 /* The connection c and the window win are supposed to be defined */
1470
1471 xcb_configure_window (c, win, XCB_CW_EVENT_MASK, values);
1472 </pre>
1473         <div class="emph">
1474         <p>
1475         Note: A common bug programmers do is adding code to handle new
1476         event types in their program, while forgetting to add the
1477         masks for these events in the creation of the window. Such a
1478         programmer then should sit down for hours debugging his
1479         program, wondering "Why doesn't my program notice that I
1480         released the button?", only to find that they registered for
1481         button press events but not for button release events.
1482         </p>
1483         </div>
1484         <li class="subtitle"><a name="loop">Receiving events: writing the events loop</a>
1485         <p>
1486         After we have registered for the event types we are interested
1487         in, we need to enter a loop of receiving events and handling
1488         them. There are two ways to receive events: a blocking way and
1489         a non-blocking way:
1490         </p>
1491         <ul>
1492           <li>
1493           <span class="code">xcb_wait_for_event (xcb_connection_t *c)</span>
1494           is the blocking way. It waits (so blocks...) until an event is
1495           queued in the X server. Then it retrieves it into a newly
1496           allocated structure (it dequeues it from the queue) and returns
1497           it. This structure has to be freed. The function returns
1498           <span class="code">NULL</span> if an error occurs.
1499
1500           <br>
1501           <li>
1502           <span class="code">xcb_poll_for_event (xcb_connection_t *c, int
1503           *error)</span> is the non-blocking way. It looks at the event
1504           queue and returns (and dequeues too) an existing event into
1505           a newly allocated structure. This structure has to be
1506           freed. It returns <span class="code">NULL</span> if there is
1507           no event. If an error occurs, the parameter <span
1508           class="code">error</span> will be filled with the error
1509           status.
1510         </ul>
1511         <p>
1512         There are various ways to write such a loop. We present two
1513         ways to write such a loop, with the two functions above. The
1514         first one uses <span class="code">xcb_wait_for_event_t</span>, which
1515         is similar to an event Xlib loop using only <span
1516         class="code">XNextEvent</span>:
1517         </p>
1518         <pre class="code">
1519   xcb_generic_event_t *e;
1520
1521   while ((e = xcb_wait_for_event (c))) {
1522     switch (e-&gt;response_type &amp; ~0x80) {
1523     case XCB_EXPOSE: {
1524       /* Handle the Expose event type */
1525       xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1526
1527       /* ... */
1528
1529       break;
1530     }
1531     case XCB_BUTTON_PRESS: {
1532       /* Handle the ButtonPress event type */
1533       xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1534
1535       /* ... */
1536
1537       break;
1538     }
1539     default: {
1540       /* Unknown event type, ignore it */
1541       break;
1542     }
1543     }
1544     /* Free the Generic Event */
1545     free (e);
1546   }
1547 </pre>
1548         <p>
1549         You will certainly want to use <span
1550         class="code">xcb_poll_for_event(xcb_connection_t *c, int
1551         *error)</span> if, in Xlib, you use <span
1552         class="code">XPending</span> or
1553         <span class="code">XCheckMaskEvent</span>:
1554         </p>
1555         <pre class="code">
1556   while (XPending (display)) {
1557     XEvent ev;
1558
1559     XNextEvent(d, &amp;ev);
1560
1561     /* Manage your event */
1562   }
1563 </pre>
1564         <p>
1565         Such a loop in XCB looks like:
1566         </p>
1567         <pre class="code">
1568   xcb_generic_event_t *ev;
1569
1570   while ((ev = xcb_poll_for_event (conn, 0))) {
1571     /* Manage your event */
1572   }
1573 </pre>
1574         <p>
1575         The events are managed in the same way as with <span
1576         class="code">xcb_wait_for_event_t</span>.
1577         Obviously, we will need to give the user some way of
1578         terminating the program. This is usually done by handling a
1579         special "quit" event, as we will soon see.
1580         </p>
1581         <div class="comp">
1582           <div class="title">
1583             Comparison Xlib/XCB
1584           </div>
1585           <div class="xlib">
1586             <ul>
1587               <li>XNextEvent ()
1588               </ul>
1589           </div>
1590           <div class="xcb">
1591             <ul>
1592               <li>xcb_wait_for_event ()
1593             </ul>
1594           </div>
1595           <div class="xlib">
1596             <ul>
1597               <li>XPending ()
1598               <li>XCheckMaskEvent ()
1599             </ul>
1600           </div>
1601           <div class="xcb">
1602             <ul>
1603               <li>xcb_poll_for_event ()
1604             </ul>
1605           </div>
1606         </div>
1607         <br>
1608         <li class="subtitle"><a name="expose">Expose events</a>
1609         <p>
1610         The <span class="code">Expose</span> event is one of the most
1611         basic (and most used) events an application may receive. It
1612         will be sent to us in one of several cases:
1613         </p>
1614         <ul>
1615           <li>A window that covered part of our window has moved
1616               away, exposing part (or all) of our window.
1617           <li>Our window was raised above other windows.
1618           <li>Our window mapped for the first time.
1619           <li>Our window was de-iconified.
1620         </ul>
1621         <p>
1622         You should note the implicit assumption hidden here: the
1623         contents of our window is lost when it is being obscured
1624         (covered) by either windows. One may wonder why the X server
1625         does not save this contents. The answer is: to save
1626         memory. After all, the number of windows on a display at a
1627         given time may be very large, and storing the contents of all
1628         of them might require a lot of memory. Actually, there is a
1629         way to tell the X server to store  the contents of a window in
1630         special cases, as we will see later.
1631         </p>
1632         <p>
1633         When we get an <span class="code">Expose</span> event, we
1634         should take the event's data from the members of the following
1635         structure:
1636         </p>
1637         <pre class="code">
1638 typedef struct {
1639     uint8_t      response_type; /* The type of the event, here it is XCB_EXPOSE */
1640     uint8_t      pad0;
1641     uint16_t     sequence;
1642     xcb_window_t window;        /* The Id of the window that receives the event (in case */
1643                                 /* our application registered for events on several windows */
1644     uint16_t     x;             /* The x coordinate of the top-left part of the window that needs to be redrawn */
1645     uint16_t     y;             /* The y coordinate of the top-left part of the window that needs to be redrawn */
1646     uint16_t     width;         /* The width of the part of the window that needs to be redrawn */
1647     uint16_t     height;        /* The height of the part of the window that needs to be redrawn */
1648     uint16_t     count;
1649 } xcb_expose_event_t;
1650 </pre>
1651         <li class="subtitle"><a name="userinput">Getting user input</a>
1652         <p>
1653         User input traditionally comes from two sources: the mouse
1654         and the keyboard. Various event types exist to notify us of
1655         user input (a key being presses on the keyboard, a key being
1656         released on the keyboard, the mouse moving over our window,
1657         the mouse entering (or leaving) our window, and so on.
1658         </p>
1659         <ol>
1660             <li class="subsubtitle"><a name="mousepressrelease">Mouse button press and release events</a>
1661           <p>
1662           The first event type we will deal with is a mouse
1663           button-press (or button-release) event in our window. In
1664           order to register to such an event type, we should add one
1665           (or more) of the following masks when we create our window:
1666           </p>
1667           <ul>
1668             <li><span class="code">XCB_EVENT_MASK_BUTTON_PRESS</span>: notify us
1669             of any button that was pressed in one of our windows.
1670             <li><span class="code">XCB_EVENT_MASK_BUTTON_RELEASE</span>: notify us
1671             of any button that was released in one of our windows.
1672           </ul>
1673           <p>
1674           The structure to be checked for in our events loop is the
1675           same for these two events, and is the following:
1676           </p>
1677           <pre class="code">
1678 typedef struct {
1679     uint8_t         response_type; /* The type of the event, here it is xcb_button_press_event_t or xcb_button_release_event_t */
1680     xcb_button_t    detail;
1681     uint16_t        sequence;
1682     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1683     xcb_window_t    root;
1684     xcb_window_t    event;
1685     xcb_window_t    child;
1686     int16_t         root_x;
1687     int16_t         root_y;
1688     int16_t         event_x;       /* The x coordinate where the mouse has been pressed in the window */
1689     int16_t         event_y;       /* The y coordinate where the mouse has been pressed in the window */
1690     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1691     uint8_t         same_screen;
1692 } xcb_button_press_event_t;
1693
1694 typedef xcb_button_press_event_t xcb_button_release_event_t;
1695 </pre>
1696           <p>
1697           The <span class="code">time</span> field may be used to calculate "double-click"
1698           situations by an application (e.g. if the mouse button was
1699           clicked two times in a duration shorter than a given amount
1700           of time, assume this was a double click).
1701           </p>
1702           <p>
1703           The <span class="code">state</span> field is a mask of the buttons held down during
1704           the event. It is a bitwise OR of any of the following (from the xcb_button_mask_t and
1705           xcb_mod_mask_t enumerations):
1706           </p>
1707           <ul>
1708             <li><span class="code">XCB_BUTTON_MASK_1</span>
1709             <li><span class="code">XCB_BUTTON_MASK_2</span>
1710             <li><span class="code">XCB_BUTTON_MASK_3</span>
1711             <li><span class="code">XCB_BUTTON_MASK_4</span>
1712             <li><span class="code">XCB_BUTTON_MASK_5</span>
1713             <li><span class="code">XCB_MOD_MASK_SHIFT</span>
1714             <li><span class="code">XCB_MOD_MASK_LOCK</span>
1715             <li><span class="code">XCB_MOD_MASK_CONTROL</span>
1716             <li><span class="code">XCB_MOD_MASK_1</span>
1717             <li><span class="code">XCB_MOD_MASK_2</span>
1718             <li><span class="code">XCB_MOD_MASK_3</span>
1719             <li><span class="code">XCB_MOD_MASK_4</span>
1720             <li><span class="code">XCB_MOD_MASK_5</span>
1721           </ul>
1722           <p>
1723           Their names are self explanatory, where the first 5 refer to
1724           the mouse buttons that are being pressed, while the rest
1725           refer to various "special keys" that are being pressed (Mod1
1726           is usually the 'Alt' key or the 'Meta' key).
1727           </p>
1728           <p>
1729           <b>TODO:</b> Problem: it seems that the state does not
1730           change when clicking with various buttons.
1731           </p>
1732             <li class="subsubtitle"><a name="mousemvnt">Mouse movement events</a>
1733           <p>
1734           Similar to mouse button press and release events, we also
1735           can be notified of various mouse movement events. These can
1736           be split into two families. One is of mouse pointer
1737           movement while no buttons are pressed, and the second is a
1738           mouse pointer motion while one (or more) of the buttons are
1739           pressed (this is sometimes called "a mouse drag operation",
1740           or just "dragging"). The following event masks may be added
1741           during the creation of our window:
1742           </p>
1743           <ul>
1744             <li><span class="code">XCB_EVENT_MASK_POINTER_MOTION</span>: events of
1745             the pointer moving in one of the windows controlled by our
1746             application, while no mouse button is held pressed.
1747             <li><span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>: Events of
1748             the pointer moving while one or more of the mouse buttons
1749             is held pressed.
1750             <li><span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>: same as
1751             <span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>, but only when
1752             the 1st mouse button is held pressed.
1753             <li><span class="code">XCB_EVENT_MASK_BUTTON_2_MOTION</span>,
1754             <span class="code">XCB_EVENT_MASK_BUTTON_3_MOTION</span>,
1755             <span class="code">XCB_EVENT_MASK_BUTTON_4_MOTION</span>,
1756             <span class="code">XCB_EVENT_MASK_BUTTON_5_MOTION</span>: same as
1757             <span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>, but
1758             respectively for 2nd, 3rd, 4th and 5th mouse button.
1759           </ul>
1760           <p>
1761           The structure to be checked for in our events loop is the
1762           same for these events, and is the following:
1763           </p>
1764           <pre class="code">
1765 typedef struct {
1766     uint8_t         response_type; /* The type of the event */
1767     uint8_t         detail;
1768     uint16_t        sequence;
1769     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1770     xcb_window_t    root;
1771     xcb_window_t    event;
1772     xcb_window_t    child;
1773     int16_t         root_x;
1774     int16_t         root_y;
1775     int16_t         event_x;       /* The x coordinate of the mouse when the  event was generated */
1776     int16_t         event_y;       /* The y coordinate of the mouse when the  event was generated */
1777     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1778     uint8_t         same_screen;
1779 } xcb_motion_notify_event_t;
1780 </pre>
1781             <li class="subsubtitle"><a name="mouseenter">Mouse pointer enter and leave events</a>
1782           <p>
1783           Another type of event that applications might be interested
1784           in, is a mouse pointer entering a window the program
1785           controls, or leaving such a window. Some programs use these
1786           events to show the user that the application is now in
1787           focus. In order to register for such an event type, we
1788           should add one (or more) of the following masks when we
1789           create our window:
1790           </p>
1791           <ul>
1792             <li><span class="code">xcb_event_enter_window_t</span>: notify us
1793             when the mouse pointer enters any of our controlled
1794             windows.
1795             <li><span class="code">xcb_event_leave_window_t</span>: notify us
1796             when the mouse pointer leaves any of our controlled
1797             windows.
1798           </ul>
1799           <p>
1800           The structure to be checked for in our events loop is the
1801           same for these two events, and is the following:
1802           </p>
1803           <pre class="code">
1804 typedef struct {
1805     uint8_t         response_type; /* The type of the event */
1806     uint8_t         detail;
1807     uint16_t        sequence;
1808     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1809     xcb_window_t    root;
1810     xcb_window_t    event;
1811     xcb_window_t    child;
1812     int16_t         root_x;
1813     int16_t         root_y;
1814     int16_t         event_x;       /* The x coordinate of the mouse when the  event was generated */
1815     int16_t         event_y;       /* The y coordinate of the mouse when the  event was generated */
1816     uint16_t        state;         /* A mask of the buttons (or keys) during the event */
1817     uint8_t         mode;          /* The number of mouse button that was clicked */
1818     uint8_t         same_screen_focus;
1819 } xcb_enter_notify_event_t;
1820
1821 typedef xcb_enter_notify_event_t xcb_leave_notify_event_t;
1822 </pre>
1823           <li class="subsubtitle"><a name="focus">The keyboard focus</a>
1824           <p>
1825           There may be many windows on a screen, but only a single
1826           keyboard attached to them. How does the X server then know
1827           which window should be sent a given keyboard input ? This is
1828           done using the keyboard focus. Only a single window on the
1829           screen may have the keyboard focus at a given time. There
1830           is a XCB function that allows a program to set the keyboard
1831           focus to a given window. The user can usually set the
1832           keyboard focus using the window manager (often by clicking
1833           on the title bar of the desired window). Once our window
1834           has the keyboard focus, every key press or key release will
1835           cause an event to be sent to our program (if it regsitered
1836           for these event types...).
1837           </p>
1838           <li class="subsubtitle"><a name="keypress">Keyboard press and release events</a>
1839           <p>
1840           If a window controlled by our program currently holds the
1841           keyboard focus, it can receive key press and key release
1842           events. So, we should add one (or more) of the following
1843           masks when we create our window:
1844           </p>
1845           <ul>
1846             <li><span class="code">XCB_EVENT_MASK_KEY_PRESS</span>: notify us when
1847             a key was pressed while any of our controlled windows had
1848             the keyboard focus.
1849             <li><span class="code">XCB_EVENT_MASK_KEY_RELEASE</span>: notify us
1850             when a key was released while any of our controlled
1851             windows had the keyboard focus.
1852           </ul>
1853           <p>
1854           The structure to be checked for in our events loop is the
1855           same for these two events, and is the following:
1856           </p>
1857           <pre class="code">
1858 typedef struct {
1859     uint8_t         response_type; /* The type of the event */
1860     xcb_keycode_t   detail;
1861     uint16_t        sequence;
1862     xcb_timestamp_t time;          /* Time, in milliseconds the event took place in */
1863     xcb_window_t    root;
1864     xcb_window_t    event;
1865     xcb_window_t    child;
1866     int16_t         root_x;
1867     int16_t         root_y;
1868     int16_t         event_x;
1869     int16_t         event_y;
1870     uint16_t        state;
1871     uint8_t         same_screen;
1872 } xcb_key_press_event_t;
1873
1874 typedef xcb_key_press_event_t xcb_key_release_event_t;
1875 </pre>
1876         <p>
1877         The <span class="code">detail</span> field refers to the
1878         physical key on the keyboard.
1879         </p>
1880         <p>
1881         <b>TODO:</b> Talk about getting the ASCII code from the key code.
1882         </p>
1883         </ol>
1884         <li class="subtitle"><a name="eventex">X events: a complete example</a>
1885         <p>
1886         As an example for handling events, we show a program that
1887         creates a window, enters an events loop and checks for all the
1888         events described above, and writes on the terminal the relevant
1889         characteristics of the event. With this code, it should be
1890         easy to add drawing operations, like those which have been
1891         described above.
1892         </p>
1893         <pre class="code">
1894 #include &lt;stdlib.h&gt;
1895 #include &lt;stdio.h&gt;
1896
1897 #include &lt;X11/XCB/xcb.h&gt;
1898
1899 void
1900 print_modifiers (uint32_t mask)
1901 {
1902   const char **mod, *mods[] = {
1903     "Shift", "Lock", "Ctrl", "Alt",
1904     "Mod2", "Mod3", "Mod4", "Mod5",
1905     "Button1", "Button2", "Button3", "Button4", "Button5"
1906   };
1907   printf ("Modifier mask: ");
1908   for (mod = mods ; mask; mask &gt;&gt;= 1, mod++)
1909     if (mask &amp; 1)
1910       printf(*mod);
1911   putchar ('\n');
1912 }
1913
1914 int
1915 main (int argc, char *argv[])
1916 {
1917   xcb_connection_t   *c;
1918   xcb_screen_t       *screen;
1919   xcb_drawable_t      win;
1920   xcb_generic_event_t *e;
1921   uint32_t             mask = 0;
1922   uint32_t             values[2];
1923
1924   /* Open the connection to the X server */
1925   c = xcb_connect (NULL, NULL);
1926
1927   /* Get the first screen */
1928   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1929
1930   /* Ask for our window's Id */
1931   win.window = xcb_window_new (c);
1932
1933   /* Create the window */
1934   mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1935   values[0] = screen-&gt;white_pixel;
1936   values[1] = XCB_EVENT_MASK_EXPOSURE       | XCB_EVENT_MASK_BUTTON_PRESS   |
1937               XCB_EVENT_MASK_BUTTON_RELEASE | XCB_EVENT_MASK_POINTER_MOTION |
1938               XCB_EVENT_MASK_ENTER_WINDOW   | XCB_EVENT_MASK_LEAVE_WINDOW   |
1939               XCB_EVENT_MASK_KEY_PRESS      | XCB_EVENT_MASK_KEY_RELEASE;
1940   xcb_create_window (c,                             /* Connection          */
1941                      0,                             /* depth               */
1942                      win.window,                    /* window Id           */
1943                      screen-&gt;root,                  /* parent window       */
1944                      0, 0,                          /* x, y                */
1945                      150, 150,                      /* width, height       */
1946                      10,                            /* border_width        */
1947                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
1948                      screen-&gt;root_visual,           /* visual              */
1949                      mask, values);                 /* masks */
1950
1951   /* Map the window on the screen */
1952   xcb_map_window (c, win.window);
1953
1954   xcb_flush (c);
1955
1956   while ((e = xcb_wait_for_event (c))) {
1957     switch (e-&gt;response_type &amp; ~0x80) {
1958     case XCB_EXPOSE: {
1959       xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1960
1961       printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
1962               ev-&gt;window.xid, ev-&gt;x, ev-&gt;y, ev-&gt;width, ev-&gt;height);
1963       break;
1964     }
1965     case XCB_BUTTON_PRESS: {
1966       xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1967       print_modifiers(ev-&gt;state);
1968
1969       switch (ev-&gt;detail.id) {
1970       case 4:
1971         printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
1972                 ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
1973         break;
1974       case 5:
1975         printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
1976                 ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
1977         break;
1978       default:
1979         printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
1980                 ev-&gt;detail.id, ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
1981       }
1982       break;
1983     }
1984     case XCB_BUTTON_RELEASE: {
1985       xcb_button_release_event_t *ev = (xcb_button_release_event_t *)e;
1986       print_modifiers(ev-&gt;state);
1987
1988       printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
1989               ev-&gt;detail.id, ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
1990       break;
1991     }
1992     case XCB_MOTION_NOTIFY: {
1993       xcb_motion_notify_event_t *ev = (xcb_motion_notify_event_t *)e;
1994
1995       printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
1996               ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
1997       break;
1998     }
1999     case XCB_ENTER_NOTIFY: {
2000       xcb_enter_notify_event_t *ev = (xcb_enter_notify_event_t *)e;
2001
2002       printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
2003               ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
2004       break;
2005     }
2006     case XCB_LEAVE_NOTIFY: {
2007       xcb_leave_notify_event_t *ev = (xcb_leave_notify_event_t *)e;
2008
2009       printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
2010               ev-&gt;event.xid, ev-&gt;event_x, ev-&gt;event_y);
2011       break;
2012     }
2013     case XCB_KEY_PRESS: {
2014       xcb_key_press_event_t *ev = (xcb_key_press_event_t *)e;
2015       print_modifiers(ev-&gt;state);
2016
2017       printf ("Key pressed in window %ld\n",
2018               ev-&gt;event.xid);
2019       break;
2020     }
2021     case XCB_KEY_RELEASE: {
2022       xcb_key_release_event_t *ev = (xcb_key_release_event_t *)e;
2023       print_modifiers(ev-&gt;state);
2024
2025       printf ("Key released in window %ld\n",
2026               ev-&gt;event.xid);
2027       break;
2028     }
2029     default:
2030       /* Unknown event type, ignore it */
2031       printf("Unknown event: %d\n", e-&gt;response_type);
2032       break;
2033     }
2034     /* Free the Generic Event */
2035     free (e);
2036   }
2037
2038   return 0;
2039 }
2040 </pre>
2041       </ol>
2042       <li class="title"><a name="font">Handling text and fonts</a>
2043       <p>
2044       Besides drawing graphics on a window, we often want to draw
2045       text. Text strings have two major properties: the characters to
2046       be drawn and the font with which they are drawn. In order to
2047       draw text, we need to first request the X server to load a
2048       font. We then assign a font to a Graphic Context, and finally, we
2049       draw the text in a window, using the Graphic Context.
2050       </p>
2051       <ol>
2052         <li class="subtitle"><a name="fontstruct">The Font structure</a>
2053         <p>
2054         In order to support flexible fonts, a font structure is
2055         defined. You know what ? It's an Id:
2056         </p>
2057         <pre class="code">
2058 typedef struct {
2059     uint32_t xid;
2060 } xcb_font_t;
2061 </pre>
2062         <p>
2063         It is used to contain information about a font, and is passed
2064         to several functions that handle fonts selection and text drawing.
2065         </p>
2066         <p>
2067         <b>TODO:</b> example for picking a font and displaying some text.
2068         Even better, also demonstrate translating keypresses to text.
2069         </p>
2070       </ol>
2071       <li class="title"><a name="wm">Interacting with the window manager</a>
2072       <p>
2073       After we have seen how to create windows and draw on them, we
2074       take one step back, and look at how our windows are interacting
2075       with their environment (the full screen and the other
2076       windows). First of all, our application needs to interact with
2077       the window manager. The window manager is responsible to
2078       decorating drawn windows (i.e. adding a frame, an iconify
2079       button, a system menu, a title bar, etc), as well as handling
2080       icons shown when windows are being iconified. It also handles
2081       ordering of windows on the screen, and other administrative
2082       tasks. We need to give it various hints as to how we want it to
2083       treat our application's windows.
2084       </p>
2085       <ol>
2086         <li class="subtitle"><a name="wmprop">Window properties</a>
2087         <p>
2088         Many of the parameters communicated to the window manager are
2089         passed using data called "properties". These properties are
2090         attached by the X server to different windows, and are stored
2091         in a format that makes it possible to read them from different
2092         machines that may use different architectures (remember that
2093         an X client program may run on a remote machine).
2094         </p>
2095         <p>
2096         The property and its type (a string, an integer, etc) are
2097         Id. Their type are <span class="code">xcb_atom_t</span>:
2098         </p>
2099         <pre class="code">
2100 typedef struct {
2101     uint32_t xid;
2102 } xcb_atom_t;
2103 </pre>
2104         <p>
2105         To change the property of a window, we use the following
2106         function:
2107         </p>
2108         <pre class="code">
2109 xcb_void_cookie_t xcb_change_property (xcb_connection_t *c,       /* Connection to the X server */
2110                                        uint8_t          mode,     /* Property mode */
2111                                        xcb_window_t     window,   /* Window */
2112                                        xcb_atom_t       property, /* Property to change */
2113                                        xcb_atom_t       type,     /* Type of the property */
2114                                        uint8_t          format,   /* Format of the property (8, 16, 32) */
2115                                        uint32_t         data_len, /* Length of the data parameter */
2116                                        const void      *data);    /* Data */
2117 </pre>
2118         <p>
2119         The <span class="code">mode</span> parameter coud be one of
2120         the following values (defined in enumeration xcb_prop_mode_t in
2121         the xproto.h header file):
2122         </p>
2123         <ul>
2124           <li>XCB_PROP_MODE_REPLACE
2125           <li>XCB_PROP_MODE_PREPEND
2126           <li>XCB_PROP_MODE_APPEND
2127         </ul>
2128         <br>
2129         <li class="subtitle"><a name="wmname">Setting the window name and icon name</a>
2130         <p>
2131         The first thing we want to do would be to set the name for our
2132         window. This is done using the
2133         <span class="code">xcb_change_property()</span> function. This
2134         name may be used by the window manager as the title of the
2135         window (in the title bar), in a task list, etc. The property
2136         atom to use to set the name of a window is
2137         <span class="code">WM_NAME</span> (and
2138         <span class="code">WM_ICON_NAME</span> for the iconified
2139         window) and its type is <span class="code">STRING</span>. Here
2140         is an example of utilization:
2141         </p>
2142         <pre class="code">
2143 #include &lt;string.h&gt;
2144
2145 #include &lt;X11/XCB/xcb.h&gt;
2146 #include &lt;X11/XCB/xcb_atom.h&gt;
2147
2148 int
2149 main (int argc, char *argv[])
2150 {
2151   xcb_connection_t *c;
2152   xcb_screen_t     *screen;
2153   xcb_window_t      win;
2154   char             *title = "Hello World !";
2155   char             *title_icon = "Hello World ! (iconified)";
2156
2157
2158
2159   /* Open the connection to the X server */
2160   c = xcb_connect (NULL, NULL);
2161
2162   /* Get the first screen */
2163   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2164
2165   /* Ask for our window's Id */
2166   win = xcb_window_new (c);
2167
2168   /* Create the window */
2169   xcb_create_window (c,                             /* Connection          */
2170                      0,                             /* depth               */
2171                      win,                           /* window Id           */
2172                      screen-&gt;root,                  /* parent window       */
2173                      0, 0,                          /* x, y                */
2174                      250, 150,                      /* width, height       */
2175                      10,                            /* border_width        */
2176                      XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class               */
2177                      screen-&gt;root_visual,           /* visual              */
2178                      0, NULL);                      /* masks, not used     */
2179
2180   /* Set the title of the window */
2181   xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2182                        WM_NAME, STRING, 8,
2183                        strlen (title), title);
2184
2185   /* Set the title of the window icon */
2186   xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2187                        WM_ICON_NAME, STRING, 8,
2188                        strlen(title_icon), title_icon);
2189
2190   /* Map the window on the screen */
2191   xcb_map_window (c, win);
2192
2193   xcb_flush (c);
2194
2195   while (1) {}
2196
2197   return 0;
2198 }
2199 </pre>
2200         <div class="emph">
2201         <p>Note: the use of the atoms needs our program to be compiled
2202         and linked against xcb_atom, so that we have to use
2203         </p>
2204         </div>
2205         <pre class="text">
2206 gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`
2207 </pre>
2208         <div class="emph">
2209         <p>
2210         for the program to compile fine.
2211         </p>
2212         </div>
2213       </ol>
2214       <li class="title"><a name="winop">Simple window operations</a>
2215       <p>
2216       One more thing we can do to our window is manipulate them on the
2217       screen (resize them, move them, raise or lower them, iconify
2218       them, and so on). Some window operations functions are supplied
2219       by XCB for this purpose.
2220       </p>
2221       <ol>
2222         <li class="subtitle"><a name="winmap">Mapping and un-mapping a window</a>
2223         <p>
2224         The first pair of operations we can apply on a window is
2225         mapping it, or un-mapping it. Mapping a window causes the
2226         window to appear on the screen, as we have seen in our simple
2227         window program example. Un-mapping it causes it to be removed
2228         from the screen (although the window as a logical entity still
2229         exists). This gives the effect of making a window hidden
2230         (unmapped) and shown again (mapped). For example, if we have a
2231         dialog box window in our program, instead of creating it every
2232         time the user asks to open it, we can create the window once,
2233         in an un-mapped mode, and when the user asks to open it, we
2234         simply map the window on the screen. When the user clicked the
2235         'OK' or 'Cancel' button, we simply un-map the window. This is
2236         much faster than creating and destroying the window, however,
2237         the cost is wasted resources, both on the client side, and on
2238         the X server side.
2239         </p>
2240         <p>
2241         To map a window, you use the following function:
2242         </p>
2243         <pre class="code">
2244 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
2245                                   xcb_window_t      window);
2246 </pre>
2247         <p>
2248         To have a simple example, see the <a href="#helloworld">example</a>
2249         above. The mapping operation will cause an
2250         <span class="code">Expose</span> event to be sent to our
2251         application, unless the window is completely covered by other
2252         windows.
2253         </p>
2254         <p>
2255         Un-mapping a window is also simple. You use the function
2256         </p>
2257         <pre class="code">
2258 xcb_void_cookie_t xcb_unmap_window (xcb_connection_t *c,
2259                                     xcb_window_t      window);
2260 </pre>
2261         <p>
2262         The utilization of this function is the same as
2263         <span class="code">xcb_map_window()</span>.
2264         </p>
2265         <li class="subtitle"><a name="winconf">Configuring a window</a>
2266         <p>
2267         As we have seen when we have created our first window, in the
2268         X Events subsection, we can set some attributes for the window
2269         (that is, the position, the size, the events the window will
2270         receive, etc). If we want to modify them, but the window is
2271         already created, we can change them by using the following
2272         function:
2273         </p>
2274         <pre class="code">
2275 xcb_void_cookie_t xcb_configure_window (xcb_connection_t *c,            /* The connection to the X server*/
2276                                         xcb_window_t      window,       /* The window to configure */
2277                                         uint16_t          value_mask,   /* The mask */
2278                                         const uint32_t   *value_list);  /* The values to set */
2279 </pre>
2280         <p>
2281         We set the <span class="code">value_mask</span> to one or
2282         several mask values that are in the xcb_config_window_t enumeration in the xproto.h header:
2283         </p>
2284         <ul>
2285           <li><span class="code">XCB_CONFIG_WINDOW_X</span>: new x coordinate of the window's top left corner
2286           <li><span class="code">XCB_CONFIG_WINDOW_Y</span>: new y coordinate of the window's top left corner
2287           <li><span class="code">XCB_CONFIG_WINDOW_WIDTH</span>: new width of the window
2288           <li><span class="code">XCB_CONFIG_WINDOW_HEIGHT</span>: new height of the window
2289           <li><span class="code">XCB_CONFIG_WINDOW_BORDER_WIDTH</span>: new width of the border of the window
2290           <li><span class="code">XCB_CONFIG_WINDOW_SIBLING</span>
2291           <li><span class="code">XCB_CONFIG_WINDOW_STACK_MODE</span>: the new stacking order
2292         </ul>
2293         <p>
2294         We then give to <span class="code">value_mask</span> the new
2295         value. We now describe how to use
2296         <span class="code">xcb_configure_window_t</span> in some useful
2297         situations.
2298         </p>
2299         <li class="subtitle"><a name="winmove">Moving a window around the screen</a>
2300         <p>
2301         An operation we might want to do with windows is to move them
2302         to a different location. This can be done like this:
2303         </p>
2304         <pre class="code">
2305 const static uint32_t values[] = { 10, 20 };
2306
2307 /* The connection c and the window win are supposed to be defined */
2308
2309 /* Move the window to coordinates x = 10 and y = 20 */
2310 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y, values);
2311 </pre>
2312         <p>
2313         Note that when the window is moved, it might get partially
2314         exposed or partially hidden by other windows, and thus we
2315         might get <span class="code">Expose</span> events due to this
2316         operation.
2317         </p>
2318         <li class="subtitle"><a name="winsize">Resizing a window</a>
2319         <p>
2320         Yet another operation we can do is to change the size of a
2321         window. This is done using the following code:
2322         </p>
2323         <pre class="code">
2324 const static uint32_t values[] = { 200, 300 };
2325
2326 /* The connection c and the window win are supposed to be defined */
2327
2328 /* Resize the window to width = 10 and height = 20 */
2329 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2330 </pre>
2331         <p>
2332         We can also combine the move and resize operations using one
2333         single call to <span class="code">xcb_configure_window_t</span>:
2334         </p>
2335         <pre class="code">
2336 const static uint32_t values[] = { 10, 20, 200, 300 };
2337
2338 /* The connection c and the window win are supposed to be defined */
2339
2340 /* Move the window to coordinates x = 10 and y = 20 */
2341 /* and resize the window to width = 10 and height = 20 */
2342 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y | XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2343 </pre>
2344         <li class="subtitle"><a name="winstack">Changing windows stacking order: raise and lower</a>
2345         <p>
2346         Until now, we changed properties of a single window. We'll see
2347         that there are properties that relate to the window and other
2348         windows. One of them is the stacking order. That is, the order
2349         in which the windows are layered on top of each other. The
2350         front-most window is said to be on the top of the stack, while
2351         the back-most window is at the bottom of the stack. Here is
2352         how to manipulate our windows stack order:
2353         </p>
2354         <pre class="code">
2355 const static uint32_t values[] = { XCB_STACK_MODE_ABOVE };
2356
2357 /* The connection c and the window win are supposed to be defined */
2358
2359 /* Move the window on the top of the stack */
2360 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2361 </pre>
2362         <pre class="code">
2363 const static uint32_t values[] = { XCB_STACK_MODE_BELOW };
2364
2365 /* The connection c and the window win are supposed to be defined */
2366
2367 /* Move the window on the bottom of the stack */
2368 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2369 </pre>
2370         <li class="subtitle"><a name="wingetinfo">Getting information about a window</a>
2371         <p>
2372         Just like we can set various attributes of our windows, we can
2373         also ask the X server supply the current values of these
2374         attributes. For example, we can check where a window is
2375         located on the screen, what is its current size, whether it is
2376         mapped or not, etc. The structure that contains some of this
2377         information is
2378         </p>
2379         <pre class="code">
2380 typedef struct {
2381     uint8_t      response_type;
2382     uint8_t      depth;         /* depth of the window */
2383     uint16_t     sequence;
2384     uint32_t     length;
2385     xcb_window_t root;          /* Id of the root window *>
2386     int16_t      x;             /* X coordinate of the window's location */
2387     int16_t      y;             /* Y coordinate of the window's location */
2388     uint16_t     width;         /* Width of the window */
2389     uint16_t     height;        /* Height of the window */
2390     uint16_t     border_width;  /* Width of the window's border */
2391 } xcb_get_geometry_reply_t;
2392 </pre>
2393         <p>
2394         XCB fill this structure with two functions:
2395         </p>
2396         <pre class="code">
2397 xcb_get_geometry_cookie_t  xcb_get_geometry       (xcb_connection_t         *c,
2398                                                    xcb_drawable_t            drawable);
2399 xcb_get_geometry_reply_t  *xcb_get_geometry_reply (xcb_connection_t         *c,
2400                                                    xcb_get_geometry_cookie_t cookie,
2401                                                    xcb_generic_error_t     **e);
2402 </pre>
2403         <p>
2404         You use them as follows:
2405         </p>
2406         <pre class="code">
2407   xcb_connection_t         *c;
2408   xcb_drawable_t            win;
2409   xcb_get_geometry_reply_t *geom;
2410
2411   /* You initialize c and win */
2412
2413   geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2414
2415   /* Do something with the fields of geom */
2416
2417   free (geom);
2418 </pre>
2419         <p>
2420         Remark that you have to free the structure, as
2421         <span class="code">xcb_get_geometry_reply_t</span> allocates a
2422         newly one.
2423         </p>
2424         <p>
2425         One problem is that the returned location of the window is
2426         relative to its parent window. This makes these coordinates
2427         rather useless for any window manipulation functions, like
2428         moving it on the screen. In order to overcome this problem, we
2429         need to take a two-step operation. First, we find out the Id
2430         of the parent window of our window. We then translate the
2431         above relative coordinates to the screen coordinates.
2432         </p>
2433         <p>
2434         To get the Id of the parent window, we need this structure:
2435         </p>
2436         <pre class="code">
2437 typedef struct {
2438     uint8_t      response_type;
2439     uint8_t      pad0;
2440     uint16_t     sequence;
2441     uint32_t     length;
2442     xcb_window_t root;
2443     xcb_window_t parent;       /* Id of the parent window */
2444     uint16_t     children_len;
2445     uint8_t      pad1[14];
2446 } xcb_query_tree_reply_t;
2447 </pre>
2448         <p>
2449         To fill this structure, we use these two functions:
2450         </p>
2451         <pre class="code">
2452 xcb_query_tree_cookie_t xcb_query_tree       (xcb_connection_t        *c,
2453                                               xcb_window_t             window);
2454 xcb_query_tree_reply_t *xcb_query_tree_reply (xcb_connection_t        *c,
2455                                               xcb_query_tree_cookie_t  cookie,
2456                                               xcb_generic_error_t    **e);
2457 </pre>
2458         <p>
2459         The translated coordinates will be found in this structure:
2460         </p>
2461         <pre class="code">
2462 typedef struct {
2463     uint8_t      response_type;
2464     uint8_t      same_screen;
2465     uint16_t     sequence;
2466     uint32_t     length;
2467     xcb_window_t child;
2468     uint16_t     dst_x;        /* Translated x coordinate */
2469     uint16_t     dst_y;        /* Translated y coordinate */
2470 } xcb_translate_coordinates_reply_t;
2471 </pre>
2472         <p>
2473         As usual, we need two functions to fill this structure:
2474         </p>
2475         <pre class="code">
2476 xcb_translate_coordinates_cookie_t xcb_translate_coordinates       (xcb_connection_t                  *c,
2477                                                                     xcb_window_t                       src_window,
2478                                                                     xcb_window_t                       dst_window,
2479                                                                     int16_t                            src_x,
2480                                                                     int16_t                            src_y);
2481 xcb_translate_coordinates_reply_t *xcb_translate_coordinates_reply (xcb_connection_t                  *c,
2482                                                                     xcb_translate_coordinates_cookie_t cookie,
2483                                                                     xcb_generic_error_t              **e);
2484 </pre>
2485         <p>
2486         We use them as follows:
2487         </p>
2488         <pre class="code">
2489   xcb_connection_t                  *c;
2490   xcb_drawable_t                     win;
2491   xcb_get_geometry_reply_t          *geom;
2492   xcb_query_tree_reply_t            *tree;
2493   xcb_translate_coordinates_reply_t *trans;
2494
2495   /* You initialize c and win */
2496
2497   geom  = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2498   if (!geom)
2499     return 0;
2500
2501   tree  = xcb_query_tree_reply (c, xcb_query_tree (c, win), NULL);
2502   if (!tree)
2503     return 0;
2504
2505   trans = xcb_translate_coordinates_reply (c,
2506                                            xcb_translate_coordinates (c,
2507                                                                       win,
2508                                                                       tree-&gt;parent,
2509                                                                       geom-&gt;x, geom-&gt;y),
2510                                            NULL);
2511   if (!trans)
2512     return 0;
2513
2514   /* the translated coordinates are in trans-&gt;dst_x and trans-&gt;dst_y */
2515
2516   free (trans);
2517   free (tree);
2518   free (geom);
2519 </pre>
2520         <p>
2521         Of course, as for <span class="code">geom</span>,
2522         <span class="code">tree</span> and
2523         <span class="code">trans</span> have to be freed.
2524         </p>
2525         <p>
2526         The work is a bit hard, but XCB is a very low-level library.
2527         </p>
2528         <p>
2529         <b>TODO:</b> the utilization of these functions should be a
2530         prog, which displays the coordinates of the window.
2531         </p>
2532         <p>
2533         There is another structure that gives informations about our window:
2534         </p>
2535         <pre class="code">
2536 typedef struct {
2537     uint8_t        response_type;
2538     uint8_t        backing_store;
2539     uint16_t       sequence;
2540     uint32_t       length;
2541     xcb_visualid_t visual;                /* Visual of the window */
2542     uint16_t       _class;
2543     uint8_t        bit_gravity;
2544     uint8_t        win_gravity;
2545     uint32_t       backing_planes;
2546     uint32_t       backing_pixel;
2547     uint8_t        save_under;
2548     uint8_t        map_is_installed;
2549     uint8_t        map_state;             /* Map state of the window */
2550     uint8_t        override_redirect;
2551     xcb_colormap_t colormap;              /* Colormap of the window */
2552     uint32_t       all_event_masks;
2553     uint32_t       your_event_mask;
2554     uint16_t       do_not_propagate_mask;
2555 } xcb_get_window_attributes_reply_t;
2556 </pre>
2557         <p>
2558         XCB supplies these two functions to fill it:
2559         </p>
2560         <pre class="code">
2561 xcb_get_window_attributes_cookie_t xcb_get_window_attributes       (xcb_connection_t                  *c,
2562                                                                     xcb_window_t                       window);
2563 xcb_get_window_attributes_reply_t *xcb_get_window_attributes_reply (xcb_connection_t                  *c,
2564                                                                     xcb_get_window_attributes_cookie_t cookie,
2565                                                                     xcb_generic_error_t              **e);
2566 </pre>
2567         <p>
2568         You use them as follows:
2569         </p>
2570         <pre class="code">
2571   xcb_connection_t                  *c;
2572   xcb_drawable_t                     win;
2573   xcb_get_window_attributes_reply_t *attr;
2574
2575   /* You initialize c and win */
2576
2577   attr = xcb_get_window_attributes_reply (c, xcb_get_window_attributes (c, win), NULL);
2578
2579   if (!attr)
2580     return 0;
2581
2582   /* Do something with the fields of attr */
2583
2584   free (attr);
2585 </pre>
2586         <p>
2587         As for <span class="code">geom</span>,
2588         <span class="code">attr</span> has to be freed.
2589         </p>
2590       </ol>
2591       <li class="title"><a name="usecolor">Using colors to paint the rainbow</a>
2592       <p>
2593       Up until now, all our painting operation were done using black
2594       and white. We will (finally) see now how to draw using colors.
2595       </p>
2596       <ol>
2597         <li class="subtitle"><a name="colormap">Color maps</a>
2598         <p>
2599         In the beginning, there were not enough colors. Screen
2600         controllers could only support a limited number of colors
2601         simultaneously (initially 2, then 4, 16 and 256). Because of
2602         this, an application could not just ask to draw in a "light
2603         purple-red" color, and expect that color to be available. Each
2604         application allocated the colors it needed, and when all the
2605         color entries (4, 16, 256 colors) were in use, the next color
2606         allocation would fail.
2607         </p>
2608         <p>
2609         Thus, the notion of "a color map" was introduced. A color map
2610         is a table whose size is the same as the number of
2611         simultaneous colors a given screen controller. Each entry
2612         contained the RGB (Red, Green and Blue) values of a different
2613         color (all colors can be drawn using some combination of red,
2614         green and blue). When an application wants to draw on the
2615         screen, it does not specify which color to use. Rather, it
2616         specifies which color entry of some color map to be used
2617         during this drawing. Change the value in this color map entry
2618         and the drawing will use a different color.
2619         </p>
2620         <p>
2621         In order to be able to draw using colors that got something to
2622         do with what the programmer intended, color map allocation
2623         functions are supplied. You could ask to allocate entry for a
2624         color with a set of RGB values. If one already existed, you
2625         would get its index in the table. If none existed, and the
2626         table was not full, a new cell would be allocated to contain
2627         the given RGB values, and its index returned. If the table was
2628         full, the procedure would fail. You could then ask to get a
2629         color map entry with a color that is closest to the one you
2630         were asking for. This would mean that the actual drawing on
2631         the screen would be done using colors similar to what you
2632         wanted, but not the same.
2633         </p>
2634         <p>
2635         On today's more modern screens where one runs an X server with
2636         support for 16 million colors, this limitation looks a little
2637         silly, but remember that there are still older computers with
2638         older graphics cards out there. Using color map, support for
2639         these screen becomes transparent to you. On a display
2640         supporting 16 million colors, any color entry allocation
2641         request would succeed. On a display supporting a limited
2642         number of colors, some color allocation requests would return
2643         similar colors. It won't look as good, but your application
2644         would still work.
2645         </p>
2646         <li class="subtitle"><a name="colormapalloc">Allocating and freeing Color Maps</a>
2647         <p>
2648         When you draw using XCB, you can choose to use the standard
2649         color map of the screen your window is displayed on, or you
2650         can allocate a new color map and apply it to a window. In the
2651         latter case, each time the mouse moves onto your window, the
2652         screen color map will be replaced by your window's color map,
2653         and you'll see all the other windows on screen change their
2654         colors into something quite bizzare. In fact, this is the
2655         effect you get with X applications that use the "-install"
2656         command line option.
2657         </p>
2658         <p>
2659         In XCB, a color map is (as often in X) an Id:
2660         </p>
2661         <pre class="code">
2662 typedef struct {
2663     uint32_t xid;
2664 } xcb_colormap_t;
2665 </pre>
2666         <p>
2667         In order to access the screen's default color map, you just
2668         have to retrieve the <span class="code">default_colormap</span>
2669         field of the <span class="code">xcb_screen_t</span> structure
2670         (see Section
2671         <a href="#screen">Checking basic information about a connection</a>):
2672         </p>
2673         <pre class="code">
2674 #include &lt;stdio.h&gt;
2675
2676 #include &lt;X11/XCB/xcb.h&gt;
2677
2678 int
2679 main (int argc, char *argv[])
2680 {
2681   xcb_connection_t *c;
2682   xcb_screen_t     *screen;
2683   xcb_colormap_t    colormap;
2684
2685   /* Open the connection to the X server and get the first screen */
2686   c = xcb_connect (NULL, NULL);
2687   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2688
2689   colormap = screen-&gt;default_colormap;
2690
2691   return 0;
2692 }
2693 </pre>
2694         <p>
2695         This will return the color map used by default on the first
2696         screen (again, remember that an X server may support several
2697         different screens, each of which might have its own resources).
2698         </p>
2699         <p>
2700         The other option, that of allocating a new colormap, works as
2701         follows.  We first ask the X server to give an Id to our color
2702         map, with this function:
2703         </p>
2704         <pre class="code">
2705 xcb_colormap_t xcb_colormap_new (xcb_connection_t *c);
2706 </pre>
2707         <p>
2708         Then, we create the color map with
2709         </p>
2710         <pre class="code">
2711 xcb_void_cookie_t xcb_create_colormap (xcb_connection_t *c,       /* Pointer to the xcb_connection_t structure */
2712                                        uint8_t           alloc,   /* Colormap entries to be allocated (AllocNone or AllocAll) */
2713                                        xcb_colormap_t    mid,     /* Id of the color map */
2714                                        xcb_window_t      window,  /* Window on whose screen the colormap will be created */
2715                                        xcb_visualid_t    visual); /* Id of the visual supported by the screen */
2716 </pre>
2717         <p>
2718         Here is an example of creation of a new color map:
2719         </p>
2720         <pre class="code">
2721 #include &lt;X11/XCB/xcb.h&gt;
2722
2723 int
2724 main (int argc, char *argv[])
2725 {
2726   xcb_connection_t *c;
2727   xcb_screen_t     *screen;
2728   xcb_window_t      win;
2729   xcb_colormap_t    cmap
2730
2731   /* Open the connection to the X server and get the first screen */
2732   c = xcb_connect (NULL, NULL);
2733   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2734
2735   /* We create the window win here*/
2736
2737   cmap = xcb_colormap_new (c);
2738   xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen-&gt;root_visual);
2739
2740   return 0;
2741 }
2742 </pre>
2743         <p>
2744         Note that the window parameter is only used to allow the X
2745         server to create the color map for the given screen. We can
2746         then use this color map for any window drawn on the same screen.
2747         </p>
2748         <p>
2749         To free  a color map, it suffices to use this function:
2750         </p>
2751         <pre class="code">
2752 xcb_void_cookie_t xcb_free_colormap (xcb_connection_t *c,   /* The connection */
2753                                      xcb_colormap_t cmap);  /* The color map */
2754 </pre>
2755         <div class="comp">
2756           <div class="title">
2757             Comparison Xlib/XCB
2758           </div>
2759           <div class="xlib">
2760             <ul>
2761               <li>XCreateColormap ()
2762             </ul>
2763           </div>
2764           <div class="xcb">
2765             <ul>
2766               <li>xcb_colormap_new ()
2767               <li>xcb_create_colormap ()
2768             </ul>
2769           </div>
2770           <div class="xlib">
2771             <ul>
2772               <li>XFreeColormap ()
2773             </ul>
2774           </div>
2775           <div class="xcb">
2776             <ul>
2777               <li>xcb_free_colormap ()
2778             </ul>
2779           </div>
2780         </div>
2781         <br>
2782         <li class="subtitle"><a name="alloccolor">Allocating and freeing a color entry</a>
2783         <p>
2784         Once we got access to some color map, we can start allocating
2785         colors. The informations related to a color are stored in the
2786         following structure:
2787         </p>
2788         <pre class="code">
2789 typedef struct {
2790     uint8_t  response_type;
2791     uint8_t  pad0;
2792     uint16_t sequence;
2793     uint32_t length;
2794     uint16_t red;          /* The red component   */
2795     uint16_t green;        /* The green component */
2796     uint16_t blue;         /* The blue component  */
2797     uint8_t  pad1[2];
2798     uint32_t pixel;        /* The entry in the color map, supplied by the X server */
2799 } xcb_alloc_color_reply_t;
2800 </pre>
2801       <p>
2802       XCB supplies these two functions to fill it:
2803       </p>
2804       <pre class="code">
2805 xcb_alloc_color_cookie_t xcb_alloc_color       (xcb_connection_t        *c,
2806                                                 xcb_colormap_t           cmap,
2807                                                 uint16_t                 red,
2808                                                 uint16_t                 green,
2809                                                 uint16_t                 blue);
2810 xcb_alloc_color_reply_t *xcb_alloc_color_reply (xcb_connection_t        *c,
2811                                                 xcb_alloc_color_cookie_t cookie,
2812                                                 xcb_generic_error_t    **e);
2813 </pre>
2814       <p>
2815       The fuction <span class="code">xcb_alloc_color()</span> takes the
2816       3 RGB components as parameters (red, green and blue). Here is an
2817       example of using these functions:
2818       </p>
2819       <pre class="code">
2820 #include &lt;malloc.h&gt;
2821
2822 #include &lt;X11/XCB/xcb.h&gt;
2823
2824 int
2825 main (int argc, char *argv[])
2826 {
2827   xcb_connection_t        *c;
2828   xcb_screen_t            *screen;
2829   xcb_window_t             win;
2830   xcb_colormap_t           cmap;
2831   xcb_alloc_color_reply_t *rep;
2832
2833   /* Open the connection to the X server and get the first screen */
2834   c = xcb_connect (NULL, NULL);
2835   screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2836
2837   /* We create the window win here*/
2838
2839   cmap = xcb_colormap_new (c);
2840   xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen-&gt;root_visual);
2841
2842   rep = xcb_alloc_color_reply (c, xcb_alloc_color (c, cmap, 65535, 0, 0), NULL);
2843
2844   if (!rep)
2845     return 0;
2846
2847   /* Do something with r-&gt;pixel or the components */
2848
2849   free (rep);
2850
2851   return 0;
2852 }
2853 </pre>
2854       <p>
2855       As <span class="code">xcb_alloc_color_reply()</span> allocates
2856       memory, you have to free <span class="code">rep</span>.
2857       </p>
2858       <p>
2859       <b>TODO</b>: Talk about freeing colors.
2860       </p>
2861       </ol>
2862       <li class="title"><a name="pixmaps">X Bitmaps and Pixmaps</a>
2863       <p>
2864       One thing many so-called "Multi-Media" applications need to do,
2865       is display images. In the X world, this is done using bitmaps
2866       and pixmaps. We have already seen some usage of them when
2867       setting an icon for our application. Lets study them further,
2868       and see how to draw these images inside a window, along side the
2869       simple graphics and text we have seen so far.
2870       </p>
2871       <p>
2872       One thing to note before delving further, is that XCB (nor Xlib)
2873       supplies no means of manipulating popular image formats, such as
2874       gif, png, jpeg or tiff. It is up to the programmer (or to higher
2875       level graphics libraries) to translate these image formats into
2876       formats that the X server is familiar with (x bitmaps and x
2877       pixmaps).
2878       </p>
2879       <ol>
2880         <li class="subtitle"><a name="pixmapswhat">What is a X Bitmap? An X Pixmap?</a>
2881         <p>
2882         An X bitmap is a two-color image stored in a format specific
2883         to the X window system. When stored in a file, the bitmap data
2884         looks like a C source file. It contains variables defining the
2885         width and the height of the bitmap, an array containing the
2886         bit values of the bitmap (the size of the array is
2887         (width+7)/8*height and the bit and byte order are LSB), and
2888         an optional hot-spot location (that will
2889         be explained later, when discussing mouse cursors).
2890         </p>
2891         <p>
2892         An X pixmap is a format used to stored images in the memory of
2893         an X server. This format can store both black and white images
2894         (such as x bitmaps) as well as color images. It is the only
2895         image format supported by the X protocol, and any image to be
2896         drawn on screen, should be first translated into this format.
2897         </p>
2898         <p>
2899         In actuality, an X pixmap can be thought of as a window that
2900         does not appear on the screen. Many graphics operations that
2901         work on windows, will also work on pixmaps. Indeed, the type
2902         of X pixmap in XCB is an Id like a window:
2903         </p>
2904         <pre class="code">
2905 typedef struct {
2906     uint32_t xid;
2907 } xcb_pixmap_t;
2908 </pre>
2909         <p>
2910         In order to make the difference between a window and a pixmap,
2911         XCB introduces a drawable type, which is a <b>union</b>
2912         </p>
2913         <pre class="code">
2914 typedef union {
2915     xcb_window_t window;
2916     xcb_pixmap_t pixmap;
2917 } xcb_drawable_t;
2918 </pre>
2919         <p>
2920         in order to avoid confusion between a window and a pixmap. The
2921         operations that will work the same on a window or a pixmap
2922         will require a <span class="code">xcb_drawable_t</span>
2923         </p>
2924         <div class="emph">
2925         <p>
2926         Remark: In Xlib, there is no specific difference between a
2927         <span class="code">Drawable</span>, a
2928         <span class="code">Pixmap</span> or a
2929         <span class="code">Window</span>: all are 32 bit long
2930         integer.  XCB wraps all these different IDs in structures to
2931         provide some measure of type-safety.
2932         </p>
2933         </div>
2934         <li class="subtitle"><a name="pixmapscreate">Creating a pixmap</a>
2935         <p>
2936         Sometimes we want to create an un-initialized pixmap, so we
2937         can later draw into it. This is useful for image drawing
2938         programs (creating a new empty canvas will cause the creation
2939         of a new pixmap on which the drawing can be stored). It is
2940         also useful when reading various image formats: we load the
2941         image data into memory, create a pixmap on the server, and
2942         then draw the decoded image data onto that pixmap.
2943         </p>
2944         <p>
2945         To create a new pixmap, we first ask the X server to give an
2946         Id to our pixmap, with this function:
2947         </p>
2948         <pre class="code">
2949 xcb_pixmap_t xcb_pixmap_new (xcb_connection_t *c);
2950 </pre>
2951         <p>
2952          Then, XCB supplies the following function to create new pixmaps:
2953         </p>
2954         <pre class="code">
2955 xcb_void_cookie_t xcb_create_pixmap (xcb_connection_t *c,         /* Pointer to the xcb_connection_t structure */
2956                                      uint8_t           depth,     /* Depth of the screen */
2957                                      xcb_pixmap_t      pid,       /* Id of the pixmap */
2958                                      xcb_drawable_t    drawable,
2959                                      uint16_t          width,     /* Width of the window (in pixels) */
2960                                      uint16_t          height);   /* Height of the window (in pixels) */
2961 </pre>
2962         <p>
2963         <b>TODO</b>: Explain the drawable parameter, and give an
2964         example (like <a href="xpoints.c">xpoints.c</a>)
2965         </p>
2966         <li class="subtitle"><a name="pixmapsdraw"></a>Drawing a pixmap in a window
2967         <p>
2968         Once we got a handle to a pixmap, we can draw it on some
2969         window, using the following function:
2970         </p>
2971         <pre class="code">
2972 xcb_void_cookie_t xcb_copy_area (xcb_connection_t *c,             /* Pointer to the xcb_connection_t structure */
2973                                  xcb_drawable_t    src_drawable,  /* The Drawable we want to paste */
2974                                  xcb_drawable_t    dst_drawable,  /* The Drawable on which we copy the previous Drawable */
2975                                  xcb_gcontext_t    gc,            /* A Graphic Context */
2976                                  int16_t          src_x,          /* Top left x coordinate of the region we want to copy */
2977                                  int16_t          src_y,          /* Top left y coordinate of the region we want to copy */
2978                                  int16_t          dst_x,          /* Top left x coordinate of the region where we want to copy */
2979                                  int16_t          dst_y,          /* Top left y coordinate of the region where we want to copy */
2980                                  uint16_t         width,          /* Width of the region we want to copy */
2981                                  uint16_t         height);        /* Height of the region we want to copy */
2982 </pre>
2983         <p>
2984         As you can see, we could copy the whole pixmap, as well as
2985         only a given rectangle of the pixmap. This is useful to
2986         optimize the drawing speed: we could copy only what we have
2987         modified in the pixmap.
2988         </p>
2989         <p>
2990         <b>One important note should be made</b>: it is possible to
2991         create pixmaps with different depths on the same screen. When
2992         we perform copy operations (a pixmap onto a window, etc), we
2993         should make sure that both source and target have the same
2994         depth. If they have a different depth, the operation would
2995         fail. The exception to this is if we copy a specific bit plane
2996         of the source pixmap using the
2997         <span class="code">xcb_copy_plane_t</span> function. In such an
2998         event, we can copy a specific plane to the target window (in
2999         actuality, setting a specific bit in the color of each pixel
3000         copied). This can be used to generate strange graphic effects
3001         in a window, but that is beyond the scope of this tutorial.
3002         </p>
3003         <li class="subtitle"><a name="pixmapsfree"></a>Freeing a pixmap
3004         <p>
3005         Finally, when we are done using a given pixmap, we should free
3006         it, in order to free resources of the X server. This is done
3007         using this function:
3008         </p>
3009         <pre class="code">
3010 xcb_void_cookie_t xcb_free_pixmap (xcb_connection_t *c,        /* Pointer to the xcb_connection_t structure */
3011                                    xcb_pixmap_t      pixmap);  /* A given pixmap */
3012 </pre>
3013         <p>
3014         Of course, after having freed it, we must not try accessing
3015         the pixmap again.
3016         </p>
3017         <p>
3018         <b>TODO</b>: Give an example, or a link to xpoints.c
3019         </p>
3020       </ol>
3021       <li class="title"><a name="mousecursor">Messing with the mouse cursor</a>
3022       <p>
3023       It it possible to modify the shape of the mouse pointer (also
3024       called the X pointer) when in certain states, as we otfen see in
3025       programs. For example, a busy application would often display
3026       the sand clock over its main window, to give the user a visual
3027       hint that he should wait. Let's see how we can change the mouse
3028       cursor of our windows.
3029       </p>
3030       <ol>
3031         <li class="subtitle"><a name="mousecursorcreate">Creating and destroying a mouse cursor</a>
3032         <p>
3033         There are two methods for creating cursors. One of them is by
3034         using a set of predefined cursors, that are supplied by the X
3035         server, the other is by using a user-supplied bitmap.
3036         </p>
3037         <p>
3038         In the first method, we use a special font named "cursor", and
3039         the function <span class="code">xcb_create_glyph_cursor</span>:
3040         </p>
3041         <pre class="code">
3042 xcb_void_cookie_t xcb_create_glyph_cursor_checked (xcb_connection_t *c,
3043                                                    xcb_cursor_t      cid,
3044                                                    xcb_font_t        source_font, /* font for the source glyph */
3045                                                    xcb_font_t        mask_font,   /* font for the mask glyph or XCB_NONE */
3046                                                    uint16_t          source_char, /* character glyph for the source */
3047                                                    uint16_t          mask_char,   /* character glyph for the mask */
3048                                                    uint16_t          fore_red,    /* red value for the foreground of the source */
3049                                                    uint16_t          fore_green,  /* green value for the foreground of the source */
3050                                                    uint16_t          fore_blue,   /* blue value for the foreground of the source */
3051                                                    uint16_t          back_red,    /* red value for the background of the source */
3052                                                    uint16_t          back_green,  /* green value for the background of the source */
3053                                                    uint16_t          back_blue)   /* blue value for the background of the source */
3054 </pre>
3055         <p>
3056         <b>TODO</b>: Describe <span class="code">source_char</span>
3057         and <span class="code">mask_char</span>, for example by giving
3058         an example on how to get the values. There is a list there:
3059         <a href="http://tronche.com/gui/x/xlib/appendix/b/">X Font Cursors</a>
3060         </p>
3061         <p>
3062         So we first open that font (see <a href="#loadfont">Loading a Font</a>)
3063         and create the new cursor. As for every X ressource, we have to
3064         ask for an X id with <span class="code">xcb_cursor_new</span>
3065         first:
3066         </p>
3067         <pre class="code">
3068 xcb_font_t           font;
3069 xcb_cursor_t         cursor;
3070
3071 /* The connection is set */
3072
3073 font = xcb_font_new (conn);
3074 xcb_open_font (conn, font, strlen ("cursor"), "cursor");
3075
3076 cursor = xcb_cursor_new (conn);
3077 xcb_create_glyph_cursor (conn, cursor, font, font,
3078                          58, 58 + 1,
3079                          0, 0, 0,
3080                          0, 0, 0);
3081 </pre>
3082         <p>
3083         We have created the cursor "right hand" by specifying 58 to
3084         the <span class="code">source_fon</span>t argument and 58 + 1
3085         to the <span class="code">mask_font</span>.
3086         </p>
3087         <p>
3088         The cursor is destroyed by using the function
3089         </p>
3090         <pre class="code">
3091 xcb_void_cookie_t xcb_free_cursor (xcb_connection_t *c,
3092                                    xcb_cursor_t      cursor);
3093 </pre>
3094         <p>
3095         In the second method, we create a new cursor by using a pair
3096         of pixmaps, with depth of one (that is, two colors
3097         pixmaps). One pixmap defines the shape of the cursor, while
3098         the other works as a mask, specifying which pixels of the
3099         cursor will be actually drawn. The rest of the pixels will be
3100         transparent.
3101         </p>
3102         <p>
3103         <b>TODO</b>: give an example.
3104         </p>
3105         <li class="subtitle"><a name="mousecursorset">Setting a window's mouse cursor</a>
3106         <p>
3107         Once the cursor is created, we can modify the cursor of our
3108         window by using <span class="code">xcb_change_window_attributes</span>
3109         and using the <span class="code">XCB_CWCURSOR</span> attribute:
3110         </p>
3111         <pre class="code">
3112 uint32_t mask;
3113 uint32_t value_list;
3114
3115 /* The connection and window are set */
3116 /* The cursor is already created */
3117
3118 mask = XCB_CWCURSOR;
3119 value_list = cursor.xid;
3120 xcb_change_window_attributes (conn, window, mask, &amp;value_list);
3121 </pre>
3122         <p>
3123         Of course, the cursor and the font must be freed.
3124         </p>
3125         <li class="subtitle"><a name="mousecursorexample">Complete example</a>
3126         <p>
3127         <b>TODO</b>: to do...
3128         </p>
3129       </ol>
3130       <li class="title"><a name="translation">Translation of basic Xlib functions and macros</a>
3131       <p>
3132       The problem when you want to port an Xlib program to XCB is that
3133       you don't know if the Xlib function that you want to "translate"
3134       is a X Window one or an Xlib macro. In that section, we describe
3135       a way to translate the usual functions or macros that Xlib
3136       provides. It's usually just a member of a structure.
3137       </p>
3138       <ol>
3139         <li class="subtitle"><a name="displaystructure">Members of the Display structure</a>
3140         <p>
3141         In this section, we look at how to translate the macros that
3142         return some members of the <span class="code">Display</span>
3143         structure. They are obtained by using a function that requires a
3144         <span class="code">xcb_connection_t *</span> or a member of the
3145         <span class="code">xcb_setup_t</span> structure
3146         (via the function <span class="code">xcb_get_setup_t</span>), or
3147         a function that requires that structure.
3148         </p>
3149         <ol>
3150           <li class="subtitle"><a name="ConnectionNumber">ConnectionNumber</a>
3151           <p>
3152           This number is the file descriptor that connects the client
3153           to the server. You just have to use that function:
3154           </p>
3155           <pre class="code">
3156 int xcb_get_file_descriptor (xcb_connection_t *c);
3157 </pre>
3158           <li class="subtitle"><a name="DefaultScreen"></a>DefaultScreen
3159           <p>
3160           That number is not stored by XCB. It is returned in the
3161           second parameter of the function <span class="code"><a href="#openconn">xcb_connect</a></span>.
3162           Hence, you have to store it yourself if you want to use
3163           it. Then, to get the <span class="code">xcb_screen_t</span>
3164           structure, you have to iterate on the screens.
3165           The equivalent function of the Xlib's
3166           <span class="code">ScreenOfDisplay</span> function can be
3167           found <a href="#ScreenOfDisplay">below</a>. This is also provided in the
3168           xcb_aux_t library as <span class="code">xcb_aux_get_screen()</span>. OK, here is the
3169           small piece of code to get that number:
3170           </p>
3171           <pre class="code">
3172 xcb_connection_t *c;
3173 int               screen_default_nbr;
3174
3175 /* you pass the name of the display you want to xcb_connect_t */
3176
3177 c = xcb_connect (display_name, &amp;screen_default_nbr);
3178
3179 /* screen_default_nbr contains now the number of the default screen */
3180 </pre>
3181           <li class="subtitle"><a name="QLength"></a>QLength
3182           <p>
3183           Not documented yet.
3184           </p>
3185           <p>
3186           However, this points out a basic difference in philosophy between
3187           Xlib and XCB.  Xlib has several functions for filtering and
3188           manipulating the incoming and outgoing X message queues.  XCB
3189           wishes to hide this as much as possible from the user, which
3190           allows for more freedom in implementation strategies.
3191           </p>
3192           <li class="subtitle"><a name="ScreenCount"></a>ScreenCount
3193           <p>
3194           You get the count of screens with the functions
3195           <span class="code">xcb_get_setup_t</span>
3196           and
3197           <span class="code">xcb_setup_roots_iterator_t</span>
3198           (if you need to iterate):
3199           </p>
3200           <pre class="code">
3201 xcb_connection_t *c;
3202 int               screen_count;
3203
3204 /* you init the connection */
3205
3206 screen_count = xcb_setup_roots_iterator (xcb_get_setup (c)).rem;
3207
3208 /* screen_count contains now the count of screens */
3209 </pre>
3210           <p>
3211           If you don't want to iterate over the screens, a better way
3212           to get that number is to use
3213           <span class="code">xcb_setup_roots_length_t</span>:
3214           </p>
3215           <pre class="code">
3216 xcb_connection_t *c;
3217 int               screen_count;
3218
3219 /* you init the connection */
3220
3221 screen_count = xcb_setup_roots_length (xcb_get_setup (c));
3222
3223 /* screen_count contains now the count of screens */
3224 </pre>
3225           <li class="subtitle"><a name="ServerVendor"></a>ServerVendor
3226           <p>
3227           You get the name of the vendor of the server hardware with
3228           the functions <span class="code">xcb_get_setup_t</span>
3229           and
3230           <span
3231           class="code">xcb_setup_vendor_t</span>. Beware
3232           that, unlike Xlib, the string returned by XCB is not
3233           necessarily null-terminaled:
3234           </p>
3235           <pre class="code">
3236 xcb_connection_t *c;
3237 char             *vendor = NULL;
3238 int               length;
3239
3240 /* you init the connection */
3241 length = xcb_setup_vendor_length (xcb_get_setup (c));
3242 vendor = (char *)malloc (length + 1);
3243 if (vendor)
3244 memcpy (vendor, xcb_setup_vendor (xcb_get_setup (c)), length);
3245 vendor[length] = '\0';
3246
3247 /* vendor contains now the name of the vendor. Must be freed when not used anymore */
3248 </pre>
3249           <li class="subtitle"><a name="ProtocolVersion"></a>ProtocolVersion
3250           <p>
3251           You get the major version of the protocol in the
3252           <span class="code">xcb_setup_t</span>
3253           structure, with the function <span class="code">xcb_get_setup_t</span>:
3254           </p>
3255           <pre class="code">
3256 xcb_connection_t *c;
3257 uint16_t          protocol_major_version;
3258
3259 /* you init the connection */
3260
3261 protocol_major_version = xcb_get_setup (c)-&gt;protocol_major_version;
3262
3263 /* protocol_major_version contains now the major version of the protocol */
3264 </pre>
3265           <li class="subtitle"><a name="ProtocolRevision"></a>ProtocolRevision
3266           <p>
3267           You get the minor version of the protocol in the
3268           <span class="code">xcb_setup_t</span>
3269           structure, with the function <span class="code">xcb_get_setup_t</span>:
3270           </p>
3271           <pre class="code">
3272 xcb_connection_t *c;
3273 uint16_t          protocol_minor_version;
3274
3275 /* you init the connection */
3276
3277 protocol_minor_version = xcb_get_setup (c)-&gt;protocol_minor_version;
3278
3279 /* protocol_minor_version contains now the minor version of the protocol */
3280 </pre>
3281           <li class="subtitle"><a name="VendorRelease"></a>VendorRelease
3282           <p>
3283           You get the number of the release of the server hardware in the
3284           <span class="code">xcb_setup_t</span>
3285           structure, with the function <span class="code">xcb_get_setup_t</span>:
3286           </p>
3287           <pre class="code">
3288 xcb_connection_t *c;
3289 uint32_t          release_number;
3290
3291 /* you init the connection */
3292
3293 release_number = xcb_get_setup (c)-&gt;release_number;
3294
3295 /* release_number contains now the number of the release of the server hardware */
3296 </pre>
3297           <li class="subtitle"><a name="DisplayString"></a>DisplayString
3298           <p>
3299           The name of the display is not stored in XCB. You have to
3300           store it by yourself.
3301           </p>
3302           <li class="subtitle"><a name="BitmapUnit"></a>BitmapUnit
3303           <p>
3304           You get the bitmap scanline unit in the
3305           <span class="code">xcb_setup_t</span>
3306           structure, with the function <span class="code">xcb_get_setup_t</span>:
3307           </p>
3308           <pre class="code">
3309 xcb_connection_t *c;
3310 uint8_t           bitmap_format_scanline_unit;
3311
3312 /* you init the connection */
3313
3314 bitmap_format_scanline_unit = xcb_get_setup (c)-&gt;bitmap_format_scanline_unit;
3315
3316 /* bitmap_format_scanline_unit contains now the bitmap scanline unit */
3317 </pre>
3318           <li class="subtitle"><a name="BitmapBitOrder"></a>BitmapBitOrder
3319           <p>
3320           You get the bitmap bit order in the
3321           <span class="code">xcb_setup_t</span>
3322           structure, with the function <span class="code">xcb_get_setup_t</span>:
3323           </p>
3324           <pre class="code">
3325 xcb_connection_t *c;
3326 uint8_t           bitmap_format_bit_order;
3327
3328 /* you init the connection */
3329
3330 bitmap_format_bit_order = xcb_get_setup (c)-&gt;bitmap_format_bit_order;
3331
3332 /* bitmap_format_bit_order contains now the bitmap bit order */
3333 </pre>
3334           <li class="subtitle"><a name="BitmapPad"></a>BitmapPad
3335           <p>
3336           You get the bitmap scanline pad in the
3337           <span class="code">xcb_setup_t</span>
3338           structure, with the function <span class="code">xcb_get_setup_t</span>:
3339           </p>
3340           <pre class="code">
3341 xcb_connection_t *c;
3342 uint8_t           bitmap_format_scanline_pad;
3343
3344 /* you init the connection */
3345
3346 bitmap_format_scanline_pad = xcb_get_setup (c)-&gt;bitmap_format_scanline_pad;
3347
3348 /* bitmap_format_scanline_pad contains now the bitmap scanline pad */
3349 </pre>
3350           <li class="subtitle"><a name="ImageByteOrder"></a>ImageByteOrder
3351           <p>
3352           You get the image byte order in the
3353           <span class="code">xcb_setup_t</span>
3354           structure, with the function <span class="code">xcb_get_setup_t</span>:
3355           </p>
3356           <pre class="code">
3357 xcb_connection_t *c;
3358 uint8_t           image_byte_order;
3359
3360 /* you init the connection */
3361
3362 image_byte_order = xcb_get_setup (c)-&gt;image_byte_order;
3363
3364 /* image_byte_order contains now the image byte order */
3365 </pre>
3366         </ol>
3367       <li class="subtitle"><a name="screenofdisplay">ScreenOfDisplay related functions</a>
3368       <p>
3369       in Xlib, <span class="code">ScreenOfDisplay</span> returns a
3370       <span class="code">Screen</span> structure that contains
3371       several characteristics of your screen. XCB has a similar
3372       structure (<span class="code">xcb_screen_t</span>),
3373       but the way to obtain it is a bit different. With
3374       Xlib, you just provide the number of the screen and you grab it
3375       from an array. With XCB, you iterate over all the screens to
3376       obtain the one you want. The complexity of this operation is
3377       O(n). So the best is to store this structure if you use
3378       it often. See <a href="#ScreenOfDisplay">screen_of_display</a> just below.
3379       </p>
3380       <p>
3381       Xlib provides generally two functions to obtain the characteristics
3382       related to the screen. One with the display and the number of
3383       the screen, which calls <span class="code">ScreenOfDisplay</span>,
3384       and the other that uses the <span class="code">Screen</span> structure.
3385       This might be a bit confusing. As mentioned above, with XCB, it
3386       is better to store the <span class="code">xcb_screen_t</span>
3387       structure. Then, you have to read the members of this
3388       structure. That's why the Xlib functions are put by pairs (or
3389       more) as, with XCB, you will use the same code.
3390       </p>
3391         <ol>
3392           <li class="subtitle"><a name="ScreenOfDisplay">ScreenOfDisplay</a>
3393           <p>
3394           This function returns the Xlib <span class="code">Screen</span>
3395           structure. With XCB, you iterate over all the screens and
3396           once you get the one you want, you return it:
3397           </p>
3398           <pre class="code"><a name="ScreenOfDisplay"></a>
3399 xcb_screen_t *screen_of_display (xcb_connection_t *c,
3400                                  int               screen)
3401 {
3402   xcb_screen_iterator_t iter;
3403
3404   iter = xcb_setup_roots_iterator (xcb_get_setup (c));
3405   for (; iter.rem; --screen, xcb_screen_next (&amp;iter))
3406     if (screen == 0)
3407       return iter.data;
3408
3409   return NULL;
3410 }
3411 </pre>
3412           <p>
3413           As mentioned above, you might want to store the value
3414           returned by this function.
3415           </p>
3416           <p>
3417           All the functions below will use the result of that
3418           function, as they just grab a specific member of the
3419           <span class="code">xcb_screen_t</span> structure.
3420           </p>
3421           <li class="subtitle"><a name="DefaultScreenOfDisplay"></a>DefaultScreenOfDisplay
3422           <p>
3423           It is the default screen that you obtain when you connect to
3424           the X server. It suffices to call the <a href="#ScreenOfDisplay">screen_of_display</a>
3425           function above with the connection and the number of the
3426           default screen.
3427           </p>
3428           <pre class="code">
3429 xcb_connection_t *c;
3430 int               screen_default_nbr;
3431 xcb_screen_t     *default_screen;  /* the returned default screen */
3432
3433 /* you pass the name of the display you want to xcb_connect_t */
3434
3435 c = xcb_connect (display_name, &amp;screen_default_nbr);
3436 default_screen = screen_of_display (c, screen_default_nbr);
3437
3438 /* default_screen contains now the default root window, or a NULL window if no screen is found */
3439 </pre>
3440           <li class="subtitle"><a name="RootWindow">RootWindow / RootWindowOfScreen</a>
3441           <p>
3442           </p>
3443           <pre class="code">
3444 xcb_connection_t *c;
3445 xcb_screen_t     *screen;
3446 int               screen_nbr;
3447 xcb_window_t      root_window = { 0 };  /* the returned window */
3448
3449 /* you init the connection and screen_nbr */
3450
3451 screen = screen_of_display (c, screen_nbr);
3452 if (screen)
3453   root_window = screen-&gt;root;
3454
3455 /* root_window contains now the root window, or a NULL window if no screen is found */
3456 </pre>
3457           <li class="subtitle"><a name="DefaultRootWindow">DefaultRootWindow</a>
3458           <p>
3459           It is the root window of the default screen. So, you call
3460           <a name="ScreenOfDisplay">ScreenOfDisplay</a> with the
3461           default screen number and you get the
3462           <a href="#RootWindow">root window</a> as above:
3463           </p>
3464           <pre class="code">
3465 xcb_connection_t *c;
3466 xcb_screen_t     *screen;
3467 int               screen_default_nbr;
3468 xcb_window_t      root_window = { 0 };  /* the returned root window */
3469
3470 /* you pass the name of the display you want to xcb_connect_t */
3471
3472 c = xcb_connect (display_name, &amp;screen_default_nbr);
3473 screen = screen_of_display (c, screen_default_nbr);
3474 if (screen)
3475   root_window = screen-&gt;root;
3476
3477 /* root_window contains now the default root window, or a NULL window if no screen is found */
3478 </pre>
3479           <li class="subtitle"><a name="DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
3480           <p>
3481           While a Visual is, in Xlib, a structure, in XCB, there are
3482           two types: <span class="code">xcb_visualid_t</span>, which is
3483           the Id of the visual, and <span class="code">xcb_visualtype_t</span>,
3484           which corresponds to the Xlib Visual. To get the Id of the
3485           visual of a screen, just get the
3486            <span class="code">root_visual</span>
3487            member of a <span class="code">xcb_screen_t</span>:
3488           </p>
3489           <pre class="code">
3490 xcb_connection_t *c;
3491 xcb_screen_t     *screen;
3492 int               screen_nbr;
3493 xcb_visualid_t    root_visual = { 0 };    /* the returned visual Id */
3494
3495 /* you init the connection and screen_nbr */
3496
3497 screen = screen_of_display (c, screen_nbr);
3498 if (screen)
3499   root_visual = screen-&gt;root_visual;
3500
3501 /* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
3502 </pre>
3503           <p>
3504           To get the <span class="code">xcb_visualtype_t</span>
3505           structure, it's a bit less easy. You have to get the
3506           <span class="code">xcb_screen_t</span> structure that you want,
3507           get its <span class="code">root_visual</span> member,
3508           then iterate over the <span class="code">xcb_depth_t</span>s
3509           and the <span class="code">xcb_visualtype_t</span>s, and compare
3510           the <span class="code">xcb_visualid_t</span> of these <span class="code">xcb_visualtype_t</span>s:
3511           with <span class="code">root_visual</span>:
3512           </p>
3513           <pre class="code">
3514 xcb_connection_t *c;
3515 xcb_screen_t     *screen;
3516 int               screen_nbr;
3517 xcb_visualid_t    root_visual = { 0 };
3518 xcb_visualtype_t  *visual_type = NULL;    /* the returned visual type */
3519
3520 /* you init the connection and screen_nbr */
3521
3522 screen = screen_of_display (c, screen_nbr);
3523 if (screen) {
3524   xcb_depth_iterator_t depth_iter;
3525
3526   depth_iter = xcb_screen_allowed_depths_iterator (screen);
3527   for (; depth_iter.rem; xcb_depth_next (&amp;depth_iter)) {
3528     xcb_visualtype_iterator_t visual_iter;
3529
3530     visual_iter = xcb_depth_visuals_iterator (depth_iter.data);
3531     for (; visual_iter.rem; xcb_visualtype_next (&amp;visual_iter)) {
3532       if (screen-&gt;root_visual.id == visual_iter.data-&gt;visual_id.id) {
3533         visual_type = visual_iter.data;
3534         break;
3535       }
3536     }
3537   }
3538 }
3539
3540 /* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */
3541 </pre>
3542           <li class="subtitle"><a name="DefaultGC">DefaultGC / DefaultGCOfScreen</a>
3543           <p>
3544           This default Graphic Context is just a newly created Graphic
3545           Context, associated to the root window of a
3546           <span class="code">xcb_screen_t</span>,
3547           using the black white pixels of that screen:
3548           </p>
3549           <pre class="code">
3550 xcb_connection_t *c;
3551 xcb_screen_t     *screen;
3552 int               screen_nbr;
3553 xcb_gcontext_t    gc = { 0 };    /* the returned default graphic context */
3554
3555 /* you init the connection and screen_nbr */
3556
3557 screen = screen_of_display (c, screen_nbr);
3558 if (screen) {
3559   xcb_drawable_t draw;
3560   uint32_t       mask;
3561   uint32_t       values[2];
3562
3563   gc = xcb_gcontext_new (c);
3564   draw.window = screen-&gt;root;
3565   mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND;
3566   values[0] = screen-&gt;black_pixel;
3567   values[1] = screen-&gt;white_pixel;
3568   xcb_create_gc (c, gc, draw, mask, values);
3569 }
3570
3571 /* gc contains now the default graphic context */
3572 </pre>
3573           <li class="subtitle"><a name="BlackPixel">BlackPixel / BlackPixelOfScreen</a>
3574           <p>
3575           It is the Id of the black pixel, which is in the structure
3576           of an <span class="code">xcb_screen_t</span>.
3577           </p>
3578           <pre class="code">
3579 xcb_connection_t *c;
3580 xcb_screen_t     *screen;
3581 int               screen_nbr;
3582 uint32_t          black_pixel = 0;    /* the returned black pixel */
3583
3584 /* you init the connection and screen_nbr */
3585
3586 screen = screen_of_display (c, screen_nbr);
3587 if (screen)
3588   black_pixel = screen-&gt;black_pixel;
3589
3590 /* black_pixel contains now the value of the black pixel, or 0 if no screen is found */
3591 </pre>
3592           <li class="subtitle"><a name="WhitePixel">WhitePixel / WhitePixelOfScreen</a>
3593           <p>
3594           It is the Id of the white pixel, which is in the structure
3595           of an <span class="code">xcb_screen_t</span>.
3596           </p>
3597           <pre class="code">
3598 xcb_connection_t *c;
3599 xcb_screen_t     *screen;
3600 int               screen_nbr;
3601 uint32_t          white_pixel = 0;    /* the returned white pixel */
3602
3603 /* you init the connection and screen_nbr */
3604
3605 screen = screen_of_display (c, screen_nbr);
3606 if (screen)
3607   white_pixel = screen-&gt;white_pixel;
3608
3609 /* white_pixel contains now the value of the white pixel, or 0 if no screen is found */
3610 </pre>
3611           <li class="subtitle"><a name="DisplayWidth">DisplayWidth / WidthOfScreen</a>
3612           <p>
3613           It is the width in pixels of the screen that you want, and
3614           which is in the structure of the corresponding
3615           <span class="code">xcb_screen_t</span>.
3616           </p>
3617           <pre class="code">
3618 xcb_connection_t *c;
3619 xcb_screen_t     *screen;
3620 int               screen_nbr;
3621 uint32_t          width_in_pixels = 0;    /* the returned width in pixels */
3622
3623 /* you init the connection and screen_nbr */
3624
3625 screen = screen_of_display (c, screen_nbr);
3626 if (screen)
3627   width_in_pixels = screen-&gt;width_in_pixels;
3628
3629 /* width_in_pixels contains now the width in pixels, or 0 if no screen is found */
3630 </pre>
3631           <li class="subtitle"><a name="DisplayHeight">DisplayHeight / HeightOfScreen</a>
3632           <p>
3633           It is the height in pixels of the screen that you want, and
3634           which is in the structure of the corresponding
3635           <span class="code">xcb_screen_t</span>.
3636           </p>
3637           <pre class="code">
3638 xcb_connection_t *c;
3639 xcb_screen_t     *screen;
3640 int               screen_nbr;
3641 uint32_t          height_in_pixels = 0;    /* the returned height in pixels */
3642
3643 /* you init the connection and screen_nbr */
3644
3645 screen = screen_of_display (c, screen_nbr);
3646 if (screen)
3647   height_in_pixels = screen-&gt;height_in_pixels;
3648
3649 /* height_in_pixels contains now the height in pixels, or 0 if no screen is found */
3650 </pre>
3651           <li class="subtitle"><a name="DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
3652           <p>
3653           It is the width in millimeters of the screen that you want, and
3654           which is in the structure of the corresponding
3655           <span class="code">xcb_screen_t</span>.
3656           </p>
3657           <pre class="code">
3658 xcb_connection_t *c;
3659 xcb_screen_t     *screen;
3660 int               screen_nbr;
3661 uint32_t          width_in_millimeters = 0;    /* the returned width in millimeters */
3662
3663 /* you init the connection and screen_nbr */
3664
3665 screen = screen_of_display (c, screen_nbr);
3666 if (screen)
3667   width_in_millimeters = screen-&gt;width_in_millimeters;
3668
3669 /* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */
3670 </pre>
3671           <li class="subtitle"><a name="DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
3672           <p>
3673           It is the height in millimeters of the screen that you want, and
3674           which is in the structure of the corresponding
3675           <span class="code">xcb_screen_t</span>.
3676           </p>
3677           <pre class="code">
3678 xcb_connection_t *c;
3679 xcb_screen_t     *screen;
3680 int               screen_nbr;
3681 uint32_t          height_in_millimeters = 0;    /* the returned height in millimeters */
3682
3683 /* you init the connection and screen_nbr */
3684
3685 screen = screen_of_display (c, screen_nbr);
3686 if (screen)
3687   height_in_millimeters = screen-&gt;height_in_millimeters;
3688
3689 /* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */
3690 </pre>
3691           <li class="subtitle"><a name="DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
3692           <p>
3693           It is the depth (in bits) of the root window of the
3694           screen. You get it from the <span class="code">xcb_screen_t</span> structure.
3695           </p>
3696           <pre class="code">
3697 xcb_connection_t *c;
3698 xcb_screen_t     *screen;
3699 int               screen_nbr;
3700 uint8_t           root_depth = 0;  /* the returned depth of the root window */
3701
3702 /* you init the connection and screen_nbr */
3703
3704 screen = screen_of_display (c, screen_nbr);
3705 if (screen)
3706   root_depth = screen-&gt;root_depth;
3707
3708 /* root_depth contains now the depth of the root window, or 0 if no screen is found */
3709 </pre>
3710           <li class="subtitle"><a name="DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
3711           <p>
3712           This is the default colormap of the screen (and not the
3713           (default) colormap of the default screen !). As usual, you
3714           get it from the <span class="code">xcb_screen_t</span> structure:
3715           </p>
3716           <pre class="code">
3717 xcb_connection_t *c;
3718 xcb_screen_t     *screen;
3719 int               screen_nbr;
3720 xcb_colormap_t    default_colormap = { 0 };  /* the returned default colormap */
3721
3722 /* you init the connection and screen_nbr */
3723
3724 screen = screen_of_display (c, screen_nbr);
3725 if (screen)
3726   default_colormap = screen-&gt;default_colormap;
3727
3728 /* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */
3729 </pre>
3730           <li class="subtitle"><a name="MinCmapsOfScreen"></a>MinCmapsOfScreen
3731           <p>
3732           You get the minimum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
3733           </p>
3734           <pre class="code">
3735 xcb_connection_t *c;
3736 xcb_screen_t     *screen;
3737 int               screen_nbr;
3738 uint16_t          min_installed_maps = 0;  /* the returned minimum installed colormaps */
3739
3740 /* you init the connection and screen_nbr */
3741
3742 screen = screen_of_display (c, screen_nbr);
3743 if (screen)
3744   min_installed_maps = screen-&gt;min_installed_maps;
3745
3746 /* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */
3747 </pre>
3748           <li class="subtitle"><a name="MaxCmapsOfScreen"></a>MaxCmapsOfScreen
3749           <p>
3750           You get the maximum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
3751           </p>
3752           <pre class="code">
3753 xcb_connection_t *c;
3754 xcb_screen_t     *screen;
3755 int               screen_nbr;
3756 uint16_t          max_installed_maps = 0;  /* the returned maximum installed colormaps */
3757
3758 /* you init the connection and screen_nbr */
3759
3760 screen = screen_of_display (c, screen_nbr);
3761 if (screen)
3762   max_installed_maps = screen-&gt;max_installed_maps;
3763
3764 /* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */
3765 </pre>
3766           <li class="subtitle"><a name="DoesSaveUnders"></a>DoesSaveUnders
3767           <p>
3768           You know if <span class="code">save_unders</span> is set,
3769           by looking in the <span class="code">xcb_screen_t</span> structure:
3770           </p>
3771           <pre class="code">
3772 xcb_connection_t *c;
3773 xcb_screen_t     *screen;
3774 int               screen_nbr;
3775 uint8_t           save_unders = 0;  /* the returned value of save_unders */
3776
3777 /* you init the connection and screen_nbr */
3778
3779 screen = screen_of_display (c, screen_nbr);
3780 if (screen)
3781   save_unders = screen-&gt;save_unders;
3782
3783 /* save_unders contains now the value of save_unders, or FALSE if no screen is found */
3784 </pre>
3785           <li class="subtitle"><a name="DoesBackingStore"></a>DoesBackingStore
3786           <p>
3787           You know the value of <span class="code">backing_stores</span>,
3788           by looking in the <span class="code">xcb_screen_t</span> structure:
3789           </p>
3790           <pre class="code">
3791 xcb_connection_t *c;
3792 xcb_screen_t     *screen;
3793 int               screen_nbr;
3794 uint8_t           backing_stores = 0;  /* the returned value of backing_stores */
3795
3796 /* you init the connection and screen_nbr */
3797
3798 screen = screen_of_display (c, screen_nbr);
3799 if (screen)
3800   backing_stores = screen-&gt;backing_stores;
3801
3802 /* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */
3803 </pre>
3804           <li class="subtitle"><a name="EventMaskOfScreen"></a>EventMaskOfScreen
3805           <p>
3806           To get the current input masks,
3807           you look in the <span class="code">xcb_screen_t</span> structure:
3808           </p>
3809           <pre class="code">
3810 xcb_connection_t *c;
3811 xcb_screen_t     *screen;
3812 int               screen_nbr;
3813 uint32_t          current_input_masks = 0;  /* the returned value of current input masks */
3814
3815 /* you init the connection and screen_nbr */
3816
3817 screen = screen_of_display (c, screen_nbr);
3818 if (screen)
3819   current_input_masks = screen-&gt;current_input_masks;
3820
3821 /* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
3822 </pre>
3823         </ol>
3824       <li class="subtitle"><a name="misc">Miscellaneous macros</a>
3825         <ol>
3826           <li class="subtitle"><a name="DisplayOfScreen"></a>DisplayOfScreen
3827           <p>
3828           in Xlib, the <span class="code">Screen</span> structure
3829           stores its associated <span class="code">Display</span>
3830           structure. This is not the case in the X Window protocol,
3831           hence, it's also not the case in XCB. So you have to store
3832           it by yourself.
3833           </p>
3834           <li class="subtitle"><a name="DisplayCells"></a>DisplayCells / CellsOfScreen
3835           <p>
3836           To get the colormap entries,
3837           you look in the <span class="code">xcb_visualtype_t</span>
3838           structure, that you grab like <a class="subsection" href="#DefaultVisual">here</a>:
3839           </p>
3840           <pre class="code">
3841 xcb_connection_t *c;
3842 xcb_visualtype_t *visual_type;
3843 uint16_t          colormap_entries = 0;  /* the returned value of the colormap entries */
3844
3845 /* you init the connection and visual_type */
3846
3847 if (visual_type)
3848   colormap_entries = visual_type-&gt;colormap_entries;
3849
3850 /* colormap_entries contains now the value of the colormap entries, or FALSE if no screen is found */
3851 </pre>
3852         </ol>
3853       </ol>
3854     </ol>
3855   </div>
3856 </body>
3857
3858 </html>