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