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>
62 <li><a class="subsection" href="#openingfont">Opening a Font</a>
63 <li><a class="subsection" href="#assigningfont">Assigning a Font to a Graphic Context</a>
64 <li><a class="subsection" href="#drawingtext">Drawing text in a drawable</a>
65 <li><a class="subsection" href="#fontcompleteexample">Complete example</a>
69 <li>Root, parent and child windows
70 <li>Events propagation
72 <li><a class="section" href="#wm">Interacting with the window manager</a>
74 <li><a class="subsection" href="#wmprop">Window properties</a>
75 <li><a class="subsection" href="#wmname">Setting the window name and icon name</a>
76 <li>Setting preferred window size(s)
77 <li>Setting miscellaneous window manager hints
78 <li>Setting an application's icon
79 <li>Obeying the delete-window protocol
81 <li><a class="section" href="#winop">Simple window operations</a>
83 <li><a class="subsection" href="#winmap">Mapping and unmapping a window</a>
84 <li><a class="subsection" href="#winconf">Configuring a window</a>
85 <li><a class="subsection" href="#winmove">Moving a window around the screen</a>
86 <li><a class="subsection" href="#winsize">Resizing a window</a>
87 <li><a class="subsection" href="#winstack">Changing windows stacking order: raise and lower</a>
88 <li>Iconifying and de-iconifying a window
89 <li><a class="subsection" href="#wingetinfo">Getting informations about a window</a>
91 <li><a class="section" href="#usecolor">Using colors to paint the rainbow</a>
93 <li><a class="subsection" href="#colormap">Color maps</a>
94 <li><a class="subsection" href="#colormapalloc">Allocating and freeing Color Maps</a>
95 <li><a class="subsection" href="#alloccolor">Allocating and freeing a color entry</a>
96 <li>Drawing with a color
98 <li><a class="section" href="#pixmaps">X Bitmaps and Pixmaps</a>
100 <li><a class="subsection" href="#pixmapswhat">What is a X Bitmap ? An X Pixmap ?</a>
101 <li>Loading a bitmap from a file
102 <li>Drawing a bitmap in a window
103 <li><a class="subsection" href="#pixmapscreate">Creating a pixmap</a>
104 <li><a class="subsection" href="#pixmapsdraw">Drawing a pixmap in a window</a>
105 <li><a class="subsection" href="#pixmapsfree">Freeing a pixmap</a>
107 <li><a class="subsection" href="#mousecursor">Messing with the mouse cursor</a>
109 <li><a class="subsection" href="#mousecursorcreate">Creating and destroying a mouse cursor</a>
110 <li><a class="subsection" href="#mousecursorset">Setting a window's mouse cursor</a>
111 <li><a class="subsection" href="#mousecursorexample">Complete example</a>
113 <li><a class="subsection" href="#translation">Translation of basic Xlib functions and macros</a>
115 <li><a class="subsection" href="#displaystructure">Members of the Display structure</a>
117 <li><a class="subsection" href="#ConnectionNumber">ConnectionNumber</a>
118 <li><a class="subsection" href="#DefaultScreen">DefaultScreen</a>
119 <li><a class="subsection" href="#QLength">QLength</a>
120 <li><a class="subsection" href="#ScreenCount">ScreenCount</a>
121 <li><a class="subsection" href="#ServerVendor">ServerVendor</a>
122 <li><a class="subsection" href="#ProtocolVersion">ProtocolVersion</a>
123 <li><a class="subsection" href="#ProtocolRevision">ProtocolRevision</a>
124 <li><a class="subsection" href="#VendorRelease">VendorRelease</a>
125 <li><a class="subsection" href="#DisplayString">DisplayString</a>
126 <li><a class="subsection" href="#BitmapUnit">BitmapUnit</a>
127 <li><a class="subsection" href="#BitmapBitOrder">BitmapBitOrder</a>
128 <li><a class="subsection" href="#BitmapPad">BitmapPad</a>
129 <li><a class="subsection" href="#ImageByteOrder">ImageByteOrder</a>
131 <li><a class="subsection" href="#screenofdisplay">ScreenOfDisplay related functions</a>
133 <li><a class="subsection" href="#ScreenOfDisplay">ScreenOfDisplay</a>
134 <li><a class="subsection" href="#DefaultScreenOfDisplay">DefaultScreenOfDisplay</a>
135 <li><a class="subsection" href="#RootWindow">RootWindow / RootWindowOfScreen</a>
136 <li><a class="subsection" href="#DefaultRootWindow">DefaultRootWindow</a>
137 <li><a class="subsection" href="#DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
138 <li><a class="subsection" href="#DefaultGC">DefaultGC / DefaultGCOfScreen</a>
139 <li><a class="subsection" href="#BlackPixel">BlackPixel / BlackPixelOfScreen</a>
140 <li><a class="subsection" href="#WhitePixel">WhitePixel / WhitePixelOfScreen</a>
141 <li><a class="subsection" href="#DisplayWidth">DisplayWidth / WidthOfScreen</a>
142 <li><a class="subsection" href="#DisplayHeight">DisplayHeight / HeightOfScreen</a>
143 <li><a class="subsection" href="#DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
144 <li><a class="subsection" href="#DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
145 <li><a class="subsection" href="#DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
146 <li><a class="subsection" href="#DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
147 <li><a class="subsection" href="#MinCmapsOfScreen">MinCmapsOfScreen</a>
148 <li><a class="subsection" href="#MaxCmapsOfScreen">MaxCmapsOfScreen</a>
149 <li><a class="subsection" href="#DoesSaveUnders">DoesSaveUnders</a>
150 <li><a class="subsection" href="#DoesBackingStore">DoesBackingStore</a>
151 <li><a class="subsection" href="#EventMaskOfScreen">EventMaskOfScreen</a>
153 <li><a class="subsection" href="#misc">Miscellaneaous macros</a>
155 <li><a class="subsection" href="#DisplayOfScreen">DisplayOfScreen</a>
156 <li><a class="subsection" href="#DisplayCells">DisplayCells / CellsOfScreen</a>
161 <div class="section">
163 <li class="title"><a name="intro">Introduction</a>
165 This tutorial is based on the
166 <a href="http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html">Xlib Tutorial</a>
167 written by <a href="mailto:choor at atcom dot co dot il">Guy Keren</a>. The
168 author allowed me to take some parts of his text, mainly the text which
169 deals with the X Windows generality.
172 This tutorial is intended for people who want to start to program
173 with the <a href="http://xcb.freedesktop.org">XCB</a>
174 library. keep in mind that XCB, like the
175 <a href="http://tronche.com/gui/x/xlib/introduction">Xlib</a>
176 library, isn't what post programmers wanting to write X
177 applications are looking for. They should use a much higher
178 level GUI toolkit like Motif,
179 <a href="http://www.lesstif.org">LessTiff</a>,
180 <a href="http://www.gtk.org">GTK</a>,
181 <a href="http://www.trolltech.com">QT</a> or
182 <a href="http://www.enlightenment.org">EWL</a>, or use
183 <a href="http://cairographics.org">Cairo</a>.
185 we need to start somewhere. More than this, knowing how things
186 work down below is never a bad idea.
189 After reading this tutorial, one should be able to write very
190 simple graphical programs, but not programs with decent user
191 interfaces. For such programs, one of the previously mentioned
192 libraries should be used.
195 But what is XCB? Xlib has been
196 the standard C binding for the <a href="http://www.x.org">X
197 Window System</a> protocol for many years now. It is an
198 excellent piece of work, but there are applications for which it
199 is not ideal, for example:
202 <li><b>Small platforms</b>: Xlib is a large piece of code, and
203 it's difficult to make it smaller
204 <li><b>Latency hiding</b>: Xlib requests requiring a reply are
205 effectively synchronous: they block until the reply appears,
206 whether the result is needed immediately or not.
207 <li><b>Direct access to the protocol</b>: Xlib does quite a
208 bit of caching, layering, and similar optimizations. While this
209 is normally a feature, it makes it difficult to simply emit
210 specified X protocol requests and process specific
212 <li><b>Threaded applications</b>: While Xlib does attempt to
213 support multithreading, the API makes this difficult and
215 <li><b>New extensions</b>: The Xlib infrastructure provides
216 limited support for the new creation of X extension client side
220 For these reasons, among others, XCB, an X C binding, has been
221 designed to solve the above problems and thus provide a base for
224 <li>Toolkit implementation.
225 <li>Direct protocol-level programming.
226 <li>Lightweight emulation of commonly used portions of the
230 <li class="title"><a name="Xmodel">The client and server model of the X window system</a>
232 The X Window System was developed with one major goal:
233 flexibility. The idea was that the way things look is one thing,
234 but the way things work is another matter. Thus, the lower
235 levels provide the tools required to draw windows, handle user
236 input, allow drawing graphics using colors (or black and white
237 screens), etc. To this point, a decision was made to separate
238 the system into two parts. A client that decides what to do, and
239 a server that actually draws on the screen and reads user input
240 in order to send it to the client for processing.
243 This model is the complete opposite of what is used to when
244 dealing with clients and servers. In our case, the user sits
245 near the machine controlled by the server, while the client
246 might be running on a remote machine. The server controls the
247 screens, mouse and keyboard. A client may connect to the server,
248 request that it draws a window (or several windows), and ask the
249 server to send it any input the user sends to these
250 windows. Thus, several clients may connect to a single X server
251 (one might be running mail software, one running a WWW
252 browser, etc). When input is sent by the user to some window,
253 the server sends a message to the client controlling this window
254 for processing. The client decides what to do with this input,
255 and sends the server requests for drawing in the window.
258 The whole session is carried out using the X message
259 protocol. This protocol was originally carried over the TCP/IP
260 protocol suite, allowing the client to run on any machine
261 connected to the same network that the server is. Later on, the
262 X servers were extended to allow clients running on the local
263 machine with more optimized access to the server (note that an X
264 protocol message may be several hundreds of KB in size), such as
265 using shared memory, or using Unix domain sockets (a method for
266 creating a logical channel on a Unix system between two processes).
268 <li class="title"><a name="asynch">GUI programming: the asynchronous model</a>
270 Unlike conventional computer programs, that carry some serial
271 nature, a GUI program usually uses an asynchronous programming
272 model, also known as "event-driven programming". This means that
273 that program mostly sits idle, waiting for events sent by the X
274 server, and then acts upon these events. An event may say "The
275 user pressed the 1st button mouse in spot (x,y)", or "The window
276 you control needs to be redrawn". In order for the program to be
277 responsive to the user input, as well as to refresh requests, it
278 needs to handle each event in a rather short period of time
279 (e.g. less that 200 milliseconds, as a rule of thumb).
282 This also implies that the program may not perform operations
283 that might take a long time while handling an event (such as
284 opening a network connection to some remote server, or
285 connecting to a database server, or even performing a long file
286 copy operation). Instead, it needs to perform all these
287 operations in an asynchronous manner. This may be done by using
288 various asynchronous models to perform the longish operations,
289 or by performing them in a different process or thread.
292 So the way a GUI program looks is something like that:
295 <li>Perform initialization routines.
296 <li>Connect to the X server.
297 <li>Perform X-related initialization.
298 <li>While not finished:
300 <li>Receive the next event from the X server.
301 <li>Handle the event, possibly sending various drawing
302 requests to the X server.
303 <li>If the event was a quit message, exit the loop.
305 <li>Close down the connection to the X server.
306 <li>Perform cleanup operations.
309 <li class="title"><a name="notions">Basic XCB notions</a>
311 XCB has been created to eliminate the need for
312 programs to actually implement the X protocol layer. This
313 library gives a program a very low-level access to any X
314 server. Since the protocol is standardized, a client using any
315 implementation of XCB may talk with any X server (the same
316 occurs for Xlib, of course). We now give a brief description of
317 the basic XCB notions. They will be detailed later.
320 <li class="subtitle"><a name="conn">The X Connection</a>
322 The major notion of using XCB is the X Connection. This is a
323 structure representing the connection we have open with a
324 given X server. It hides a queue of messages coming from the
325 server, and a queue of pending requests that our client
326 intends to send to the server. In XCB, this structure is named
327 'xcb_connection_t'. It is analogous to the Xlib Display.
328 When we open a connection to an X server, the
329 library returns a pointer to such a structure. Later, we
330 supply this pointer to any XCB function that should send
331 messages to the X server or receive messages from this server.
333 <li class="subtitle"><a name="requestsreplies">Requests and
334 replies: the Xlib killers</a>
336 To ask for information from the X server, we have to make a request
337 and ask for a reply. With Xlib, these two tasks are
338 automatically done: Xlib locks the system, sends a request,
339 waits for a reply from the X server and unlocks. This is
340 annoying, especially if one makes a lot of requests to the X
341 server. Indeed, Xlib has to wait for the end of a reply
342 before asking for the next request (because of the locks that
343 Xlib sends). For example, here is a time-line of N=4
344 requests/replies with Xlib, with a round-trip latency
345 <b>T_round_trip</b> that is 5 times long as the time required
346 to write or read a request/reply (<b>T_write/T_read</b>):
349 W-----RW-----RW-----RW-----R
352 <li>W: Writing request
353 <li>-: Stalled, waiting for data
357 The total time is N * (T_write + T_round_trip + T_read).
360 With XCB, we can suppress most of the round-trips as the
361 requests and the replies are not locked. We usually send a
362 request, then XCB returns to us a <b>cookie</b>, which is an
363 identifier. Then, later, we ask for a reply using this
364 <b>cookie</b> and XCB returns a
365 pointer to that reply. Hence, with XCB, we can send a lot of
366 requests, and later in the program, ask for all the replies
367 when we need them. Here is the time-line for 4
368 requests/replies when we use this property of XCB:
374 The total time is N * T_write + max (0, T_round_trip - (N-1) *
375 T_write) + N * T_read. Which can be considerably faster than
376 all those Xlib round-trips.
379 Here is a program that computes the time to create 500 atoms
380 with Xlib and XCB. It shows the Xlib way, the bad XCB way
381 (which is similar to Xlib) and the good XCB way. On my
382 computer, XCB is 25 times faster than Xlib.
385 #include <stdlib.h>
386 #include <stdio.h>
387 #include <string.h>
388 #include <sys/time.h>
390 #include <xcb/xcb.h>
392 #include <X11/Xlib.h>
397 struct timeval timev;
399 gettimeofday(&timev, NULL);
401 return (double)timev.tv_sec + (((double)timev.tv_usec) / 1000000);
409 xcb_intern_atom_cookie_t *cs;
422 c = xcb_connect (NULL, NULL);
425 atoms = (xcb_atom_t *)malloc (count * sizeof (atoms));
426 names = (char **)malloc (count * sizeof (char *));
429 for (i = 0; i < count; ++i) {
432 sprintf (buf, "NAME%d", i);
433 names[i] = strdup (buf);
439 for (i = 0; i < count; ++i)
440 atoms[i] = xcb_intern_atom_reply (c,
449 printf ("bad use time : %f\n", diff);
454 cs = (xcb_intern_atom_cookie_t *) malloc (count * sizeof(xcb_intern_atom_cookie_t));
455 for(i = 0; i < count; ++i)
456 cs[i] = xcb_intern_atom (c, 0, strlen(names[i]), names[i]);
458 for(i = 0; i < count; ++i) {
459 xcb_intern_atom_reply_t *r;
461 r = xcb_intern_atom_reply(c, cs[i], 0);
468 printf ("good use time : %f\n", end - start);
469 printf ("ratio : %f\n", diff / (end - start));
473 for (i = 0; i < count; ++i)
481 disp = XOpenDisplay (getenv("DISPLAY"));
483 atoms_x = (Atom *)malloc (count * sizeof (atoms_x));
487 for (i = 0; i < count; ++i)
488 atoms_x[i] = XInternAtom(disp, names[i], 0);
491 diff_x = end - start;
492 printf ("Xlib use time : %f\n", diff_x);
493 printf ("ratio : %f\n", diff_x / diff);
498 XCloseDisplay (disp);
503 <li class="subtitle"><a name="gc">The Graphic Context</a>
505 When we perform various drawing operations (graphics, text,
506 etc), we may specify various options for controlling how the
507 data will be drawn (what foreground and background colors to
508 use, how line edges will be connected, what font to use when
509 drawing some text, etc). In order to avoid the need to supply
510 hundreds of parameters to each drawing function, a graphical
511 context structure is used. We set the various drawing options
512 in this structure, and then we pass a pointer to this
513 structure to any drawing routines. This is rather handy, as we
514 often need to perform several drawing requests with the same
515 options. Thus, we would initialize a graphical context, set
516 the desired options, and pass this structure to all drawing
520 Note that graphic contexts have no client-side structure in
521 XCB, they're just XIDs. Xlib has a client-side structure
522 because it caches the GC contents so it can avoid making
523 redundant requests, but of course XCB doesn't do that.
525 <li class="subtitle"><a name="events">Events</a>
527 A structure is used to pass events received from the X
528 server. XCB supports exactly the events specified in the
529 protocol (33 events). This structure contains the type
530 of event received (including a bit for whether it came
531 from the server or another client), as well as the data associated with the
532 event (e.g. position on the screen where the event was
533 generated, mouse button associated with the event, region of
534 the screen associated with a "redraw" event, etc). The way to
535 read the event's data depends on the event type.
539 <li class="title"><a name="use">Using XCB-based programs</a>
542 <li class="subtitle"><a name="inst">Installation of XCB</a>
544 <b>TODO:</b> These instructions are out of date.
545 Just reference the <a href="http://xcb.freedesktop.org/">main XCB page</a>
546 so we don't have to maintain these instructions in more than
550 To build XCB from source, you need to have installed at
555 <li><a href="http://www.gnu.org/software/automake/">automake 1.7</a>
556 <li><a href="http://www.gnu.org/software/autoconf/">autoconf 2.50</a>
557 <li><a href="http://www.check.org">check</a>
558 <li><a href="http://xmlsoft.org/XSLT/">xsltproc</a>
559 <li><a href="http://www.gnu.org/software/gperf/">gperf 3.0.1</a>
562 You have to checkout in the git repository the following modules:
570 Note that xcb-proto exists only to install header
571 files, so typing 'make' or 'make all' will produce the message
572 "Nothing to be done for 'all'". That's normal.
574 <li class="subtitle"><a name="comp">Compiling XCB-based programs</a>
576 Compiling XCB-based programs requires linking them with the XCB
577 library. This is easily done thanks to pkgconfig:
580 gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb`
583 <li class="title"><a name="openconn">Opening and closing the connection to an X server</a>
585 An X program first needs to open the connection to the X
586 server. There is a function that opens a connection. It requires
587 the display name, or NULL. In the latter case, the display name
588 will be the one in the environment variable DISPLAY.
591 <span class="type">xcb_connection_t</span> *xcb_connect (<span class="keyword">const</span> <span class="type">char</span> *displayname,
592 <span class="type">int</span> *screenp);
595 The second parameter returns the screen number used for the
596 connection. The returned structure describes an XCB connection
597 and is opaque. Here is how the connection can be opened:
600 #<span class="include">include</span> <span class="string"><xcb/xcb.h></span>
602 <span class="type">int</span>
603 <span class="function">main</span> ()
605 <span class="type">xcb_connection_t</span> *c;
607 /* Open the connection to the X server. Use the DISPLAY environment variable as the default display name */
608 c = xcb_connect (NULL, NULL);
610 <span class="keyword">return</span> 0;
614 To close a connection, it suffices to use:
617 <span class="type">void</span> xcb_disconnect (<span class="type">xcb_connection_t</span> *c);
640 <li>xcb_disconnect ()
645 <li class="title"><a name="screen">Checking basic information about a connection</a>
647 Once we have opened a connection to an X server, we should check some
648 basic information about it: what screens it has, what is the
649 size (width and height) of the screen, how many colors it
650 supports (black and white ? grey scale ?, 256 colors ? more ?),
651 and so on. We get such information from the xcb_screen_t
657 xcb_colormap_t default_colormap;
658 uint32_t white_pixel;
659 uint32_t black_pixel;
660 uint32_t current_input_masks;
661 uint16_t width_in_pixels;
662 uint16_t height_in_pixels;
663 uint16_t width_in_millimeters;
664 uint16_t height_in_millimeters;
665 uint16_t min_installed_maps;
666 uint16_t max_installed_maps;
667 xcb_visualid_t root_visual;
668 uint8_t backing_stores;
671 uint8_t allowed_depths_len;
675 We could retrieve the first screen of the connection by using the
679 xcb_screen_iterator_t xcb_setup_roots_iterator (xcb_setup_t *R);
682 Here is a small program that shows how to use this function:
685 #include <stdio.h>
687 #include <xcb/xcb.h>
693 xcb_screen_t *screen;
695 xcb_screen_iterator_t iter;
697 /* Open the connection to the X server. Use the DISPLAY environment variable */
698 c = xcb_connect (NULL, &screen_nbr);
700 /* Get the screen #screen_nbr */
701 iter = xcb_setup_roots_iterator (xcb_get_setup (c));
702 for (; iter.rem; --screen_nbr, xcb_screen_next (&iter))
703 if (screen_nbr == 0) {
709 printf ("Informations of screen %ld:\n", screen->root);
710 printf (" width.........: %d\n", screen->width_in_pixels);
711 printf (" height........: %d\n", screen->height_in_pixels);
712 printf (" white pixel...: %ld\n", screen->white_pixel);
713 printf (" black pixel...: %ld\n", screen->black_pixel);
719 <li class="title"><a name="helloworld">Creating a basic window - the "hello world" program</a>
721 After we got some basic information about our screen, we can
722 create our first window. In the X Window System, a window is
723 characterized by an Id. So, in XCB, a window is of type:
726 typedef uint32_t xcb_window_t;
729 We first ask for a new Id for our window, with this function:
732 xcb_window_t xcb_generate_id(xcb_connection_t *c);
735 Then, XCB supplies the following function to create new windows:
738 xcb_void_cookie_t xcb_create_window (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
739 uint8_t depth, /* Depth of the screen */
740 xcb_window_t wid, /* Id of the window */
741 xcb_window_t parent, /* Id of an existing window that should be the parent of the new window */
742 int16_t x, /* X position of the top-left corner of the window (in pixels) */
743 int16_t y, /* Y position of the top-left corner of the window (in pixels) */
744 uint16_t width, /* Width of the window (in pixels) */
745 uint16_t height, /* Height of the window (in pixels) */
746 uint16_t border_width, /* Width of the window's border (in pixels) */
748 xcb_visualid_t visual,
750 const uint32_t *value_list);
753 The fact that we created the window does not mean that it will
754 be drawn on screen. By default, newly created windows are not
755 mapped on the screen (they are invisible). In order to make our
756 window visible, we use the function <span class="code">xcb_map_window()</span>, whose
760 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
761 xcb_window_t window);
764 Finally, here is a small program to create a window of size
765 150x150 pixels, positioned at the top-left corner of the screen:
768 #include <unistd.h> /* pause() */
770 #include <xcb/xcb.h>
776 xcb_screen_t *screen;
779 /* Open the connection to the X server */
780 c = xcb_connect (NULL, NULL);
782 /* Get the first screen */
783 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
785 /* Ask for our window's Id */
786 win = xcb_generate_id(c);
788 /* Create the window */
789 xcb_create_window (c, /* Connection */
790 XCB_COPY_FROM_PARENT, /* depth (same as root)*/
792 screen->root, /* parent window */
794 150, 150, /* width, height */
795 10, /* border_width */
796 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
797 screen->root_visual, /* visual */
798 0, NULL); /* masks, not used yet */
800 /* Map the window on the screen */
801 xcb_map_window (c, win);
803 /* Make sure commands are sent before we pause, so window is shown */
806 pause (); /* hold client until Ctrl-C */
812 In this code, you see one more function - <span class="code">xcb_flush()</span>, not explained
813 yet. It is used to flush all the pending requests. More
814 precisely, there are 2 functions that do such things. The first
815 one is <span class="code">xcb_flush()</span>:
818 int xcb_flush (xcb_connection_t *c);
821 This function flushes all pending requests to the X server (much
822 like the <span class="code">fflush()</span> function is used to
823 flush standard output). The second function is
824 <span class="code">xcb_aux_sync()</span>:
827 int xcb_aux_sync (xcb_connection_t *c);
830 This functions also flushes all pending requests to the X
831 server, and then waits until the X server finishing processing
832 these requests. In a normal program, this will not be necessary
833 (we'll see why when we get to write a normal X program), but for
834 now, we put it there.
837 The window that is created by the above code has a non defined
838 background. This one can be set to a specific color,
839 thanks to the two last parameters of
840 <span class="code">xcb_create_window()</span>, which are not
841 described yet. See the subsections
842 <a href="#winconf">Configuring a window</a> or
843 <a href="#winconf">Registering for event types using event masks</a>
844 for examples on how to use these parameters. In addition, as no
845 events are handled, you have to make a Ctrl-C to interrupt the
849 <b>TODO</b>: one should tell what these functions return and
850 about the generic error
863 <li>xcb_generate_id ()
864 <li>xcb_create_window ()
869 <li class="title"><a name="drawing">Drawing in a window</a>
871 Drawing in a window can be done using various graphical
872 functions (drawing pixels, lines, rectangles, etc). In order to
873 draw in a window, we first need to define various general
874 drawing parameters (what line width to use, which color to draw
875 with, etc). This is done using a graphical context.
878 <li class="subtitle"><a name="allocgc">Allocating a Graphics Context</a>
880 As we said, a graphical context defines several attributes to
881 be used with the various drawing functions. For this, we
882 define a graphical context. We can use more than one graphical
883 context with a single window, in order to draw in multiple
884 styles (different colors, different line widths, etc). In XCB,
885 a Graphics Context is, as a window, characterized by an Id:
888 typedef uint32_t xcb_gcontext_t;
891 We first ask the X server to attribute an Id to our graphic
892 context with this function:
895 xcb_gcontext_t xcb_generate_id (xcb_connection_t *c);
898 Then, we set the attributes of the graphic context with this function:
901 xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c,
903 xcb_drawable_t drawable,
905 const uint32_t *value_list);
908 We give now an example on how to allocate a graphic context
909 that specifies that each drawing function that uses it will
910 draw in foreground with a black color.
913 #include <xcb/xcb.h>
919 xcb_screen_t *screen;
921 xcb_gcontext_t black;
925 /* Open the connection to the X server and get the first screen */
926 c = xcb_connect (NULL, NULL);
927 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
929 /* Create a black graphic context for drawing in the foreground */
930 win = screen->root;
931 black = xcb_generate_id (c);
932 mask = XCB_GC_FOREGROUND;
933 value[0] = screen->black_pixel;
934 xcb_create_gc (c, black, win, mask, value);
940 Note should be taken regarding the role of "value_mask" and
941 "value_list" in the prototype of <span class="code">xcb_create_gc()</span>. Since a
942 graphic context has many attributes, and since we often just
943 want to define a few of them, we need to be able to tell the
944 <span class="code">xcb_create_gc()</span> which attributes we
945 want to set. This is what the "value_mask" parameter is
946 for. We then use the "value_list" parameter to specify actual
947 values for the attribute we defined in "value_mask". Thus, for
948 each constant used in "value_list", we will use the matching
949 constant in "value_mask". In this case, we define a graphic
950 context with one attribute: when drawing (a point, a line,
951 etc), the foreground color will be black. The rest of the
952 attributes of this graphic context will be set to their
956 See the next Subsection for more details.
969 <li>xcb_generate_id ()
975 <li class="subtitle"><a name="changegc">Changing the attributes of a Graphics Context</a>
977 Once we have allocated a Graphic Context, we may need to
978 change its attributes (for example, changing the foreground
979 color we use to draw a line, or changing the attributes of the
980 font we use to display strings. See Subsections Drawing with a
982 <a href="#assigningfont">Assigning a Font to a Graphic Context</a>).
983 This is done by using this function:
986 xcb_void_cookie_t xcb_change_gc (xcb_connection_t *c, /* The XCB Connection */
987 xcb_gcontext_t gc, /* The Graphic Context */
988 uint32_t value_mask, /* Components of the Graphic Context that have to be set */
989 const uint32_t *value_list); /* Value as specified by value_mask */
992 The <span class="code">value_mask</span> parameter could take
993 any combination of these masks from the xcb_gc_t enumeration:
997 <li>XCB_GC_PLANE_MASK
998 <li>XCB_GC_FOREGROUND
999 <li>XCB_GC_BACKGROUND
1000 <li>XCB_GC_LINE_WIDTH
1001 <li>XCB_GC_LINE_STYLE
1002 <li>XCB_GC_CAP_STYLE
1003 <li>XCB_GC_JOIN_STYLE
1004 <li>XCB_GC_FILL_STYLE
1005 <li>XCB_GC_FILL_RULE
1008 <li>XCB_GC_TILE_STIPPLE_ORIGIN_X
1009 <li>XCB_GC_TILE_STIPPLE_ORIGIN_Y
1011 <li>XCB_GC_SUBWINDOW_MODE
1012 <li>XCB_GC_GRAPHICS_EXPOSURES
1013 <li>XCB_GC_CLIP_ORIGIN_X
1014 <li>XCB_GC_CLIP_ORIGIN_Y
1015 <li>XCB_GC_CLIP_MASK
1016 <li>XCB_GC_DASH_OFFSET
1017 <li>XCB_GC_DASH_LIST
1021 It is possible to set several attributes at the same
1022 time (for example setting the attributes of a font and the
1023 color which will be used to display a string), by OR'ing these
1024 values in <span class="code">value_mask</span>. Then
1025 <span class="code">value_list</span> has to be an array which
1026 lists the value for the respective attributes. <b>These values
1027 must be in the same order as masks listed above.</b> See Subsection
1028 Drawing with a color to have an example.
1031 <b>TODO</b>: set the links of the 3 subsections, once they will
1035 <b>TODO</b>: give an example which sets several attributes.
1037 <li class="subtitle"><a name="drawingprim">Drawing primitives: point, line, box, circle,...</a>
1039 After we have created a Graphic Context, we can draw on a
1040 window using this Graphic Context, with a set of XCB
1041 functions, collectively called "drawing primitives". Let see
1045 To draw a point, or several points, we use
1048 xcb_void_cookie_t xcb_poly_point (xcb_connection_t *c, /* The connection to the X server */
1049 uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1050 xcb_drawable_t drawable, /* The drawable on which we want to draw the point(s) */
1051 xcb_gcontext_t gc, /* The Graphic Context we use to draw the point(s) */
1052 uint32_t points_len, /* The number of points */
1053 const xcb_point_t *points); /* An array of points */
1056 The <span class="code">coordinate_mode</span> parameter
1057 specifies the coordinate mode. Available values are
1060 <li><span class="code">XCB_COORD_MODE_ORIGIN</span>
1061 <li><span class="code">XCB_COORD_MODE_PREVIOUS</span>
1064 If XCB_COORD_MODE_PREVIOUS is used, then all points but the first one
1065 are relative to the immediately previous point.
1068 The <span class="code">xcb_point_t</span> type is just a
1069 structure with two fields (the coordinates of the point):
1078 You could see an example in xpoints.c. <b>TODO</b> Set the link.
1081 To draw a line, or a polygonal line, we use
1084 xcb_void_cookie_t xcb_poly_line (xcb_connection_t *c, /* The connection to the X server */
1085 uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */
1086 xcb_drawable_t drawable, /* The drawable on which we want to draw the line(s) */
1087 xcb_gcontext_t gc, /* The Graphic Context we use to draw the line(s) */
1088 uint32_t points_len, /* The number of points in the polygonal line */
1089 const xcb_point_t *points); /* An array of points */
1092 This function will draw the line between the first and the
1093 second points, then the line between the second and the third
1097 To draw a segment, or several segments, we use
1100 xcb_void_cookie_t xcb_poly_segment (xcb_connection_t *c, /* The connection to the X server */
1101 xcb_drawable_t drawable, /* The drawable on which we want to draw the segment(s) */
1102 xcb_gcontext_t gc, /* The Graphic Context we use to draw the segment(s) */
1103 uint32_t segments_len, /* The number of segments */
1104 const xcb_segment_t *segments); /* An array of segments */
1107 The <span class="code">xcb_segment_t</span> type is just a
1108 structure with four fields (the coordinates of the two points
1109 that define the segment):
1120 To draw a rectangle, or several rectangles, we use
1123 xcb_void_cookie_t xcb_poly_rectangle (xcb_connection_t *c, /* The connection to the X server */
1124 xcb_drawable_t drawable, /* The drawable on which we want to draw the rectangle(s) */
1125 xcb_gcontext_t gc, /* The Graphic Context we use to draw the rectangle(s) */
1126 uint32_t rectangles_len, /* The number of rectangles */
1127 const xcb_rectangle_t *rectangles); /* An array of rectangles */
1130 The <span class="code">xcb_rectangle_t</span> type is just a
1131 structure with four fields (the coordinates of the top-left
1132 corner of the rectangle, and its width and height):
1142 <!-- There's no coordinate_mode. Is it normal? -->
1143 <!-- [iano] Yes, it's not in the protocol. -->
1145 To draw an elliptical arc, or several elliptical arcs, we use
1148 xcb_void_cookie_t xcb_poly_arc (xcb_connection_t *c, /* The connection to the X server */
1149 xcb_drawable_t drawable, /* The drawable on which we want to draw the arc(s) */
1150 xcb_gcontext_t gc, /* The Graphic Context we use to draw the arc(s) */
1151 uint32_t arcs_len, /* The number of arcs */
1152 const xcb_arc_t *arcs); /* An array of arcs */
1155 The <span class="code">xcb_arc_t</span> type is a structure with
1160 int16_t x; /* Top left x coordinate of the rectangle surrounding the ellipse */
1161 int16_t y; /* Top left y coordinate of the rectangle surrounding the ellipse */
1162 uint16_t width; /* Width of the rectangle surrounding the ellipse */
1163 uint16_t height; /* Height of the rectangle surrounding the ellipse */
1164 int16_t angle1; /* Angle at which the arc begins */
1165 int16_t angle2; /* Angle at which the arc ends */
1170 Note: the angles are expressed in units of 1/64 of a degree,
1171 so to have an angle of 90 degrees, starting at 0,
1172 <span class="code">angle1 = 0</span> and
1173 <span class="code">angle2 = 90 << 6</span>. Positive angles
1174 indicate counterclockwise motion, while negative angles
1175 indicate clockwise motion.
1178 <!-- I think that (x,y) should be the center of the
1179 ellipse, and (width, height) the radius. It's more logical. -->
1180 <!-- iano: Yes, and I bet some toolkits do that.
1181 But the protocol (and many other graphics APIs) define arcs
1182 by bounding rectangles. -->
1184 The corresponding function which fill inside the geometrical
1185 object are listed below, without further explanation, as they
1186 are used as the above functions.
1189 To Fill a polygon defined by the points given as arguments ,
1193 xcb_void_cookie_t xcb_fill_poly (xcb_connection_t *c,
1194 xcb_drawable_t drawable,
1197 uint8_t coordinate_mode,
1198 uint32_t points_len,
1199 const xcb_point_t *points);
1202 The <span class="code">shape</span> parameter specifies a
1203 shape that helps the server to improve performance. Available
1207 <li><span class="code">XCB_POLY_SHAPE_COMPLEX</span>
1208 <li><span class="code">XCB_POLY_SHAPE_NONCONVEX</span>
1209 <li><span class="code">XCB_POLY_SHAPE_CONVEX</span>
1212 To fill one or several rectangles, we use
1215 xcb_void_cookie_t xcb_poly_fill_rectangle (xcb_connection_t *c,
1216 xcb_drawable_t drawable,
1218 uint32_t rectangles_len,
1219 const xcb_rectangle_t *rectangles);
1222 To fill one or several arcs, we use
1225 xcb_void_cookie_t xcb_poly_fill_arc (xcb_connection_t *c,
1226 xcb_drawable_t drawable,
1229 const xcb_arc_t *arcs);
1232 <a name="points.c"></a>
1234 To illustrate these functions, here is an example that draws
1235 four points, a polygonal line, two segments, two rectangles
1236 and two arcs. Remark that we use events for the first time, as
1237 an introduction to the next section.
1240 <b>TODO:</b> Use screen->root_depth for depth parameter.
1243 #include <stdlib.h>
1244 #include <stdio.h>
1246 #include <xcb/xcb.h>
1251 xcb_connection_t *c;
1252 xcb_screen_t *screen;
1254 xcb_gcontext_t foreground;
1255 xcb_generic_event_t *e;
1259 /* geometric objects */
1260 xcb_point_t points[] = {
1266 xcb_point_t polyline[] = {
1268 { 5, 20}, /* rest of points are relative */
1272 xcb_segment_t segments[] = {
1274 {110, 25, 130, 60}};
1276 xcb_rectangle_t rectangles[] = {
1280 xcb_arc_t arcs[] = {
1281 {10, 100, 60, 40, 0, 90 << 6},
1282 {90, 100, 55, 40, 0, 270 << 6}};
1284 /* Open the connection to the X server */
1285 c = xcb_connect (NULL, NULL);
1287 /* Get the first screen */
1288 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1290 /* Create black (foreground) graphic context */
1291 win = screen->root;
1293 foreground = xcb_generate_id (c);
1294 mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
1295 values[0] = screen->black_pixel;
1297 xcb_create_gc (c, foreground, win, mask, values);
1299 /* Ask for our window's Id */
1300 win = xcb_generate_id(c);
1302 /* Create the window */
1303 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1304 values[0] = screen->white_pixel;
1305 values[1] = XCB_EVENT_MASK_EXPOSURE;
1306 xcb_create_window (c, /* Connection */
1307 XCB_COPY_FROM_PARENT, /* depth */
1308 win, /* window Id */
1309 screen->root, /* parent window */
1311 150, 150, /* width, height */
1312 10, /* border_width */
1313 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
1314 screen->root_visual, /* visual */
1315 mask, values); /* masks */
1317 /* Map the window on the screen */
1318 xcb_map_window (c, win);
1321 /* We flush the request */
1324 while ((e = xcb_wait_for_event (c))) {
1325 switch (e->response_type & ~0x80) {
1327 /* We draw the points */
1328 xcb_poly_point (c, XCB_COORD_MODE_ORIGIN, win, foreground, 4, points);
1330 /* We draw the polygonal line */
1331 xcb_poly_line (c, XCB_COORD_MODE_PREVIOUS, win, foreground, 4, polyline);
1333 /* We draw the segements */
1334 xcb_poly_segment (c, win, foreground, 2, segments);
1336 /* We draw the rectangles */
1337 xcb_poly_rectangle (c, win, foreground, 2, rectangles);
1339 /* We draw the arcs */
1340 xcb_poly_arc (c, win, foreground, 2, arcs);
1342 /* We flush the request */
1348 /* Unknown event type, ignore it */
1352 /* Free the Generic Event */
1360 <li class="title"><a name="xevents">X Events</a>
1362 In an X program, everything is driven by events. Event painting
1363 on the screen is sometimes done as a response to an event (an
1364 <span class="code">Expose</span> event). If part of a program's
1365 window that was hidden, gets exposed (e.g. the window was raised
1366 above other widows), the X server will send an "expose" event to
1367 let the program know it should repaint that part of the
1368 window. User input (key presses, mouse movement, etc) is also
1369 received as a set of events.
1372 <li class="subtitle"><a name="register">Registering for event types using event masks</a>
1374 During the creation of a window, you should give it what kind
1375 of events it wishes to receive. Thus, you may register for
1376 various mouse (also called pointer) events, keyboard events,
1377 expose events, and so on. This is done for optimizing the
1378 server-to-client connection (i.e. why send a program (that
1379 might even be running at the other side of the globe) an event
1380 it is not interested in ?)
1383 In XCB, you use the "value_mask" and "value_list" data in the
1384 <span class="code">xcb_create_window()</span> function to
1385 register for events. Here is how we register for
1386 <span class="code">Expose</span> event when creating a window:
1389 mask = XCB_CW_EVENT_MASK;
1390 valwin[0] = XCB_EVENT_MASK_EXPOSURE;
1391 win = xcb_generate_id (c);
1392 xcb_create_window (c, depth, win, root->root,
1394 XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual,
1398 <span class="code">XCB_EVENT_MASK_EXPOSURE</span> is a constant defined
1399 in the xcb_event_mask_t enumeration in the "xproto.h" header file. If we wanted to register for several
1400 event types, we can logically "or" them, as follows:
1403 mask = XCB_CW_EVENT_MASK;
1404 valwin[0] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS;
1405 win = xcb_generate_id (c);
1406 xcb_create_window (c, depth, win, root->root,
1408 XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual,
1412 This registers for <span class="code">Expose</span> events as
1413 well as for mouse button presses inside the created
1414 window. You should note that a mask may represent several
1418 The values that a mask could take are given
1419 by the <span class="code">xcb_cw_t</span> enumeration:
1423 XCB_CW_BACK_PIXMAP = 1L<<0,
1424 XCB_CW_BACK_PIXEL = 1L<<1,
1425 XCB_CW_BORDER_PIXMAP = 1L<<2,
1426 XCB_CW_BORDER_PIXEL = 1L<<3,
1427 XCB_CW_BIT_GRAVITY = 1L<<4,
1428 XCB_CW_WIN_GRAVITY = 1L<<5,
1429 XCB_CW_BACKING_STORE = 1L<<6,
1430 XCB_CW_BACKING_PLANES = 1L<<7,
1431 XCB_CW_BACKING_PIXEL = 1L<<8,
1432 XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
1433 XCB_CW_SAVE_UNDER = 1L<<10,
1434 XCB_CW_EVENT_MASK = 1L<<11,
1435 XCB_CW_DONT_PROPAGATE = 1L<<12,
1436 XCB_CW_COLORMAP = 1L<<13,
1437 XCB_CW_CURSOR = 1L<<14
1441 <p>Note: we must be careful when setting the values of the valwin
1442 parameter, as they have to follow the order the
1443 <span class="code">xcb_cw_t</span> enumeration. Here is an
1448 mask = XCB_CW_EVENT_MASK | XCB_CW_BACK_PIXMAP;
1449 valwin[0] = XCB_NONE; /* for XCB_CW_BACK_PIXMAP (whose value is 1) */
1450 valwin[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; /* for XCB_CW_EVENT_MASK, whose value (2048) */
1451 /* is greater than the one of XCB_CW_BACK_PIXMAP */
1454 If the window has already been created, we can use the
1455 <span class="code">xcb_configure_window()</span> function to set
1456 the events that the window will receive. The subsection
1457 <a href="#winconf">Configuring a window</a> shows its
1458 prototype. As an example, here is a piece of code that
1459 configures the window to receive the
1460 <span class="code">Expose</span> and
1461 <span class="code">ButtonPress</span> events:
1464 const static uint32_t values[] = { XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS };
1466 /* The connection c and the window win are supposed to be defined */
1468 xcb_configure_window (c, win, XCB_CW_EVENT_MASK, values);
1472 Note: A common bug programmers do is adding code to handle new
1473 event types in their program, while forgetting to add the
1474 masks for these events in the creation of the window. Such a
1475 programmer then should sit down for hours debugging his
1476 program, wondering "Why doesn't my program notice that I
1477 released the button?", only to find that they registered for
1478 button press events but not for button release events.
1481 <li class="subtitle"><a name="loop">Receiving events: writing the events loop</a>
1483 After we have registered for the event types we are interested
1484 in, we need to enter a loop of receiving events and handling
1485 them. There are two ways to receive events: a blocking way and
1490 <span class="code">xcb_wait_for_event (xcb_connection_t *c)</span>
1491 is the blocking way. It waits (so blocks...) until an event is
1492 queued in the X server. Then it retrieves it into a newly
1493 allocated structure (it dequeues it from the queue) and returns
1494 it. This structure has to be freed. The function returns
1495 <span class="code">NULL</span> if an error occurs.
1499 <span class="code">xcb_poll_for_event (xcb_connection_t *c, int
1500 *error)</span> is the non-blocking way. It looks at the event
1501 queue and returns (and dequeues too) an existing event into
1502 a newly allocated structure. This structure has to be
1503 freed. It returns <span class="code">NULL</span> if there is
1504 no event. If an error occurs, the parameter <span
1505 class="code">error</span> will be filled with the error
1509 There are various ways to write such a loop. We present two
1510 ways to write such a loop, with the two functions above. The
1511 first one uses <span class="code">xcb_wait_for_event_t</span>, which
1512 is similar to an event Xlib loop using only <span
1513 class="code">XNextEvent</span>:
1516 xcb_generic_event_t *e;
1518 while ((e = xcb_wait_for_event (c))) {
1519 switch (e->response_type & ~0x80) {
1521 /* Handle the Expose event type */
1522 xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1528 case XCB_BUTTON_PRESS: {
1529 /* Handle the ButtonPress event type */
1530 xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1537 /* Unknown event type, ignore it */
1541 /* Free the Generic Event */
1546 You will certainly want to use <span
1547 class="code">xcb_poll_for_event(xcb_connection_t *c, int
1548 *error)</span> if, in Xlib, you use <span
1549 class="code">XPending</span> or
1550 <span class="code">XCheckMaskEvent</span>:
1553 while (XPending (display)) {
1556 XNextEvent(d, &ev);
1558 /* Manage your event */
1562 Such a loop in XCB looks like:
1565 xcb_generic_event_t *ev;
1567 while ((ev = xcb_poll_for_event (conn, 0))) {
1568 /* Manage your event */
1572 The events are managed in the same way as with <span
1573 class="code">xcb_wait_for_event_t</span>.
1574 Obviously, we will need to give the user some way of
1575 terminating the program. This is usually done by handling a
1576 special "quit" event, as we will soon see.
1589 <li>xcb_wait_for_event ()
1595 <li>XCheckMaskEvent ()
1600 <li>xcb_poll_for_event ()
1605 <li class="subtitle"><a name="expose">Expose events</a>
1607 The <span class="code">Expose</span> event is one of the most
1608 basic (and most used) events an application may receive. It
1609 will be sent to us in one of several cases:
1612 <li>A window that covered part of our window has moved
1613 away, exposing part (or all) of our window.
1614 <li>Our window was raised above other windows.
1615 <li>Our window mapped for the first time.
1616 <li>Our window was de-iconified.
1619 You should note the implicit assumption hidden here: the
1620 contents of our window is lost when it is being obscured
1621 (covered) by either windows. One may wonder why the X server
1622 does not save this contents. The answer is: to save
1623 memory. After all, the number of windows on a display at a
1624 given time may be very large, and storing the contents of all
1625 of them might require a lot of memory. Actually, there is a
1626 way to tell the X server to store the contents of a window in
1627 special cases, as we will see later.
1630 When we get an <span class="code">Expose</span> event, we
1631 should take the event's data from the members of the following
1636 uint8_t response_type; /* The type of the event, here it is XCB_EXPOSE */
1639 xcb_window_t window; /* The Id of the window that receives the event (in case */
1640 /* our application registered for events on several windows */
1641 uint16_t x; /* The x coordinate of the top-left part of the window that needs to be redrawn */
1642 uint16_t y; /* The y coordinate of the top-left part of the window that needs to be redrawn */
1643 uint16_t width; /* The width of the part of the window that needs to be redrawn */
1644 uint16_t height; /* The height of the part of the window that needs to be redrawn */
1646 } xcb_expose_event_t;
1648 <li class="subtitle"><a name="userinput">Getting user input</a>
1650 User input traditionally comes from two sources: the mouse
1651 and the keyboard. Various event types exist to notify us of
1652 user input (a key being presses on the keyboard, a key being
1653 released on the keyboard, the mouse moving over our window,
1654 the mouse entering (or leaving) our window, and so on.
1657 <li class="subsubtitle"><a name="mousepressrelease">Mouse button press and release events</a>
1659 The first event type we will deal with is a mouse
1660 button-press (or button-release) event in our window. In
1661 order to register to such an event type, we should add one
1662 (or more) of the following masks when we create our window:
1665 <li><span class="code">XCB_EVENT_MASK_BUTTON_PRESS</span>: notify us
1666 of any button that was pressed in one of our windows.
1667 <li><span class="code">XCB_EVENT_MASK_BUTTON_RELEASE</span>: notify us
1668 of any button that was released in one of our windows.
1671 The structure to be checked for in our events loop is the
1672 same for these two events, and is the following:
1676 uint8_t response_type; /* The type of the event, here it is xcb_button_press_event_t or xcb_button_release_event_t */
1677 xcb_button_t detail;
1679 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1685 int16_t event_x; /* The x coordinate where the mouse has been pressed in the window */
1686 int16_t event_y; /* The y coordinate where the mouse has been pressed in the window */
1687 uint16_t state; /* A mask of the buttons (or keys) during the event */
1688 uint8_t same_screen;
1689 } xcb_button_press_event_t;
1691 typedef xcb_button_press_event_t xcb_button_release_event_t;
1694 The <span class="code">time</span> field may be used to calculate "double-click"
1695 situations by an application (e.g. if the mouse button was
1696 clicked two times in a duration shorter than a given amount
1697 of time, assume this was a double click).
1700 The <span class="code">state</span> field is a mask of the buttons held down during
1701 the event. It is a bitwise OR of any of the following (from the xcb_button_mask_t and
1702 xcb_mod_mask_t enumerations):
1705 <li><span class="code">XCB_BUTTON_MASK_1</span>
1706 <li><span class="code">XCB_BUTTON_MASK_2</span>
1707 <li><span class="code">XCB_BUTTON_MASK_3</span>
1708 <li><span class="code">XCB_BUTTON_MASK_4</span>
1709 <li><span class="code">XCB_BUTTON_MASK_5</span>
1710 <li><span class="code">XCB_MOD_MASK_SHIFT</span>
1711 <li><span class="code">XCB_MOD_MASK_LOCK</span>
1712 <li><span class="code">XCB_MOD_MASK_CONTROL</span>
1713 <li><span class="code">XCB_MOD_MASK_1</span>
1714 <li><span class="code">XCB_MOD_MASK_2</span>
1715 <li><span class="code">XCB_MOD_MASK_3</span>
1716 <li><span class="code">XCB_MOD_MASK_4</span>
1717 <li><span class="code">XCB_MOD_MASK_5</span>
1720 Their names are self explanatory, where the first 5 refer to
1721 the mouse buttons that are being pressed, while the rest
1722 refer to various "special keys" that are being pressed (Mod1
1723 is usually the 'Alt' key or the 'Meta' key).
1726 <b>TODO:</b> Problem: it seems that the state does not
1727 change when clicking with various buttons.
1729 <li class="subsubtitle"><a name="mousemvnt">Mouse movement events</a>
1731 Similar to mouse button press and release events, we also
1732 can be notified of various mouse movement events. These can
1733 be split into two families. One is of mouse pointer
1734 movement while no buttons are pressed, and the second is a
1735 mouse pointer motion while one (or more) of the buttons are
1736 pressed (this is sometimes called "a mouse drag operation",
1737 or just "dragging"). The following event masks may be added
1738 during the creation of our window:
1741 <li><span class="code">XCB_EVENT_MASK_POINTER_MOTION</span>: events of
1742 the pointer moving in one of the windows controlled by our
1743 application, while no mouse button is held pressed.
1744 <li><span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>: Events of
1745 the pointer moving while one or more of the mouse buttons
1747 <li><span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>: same as
1748 <span class="code">XCB_EVENT_MASK_BUTTON_MOTION</span>, but only when
1749 the 1st mouse button is held pressed.
1750 <li><span class="code">XCB_EVENT_MASK_BUTTON_2_MOTION</span>,
1751 <span class="code">XCB_EVENT_MASK_BUTTON_3_MOTION</span>,
1752 <span class="code">XCB_EVENT_MASK_BUTTON_4_MOTION</span>,
1753 <span class="code">XCB_EVENT_MASK_BUTTON_5_MOTION</span>: same as
1754 <span class="code">XCB_EVENT_MASK_BUTTON_1_MOTION</span>, but
1755 respectively for 2nd, 3rd, 4th and 5th mouse button.
1758 The structure to be checked for in our events loop is the
1759 same for these events, and is the following:
1763 uint8_t response_type; /* The type of the event */
1766 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1772 int16_t event_x; /* The x coordinate of the mouse when the event was generated */
1773 int16_t event_y; /* The y coordinate of the mouse when the event was generated */
1774 uint16_t state; /* A mask of the buttons (or keys) during the event */
1775 uint8_t same_screen;
1776 } xcb_motion_notify_event_t;
1778 <li class="subsubtitle"><a name="mouseenter">Mouse pointer enter and leave events</a>
1780 Another type of event that applications might be interested
1781 in, is a mouse pointer entering a window the program
1782 controls, or leaving such a window. Some programs use these
1783 events to show the user that the application is now in
1784 focus. In order to register for such an event type, we
1785 should add one (or more) of the following masks when we
1789 <li><span class="code">xcb_event_enter_window_t</span>: notify us
1790 when the mouse pointer enters any of our controlled
1792 <li><span class="code">xcb_event_leave_window_t</span>: notify us
1793 when the mouse pointer leaves any of our controlled
1797 The structure to be checked for in our events loop is the
1798 same for these two events, and is the following:
1802 uint8_t response_type; /* The type of the event */
1805 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1811 int16_t event_x; /* The x coordinate of the mouse when the event was generated */
1812 int16_t event_y; /* The y coordinate of the mouse when the event was generated */
1813 uint16_t state; /* A mask of the buttons (or keys) during the event */
1814 uint8_t mode; /* The number of mouse button that was clicked */
1815 uint8_t same_screen_focus;
1816 } xcb_enter_notify_event_t;
1818 typedef xcb_enter_notify_event_t xcb_leave_notify_event_t;
1820 <li class="subsubtitle"><a name="focus">The keyboard focus</a>
1822 There may be many windows on a screen, but only a single
1823 keyboard attached to them. How does the X server then know
1824 which window should be sent a given keyboard input ? This is
1825 done using the keyboard focus. Only a single window on the
1826 screen may have the keyboard focus at a given time. There
1827 is a XCB function that allows a program to set the keyboard
1828 focus to a given window. The user can usually set the
1829 keyboard focus using the window manager (often by clicking
1830 on the title bar of the desired window). Once our window
1831 has the keyboard focus, every key press or key release will
1832 cause an event to be sent to our program (if it regsitered
1833 for these event types...).
1835 <li class="subsubtitle"><a name="keypress">Keyboard press and release events</a>
1837 If a window controlled by our program currently holds the
1838 keyboard focus, it can receive key press and key release
1839 events. So, we should add one (or more) of the following
1840 masks when we create our window:
1843 <li><span class="code">XCB_EVENT_MASK_KEY_PRESS</span>: notify us when
1844 a key was pressed while any of our controlled windows had
1846 <li><span class="code">XCB_EVENT_MASK_KEY_RELEASE</span>: notify us
1847 when a key was released while any of our controlled
1848 windows had the keyboard focus.
1851 The structure to be checked for in our events loop is the
1852 same for these two events, and is the following:
1856 uint8_t response_type; /* The type of the event */
1857 xcb_keycode_t detail;
1859 xcb_timestamp_t time; /* Time, in milliseconds the event took place in */
1868 uint8_t same_screen;
1869 } xcb_key_press_event_t;
1871 typedef xcb_key_press_event_t xcb_key_release_event_t;
1874 The <span class="code">detail</span> field refers to the
1875 physical key on the keyboard.
1878 <b>TODO:</b> Talk about getting the ASCII code from the key code.
1881 <li class="subtitle"><a name="eventex">X events: a complete example</a>
1883 As an example for handling events, we show a program that
1884 creates a window, enters an events loop and checks for all the
1885 events described above, and writes on the terminal the relevant
1886 characteristics of the event. With this code, it should be
1887 easy to add drawing operations, like those which have been
1891 #include <stdlib.h>
1892 #include <stdio.h>
1894 #include <xcb/xcb.h>
1897 print_modifiers (uint32_t mask)
1899 const char **mod, *mods[] = {
1900 "Shift", "Lock", "Ctrl", "Alt",
1901 "Mod2", "Mod3", "Mod4", "Mod5",
1902 "Button1", "Button2", "Button3", "Button4", "Button5"
1904 printf ("Modifier mask: ");
1905 for (mod = mods ; mask; mask >>= 1, mod++)
1914 xcb_connection_t *c;
1915 xcb_screen_t *screen;
1917 xcb_generic_event_t *e;
1921 /* Open the connection to the X server */
1922 c = xcb_connect (NULL, NULL);
1924 /* Get the first screen */
1925 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
1927 /* Ask for our window's Id */
1928 win = xcb_generate_id (c);
1930 /* Create the window */
1931 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
1932 values[0] = screen->white_pixel;
1933 values[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS |
1934 XCB_EVENT_MASK_BUTTON_RELEASE | XCB_EVENT_MASK_POINTER_MOTION |
1935 XCB_EVENT_MASK_ENTER_WINDOW | XCB_EVENT_MASK_LEAVE_WINDOW |
1936 XCB_EVENT_MASK_KEY_PRESS | XCB_EVENT_MASK_KEY_RELEASE;
1937 xcb_create_window (c, /* Connection */
1939 win, /* window Id */
1940 screen->root, /* parent window */
1942 150, 150, /* width, height */
1943 10, /* border_width */
1944 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
1945 screen->root_visual, /* visual */
1946 mask, values); /* masks */
1948 /* Map the window on the screen */
1949 xcb_map_window (c, win);
1953 while ((e = xcb_wait_for_event (c))) {
1954 switch (e->response_type & ~0x80) {
1956 xcb_expose_event_t *ev = (xcb_expose_event_t *)e;
1958 printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
1959 ev->window, ev->x, ev->y, ev->width, ev->height);
1962 case XCB_BUTTON_PRESS: {
1963 xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e;
1964 print_modifiers(ev->state);
1966 switch (ev->detail) {
1968 printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
1969 ev->event, ev->event_x, ev->event_y);
1972 printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
1973 ev->event, ev->event_x, ev->event_y);
1976 printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
1977 ev->detail, ev->event, ev->event_x, ev->event_y);
1981 case XCB_BUTTON_RELEASE: {
1982 xcb_button_release_event_t *ev = (xcb_button_release_event_t *)e;
1983 print_modifiers(ev->state);
1985 printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
1986 ev->detail, ev->event, ev->event_x, ev->event_y);
1989 case XCB_MOTION_NOTIFY: {
1990 xcb_motion_notify_event_t *ev = (xcb_motion_notify_event_t *)e;
1992 printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
1993 ev->event, ev->event_x, ev->event_y);
1996 case XCB_ENTER_NOTIFY: {
1997 xcb_enter_notify_event_t *ev = (xcb_enter_notify_event_t *)e;
1999 printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
2000 ev->event, ev->event_x, ev->event_y);
2003 case XCB_LEAVE_NOTIFY: {
2004 xcb_leave_notify_event_t *ev = (xcb_leave_notify_event_t *)e;
2006 printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
2007 ev->event, ev->event_x, ev->event_y);
2010 case XCB_KEY_PRESS: {
2011 xcb_key_press_event_t *ev = (xcb_key_press_event_t *)e;
2012 print_modifiers(ev->state);
2014 printf ("Key pressed in window %ld\n",
2018 case XCB_KEY_RELEASE: {
2019 xcb_key_release_event_t *ev = (xcb_key_release_event_t *)e;
2020 print_modifiers(ev->state);
2022 printf ("Key released in window %ld\n",
2027 /* Unknown event type, ignore it */
2028 printf("Unknown event: %d\n", e->response_type);
2031 /* Free the Generic Event */
2039 <li class="title"><a name="font">Handling text and fonts</a>
2041 Besides drawing graphics on a window, we often want to draw
2042 text. Text strings have two major properties: the characters to
2043 be drawn and the font with which they are drawn. In order to
2044 draw text, we need to first request the X server to load a
2045 font. We then assign a font to a Graphic Context, and finally, we
2046 draw the text in a window, using the Graphic Context.
2049 <li class="subtitle"><a name="fontstruct">The Font structure</a>
2051 In order to support flexible fonts, a font type is
2052 defined. You know what ? It's an Id:
2055 typedef uint32_t xcb_font_t;
2058 It is used to contain information about a font, and is passed
2059 to several functions that handle fonts selection and text drawing.
2060 We ask the X server to attribute an Id to our font with the
2064 xcb_font_t xcb_generate_id (xcb_connection_t *c);
2067 <li class="subtitle"><a name="openingfont">Opening a Font</a>
2069 To open a font, we use the following function:
2072 xcb_void_cookie_t xcb_open_font (xcb_connection_t *c,
2078 The <span class="code">fid</span> parameter is the font Id
2079 defined by <span class="code">xcb_generate_id()</span> (see
2080 above). The <span class="code">name</span> parameter is the
2081 name of the font you want to open. Use the command
2082 <span class="code">xlsfonts</span> in a terminal to know which
2083 are the fonts available on your computer. The parameter
2084 <span class="code">name_len</span> is the length of the name
2085 of the font (given by <span class="code">strlen()</span>).
2087 <li class="subtitle"><a name="assigningfont">Assigning a Font to a Graphic Context</a>
2089 Once a font is opened, you have to create a Graphic Context
2090 that will contain the informations about the color of the
2091 foreground and the background used when you draw a text in a
2092 Drawable. Here is an exemple of a Graphic Context that will
2093 allow us to draw an opened font with a black foreground and a
2098 * c is the connection
2099 * screen is the screen where the window is displayed
2100 * window is the window in which we will draw the text
2101 * font is the opened font
2104 uint32_t value_list[3];
2108 gc = xcb_generate_id (c);
2109 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
2110 value_list[0] = screen->black_pixel;
2111 value_list[1] = screen->white_pixel;
2112 value_list[2] = font;
2113 xcb_create_gc (c, gc, window, mask, value_list);
2115 /* The font is not needed anymore, so we close it */
2116 xcb_close_font (c, font);
2118 <li class="subtitle"><a name="drawingtext">Drawing text in a drawable</a>
2120 To draw a text in a drawable, we use the following function:
2123 xcb_void_cookie_t xcb_image_text_8 (xcb_connection_t *c,
2125 xcb_drawable_t drawable,
2129 const char *string);
2132 The <span class="code">string</span> parameter is the text to
2133 draw. The location of the drawing is given by the parameters
2134 <span class="code">x</span> and <span class="code">y</span>.
2135 The base line of the text is exactly the parameter
2136 <span class="code">y</span>.
2138 <li class="subtitle"><a name="fontcompleteexample">Complete example</a>
2140 This example draw a text at 10 pixels (for the base line) of
2141 the bottom of a window. Pressing the Esc key exits the program.
2144 #include <stdlib.h>
2145 #include <stdio.h>
2146 #include <string.h>
2148 #include <xcb/xcb.h>
2155 static xcb_gc_t gc_font_get (xcb_connection_t *c,
2156 xcb_screen_t *screen,
2157 xcb_window_t window,
2158 const char *font_name);
2160 static void text_draw (xcb_connection_t *c,
2161 xcb_screen_t *screen,
2162 xcb_window_t window,
2168 text_draw (xcb_connection_t *c,
2169 xcb_screen_t *screen,
2170 xcb_window_t window,
2175 xcb_void_cookie_t cookie_gc;
2176 xcb_void_cookie_t cookie_text;
2177 xcb_generic_error_t *error;
2181 length = strlen (label);
2183 gc = gc_font_get(c, screen, window, "7x13");
2185 cookie_text = xcb_image_text_8_checked (c, length, window, gc,
2188 error = xcb_request_check (c, cookie_text);
2190 fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
2195 cookie_gc = xcb_free_gc (c, gc);
2196 error = xcb_request_check (c, cookie_gc);
2198 fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
2205 gc_font_get (xcb_connection_t *c,
2206 xcb_screen_t *screen,
2207 xcb_window_t window,
2208 const char *font_name)
2210 uint32_t value_list[3];
2211 xcb_void_cookie_t cookie_font;
2212 xcb_void_cookie_t cookie_gc;
2213 xcb_generic_error_t *error;
2218 font = xcb_generate_id (c);
2219 cookie_font = xcb_open_font_checked (c, font,
2223 error = xcb_request_check (c, cookie_font);
2225 fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
2230 gc = xcb_generate_id (c);
2231 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
2232 value_list[0] = screen->black_pixel;
2233 value_list[1] = screen->white_pixel;
2234 value_list[2] = font;
2235 cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list);
2236 error = xcb_request_check (c, cookie_gc);
2238 fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
2243 cookie_font = xcb_close_font_checked (c, font);
2244 error = xcb_request_check (c, cookie_font);
2246 fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
2256 xcb_screen_iterator_t screen_iter;
2257 xcb_connection_t *c;
2258 const xcb_setup_t *setup;
2259 xcb_screen_t *screen;
2260 xcb_generic_event_t *e;
2261 xcb_generic_error_t *error;
2262 xcb_void_cookie_t cookie_window;
2263 xcb_void_cookie_t cookie_map;
2264 xcb_window_t window;
2269 /* getting the connection */
2270 c = xcb_connect (NULL, &screen_number);
2272 fprintf (stderr, "ERROR: can't connect to an X server\n");
2276 /* getting the current screen */
2277 setup = xcb_get_setup (c);
2280 screen_iter = xcb_setup_roots_iterator (setup);
2281 for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&screen_iter))
2282 if (screen_number == 0)
2284 screen = screen_iter.data;
2288 fprintf (stderr, "ERROR: can't get the current screen\n");
2293 /* creating the window */
2294 window = xcb_generate_id (c);
2295 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
2296 values[0] = screen->white_pixel;
2298 XCB_EVENT_MASK_KEY_RELEASE |
2299 XCB_EVENT_MASK_BUTTON_PRESS |
2300 XCB_EVENT_MASK_EXPOSURE |
2301 XCB_EVENT_MASK_POINTER_MOTION;
2302 cookie_window = xcb_create_window_checked (c,
2304 window, screen->root,
2305 20, 200, WIDTH, HEIGHT,
2306 0, XCB_WINDOW_CLASS_INPUT_OUTPUT,
2307 screen->root_visual,
2309 cookie_map = xcb_map_window_checked (c, window);
2311 /* error managing */
2312 error = xcb_request_check (c, cookie_window);
2314 fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code);
2318 error = xcb_request_check (c, cookie_map);
2320 fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code);
2328 e = xcb_poll_for_event(c);
2330 switch (e->response_type) {
2334 text = "Press ESC key to exit...";
2335 text_draw (c, screen, window, 10, HEIGHT - 10, text);
2338 case XCB_KEY_RELEASE: {
2339 xcb_key_release_event_t *ev;
2341 ev = (xcb_key_release_event_t *)e;
2343 switch (ev->detail) {
2360 <li class="title"><a name="wm">Interacting with the window manager</a>
2362 After we have seen how to create windows and draw on them, we
2363 take one step back, and look at how our windows are interacting
2364 with their environment (the full screen and the other
2365 windows). First of all, our application needs to interact with
2366 the window manager. The window manager is responsible to
2367 decorating drawn windows (i.e. adding a frame, an iconify
2368 button, a system menu, a title bar, etc), as well as handling
2369 icons shown when windows are being iconified. It also handles
2370 ordering of windows on the screen, and other administrative
2371 tasks. We need to give it various hints as to how we want it to
2372 treat our application's windows.
2375 <li class="subtitle"><a name="wmprop">Window properties</a>
2377 Many of the parameters communicated to the window manager are
2378 passed using data called "properties". These properties are
2379 attached by the X server to different windows, and are stored
2380 in a format that makes it possible to read them from different
2381 machines that may use different architectures (remember that
2382 an X client program may run on a remote machine).
2385 The property and its type (a string, an integer, etc) are
2386 Id. Their type are <span class="code">xcb_atom_t</span>:
2389 typedef uint32_t xcb_atom_t;
2392 To change the property of a window, we use the following
2396 xcb_void_cookie_t xcb_change_property (xcb_connection_t *c, /* Connection to the X server */
2397 uint8_t mode, /* Property mode */
2398 xcb_window_t window, /* Window */
2399 xcb_atom_t property, /* Property to change */
2400 xcb_atom_t type, /* Type of the property */
2401 uint8_t format, /* Format of the property (8, 16, 32) */
2402 uint32_t data_len, /* Length of the data parameter */
2403 const void *data); /* Data */
2406 The <span class="code">mode</span> parameter coud be one of
2407 the following values (defined in enumeration xcb_prop_mode_t in
2408 the xproto.h header file):
2411 <li>XCB_PROP_MODE_REPLACE
2412 <li>XCB_PROP_MODE_PREPEND
2413 <li>XCB_PROP_MODE_APPEND
2416 <li class="subtitle"><a name="wmname">Setting the window name and icon name</a>
2418 The first thing we want to do would be to set the name for our
2419 window. This is done using the
2420 <span class="code">xcb_change_property()</span> function. This
2421 name may be used by the window manager as the title of the
2422 window (in the title bar), in a task list, etc. The property
2423 atom to use to set the name of a window is
2424 <span class="code">WM_NAME</span> (and
2425 <span class="code">WM_ICON_NAME</span> for the iconified
2426 window) and its type is <span class="code">STRING</span>. Here
2427 is an example of utilization:
2430 #include <string.h>
2432 #include <xcb/xcb.h>
2433 #include <xcb/xcb_atom.h>
2438 xcb_connection_t *c;
2439 xcb_screen_t *screen;
2441 char *title = "Hello World !";
2442 char *title_icon = "Hello World ! (iconified)";
2446 /* Open the connection to the X server */
2447 c = xcb_connect (NULL, NULL);
2449 /* Get the first screen */
2450 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2452 /* Ask for our window's Id */
2453 win = xcb_generate_id (c);
2455 /* Create the window */
2456 xcb_create_window (c, /* Connection */
2458 win, /* window Id */
2459 screen->root, /* parent window */
2461 250, 150, /* width, height */
2462 10, /* border_width */
2463 XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */
2464 screen->root_visual, /* visual */
2465 0, NULL); /* masks, not used */
2467 /* Set the title of the window */
2468 xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2470 strlen (title), title);
2472 /* Set the title of the window icon */
2473 xcb_change_property (c, XCB_PROP_MODE_REPLACE, win,
2474 WM_ICON_NAME, STRING, 8,
2475 strlen(title_icon), title_icon);
2477 /* Map the window on the screen */
2478 xcb_map_window (c, win);
2488 <p>Note: the use of the atoms needs our program to be compiled
2489 and linked against xcb_atom, so that we have to use
2493 gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`
2497 for the program to compile fine.
2501 <li class="title"><a name="winop">Simple window operations</a>
2503 One more thing we can do to our window is manipulate them on the
2504 screen (resize them, move them, raise or lower them, iconify
2505 them, and so on). Some window operations functions are supplied
2506 by XCB for this purpose.
2509 <li class="subtitle"><a name="winmap">Mapping and un-mapping a window</a>
2511 The first pair of operations we can apply on a window is
2512 mapping it, or un-mapping it. Mapping a window causes the
2513 window to appear on the screen, as we have seen in our simple
2514 window program example. Un-mapping it causes it to be removed
2515 from the screen (although the window as a logical entity still
2516 exists). This gives the effect of making a window hidden
2517 (unmapped) and shown again (mapped). For example, if we have a
2518 dialog box window in our program, instead of creating it every
2519 time the user asks to open it, we can create the window once,
2520 in an un-mapped mode, and when the user asks to open it, we
2521 simply map the window on the screen. When the user clicked the
2522 'OK' or 'Cancel' button, we simply un-map the window. This is
2523 much faster than creating and destroying the window, however,
2524 the cost is wasted resources, both on the client side, and on
2528 To map a window, you use the following function:
2531 xcb_void_cookie_t xcb_map_window (xcb_connection_t *c,
2532 xcb_window_t window);
2535 To have a simple example, see the <a href="#helloworld">example</a>
2536 above. The mapping operation will cause an
2537 <span class="code">Expose</span> event to be sent to our
2538 application, unless the window is completely covered by other
2542 Un-mapping a window is also simple. You use the function
2545 xcb_void_cookie_t xcb_unmap_window (xcb_connection_t *c,
2546 xcb_window_t window);
2549 The utilization of this function is the same as
2550 <span class="code">xcb_map_window()</span>.
2552 <li class="subtitle"><a name="winconf">Configuring a window</a>
2554 As we have seen when we have created our first window, in the
2555 X Events subsection, we can set some attributes for the window
2556 (that is, the position, the size, the events the window will
2557 receive, etc). If we want to modify them, but the window is
2558 already created, we can change them by using the following
2562 xcb_void_cookie_t xcb_configure_window (xcb_connection_t *c, /* The connection to the X server*/
2563 xcb_window_t window, /* The window to configure */
2564 uint16_t value_mask, /* The mask */
2565 const uint32_t *value_list); /* The values to set */
2568 We set the <span class="code">value_mask</span> to one or
2569 several mask values that are in the xcb_config_window_t enumeration in the xproto.h header:
2572 <li><span class="code">XCB_CONFIG_WINDOW_X</span>: new x coordinate of the window's top left corner
2573 <li><span class="code">XCB_CONFIG_WINDOW_Y</span>: new y coordinate of the window's top left corner
2574 <li><span class="code">XCB_CONFIG_WINDOW_WIDTH</span>: new width of the window
2575 <li><span class="code">XCB_CONFIG_WINDOW_HEIGHT</span>: new height of the window
2576 <li><span class="code">XCB_CONFIG_WINDOW_BORDER_WIDTH</span>: new width of the border of the window
2577 <li><span class="code">XCB_CONFIG_WINDOW_SIBLING</span>
2578 <li><span class="code">XCB_CONFIG_WINDOW_STACK_MODE</span>: the new stacking order
2581 We then give to <span class="code">value_mask</span> the new
2582 value. We now describe how to use
2583 <span class="code">xcb_configure_window_t</span> in some useful
2586 <li class="subtitle"><a name="winmove">Moving a window around the screen</a>
2588 An operation we might want to do with windows is to move them
2589 to a different location. This can be done like this:
2592 const static uint32_t values[] = { 10, 20 };
2594 /* The connection c and the window win are supposed to be defined */
2596 /* Move the window to coordinates x = 10 and y = 20 */
2597 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y, values);
2600 Note that when the window is moved, it might get partially
2601 exposed or partially hidden by other windows, and thus we
2602 might get <span class="code">Expose</span> events due to this
2605 <li class="subtitle"><a name="winsize">Resizing a window</a>
2607 Yet another operation we can do is to change the size of a
2608 window. This is done using the following code:
2611 const static uint32_t values[] = { 200, 300 };
2613 /* The connection c and the window win are supposed to be defined */
2615 /* Resize the window to width = 10 and height = 20 */
2616 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2619 We can also combine the move and resize operations using one
2620 single call to <span class="code">xcb_configure_window_t</span>:
2623 const static uint32_t values[] = { 10, 20, 200, 300 };
2625 /* The connection c and the window win are supposed to be defined */
2627 /* Move the window to coordinates x = 10 and y = 20 */
2628 /* and resize the window to width = 10 and height = 20 */
2629 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y | XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);
2631 <li class="subtitle"><a name="winstack">Changing windows stacking order: raise and lower</a>
2633 Until now, we changed properties of a single window. We'll see
2634 that there are properties that relate to the window and other
2635 windows. One of them is the stacking order. That is, the order
2636 in which the windows are layered on top of each other. The
2637 front-most window is said to be on the top of the stack, while
2638 the back-most window is at the bottom of the stack. Here is
2639 how to manipulate our windows stack order:
2642 const static uint32_t values[] = { XCB_STACK_MODE_ABOVE };
2644 /* The connection c and the window win are supposed to be defined */
2646 /* Move the window on the top of the stack */
2647 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2650 const static uint32_t values[] = { XCB_STACK_MODE_BELOW };
2652 /* The connection c and the window win are supposed to be defined */
2654 /* Move the window on the bottom of the stack */
2655 xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);
2657 <li class="subtitle"><a name="wingetinfo">Getting information about a window</a>
2659 Just like we can set various attributes of our windows, we can
2660 also ask the X server supply the current values of these
2661 attributes. For example, we can check where a window is
2662 located on the screen, what is its current size, whether it is
2663 mapped or not, etc. The structure that contains some of this
2668 uint8_t response_type;
2669 uint8_t depth; /* depth of the window */
2672 xcb_window_t root; /* Id of the root window *>
2673 int16_t x; /* X coordinate of the window's location */
2674 int16_t y; /* Y coordinate of the window's location */
2675 uint16_t width; /* Width of the window */
2676 uint16_t height; /* Height of the window */
2677 uint16_t border_width; /* Width of the window's border */
2678 } xcb_get_geometry_reply_t;
2681 XCB fill this structure with two functions:
2684 xcb_get_geometry_cookie_t xcb_get_geometry (xcb_connection_t *c,
2685 xcb_drawable_t drawable);
2686 xcb_get_geometry_reply_t *xcb_get_geometry_reply (xcb_connection_t *c,
2687 xcb_get_geometry_cookie_t cookie,
2688 xcb_generic_error_t **e);
2691 You use them as follows:
2694 xcb_connection_t *c;
2696 xcb_get_geometry_reply_t *geom;
2698 /* You initialize c and win */
2700 geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2702 /* Do something with the fields of geom */
2707 Remark that you have to free the structure, as
2708 <span class="code">xcb_get_geometry_reply_t</span> allocates a
2712 One problem is that the returned location of the window is
2713 relative to its parent window. This makes these coordinates
2714 rather useless for any window manipulation functions, like
2715 moving it on the screen. In order to overcome this problem, we
2716 need to take a two-step operation. First, we find out the Id
2717 of the parent window of our window. We then translate the
2718 above relative coordinates to the screen coordinates.
2721 To get the Id of the parent window, we need this structure:
2725 uint8_t response_type;
2730 xcb_window_t parent; /* Id of the parent window */
2731 uint16_t children_len;
2733 } xcb_query_tree_reply_t;
2736 To fill this structure, we use these two functions:
2739 xcb_query_tree_cookie_t xcb_query_tree (xcb_connection_t *c,
2740 xcb_window_t window);
2741 xcb_query_tree_reply_t *xcb_query_tree_reply (xcb_connection_t *c,
2742 xcb_query_tree_cookie_t cookie,
2743 xcb_generic_error_t **e);
2746 The translated coordinates will be found in this structure:
2750 uint8_t response_type;
2751 uint8_t same_screen;
2755 uint16_t dst_x; /* Translated x coordinate */
2756 uint16_t dst_y; /* Translated y coordinate */
2757 } xcb_translate_coordinates_reply_t;
2760 As usual, we need two functions to fill this structure:
2763 xcb_translate_coordinates_cookie_t xcb_translate_coordinates (xcb_connection_t *c,
2764 xcb_window_t src_window,
2765 xcb_window_t dst_window,
2768 xcb_translate_coordinates_reply_t *xcb_translate_coordinates_reply (xcb_connection_t *c,
2769 xcb_translate_coordinates_cookie_t cookie,
2770 xcb_generic_error_t **e);
2773 We use them as follows:
2776 xcb_connection_t *c;
2778 xcb_get_geometry_reply_t *geom;
2779 xcb_query_tree_reply_t *tree;
2780 xcb_translate_coordinates_reply_t *trans;
2782 /* You initialize c and win */
2784 geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL);
2788 tree = xcb_query_tree_reply (c, xcb_query_tree (c, win), NULL);
2792 trans = xcb_translate_coordinates_reply (c,
2793 xcb_translate_coordinates (c,
2796 geom->x, geom->y),
2801 /* the translated coordinates are in trans->dst_x and trans->dst_y */
2808 Of course, as for <span class="code">geom</span>,
2809 <span class="code">tree</span> and
2810 <span class="code">trans</span> have to be freed.
2813 The work is a bit hard, but XCB is a very low-level library.
2816 <b>TODO:</b> the utilization of these functions should be a
2817 prog, which displays the coordinates of the window.
2820 There is another structure that gives informations about our window:
2824 uint8_t response_type;
2825 uint8_t backing_store;
2828 xcb_visualid_t visual; /* Visual of the window */
2830 uint8_t bit_gravity;
2831 uint8_t win_gravity;
2832 uint32_t backing_planes;
2833 uint32_t backing_pixel;
2835 uint8_t map_is_installed;
2836 uint8_t map_state; /* Map state of the window */
2837 uint8_t override_redirect;
2838 xcb_colormap_t colormap; /* Colormap of the window */
2839 uint32_t all_event_masks;
2840 uint32_t your_event_mask;
2841 uint16_t do_not_propagate_mask;
2842 } xcb_get_window_attributes_reply_t;
2845 XCB supplies these two functions to fill it:
2848 xcb_get_window_attributes_cookie_t xcb_get_window_attributes (xcb_connection_t *c,
2849 xcb_window_t window);
2850 xcb_get_window_attributes_reply_t *xcb_get_window_attributes_reply (xcb_connection_t *c,
2851 xcb_get_window_attributes_cookie_t cookie,
2852 xcb_generic_error_t **e);
2855 You use them as follows:
2858 xcb_connection_t *c;
2860 xcb_get_window_attributes_reply_t *attr;
2862 /* You initialize c and win */
2864 attr = xcb_get_window_attributes_reply (c, xcb_get_window_attributes (c, win), NULL);
2869 /* Do something with the fields of attr */
2874 As for <span class="code">geom</span>,
2875 <span class="code">attr</span> has to be freed.
2878 <li class="title"><a name="usecolor">Using colors to paint the rainbow</a>
2880 Up until now, all our painting operation were done using black
2881 and white. We will (finally) see now how to draw using colors.
2884 <li class="subtitle"><a name="colormap">Color maps</a>
2886 In the beginning, there were not enough colors. Screen
2887 controllers could only support a limited number of colors
2888 simultaneously (initially 2, then 4, 16 and 256). Because of
2889 this, an application could not just ask to draw in a "light
2890 purple-red" color, and expect that color to be available. Each
2891 application allocated the colors it needed, and when all the
2892 color entries (4, 16, 256 colors) were in use, the next color
2893 allocation would fail.
2896 Thus, the notion of "a color map" was introduced. A color map
2897 is a table whose size is the same as the number of
2898 simultaneous colors a given screen controller. Each entry
2899 contained the RGB (Red, Green and Blue) values of a different
2900 color (all colors can be drawn using some combination of red,
2901 green and blue). When an application wants to draw on the
2902 screen, it does not specify which color to use. Rather, it
2903 specifies which color entry of some color map to be used
2904 during this drawing. Change the value in this color map entry
2905 and the drawing will use a different color.
2908 In order to be able to draw using colors that got something to
2909 do with what the programmer intended, color map allocation
2910 functions are supplied. You could ask to allocate entry for a
2911 color with a set of RGB values. If one already existed, you
2912 would get its index in the table. If none existed, and the
2913 table was not full, a new cell would be allocated to contain
2914 the given RGB values, and its index returned. If the table was
2915 full, the procedure would fail. You could then ask to get a
2916 color map entry with a color that is closest to the one you
2917 were asking for. This would mean that the actual drawing on
2918 the screen would be done using colors similar to what you
2919 wanted, but not the same.
2922 On today's more modern screens where one runs an X server with
2923 support for 16 million colors, this limitation looks a little
2924 silly, but remember that there are still older computers with
2925 older graphics cards out there. Using color map, support for
2926 these screen becomes transparent to you. On a display
2927 supporting 16 million colors, any color entry allocation
2928 request would succeed. On a display supporting a limited
2929 number of colors, some color allocation requests would return
2930 similar colors. It won't look as good, but your application
2933 <li class="subtitle"><a name="colormapalloc">Allocating and freeing Color Maps</a>
2935 When you draw using XCB, you can choose to use the standard
2936 color map of the screen your window is displayed on, or you
2937 can allocate a new color map and apply it to a window. In the
2938 latter case, each time the mouse moves onto your window, the
2939 screen color map will be replaced by your window's color map,
2940 and you'll see all the other windows on screen change their
2941 colors into something quite bizzare. In fact, this is the
2942 effect you get with X applications that use the "-install"
2943 command line option.
2946 In XCB, a color map is (as often in X) an Id:
2949 typedef uint32_t xcb_colormap_t;
2952 In order to access the screen's default color map, you just
2953 have to retrieve the <span class="code">default_colormap</span>
2954 field of the <span class="code">xcb_screen_t</span> structure
2956 <a href="#screen">Checking basic information about a connection</a>):
2959 #include <stdio.h>
2961 #include <xcb/xcb.h>
2966 xcb_connection_t *c;
2967 xcb_screen_t *screen;
2968 xcb_colormap_t colormap;
2970 /* Open the connection to the X server and get the first screen */
2971 c = xcb_connect (NULL, NULL);
2972 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
2974 colormap = screen->default_colormap;
2980 This will return the color map used by default on the first
2981 screen (again, remember that an X server may support several
2982 different screens, each of which might have its own resources).
2985 The other option, that of allocating a new colormap, works as
2986 follows. We first ask the X server to give an Id to our color
2987 map, with this function:
2990 xcb_colormap_t xcb_generate_id (xcb_connection_t *c);
2993 Then, we create the color map with
2996 xcb_void_cookie_t xcb_create_colormap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
2997 uint8_t alloc, /* Colormap entries to be allocated (AllocNone or AllocAll) */
2998 xcb_colormap_t mid, /* Id of the color map */
2999 xcb_window_t window, /* Window on whose screen the colormap will be created */
3000 xcb_visualid_t visual); /* Id of the visual supported by the screen */
3003 Here is an example of creation of a new color map:
3006 #include <xcb/xcb.h>
3011 xcb_connection_t *c;
3012 xcb_screen_t *screen;
3016 /* Open the connection to the X server and get the first screen */
3017 c = xcb_connect (NULL, NULL);
3018 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
3020 /* We create the window win here*/
3022 cmap = xcb_generate_id (c);
3023 xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual);
3029 Note that the window parameter is only used to allow the X
3030 server to create the color map for the given screen. We can
3031 then use this color map for any window drawn on the same screen.
3034 To free a color map, it suffices to use this function:
3037 xcb_void_cookie_t xcb_free_colormap (xcb_connection_t *c, /* The connection */
3038 xcb_colormap_t cmap); /* The color map */
3046 <li>XCreateColormap ()
3051 <li>xcb_generate_id ()
3052 <li>xcb_create_colormap ()
3057 <li>XFreeColormap ()
3062 <li>xcb_free_colormap ()
3067 <li class="subtitle"><a name="alloccolor">Allocating and freeing a color entry</a>
3069 Once we got access to some color map, we can start allocating
3070 colors. The informations related to a color are stored in the
3071 following structure:
3075 uint8_t response_type;
3079 uint16_t red; /* The red component */
3080 uint16_t green; /* The green component */
3081 uint16_t blue; /* The blue component */
3083 uint32_t pixel; /* The entry in the color map, supplied by the X server */
3084 } xcb_alloc_color_reply_t;
3087 XCB supplies these two functions to fill it:
3090 xcb_alloc_color_cookie_t xcb_alloc_color (xcb_connection_t *c,
3091 xcb_colormap_t cmap,
3095 xcb_alloc_color_reply_t *xcb_alloc_color_reply (xcb_connection_t *c,
3096 xcb_alloc_color_cookie_t cookie,
3097 xcb_generic_error_t **e);
3100 The fuction <span class="code">xcb_alloc_color()</span> takes the
3101 3 RGB components as parameters (red, green and blue). Here is an
3102 example of using these functions:
3105 #include <malloc.h>
3107 #include <xcb/xcb.h>
3112 xcb_connection_t *c;
3113 xcb_screen_t *screen;
3115 xcb_colormap_t cmap;
3116 xcb_alloc_color_reply_t *rep;
3118 /* Open the connection to the X server and get the first screen */
3119 c = xcb_connect (NULL, NULL);
3120 screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
3122 /* We create the window win here*/
3124 cmap = xcb_generate_id (c);
3125 xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual);
3127 rep = xcb_alloc_color_reply (c, xcb_alloc_color (c, cmap, 65535, 0, 0), NULL);
3132 /* Do something with r->pixel or the components */
3140 As <span class="code">xcb_alloc_color_reply()</span> allocates
3141 memory, you have to free <span class="code">rep</span>.
3144 <b>TODO</b>: Talk about freeing colors.
3147 <li class="title"><a name="pixmaps">X Bitmaps and Pixmaps</a>
3149 One thing many so-called "Multi-Media" applications need to do,
3150 is display images. In the X world, this is done using bitmaps
3151 and pixmaps. We have already seen some usage of them when
3152 setting an icon for our application. Lets study them further,
3153 and see how to draw these images inside a window, along side the
3154 simple graphics and text we have seen so far.
3157 One thing to note before delving further, is that XCB (nor Xlib)
3158 supplies no means of manipulating popular image formats, such as
3159 gif, png, jpeg or tiff. It is up to the programmer (or to higher
3160 level graphics libraries) to translate these image formats into
3161 formats that the X server is familiar with (x bitmaps and x
3165 <li class="subtitle"><a name="pixmapswhat">What is a X Bitmap? An X Pixmap?</a>
3167 An X bitmap is a two-color image stored in a format specific
3168 to the X window system. When stored in a file, the bitmap data
3169 looks like a C source file. It contains variables defining the
3170 width and the height of the bitmap, an array containing the
3171 bit values of the bitmap (the size of the array is
3172 (width+7)/8*height and the bit and byte order are LSB), and
3173 an optional hot-spot location (that will
3174 be explained later, when discussing mouse cursors).
3177 An X pixmap is a format used to stored images in the memory of
3178 an X server. This format can store both black and white images
3179 (such as x bitmaps) as well as color images. It is the only
3180 image format supported by the X protocol, and any image to be
3181 drawn on screen, should be first translated into this format.
3184 In actuality, an X pixmap can be thought of as a window that
3185 does not appear on the screen. Many graphics operations that
3186 work on windows, will also work on pixmaps. Indeed, the type
3187 of X pixmap in XCB is an Id like a window:
3190 typedef uint32_t xcb_pixmap_t;
3193 Like Xlib, there is no difference between a Drawable, a Window
3197 typedef uint32_t xcb_drawable_t;
3200 in order to avoid confusion between a window and a pixmap. The
3201 operations that will work the same on a window or a pixmap
3202 will require a <span class="code">xcb_drawable_t</span>
3206 Remark: In Xlib, there is no specific difference between a
3207 <span class="code">Drawable</span>, a
3208 <span class="code">Pixmap</span> or a
3209 <span class="code">Window</span>: all are 32 bit long
3210 integer. XCB wraps all these different IDs in structures to
3211 provide some measure of type-safety.
3214 <li class="subtitle"><a name="pixmapscreate">Creating a pixmap</a>
3216 Sometimes we want to create an un-initialized pixmap, so we
3217 can later draw into it. This is useful for image drawing
3218 programs (creating a new empty canvas will cause the creation
3219 of a new pixmap on which the drawing can be stored). It is
3220 also useful when reading various image formats: we load the
3221 image data into memory, create a pixmap on the server, and
3222 then draw the decoded image data onto that pixmap.
3225 To create a new pixmap, we first ask the X server to give an
3226 Id to our pixmap, with this function:
3229 xcb_pixmap_t xcb_generate_id (xcb_connection_t *c);
3232 Then, XCB supplies the following function to create new pixmaps:
3235 xcb_void_cookie_t xcb_create_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
3236 uint8_t depth, /* Depth of the screen */
3237 xcb_pixmap_t pid, /* Id of the pixmap */
3238 xcb_drawable_t drawable,
3239 uint16_t width, /* Width of the window (in pixels) */
3240 uint16_t height); /* Height of the window (in pixels) */
3243 <b>TODO</b>: Explain the drawable parameter, and give an
3244 example (like <a href="xpoints.c">xpoints.c</a>)
3246 <li class="subtitle"><a name="pixmapsdraw"></a>Drawing a pixmap in a window
3248 Once we got a handle to a pixmap, we can draw it on some
3249 window, using the following function:
3252 xcb_void_cookie_t xcb_copy_area (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
3253 xcb_drawable_t src_drawable, /* The Drawable we want to paste */
3254 xcb_drawable_t dst_drawable, /* The Drawable on which we copy the previous Drawable */
3255 xcb_gcontext_t gc, /* A Graphic Context */
3256 int16_t src_x, /* Top left x coordinate of the region we want to copy */
3257 int16_t src_y, /* Top left y coordinate of the region we want to copy */
3258 int16_t dst_x, /* Top left x coordinate of the region where we want to copy */
3259 int16_t dst_y, /* Top left y coordinate of the region where we want to copy */
3260 uint16_t width, /* Width of the region we want to copy */
3261 uint16_t height); /* Height of the region we want to copy */
3264 As you can see, we could copy the whole pixmap, as well as
3265 only a given rectangle of the pixmap. This is useful to
3266 optimize the drawing speed: we could copy only what we have
3267 modified in the pixmap.
3270 <b>One important note should be made</b>: it is possible to
3271 create pixmaps with different depths on the same screen. When
3272 we perform copy operations (a pixmap onto a window, etc), we
3273 should make sure that both source and target have the same
3274 depth. If they have a different depth, the operation would
3275 fail. The exception to this is if we copy a specific bit plane
3276 of the source pixmap using the
3277 <span class="code">xcb_copy_plane_t</span> function. In such an
3278 event, we can copy a specific plane to the target window (in
3279 actuality, setting a specific bit in the color of each pixel
3280 copied). This can be used to generate strange graphic effects
3281 in a window, but that is beyond the scope of this tutorial.
3283 <li class="subtitle"><a name="pixmapsfree"></a>Freeing a pixmap
3285 Finally, when we are done using a given pixmap, we should free
3286 it, in order to free resources of the X server. This is done
3287 using this function:
3290 xcb_void_cookie_t xcb_free_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */
3291 xcb_pixmap_t pixmap); /* A given pixmap */
3294 Of course, after having freed it, we must not try accessing
3298 <b>TODO</b>: Give an example, or a link to xpoints.c
3301 <li class="title"><a name="mousecursor">Messing with the mouse cursor</a>
3303 It it possible to modify the shape of the mouse pointer (also
3304 called the X pointer) when in certain states, as we otfen see in
3305 programs. For example, a busy application would often display
3306 the sand clock over its main window, to give the user a visual
3307 hint that he should wait. Let's see how we can change the mouse
3308 cursor of our windows.
3311 <li class="subtitle"><a name="mousecursorcreate">Creating and destroying a mouse cursor</a>
3313 There are two methods for creating cursors. One of them is by
3314 using a set of predefined cursors, that are supplied by the X
3315 server, the other is by using a user-supplied bitmap.
3318 In the first method, we use a special font named "cursor", and
3319 the function <span class="code">xcb_create_glyph_cursor</span>:
3322 xcb_void_cookie_t xcb_create_glyph_cursor (xcb_connection_t *c,
3324 xcb_font_t source_font, /* font for the source glyph */
3325 xcb_font_t mask_font, /* font for the mask glyph or XCB_NONE */
3326 uint16_t source_char, /* character glyph for the source */
3327 uint16_t mask_char, /* character glyph for the mask */
3328 uint16_t fore_red, /* red value for the foreground of the source */
3329 uint16_t fore_green, /* green value for the foreground of the source */
3330 uint16_t fore_blue, /* blue value for the foreground of the source */
3331 uint16_t back_red, /* red value for the background of the source */
3332 uint16_t back_green, /* green value for the background of the source */
3333 uint16_t back_blue) /* blue value for the background of the source */
3336 <b>TODO</b>: Describe <span class="code">source_char</span>
3337 and <span class="code">mask_char</span>, for example by giving
3338 an example on how to get the values. There is a list there:
3339 <a href="http://tronche.com/gui/x/xlib/appendix/b/">X Font Cursors</a>
3342 So we first open that font (see <a href="#loadfont">Loading a Font</a>)
3343 and create the new cursor. As for every X ressource, we have to
3344 ask for an X id with <span class="code">xcb_generate_id</span>
3349 xcb_cursor_t cursor;
3351 /* The connection is set */
3353 font = xcb_generate_id (conn);
3354 xcb_open_font (conn, font, strlen ("cursor"), "cursor");
3356 cursor = xcb_generate_id (conn);
3357 xcb_create_glyph_cursor (conn, cursor, font, font,
3363 We have created the cursor "right hand" by specifying 58 to
3364 the <span class="code">source_fon</span>t argument and 58 + 1
3365 to the <span class="code">mask_font</span>.
3368 The cursor is destroyed by using the function
3371 xcb_void_cookie_t xcb_free_cursor (xcb_connection_t *c,
3372 xcb_cursor_t cursor);
3375 In the second method, we create a new cursor by using a pair
3376 of pixmaps, with depth of one (that is, two colors
3377 pixmaps). One pixmap defines the shape of the cursor, while
3378 the other works as a mask, specifying which pixels of the
3379 cursor will be actually drawn. The rest of the pixels will be
3383 <b>TODO</b>: give an example.
3385 <li class="subtitle"><a name="mousecursorset">Setting a window's mouse cursor</a>
3387 Once the cursor is created, we can modify the cursor of our
3388 window by using <span class="code">xcb_change_window_attributes</span>
3389 and using the <span class="code">XCB_CWCURSOR</span> attribute:
3393 uint32_t value_list;
3395 /* The connection and window are set */
3396 /* The cursor is already created */
3398 mask = XCB_CWCURSOR;
3399 value_list = cursor;
3400 xcb_change_window_attributes (conn, window, mask, &value_list);
3403 Of course, the cursor and the font must be freed.
3405 <li class="subtitle"><a name="mousecursorexample">Complete example</a>
3407 The following example displays a window with a
3408 button. When entering the window, the window cursor is changed
3409 to an arrow. When clicking once on the button, the cursor is
3410 changed to a hand. When clicking again on the button, the
3411 cursor window gets back to the arrow. The Esc key exits the
3415 #include <stdlib.h>
3416 #include <stdio.h>
3417 #include <string.h>
3419 #include <xcb/xcb.h>
3426 static xcb_gc_t gc_font_get (xcb_connection_t *c,
3427 xcb_screen_t *screen,
3428 xcb_window_t window,
3429 const char *font_name);
3431 static void button_draw (xcb_connection_t *c,
3432 xcb_screen_t *screen,
3433 xcb_window_t window,
3438 static void text_draw (xcb_connection_t *c,
3439 xcb_screen_t *screen,
3440 xcb_window_t window,
3445 static void cursor_set (xcb_connection_t *c,
3446 xcb_screen_t *screen,
3447 xcb_window_t window,
3452 button_draw (xcb_connection_t *c,
3453 xcb_screen_t *screen,
3454 xcb_window_t window,
3459 xcb_point_t points[5];
3460 xcb_void_cookie_t cookie_gc;
3461 xcb_void_cookie_t cookie_line;
3462 xcb_void_cookie_t cookie_text;
3463 xcb_generic_error_t *error;
3470 length = strlen (label);
3473 gc = gc_font_get(c, screen, window, "7x13");
3475 width = 7 * length + 2 * (inset + 1);
3476 height = 13 + 2 * (inset + 1);
3479 points[1].x = x1 + width;
3481 points[2].x = x1 + width;
3482 points[2].y = y1 - height;
3484 points[3].y = y1 - height;
3487 cookie_line = xcb_poly_line_checked (c, XCB_COORD_MODE_ORIGIN,
3488 window, gc, 5, points);
3490 error = xcb_request_check (c, cookie_line);
3492 fprintf (stderr, "ERROR: can't draw lines : %d\n", error->error_code);
3497 cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3499 y1 - inset - 1, label);
3500 error = xcb_request_check (c, cookie_text);
3502 fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3507 cookie_gc = xcb_free_gc (c, gc);
3508 error = xcb_request_check (c, cookie_gc);
3510 fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3517 text_draw (xcb_connection_t *c,
3518 xcb_screen_t *screen,
3519 xcb_window_t window,
3524 xcb_void_cookie_t cookie_gc;
3525 xcb_void_cookie_t cookie_text;
3526 xcb_generic_error_t *error;
3530 length = strlen (label);
3532 gc = gc_font_get(c, screen, window, "7x13");
3534 cookie_text = xcb_image_text_8_checked (c, length, window, gc,
3537 error = xcb_request_check (c, cookie_text);
3539 fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code);
3544 cookie_gc = xcb_free_gc (c, gc);
3545 error = xcb_request_check (c, cookie_gc);
3547 fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code);
3554 gc_font_get (xcb_connection_t *c,
3555 xcb_screen_t *screen,
3556 xcb_window_t window,
3557 const char *font_name)
3559 uint32_t value_list[3];
3560 xcb_void_cookie_t cookie_font;
3561 xcb_void_cookie_t cookie_gc;
3562 xcb_generic_error_t *error;
3567 font = xcb_generate_id (c);
3568 cookie_font = xcb_open_font_checked (c, font,
3572 error = xcb_request_check (c, cookie_font);
3574 fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3579 gc = xcb_generate_id (c);
3580 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3581 value_list[0] = screen->black_pixel;
3582 value_list[1] = screen->white_pixel;
3583 value_list[2] = font;
3584 cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list);
3585 error = xcb_request_check (c, cookie_gc);
3587 fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3592 cookie_font = xcb_close_font_checked (c, font);
3593 error = xcb_request_check (c, cookie_font);
3595 fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3604 cursor_set (xcb_connection_t *c,
3605 xcb_screen_t *screen,
3606 xcb_window_t window,
3609 uint32_t values_list[3];
3610 xcb_void_cookie_t cookie_font;
3611 xcb_void_cookie_t cookie_gc;
3612 xcb_generic_error_t *error;
3614 xcb_cursor_t cursor;
3617 uint32_t value_list;
3619 font = xcb_generate_id (c);
3620 cookie_font = xcb_open_font_checked (c, font,
3623 error = xcb_request_check (c, cookie_font);
3625 fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code);
3630 cursor = xcb_generate_id (c);
3631 xcb_create_glyph_cursor (c, cursor, font, font,
3632 cursor_id, cursor_id + 1,
3636 gc = xcb_generate_id (c);
3637 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT;
3638 values_list[0] = screen->black_pixel;
3639 values_list[1] = screen->white_pixel;
3640 values_list[2] = font;
3641 cookie_gc = xcb_create_gc_checked (c, gc, window, mask, values_list);
3642 error = xcb_request_check (c, cookie_gc);
3644 fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code);
3649 mask = XCB_CW_CURSOR;
3650 value_list = cursor;
3651 xcb_change_window_attributes (c, window, mask, &value_list);
3653 xcb_free_cursor (c, cursor);
3655 cookie_font = xcb_close_font_checked (c, font);
3656 error = xcb_request_check (c, cookie_font);
3658 fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code);
3666 xcb_screen_iterator_t screen_iter;
3667 xcb_connection_t *c;
3668 const xcb_setup_t *setup;
3669 xcb_screen_t *screen;
3670 xcb_generic_event_t *e;
3671 xcb_generic_error_t *error;
3672 xcb_void_cookie_t cookie_window;
3673 xcb_void_cookie_t cookie_map;
3674 xcb_window_t window;
3678 uint8_t is_hand = 0;
3680 /* getting the connection */
3681 c = xcb_connect (NULL, &screen_number);
3683 fprintf (stderr, "ERROR: can't connect to an X server\n");
3687 /* getting the current screen */
3688 setup = xcb_get_setup (c);
3691 screen_iter = xcb_setup_roots_iterator (setup);
3692 for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&screen_iter))
3693 if (screen_number == 0)
3695 screen = screen_iter.data;
3699 fprintf (stderr, "ERROR: can't get the current screen\n");
3704 /* creating the window */
3705 window = xcb_generate_id (c);
3706 mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
3707 values[0] = screen->white_pixel;
3709 XCB_EVENT_MASK_KEY_RELEASE |
3710 XCB_EVENT_MASK_BUTTON_PRESS |
3711 XCB_EVENT_MASK_EXPOSURE |
3712 XCB_EVENT_MASK_POINTER_MOTION;
3713 cookie_window = xcb_create_window_checked (c,
3715 window, screen->root,
3716 20, 200, WIDTH, HEIGHT,
3717 0, XCB_WINDOW_CLASS_INPUT_OUTPUT,
3718 screen->root_visual,
3720 cookie_map = xcb_map_window_checked (c, window);
3722 /* error managing */
3723 error = xcb_request_check (c, cookie_window);
3725 fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code);
3729 error = xcb_request_check (c, cookie_map);
3731 fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code);
3736 cursor_set (c, screen, window, 68);
3741 e = xcb_poll_for_event(c);
3743 switch (e->response_type) {
3747 text = "click here to change cursor";
3748 button_draw (c, screen, window,
3749 (WIDTH - 7 * strlen(text)) / 2,
3750 (HEIGHT - 16) / 2, text);
3752 text = "Press ESC key to exit...";
3753 text_draw (c, screen, window, 10, HEIGHT - 10, text);
3756 case XCB_BUTTON_PRESS: {
3757 xcb_button_press_event_t *ev;
3760 ev = (xcb_button_press_event_t *)e;
3761 length = strlen ("click here to change cursor");
3763 if ((ev->event_x >= (WIDTH - 7 * length) / 2) &&
3764 (ev->event_x <= ((WIDTH - 7 * length) / 2 + 7 * length + 6)) &&
3765 (ev->event_y >= (HEIGHT - 16) / 2 - 19) &&
3766 (ev->event_y <= ((HEIGHT - 16) / 2)))
3767 is_hand = 1 - is_hand;
3769 is_hand ? cursor_set (c, screen, window, 58) : cursor_set (c, screen, window, 68);
3771 case XCB_KEY_RELEASE: {
3772 xcb_key_release_event_t *ev;
3774 ev = (xcb_key_release_event_t *)e;
3776 switch (ev->detail) {
3793 <li class="title"><a name="translation">Translation of basic Xlib functions and macros</a>
3795 The problem when you want to port an Xlib program to XCB is that
3796 you don't know if the Xlib function that you want to "translate"
3797 is a X Window one or an Xlib macro. In that section, we describe
3798 a way to translate the usual functions or macros that Xlib
3799 provides. It's usually just a member of a structure.
3802 <li class="subtitle"><a name="displaystructure">Members of the Display structure</a>
3804 In this section, we look at how to translate the macros that
3805 return some members of the <span class="code">Display</span>
3806 structure. They are obtained by using a function that requires a
3807 <span class="code">xcb_connection_t *</span> or a member of the
3808 <span class="code">xcb_setup_t</span> structure
3809 (via the function <span class="code">xcb_get_setup</span>), or
3810 a function that requires that structure.
3813 <li class="subtitle"><a name="ConnectionNumber">ConnectionNumber</a>
3815 This number is the file descriptor that connects the client
3816 to the server. You just have to use that function:
3819 int xcb_get_file_descriptor (xcb_connection_t *c);
3821 <li class="subtitle"><a name="DefaultScreen"></a>DefaultScreen
3823 That number is not stored by XCB. It is returned in the
3824 second parameter of the function <span class="code"><a href="#openconn">xcb_connect</a></span>.
3825 Hence, you have to store it yourself if you want to use
3826 it. Then, to get the <span class="code">xcb_screen_t</span>
3827 structure, you have to iterate on the screens.
3828 The equivalent function of the Xlib's
3829 <span class="code">ScreenOfDisplay</span> function can be
3830 found <a href="#ScreenOfDisplay">below</a>. This is also provided in the
3831 xcb_aux_t library as <span class="code">xcb_aux_get_screen()</span>. OK, here is the
3832 small piece of code to get that number:
3835 xcb_connection_t *c;
3836 int screen_default_nbr;
3838 /* you pass the name of the display you want to xcb_connect_t */
3840 c = xcb_connect (display_name, &screen_default_nbr);
3842 /* screen_default_nbr contains now the number of the default screen */
3844 <li class="subtitle"><a name="QLength"></a>QLength
3849 However, this points out a basic difference in philosophy between
3850 Xlib and XCB. Xlib has several functions for filtering and
3851 manipulating the incoming and outgoing X message queues. XCB
3852 wishes to hide this as much as possible from the user, which
3853 allows for more freedom in implementation strategies.
3855 <li class="subtitle"><a name="ScreenCount"></a>ScreenCount
3857 You get the count of screens with the functions
3858 <span class="code">xcb_get_setup</span>
3860 <span class="code">xcb_setup_roots_iterator</span>
3861 (if you need to iterate):
3864 xcb_connection_t *c;
3867 /* you init the connection */
3869 screen_count = xcb_setup_roots_iterator (xcb_get_setup (c)).rem;
3871 /* screen_count contains now the count of screens */
3874 If you don't want to iterate over the screens, a better way
3875 to get that number is to use
3876 <span class="code">xcb_setup_roots_length_t</span>:
3879 xcb_connection_t *c;
3882 /* you init the connection */
3884 screen_count = xcb_setup_roots_length (xcb_get_setup (c));
3886 /* screen_count contains now the count of screens */
3888 <li class="subtitle"><a name="ServerVendor"></a>ServerVendor
3890 You get the name of the vendor of the server hardware with
3891 the functions <span class="code">xcb_get_setup</span>
3894 class="code">xcb_setup_vendor</span>. Beware
3895 that, unlike Xlib, the string returned by XCB is not
3896 necessarily null-terminaled:
3899 xcb_connection_t *c;
3900 char *vendor = NULL;
3903 /* you init the connection */
3904 length = xcb_setup_vendor_length (xcb_get_setup (c));
3905 vendor = (char *)malloc (length + 1);
3907 memcpy (vendor, xcb_setup_vendor (xcb_get_setup (c)), length);
3908 vendor[length] = '\0';
3910 /* vendor contains now the name of the vendor. Must be freed when not used anymore */
3912 <li class="subtitle"><a name="ProtocolVersion"></a>ProtocolVersion
3914 You get the major version of the protocol in the
3915 <span class="code">xcb_setup_t</span>
3916 structure, with the function <span class="code">xcb_get_setup</span>:
3919 xcb_connection_t *c;
3920 uint16_t protocol_major_version;
3922 /* you init the connection */
3924 protocol_major_version = xcb_get_setup (c)->protocol_major_version;
3926 /* protocol_major_version contains now the major version of the protocol */
3928 <li class="subtitle"><a name="ProtocolRevision"></a>ProtocolRevision
3930 You get the minor version of the protocol in the
3931 <span class="code">xcb_setup_t</span>
3932 structure, with the function <span class="code">xcb_get_setup</span>:
3935 xcb_connection_t *c;
3936 uint16_t protocol_minor_version;
3938 /* you init the connection */
3940 protocol_minor_version = xcb_get_setup (c)->protocol_minor_version;
3942 /* protocol_minor_version contains now the minor version of the protocol */
3944 <li class="subtitle"><a name="VendorRelease"></a>VendorRelease
3946 You get the number of the release of the server hardware in the
3947 <span class="code">xcb_setup_t</span>
3948 structure, with the function <span class="code">xcb_get_setup</span>:
3951 xcb_connection_t *c;
3952 uint32_t release_number;
3954 /* you init the connection */
3956 release_number = xcb_get_setup (c)->release_number;
3958 /* release_number contains now the number of the release of the server hardware */
3960 <li class="subtitle"><a name="DisplayString"></a>DisplayString
3962 The name of the display is not stored in XCB. You have to
3963 store it by yourself.
3965 <li class="subtitle"><a name="BitmapUnit"></a>BitmapUnit
3967 You get the bitmap scanline unit in the
3968 <span class="code">xcb_setup_t</span>
3969 structure, with the function <span class="code">xcb_get_setup</span>:
3972 xcb_connection_t *c;
3973 uint8_t bitmap_format_scanline_unit;
3975 /* you init the connection */
3977 bitmap_format_scanline_unit = xcb_get_setup (c)->bitmap_format_scanline_unit;
3979 /* bitmap_format_scanline_unit contains now the bitmap scanline unit */
3981 <li class="subtitle"><a name="BitmapBitOrder"></a>BitmapBitOrder
3983 You get the bitmap bit order in the
3984 <span class="code">xcb_setup_t</span>
3985 structure, with the function <span class="code">xcb_get_setup</span>:
3988 xcb_connection_t *c;
3989 uint8_t bitmap_format_bit_order;
3991 /* you init the connection */
3993 bitmap_format_bit_order = xcb_get_setup (c)->bitmap_format_bit_order;
3995 /* bitmap_format_bit_order contains now the bitmap bit order */
3997 <li class="subtitle"><a name="BitmapPad"></a>BitmapPad
3999 You get the bitmap scanline pad in the
4000 <span class="code">xcb_setup_t</span>
4001 structure, with the function <span class="code">xcb_get_setup</span>:
4004 xcb_connection_t *c;
4005 uint8_t bitmap_format_scanline_pad;
4007 /* you init the connection */
4009 bitmap_format_scanline_pad = xcb_get_setup (c)->bitmap_format_scanline_pad;
4011 /* bitmap_format_scanline_pad contains now the bitmap scanline pad */
4013 <li class="subtitle"><a name="ImageByteOrder"></a>ImageByteOrder
4015 You get the image byte order in the
4016 <span class="code">xcb_setup_t</span>
4017 structure, with the function <span class="code">xcb_get_setup</span>:
4020 xcb_connection_t *c;
4021 uint8_t image_byte_order;
4023 /* you init the connection */
4025 image_byte_order = xcb_get_setup (c)->image_byte_order;
4027 /* image_byte_order contains now the image byte order */
4030 <li class="subtitle"><a name="screenofdisplay">ScreenOfDisplay related functions</a>
4032 in Xlib, <span class="code">ScreenOfDisplay</span> returns a
4033 <span class="code">Screen</span> structure that contains
4034 several characteristics of your screen. XCB has a similar
4035 structure (<span class="code">xcb_screen_t</span>),
4036 but the way to obtain it is a bit different. With
4037 Xlib, you just provide the number of the screen and you grab it
4038 from an array. With XCB, you iterate over all the screens to
4039 obtain the one you want. The complexity of this operation is
4040 O(n). So the best is to store this structure if you use
4041 it often. See <a href="#ScreenOfDisplay">screen_of_display</a> just below.
4044 Xlib provides generally two functions to obtain the characteristics
4045 related to the screen. One with the display and the number of
4046 the screen, which calls <span class="code">ScreenOfDisplay</span>,
4047 and the other that uses the <span class="code">Screen</span> structure.
4048 This might be a bit confusing. As mentioned above, with XCB, it
4049 is better to store the <span class="code">xcb_screen_t</span>
4050 structure. Then, you have to read the members of this
4051 structure. That's why the Xlib functions are put by pairs (or
4052 more) as, with XCB, you will use the same code.
4055 <li class="subtitle"><a name="ScreenOfDisplay">ScreenOfDisplay</a>
4057 This function returns the Xlib <span class="code">Screen</span>
4058 structure. With XCB, you iterate over all the screens and
4059 once you get the one you want, you return it:
4061 <pre class="code"><a name="ScreenOfDisplay"></a>
4062 xcb_screen_t *screen_of_display (xcb_connection_t *c,
4065 xcb_screen_iterator_t iter;
4067 iter = xcb_setup_roots_iterator (xcb_get_setup (c));
4068 for (; iter.rem; --screen, xcb_screen_next (&iter))
4076 As mentioned above, you might want to store the value
4077 returned by this function.
4080 All the functions below will use the result of that
4081 function, as they just grab a specific member of the
4082 <span class="code">xcb_screen_t</span> structure.
4084 <li class="subtitle"><a name="DefaultScreenOfDisplay"></a>DefaultScreenOfDisplay
4086 It is the default screen that you obtain when you connect to
4087 the X server. It suffices to call the <a href="#ScreenOfDisplay">screen_of_display</a>
4088 function above with the connection and the number of the
4092 xcb_connection_t *c;
4093 int screen_default_nbr;
4094 xcb_screen_t *default_screen; /* the returned default screen */
4096 /* you pass the name of the display you want to xcb_connect_t */
4098 c = xcb_connect (display_name, &screen_default_nbr);
4099 default_screen = screen_of_display (c, screen_default_nbr);
4101 /* default_screen contains now the default root window, or a NULL window if no screen is found */
4103 <li class="subtitle"><a name="RootWindow">RootWindow / RootWindowOfScreen</a>
4106 xcb_connection_t *c;
4107 xcb_screen_t *screen;
4109 xcb_window_t root_window = { 0 }; /* the returned window */
4111 /* you init the connection and screen_nbr */
4113 screen = screen_of_display (c, screen_nbr);
4115 root_window = screen->root;
4117 /* root_window contains now the root window, or a NULL window if no screen is found */
4119 <li class="subtitle"><a name="DefaultRootWindow">DefaultRootWindow</a>
4121 It is the root window of the default screen. So, you call
4122 <a name="ScreenOfDisplay">ScreenOfDisplay</a> with the
4123 default screen number and you get the
4124 <a href="#RootWindow">root window</a> as above:
4127 xcb_connection_t *c;
4128 xcb_screen_t *screen;
4129 int screen_default_nbr;
4130 xcb_window_t root_window = { 0 }; /* the returned root window */
4132 /* you pass the name of the display you want to xcb_connect_t */
4134 c = xcb_connect (display_name, &screen_default_nbr);
4135 screen = screen_of_display (c, screen_default_nbr);
4137 root_window = screen->root;
4139 /* root_window contains now the default root window, or a NULL window if no screen is found */
4141 <li class="subtitle"><a name="DefaultVisual">DefaultVisual / DefaultVisualOfScreen</a>
4143 While a Visual is, in Xlib, a structure, in XCB, there are
4144 two types: <span class="code">xcb_visualid_t</span>, which is
4145 the Id of the visual, and <span class="code">xcb_visualtype_t</span>,
4146 which corresponds to the Xlib Visual. To get the Id of the
4147 visual of a screen, just get the
4148 <span class="code">root_visual</span>
4149 member of a <span class="code">xcb_screen_t</span>:
4152 xcb_connection_t *c;
4153 xcb_screen_t *screen;
4155 xcb_visualid_t root_visual = { 0 }; /* the returned visual Id */
4157 /* you init the connection and screen_nbr */
4159 screen = screen_of_display (c, screen_nbr);
4161 root_visual = screen->root_visual;
4163 /* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
4166 To get the <span class="code">xcb_visualtype_t</span>
4167 structure, it's a bit less easy. You have to get the
4168 <span class="code">xcb_screen_t</span> structure that you want,
4169 get its <span class="code">root_visual</span> member,
4170 then iterate over the <span class="code">xcb_depth_t</span>s
4171 and the <span class="code">xcb_visualtype_t</span>s, and compare
4172 the <span class="code">xcb_visualid_t</span> of these <span class="code">xcb_visualtype_t</span>s:
4173 with <span class="code">root_visual</span>:
4176 xcb_connection_t *c;
4177 xcb_screen_t *screen;
4179 xcb_visualid_t root_visual = { 0 };
4180 xcb_visualtype_t *visual_type = NULL; /* the returned visual type */
4182 /* you init the connection and screen_nbr */
4184 screen = screen_of_display (c, screen_nbr);
4186 xcb_depth_iterator_t depth_iter;
4188 depth_iter = xcb_screen_allowed_depths_iterator (screen);
4189 for (; depth_iter.rem; xcb_depth_next (&depth_iter)) {
4190 xcb_visualtype_iterator_t visual_iter;
4192 visual_iter = xcb_depth_visuals_iterator (depth_iter.data);
4193 for (; visual_iter.rem; xcb_visualtype_next (&visual_iter)) {
4194 if (screen->root_visual == visual_iter.data->visual_id) {
4195 visual_type = visual_iter.data;
4202 /* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */
4204 <li class="subtitle"><a name="DefaultGC">DefaultGC / DefaultGCOfScreen</a>
4206 This default Graphic Context is just a newly created Graphic
4207 Context, associated to the root window of a
4208 <span class="code">xcb_screen_t</span>,
4209 using the black white pixels of that screen:
4212 xcb_connection_t *c;
4213 xcb_screen_t *screen;
4215 xcb_gcontext_t gc = { 0 }; /* the returned default graphic context */
4217 /* you init the connection and screen_nbr */
4219 screen = screen_of_display (c, screen_nbr);
4221 xcb_drawable_t draw;
4225 gc = xcb_generate_id (c);
4226 draw = screen->root;
4227 mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND;
4228 values[0] = screen->black_pixel;
4229 values[1] = screen->white_pixel;
4230 xcb_create_gc (c, gc, draw, mask, values);
4233 /* gc contains now the default graphic context */
4235 <li class="subtitle"><a name="BlackPixel">BlackPixel / BlackPixelOfScreen</a>
4237 It is the Id of the black pixel, which is in the structure
4238 of an <span class="code">xcb_screen_t</span>.
4241 xcb_connection_t *c;
4242 xcb_screen_t *screen;
4244 uint32_t black_pixel = 0; /* the returned black pixel */
4246 /* you init the connection and screen_nbr */
4248 screen = screen_of_display (c, screen_nbr);
4250 black_pixel = screen->black_pixel;
4252 /* black_pixel contains now the value of the black pixel, or 0 if no screen is found */
4254 <li class="subtitle"><a name="WhitePixel">WhitePixel / WhitePixelOfScreen</a>
4256 It is the Id of the white pixel, which is in the structure
4257 of an <span class="code">xcb_screen_t</span>.
4260 xcb_connection_t *c;
4261 xcb_screen_t *screen;
4263 uint32_t white_pixel = 0; /* the returned white pixel */
4265 /* you init the connection and screen_nbr */
4267 screen = screen_of_display (c, screen_nbr);
4269 white_pixel = screen->white_pixel;
4271 /* white_pixel contains now the value of the white pixel, or 0 if no screen is found */
4273 <li class="subtitle"><a name="DisplayWidth">DisplayWidth / WidthOfScreen</a>
4275 It is the width in pixels of the screen that you want, and
4276 which is in the structure of the corresponding
4277 <span class="code">xcb_screen_t</span>.
4280 xcb_connection_t *c;
4281 xcb_screen_t *screen;
4283 uint32_t width_in_pixels = 0; /* the returned width in pixels */
4285 /* you init the connection and screen_nbr */
4287 screen = screen_of_display (c, screen_nbr);
4289 width_in_pixels = screen->width_in_pixels;
4291 /* width_in_pixels contains now the width in pixels, or 0 if no screen is found */
4293 <li class="subtitle"><a name="DisplayHeight">DisplayHeight / HeightOfScreen</a>
4295 It is the height in pixels of the screen that you want, and
4296 which is in the structure of the corresponding
4297 <span class="code">xcb_screen_t</span>.
4300 xcb_connection_t *c;
4301 xcb_screen_t *screen;
4303 uint32_t height_in_pixels = 0; /* the returned height in pixels */
4305 /* you init the connection and screen_nbr */
4307 screen = screen_of_display (c, screen_nbr);
4309 height_in_pixels = screen->height_in_pixels;
4311 /* height_in_pixels contains now the height in pixels, or 0 if no screen is found */
4313 <li class="subtitle"><a name="DisplayWidthMM">DisplayWidthMM / WidthMMOfScreen</a>
4315 It is the width in millimeters of the screen that you want, and
4316 which is in the structure of the corresponding
4317 <span class="code">xcb_screen_t</span>.
4320 xcb_connection_t *c;
4321 xcb_screen_t *screen;
4323 uint32_t width_in_millimeters = 0; /* the returned width in millimeters */
4325 /* you init the connection and screen_nbr */
4327 screen = screen_of_display (c, screen_nbr);
4329 width_in_millimeters = screen->width_in_millimeters;
4331 /* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */
4333 <li class="subtitle"><a name="DisplayHeightMM">DisplayHeightMM / HeightMMOfScreen</a>
4335 It is the height in millimeters of the screen that you want, and
4336 which is in the structure of the corresponding
4337 <span class="code">xcb_screen_t</span>.
4340 xcb_connection_t *c;
4341 xcb_screen_t *screen;
4343 uint32_t height_in_millimeters = 0; /* the returned height in millimeters */
4345 /* you init the connection and screen_nbr */
4347 screen = screen_of_display (c, screen_nbr);
4349 height_in_millimeters = screen->height_in_millimeters;
4351 /* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */
4353 <li class="subtitle"><a name="DisplayPlanes">DisplayPlanes / DefaultDepth / DefaultDepthOfScreen / PlanesOfScreen</a>
4355 It is the depth (in bits) of the root window of the
4356 screen. You get it from the <span class="code">xcb_screen_t</span> structure.
4359 xcb_connection_t *c;
4360 xcb_screen_t *screen;
4362 uint8_t root_depth = 0; /* the returned depth of the root window */
4364 /* you init the connection and screen_nbr */
4366 screen = screen_of_display (c, screen_nbr);
4368 root_depth = screen->root_depth;
4370 /* root_depth contains now the depth of the root window, or 0 if no screen is found */
4372 <li class="subtitle"><a name="DefaultColormap">DefaultColormap / DefaultColormapOfScreen</a>
4374 This is the default colormap of the screen (and not the
4375 (default) colormap of the default screen !). As usual, you
4376 get it from the <span class="code">xcb_screen_t</span> structure:
4379 xcb_connection_t *c;
4380 xcb_screen_t *screen;
4382 xcb_colormap_t default_colormap = { 0 }; /* the returned default colormap */
4384 /* you init the connection and screen_nbr */
4386 screen = screen_of_display (c, screen_nbr);
4388 default_colormap = screen->default_colormap;
4390 /* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */
4392 <li class="subtitle"><a name="MinCmapsOfScreen"></a>MinCmapsOfScreen
4394 You get the minimum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4397 xcb_connection_t *c;
4398 xcb_screen_t *screen;
4400 uint16_t min_installed_maps = 0; /* the returned minimum installed colormaps */
4402 /* you init the connection and screen_nbr */
4404 screen = screen_of_display (c, screen_nbr);
4406 min_installed_maps = screen->min_installed_maps;
4408 /* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */
4410 <li class="subtitle"><a name="MaxCmapsOfScreen"></a>MaxCmapsOfScreen
4412 You get the maximum installed colormaps in the <span class="code">xcb_screen_t</span> structure:
4415 xcb_connection_t *c;
4416 xcb_screen_t *screen;
4418 uint16_t max_installed_maps = 0; /* the returned maximum installed colormaps */
4420 /* you init the connection and screen_nbr */
4422 screen = screen_of_display (c, screen_nbr);
4424 max_installed_maps = screen->max_installed_maps;
4426 /* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */
4428 <li class="subtitle"><a name="DoesSaveUnders"></a>DoesSaveUnders
4430 You know if <span class="code">save_unders</span> is set,
4431 by looking in the <span class="code">xcb_screen_t</span> structure:
4434 xcb_connection_t *c;
4435 xcb_screen_t *screen;
4437 uint8_t save_unders = 0; /* the returned value of save_unders */
4439 /* you init the connection and screen_nbr */
4441 screen = screen_of_display (c, screen_nbr);
4443 save_unders = screen->save_unders;
4445 /* save_unders contains now the value of save_unders, or FALSE if no screen is found */
4447 <li class="subtitle"><a name="DoesBackingStore"></a>DoesBackingStore
4449 You know the value of <span class="code">backing_stores</span>,
4450 by looking in the <span class="code">xcb_screen_t</span> structure:
4453 xcb_connection_t *c;
4454 xcb_screen_t *screen;
4456 uint8_t backing_stores = 0; /* the returned value of backing_stores */
4458 /* you init the connection and screen_nbr */
4460 screen = screen_of_display (c, screen_nbr);
4462 backing_stores = screen->backing_stores;
4464 /* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */
4466 <li class="subtitle"><a name="EventMaskOfScreen"></a>EventMaskOfScreen
4468 To get the current input masks,
4469 you look in the <span class="code">xcb_screen_t</span> structure:
4472 xcb_connection_t *c;
4473 xcb_screen_t *screen;
4475 uint32_t current_input_masks = 0; /* the returned value of current input masks */
4477 /* you init the connection and screen_nbr */
4479 screen = screen_of_display (c, screen_nbr);
4481 current_input_masks = screen->current_input_masks;
4483 /* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
4486 <li class="subtitle"><a name="misc">Miscellaneous macros</a>
4488 <li class="subtitle"><a name="DisplayOfScreen"></a>DisplayOfScreen
4490 in Xlib, the <span class="code">Screen</span> structure
4491 stores its associated <span class="code">Display</span>
4492 structure. This is not the case in the X Window protocol,
4493 hence, it's also not the case in XCB. So you have to store
4496 <li class="subtitle"><a name="DisplayCells"></a>DisplayCells / CellsOfScreen
4498 To get the colormap entries,
4499 you look in the <span class="code">xcb_visualtype_t</span>
4500 structure, that you grab like <a class="subsection" href="#DefaultVisual">here</a>:
4503 xcb_connection_t *c;
4504 xcb_visualtype_t *visual_type;
4505 uint16_t colormap_entries = 0; /* the returned value of the colormap entries */
4507 /* you init the connection and visual_type */
4510 colormap_entries = visual_type->colormap_entries;
4512 /* colormap_entries contains now the value of the colormap entries, or FALSE if no screen is found */
projects / free-sw / xcb / libxcb / blob