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

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