1 <!DOCTYPE html public "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
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">
14 Basic Graphics Programming With The XCB Library
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>
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>
27 <li>Memory allocation for XCB structures
28 <li><a class="subsection" href="#events">Events</a>
30 <li><a class="section" href="#use">Using XCB-based programs</a>
32 <li><a class="subsection" href="#inst">Installation of XCB</a>
33 <li><a class="subsection" href="#comp">Compiling XCB-based programs</a>
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>
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>
44 <li><a class="section" href="#xevents">X Events</a>
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>
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>
57 <li><a class="subsection" href="#eventex">X events: a complete example</a>
59 <li><a class="section" href="#font">Handling text and fonts</a>
61 <li><a class="subsection" href="#fontstruct">The Font structure</a>
63 <li>Assigning a Font to a Graphic Context
64 <li>Drawing text in a window
68 <li>Root, parent and child windows
69 <li>Events propagation
71 <li><a class="section" href="#wm">Interacting with the window manager</a>
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
80 <li><a class="section" href="#winop">Simple window operations</a>
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>
90 <li><a class="section" href="#usecolor">Using colors to paint the rainbow</a>
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
97 <li><a class="section" href="#pixmaps">X Bitmaps and Pixmaps</a>
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>
106 <li><a class="subsection" href="#mousecursor">Messing with the mouse cursor</a>
108 <li><a class="subsection" href="#mousecursorcreate">Creating and destroying a mouse cursor</a>
109 <li><a class="subsection" href="#mousecursorset">Setting a window's mouse cursor</a>
110 <li><a class="subsection" href="#mousecursorexample">Complete example</a>
112 <li><a class="subsection" href="#translation">Translation of basic Xlib functions and macros</a>
114 <li><a class="subsection" href="#displaystructure">Members of the Display structure</a>
116 <li><a class="subsection" href="#ConnectionNumber">ConnectionNumber</a>
117 <li><a class="subsection" href="#DefaultScreen">DefaultScreen</a>
118 <li><a class="subsection" href="#QLength">QLength</a>
119 <li><a class="subsection" href="#ScreenCount">ScreenCount</a>
120 <li><a class="subsection" href="#ServerVendor">ServerVendor</a>
121 <li><a class="subsection" href="#ProtocolVersion">ProtocolVersion</a>
122 <li><a class="subsection" href="#ProtocolRevision">ProtocolRevision</a>
123 <li><a class="subsection" href="#VendorRelease">VendorRelease</a>
124 <li><a class="subsection" href="#DisplayString">DisplayString</a>
125 <li><a class="subsection" href="#BitmapUnit">BitmapUnit</a>
126 <li><a class="subsection" href="#BitmapBitOrder">BitmapBitOrder</a>
127 <li><a class="subsection" href="#BitmapPad">BitmapPad</a>
128 <li><a class="subsection" href="#ImageByteOrder">ImageByteOrder</a>
130 <li><a class="subsection" href="#screenofdisplay">ScreenOfDisplay related functions</a>
132 <li><a class="subsection" href="#ScreenOfDisplay">ScreenOfDisplay</a>
133 <li><a class="subsection" href="#DefaultScreenOfDisplay">DefaultScreenOfDisplay</a>
134 <li><a class="subsection" href="#RootWindow">RootWindow / RootWindowOfScreen</a>
135 <li><a class="subsection" href="#DefaultRootWindow">DefaultRootWindow</a>
136 <li><a class="subsection" href="#DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
137 <li><a class="subsection" href="#DefaultGC">DefaultGC / DefaultGCOfScreen</a>
138 <li><a class="subsection" href="#BlackPixel">BlackPixel / BlackPixelOfScreen</a>
139 <li><a class="subsection" href="#WhitePixel">WhitePixel / WhitePixelOfScreen</a>
140 <li><a class="subsection" href="#DisplayWidth">DisplayWidth / WidthOfScreen</a>
141 <li><a class="subsection" href="#DisplayHeight">DisplayHeight / HeightOfScreen</a>
142 <li><a class="subsection" href="#DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
143 <li><a class="subsection" href="#DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
144 <li><a class="subsection" href="#DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
145 <li><a class="subsection" href="#DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
146 <li><a class="subsection" href="#MinCmapsOfScreen">MinCmapsOfScreen</a>
147 <li><a class="subsection" href="#MaxCmapsOfScreen">MaxCmapsOfScreen</a>
148 <li><a class="subsection" href="#DoesSaveUnders">DoesSaveUnders</a>
149 <li><a class="subsection" href="#DoesBackingStore">DoesBackingStore</a>
150 <li><a class="subsection" href="#EventMaskOfScreen">EventMaskOfScreen</a>
152 <li><a class="subsection" href="#misc">Miscellaneaous macros</a>
154 <li><a class="subsection" href="#DisplayOfScreen">DisplayOfScreen</a>
155 <li><a class="subsection" href="#DisplayCells">DisplayCells / CellsOfScreen</a>
160 <div class="section">
162 <li class="title"><a name="intro">Introduction</a>
164 This tutorial is based on the
165 <a href="http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html">Xlib Tutorial</a>
166 written by <a href="mailto:choor at atcom dot co dot il">Guy Keren</a>. The
167 author allowed me to take some parts of his text, mainly the text which
168 deals with the X Windows generality.
171 This tutorial is intended for people who want to start to program
172 with the <a href="http://xcb.freedesktop.org">XCB</a>
173 library. keep in mind that XCB, like the
174 <a href="http://tronche.com/gui/x/xlib/introduction">Xlib</a>
175 library, isn't what post programmers wanting to write X
176 applications are looking for. They should use a much higher
177 level GUI toolkit like Motif,
178 <a href="http://www.lesstif.org">LessTiff</a>,
179 <a href="http://www.gtk.org">GTK</a>,
180 <a href="http://www.trolltech.com">QT</a> or
181 <a href="http://www.enlightenment.org">EWL</a>, or use
182 <a href="http://cairographics.org">Cairo</a>.
184 we need to start somewhere. More than this, knowing how things
185 work down below is never a bad idea.
188 After reading this tutorial, one should be able to write very
189 simple graphical programs, but not programs with decent user
190 interfaces. For such programs, one of the previously mentioned
191 libraries should be used.
194 But what is XCB? Xlib has been
195 the standard C binding for the <a href="http://www.x.org">X
196 Window System</a> protocol for many years now. It is an
197 excellent piece of work, but there are applications for which it
198 is not ideal, for example:
201 <li><b>Small platforms</b>: Xlib is a large piece of code, and
202 it's difficult to make it smaller
203 <li><b>Latency hiding</b>: Xlib requests requiring a reply are
204 effectively synchronous: they block until the reply appears,
205 whether the result is needed immediately or not.
206 <li><b>Direct access to the protocol</b>: Xlib does quite a
207 bit of caching, layering, and similar optimizations. While this
208 is normally a feature, it makes it difficult to simply emit
209 specified X protocol requests and process specific
211 <li><b>Threaded applications</b>: While Xlib does attempt to
212 support multithreading, the API makes this difficult and
214 <li><b>New extensions</b>: The Xlib infrastructure provides
215 limited support for the new creation of X extension client side
219 For these reasons, among others, XCB, an X C binding, has been
220 designed to solve the above problems and thus provide a base for
223 <li>Toolkit implementation.
224 <li>Direct protocol-level programming.
225 <li>Lightweight emulation of commonly used portions of the
229 <li class="title"><a name="Xmodel">The client and server model of the X window system</a>
231 The X Window System was developed with one major goal:
232 flexibility. The idea was that the way things look is one thing,
233 but the way things work is another matter. Thus, the lower
234 levels provide the tools required to draw windows, handle user
235 input, allow drawing graphics using colors (or black and white
236 screens), etc. To this point, a decision was made to separate
237 the system into two parts. A client that decides what to do, and
238 a server that actually draws on the screen and reads user input
239 in order to send it to the client for processing.
242 This model is the complete opposite of what is used to when
243 dealing with clients and servers. In our case, the user sits
244 near the machine controlled by the server, while the client
245 might be running on a remote machine. The server controls the
246 screens, mouse and keyboard. A client may connect to the server,
247 request that it draws a window (or several windows), and ask the
248 server to send it any input the user sends to these
249 windows. Thus, several clients may connect to a single X server
250 (one might be running mail software, one running a WWW
251 browser, etc). When input is sent by the user to some window,
252 the server sends a message to the client controlling this window
253 for processing. The client decides what to do with this input,
254 and sends the server requests for drawing in the window.
257 The whole session is carried out using the X message
258 protocol. This protocol was originally carried over the TCP/IP
259 protocol suite, allowing the client to run on any machine
260 connected to the same network that the server is. Later on, the
261 X servers were extended to allow clients running on the local
262 machine with more optimized access to the server (note that an X
263 protocol message may be several hundreds of KB in size), such as
264 using shared memory, or using Unix domain sockets (a method for
265 creating a logical channel on a Unix system between two processes).
267 <li class="title"><a name="asynch">GUI programming: the asynchronous model</a>
269 Unlike conventional computer programs, that carry some serial
270 nature, a GUI program usually uses an asynchronous programming
271 model, also known as "event-driven programming". This means that
272 that program mostly sits idle, waiting for events sent by the X
273 server, and then acts upon these events. An event may say "The
274 user pressed the 1st button mouse in spot (x,y)", or "The window
275 you control needs to be redrawn". In order for the program to be
276 responsive to the user input, as well as to refresh requests, it
277 needs to handle each event in a rather short period of time
278 (e.g. less that 200 milliseconds, as a rule of thumb).
281 This also implies that the program may not perform operations
282 that might take a long time while handling an event (such as
283 opening a network connection to some remote server, or
284 connecting to a database server, or even performing a long file
285 copy operation). Instead, it needs to perform all these
286 operations in an asynchronous manner. This may be done by using
287 various asynchronous models to perform the longish operations,
288 or by performing them in a different process or thread.
291 So the way a GUI program looks is something like that:
294 <li>Perform initialization routines.
295 <li>Connect to the X server.
296 <li>Perform X-related initialization.
297 <li>While not finished:
299 <li>Receive the next event from the X server.
300 <li>Handle the event, possibly sending various drawing
301 requests to the X server.
302 <li>If the event was a quit message, exit the loop.
304 <li>Close down the connection to the X server.
305 <li>Perform cleanup operations.
308 <li class="title"><a name="notions">Basic XCB notions</a>
310 XCB has been created to eliminate the need for
311 programs to actually implement the X protocol layer. This
312 library gives a program a very low-level access to any X
313 server. Since the protocol is standardized, a client using any
314 implementation of XCB may talk with any X server (the same
315 occurs for Xlib, of course). We now give a brief description of
316 the basic XCB notions. They will be detailed later.
319 <li class="subtitle"><a name="conn">The X Connection</a>
321 The major notion of using XCB is the X Connection. This is a
322 structure representing the connection we have open with a
323 given X server. It hides a queue of messages coming from the
324 server, and a queue of pending requests that our client
325 intends to send to the server. In XCB, this structure is named
326 'xcb_connection_t'. It is analogous to the Xlib Display.
327 When we open a connection to an X server, the
328 library returns a pointer to such a structure. Later, we
329 supply this pointer to any XCB function that should send
330 messages to the X server or receive messages from this server.
332 <li class="subtitle"><a name="requestsreplies">Requests and
333 replies: the Xlib killers</a>
335 To ask for information from the X server, we have to make a request
336 and ask for a reply. With Xlib, these two tasks are
337 automatically done: Xlib locks the system, sends a request,
338 waits for a reply from the X server and unlocks. This is
339 annoying, especially if one makes a lot of requests to the X
340 server. Indeed, Xlib has to wait for the end of a reply
341 before asking for the next request (because of the locks that
342 Xlib sends). For example, here is a time-line of N=4
343 requests/replies with Xlib, with a round-trip latency
344 <b>T_round_trip</b> that is 5 times long as the time required
345 to write or read a request/reply (<b>T_write/T_read</b>):
348 W-----RW-----RW-----RW-----R
351 <li>W: Writing request
352 <li>-: Stalled, waiting for data
356 The total time is N * (T_write + T_round_trip + T_read).
359 With XCB, we can suppress most of the round-trips as the
360 requests and the replies are not locked. We usually send a
361 request, then XCB returns to us a <b>cookie</b>, which is an
362 identifier. Then, later, we ask for a reply using this
363 <b>cookie</b> and XCB returns a
364 pointer to that reply. Hence, with XCB, we can send a lot of
365 requests, and later in the program, ask for all the replies
366 when we need them. Here is the time-line for 4
367 requests/replies when we use this property of XCB:
373 The total time is N * T_write + max (0, T_round_trip - (N-1) *
374 T_write) + N * T_read. Which can be considerably faster than
375 all those Xlib round-trips.
378 Here is a program that computes the time to create 500 atoms
379 with Xlib and XCB. It shows the Xlib way, the bad XCB way
380 (which is similar to Xlib) and the good XCB way. On my
381 computer, XCB is 25 times faster than Xlib.
384 #include <stdlib.h>
385 #include <stdio.h>
386 #include <string.h>
387 #include <sys/time.h>
389 #include <xcb/xcb.h>
391 #include <X11/Xlib.h>
396 struct timeval timev;
398 gettimeofday(&timev, NULL);
400 return (double)timev.tv_sec + (((double)timev.tv_usec) / 1000000);
408 xcb_intern_atom_cookie_t *cs;
421 c = xcb_connect (NULL, NULL);
424 atoms = (xcb_atom_t *)malloc (count * sizeof (atoms));
425 names = (char **)malloc (count * sizeof (char *));
428 for (i = 0; i < count; ++i) {
431 sprintf (buf, "NAME%d", i);
432 names[i] = strdup (buf);
438 for (i = 0; i < count; ++i)
439 atoms[i] = xcb_intern_atom_reply (c,
448 printf ("bad use time : %f\n", diff);
453 cs = (xcb_intern_atom_cookie_t *) malloc (count * sizeof(xcb_intern_atom_cookie_t));
454 for(i = 0; i < count; ++i)
455 cs[i] = xcb_intern_atom (c, 0, strlen(names[i]), names[i]);
457 for(i = 0; i < count; ++i) {
458 xcb_intern_atom_reply_t *r;
460 r = xcb_intern_atom_reply(c, cs[i], 0);
467 printf ("good use time : %f\n", end - start);
468 printf ("ratio : %f\n", diff / (end - start));
472 for (i = 0; i < count; ++i)
480 disp = XOpenDisplay (getenv("DISPLAY"));
482 atoms_x = (Atom *)malloc (count * sizeof (atoms_x));
486 for (i = 0; i < count; ++i)
487 atoms_x[i] = XInternAtom(disp, names[i], 0);
490 diff_x = end - start;
491 printf ("Xlib use time : %f\n", diff_x);
492 printf ("ratio : %f\n", diff_x / diff);
497 XCloseDisplay (disp);
502 <li class="subtitle"><a name="gc">The Graphic Context</a>
504 When we perform various drawing operations (graphics, text,
505 etc), we may specify various options for controlling how the
506 data will be drawn (what foreground and background colors to
507 use, how line edges will be connected, what font to use when
508 drawing some text, etc). In order to avoid the need to supply
509 hundreds of parameters to each drawing function, a graphical
510 context structure is used. We set the various drawing options
511 in this structure, and then we pass a pointer to this
512 structure to any drawing routines. This is rather handy, as we
513 often need to perform several drawing requests with the same
514 options. Thus, we would initialize a graphical context, set
515 the desired options, and pass this structure to all drawing
519 Note that graphic contexts have no client-side structure in
520 XCB, they're just XIDs. Xlib has a client-side structure
521 because it caches the GC contents so it can avoid making
522 redundant requests, but of course XCB doesn't do that.
524 <li class="subtitle"><a name="events">Events</a>
526 A structure is used to pass events received from the X
527 server. XCB supports exactly the events specified in the
528 protocol (33 events). This structure contains the type
529 of event received (including a bit for whether it came
530 from the server or another client), as well as the data associated with the
531 event (e.g. position on the screen where the event was
532 generated, mouse button associated with the event, region of
533 the screen associated with a "redraw" event, etc). The way to
534 read the event's data depends on the event type.
538 <li class="title"><a name="use">Using XCB-based programs</a>
541 <li class="subtitle"><a name="inst">Installation of XCB</a>
543 <b>TODO:</b> These instructions are out of date.
544 Just reference the <a href="http://xcb.freedesktop.org/">main XCB page</a>
545 so we don't have to maintain these instructions in more than
549 To build XCB from source, you need to have installed at
554 <li><a href="http://www.gnu.org/software/automake/">automake 1.7</a>
555 <li><a href="http://www.gnu.org/software/autoconf/">autoconf 2.50</a>
556 <li><a href="http://www.check.org">check</a>
557 <li><a href="http://xmlsoft.org/XSLT/">xsltproc</a>
558 <li><a href="http://www.gnu.org/software/gperf/">gperf 3.0.1</a>
561 You have to checkout in the git repository the following modules:
569 Note that xcb-proto exists only to install header
570 files, so typing 'make' or 'make all' will produce the message
571 "Nothing to be done for 'all'". That's normal.
573 <li class="subtitle"><a name="comp">Compiling XCB-based programs</a>
575 Compiling XCB-based programs requires linking them with the XCB
576 library. This is easily done thanks to pkgconfig:
579 gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb`
582 <li class="title"><a name="openconn">Opening and closing the connection to an X server</a>
584 An X program first needs to open the connection to the X
585 server. There is a function that opens a connection. It requires
586 the display name, or NULL. In the latter case, the display name
587 will be the one in the environment variable DISPLAY.
590 <span class="type">xcb_connection_t</span> *xcb_connect (<span class="keyword">const</span> <span class="type">char</span> *displayname,
591 <span class="type">int</span> *screenp);
594 The second parameter returns the screen number used for the
595 connection. The returned structure describes an XCB connection
596 and is opaque. Here is how the connection can be opened:
599 #<span class="include">include</span> <span class="string"><xcb/xcb.h></span>
601 <span class="type">int</span>
602 <span class="function">main</span> ()
604 <span class="type">xcb_connection_t</span> *c;
606 /* Open the connection to the X server. Use the DISPLAY environment variable as the default display name */
607 c = xcb_connect (NULL, NULL);
609 <span class="keyword">return</span> 0;
613 To close a connection, it suffices to use:
616 <span class="type">void</span> xcb_disconnect (<span class="type">xcb_connection_t</span> *c);
639 <li>xcb_disconnect ()
644 <li class="title"><a name="screen">Checking basic information about a connection</a>
646 Once we have opened a connection to an X server, we should check some
647 basic information about it: what screens it has, what is the
648 size (width and height) of the screen, how many colors it
649 supports (black and white ? grey scale ?, 256 colors ? more ?),
650 and so on. We get such information from the xcb_screen_t
656 xcb_colormap_t default_colormap;
657 uint32_t white_pixel;
658 uint32_t black_pixel;
659 uint32_t current_input_masks;
660 uint16_t width_in_pixels;
661 uint16_t height_in_pixels;
662 uint16_t width_in_millimeters;
663 uint16_t height_in_millimeters;
664 uint16_t min_installed_maps;
665 uint16_t max_installed_maps;
666 xcb_visualid_t root_visual;
667 uint8_t backing_stores;
670 uint8_t allowed_depths_len;
674 We could retrieve the first screen of the connection by using the
678 xcb_screen_iterator_t xcb_setup_roots_iterator (xcb_setup_t *R);
681 Here is a small program that shows how to use this function:
684 #include <stdio.h>
686 #include <xcb/xcb.h>
692 xcb_screen_t *screen;
694 xcb_screen_iterator_t iter;
696 /* Open the connection to the X server. Use the DISPLAY environment variable */
697 c = xcb_connect (NULL, &screen_nbr);
699 /* Get the screen #screen_nbr */
700 iter = xcb_setup_roots_iterator (xcb_get_setup (c));
701 for (; iter.rem; --screen_nbr, xcb_screen_next (&iter))
702 if (screen_nbr == 0) {
708 printf ("Informations of screen %ld:\n", screen->root);
709 printf (" width.........: %d\n", screen->width_in_pixels);
710 printf (" height........: %d\n", screen->height_in_pixels);
711 printf (" white pixel...: %ld\n", screen->white_pixel);
712 printf (" black pixel...: %ld\n", screen->black_pixel);
718 <li class="title"><a name="helloworld">Creating a basic window - the "hello world" program</a>
720 After we got some basic information about our screen, we can
721 create our first window. In the X Window System, a window is
722 characterized by an Id. So, in XCB, a window is of type:
725 typedef uint32_t xcb_window_t;
728 We first ask for a new Id for our window, with this function:
731 xcb_window_t xcb_generate_id(xcb_connection_t *c);
734 Then, XCB supplies the following function to create new windows:
737 xcb_void_cookie_t xcb_create_window (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
738 uint8_t depth, /* Depth of the screen */
739 xcb_window_t wid, /* Id of the window */
740 xcb_window_t parent, /* Id of an existing window that should be the parent of the new window */
741 int16_t x, /* X position of the top-left corner of the window (in pixels) */
742 int16_t y, /* Y position of the top-left corner of the window (in pixels) */
743 uint16_t width, /* Width of the window (in pixels) */
744 uint16_t height, /* Height of the window (in pixels) */
745 uint16_t border_width, /* Width of the window's border (in pixels) */
747 xcb_visualid_t visual,
749 const uint32_t *value_list);
752 The fact that we created the window does not mean that it will
753 be drawn on screen. By default, newly created windows are not
754 mapped on the screen (they are invisible). In order to make our
755 window visible, we use the function <span class="code">xcb_map_window()</span>, whose
759 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
760 xcb_window_t window);
763 Finally, here is a small program to create a window of size
764 150x150 pixels, positioned at the top-left corner of the screen:
767 #include <unistd.h> /* pause() */
769 #include <xcb/xcb.h>
775 xcb_screen_t *screen;
778 /* Open the connection to the X server */
779 c = xcb_connect (NULL, NULL);
781 /* Get the first screen */
782 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
784 /* Ask for our window's Id */
785 win = xcb_generate_id(c);
787 /* Create the window */
788 xcb_create_window (c, /* Connection */
789 XCB_COPY_FROM_PARENT, /* depth (same as root)*/
791 screen->root, /* parent window */
793 150, 150, /* width, height */
794 10, /* border_width */
795 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
796 screen->root_visual, /* visual */
797 0, NULL); /* masks, not used yet */
799 /* Map the window on the screen */
800 xcb_map_window (c, win);
802 /* Make sure commands are sent before we pause, so window is shown */
805 pause (); /* hold client until Ctrl-C */
811 In this code, you see one more function - <span class="code">xcb_flush()</span>, not explained
812 yet. It is used to flush all the pending requests. More
813 precisely, there are 2 functions that do such things. The first
814 one is <span class="code">xcb_flush()</span>:
817 int xcb_flush (xcb_connection_t *c);
820 This function flushes all pending requests to the X server (much
821 like the <span class="code">fflush()</span> function is used to
822 flush standard output). The second function is
823 <span class="code">xcb_aux_sync()</span>:
826 int xcb_aux_sync (xcb_connection_t *c);
829 This functions also flushes all pending requests to the X
830 server, and then waits until the X server finishing processing
831 these requests. In a normal program, this will not be necessary
832 (we'll see why when we get to write a normal X program), but for
833 now, we put it there.
836 The window that is created by the above code has a non defined
837 background. This one can be set to a specific color,
838 thanks to the two last parameters of
839 <span class="code">xcb_create_window()</span>, which are not
840 described yet. See the subsections
841 <a href="#winconf">Configuring a window</a> or
842 <a href="#winconf">Registering for event types using event masks</a>
843 for examples on how to use these parameters. In addition, as no
844 events are handled, you have to make a Ctrl-C to interrupt the
848 <b>TODO</b>: one should tell what these functions return and
849 about the generic error
862 <li>xcb_generate_id ()
863 <li>xcb_create_window ()
868 <li class="title"><a name="drawing">Drawing in a window</a>
870 Drawing in a window can be done using various graphical
871 functions (drawing pixels, lines, rectangles, etc). In order to
872 draw in a window, we first need to define various general
873 drawing parameters (what line width to use, which color to draw
874 with, etc). This is done using a graphical context.
877 <li class="subtitle"><a name="allocgc">Allocating a Graphics Context</a>
879 As we said, a graphical context defines several attributes to
880 be used with the various drawing functions. For this, we
881 define a graphical context. We can use more than one graphical
882 context with a single window, in order to draw in multiple
883 styles (different colors, different line widths, etc). In XCB,
884 a Graphics Context is, as a window, characterized by an Id:
887 typedef uint32_t xcb_gcontext_t;
890 We first ask the X server to attribute an Id to our graphic
891 context with this function:
894 xcb_gcontext_t xcb_generate_id (xcb_connection_t *c);
897 Then, we set the attributes of the graphic context with this function:
900 xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c,
902 xcb_drawable_t drawable,
904 const uint32_t *value_list);
907 We give now an example on how to allocate a graphic context
908 that specifies that each drawing function that uses it will
909 draw in foreground with a black color.
912 #include <xcb/xcb.h>
918 xcb_screen_t *screen;
920 xcb_gcontext_t black;
924 /* Open the connection to the X server and get the first screen */
925 c = xcb_connect (NULL, NULL);
926 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
928 /* Create a black graphic context for drawing in the foreground */
929 win = screen->root;
930 black = xcb_generate_id (c);
931 mask = XCB_GC_FOREGROUND;
932 value[0] = screen->black_pixel;
933 xcb_create_gc (c, black, win, mask, value);
939 Note should be taken regarding the role of "value_mask" and
940 "value_list" in the prototype of <span class="code">xcb_create_gc()</span>. Since a
941 graphic context has many attributes, and since we often just
942 want to define a few of them, we need to be able to tell the
943 <span class="code">xcb_create_gc()</span> which attributes we
944 want to set. This is what the "value_mask" parameter is
945 for. We then use the "value_list" parameter to specify actual
946 values for the attribute we defined in "value_mask". Thus, for
947 each constant used in "value_list", we will use the matching
948 constant in "value_mask". In this case, we define a graphic
949 context with one attribute: when drawing (a point, a line,
950 etc), the foreground color will be black. The rest of the
951 attributes of this graphic context will be set to their
955 See the next Subsection for more details.
968 <li>xcb_generate_id ()
974 <li class="subtitle"><a name="changegc">Changing the attributes of a Graphics Context</a>
976 Once we have allocated a Graphic Context, we may need to
977 change its attributes (for example, changing the foreground
978 color we use to draw a line, or changing the attributes of the
979 font we use to display strings. See Subsections Drawing with a
980 color and Assigning a Font to a Graphic Context). This is done
981 by using this function:
984 xcb_void_cookie_t xcb_change_gc (xcb_connection_t *c, /* The XCB Connection */
985 xcb_gcontext_t gc, /* The Graphic Context */
986 uint32_t value_mask, /* Components of the Graphic Context that have to be set */
987 const uint32_t *value_list); /* Value as specified by value_mask */
990 The <span class="code">value_mask</span> parameter could take
991 any combination of these masks from the xcb_gc_t enumeration:
995 <li>XCB_GC_PLANE_MASK
996 <li>XCB_GC_FOREGROUND
997 <li>XCB_GC_BACKGROUND
998 <li>XCB_GC_LINE_WIDTH
999 <li>XCB_GC_LINE_STYLE
1000 <li>XCB_GC_CAP_STYLE
1001 <li>XCB_GC_JOIN_STYLE
1002 <li>XCB_GC_FILL_STYLE
1003 <li>XCB_GC_FILL_RULE
1006 <li>XCB_GC_TILE_STIPPLE_ORIGIN_X
1007 <li>XCB_GC_TILE_STIPPLE_ORIGIN_Y
1009 <li>XCB_GC_SUBWINDOW_MODE
1010 <li>XCB_GC_GRAPHICS_EXPOSURES
1011 <li>XCB_GC_CLIP_ORIGIN_X
1012 <li>XCB_GC_CLIP_ORIGIN_Y
1013 <li>XCB_GC_CLIP_MASK
1014 <li>XCB_GC_DASH_OFFSET
1015 <li>XCB_GC_DASH_LIST
1019 It is possible to set several attributes at the same
1020 time (for example setting the attributes of a font and the
1021 color which will be used to display a string), by OR'ing these
1022 values in <span class="code">value_mask</span>. Then
1023 <span class="code">value_list</span> has to be an array which
1024 lists the value for the respective attributes. <b>These values
1025 must be in the same order as masks listed above.</b> See Subsection
1026 Drawing with a color to have an example.
1029 <b>TODO</b>: set the links of the 3 subsections, once they will
1033 <b>TODO</b>: give an example which sets several attributes.
1035 <li class="subtitle"><a name="drawingprim">Drawing primitives: point, line, box, circle,...</a>
1037 After we have created a Graphic Context, we can draw on a
1038 window using this Graphic Context, with a set of XCB
1039 functions, collectively called "drawing primitives". Let see
1043 To draw a point, or several points, we use
1046 xcb_void_cookie_t xcb_poly_point (xcb_connection_t *c, /* The connection to the X server */
1047 uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1048 xcb_drawable_t drawable, /* The drawable on which we want to draw the point(s) */
1049 xcb_gcontext_t gc, /* The Graphic Context we use to draw the point(s) */
1050 uint32_t points_len, /* The number of points */
1051 const xcb_point_t *points); /* An array of points */
1054 The <span class="code">coordinate_mode</span> parameter
1055 specifies the coordinate mode. Available values are
1058 <li><span class="code">XCB_COORD_MODE_ORIGIN</span>
1059 <li><span class="code">XCB_COORD_MODE_PREVIOUS</span>
1062 If XCB_COORD_MODE_PREVIOUS is used, then all points but the first one
1063 are relative to the immediately previous point.
1066 The <span class="code">xcb_point_t</span> type is just a
1067 structure with two fields (the coordinates of the point):
1076 You could see an example in xpoints.c. <b>TODO</b> Set the link.
1079 To draw a line, or a polygonal line, we use
1082 xcb_void_cookie_t xcb_poly_line (xcb_connection_t *c, /* The connection to the X server */
1083 uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1084 xcb_drawable_t drawable, /* The drawable on which we want to draw the line(s) */
1085 xcb_gcontext_t gc, /* The Graphic Context we use to draw the line(s) */
1086 uint32_t points_len, /* The number of points in the polygonal line */
1087 const xcb_point_t *points); /* An array of points */
1090 This function will draw the line between the first and the
1091 second points, then the line between the second and the third
1095 To draw a segment, or several segments, we use
1098 xcb_void_cookie_t xcb_poly_segment (xcb_connection_t *c, /* The connection to the X server */
1099 xcb_drawable_t drawable, /* The drawable on which we want to draw the segment(s) */
1100 xcb_gcontext_t gc, /* The Graphic Context we use to draw the segment(s) */
1101 uint32_t segments_len, /* The number of segments */
1102 const xcb_segment_t *segments); /* An array of segments */
1105 The <span class="code">xcb_segment_t</span> type is just a
1106 structure with four fields (the coordinates of the two points
1107 that define the segment):
1118 To draw a rectangle, or several rectangles, we use
1121 xcb_void_cookie_t xcb_poly_rectangle (xcb_connection_t *c, /* The connection to the X server */
1122 xcb_drawable_t drawable, /* The drawable on which we want to draw the rectangle(s) */
1123 xcb_gcontext_t gc, /* The Graphic Context we use to draw the rectangle(s) */
1124 uint32_t rectangles_len, /* The number of rectangles */
1125 const xcb_rectangle_t *rectangles); /* An array of rectangles */
1128 The <span class="code">xcb_rectangle_t</span> type is just a
1129 structure with four fields (the coordinates of the top-left
1130 corner of the rectangle, and its width and height):
1140 <!-- There's no coordinate_mode. Is it normal? -->
1141 <!-- [iano] Yes, it's not in the protocol. -->
1143 To draw an elliptical arc, or several elliptical arcs, we use
1146 xcb_void_cookie_t xcb_poly_arc (xcb_connection_t *c, /* The connection to the X server */
1147 xcb_drawable_t drawable, /* The drawable on which we want to draw the arc(s) */
1148 xcb_gcontext_t gc, /* The Graphic Context we use to draw the arc(s) */
1149 uint32_t arcs_len, /* The number of arcs */
1150 const xcb_arc_t *arcs); /* An array of arcs */
1153 The <span class="code">xcb_arc_t</span> type is a structure with
1158 int16_t x; /* Top left x coordinate of the rectangle surrounding the ellipse */
1159 int16_t y; /* Top left y coordinate of the rectangle surrounding the ellipse */
1160 uint16_t width; /* Width of the rectangle surrounding the ellipse */
1161 uint16_t height; /* Height of the rectangle surrounding the ellipse */
1162 int16_t angle1; /* Angle at which the arc begins */
1163 int16_t angle2; /* Angle at which the arc ends */
1168 Note: the angles are expressed in units of 1/64 of a degree,
1169 so to have an angle of 90 degrees, starting at 0,
1170 <span class="code">angle1 = 0</span> and
1171 <span class="code">angle2 = 90 << 6</span>. Positive angles
1172 indicate counterclockwise motion, while negative angles
1173 indicate clockwise motion.
1176 <!-- I think that (x,y) should be the center of the
1177 ellipse, and (width, height) the radius. It's more logical. -->
1178 <!-- iano: Yes, and I bet some toolkits do that.
1179 But the protocol (and many other graphics APIs) define arcs
1180 by bounding rectangles. -->
1182 The corresponding function which fill inside the geometrical
1183 object are listed below, without further explanation, as they
1184 are used as the above functions.
1187 To Fill a polygon defined by the points given as arguments ,
1191 xcb_void_cookie_t xcb_fill_poly (xcb_connection_t *c,
1192 xcb_drawable_t drawable,
1195 uint8_t coordinate_mode,
1196 uint32_t points_len,
1197 const xcb_point_t *points);
1200 The <span class="code">shape</span> parameter specifies a
1201 shape that helps the server to improve performance. Available
1205 <li><span class="code">XCB_POLY_SHAPE_COMPLEX</span>
1206 <li><span class="code">XCB_POLY_SHAPE_NONCONVEX</span>
1207 <li><span class="code">XCB_POLY_SHAPE_CONVEX</span>
1210 To fill one or several rectangles, we use
1213 xcb_void_cookie_t xcb_poly_fill_rectangle (xcb_connection_t *c,
1214 xcb_drawable_t drawable,
1216 uint32_t rectangles_len,
1217 const xcb_rectangle_t *rectangles);
1220 To fill one or several arcs, we use
1223 xcb_void_cookie_t xcb_poly_fill_arc (xcb_connection_t *c,
1224 xcb_drawable_t drawable,
1227 const xcb_arc_t *arcs);
1230 <a name="points.c"></a>
1232 To illustrate these functions, here is an example that draws
1233 four points, a polygonal line, two segments, two rectangles
1234 and two arcs. Remark that we use events for the first time, as
1235 an introduction to the next section.
1238 <b>TODO:</b> Use screen->root_depth for depth parameter.
1241 #include <stdlib.h>
1242 #include <stdio.h>
1244 #include <xcb/xcb.h>
1249 xcb_connection_t *c;
1250 xcb_screen_t *screen;
1252 xcb_gcontext_t foreground;
1253 xcb_generic_event_t *e;
1257 /* geometric objects */
1258 xcb_point_t points[] = {
1264 xcb_point_t polyline[] = {
1266 { 5, 20}, /* rest of points are relative */
1270 xcb_segment_t segments[] = {
1272 {110, 25, 130, 60}};
1274 xcb_rectangle_t rectangles[] = {
1278 xcb_arc_t arcs[] = {
1279 {10, 100, 60, 40, 0, 90 << 6},
1280 {90, 100, 55, 40, 0, 270 << 6}};
1282 /* Open the connection to the X server */
1283 c = xcb_connect (NULL, NULL);
1285 /* Get the first screen */
1286 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1288 /* Create black (foreground) graphic context */
1289 win = screen->root;
1291 foreground = xcb_generate_id (c);
1292 mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
1293 values[0] = screen->black_pixel;
1295 xcb_create_gc (c, foreground, win, mask, values);
1297 /* Ask for our window's Id */
1298 win = xcb_generate_id(c);
1300 /* Create the window */
1301 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1302 values[0] = screen->white_pixel;
1303 values[1] = XCB_EVENT_MASK_EXPOSURE;
1304 xcb_create_window (c, /* Connection */
1305 XCB_COPY_FROM_PARENT, /* depth */
1306 win, /* window Id */
1307 screen->root, /* parent window */
1309 150, 150, /* width, height */
1310 10, /* border_width */
1311 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
1312 screen->root_visual, /* visual */
1313 mask, values); /* masks */
1315 /* Map the window on the screen */
1316 xcb_map_window (c, win);
1319 /* We flush the request */
1322 while ((e = xcb_wait_for_event (c))) {
1323 switch (e->response_type & ~0x80) {
1325 /* We draw the points */
1326 xcb_poly_point (c, XCB_COORD_MODE_ORIGIN, win, foreground, 4, points);
1328 /* We draw the polygonal line */
1329 xcb_poly_line (c, XCB_COORD_MODE_PREVIOUS, win, foreground, 4, polyline);
1331 /* We draw the segements */
1332 xcb_poly_segment (c, win, foreground, 2, segments);
1334 /* We draw the rectangles */
1335 xcb_poly_rectangle (c, win, foreground, 2, rectangles);
1337 /* We draw the arcs */
1338 xcb_poly_arc (c, win, foreground, 2, arcs);
1340 /* We flush the request */
1346 /* Unknown event type, ignore it */
1350 /* Free the Generic Event */
1358 <li class="title"><a name="xevents">X Events</a>
1360 In an X program, everything is driven by events. Event painting
1361 on the screen is sometimes done as a response to an event (an
1362 <span class="code">Expose</span> event). If part of a program's
1363 window that was hidden, gets exposed (e.g. the window was raised
1364 above other widows), the X server will send an "expose" event to
1365 let the program know it should repaint that part of the
1366 window. User input (key presses, mouse movement, etc) is also
1367 received as a set of events.
1370 <li class="subtitle"><a name="register">Registering for event types using event masks</a>
1372 During the creation of a window, you should give it what kind
1373 of events it wishes to receive. Thus, you may register for
1374 various mouse (also called pointer) events, keyboard events,
1375 expose events, and so on. This is done for optimizing the
1376 server-to-client connection (i.e. why send a program (that
1377 might even be running at the other side of the globe) an event
1378 it is not interested in ?)
1381 In XCB, you use the "value_mask" and "value_list" data in the
1382 <span class="code">xcb_create_window()</span> function to
1383 register for events. Here is how we register for
1384 <span class="code">Expose</span> event when creating a window:
1387 mask = XCB_CW_EVENT_MASK;
1388 valwin[0] = XCB_EVENT_MASK_EXPOSURE;
1389 win = xcb_generate_id (c);
1390 xcb_create_window (c, depth, win, root->root,
1392 XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual,
1396 <span class="code">XCB_EVENT_MASK_EXPOSURE</span> is a constant defined
1397 in the xcb_event_mask_t enumeration in the "xproto.h" header file. If we wanted to register for several
1398 event types, we can logically "or" them, as follows:
1401 mask = XCB_CW_EVENT_MASK;
1402 valwin[0] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS;
1403 win = xcb_generate_id (c);
1404 xcb_create_window (c, depth, win, root->root,
1406 XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual,
1410 This registers for <span class="code">Expose</span> events as
1411 well as for mouse button presses inside the created
1412 window. You should note that a mask may represent several
1416 The values that a mask could take are given
1417 by the <span class="code">xcb_cw_t</span> enumeration:
1421 XCB_CW_BACK_PIXMAP = 1L<<0,
1422 XCB_CW_BACK_PIXEL = 1L<<1,
1423 XCB_CW_BORDER_PIXMAP = 1L<<2,
1424 XCB_CW_BORDER_PIXEL = 1L<<3,
1425 XCB_CW_BIT_GRAVITY = 1L<<4,
1426 XCB_CW_WIN_GRAVITY = 1L<<5,
1427 XCB_CW_BACKING_STORE = 1L<<6,
1428 XCB_CW_BACKING_PLANES = 1L<<7,
1429 XCB_CW_BACKING_PIXEL = 1L<<8,
1430 XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
1431 XCB_CW_SAVE_UNDER = 1L<<10,
1432 XCB_CW_EVENT_MASK = 1L<<11,
1433 XCB_CW_DONT_PROPAGATE = 1L<<12,
1434 XCB_CW_COLORMAP = 1L<<13,
1435 XCB_CW_CURSOR = 1L<<14
1439 <p>Note: we must be careful when setting the values of the valwin
1440 parameter, as they have to follow the order the
1441 <span class="code">xcb_cw_t</span> enumeration. Here is an
1446 mask = XCB_CW_EVENT_MASK | XCB_CW_BACK_PIXMAP;
1447 valwin[0] = XCB_NONE; /* for XCB_CW_BACK_PIXMAP (whose value is 1) */
1448 valwin[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; /* for XCB_CW_EVENT_MASK, whose value (2048) */
1449 /* is greater than the one of XCB_CW_BACK_PIXMAP */
1452 If the window has already been created, we can use the
1453 <span class="code">xcb_configure_window()</span> function to set
1454 the events that the window will receive. The subsection
1455 <a href="#winconf">Configuring a window</a> shows its
1456 prototype. As an example, here is a piece of code that
1457 configures the window to receive the
1458 <span class="code">Expose</span> and
1459 <span class="code">ButtonPress</span> events:
1462 const static uint32_t values[] = { XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS };
1464 /* The connection c and the window win are supposed to be defined */
1466 xcb_configure_window (c, win, XCB_CW_EVENT_MASK, values);
1470 Note: A common bug programmers do is adding code to handle new
1471 event types in their program, while forgetting to add the
1472 masks for these events in the creation of the window. Such a
1473 programmer then should sit down for hours debugging his
1474 program, wondering "Why doesn't my program notice that I
1475 released the button?", only to find that they registered for
1476 button press events but not for button release events.
1479 <li class="subtitle"><a name="loop">Receiving events: writing the events loop</a>
1481 After we have registered for the event types we are interested
1482 in, we need to enter a loop of receiving events and handling
1483 them. There are two ways to receive events: a blocking way and
1488 <span class="code">xcb_wait_for_event (xcb_connection_t *c)</span>
1489 is the blocking way. It waits (so blocks...) until an event is
1490 queued in the X server. Then it retrieves it into a newly
1491 allocated structure (it dequeues it from the queue) and returns
1492 it. This structure has to be freed. The function returns
1493 <span class="code">NULL</span> if an error occurs.
1497 <span class="code">xcb_poll_for_event (xcb_connection_t *c, int
1498 *error)</span> is the non-blocking way. It looks at the event
1499 queue and returns (and dequeues too) an existing event into
1500 a newly allocated structure. This structure has to be
1501 freed. It returns <span class="code">NULL</span> if there is
1502 no event. If an error occurs, the parameter <span
1503 class="code">error</span> will be filled with the error
1507 There are various ways to write such a loop. We present two
1508 ways to write such a loop, with the two functions above. The
1509 first one uses <span class="code">xcb_wait_for_event_t</span>, which
1510 is similar to an event Xlib loop using only <span
1511 class="code">XNextEvent</span>:
1514 xcb_generic_event_t *e;
1516 while ((e = xcb_wait_for_event (c))) {
1517 switch (e->response_type & ~0x80) {
1519 /* Handle the Expose event type */
1520 xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1526 case XCB_BUTTON_PRESS: {
1527 /* Handle the ButtonPress event type */
1528 xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1535 /* Unknown event type, ignore it */
1539 /* Free the Generic Event */
1544 You will certainly want to use <span
1545 class="code">xcb_poll_for_event(xcb_connection_t *c, int
1546 *error)</span> if, in Xlib, you use <span
1547 class="code">XPending</span> or
1548 <span class="code">XCheckMaskEvent</span>:
1551 while (XPending (display)) {
1554 XNextEvent(d, &ev);
1556 /* Manage your event */
1560 Such a loop in XCB looks like:
1563 xcb_generic_event_t *ev;
1565 while ((ev = xcb_poll_for_event (conn, 0))) {
1566 /* Manage your event */
1570 The events are managed in the same way as with <span
1571 class="code">xcb_wait_for_event_t</span>.
1572 Obviously, we will need to give the user some way of
1573 terminating the program. This is usually done by handling a
1574 special "quit" event, as we will soon see.
1587 <li>xcb_wait_for_event ()
1593 <li>XCheckMaskEvent ()
1598 <li>xcb_poll_for_event ()
1603 <li class="subtitle"><a name="expose">Expose events</a>
1605 The <span class="code">Expose</span> event is one of the most
1606 basic (and most used) events an application may receive. It
1607 will be sent to us in one of several cases:
1610 <li>A window that covered part of our window has moved
1611 away, exposing part (or all) of our window.
1612 <li>Our window was raised above other windows.
1613 <li>Our window mapped for the first time.
1614 <li>Our window was de-iconified.
1617 You should note the implicit assumption hidden here: the
1618 contents of our window is lost when it is being obscured
1619 (covered) by either windows. One may wonder why the X server
1620 does not save this contents. The answer is: to save
1621 memory. After all, the number of windows on a display at a
1622 given time may be very large, and storing the contents of all
1623 of them might require a lot of memory. Actually, there is a
1624 way to tell the X server to store the contents of a window in
1625 special cases, as we will see later.
1628 When we get an <span class="code">Expose</span> event, we
1629 should take the event's data from the members of the following
1634 uint8_t response_type; /* The type of the event, here it is XCB_EXPOSE */
1637 xcb_window_t window; /* The Id of the window that receives the event (in case */
1638 /* our application registered for events on several windows */
1639 uint16_t x; /* The x coordinate of the top-left part of the window that needs to be redrawn */
1640 uint16_t y; /* The y coordinate of the top-left part of the window that needs to be redrawn */
1641 uint16_t width; /* The width of the part of the window that needs to be redrawn */
1642 uint16_t height; /* The height of the part of the window that needs to be redrawn */
1644 } xcb_expose_event_t;
1646 <li class="subtitle"><a name="userinput">Getting user input</a>
1648 User input traditionally comes from two sources: the mouse
1649 and the keyboard. Various event types exist to notify us of
1650 user input (a key being presses on the keyboard, a key being
1651 released on the keyboard, the mouse moving over our window,
1652 the mouse entering (or leaving) our window, and so on.
1655 <li class="subsubtitle"><a name="mousepressrelease">Mouse button press and release events</a>
1657 The first event type we will deal with is a mouse
1658 button-press (or button-release) event in our window. In
1659 order to register to such an event type, we should add one
1660 (or more) of the following masks when we create our window:
1663 <li><span class="code">XCB_EVENT_MASK_BUTTON_PRESS</span>: notify us
1664 of any button that was pressed in one of our windows.
1665 <li><span class="code">XCB_EVENT_MASK_BUTTON_RELEASE</span>: notify us
1666 of any button that was released in one of our windows.
1669 The structure to be checked for in our events loop is the
1670 same for these two events, and is the following:
1674 uint8_t response_type; /* The type of the event, here it is xcb_button_press_event_t or xcb_button_release_event_t */
1675 xcb_button_t detail;
1677 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1683 int16_t event_x; /* The x coordinate where the mouse has been pressed in the window */
1684 int16_t event_y; /* The y coordinate where the mouse has been pressed in the window */
1685 uint16_t state; /* A mask of the buttons (or keys) during the event */
1686 uint8_t same_screen;
1687 } xcb_button_press_event_t;
1689 typedef xcb_button_press_event_t xcb_button_release_event_t;
1692 The <span class="code">time</span> field may be used to calculate "double-click"
1693 situations by an application (e.g. if the mouse button was
1694 clicked two times in a duration shorter than a given amount
1695 of time, assume this was a double click).
1698 The <span class="code">state</span> field is a mask of the buttons held down during
1699 the event. It is a bitwise OR of any of the following (from the xcb_button_mask_t and
1700 xcb_mod_mask_t enumerations):
1703 <li><span class="code">XCB_BUTTON_MASK_1</span>
1704 <li><span class="code">XCB_BUTTON_MASK_2</span>
1705 <li><span class="code">XCB_BUTTON_MASK_3</span>
1706 <li><span class="code">XCB_BUTTON_MASK_4</span>
1707 <li><span class="code">XCB_BUTTON_MASK_5</span>
1708 <li><span class="code">XCB_MOD_MASK_SHIFT</span>
1709 <li><span class="code">XCB_MOD_MASK_LOCK</span>
1710 <li><span class="code">XCB_MOD_MASK_CONTROL</span>
1711 <li><span class="code">XCB_MOD_MASK_1</span>
1712 <li><span class="code">XCB_MOD_MASK_2</span>
1713 <li><span class="code">XCB_MOD_MASK_3</span>
1714 <li><span class="code">XCB_MOD_MASK_4</span>
1715 <li><span class="code">XCB_MOD_MASK_5</span>
1718 Their names are self explanatory, where the first 5 refer to
1719 the mouse buttons that are being pressed, while the rest
1720 refer to various "special keys" that are being pressed (Mod1
1721 is usually the 'Alt' key or the 'Meta' key).
1724 <b>TODO:</b> Problem: it seems that the state does not
1725 change when clicking with various buttons.
1727 <li class="subsubtitle"><a name="mousemvnt">Mouse movement events</a>
1729 Similar to mouse button press and release events, we also
1730 can be notified of various mouse movement events. These can
1731 be split into two families. One is of mouse pointer
1732 movement while no buttons are pressed, and the second is a
1733 mouse pointer motion while one (or more) of the buttons are
1734 pressed (this is sometimes called "a mouse drag operation",
1735 or just "dragging"). The following event masks may be added
1736 during the creation of our window:
1739 <li><span class="code">XCB_EVENT_MASK_POINTER_MOTION</span>: events of
1740 the pointer moving in one of the windows controlled by our
1741 application, while no mouse button is held pressed.
1742 <li><span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>: Events of
1743 the pointer moving while one or more of the mouse buttons
1745 <li><span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>: same as
1746 <span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>, but only when
1747 the 1st mouse button is held pressed.
1748 <li><span class="code">XCB_EVENT_MASK_BUTTON_2_MOTION</span>,
1749 <span class="code">XCB_EVENT_MASK_BUTTON_3_MOTION</span>,
1750 <span class="code">XCB_EVENT_MASK_BUTTON_4_MOTION</span>,
1751 <span class="code">XCB_EVENT_MASK_BUTTON_5_MOTION</span>: same as
1752 <span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>, but
1753 respectively for 2nd, 3rd, 4th and 5th mouse button.
1756 The structure to be checked for in our events loop is the
1757 same for these events, and is the following:
1761 uint8_t response_type; /* The type of the event */
1764 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1770 int16_t event_x; /* The x coordinate of the mouse when the event was generated */
1771 int16_t event_y; /* The y coordinate of the mouse when the event was generated */
1772 uint16_t state; /* A mask of the buttons (or keys) during the event */
1773 uint8_t same_screen;
1774 } xcb_motion_notify_event_t;
1776 <li class="subsubtitle"><a name="mouseenter">Mouse pointer enter and leave events</a>
1778 Another type of event that applications might be interested
1779 in, is a mouse pointer entering a window the program
1780 controls, or leaving such a window. Some programs use these
1781 events to show the user that the application is now in
1782 focus. In order to register for such an event type, we
1783 should add one (or more) of the following masks when we
1787 <li><span class="code">xcb_event_enter_window_t</span>: notify us
1788 when the mouse pointer enters any of our controlled
1790 <li><span class="code">xcb_event_leave_window_t</span>: notify us
1791 when the mouse pointer leaves any of our controlled
1795 The structure to be checked for in our events loop is the
1796 same for these two events, and is the following:
1800 uint8_t response_type; /* The type of the event */
1803 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1809 int16_t event_x; /* The x coordinate of the mouse when the event was generated */
1810 int16_t event_y; /* The y coordinate of the mouse when the event was generated */
1811 uint16_t state; /* A mask of the buttons (or keys) during the event */
1812 uint8_t mode; /* The number of mouse button that was clicked */
1813 uint8_t same_screen_focus;
1814 } xcb_enter_notify_event_t;
1816 typedef xcb_enter_notify_event_t xcb_leave_notify_event_t;
1818 <li class="subsubtitle"><a name="focus">The keyboard focus</a>
1820 There may be many windows on a screen, but only a single
1821 keyboard attached to them. How does the X server then know
1822 which window should be sent a given keyboard input ? This is
1823 done using the keyboard focus. Only a single window on the
1824 screen may have the keyboard focus at a given time. There
1825 is a XCB function that allows a program to set the keyboard
1826 focus to a given window. The user can usually set the
1827 keyboard focus using the window manager (often by clicking
1828 on the title bar of the desired window). Once our window
1829 has the keyboard focus, every key press or key release will
1830 cause an event to be sent to our program (if it regsitered
1831 for these event types...).
1833 <li class="subsubtitle"><a name="keypress">Keyboard press and release events</a>
1835 If a window controlled by our program currently holds the
1836 keyboard focus, it can receive key press and key release
1837 events. So, we should add one (or more) of the following
1838 masks when we create our window:
1841 <li><span class="code">XCB_EVENT_MASK_KEY_PRESS</span>: notify us when
1842 a key was pressed while any of our controlled windows had
1844 <li><span class="code">XCB_EVENT_MASK_KEY_RELEASE</span>: notify us
1845 when a key was released while any of our controlled
1846 windows had the keyboard focus.
1849 The structure to be checked for in our events loop is the
1850 same for these two events, and is the following:
1854 uint8_t response_type; /* The type of the event */
1855 xcb_keycode_t detail;
1857 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1866 uint8_t same_screen;
1867 } xcb_key_press_event_t;
1869 typedef xcb_key_press_event_t xcb_key_release_event_t;
1872 The <span class="code">detail</span> field refers to the
1873 physical key on the keyboard.
1876 <b>TODO:</b> Talk about getting the ASCII code from the key code.
1879 <li class="subtitle"><a name="eventex">X events: a complete example</a>
1881 As an example for handling events, we show a program that
1882 creates a window, enters an events loop and checks for all the
1883 events described above, and writes on the terminal the relevant
1884 characteristics of the event. With this code, it should be
1885 easy to add drawing operations, like those which have been
1889 #include <stdlib.h>
1890 #include <stdio.h>
1892 #include <xcb/xcb.h>
1895 print_modifiers (uint32_t mask)
1897 const char **mod, *mods[] = {
1898 "Shift", "Lock", "Ctrl", "Alt",
1899 "Mod2", "Mod3", "Mod4", "Mod5",
1900 "Button1", "Button2", "Button3", "Button4", "Button5"
1902 printf ("Modifier mask: ");
1903 for (mod = mods ; mask; mask >>= 1, mod++)
1912 xcb_connection_t *c;
1913 xcb_screen_t *screen;
1915 xcb_generic_event_t *e;
1919 /* Open the connection to the X server */
1920 c = xcb_connect (NULL, NULL);
1922 /* Get the first screen */
1923 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1925 /* Ask for our window's Id */
1926 win = xcb_generate_id (c);
1928 /* Create the window */
1929 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1930 values[0] = screen->white_pixel;
1931 values[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS |
1932 XCB_EVENT_MASK_BUTTON_RELEASE | XCB_EVENT_MASK_POINTER_MOTION |
1933 XCB_EVENT_MASK_ENTER_WINDOW | XCB_EVENT_MASK_LEAVE_WINDOW |
1934 XCB_EVENT_MASK_KEY_PRESS | XCB_EVENT_MASK_KEY_RELEASE;
1935 xcb_create_window (c, /* Connection */
1937 win, /* window Id */
1938 screen->root, /* parent window */
1940 150, 150, /* width, height */
1941 10, /* border_width */
1942 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
1943 screen->root_visual, /* visual */
1944 mask, values); /* masks */
1946 /* Map the window on the screen */
1947 xcb_map_window (c, win);
1951 while ((e = xcb_wait_for_event (c))) {
1952 switch (e->response_type & ~0x80) {
1954 xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1956 printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
1957 ev->window, ev->x, ev->y, ev->width, ev->height);
1960 case XCB_BUTTON_PRESS: {
1961 xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1962 print_modifiers(ev->state);
1964 switch (ev->detail) {
1966 printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
1967 ev->event, ev->event_x, ev->event_y);
1970 printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
1971 ev->event, ev->event_x, ev->event_y);
1974 printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
1975 ev->detail, ev->event, ev->event_x, ev->event_y);
1979 case XCB_BUTTON_RELEASE: {
1980 xcb_button_release_event_t *ev = (xcb_button_release_event_t *)e;
1981 print_modifiers(ev->state);
1983 printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
1984 ev->detail, ev->event, ev->event_x, ev->event_y);
1987 case XCB_MOTION_NOTIFY: {
1988 xcb_motion_notify_event_t *ev = (xcb_motion_notify_event_t *)e;
1990 printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
1991 ev->event, ev->event_x, ev->event_y);
1994 case XCB_ENTER_NOTIFY: {
1995 xcb_enter_notify_event_t *ev = (xcb_enter_notify_event_t *)e;
1997 printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
1998 ev->event, ev->event_x, ev->event_y);
2001 case XCB_LEAVE_NOTIFY: {
2002 xcb_leave_notify_event_t *ev = (xcb_leave_notify_event_t *)e;
2004 printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
2005 ev->event, ev->event_x, ev->event_y);
2008 case XCB_KEY_PRESS: {
2009 xcb_key_press_event_t *ev = (xcb_key_press_event_t *)e;
2010 print_modifiers(ev->state);
2012 printf ("Key pressed in window %ld\n",
2016 case XCB_KEY_RELEASE: {
2017 xcb_key_release_event_t *ev = (xcb_key_release_event_t *)e;
2018 print_modifiers(ev->state);
2020 printf ("Key released in window %ld\n",
2025 /* Unknown event type, ignore it */
2026 printf("Unknown event: %d\n", e->response_type);
2029 /* Free the Generic Event */
2037 <li class="title"><a name="font">Handling text and fonts</a>
2039 Besides drawing graphics on a window, we often want to draw
2040 text. Text strings have two major properties: the characters to
2041 be drawn and the font with which they are drawn. In order to
2042 draw text, we need to first request the X server to load a
2043 font. We then assign a font to a Graphic Context, and finally, we
2044 draw the text in a window, using the Graphic Context.
2047 <li class="subtitle"><a name="fontstruct">The Font structure</a>
2049 In order to support flexible fonts, a font structure is
2050 defined. You know what ? It's an Id:
2053 typedef uint32_t xcb_font_t;
2056 It is used to contain information about a font, and is passed
2057 to several functions that handle fonts selection and text drawing.
2060 <b>TODO:</b> example for picking a font and displaying some text.
2061 Even better, also demonstrate translating keypresses to text.
2064 <li class="title"><a name="wm">Interacting with the window manager</a>
2066 After we have seen how to create windows and draw on them, we
2067 take one step back, and look at how our windows are interacting
2068 with their environment (the full screen and the other
2069 windows). First of all, our application needs to interact with
2070 the window manager. The window manager is responsible to
2071 decorating drawn windows (i.e. adding a frame, an iconify
2072 button, a system menu, a title bar, etc), as well as handling
2073 icons shown when windows are being iconified. It also handles
2074 ordering of windows on the screen, and other administrative
2075 tasks. We need to give it various hints as to how we want it to
2076 treat our application's windows.
2079 <li class="subtitle"><a name="wmprop">Window properties</a>
2081 Many of the parameters communicated to the window manager are
2082 passed using data called "properties". These properties are
2083 attached by the X server to different windows, and are stored
2084 in a format that makes it possible to read them from different
2085 machines that may use different architectures (remember that
2086 an X client program may run on a remote machine).
2089 The property and its type (a string, an integer, etc) are
2090 Id. Their type are <span class="code">xcb_atom_t</span>:
2093 typedef uint32_t xcb_atom_t;
2096 To change the property of a window, we use the following
2100 xcb_void_cookie_t xcb_change_property (xcb_connection_t *c, /* Connection to the X server */
2101 uint8_t mode, /* Property mode */
2102 xcb_window_t window, /* Window */
2103 xcb_atom_t property, /* Property to change */
2104 xcb_atom_t type, /* Type of the property */
2105 uint8_t format, /* Format of the property (8, 16, 32) */
2106 uint32_t data_len, /* Length of the data parameter */
2107 const void *data); /* Data */
2110 The <span class="code">mode</span> parameter coud be one of
2111 the following values (defined in enumeration xcb_prop_mode_t in
2112 the xproto.h header file):
2115 <li>XCB_PROP_MODE_REPLACE
2116 <li>XCB_PROP_MODE_PREPEND
2117 <li>XCB_PROP_MODE_APPEND
2120 <li class="subtitle"><a name="wmname">Setting the window name and icon name</a>
2122 The first thing we want to do would be to set the name for our
2123 window. This is done using the
2124 <span class="code">xcb_change_property()</span> function. This
2125 name may be used by the window manager as the title of the
2126 window (in the title bar), in a task list, etc. The property
2127 atom to use to set the name of a window is
2128 <span class="code">WM_NAME</span> (and
2129 <span class="code">WM_ICON_NAME</span> for the iconified
2130 window) and its type is <span class="code">STRING</span>. Here
2131 is an example of utilization:
2134 #include <string.h>
2136 #include <xcb/xcb.h>
2137 #include <xcb/xcb_atom.h>
2142 xcb_connection_t *c;
2143 xcb_screen_t *screen;
2145 char *title = "Hello World !";
2146 char *title_icon = "Hello World ! (iconified)";
2150 /* Open the connection to the X server */
2151 c = xcb_connect (NULL, NULL);
2153 /* Get the first screen */
2154 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2156 /* Ask for our window's Id */
2157 win = xcb_generate_id (c);
2159 /* Create the window */
2160 xcb_create_window (c, /* Connection */
2162 win, /* window Id */
2163 screen->root, /* parent window */
2165 250, 150, /* width, height */
2166 10, /* border_width */
2167 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
2168 screen->root_visual, /* visual */
2169 0, NULL); /* masks, not used */
2171 /* Set the title of the window */
2172 xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2174 strlen (title), title);
2176 /* Set the title of the window icon */
2177 xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2178 WM_ICON_NAME, STRING, 8,
2179 strlen(title_icon), title_icon);
2181 /* Map the window on the screen */
2182 xcb_map_window (c, win);
2192 <p>Note: the use of the atoms needs our program to be compiled
2193 and linked against xcb_atom, so that we have to use
2197 gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`
2201 for the program to compile fine.
2205 <li class="title"><a name="winop">Simple window operations</a>
2207 One more thing we can do to our window is manipulate them on the
2208 screen (resize them, move them, raise or lower them, iconify
2209 them, and so on). Some window operations functions are supplied
2210 by XCB for this purpose.
2213 <li class="subtitle"><a name="winmap">Mapping and un-mapping a window</a>
2215 The first pair of operations we can apply on a window is
2216 mapping it, or un-mapping it. Mapping a window causes the
2217 window to appear on the screen, as we have seen in our simple
2218 window program example. Un-mapping it causes it to be removed
2219 from the screen (although the window as a logical entity still
2220 exists). This gives the effect of making a window hidden
2221 (unmapped) and shown again (mapped). For example, if we have a
2222 dialog box window in our program, instead of creating it every
2223 time the user asks to open it, we can create the window once,
2224 in an un-mapped mode, and when the user asks to open it, we
2225 simply map the window on the screen. When the user clicked the
2226 'OK' or 'Cancel' button, we simply un-map the window. This is
2227 much faster than creating and destroying the window, however,
2228 the cost is wasted resources, both on the client side, and on
2232 To map a window, you use the following function:
2235 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
2236 xcb_window_t window);
2239 To have a simple example, see the <a href="#helloworld">example</a>
2240 above. The mapping operation will cause an
2241 <span class="code">Expose</span> event to be sent to our
2242 application, unless the window is completely covered by other
2246 Un-mapping a window is also simple. You use the function
2249 xcb_void_cookie_t xcb_unmap_window (xcb_connection_t *c,
2250 xcb_window_t window);
2253 The utilization of this function is the same as
2254 <span class="code">xcb_map_window()</span>.
2256 <li class="subtitle"><a name="winconf">Configuring a window</a>
2258 As we have seen when we have created our first window, in the
2259 X Events subsection, we can set some attributes for the window
2260 (that is, the position, the size, the events the window will
2261 receive, etc). If we want to modify them, but the window is
2262 already created, we can change them by using the following
2266 xcb_void_cookie_t xcb_configure_window (xcb_connection_t *c, /* The connection to the X server*/
2267 xcb_window_t window, /* The window to configure */
2268 uint16_t value_mask, /* The mask */
2269 const uint32_t *value_list); /* The values to set */
2272 We set the <span class="code">value_mask</span> to one or
2273 several mask values that are in the xcb_config_window_t enumeration in the xproto.h header:
2276 <li><span class="code">XCB_CONFIG_WINDOW_X</span>: new x coordinate of the window's top left corner
2277 <li><span class="code">XCB_CONFIG_WINDOW_Y</span>: new y coordinate of the window's top left corner
2278 <li><span class="code">XCB_CONFIG_WINDOW_WIDTH</span>: new width of the window
2279 <li><span class="code">XCB_CONFIG_WINDOW_HEIGHT</span>: new height of the window
2280 <li><span class="code">XCB_CONFIG_WINDOW_BORDER_WIDTH</span>: new width of the border of the window
2281 <li><span class="code">XCB_CONFIG_WINDOW_SIBLING</span>
2282 <li><span class="code">XCB_CONFIG_WINDOW_STACK_MODE</span>: the new stacking order
2285 We then give to <span class="code">value_mask</span> the new
2286 value. We now describe how to use
2287 <span class="code">xcb_configure_window_t</span> in some useful
2290 <li class="subtitle"><a name="winmove">Moving a window around the screen</a>
2292 An operation we might want to do with windows is to move them
2293 to a different location. This can be done like this:
2296 const static uint32_t values[] = { 10, 20 };
2298 /* The connection c and the window win are supposed to be defined */
2300 /* Move the window to coordinates x = 10 and y = 20 */
2301 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y, values);
2304 Note that when the window is moved, it might get partially
2305 exposed or partially hidden by other windows, and thus we
2306 might get <span class="code">Expose</span> events due to this
2309 <li class="subtitle"><a name="winsize">Resizing a window</a>
2311 Yet another operation we can do is to change the size of a
2312 window. This is done using the following code:
2315 const static uint32_t values[] = { 200, 300 };
2317 /* The connection c and the window win are supposed to be defined */
2319 /* Resize the window to width = 10 and height = 20 */
2320 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2323 We can also combine the move and resize operations using one
2324 single call to <span class="code">xcb_configure_window_t</span>:
2327 const static uint32_t values[] = { 10, 20, 200, 300 };
2329 /* The connection c and the window win are supposed to be defined */
2331 /* Move the window to coordinates x = 10 and y = 20 */
2332 /* and resize the window to width = 10 and height = 20 */
2333 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y | XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2335 <li class="subtitle"><a name="winstack">Changing windows stacking order: raise and lower</a>
2337 Until now, we changed properties of a single window. We'll see
2338 that there are properties that relate to the window and other
2339 windows. One of them is the stacking order. That is, the order
2340 in which the windows are layered on top of each other. The
2341 front-most window is said to be on the top of the stack, while
2342 the back-most window is at the bottom of the stack. Here is
2343 how to manipulate our windows stack order:
2346 const static uint32_t values[] = { XCB_STACK_MODE_ABOVE };
2348 /* The connection c and the window win are supposed to be defined */
2350 /* Move the window on the top of the stack */
2351 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2354 const static uint32_t values[] = { XCB_STACK_MODE_BELOW };
2356 /* The connection c and the window win are supposed to be defined */
2358 /* Move the window on the bottom of the stack */
2359 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2361 <li class="subtitle"><a name="wingetinfo">Getting information about a window</a>
2363 Just like we can set various attributes of our windows, we can
2364 also ask the X server supply the current values of these
2365 attributes. For example, we can check where a window is
2366 located on the screen, what is its current size, whether it is
2367 mapped or not, etc. The structure that contains some of this
2372 uint8_t response_type;
2373 uint8_t depth; /* depth of the window */
2376 xcb_window_t root; /* Id of the root window *>
2377 int16_t x; /* X coordinate of the window's location */
2378 int16_t y; /* Y coordinate of the window's location */
2379 uint16_t width; /* Width of the window */
2380 uint16_t height; /* Height of the window */
2381 uint16_t border_width; /* Width of the window's border */
2382 } xcb_get_geometry_reply_t;
2385 XCB fill this structure with two functions:
2388 xcb_get_geometry_cookie_t xcb_get_geometry (xcb_connection_t *c,
2389 xcb_drawable_t drawable);
2390 xcb_get_geometry_reply_t *xcb_get_geometry_reply (xcb_connection_t *c,
2391 xcb_get_geometry_cookie_t cookie,
2392 xcb_generic_error_t **e);
2395 You use them as follows:
2398 xcb_connection_t *c;
2400 xcb_get_geometry_reply_t *geom;
2402 /* You initialize c and win */
2404 geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2406 /* Do something with the fields of geom */
2411 Remark that you have to free the structure, as
2412 <span class="code">xcb_get_geometry_reply_t</span> allocates a
2416 One problem is that the returned location of the window is
2417 relative to its parent window. This makes these coordinates
2418 rather useless for any window manipulation functions, like
2419 moving it on the screen. In order to overcome this problem, we
2420 need to take a two-step operation. First, we find out the Id
2421 of the parent window of our window. We then translate the
2422 above relative coordinates to the screen coordinates.
2425 To get the Id of the parent window, we need this structure:
2429 uint8_t response_type;
2434 xcb_window_t parent; /* Id of the parent window */
2435 uint16_t children_len;
2437 } xcb_query_tree_reply_t;
2440 To fill this structure, we use these two functions:
2443 xcb_query_tree_cookie_t xcb_query_tree (xcb_connection_t *c,
2444 xcb_window_t window);
2445 xcb_query_tree_reply_t *xcb_query_tree_reply (xcb_connection_t *c,
2446 xcb_query_tree_cookie_t cookie,
2447 xcb_generic_error_t **e);
2450 The translated coordinates will be found in this structure:
2454 uint8_t response_type;
2455 uint8_t same_screen;
2459 uint16_t dst_x; /* Translated x coordinate */
2460 uint16_t dst_y; /* Translated y coordinate */
2461 } xcb_translate_coordinates_reply_t;
2464 As usual, we need two functions to fill this structure:
2467 xcb_translate_coordinates_cookie_t xcb_translate_coordinates (xcb_connection_t *c,
2468 xcb_window_t src_window,
2469 xcb_window_t dst_window,
2472 xcb_translate_coordinates_reply_t *xcb_translate_coordinates_reply (xcb_connection_t *c,
2473 xcb_translate_coordinates_cookie_t cookie,
2474 xcb_generic_error_t **e);
2477 We use them as follows:
2480 xcb_connection_t *c;
2482 xcb_get_geometry_reply_t *geom;
2483 xcb_query_tree_reply_t *tree;
2484 xcb_translate_coordinates_reply_t *trans;
2486 /* You initialize c and win */
2488 geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2492 tree = xcb_query_tree_reply (c, xcb_query_tree (c, win), NULL);
2496 trans = xcb_translate_coordinates_reply (c,
2497 xcb_translate_coordinates (c,
2500 geom->x, geom->y),
2505 /* the translated coordinates are in trans->dst_x and trans->dst_y */
2512 Of course, as for <span class="code">geom</span>,
2513 <span class="code">tree</span> and
2514 <span class="code">trans</span> have to be freed.
2517 The work is a bit hard, but XCB is a very low-level library.
2520 <b>TODO:</b> the utilization of these functions should be a
2521 prog, which displays the coordinates of the window.
2524 There is another structure that gives informations about our window:
2528 uint8_t response_type;
2529 uint8_t backing_store;
2532 xcb_visualid_t visual; /* Visual of the window */
2534 uint8_t bit_gravity;
2535 uint8_t win_gravity;
2536 uint32_t backing_planes;
2537 uint32_t backing_pixel;
2539 uint8_t map_is_installed;
2540 uint8_t map_state; /* Map state of the window */
2541 uint8_t override_redirect;
2542 xcb_colormap_t colormap; /* Colormap of the window */
2543 uint32_t all_event_masks;
2544 uint32_t your_event_mask;
2545 uint16_t do_not_propagate_mask;
2546 } xcb_get_window_attributes_reply_t;
2549 XCB supplies these two functions to fill it:
2552 xcb_get_window_attributes_cookie_t xcb_get_window_attributes (xcb_connection_t *c,
2553 xcb_window_t window);
2554 xcb_get_window_attributes_reply_t *xcb_get_window_attributes_reply (xcb_connection_t *c,
2555 xcb_get_window_attributes_cookie_t cookie,
2556 xcb_generic_error_t **e);
2559 You use them as follows:
2562 xcb_connection_t *c;
2564 xcb_get_window_attributes_reply_t *attr;
2566 /* You initialize c and win */
2568 attr = xcb_get_window_attributes_reply (c, xcb_get_window_attributes (c, win), NULL);
2573 /* Do something with the fields of attr */
2578 As for <span class="code">geom</span>,
2579 <span class="code">attr</span> has to be freed.
2582 <li class="title"><a name="usecolor">Using colors to paint the rainbow</a>
2584 Up until now, all our painting operation were done using black
2585 and white. We will (finally) see now how to draw using colors.
2588 <li class="subtitle"><a name="colormap">Color maps</a>
2590 In the beginning, there were not enough colors. Screen
2591 controllers could only support a limited number of colors
2592 simultaneously (initially 2, then 4, 16 and 256). Because of
2593 this, an application could not just ask to draw in a "light
2594 purple-red" color, and expect that color to be available. Each
2595 application allocated the colors it needed, and when all the
2596 color entries (4, 16, 256 colors) were in use, the next color
2597 allocation would fail.
2600 Thus, the notion of "a color map" was introduced. A color map
2601 is a table whose size is the same as the number of
2602 simultaneous colors a given screen controller. Each entry
2603 contained the RGB (Red, Green and Blue) values of a different
2604 color (all colors can be drawn using some combination of red,
2605 green and blue). When an application wants to draw on the
2606 screen, it does not specify which color to use. Rather, it
2607 specifies which color entry of some color map to be used
2608 during this drawing. Change the value in this color map entry
2609 and the drawing will use a different color.
2612 In order to be able to draw using colors that got something to
2613 do with what the programmer intended, color map allocation
2614 functions are supplied. You could ask to allocate entry for a
2615 color with a set of RGB values. If one already existed, you
2616 would get its index in the table. If none existed, and the
2617 table was not full, a new cell would be allocated to contain
2618 the given RGB values, and its index returned. If the table was
2619 full, the procedure would fail. You could then ask to get a
2620 color map entry with a color that is closest to the one you
2621 were asking for. This would mean that the actual drawing on
2622 the screen would be done using colors similar to what you
2623 wanted, but not the same.
2626 On today's more modern screens where one runs an X server with
2627 support for 16 million colors, this limitation looks a little
2628 silly, but remember that there are still older computers with
2629 older graphics cards out there. Using color map, support for
2630 these screen becomes transparent to you. On a display
2631 supporting 16 million colors, any color entry allocation
2632 request would succeed. On a display supporting a limited
2633 number of colors, some color allocation requests would return
2634 similar colors. It won't look as good, but your application
2637 <li class="subtitle"><a name="colormapalloc">Allocating and freeing Color Maps</a>
2639 When you draw using XCB, you can choose to use the standard
2640 color map of the screen your window is displayed on, or you
2641 can allocate a new color map and apply it to a window. In the
2642 latter case, each time the mouse moves onto your window, the
2643 screen color map will be replaced by your window's color map,
2644 and you'll see all the other windows on screen change their
2645 colors into something quite bizzare. In fact, this is the
2646 effect you get with X applications that use the "-install"
2647 command line option.
2650 In XCB, a color map is (as often in X) an Id:
2653 typedef uint32_t xcb_colormap_t;
2656 In order to access the screen's default color map, you just
2657 have to retrieve the <span class="code">default_colormap</span>
2658 field of the <span class="code">xcb_screen_t</span> structure
2660 <a href="#screen">Checking basic information about a connection</a>):
2663 #include <stdio.h>
2665 #include <xcb/xcb.h>
2670 xcb_connection_t *c;
2671 xcb_screen_t *screen;
2672 xcb_colormap_t colormap;
2674 /* Open the connection to the X server and get the first screen */
2675 c = xcb_connect (NULL, NULL);
2676 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2678 colormap = screen->default_colormap;
2684 This will return the color map used by default on the first
2685 screen (again, remember that an X server may support several
2686 different screens, each of which might have its own resources).
2689 The other option, that of allocating a new colormap, works as
2690 follows. We first ask the X server to give an Id to our color
2691 map, with this function:
2694 xcb_colormap_t xcb_generate_id (xcb_connection_t *c);
2697 Then, we create the color map with
2700 xcb_void_cookie_t xcb_create_colormap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
2701 uint8_t alloc, /* Colormap entries to be allocated (AllocNone or AllocAll) */
2702 xcb_colormap_t mid, /* Id of the color map */
2703 xcb_window_t window, /* Window on whose screen the colormap will be created */
2704 xcb_visualid_t visual); /* Id of the visual supported by the screen */
2707 Here is an example of creation of a new color map:
2710 #include <xcb/xcb.h>
2715 xcb_connection_t *c;
2716 xcb_screen_t *screen;
2720 /* Open the connection to the X server and get the first screen */
2721 c = xcb_connect (NULL, NULL);
2722 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2724 /* We create the window win here*/
2726 cmap = xcb_generate_id (c);
2727 xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual);
2733 Note that the window parameter is only used to allow the X
2734 server to create the color map for the given screen. We can
2735 then use this color map for any window drawn on the same screen.
2738 To free a color map, it suffices to use this function:
2741 xcb_void_cookie_t xcb_free_colormap (xcb_connection_t *c, /* The connection */
2742 xcb_colormap_t cmap); /* The color map */
2750 <li>XCreateColormap ()
2755 <li>xcb_generate_id ()
2756 <li>xcb_create_colormap ()
2761 <li>XFreeColormap ()
2766 <li>xcb_free_colormap ()
2771 <li class="subtitle"><a name="alloccolor">Allocating and freeing a color entry</a>
2773 Once we got access to some color map, we can start allocating
2774 colors. The informations related to a color are stored in the
2775 following structure:
2779 uint8_t response_type;
2783 uint16_t red; /* The red component */
2784 uint16_t green; /* The green component */
2785 uint16_t blue; /* The blue component */
2787 uint32_t pixel; /* The entry in the color map, supplied by the X server */
2788 } xcb_alloc_color_reply_t;
2791 XCB supplies these two functions to fill it:
2794 xcb_alloc_color_cookie_t xcb_alloc_color (xcb_connection_t *c,
2795 xcb_colormap_t cmap,
2799 xcb_alloc_color_reply_t *xcb_alloc_color_reply (xcb_connection_t *c,
2800 xcb_alloc_color_cookie_t cookie,
2801 xcb_generic_error_t **e);
2804 The fuction <span class="code">xcb_alloc_color()</span> takes the
2805 3 RGB components as parameters (red, green and blue). Here is an
2806 example of using these functions:
2809 #include <malloc.h>
2811 #include <xcb/xcb.h>
2816 xcb_connection_t *c;
2817 xcb_screen_t *screen;
2819 xcb_colormap_t cmap;
2820 xcb_alloc_color_reply_t *rep;
2822 /* Open the connection to the X server and get the first screen */
2823 c = xcb_connect (NULL, NULL);
2824 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2826 /* We create the window win here*/
2828 cmap = xcb_generate_id (c);
2829 xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual);
2831 rep = xcb_alloc_color_reply (c, xcb_alloc_color (c, cmap, 65535, 0, 0), NULL);
2836 /* Do something with r->pixel or the components */
2844 As <span class="code">xcb_alloc_color_reply()</span> allocates
2845 memory, you have to free <span class="code">rep</span>.
2848 <b>TODO</b>: Talk about freeing colors.
2851 <li class="title"><a name="pixmaps">X Bitmaps and Pixmaps</a>
2853 One thing many so-called "Multi-Media" applications need to do,
2854 is display images. In the X world, this is done using bitmaps
2855 and pixmaps. We have already seen some usage of them when
2856 setting an icon for our application. Lets study them further,
2857 and see how to draw these images inside a window, along side the
2858 simple graphics and text we have seen so far.
2861 One thing to note before delving further, is that XCB (nor Xlib)
2862 supplies no means of manipulating popular image formats, such as
2863 gif, png, jpeg or tiff. It is up to the programmer (or to higher
2864 level graphics libraries) to translate these image formats into
2865 formats that the X server is familiar with (x bitmaps and x
2869 <li class="subtitle"><a name="pixmapswhat">What is a X Bitmap? An X Pixmap?</a>
2871 An X bitmap is a two-color image stored in a format specific
2872 to the X window system. When stored in a file, the bitmap data
2873 looks like a C source file. It contains variables defining the
2874 width and the height of the bitmap, an array containing the
2875 bit values of the bitmap (the size of the array is
2876 (width+7)/8*height and the bit and byte order are LSB), and
2877 an optional hot-spot location (that will
2878 be explained later, when discussing mouse cursors).
2881 An X pixmap is a format used to stored images in the memory of
2882 an X server. This format can store both black and white images
2883 (such as x bitmaps) as well as color images. It is the only
2884 image format supported by the X protocol, and any image to be
2885 drawn on screen, should be first translated into this format.
2888 In actuality, an X pixmap can be thought of as a window that
2889 does not appear on the screen. Many graphics operations that
2890 work on windows, will also work on pixmaps. Indeed, the type
2891 of X pixmap in XCB is an Id like a window:
2894 typedef uint32_t xcb_pixmap_t;
2897 Like Xlib, there is no difference between a Drawable, a Window
2901 typedef uint32_t xcb_drawable_t;
2904 in order to avoid confusion between a window and a pixmap. The
2905 operations that will work the same on a window or a pixmap
2906 will require a <span class="code">xcb_drawable_t</span>
2910 Remark: In Xlib, there is no specific difference between a
2911 <span class="code">Drawable</span>, a
2912 <span class="code">Pixmap</span> or a
2913 <span class="code">Window</span>: all are 32 bit long
2914 integer. XCB wraps all these different IDs in structures to
2915 provide some measure of type-safety.
2918 <li class="subtitle"><a name="pixmapscreate">Creating a pixmap</a>
2920 Sometimes we want to create an un-initialized pixmap, so we
2921 can later draw into it. This is useful for image drawing
2922 programs (creating a new empty canvas will cause the creation
2923 of a new pixmap on which the drawing can be stored). It is
2924 also useful when reading various image formats: we load the
2925 image data into memory, create a pixmap on the server, and
2926 then draw the decoded image data onto that pixmap.
2929 To create a new pixmap, we first ask the X server to give an
2930 Id to our pixmap, with this function:
2933 xcb_pixmap_t xcb_generate_id (xcb_connection_t *c);
2936 Then, XCB supplies the following function to create new pixmaps:
2939 xcb_void_cookie_t xcb_create_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
2940 uint8_t depth, /* Depth of the screen */
2941 xcb_pixmap_t pid, /* Id of the pixmap */
2942 xcb_drawable_t drawable,
2943 uint16_t width, /* Width of the window (in pixels) */
2944 uint16_t height); /* Height of the window (in pixels) */
2947 <b>TODO</b>: Explain the drawable parameter, and give an
2948 example (like <a href="xpoints.c">xpoints.c</a>)
2950 <li class="subtitle"><a name="pixmapsdraw"></a>Drawing a pixmap in a window
2952 Once we got a handle to a pixmap, we can draw it on some
2953 window, using the following function:
2956 xcb_void_cookie_t xcb_copy_area (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
2957 xcb_drawable_t src_drawable, /* The Drawable we want to paste */
2958 xcb_drawable_t dst_drawable, /* The Drawable on which we copy the previous Drawable */
2959 xcb_gcontext_t gc, /* A Graphic Context */
2960 int16_t src_x, /* Top left x coordinate of the region we want to copy */
2961 int16_t src_y, /* Top left y coordinate of the region we want to copy */
2962 int16_t dst_x, /* Top left x coordinate of the region where we want to copy */
2963 int16_t dst_y, /* Top left y coordinate of the region where we want to copy */
2964 uint16_t width, /* Width of the region we want to copy */
2965 uint16_t height); /* Height of the region we want to copy */
2968 As you can see, we could copy the whole pixmap, as well as
2969 only a given rectangle of the pixmap. This is useful to
2970 optimize the drawing speed: we could copy only what we have
2971 modified in the pixmap.
2974 <b>One important note should be made</b>: it is possible to
2975 create pixmaps with different depths on the same screen. When
2976 we perform copy operations (a pixmap onto a window, etc), we
2977 should make sure that both source and target have the same
2978 depth. If they have a different depth, the operation would
2979 fail. The exception to this is if we copy a specific bit plane
2980 of the source pixmap using the
2981 <span class="code">xcb_copy_plane_t</span> function. In such an
2982 event, we can copy a specific plane to the target window (in
2983 actuality, setting a specific bit in the color of each pixel
2984 copied). This can be used to generate strange graphic effects
2985 in a window, but that is beyond the scope of this tutorial.
2987 <li class="subtitle"><a name="pixmapsfree"></a>Freeing a pixmap
2989 Finally, when we are done using a given pixmap, we should free
2990 it, in order to free resources of the X server. This is done
2991 using this function:
2994 xcb_void_cookie_t xcb_free_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
2995 xcb_pixmap_t pixmap); /* A given pixmap */
2998 Of course, after having freed it, we must not try accessing
3002 <b>TODO</b>: Give an example, or a link to xpoints.c
3005 <li class="title"><a name="mousecursor">Messing with the mouse cursor</a>
3007 It it possible to modify the shape of the mouse pointer (also
3008 called the X pointer) when in certain states, as we otfen see in
3009 programs. For example, a busy application would often display
3010 the sand clock over its main window, to give the user a visual
3011 hint that he should wait. Let's see how we can change the mouse
3012 cursor of our windows.
3015 <li class="subtitle"><a name="mousecursorcreate">Creating and destroying a mouse cursor</a>
3017 There are two methods for creating cursors. One of them is by
3018 using a set of predefined cursors, that are supplied by the X
3019 server, the other is by using a user-supplied bitmap.
3022 In the first method, we use a special font named "cursor", and
3023 the function <span class="code">xcb_create_glyph_cursor</span>:
3026 xcb_void_cookie_t xcb_create_glyph_cursor (xcb_connection_t *c,
3028 xcb_font_t source_font, /* font for the source glyph */
3029 xcb_font_t mask_font, /* font for the mask glyph or XCB_NONE */
3030 uint16_t source_char, /* character glyph for the source */
3031 uint16_t mask_char, /* character glyph for the mask */
3032 uint16_t fore_red, /* red value for the foreground of the source */
3033 uint16_t fore_green, /* green value for the foreground of the source */
3034 uint16_t fore_blue, /* blue value for the foreground of the source */
3035 uint16_t back_red, /* red value for the background of the source */
3036 uint16_t back_green, /* green value for the background of the source */
3037 uint16_t back_blue) /* blue value for the background of the source */
3040 <b>TODO</b>: Describe <span class="code">source_char</span>
3041 and <span class="code">mask_char</span>, for example by giving
3042 an example on how to get the values. There is a list there:
3043 <a href="http://tronche.com/gui/x/xlib/appendix/b/">X Font Cursors</a>
3046 So we first open that font (see <a href="#loadfont">Loading a Font</a>)
3047 and create the new cursor. As for every X ressource, we have to
3048 ask for an X id with <span class="code">xcb_generate_id</span>
3053 xcb_cursor_t cursor;
3055 /* The connection is set */
3057 font = xcb_generate_id (conn);
3058 xcb_open_font (conn, font, strlen ("cursor"), "cursor");
3060 cursor = xcb_generate_id (conn);
3061 xcb_create_glyph_cursor (conn, cursor, font, font,
3067 We have created the cursor "right hand" by specifying 58 to
3068 the <span class="code">source_fon</span>t argument and 58 + 1
3069 to the <span class="code">mask_font</span>.
3072 The cursor is destroyed by using the function
3075 xcb_void_cookie_t xcb_free_cursor (xcb_connection_t *c,
3076 xcb_cursor_t cursor);
3079 In the second method, we create a new cursor by using a pair
3080 of pixmaps, with depth of one (that is, two colors
3081 pixmaps). One pixmap defines the shape of the cursor, while
3082 the other works as a mask, specifying which pixels of the
3083 cursor will be actually drawn. The rest of the pixels will be
3087 <b>TODO</b>: give an example.
3089 <li class="subtitle"><a name="mousecursorset">Setting a window's mouse cursor</a>
3091 Once the cursor is created, we can modify the cursor of our
3092 window by using <span class="code">xcb_change_window_attributes</span>
3093 and using the <span class="code">XCB_CWCURSOR</span> attribute:
3097 uint32_t value_list;
3099 /* The connection and window are set */
3100 /* The cursor is already created */
3102 mask = XCB_CWCURSOR;
3103 value_list = cursor;
3104 xcb_change_window_attributes (conn, window, mask, &value_list);
3107 Of course, the cursor and the font must be freed.
3109 <li class="subtitle"><a name="mousecursorexample">Complete example</a>
3111 The following example displays a window with a
3112 button. When entering the window, the window cursor is changed
3113 to an arrow. When clicking once on the button, the cursor is
3114 changed to a hand. When clicking again on the button, the
3115 cursor window gets back to the arrow. The Esc key exits the
3119 #include <stdlib.h>
3120 #include <stdio.h>
3121 #include <string.h>
3123 #include <xcb/xcb.h>
3130 static xcb_gc_t gc_font_get (xcb_connection_t *c,
3131 xcb_screen_t *screen,
3132 xcb_window_t window,
3133 const char *font_name);
3135 static void button_draw (xcb_connection_t *c,
3136 xcb_screen_t *screen,
3137 xcb_window_t window,
3142 static void text_draw (xcb_connection_t *c,
3143 xcb_screen_t *screen,
3144 xcb_window_t window,
3149 static void cursor_set (xcb_connection_t *c,
3150 xcb_screen_t *screen,
3151 xcb_window_t window,
3156 button_draw (xcb_connection_t *c,
3157 xcb_screen_t *screen,
3158 xcb_window_t window,
3163 xcb_point_t points[5];
3164 xcb_void_cookie_t cookie_gc;
3165 xcb_void_cookie_t cookie_line;
3166 xcb_void_cookie_t cookie_text;
3167 xcb_generic_error_t *error;
3174 length = strlen (label);
3177 gc = gc_font_get(c, screen, window, "7x13");
3179 width = 7 * length + 2 * (inset + 1);
3180 height = 13 + 2 * (inset + 1);
3183 points[1].x = x1 + width;
3185 points[2].x = x1 + width;
3186 points[2].y = y1 - height;
3188 points[3].y = y1 - height;
3191 cookie_line = xcb_poly_line_checked (c, XCB_COORD_MODE_ORIGIN,
3192 window, gc, 5, points);
3194 error = xcb_request_check (c, cookie_line);
3196 fprintf (stderr, "ERROR: can't draw lines : %d\n", error->error_code);
3201 cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3203 y1 - inset - 1, label);
3204 error = xcb_request_check (c, cookie_text);
3206 fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3211 cookie_gc = xcb_free_gc (c, gc);
3212 error = xcb_request_check (c, cookie_gc);
3214 fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3221 text_draw (xcb_connection_t *c,
3222 xcb_screen_t *screen,
3223 xcb_window_t window,
3228 xcb_void_cookie_t cookie_gc;
3229 xcb_void_cookie_t cookie_text;
3230 xcb_generic_error_t *error;
3234 length = strlen (label);
3236 gc = gc_font_get(c, screen, window, "7x13");
3238 cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3241 error = xcb_request_check (c, cookie_text);
3243 fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3248 cookie_gc = xcb_free_gc (c, gc);
3249 error = xcb_request_check (c, cookie_gc);
3251 fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3258 gc_font_get (xcb_connection_t *c,
3259 xcb_screen_t *screen,
3260 xcb_window_t window,
3261 const char *font_name)
3263 uint32_t value_list[3];
3264 xcb_void_cookie_t cookie_font;
3265 xcb_void_cookie_t cookie_gc;
3266 xcb_generic_error_t *error;
3271 font = xcb_generate_id (c);
3272 cookie_font = xcb_open_font_checked (c, font,
3276 error = xcb_request_check (c, cookie_font);
3278 fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3283 gc = xcb_generate_id (c);
3284 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3285 value_list[0] = screen->black_pixel;
3286 value_list[1] = screen->white_pixel;
3287 value_list[2] = font;
3288 cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list);
3289 error = xcb_request_check (c, cookie_gc);
3291 fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3296 cookie_font = xcb_close_font_checked (c, font);
3297 error = xcb_request_check (c, cookie_font);
3299 fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3308 cursor_set (xcb_connection_t *c,
3309 xcb_screen_t *screen,
3310 xcb_window_t window,
3313 uint32_t values_list[3];
3314 xcb_void_cookie_t cookie_font;
3315 xcb_void_cookie_t cookie_gc;
3316 xcb_generic_error_t *error;
3318 xcb_cursor_t cursor;
3321 uint32_t value_list;
3323 font = xcb_generate_id (c);
3324 cookie_font = xcb_open_font_checked (c, font,
3327 error = xcb_request_check (c, cookie_font);
3329 fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3334 cursor = xcb_generate_id (c);
3335 xcb_create_glyph_cursor (c, cursor, font, font,
3336 cursor_id, cursor_id + 1,
3340 gc = xcb_generate_id (c);
3341 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3342 values_list[0] = screen->black_pixel;
3343 values_list[1] = screen->white_pixel;
3344 values_list[2] = font;
3345 cookie_gc = xcb_create_gc_checked (c, gc, window, mask, values_list);
3346 error = xcb_request_check (c, cookie_gc);
3348 fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3353 mask = XCB_CW_CURSOR;
3354 value_list = cursor;
3355 xcb_change_window_attributes (c, window, mask, &value_list);
3357 xcb_free_cursor (c, cursor);
3359 cookie_font = xcb_close_font_checked (c, font);
3360 error = xcb_request_check (c, cookie_font);
3362 fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3370 xcb_screen_iterator_t screen_iter;
3371 xcb_connection_t *c;
3372 const xcb_setup_t *setup;
3373 xcb_screen_t *screen;
3374 xcb_generic_event_t *e;
3375 xcb_generic_error_t *error;
3376 xcb_void_cookie_t cookie_window;
3377 xcb_void_cookie_t cookie_map;
3378 xcb_window_t window;
3382 uint8_t is_hand = 0;
3384 /* getting the connection */
3385 c = xcb_connect (NULL, &screen_number);
3387 fprintf (stderr, "ERROR: can't connect to an X server\n");
3391 /* getting the current screen */
3392 setup = xcb_get_setup (c);
3395 screen_iter = xcb_setup_roots_iterator (setup);
3396 for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&screen_iter))
3397 if (screen_number == 0)
3399 screen = screen_iter.data;
3403 fprintf (stderr, "ERROR: can't get the current screen\n");
3408 /* creating the window */
3409 window = xcb_generate_id (c);
3410 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
3411 values[0] = screen->white_pixel;
3413 XCB_EVENT_MASK_KEY_RELEASE |
3414 XCB_EVENT_MASK_BUTTON_PRESS |
3415 XCB_EVENT_MASK_EXPOSURE |
3416 XCB_EVENT_MASK_POINTER_MOTION;
3417 cookie_window = xcb_create_window_checked (c,
3419 window, screen->root,
3420 20, 200, WIDTH, HEIGHT,
3421 0, XCB_WINDOW_CLASS_INPUT_OUTPUT,
3422 screen->root_visual,
3424 cookie_map = xcb_map_window_checked (c, window);
3426 /* error managing */
3427 error = xcb_request_check (c, cookie_window);
3429 fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code);
3433 error = xcb_request_check (c, cookie_map);
3435 fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code);
3440 cursor_set (c, screen, window, 68);
3445 e = xcb_poll_for_event(c);
3447 switch (e->response_type) {
3451 text = "click here to change cursor";
3452 button_draw (c, screen, window,
3453 (WIDTH - 7 * strlen(text)) / 2,
3454 (HEIGHT - 16) / 2, text);
3456 text = "Press ESC key to exit...";
3457 text_draw (c, screen, window, 10, HEIGHT - 10, text);
3460 case XCB_BUTTON_PRESS: {
3461 xcb_button_press_event_t *ev;
3464 ev = (xcb_button_press_event_t *)e;
3465 length = strlen ("click here to change cursor");
3467 if ((ev->event_x >= (WIDTH - 7 * length) / 2) &&
3468 (ev->event_x <= ((WIDTH - 7 * length) / 2 + 7 * length + 6)) &&
3469 (ev->event_y >= (HEIGHT - 16) / 2 - 19) &&
3470 (ev->event_y <= ((HEIGHT - 16) / 2)))
3471 is_hand = 1 - is_hand;
3473 is_hand ? cursor_set (c, screen, window, 58) : cursor_set (c, screen, window, 68);
3475 case XCB_KEY_RELEASE: {
3476 xcb_key_release_event_t *ev;
3478 ev = (xcb_key_release_event_t *)e;
3480 switch (ev->detail) {
3497 <li class="title"><a name="translation">Translation of basic Xlib functions and macros</a>
3499 The problem when you want to port an Xlib program to XCB is that
3500 you don't know if the Xlib function that you want to "translate"
3501 is a X Window one or an Xlib macro. In that section, we describe
3502 a way to translate the usual functions or macros that Xlib
3503 provides. It's usually just a member of a structure.
3506 <li class="subtitle"><a name="displaystructure">Members of the Display structure</a>
3508 In this section, we look at how to translate the macros that
3509 return some members of the <span class="code">Display</span>
3510 structure. They are obtained by using a function that requires a
3511 <span class="code">xcb_connection_t *</span> or a member of the
3512 <span class="code">xcb_setup_t</span> structure
3513 (via the function <span class="code">xcb_get_setup</span>), or
3514 a function that requires that structure.
3517 <li class="subtitle"><a name="ConnectionNumber">ConnectionNumber</a>
3519 This number is the file descriptor that connects the client
3520 to the server. You just have to use that function:
3523 int xcb_get_file_descriptor (xcb_connection_t *c);
3525 <li class="subtitle"><a name="DefaultScreen"></a>DefaultScreen
3527 That number is not stored by XCB. It is returned in the
3528 second parameter of the function <span class="code"><a href="#openconn">xcb_connect</a></span>.
3529 Hence, you have to store it yourself if you want to use
3530 it. Then, to get the <span class="code">xcb_screen_t</span>
3531 structure, you have to iterate on the screens.
3532 The equivalent function of the Xlib's
3533 <span class="code">ScreenOfDisplay</span> function can be
3534 found <a href="#ScreenOfDisplay">below</a>. This is also provided in the
3535 xcb_aux_t library as <span class="code">xcb_aux_get_screen()</span>. OK, here is the
3536 small piece of code to get that number:
3539 xcb_connection_t *c;
3540 int screen_default_nbr;
3542 /* you pass the name of the display you want to xcb_connect_t */
3544 c = xcb_connect (display_name, &screen_default_nbr);
3546 /* screen_default_nbr contains now the number of the default screen */
3548 <li class="subtitle"><a name="QLength"></a>QLength
3553 However, this points out a basic difference in philosophy between
3554 Xlib and XCB. Xlib has several functions for filtering and
3555 manipulating the incoming and outgoing X message queues. XCB
3556 wishes to hide this as much as possible from the user, which
3557 allows for more freedom in implementation strategies.
3559 <li class="subtitle"><a name="ScreenCount"></a>ScreenCount
3561 You get the count of screens with the functions
3562 <span class="code">xcb_get_setup</span>
3564 <span class="code">xcb_setup_roots_iterator</span>
3565 (if you need to iterate):
3568 xcb_connection_t *c;
3571 /* you init the connection */
3573 screen_count = xcb_setup_roots_iterator (xcb_get_setup (c)).rem;
3575 /* screen_count contains now the count of screens */
3578 If you don't want to iterate over the screens, a better way
3579 to get that number is to use
3580 <span class="code">xcb_setup_roots_length_t</span>:
3583 xcb_connection_t *c;
3586 /* you init the connection */
3588 screen_count = xcb_setup_roots_length (xcb_get_setup (c));
3590 /* screen_count contains now the count of screens */
3592 <li class="subtitle"><a name="ServerVendor"></a>ServerVendor
3594 You get the name of the vendor of the server hardware with
3595 the functions <span class="code">xcb_get_setup</span>
3598 class="code">xcb_setup_vendor</span>. Beware
3599 that, unlike Xlib, the string returned by XCB is not
3600 necessarily null-terminaled:
3603 xcb_connection_t *c;
3604 char *vendor = NULL;
3607 /* you init the connection */
3608 length = xcb_setup_vendor_length (xcb_get_setup (c));
3609 vendor = (char *)malloc (length + 1);
3611 memcpy (vendor, xcb_setup_vendor (xcb_get_setup (c)), length);
3612 vendor[length] = '\0';
3614 /* vendor contains now the name of the vendor. Must be freed when not used anymore */
3616 <li class="subtitle"><a name="ProtocolVersion"></a>ProtocolVersion
3618 You get the major version of the protocol in the
3619 <span class="code">xcb_setup_t</span>
3620 structure, with the function <span class="code">xcb_get_setup</span>:
3623 xcb_connection_t *c;
3624 uint16_t protocol_major_version;
3626 /* you init the connection */
3628 protocol_major_version = xcb_get_setup (c)->protocol_major_version;
3630 /* protocol_major_version contains now the major version of the protocol */
3632 <li class="subtitle"><a name="ProtocolRevision"></a>ProtocolRevision
3634 You get the minor version of the protocol in the
3635 <span class="code">xcb_setup_t</span>
3636 structure, with the function <span class="code">xcb_get_setup</span>:
3639 xcb_connection_t *c;
3640 uint16_t protocol_minor_version;
3642 /* you init the connection */
3644 protocol_minor_version = xcb_get_setup (c)->protocol_minor_version;
3646 /* protocol_minor_version contains now the minor version of the protocol */
3648 <li class="subtitle"><a name="VendorRelease"></a>VendorRelease
3650 You get the number of the release of the server hardware in the
3651 <span class="code">xcb_setup_t</span>
3652 structure, with the function <span class="code">xcb_get_setup</span>:
3655 xcb_connection_t *c;
3656 uint32_t release_number;
3658 /* you init the connection */
3660 release_number = xcb_get_setup (c)->release_number;
3662 /* release_number contains now the number of the release of the server hardware */
3664 <li class="subtitle"><a name="DisplayString"></a>DisplayString
3666 The name of the display is not stored in XCB. You have to
3667 store it by yourself.
3669 <li class="subtitle"><a name="BitmapUnit"></a>BitmapUnit
3671 You get the bitmap scanline unit in the
3672 <span class="code">xcb_setup_t</span>
3673 structure, with the function <span class="code">xcb_get_setup</span>:
3676 xcb_connection_t *c;
3677 uint8_t bitmap_format_scanline_unit;
3679 /* you init the connection */
3681 bitmap_format_scanline_unit = xcb_get_setup (c)->bitmap_format_scanline_unit;
3683 /* bitmap_format_scanline_unit contains now the bitmap scanline unit */
3685 <li class="subtitle"><a name="BitmapBitOrder"></a>BitmapBitOrder
3687 You get the bitmap bit order in the
3688 <span class="code">xcb_setup_t</span>
3689 structure, with the function <span class="code">xcb_get_setup</span>:
3692 xcb_connection_t *c;
3693 uint8_t bitmap_format_bit_order;
3695 /* you init the connection */
3697 bitmap_format_bit_order = xcb_get_setup (c)->bitmap_format_bit_order;
3699 /* bitmap_format_bit_order contains now the bitmap bit order */
3701 <li class="subtitle"><a name="BitmapPad"></a>BitmapPad
3703 You get the bitmap scanline pad in the
3704 <span class="code">xcb_setup_t</span>
3705 structure, with the function <span class="code">xcb_get_setup</span>:
3708 xcb_connection_t *c;
3709 uint8_t bitmap_format_scanline_pad;
3711 /* you init the connection */
3713 bitmap_format_scanline_pad = xcb_get_setup (c)->bitmap_format_scanline_pad;
3715 /* bitmap_format_scanline_pad contains now the bitmap scanline pad */
3717 <li class="subtitle"><a name="ImageByteOrder"></a>ImageByteOrder
3719 You get the image byte order in the
3720 <span class="code">xcb_setup_t</span>
3721 structure, with the function <span class="code">xcb_get_setup</span>:
3724 xcb_connection_t *c;
3725 uint8_t image_byte_order;
3727 /* you init the connection */
3729 image_byte_order = xcb_get_setup (c)->image_byte_order;
3731 /* image_byte_order contains now the image byte order */
3734 <li class="subtitle"><a name="screenofdisplay">ScreenOfDisplay related functions</a>
3736 in Xlib, <span class="code">ScreenOfDisplay</span> returns a
3737 <span class="code">Screen</span> structure that contains
3738 several characteristics of your screen. XCB has a similar
3739 structure (<span class="code">xcb_screen_t</span>),
3740 but the way to obtain it is a bit different. With
3741 Xlib, you just provide the number of the screen and you grab it
3742 from an array. With XCB, you iterate over all the screens to
3743 obtain the one you want. The complexity of this operation is
3744 O(n). So the best is to store this structure if you use
3745 it often. See <a href="#ScreenOfDisplay">screen_of_display</a> just below.
3748 Xlib provides generally two functions to obtain the characteristics
3749 related to the screen. One with the display and the number of
3750 the screen, which calls <span class="code">ScreenOfDisplay</span>,
3751 and the other that uses the <span class="code">Screen</span> structure.
3752 This might be a bit confusing. As mentioned above, with XCB, it
3753 is better to store the <span class="code">xcb_screen_t</span>
3754 structure. Then, you have to read the members of this
3755 structure. That's why the Xlib functions are put by pairs (or
3756 more) as, with XCB, you will use the same code.
3759 <li class="subtitle"><a name="ScreenOfDisplay">ScreenOfDisplay</a>
3761 This function returns the Xlib <span class="code">Screen</span>
3762 structure. With XCB, you iterate over all the screens and
3763 once you get the one you want, you return it:
3765 <pre class="code"><a name="ScreenOfDisplay"></a>
3766 xcb_screen_t *screen_of_display (xcb_connection_t *c,
3769 xcb_screen_iterator_t iter;
3771 iter = xcb_setup_roots_iterator (xcb_get_setup (c));
3772 for (; iter.rem; --screen, xcb_screen_next (&iter))
3780 As mentioned above, you might want to store the value
3781 returned by this function.
3784 All the functions below will use the result of that
3785 function, as they just grab a specific member of the
3786 <span class="code">xcb_screen_t</span> structure.
3788 <li class="subtitle"><a name="DefaultScreenOfDisplay"></a>DefaultScreenOfDisplay
3790 It is the default screen that you obtain when you connect to
3791 the X server. It suffices to call the <a href="#ScreenOfDisplay">screen_of_display</a>
3792 function above with the connection and the number of the
3796 xcb_connection_t *c;
3797 int screen_default_nbr;
3798 xcb_screen_t *default_screen; /* the returned default screen */
3800 /* you pass the name of the display you want to xcb_connect_t */
3802 c = xcb_connect (display_name, &screen_default_nbr);
3803 default_screen = screen_of_display (c, screen_default_nbr);
3805 /* default_screen contains now the default root window, or a NULL window if no screen is found */
3807 <li class="subtitle"><a name="RootWindow">RootWindow / RootWindowOfScreen</a>
3810 xcb_connection_t *c;
3811 xcb_screen_t *screen;
3813 xcb_window_t root_window = { 0 }; /* the returned window */
3815 /* you init the connection and screen_nbr */
3817 screen = screen_of_display (c, screen_nbr);
3819 root_window = screen->root;
3821 /* root_window contains now the root window, or a NULL window if no screen is found */
3823 <li class="subtitle"><a name="DefaultRootWindow">DefaultRootWindow</a>
3825 It is the root window of the default screen. So, you call
3826 <a name="ScreenOfDisplay">ScreenOfDisplay</a> with the
3827 default screen number and you get the
3828 <a href="#RootWindow">root window</a> as above:
3831 xcb_connection_t *c;
3832 xcb_screen_t *screen;
3833 int screen_default_nbr;
3834 xcb_window_t root_window = { 0 }; /* the returned root window */
3836 /* you pass the name of the display you want to xcb_connect_t */
3838 c = xcb_connect (display_name, &screen_default_nbr);
3839 screen = screen_of_display (c, screen_default_nbr);
3841 root_window = screen->root;
3843 /* root_window contains now the default root window, or a NULL window if no screen is found */
3845 <li class="subtitle"><a name="DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
3847 While a Visual is, in Xlib, a structure, in XCB, there are
3848 two types: <span class="code">xcb_visualid_t</span>, which is
3849 the Id of the visual, and <span class="code">xcb_visualtype_t</span>,
3850 which corresponds to the Xlib Visual. To get the Id of the
3851 visual of a screen, just get the
3852 <span class="code">root_visual</span>
3853 member of a <span class="code">xcb_screen_t</span>:
3856 xcb_connection_t *c;
3857 xcb_screen_t *screen;
3859 xcb_visualid_t root_visual = { 0 }; /* the returned visual Id */
3861 /* you init the connection and screen_nbr */
3863 screen = screen_of_display (c, screen_nbr);
3865 root_visual = screen->root_visual;
3867 /* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
3870 To get the <span class="code">xcb_visualtype_t</span>
3871 structure, it's a bit less easy. You have to get the
3872 <span class="code">xcb_screen_t</span> structure that you want,
3873 get its <span class="code">root_visual</span> member,
3874 then iterate over the <span class="code">xcb_depth_t</span>s
3875 and the <span class="code">xcb_visualtype_t</span>s, and compare
3876 the <span class="code">xcb_visualid_t</span> of these <span class="code">xcb_visualtype_t</span>s:
3877 with <span class="code">root_visual</span>:
3880 xcb_connection_t *c;
3881 xcb_screen_t *screen;
3883 xcb_visualid_t root_visual = { 0 };
3884 xcb_visualtype_t *visual_type = NULL; /* the returned visual type */
3886 /* you init the connection and screen_nbr */
3888 screen = screen_of_display (c, screen_nbr);
3890 xcb_depth_iterator_t depth_iter;
3892 depth_iter = xcb_screen_allowed_depths_iterator (screen);
3893 for (; depth_iter.rem; xcb_depth_next (&depth_iter)) {
3894 xcb_visualtype_iterator_t visual_iter;
3896 visual_iter = xcb_depth_visuals_iterator (depth_iter.data);
3897 for (; visual_iter.rem; xcb_visualtype_next (&visual_iter)) {
3898 if (screen->root_visual == visual_iter.data->visual_id) {
3899 visual_type = visual_iter.data;
3906 /* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */
3908 <li class="subtitle"><a name="DefaultGC">DefaultGC / DefaultGCOfScreen</a>
3910 This default Graphic Context is just a newly created Graphic
3911 Context, associated to the root window of a
3912 <span class="code">xcb_screen_t</span>,
3913 using the black white pixels of that screen:
3916 xcb_connection_t *c;
3917 xcb_screen_t *screen;
3919 xcb_gcontext_t gc = { 0 }; /* the returned default graphic context */
3921 /* you init the connection and screen_nbr */
3923 screen = screen_of_display (c, screen_nbr);
3925 xcb_drawable_t draw;
3929 gc = xcb_generate_id (c);
3930 draw = screen->root;
3931 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND;
3932 values[0] = screen->black_pixel;
3933 values[1] = screen->white_pixel;
3934 xcb_create_gc (c, gc, draw, mask, values);
3937 /* gc contains now the default graphic context */
3939 <li class="subtitle"><a name="BlackPixel">BlackPixel / BlackPixelOfScreen</a>
3941 It is the Id of the black pixel, which is in the structure
3942 of an <span class="code">xcb_screen_t</span>.
3945 xcb_connection_t *c;
3946 xcb_screen_t *screen;
3948 uint32_t black_pixel = 0; /* the returned black pixel */
3950 /* you init the connection and screen_nbr */
3952 screen = screen_of_display (c, screen_nbr);
3954 black_pixel = screen->black_pixel;
3956 /* black_pixel contains now the value of the black pixel, or 0 if no screen is found */
3958 <li class="subtitle"><a name="WhitePixel">WhitePixel / WhitePixelOfScreen</a>
3960 It is the Id of the white pixel, which is in the structure
3961 of an <span class="code">xcb_screen_t</span>.
3964 xcb_connection_t *c;
3965 xcb_screen_t *screen;
3967 uint32_t white_pixel = 0; /* the returned white pixel */
3969 /* you init the connection and screen_nbr */
3971 screen = screen_of_display (c, screen_nbr);
3973 white_pixel = screen->white_pixel;
3975 /* white_pixel contains now the value of the white pixel, or 0 if no screen is found */
3977 <li class="subtitle"><a name="DisplayWidth">DisplayWidth / WidthOfScreen</a>
3979 It is the width in pixels of the screen that you want, and
3980 which is in the structure of the corresponding
3981 <span class="code">xcb_screen_t</span>.
3984 xcb_connection_t *c;
3985 xcb_screen_t *screen;
3987 uint32_t width_in_pixels = 0; /* the returned width in pixels */
3989 /* you init the connection and screen_nbr */
3991 screen = screen_of_display (c, screen_nbr);
3993 width_in_pixels = screen->width_in_pixels;
3995 /* width_in_pixels contains now the width in pixels, or 0 if no screen is found */
3997 <li class="subtitle"><a name="DisplayHeight">DisplayHeight / HeightOfScreen</a>
3999 It is the height in pixels of the screen that you want, and
4000 which is in the structure of the corresponding
4001 <span class="code">xcb_screen_t</span>.
4004 xcb_connection_t *c;
4005 xcb_screen_t *screen;
4007 uint32_t height_in_pixels = 0; /* the returned height in pixels */
4009 /* you init the connection and screen_nbr */
4011 screen = screen_of_display (c, screen_nbr);
4013 height_in_pixels = screen->height_in_pixels;
4015 /* height_in_pixels contains now the height in pixels, or 0 if no screen is found */
4017 <li class="subtitle"><a name="DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
4019 It is the width in millimeters of the screen that you want, and
4020 which is in the structure of the corresponding
4021 <span class="code">xcb_screen_t</span>.
4024 xcb_connection_t *c;
4025 xcb_screen_t *screen;
4027 uint32_t width_in_millimeters = 0; /* the returned width in millimeters */
4029 /* you init the connection and screen_nbr */
4031 screen = screen_of_display (c, screen_nbr);
4033 width_in_millimeters = screen->width_in_millimeters;
4035 /* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */
4037 <li class="subtitle"><a name="DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
4039 It is the height in millimeters of the screen that you want, and
4040 which is in the structure of the corresponding
4041 <span class="code">xcb_screen_t</span>.
4044 xcb_connection_t *c;
4045 xcb_screen_t *screen;
4047 uint32_t height_in_millimeters = 0; /* the returned height in millimeters */
4049 /* you init the connection and screen_nbr */
4051 screen = screen_of_display (c, screen_nbr);
4053 height_in_millimeters = screen->height_in_millimeters;
4055 /* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */
4057 <li class="subtitle"><a name="DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
4059 It is the depth (in bits) of the root window of the
4060 screen. You get it from the <span class="code">xcb_screen_t</span> structure.
4063 xcb_connection_t *c;
4064 xcb_screen_t *screen;
4066 uint8_t root_depth = 0; /* the returned depth of the root window */
4068 /* you init the connection and screen_nbr */
4070 screen = screen_of_display (c, screen_nbr);
4072 root_depth = screen->root_depth;
4074 /* root_depth contains now the depth of the root window, or 0 if no screen is found */
4076 <li class="subtitle"><a name="DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
4078 This is the default colormap of the screen (and not the
4079 (default) colormap of the default screen !). As usual, you
4080 get it from the <span class="code">xcb_screen_t</span> structure:
4083 xcb_connection_t *c;
4084 xcb_screen_t *screen;
4086 xcb_colormap_t default_colormap = { 0 }; /* the returned default colormap */
4088 /* you init the connection and screen_nbr */
4090 screen = screen_of_display (c, screen_nbr);
4092 default_colormap = screen->default_colormap;
4094 /* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */
4096 <li class="subtitle"><a name="MinCmapsOfScreen"></a>MinCmapsOfScreen
4098 You get the minimum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4101 xcb_connection_t *c;
4102 xcb_screen_t *screen;
4104 uint16_t min_installed_maps = 0; /* the returned minimum installed colormaps */
4106 /* you init the connection and screen_nbr */
4108 screen = screen_of_display (c, screen_nbr);
4110 min_installed_maps = screen->min_installed_maps;
4112 /* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */
4114 <li class="subtitle"><a name="MaxCmapsOfScreen"></a>MaxCmapsOfScreen
4116 You get the maximum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4119 xcb_connection_t *c;
4120 xcb_screen_t *screen;
4122 uint16_t max_installed_maps = 0; /* the returned maximum installed colormaps */
4124 /* you init the connection and screen_nbr */
4126 screen = screen_of_display (c, screen_nbr);
4128 max_installed_maps = screen->max_installed_maps;
4130 /* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */
4132 <li class="subtitle"><a name="DoesSaveUnders"></a>DoesSaveUnders
4134 You know if <span class="code">save_unders</span> is set,
4135 by looking in the <span class="code">xcb_screen_t</span> structure:
4138 xcb_connection_t *c;
4139 xcb_screen_t *screen;
4141 uint8_t save_unders = 0; /* the returned value of save_unders */
4143 /* you init the connection and screen_nbr */
4145 screen = screen_of_display (c, screen_nbr);
4147 save_unders = screen->save_unders;
4149 /* save_unders contains now the value of save_unders, or FALSE if no screen is found */
4151 <li class="subtitle"><a name="DoesBackingStore"></a>DoesBackingStore
4153 You know the value of <span class="code">backing_stores</span>,
4154 by looking in the <span class="code">xcb_screen_t</span> structure:
4157 xcb_connection_t *c;
4158 xcb_screen_t *screen;
4160 uint8_t backing_stores = 0; /* the returned value of backing_stores */
4162 /* you init the connection and screen_nbr */
4164 screen = screen_of_display (c, screen_nbr);
4166 backing_stores = screen->backing_stores;
4168 /* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */
4170 <li class="subtitle"><a name="EventMaskOfScreen"></a>EventMaskOfScreen
4172 To get the current input masks,
4173 you look in the <span class="code">xcb_screen_t</span> structure:
4176 xcb_connection_t *c;
4177 xcb_screen_t *screen;
4179 uint32_t current_input_masks = 0; /* the returned value of current input masks */
4181 /* you init the connection and screen_nbr */
4183 screen = screen_of_display (c, screen_nbr);
4185 current_input_masks = screen->current_input_masks;
4187 /* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
4190 <li class="subtitle"><a name="misc">Miscellaneous macros</a>
4192 <li class="subtitle"><a name="DisplayOfScreen"></a>DisplayOfScreen
4194 in Xlib, the <span class="code">Screen</span> structure
4195 stores its associated <span class="code">Display</span>
4196 structure. This is not the case in the X Window protocol,
4197 hence, it's also not the case in XCB. So you have to store
4200 <li class="subtitle"><a name="DisplayCells"></a>DisplayCells / CellsOfScreen
4202 To get the colormap entries,
4203 you look in the <span class="code">xcb_visualtype_t</span>
4204 structure, that you grab like <a class="subsection" href="#DefaultVisual">here</a>:
4207 xcb_connection_t *c;
4208 xcb_visualtype_t *visual_type;
4209 uint16_t colormap_entries = 0; /* the returned value of the colormap entries */
4211 /* you init the connection and visual_type */
4214 colormap_entries = visual_type->colormap_entries;
4216 /* colormap_entries contains now the value of the colormap entries, or FALSE if no screen is found */