X-Git-Url: http://git.demorecorder.com/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=doc%2Ftutorial%2Findex.html;h=c5404263f76764e66f28adc74ad0cbd3618268d6;hb=f896ae8c53e99f39b347f9f0ac2b4a8cc12cad6f;hp=62110a6fedada0a50e379698639b5a861ef2b2cb;hpb=6e4745bbd0c924d846550496a072b0f2b0d4482c;p=free-sw%2Fxcb%2Flibxcb diff --git a/doc/tutorial/index.html b/doc/tutorial/index.html old mode 100755 new mode 100644 index 62110a6..c540426 --- a/doc/tutorial/index.html +++ b/doc/tutorial/index.html @@ -5,7 +5,8 @@
This tutorial is based on the Xlib Tutorial - written by Guy Keren. The + written by Guy Keren. The author allowed me to take some parts of his text, mainly the text which deals with the X Windows generality.
- This tutorial is intended to people who want to start to program + This tutorial is intended for people who want to start to program with the XCB library. keep in mind that XCB, like the Xlib @@ -174,8 +178,9 @@ level GUI toolkit like Motif, LessTiff, GTK, - QT or - EWL, or use + QT, + EWL, + ETK, or use Cairo. However, we need to start somewhere. More than this, knowing how things @@ -183,47 +188,47 @@
After reading this tutorial, one should be able to write very - simple graphical programs, but not programs with descent user + simple graphical programs, but not programs with decent user interfaces. For such programs, one of the previously mentioned - library should be used. + libraries should be used.
But what is XCB? Xlib has been - the standard C binding for the X + the standard C binding for the X Window System protocol for many years now. It is an excellent piece of work, but there are applications for which it - is not ideal, for example + is not ideal, for example: +
For these reasons, among others, XCB, an X C binding, has been designed to solve the above problems and thus provide a base for +
The X Window System was developed with one major goal: flexibility. The idea was that the way things look is one thing, @@ -237,14 +242,14 @@
This model is the complete opposite of what is used to when - dealing with clients and servers. In our case, the user seats + dealing with clients and servers. In our case, the user sits near the machine controlled by the server, while the client might be running on a remote machine. The server controls the screens, mouse and keyboard. A client may connect to the server, request that it draws a window (or several windows), and ask the server to send it any input the user sends to these windows. Thus, several clients may connect to a single X server - (one might be running an mail software, one running a WWW + (one might be running mail software, one running a WWW browser, etc). When input is sent by the user to some window, the server sends a message to the client controlling this window for processing. The client decides what to do with this input, @@ -261,7 +266,7 @@ using shared memory, or using Unix domain sockets (a method for creating a logical channel on a Unix system between two processes).
-Unlike conventional computer programs, that carry some serial nature, a GUI program usually uses an asynchronous programming @@ -286,25 +291,25 @@
So the way a GUI program looks is something like that: +
- XCB has been created to eliminate the needs of + XCB has been created to eliminate the need for programs to actually implement the X protocol layer. This library gives a program a very low-level access to any X server. Since the protocol is standardized, a client using any @@ -313,22 +318,23 @@ the basic XCB notions. They will be detailed later.
- The major notion of using XCB is the X Connection. This is a - structure representing the connection we have open with a - given X server. It hides a queue of messages coming from the - server, and a queue of pending requests that our client - intends to send to the server. In XCB, this structure is named - 'XCBConnection'. When we open a connection to an X server, the - library returns a pointer to such a structure. Later, we - supply this pointer to any XCB function that should send - messages to the X server or receive messages from this server. -
++ The major notion of using XCB is the X Connection. This is a + structure representing the connection we have open with a + given X server. It hides a queue of messages coming from the + server, and a queue of pending requests that our client + intends to send to the server. In XCB, this structure is named + 'xcb_connection_t'. It is analogous to the Xlib Display. + When we open a connection to an X server, the + library returns a pointer to such a structure. Later, we + supply this pointer to any XCB function that should send + messages to the X server or receive messages from this server. +
- To ask informations to the X server, we have to make a request + replies: the Xlib killers +
+ To ask for information from the X server, we have to make a request and ask for a reply. With Xlib, these two tasks are automatically done: Xlib locks the system, sends a request, waits for a reply from the X server and unlocks. This is @@ -339,14 +345,14 @@ requests/replies with Xlib, with a round-trip latency T_round_trip that is 5 times long as the time required to write or read a request/reply (T_write/T_read): -
-+ +W-----RW-----RW-----RW-----R
The total time is N * (T_write + T_round_trip + T_read). @@ -362,7 +368,7 @@ when we need them. Here is the time-line for 4 requests/replies when we use this property of XCB:
-+-WWWW--RRRR@@ -382,7 +388,7 @@ #include <string.h> #include <sys/time.h> -#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> #include <X11/Xlib.h> @@ -390,8 +396,8 @@ double get_time(void) { struct timeval timev; - - gettimeofday(&timev, NULL); + + gettimeofday(&timev, NULL); return (double)timev.tv_sec + (((double)timev.tv_usec) / 1000000); } @@ -399,46 +405,45 @@ get_time(void) int main () { - XCBConnection *c; - XCBATOM *atoms; - XCBInternAtomCookie *cs; - char **names; - int count; - int i; - double start; - double end; - double diff; + xcb_connection_t *c; + xcb_atom_t *atoms; + xcb_intern_atom_cookie_t *cs; + char **names; + int count; + int i; + double start; + double end; + double diff; /* Xlib */ Display *disp; Atom *atoms_x; double diff_x; - c = XCBConnectBasic (); + c = xcb_connect (NULL, NULL); count = 500; - atoms = (XCBATOM *)malloc (count * sizeof (atoms)); + atoms = (xcb_atom_t *)malloc (count * sizeof (atoms)); names = (char **)malloc (count * sizeof (char *)); /* init names */ - for (i = 0; i < count; ++i) - { - char buf[100]; + for (i = 0; i < count; ++i) { + char buf[100]; - sprintf (buf, "NAME%d", i); - names[i] = strdup (buf); - } + sprintf (buf, "NAME%d", i); + names[i] = strdup (buf); + } /* bad use */ start = get_time (); for (i = 0; i < count; ++i) - atoms[i] = XCBInternAtomReply (c, - XCBInternAtom (c, - 0, - strlen(names[i]), - names[i]), - NULL)->atom; + atoms[i] = xcb_intern_atom_reply (c, + xcb_intern_atom (c, + 0, + strlen(names[i]), + names[i]), + NULL)->atom; end = get_time (); diff = end - start; @@ -447,19 +452,18 @@ main () /* good use */ start = get_time (); - cs = (XCBInternAtomCookie *) malloc (count * sizeof(XCBInternAtomCookie)); + cs = (xcb_intern_atom_cookie_t *) malloc (count * sizeof(xcb_intern_atom_cookie_t)); for(i = 0; i < count; ++i) - cs[i] = XCBInternAtom (c, 0, strlen(names[i]), names[i]); + cs[i] = xcb_intern_atom (c, 0, strlen(names[i]), names[i]); - for(i = 0; i < count; ++i) - { - XCBInternAtomRep *r; + for(i = 0; i < count; ++i) { + xcb_intern_atom_reply_t *r; - r = XCBInternAtomReply(c, cs[i], 0); - if(r) - atoms[i] = r->atom; - free(r); - } + r = xcb_intern_atom_reply(c, cs[i], 0); + if(r) + atoms[i] = r->atom; + free(r); + } end = get_time (); printf ("good use time : %f\n", end - start); @@ -468,13 +472,11 @@ main () /* free var */ for (i = 0; i < count; ++i) - { - free (names[i]); - } + free (names[i]); free (atoms); free (cs); - XCBDisconnect (c); + xcb_disconnect (c); /* Xlib */ disp = XOpenDisplay (getenv("DISPLAY")); @@ -495,84 +497,91 @@ main () free (names); XCloseDisplay (disp); - - return 1; + + return 0; }
- When we perform various drawing operations (graphics, text, - etc), we may specify various options for controlling how the - data will be drawn (what foreground and background colors to - use, how line edges will be connected, what font to use when - drawing some text, etc). In order to avoid the need to supply - hundreds of parameters to each drawing function, a graphical - context structure is used. We set the various drawing options - in this structure, and then we pass a pointer to this - structure to any drawing routines. This is rather handy, as we - often need to perform several drawing requests with the same - options. Thus, we would initialize a graphical context, set - the desired options, and pass this structure to all drawing - functions. -
++ When we perform various drawing operations (graphics, text, + etc), we may specify various options for controlling how the + data will be drawn (what foreground and background colors to + use, how line edges will be connected, what font to use when + drawing some text, etc). In order to avoid the need to supply + hundreds of parameters to each drawing function, a graphical + context structure is used. We set the various drawing options + in this structure, and then we pass a pointer to this + structure to any drawing routines. This is rather handy, as we + often need to perform several drawing requests with the same + options. Thus, we would initialize a graphical context, set + the desired options, and pass this structure to all drawing + functions. +
Note that graphic contexts have no client-side structure in XCB, they're just XIDs. Xlib has a client-side structure because it caches the GC contents so it can avoid making redundant requests, but of course XCB doesn't do that.
-- A structure is used to pass events received from the X - server. XCB supports exactly the events specified in the - protocol (33 events). This structure contains the type - of event received, as well as the data associated with the - event (e.g. position on the screen where the event was - generated, mouse button associated with the event, region of - the screen associated with a "redraw" event, etc). The way to - read the event's data epends on the event type. -
++ A structure is used to pass events received from the X + server. XCB supports exactly the events specified in the + protocol (33 events). This structure contains the type + of event received (including a bit for whether it came + from the server or another client), as well as the data associated with the + event (e.g. position on the screen where the event was + generated, mouse button associated with the event, region of + the screen associated with a "redraw" event, etc). The way to + read the event's data depends on the event type. +
- To build XCB from source, you need to have installed at - least: -
- -- You have to checkout in CVS the following modules: -
-- Note that Xproto and xcb-proto exist only to install header - files, so typing 'make' or 'make all' will produce the message - "Nothing to be done for 'all'". That's normal. -
-- Compiling XCB-based programs requires linking them with the XCB - library. This is easily done thanks to pkgconfig: -
-+
+ TODO: These instructions are out of date. + Just reference the main XCB page + so we don't have to maintain these instructions in more than + one place. +
++ To build XCB from source, you need to have installed at + least: +
++ You have to checkout in the git repository the following modules: +
++ Note that xcb-proto exists only to install header + files, so typing 'make' or 'make all' will produce the message + "Nothing to be done for 'all'". That's normal. +
++ Compiling XCB-based programs requires linking them with the XCB + library. This is easily done thanks to pkgconfig: +
+gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb`
An X program first needs to open the connection to the X server. There is a function that opens a connection. It requires @@ -580,8 +589,8 @@ gcc -Wall prog.c -o prog `pkg-config --cflags --libs xcb` will be the one in the environment variable DISPLAY.
-XCBConnection *XCBConnect (const char *displayname, - int *screenp); +xcb_connection_t *xcb_connect (const char *displayname, + int *screenp);
The second parameter returns the screen number used for the @@ -589,87 +598,86 @@ XCBConnection *XCBConnect (const char *displayname, and is opaque. Here is how the connection can be opened:
-#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> -int -main (int argc, char *argv[]) +int +main () { - XCBConnection *c; - - /* Open the connection to the X server. use the DISPLAY environment variable as the default display name */ - c = XCBConnect (NULL, NULL); + xcb_connection_t *c; - return 1; + /* Open the connection to the X server. Use the DISPLAY environment variable as the default display name */ + c = xcb_connect (NULL, NULL); + + return 0; }
To close a connection, it suffices to use:
-void XCBDisconnect (XCBConnection *c); +void xcb_disconnect (xcb_connection_t *c);
-
-- Once we opened a connection to an X server, we should check some - basic informations about it: what screens it has, what is the + Once we have opened a connection to an X server, we should check some + basic information about it: what screens it has, what is the size (width and height) of the screen, how many colors it supports (black and white ? grey scale ?, 256 colors ? more ?), - and so on. We get such informations from the XCBSCREEN + and so on. We get such information from the xcb_screen_t structure:
typedef struct { - XCBWINDOW root; - XCBCOLORMAP default_colormap; - CARD32 white_pixel; - CARD32 black_pixel; - CARD32 current_input_masks; - CARD16 width_in_pixels; - CARD16 height_in_pixels; - CARD16 width_in_millimeters; - CARD16 height_in_millimeters; - CARD16 min_installed_maps; - CARD16 max_installed_maps; - XCBVISUALID root_visual; - BYTE backing_stores; - BOOL save_unders; - CARD8 root_depth; - CARD8 allowed_depths_len; -} XCBSCREEN; + xcb_window_t root; + xcb_colormap_t default_colormap; + uint32_t white_pixel; + uint32_t black_pixel; + uint32_t current_input_masks; + uint16_t width_in_pixels; + uint16_t height_in_pixels; + uint16_t width_in_millimeters; + uint16_t height_in_millimeters; + uint16_t min_installed_maps; + uint16_t max_installed_maps; + xcb_visualid_t root_visual; + uint8_t backing_stores; + uint8_t save_unders; + uint8_t root_depth; + uint8_t allowed_depths_len; +} xcb_screen_t;
We could retrieve the first screen of the connection by using the following function:
-XCBSCREENIter XCBConnSetupSuccessRepRootsIter (XCBConnSetupSuccessRep *R); +xcb_screen_iterator_t xcb_setup_roots_iterator (xcb_setup_t *R);
Here is a small program that shows how to use this function: @@ -677,165 +685,164 @@ XCBSCREENIter XCBConnSetupSuccessRepRootsIter (XCBConnSetupSuccessRep *R);
#include <stdio.h> -#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - int screen_nbr; - XCBSCREENIter iter; - + xcb_connection_t *c; + xcb_screen_t *screen; + int screen_nbr; + xcb_screen_iterator_t iter; + /* Open the connection to the X server. Use the DISPLAY environment variable */ - c = XCBConnect (NULL, &screen_nbr); - + c = xcb_connect (NULL, &screen_nbr); + /* Get the screen #screen_nbr */ - iter = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)); - for (; iter.rem; --screen_nbr, XCBSCREENNext (&iter)) - if (screen_nbr == 0) - { - screen = iter.data; - break; - } + iter = xcb_setup_roots_iterator (xcb_get_setup (c)); + for (; iter.rem; --screen_nbr, xcb_screen_next (&iter)) + if (screen_nbr == 0) { + screen = iter.data; + break; + } printf ("\n"); - printf ("Informations of screen %ld:\n", screen->root.xid); + printf ("Informations of screen %ld:\n", screen->root); printf (" width.........: %d\n", screen->width_in_pixels); printf (" height........: %d\n", screen->height_in_pixels); printf (" white pixel...: %ld\n", screen->white_pixel); printf (" black pixel...: %ld\n", screen->black_pixel); printf ("\n"); - return 1; + return 0; }-
- After we got some basic informations about our screen, we can + After we got some basic information about our screen, we can create our first window. In the X Window System, a window is characterized by an Id. So, in XCB, a window is of type:
-typedef struct { - CARD32 xid; -} XCBWINDOW; +typedef uint32_t xcb_window_t;
We first ask for a new Id for our window, with this function:
-XCBWINDOW XCBWINDOWNew(XCBConnection *c); +xcb_window_t xcb_generate_id(xcb_connection_t *c);
Then, XCB supplies the following function to create new windows:
-XCBVoidCookie XCBCreateWindow (XCBConnection *c, /* Pointer to the XCBConnection structure */ - CARD8 depth, /* Depth of the screen */ - XCBWINDOW wid, /* Id of the window */ - XCBWINDOW parent, /* Id of an existing window that should be the parent of the new window */ - INT16 x, /* X position of the top-left corner of the window (in pixels) */ - INT16 y, /* Y position of the top-left corner of the window (in pixels) */ - CARD16 width, /* Width of the window (in pixels) */ - CARD16 height, /* Height of the window (in pixels) */ - CARD16 border_width, /* Width of the window's border (in pixels) */ - CARD16 _class, - XCBVISUALID visual, - CARD32 value_mask, - const CARD32 *value_list); +xcb_void_cookie_t xcb_create_window (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */ + uint8_t depth, /* Depth of the screen */ + xcb_window_t wid, /* Id of the window */ + xcb_window_t parent, /* Id of an existing window that should be the parent of the new window */ + int16_t x, /* X position of the top-left corner of the window (in pixels) */ + int16_t y, /* Y position of the top-left corner of the window (in pixels) */ + uint16_t width, /* Width of the window (in pixels) */ + uint16_t height, /* Height of the window (in pixels) */ + uint16_t border_width, /* Width of the window's border (in pixels) */ + uint16_t _class, + xcb_visualid_t visual, + uint32_t value_mask, + const uint32_t *value_list);
The fact that we created the window does not mean that it will be drawn on screen. By default, newly created windows are not mapped on the screen (they are invisible). In order to make our - window visible, we use the function XCBMapWindow(), whose + window visible, we use the function xcb_map_window(), whose prototype is
-XCBVoidCookie XCBMapWindow (XCBConnection *c, XCBWINDOW window); +xcb_void_cookie_t xcb_map_window (xcb_connection_t *c, + xcb_window_t window);
Finally, here is a small program to create a window of size 150x150 pixels, positioned at the top-left corner of the screen:
-#include <unistd.h> +#include <unistd.h> /* pause() */ -#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBDRAWABLE win; - + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_window_t win; + /* Open the connection to the X server */ - c = XCBConnect (NULL, NULL); - + c = xcb_connect (NULL, NULL); + /* Get the first screen */ - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; /* Ask for our window's Id */ - win.window = XCBWINDOWNew(c); + win = xcb_generate_id(c); /* Create the window */ - XCBCreateWindow (c, /* Connection */ - 0, /* depth */ - win.window, /* window Id */ - screen->root, /* parent window */ - 0, 0, /* x, y */ - 150, 150, /* width, height */ - 10, /* border_width */ - InputOutput, /* class */ - screen->root_visual, /* visual */ - 0, NULL); /* masks, not used yet */ + xcb_create_window (c, /* Connection */ + XCB_COPY_FROM_PARENT, /* depth (same as root)*/ + win, /* window Id */ + screen->root, /* parent window */ + 0, 0, /* x, y */ + 150, 150, /* width, height */ + 10, /* border_width */ + XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */ + screen->root_visual, /* visual */ + 0, NULL); /* masks, not used yet */ /* Map the window on the screen */ - XCBMapWindow (c, win.window); + xcb_map_window (c, win); + + /* Make sure commands are sent before we pause, so window is shown */ + xcb_flush (c); - XCBSync (c, 0); - - pause (); + pause (); /* hold client until Ctrl-C */ - return 1; + return 0; }
- In this code, you see one more function - XCBSync(), not explained + In this code, you see one more function - xcb_flush(), not explained yet. It is used to flush all the pending requests. More precisely, there are 2 functions that do such things. The first - one is XCBFlush(): + one is xcb_flush():
-int XCBFlush (XCBConnection *c); +int xcb_flush (xcb_connection_t *c);
This function flushes all pending requests to the X server (much like the fflush() function is used to - flush standard output). The second function is - XCBSync(): + flush standard output). The second function is + xcb_aux_sync():
-int XCBSync(XCBConnection *c, XCBGenericError **e); +int xcb_aux_sync (xcb_connection_t *c);
This functions also flushes all pending requests to the X server, and then waits until the X server finishing processing these requests. In a normal program, this will not be necessary (we'll see why when we get to write a normal X program), but for - now, we put it there. + now, we put it there.
- The window that is created by the above code has a default - background (gray). This one can be set to a specific color, + The window that is created by the above code has a non defined + background. This one can be set to a specific color, thanks to the two last parameters of - XCBCreateWindow(), which are not + xcb_create_window(), which are not described yet. See the subsections Configuring a window or Registering for event types using event masks - for exemples on how to use these parameters. In addition, as no + for examples on how to use these parameters. In addition, as no events are handled, you have to make a Ctrl-C to interrupt the program.
@@ -845,22 +852,22 @@ int XCBSync(XCBConnection *c, XCBGenericError **e);Drawing in a window can be done using various graphical functions (drawing pixels, lines, rectangles, etc). In order to @@ -869,512 +876,489 @@ int XCBSync(XCBConnection *c, XCBGenericError **e); with, etc). This is done using a graphical context.
- As we said, a graphical context defines several attributes to - be used with the various drawing functions. For this, we - define a graphical context. We can use more than one graphical - context with a single window, in order to draw in multiple - styles (different colors, different line widths, etc). In XCB, - a Graphics Context is, as a window, characterized by an Id: + As we said, a graphical context defines several attributes to + be used with the various drawing functions. For this, we + define a graphical context. We can use more than one graphical + context with a single window, in order to draw in multiple + styles (different colors, different line widths, etc). In XCB, + a Graphics Context is, as a window, characterized by an Id:
--typedef struct { - CARD32 xid; -} XCBGCONTEXT; ++typedef uint32_t xcb_gcontext_t;We first ask the X server to attribute an Id to our graphic - context with this function: + context with this function:
--XCBGCONTEXT XCBGCONTEXTNew (XCBConnection *c); ++xcb_gcontext_t xcb_generate_id (xcb_connection_t *c);Then, we set the attributes of the graphic context with this function:
--XCBVoidCookie XCBCreateGC (XCBConnection *c, - XCBGCONTEXT cid, - XCBDRAWABLE drawable, - CARD32 value_mask, - const CARD32 *value_list); ++xcb_void_cookie_t xcb_create_gc (xcb_connection_t *c, + xcb_gcontext_t cid, + xcb_drawable_t drawable, + uint32_t value_mask, + const uint32_t *value_list);- We give now an example on how to allocate a graphic context - that specifies that each drawing functions that use it will - draw in foreground with a black color. -
+ We give now an example on how to allocate a graphic context + that specifies that each drawing function that uses it will + draw in foreground with a black color. +-#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBDRAWABLE win; - XCBGCONTEXT black; - CARD32 mask; - CARD32 value[1]; - + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_drawable_t win; + xcb_gcontext_t black; + uint32_t mask; + uint32_t value[1]; + /* Open the connection to the X server and get the first screen */ - c = XCBConnect (NULL, NULL); - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + c = xcb_connect (NULL, NULL); + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; /* Create a black graphic context for drawing in the foreground */ - win.window = screen->root; - black = XCBGCONTEXTNew (c); - mask = GCForeground; + win = screen->root; + black = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND; value[0] = screen->black_pixel; - XCBCreateGC (c, black, win, mask, value); + xcb_create_gc (c, black, win, mask, value); - return 1; + return 0; }Note should be taken regarding the role of "value_mask" and - "value_list" in the prototype of XCBCreateGC(). Since a - graphic context has many attributes, and since we often just - want to define a few of them, we need to be able to tell the - XCBCreateGC() which attributes we - want to set. This is what the "value_mask" parameter is - for. We then use the "value_list" parameter to specify actual - values for the attribute we defined in "value_mask". Thus, for - each constant used in "value_list", we will use the matching - constant in "value_mask". In this case, we define a graphic - context with one attribute: when drawing (a point, a line, - etc), the foreground color will be black. The rest of the - attributes of this graphic context will be set to their - default values. -
-- See the next Subsection for more details. -
+ "value_list" in the prototype of xcb_create_gc(). Since a + graphic context has many attributes, and since we often just + want to define a few of them, we need to be able to tell the + xcb_create_gc() which attributes we + want to set. This is what the "value_mask" parameter is + for. We then use the "value_list" parameter to specify actual + values for the attribute we defined in "value_mask". Thus, for + each constant used in "value_list", we will use the matching + constant in "value_mask". In this case, we define a graphic + context with one attribute: when drawing (a point, a line, + etc), the foreground color will be black. The rest of the + attributes of this graphic context will be set to their + default values. + ++ See the next Subsection for more details. +
+- Comparison Xlib/XCB -----
-- XCreateGC ()
--+ Comparison Xlib/XCB +-
-- XCBGCONTEXTNew ()
-- XCBCreateGC ()
-+++
+- XCreateGC () +
+- -+
+- xcb_generate_id () +
- xcb_create_gc () +
- Once we have allocated a Graphic Context, we may need to - change its attributes (for example, changing the foreground - color we use to draw a line, or changing the attributes of the - font we use to display strings. See Subsections Drawing with a - color and Assigning a Font to a Graphic Context). This is done - by using this function: -
--XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */ - XCBGCONTEXT gc, /* The Graphic Context */ - CARD32 value_mask, /* Components of the Graphic Context that have to be set */ - const CARD32 *value_list); /* Value as specified by value_mask */ --
- The value_mask parameter could take - these values: -
-- It is possible to set several attributes at the same - time (for example setting the attributes of a font and the - color which will be used to display a string), by OR'ing these - values in value_mask. Then - value_list has to be an array which - lists the value for the respective attributes. See Subsection - Drawing with a color to have an example. -
-- TODO: set the links of the 3 subsections, once they will - be written :) -
-- TODO: give an example which sets several attributes. -
-- After we have created a Graphic Context, we can draw on a - window using this Graphic Context, with a set of XCB - functions, collectively called "drawing primitive". Let see - how they are used. -
-- To draw a point, or several points, we use -
--XCBVoidCookie XCBPolyPoint (XCBConnection *c, /* The connection to the X server */ - BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */ - XCBDRAWABLE drawable, /* The drawable on which we want to draw the point(s) */ - XCBGCONTEXT gc, /* The Graphic Context we use to draw the point(s) */ - CARD32 points_len, /* The number of points */ - const XCBPOINT *points); /* An array of points */ --
- The coordinate_mode parameter - specifies the coordinate mode. Available values are -
-- The XCBPOINT type is just a - structure with two fields (the coordinates of the point): -
-+
+
+ Once we have allocated a Graphic Context, we may need to + change its attributes (for example, changing the foreground + color we use to draw a line, or changing the attributes of the + font we use to display strings. See Subsections Drawing with a + color and + Assigning a Font to a Graphic Context). + This is done by using this function: +
++xcb_void_cookie_t xcb_change_gc (xcb_connection_t *c, /* The XCB Connection */ + xcb_gcontext_t gc, /* The Graphic Context */ + uint32_t value_mask, /* Components of the Graphic Context that have to be set */ + const uint32_t *value_list); /* Value as specified by value_mask */ ++
+ The value_mask parameter could take + any combination of these masks from the xcb_gc_t enumeration: +
++ It is possible to set several attributes at the same + time (for example setting the attributes of a font and the + color which will be used to display a string), by OR'ing these + values in value_mask. Then + value_list has to be an array which + lists the value for the respective attributes. These values + must be in the same order as masks listed above. See Subsection + Drawing with a color to have an example. +
++ TODO: set the links of the 3 subsections, once they will + be written :) +
++ TODO: give an example which sets several attributes. +
++ After we have created a Graphic Context, we can draw on a + window using this Graphic Context, with a set of XCB + functions, collectively called "drawing primitives". Let see + how they are used. +
++ To draw a point, or several points, we use +
++xcb_void_cookie_t xcb_poly_point (xcb_connection_t *c, /* The connection to the X server */ + uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */ + xcb_drawable_t drawable, /* The drawable on which we want to draw the point(s) */ + xcb_gcontext_t gc, /* The Graphic Context we use to draw the point(s) */ + uint32_t points_len, /* The number of points */ + const xcb_point_t *points); /* An array of points */ ++
+ The coordinate_mode parameter + specifies the coordinate mode. Available values are +
++ If XCB_COORD_MODE_PREVIOUS is used, then all points but the first one + are relative to the immediately previous point. +
++ The xcb_point_t type is just a + structure with two fields (the coordinates of the point): +
+typedef struct { - INT16 x; - INT16 y; -} XCBPOINT; --
- You could see an example in xpoints.c. TODO Set the link. -
-- To draw a line, or a polygonal line, we use -
--XCBVoidCookie XCBPolyLine (XCBConnection *c, /* The connection to the X server */ - BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */ - XCBDRAWABLE drawable, /* The drawable on which we want to draw the line(s) */ - XCBGCONTEXT gc, /* The Graphic Context we use to draw the line(s) */ - CARD32 points_len, /* The number of points in the polygonal line */ - const XCBPOINT *points); /* An array of points */ --
- This function will draw the line between the first and the - second points, then the line between the second and the third - points, and so on. -
-- To draw a segment, or several segments, we use -
--XCBVoidCookie XCBPolySegment (XCBConnection *c, /* The connection to the X server */ - XCBDRAWABLE drawable, /* The drawable on which we want to draw the segment(s) */ - XCBGCONTEXT gc, /* The Graphic Context we use to draw the segment(s) */ - CARD32 segments_len, /* The number of segments */ - const XCBSEGMENT *segments); /* An array of segments */ --
- The XCBSEGMENT type is just a - structure with four fields (the coordinates of the two points - that define the segment): -
-+ int16_t x; + int16_t y; +} xcb_point_t; ++
+ You could see an example in xpoints.c. TODO Set the link. +
++ To draw a line, or a polygonal line, we use +
++xcb_void_cookie_t xcb_poly_line (xcb_connection_t *c, /* The connection to the X server */ + uint8_t coordinate_mode, /* Coordinate mode, usually set to XCB_COORD_MODE_ORIGIN */ + xcb_drawable_t drawable, /* The drawable on which we want to draw the line(s) */ + xcb_gcontext_t gc, /* The Graphic Context we use to draw the line(s) */ + uint32_t points_len, /* The number of points in the polygonal line */ + const xcb_point_t *points); /* An array of points */ ++
+ This function will draw the line between the first and the + second points, then the line between the second and the third + points, and so on. +
++ To draw a segment, or several segments, we use +
++xcb_void_cookie_t xcb_poly_segment (xcb_connection_t *c, /* The connection to the X server */ + xcb_drawable_t drawable, /* The drawable on which we want to draw the segment(s) */ + xcb_gcontext_t gc, /* The Graphic Context we use to draw the segment(s) */ + uint32_t segments_len, /* The number of segments */ + const xcb_segment_t *segments); /* An array of segments */ ++
+ The xcb_segment_t type is just a + structure with four fields (the coordinates of the two points + that define the segment): +
+typedef struct { - INT16 x1; - INT16 y1; - INT16 x2; - INT16 y2; -} XCBSEGMENT; --
- To draw a rectangle, or several rectangles, we use -
--XCBVoidCookie XCBPolyRectangle (XCBConnection *c, /* The connection to the X server */ - XCBDRAWABLE drawable, /* The drawable on which we want to draw the rectangle(s) */ - XCBGCONTEXT gc, /* The Graphic Context we use to draw the rectangle(s) */ - CARD32 rectangles_len, /* The number of rectangles */ - const XCBRECTANGLE *rectangles); /* An array of rectangles */ --
- The XCBRECTANGLE type is just a - structure with four fields (the coordinates of the top-left - corner of the rectangle, and its width and height): -
-+ int16_t x1; + int16_t y1; + int16_t x2; + int16_t y2; +} xcb_segment_t; ++
+ To draw a rectangle, or several rectangles, we use +
++xcb_void_cookie_t xcb_poly_rectangle (xcb_connection_t *c, /* The connection to the X server */ + xcb_drawable_t drawable, /* The drawable on which we want to draw the rectangle(s) */ + xcb_gcontext_t gc, /* The Graphic Context we use to draw the rectangle(s) */ + uint32_t rectangles_len, /* The number of rectangles */ + const xcb_rectangle_t *rectangles); /* An array of rectangles */ ++
+ The xcb_rectangle_t type is just a + structure with four fields (the coordinates of the top-left + corner of the rectangle, and its width and height): +
+typedef struct { - INT16 x; - INT16 y; - CARD16 width; - CARD16 height; -} XCBRECTANGLE; --
- TODO: there's no coordinate_mode. Is it normal ? -
-- To draw an elliptical arc, or several elliptical arcs, we use -
--XCBVoidCookie XCBPolyArc (XCBConnection *c, /* The connection to the X server */ - XCBDRAWABLE drawable, /* The drawable on which we want to draw the arc(s) */ - XCBGCONTEXT gc, /* The Graphic Context we use to draw the arc(s) */ - CARD32 arcs_len, /* The number of arcs */ - const XCBARC *arcs); /* An array of arcs */ --
- The XCBARC type is a structure with - six fields: -
-+ int16_t x; + int16_t y; + uint16_t width; + uint16_t height; +} xcb_rectangle_t; ++ + +
+ To draw an elliptical arc, or several elliptical arcs, we use +
++xcb_void_cookie_t xcb_poly_arc (xcb_connection_t *c, /* The connection to the X server */ + xcb_drawable_t drawable, /* The drawable on which we want to draw the arc(s) */ + xcb_gcontext_t gc, /* The Graphic Context we use to draw the arc(s) */ + uint32_t arcs_len, /* The number of arcs */ + const xcb_arc_t *arcs); /* An array of arcs */ ++
+ The xcb_arc_t type is a structure with + six fields: +
+typedef struct { - INT16 x; /* Top left x coordinate of the rectangle surrounding the ellipse */ - INT16 y; /* Top left y coordinate of the rectangle surrounding the ellipse */ - CARD16 width; /* Width of the rectangle surrounding the ellipse */ - CARD16 height; /* Height of the rectangle surrounding the ellipse */ - INT16 angle1; /* Angle at which the arc begins */ - INT16 angle2; /* Angle at which the arc ends */ -} XCBARC; --
- Note: the angles are expressed in units of 1/64 of a degree, - so to have an angle of 90 degrees, starting at 0, - angle1 = 0 and - angle2 = 90 << 6. Positive angles - indicate counterclockwise motion, while negative angles - indicate clockwise motion. -
-- TODO: there's no coordinate_mode. Is it normal ? -
-- TODO: I think that (x,y) should be the center of the - ellipse, and (width, height) the radius. It's more logical. -
-- The corresponding function which fill inside the geometrical - object are listed below, without further explanation, as they - are used as the above functions. -
-- To Fill a polygon defined by the points given as arguments , - we use -
--XCBVoidCookie XCBFillPoly (XCBConnection *c, - XCBDRAWABLE drawable, - XCBGCONTEXT gc, - CARD8 shape, - CARD8 coordinate_mode, - CARD32 points_len, - const XCBPOINT *points); --
- The shape parameter specifies a - shape that helps the server to improve performance. Available - values are -
-- To fill one or several rectangles, we use -
--XCBVoidCookie XCBPolyFillRectangle (XCBConnection *c, - XCBDRAWABLE drawable, - XCBGCONTEXT gc, - CARD32 rectangles_len, - const XCBRECTANGLE *rectangles); --
- To fill one or several arcs, we use -
--XCBVoidCookie XCBPolyFillArc (XCBConnection *c, - XCBDRAWABLE drawable, - XCBGCONTEXT gc, - CARD32 arcs_len, - const XCBARC *arcs); -- -
- To illustrate these functions, here is an example that draws - four points, a polygonal line, two segments, two rectangles - and two arcs. Remark that we use events for the first time, as - an introduction to the next section. -
-+ int16_t x; /* Top left x coordinate of the rectangle surrounding the ellipse */ + int16_t y; /* Top left y coordinate of the rectangle surrounding the ellipse */ + uint16_t width; /* Width of the rectangle surrounding the ellipse */ + uint16_t height; /* Height of the rectangle surrounding the ellipse */ + int16_t angle1; /* Angle at which the arc begins */ + int16_t angle2; /* Angle at which the arc ends */ +} xcb_arc_t; ++
+ Note: the angles are expressed in units of 1/64 of a degree, + so to have an angle of 90 degrees, starting at 0, + angle1 = 0 and + angle2 = 90 << 6. Positive angles + indicate counterclockwise motion, while negative angles + indicate clockwise motion. +
++ The corresponding function which fill inside the geometrical + object are listed below, without further explanation, as they + are used as the above functions. +
++ To Fill a polygon defined by the points given as arguments , + we use +
++xcb_void_cookie_t xcb_fill_poly (xcb_connection_t *c, + xcb_drawable_t drawable, + xcb_gcontext_t gc, + uint8_t shape, + uint8_t coordinate_mode, + uint32_t points_len, + const xcb_point_t *points); ++
+ The shape parameter specifies a + shape that helps the server to improve performance. Available + values are +
++ To fill one or several rectangles, we use +
++xcb_void_cookie_t xcb_poly_fill_rectangle (xcb_connection_t *c, + xcb_drawable_t drawable, + xcb_gcontext_t gc, + uint32_t rectangles_len, + const xcb_rectangle_t *rectangles); ++
+ To fill one or several arcs, we use +
++xcb_void_cookie_t xcb_poly_fill_arc (xcb_connection_t *c, + xcb_drawable_t drawable, + xcb_gcontext_t gc, + uint32_t arcs_len, + const xcb_arc_t *arcs); ++
+ To illustrate these functions, here is an example that draws + four points, a polygonal line, two segments, two rectangles + and two arcs. Remark that we use events for the first time, as + an introduction to the next section. +
++ TODO: Use screen->root_depth for depth parameter. +
+#include <stdlib.h> #include <stdio.h> -#include <X11/XCB/xcb.h> - -/* Get the depth of the screen. Needed in order to draw something */ -int -get_depth(XCBConnection *c, - XCBSCREEN *root) -{ - XCBDRAWABLE drawable; - XCBGetGeometryRep *geom; - int depth; - - drawable.window = root->root; - geom = XCBGetGeometryReply (c, XCBGetGeometry(c, drawable), 0); - - if(!geom) - { - perror ("GetGeometry(root) failed"); - exit (0); - } - - depth = geom->depth; - free (geom); - - return depth; -} +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBDRAWABLE win; - XCBGCONTEXT foreground; - XCBGenericEvent *e; - CARD32 mask = 0; - CARD32 values[2]; + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_drawable_t win; + xcb_gcontext_t foreground; + xcb_generic_event_t *e; + uint32_t mask = 0; + uint32_t values[2]; /* geometric objects */ - XCBPOINT points[] = { + xcb_point_t points[] = { {10, 10}, {10, 20}, {20, 10}, {20, 20}}; - XCBPOINT polyline[] = { + xcb_point_t polyline[] = { {50, 10}, - {55, 30}, - {80, 10}, - {90, 20}}; + { 5, 20}, /* rest of points are relative */ + {25,-20}, + {10, 10}}; - XCBSEGMENT segments[] = { + xcb_segment_t segments[] = { {100, 10, 140, 30}, {110, 25, 130, 60}}; - XCBRECTANGLE rectangles[] = { + xcb_rectangle_t rectangles[] = { { 10, 50, 40, 20}, { 80, 50, 10, 40}}; - XCBARC arcs[] = { - {10, 100, 60, 40, 0, 90 << 6}, - {90, 100, 55, 40, 0, 270 << 6}}; - + xcb_arc_t arcs[] = { + {10, 100, 60, 40, 0, 90 << 6}, + {90, 100, 55, 40, 0, 270 << 6}}; + /* Open the connection to the X server */ - c = XCBConnect (NULL, NULL); - + c = xcb_connect (NULL, NULL); + /* Get the first screen */ - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; - /* Create black (foregroung) graphic context */ - win.window = screen->root; + /* Create black (foreground) graphic context */ + win = screen->root; - foreground = XCBGCONTEXTNew (c); - mask = GCForeground | GCGraphicsExposures; + foreground = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES; values[0] = screen->black_pixel; values[1] = 0; - XCBCreateGC (c, foreground, win, mask, values); + xcb_create_gc (c, foreground, win, mask, values); /* Ask for our window's Id */ - win.window = XCBWINDOWNew(c); + win = xcb_generate_id(c); /* Create the window */ - mask = XCBCWBackPixel | XCBCWEventMask; + mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK; values[0] = screen->white_pixel; - values[1] = ExposureMask; - XCBCreateWindow (c, /* Connection */ - 0, /* depth */ - win.window, /* window Id */ - screen->root, /* parent window */ - 0, 0, /* x, y */ - 150, 150, /* width, height */ - 10, /* border_width */ - InputOutput, /* class */ - screen->root_visual, /* visual */ - mask, values); /* masks */ + values[1] = XCB_EVENT_MASK_EXPOSURE; + xcb_create_window (c, /* Connection */ + XCB_COPY_FROM_PARENT, /* depth */ + win, /* window Id */ + screen->root, /* parent window */ + 0, 0, /* x, y */ + 150, 150, /* width, height */ + 10, /* border_width */ + XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */ + screen->root_visual, /* visual */ + mask, values); /* masks */ /* Map the window on the screen */ - XCBMapWindow (c, win.window); + xcb_map_window (c, win); /* We flush the request */ - XCBSync (c, 0); - - while ((e = XCBWaitEvent (c))) - { - switch (e->response_type) - { - case XCBExpose: - { - /* We draw the points */ - XCBPolyPoint (c, CoordModeOrigin, win, foreground, 4, points); - - /* We draw the polygonal line */ - XCBPolyLine (c, CoordModeOrigin, win, foreground, 4, polyline); - - /* We draw the segements */ - XCBPolySegment (c, win, foreground, 2, segments); - - /* We draw the rectangles */ - XCBPolyRectangle (c, win, foreground, 2, rectangles); - - /* We draw the arcs */ - XCBPolyArc (c, win, foreground, 2, arcs); - - /* We flush the request */ - XCBSync (c, 0); - - break; - } - default: - { - /* Unknown event type, ignore it */ - break; - } - } - /* Free the Generic Event */ - free (e); + xcb_flush (c); + + while ((e = xcb_wait_for_event (c))) { + switch (e->response_type & ~0x80) { + case XCB_EXPOSE: { + /* We draw the points */ + xcb_poly_point (c, XCB_COORD_MODE_ORIGIN, win, foreground, 4, points); + + /* We draw the polygonal line */ + xcb_poly_line (c, XCB_COORD_MODE_PREVIOUS, win, foreground, 4, polyline); + + /* We draw the segements */ + xcb_poly_segment (c, win, foreground, 2, segments); + + /* We draw the rectangles */ + xcb_poly_rectangle (c, win, foreground, 2, rectangles); + + /* We draw the arcs */ + xcb_poly_arc (c, win, foreground, 2, arcs); + + /* We flush the request */ + xcb_flush (c); + + break; + } + default: { + /* Unknown event type, ignore it */ + break; + } } + /* Free the Generic Event */ + free (e); + } - return 1; + return 0; }
In an X program, everything is driven by events. Event painting on the screen is sometimes done as a response to an event (an @@ -1386,700 +1370,674 @@ main (int argc, char *argv[]) received as a set of events.
- During the creation of a window, you should give it what kind - of events it wishes to receive. Thus, you may register for - various mouse (also called pointer) events, keyboard events, - expose events, and so on. This is done for optimizing the - server-to-client connection (i.e. why send a program (that - might even be running at the other side of the globe) an event - it is not interested in ?) -
-- In XCB, you use the "value_mask" and "value_list" data in the - XCBCreateWindow() function to - register for events. Here is how we register for - Expose event when creating a window: -
-- mask = XCBCWEventMask; - valwin[0] = ExposureMask; - win.window = XCBWINDOWNew (c); - XCBCreateWindow (c, depth, win.window, root->root, - 0, 0, 150, 150, 10, - InputOutput, root->root_visual, - mask, valwin); --
- ExposureMask is a constant defined - in the "X.h" header file. If we wanted to register to several - event types, we can logically "or" them, as follows: -
-- mask = XCBCWEventMask; - valwin[0] = ExposureMask | ButtonPressMask; - win.window = XCBWINDOWNew (c); - XCBCreateWindow (c, depth, win.window, root->root, - 0, 0, 150, 150, 10, - InputOutput, root->root_visual, - mask, valwin); --
- This registers for Expose events as - well as for mouse button presses insode the created - window. You should note that a mask may represent several - event sub-types. -
-- The values that a mask could take are given - by the XCBCW enumeration: -
-+
+ During the creation of a window, you should give it what kind + of events it wishes to receive. Thus, you may register for + various mouse (also called pointer) events, keyboard events, + expose events, and so on. This is done for optimizing the + server-to-client connection (i.e. why send a program (that + might even be running at the other side of the globe) an event + it is not interested in ?) +
++ In XCB, you use the "value_mask" and "value_list" data in the + xcb_create_window() function to + register for events. Here is how we register for + Expose event when creating a window: +
++ mask = XCB_CW_EVENT_MASK; + valwin[0] = XCB_EVENT_MASK_EXPOSURE; + win = xcb_generate_id (c); + xcb_create_window (c, depth, win, root->root, + 0, 0, 150, 150, 10, + XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual, + mask, valwin); ++
+ XCB_EVENT_MASK_EXPOSURE is a constant defined + in the xcb_event_mask_t enumeration in the "xproto.h" header file. If we wanted to register for several + event types, we can logically "or" them, as follows: +
++ mask = XCB_CW_EVENT_MASK; + valwin[0] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; + win = xcb_generate_id (c); + xcb_create_window (c, depth, win, root->root, + 0, 0, 150, 150, 10, + XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual, + mask, valwin); ++
+ This registers for Expose events as + well as for mouse button presses inside the created + window. You should note that a mask may represent several + event sub-types. +
++ The values that a mask could take are given + by the xcb_cw_t enumeration: +
+typedef enum { - XCBCWBackPixmap = 1L<<0, - XCBCWBackPixel = 1L<<1, - XCBCWBorderPixmap = 1L<<2, - XCBCWBorderPixel = 1L<<3, - XCBCWBitGravity = 1L<<4, - XCBCWWinGravity = 1L<<5, - XCBCWBackingStore = 1L<<6, - XCBCWBackingPlanes = 1L<<7, - XCBCWBackingPixel = 1L<<8, - XCBCWOverrideRedirect = 1L<<9, - XCBCWSaveUnder = 1L<<10, - XCBCWEventMask = 1L<<11, - XCBCWDontPropagate = 1L<<12, - XCBCWColormap = 1L<<13, - XCBCWCursor = 1L<<14 -} XCBCW; --
Note: we must be careful when setting the values of the valwin parameter, as they have to follow the order the - XCBCW enumeration. Here is an + xcb_cw_t enumeration. Here is an example: -
-- mask = XCBCWEventMask | XCBCWBackPixmap; - valwin[0] = None; /* for XCBCWBackPixmap (whose value is 1) */ - valwin[1] = ExposureMask | ButtonPressMask; /* for XCBCWEventMask, whose value (2048) */ - /* is superior to the one of XCBCWBackPixmap */ --
- If the window has already been created, we can use the - XCBConfigureWindow() function to set - the events that the window will receive. The subsection - Configuring a window shows its - prototype. As an example, here is a piece of code that - configures the window to receive the - Expose and - ButtonPressMask events: -
--const static CARD32 values[] = { ExposureMask | ButtonPressMask }; + +
+ mask = XCB_CW_EVENT_MASK | XCB_CW_BACK_PIXMAP; + valwin[0] = XCB_NONE; /* for XCB_CW_BACK_PIXMAP (whose value is 1) */ + valwin[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS; /* for XCB_CW_EVENT_MASK, whose value (2048) */ + /* is greater than the one of XCB_CW_BACK_PIXMAP */ ++
+ If the window has already been created, we can use the + xcb_configure_window() function to set + the events that the window will receive. The subsection + Configuring a window shows its + prototype. As an example, here is a piece of code that + configures the window to receive the + Expose and + ButtonPress events: +
++const static uint32_t values[] = { XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS }; /* The connection c and the window win are supposed to be defined */ -XCBConfigureWindow (c, win, XCBCWEventMask, values); --
- Note: A common bug programmers do is adding code to handle new - event types in their program, while forgetting to add the - masks for these events in the creation of the window. Such a - programmer then should sit down for hours debugging his - program, wondering "Why doesn't my program notice that I - released the button?", only to find that they registered for - button press events but not for button release events. -
-- After we have registered for the event types we are interested - in, we need to enter a loop of receiving events and handling - them. There are two ways to receive events: a blocking way and - a non blocking way: -
-- There are various ways to write such a loop. We present two - ways to write such a loop, with the two functions above. The - first one uses XCBWaitEvent, which - is similar to an event Xlib loop using only XNextEvent: -
-- XCBGenericEvent *e; - - while ((e = XCBWaitEvent (c))) - { - switch (e->response_type) - { - case XCBExpose: - { - /* Handle the Expose event type */ - XCBExposeEvent *ev = (XCBExposeEvent *)e; - - /* ... */ - - break; - } - case XCBButtonPress: - { - /* Handle the ButtonPress event type */ - XCBButtonPressEvent *ev = (XCBButtonPressEvent *)e; - - /* ... */ - - break; - } - default: - { - /* Unknown event type, ignore it */ - break; - } - } - /* Free the Generic Event */ - free (e); - } --
- You will certainly want to use XCBPollForEvent(XCBConnection *c, int - *error) if, in Xlib, you use XPending: -
-- while (XPending (display)) - { - XEvent ev; - - XNextEvent(d, &ev); - - /* Manage your event */ - } +xcb_configure_window (c, win, XCB_CW_EVENT_MASK, values);+
- Such a loop in XCB looks like: -
-- XCBGenericEvent *ev; - - while ((ev = XCBPollForEvent (conn, 0))) - { - /* Manage your event */ - } --
- The events are managed in the same way as with XCBWaitEvent. - Obviously, we will need to give the user some way of - terminating the program. This is usually done by handling a - special "quit" event, as we will soon see. -
-- The Expose event is one of the most - basic (and most used) events an application may receive. It - will be sent to us in one of several cases: -
- You should note the implicit assumption hidden here: the - contents of our window is lost when it is being obscured - (covered) by either windows. One may wonder why the X server - does not save this contents. The answer is: to save - memory. After all, the number of windows on a display at a - given time may be very large, and storing the contents of all - of them might require a lot of memory. Actually, there is a - way to tell the X server to store the contents of a window in - special cases, as we will see later. -
-- When we get an Expose event, we - should take the event's data from the members of the following - structure: -
--typedef struct { - BYTE response_type; /* The type of the event, here it is XCBExpose */ - CARD8 pad0; - CARD16 sequence; - XCBWINDOW window; /* The Id of the window that receives the event (in case */ - /* our application registered for events on several windows */ - CARD16 x; /* The x coordinate of the top-left part of the window that needs to be redrawn */ - CARD16 y; /* The y coordinate of the top-left part of the window that needs to be redrawn */ - CARD16 width; /* The width of the part of the window that needs to be redrawn */ - CARD16 height; /* The height of the part of the window that needs to be redrawn */ - CARD16 count; -} XCBExposeEvent; --
- User input traditionally comes from two sources: the mouse - and the keyboard. Various event types exist to notify us of - user input (a key being presses on the keyboard, a key being - released on the keyboard, the mouse moving over our window, - the mouse entering (or leaving) our window, and so on. -
-- The first event type we will deal with is a mouse - button-press (or button-release) event in our window. In - order to register to such an event type, we should add one - (or more) of the following masks when we create our window: -
-- The structure to be checked for in our events loop is the - same for these two events, and is the following: -
--typedef struct { - BYTE response_type; /* The type of the event, here it is XCBButtonPressEvent or XCBButtonReleaseEvent */ - XCBBUTTON detail; - CARD16 sequence; - XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */ - XCBWINDOW root; - XCBWINDOW event; - XCBWINDOW child; - INT16 root_x; - INT16 root_y; - INT16 event_x; /* The x coordinate where the mouse has been pressed in the window */ - INT16 event_y; /* The y coordinate where the mouse has been pressed in the window */ - CARD16 state; /* A mask of the buttons (or keys) during the event */ - BOOL same_screen; -} XCBButtonPressEvent; - -typedef XCBButtonPressEvent XCBButtonReleaseEvent; --
- The time field may be used to calculate "double-click" - situations by an application (e.g. if the mouse button was - clicked two times in a duration shorter than a given amount - of time, assume this was a double click). -
-- The state field is a mask of the buttons held down during - the event. It is a bitwise OR of any of the following: -
-- Their names are self explanatory, where the first 5 refer to - the mouse buttons that are being pressed, while the rest - refer to various "special keys" that are being pressed (Mod1 - is usually the 'Alt' key or the 'Meta' key). -
-- TODO: Problem: it seems that the state does not - change when clicking with various buttons. -
-- Similar to mouse button press and release events, we also - can be notified of various mouse movement events. These can - be split into two families. One is of mouse pointer - movement while no buttons are pressed, and the second is a - mouse pointer motion while one (or more) of the buttons are - pressed (this is sometimes called "a mouse drag operation", - or just "dragging"). The following event masks may be added - during the creation of our window: -
-- The structure to be checked for in our events loop is the - same for these events, and is the following: -
--typedef struct { - BYTE response_type; /* The type of the event */ - BYTE detail; - CARD16 sequence; - XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */ - XCBWINDOW root; - XCBWINDOW event; - XCBWINDOW child; - INT16 root_x; - INT16 root_y; - INT16 event_x; /* The x coordinate of the mouse when the event was generated */ - INT16 event_y; /* The y coordinate of the mouse when the event was generated */ - CARD16 state; /* A mask of the buttons (or keys) during the event */ - BOOL same_screen; -} XCBMotionNotifyEvent; --
- Another type of event that applications might be interested - at, is a mouse pointer entering a window the program - controls, or leaving such a window. Some programs use these - events to show the user tht the applications is now in - focus. In order to register for such an event type, we - should add one (or more) of the following masks when we - create our window: -
-- The structure to be checked for in our events loop is the - same for these two events, and is the following: -
--typedef struct { - BYTE response_type; /* The type of the event */ - BYTE detail; - CARD16 sequence; - XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */ - XCBWINDOW root; - XCBWINDOW event; - XCBWINDOW child; - INT16 root_x; - INT16 root_y; - INT16 event_x; /* The x coordinate of the mouse when the event was generated */ - INT16 event_y; /* The y coordinate of the mouse when the event was generated */ - CARD16 state; /* A mask of the buttons (or keys) during the event */ - BYTE mode; /* The number of mouse button that was clicked */ - BYTE same_screen_focus; -} XCBEnterNotifyEvent; - -typedef XCBEnterNotifyEvent XCBLeaveNotifyEvent; --
- There may be many windows on a screen, but only a single - keyboard attached to them. How does the X server then know - which window should be sent a given keyboard input ? This is - done using the keyboard focus. Only a single window on the - screen may have the keyboard focus at a given time. There - is a XCB function that allow a program to set the keyboard - focus to a given window. The user can usually set the - keyboard ficus using the window manager (often by clicking - on the title bar of the desired window). Once our window - has the keyboard focus, every key press or key release will - cause an event to be sent to our program (if it regsitered - for these event types...). -
-- If a window controlled by our program currently holds the - keyboard focus, it can receive key press and key release - events. So, we should add one (or more) of the following - masks when we create our window: -
-- The structure to be checked for in our events loop is the - same for these two events, and is the following: -
--typedef struct { - BYTE response_type; /* The type of the event */ - XCBKEYCODE detail; - CARD16 sequence; - XCBTIMESTAMP time; /* Time, in milliseconds the event took place in */ - XCBWINDOW root; - XCBWINDOW event; - XCBWINDOW child; - INT16 root_x; - INT16 root_y; - INT16 event_x; - INT16 event_y; - CARD16 state; - BOOL same_screen; -} XCBKeyPressEvent; - -typedef XCBKeyPressEvent XCBKeyReleaseEvent; --
- The detail field refer to the - physical key on the keyboard. -
-- TODO: Talk about getting the ASCII code from the key code. -
-- As an example for handling events, we show a program that - creates a window, enter an events loop and check for all the - events described above, and write on the terminal the relevant - characteristics of the event. With this code, it should be - easy to add drawing operations, like those which have been - described above. -
+ Note: A common bug programmers do is adding code to handle new + event types in their program, while forgetting to add the + masks for these events in the creation of the window. Such a + programmer then should sit down for hours debugging his + program, wondering "Why doesn't my program notice that I + released the button?", only to find that they registered for + button press events but not for button release events. + ++ After we have registered for the event types we are interested + in, we need to enter a loop of receiving events and handling + them. There are two ways to receive events: a blocking way and + a non-blocking way: +
++ There are various ways to write such a loop. We present two + ways to write such a loop, with the two functions above. The + first one uses xcb_wait_for_event_t, which + is similar to an event Xlib loop using only XNextEvent: +
-#include <malloc.h> -#include <stdio.h> + xcb_generic_event_t *e; -#include <X11/XCB/xcb.h> + while ((e = xcb_wait_for_event (c))) { + switch (e->response_type & ~0x80) { + case XCB_EXPOSE: { + /* Handle the Expose event type */ + xcb_expose_event_t *ev = (xcb_expose_event_t *)e; -int -main (int argc, char *argv[]) -{ - XCBConnection *c; - XCBSCREEN *screen; - XCBDRAWABLE win; - XCBGenericEvent *e; - CARD32 mask = 0; - CARD32 values[2]; - - /* Open the connection to the X server */ - c = XCBConnect (NULL, NULL); - - /* Get the first screen */ - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + /* ... */ - /* Ask for our window's Id */ - win.window = XCBWINDOWNew(c); + break; + } + case XCB_BUTTON_PRESS: { + /* Handle the ButtonPress event type */ + xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e; + + /* ... */ + + break; + } + default: { + /* Unknown event type, ignore it */ + break; + } + } + /* Free the Generic Event */ + free (e); + } ++
+ You will certainly want to use xcb_poll_for_event(xcb_connection_t *c, int + *error) if, in Xlib, you use XPending or + XCheckMaskEvent: +
++ while (XPending (display)) { + XEvent ev; + + XNextEvent(d, &ev); + + /* Manage your event */ + } ++
+ Such a loop in XCB looks like: +
++ xcb_generic_event_t *ev; + + while ((ev = xcb_poll_for_event (conn, 0))) { + /* Manage your event */ + } ++
+ The events are managed in the same way as with xcb_wait_for_event_t. + Obviously, we will need to give the user some way of + terminating the program. This is usually done by handling a + special "quit" event, as we will soon see. +
++ The Expose event is one of the most + basic (and most used) events an application may receive. It + will be sent to us in one of several cases: +
++ You should note the implicit assumption hidden here: the + contents of our window is lost when it is being obscured + (covered) by either windows. One may wonder why the X server + does not save this contents. The answer is: to save + memory. After all, the number of windows on a display at a + given time may be very large, and storing the contents of all + of them might require a lot of memory. Actually, there is a + way to tell the X server to store the contents of a window in + special cases, as we will see later. +
++ When we get an Expose event, we + should take the event's data from the members of the following + structure: +
++typedef struct { + uint8_t response_type; /* The type of the event, here it is XCB_EXPOSE */ + uint8_t pad0; + uint16_t sequence; + xcb_window_t window; /* The Id of the window that receives the event (in case */ + /* our application registered for events on several windows */ + uint16_t x; /* The x coordinate of the top-left part of the window that needs to be redrawn */ + uint16_t y; /* The y coordinate of the top-left part of the window that needs to be redrawn */ + uint16_t width; /* The width of the part of the window that needs to be redrawn */ + uint16_t height; /* The height of the part of the window that needs to be redrawn */ + uint16_t count; +} xcb_expose_event_t; ++
+ User input traditionally comes from two sources: the mouse + and the keyboard. Various event types exist to notify us of + user input (a key being presses on the keyboard, a key being + released on the keyboard, the mouse moving over our window, + the mouse entering (or leaving) our window, and so on. +
++ The first event type we will deal with is a mouse + button-press (or button-release) event in our window. In + order to register to such an event type, we should add one + (or more) of the following masks when we create our window: +
++ The structure to be checked for in our events loop is the + same for these two events, and is the following: +
++typedef struct { + uint8_t response_type; /* The type of the event, here it is xcb_button_press_event_t or xcb_button_release_event_t */ + xcb_button_t detail; + uint16_t sequence; + xcb_timestamp_t time; /* Time, in milliseconds the event took place in */ + xcb_window_t root; + xcb_window_t event; + xcb_window_t child; + int16_t root_x; + int16_t root_y; + int16_t event_x; /* The x coordinate where the mouse has been pressed in the window */ + int16_t event_y; /* The y coordinate where the mouse has been pressed in the window */ + uint16_t state; /* A mask of the buttons (or keys) during the event */ + uint8_t same_screen; +} xcb_button_press_event_t; + +typedef xcb_button_press_event_t xcb_button_release_event_t; ++
+ The time field may be used to calculate "double-click" + situations by an application (e.g. if the mouse button was + clicked two times in a duration shorter than a given amount + of time, assume this was a double click). +
++ The state field is a mask of the buttons held down during + the event. It is a bitwise OR of any of the following (from the xcb_button_mask_t and + xcb_mod_mask_t enumerations): +
++ Their names are self explanatory, where the first 5 refer to + the mouse buttons that are being pressed, while the rest + refer to various "special keys" that are being pressed (Mod1 + is usually the 'Alt' key or the 'Meta' key). +
++ TODO: Problem: it seems that the state does not + change when clicking with various buttons. +
++ Similar to mouse button press and release events, we also + can be notified of various mouse movement events. These can + be split into two families. One is of mouse pointer + movement while no buttons are pressed, and the second is a + mouse pointer motion while one (or more) of the buttons are + pressed (this is sometimes called "a mouse drag operation", + or just "dragging"). The following event masks may be added + during the creation of our window: +
++ The structure to be checked for in our events loop is the + same for these events, and is the following: +
++typedef struct { + uint8_t response_type; /* The type of the event */ + uint8_t detail; + uint16_t sequence; + xcb_timestamp_t time; /* Time, in milliseconds the event took place in */ + xcb_window_t root; + xcb_window_t event; + xcb_window_t child; + int16_t root_x; + int16_t root_y; + int16_t event_x; /* The x coordinate of the mouse when the event was generated */ + int16_t event_y; /* The y coordinate of the mouse when the event was generated */ + uint16_t state; /* A mask of the buttons (or keys) during the event */ + uint8_t same_screen; +} xcb_motion_notify_event_t; ++
+ Another type of event that applications might be interested + in, is a mouse pointer entering a window the program + controls, or leaving such a window. Some programs use these + events to show the user that the application is now in + focus. In order to register for such an event type, we + should add one (or more) of the following masks when we + create our window: +
++ The structure to be checked for in our events loop is the + same for these two events, and is the following: +
++typedef struct { + uint8_t response_type; /* The type of the event */ + uint8_t detail; + uint16_t sequence; + xcb_timestamp_t time; /* Time, in milliseconds the event took place in */ + xcb_window_t root; + xcb_window_t event; + xcb_window_t child; + int16_t root_x; + int16_t root_y; + int16_t event_x; /* The x coordinate of the mouse when the event was generated */ + int16_t event_y; /* The y coordinate of the mouse when the event was generated */ + uint16_t state; /* A mask of the buttons (or keys) during the event */ + uint8_t mode; /* The number of mouse button that was clicked */ + uint8_t same_screen_focus; +} xcb_enter_notify_event_t; + +typedef xcb_enter_notify_event_t xcb_leave_notify_event_t; ++
+ There may be many windows on a screen, but only a single + keyboard attached to them. How does the X server then know + which window should be sent a given keyboard input ? This is + done using the keyboard focus. Only a single window on the + screen may have the keyboard focus at a given time. There + is a XCB function that allows a program to set the keyboard + focus to a given window. The user can usually set the + keyboard focus using the window manager (often by clicking + on the title bar of the desired window). Once our window + has the keyboard focus, every key press or key release will + cause an event to be sent to our program (if it regsitered + for these event types...). +
++ If a window controlled by our program currently holds the + keyboard focus, it can receive key press and key release + events. So, we should add one (or more) of the following + masks when we create our window: +
++ The structure to be checked for in our events loop is the + same for these two events, and is the following: +
++typedef struct { + uint8_t response_type; /* The type of the event */ + xcb_keycode_t detail; + uint16_t sequence; + xcb_timestamp_t time; /* Time, in milliseconds the event took place in */ + xcb_window_t root; + xcb_window_t event; + xcb_window_t child; + int16_t root_x; + int16_t root_y; + int16_t event_x; + int16_t event_y; + uint16_t state; + uint8_t same_screen; +} xcb_key_press_event_t; + +typedef xcb_key_press_event_t xcb_key_release_event_t; ++
+ The detail field refers to the + physical key on the keyboard. +
++ TODO: Talk about getting the ASCII code from the key code. +
++ As an example for handling events, we show a program that + creates a window, enters an events loop and checks for all the + events described above, and writes on the terminal the relevant + characteristics of the event. With this code, it should be + easy to add drawing operations, like those which have been + described above. +
++#include <stdlib.h> +#include <stdio.h> + +#include <xcb/xcb.h> + +void +print_modifiers (uint32_t mask) +{ + const char **mod, *mods[] = { + "Shift", "Lock", "Ctrl", "Alt", + "Mod2", "Mod3", "Mod4", "Mod5", + "Button1", "Button2", "Button3", "Button4", "Button5" + }; + printf ("Modifier mask: "); + for (mod = mods ; mask; mask >>= 1, mod++) + if (mask & 1) + printf(*mod); + putchar ('\n'); +} + +int +main () +{ + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_window_t win; + xcb_generic_event_t *e; + uint32_t mask = 0; + uint32_t values[2]; + + /* Open the connection to the X server */ + c = xcb_connect (NULL, NULL); + + /* Get the first screen */ + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; + + /* Ask for our window's Id */ + win = xcb_generate_id (c); /* Create the window */ - mask = XCBCWBackPixel | XCBCWEventMask; + mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK; values[0] = screen->white_pixel; - values[1] = ExposureMask | ButtonPressMask | ButtonReleaseMask | - PointerMotionMask | EnterWindowMask | LeaveWindowMask | - KeyPressMask | KeyReleaseMask; - XCBCreateWindow (c, /* Connection */ - 0, /* depth */ - win.window, /* window Id */ - screen->root, /* parent window */ - 0, 0, /* x, y */ - 150, 150, /* width, height */ - 10, /* border_width */ - InputOutput, /* class */ - screen->root_visual, /* visual */ - mask, values); /* masks */ + values[1] = XCB_EVENT_MASK_EXPOSURE | XCB_EVENT_MASK_BUTTON_PRESS | + XCB_EVENT_MASK_BUTTON_RELEASE | XCB_EVENT_MASK_POINTER_MOTION | + XCB_EVENT_MASK_ENTER_WINDOW | XCB_EVENT_MASK_LEAVE_WINDOW | + XCB_EVENT_MASK_KEY_PRESS | XCB_EVENT_MASK_KEY_RELEASE; + xcb_create_window (c, /* Connection */ + 0, /* depth */ + win, /* window Id */ + screen->root, /* parent window */ + 0, 0, /* x, y */ + 150, 150, /* width, height */ + 10, /* border_width */ + XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */ + screen->root_visual, /* visual */ + mask, values); /* masks */ /* Map the window on the screen */ - XCBMapWindow (c, win.window); - - XCBSync (c, 0); - while ((e = XCBWaitEvent (c))) - { - switch (e->response_type) - { - case XCBExpose: - { - XCBExposeEvent *ev = (XCBExposeEvent *)e; - - printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n", - ev->window.xid, ev->x, ev->y, ev->width, ev->height); - break; - } - case XCBButtonPress: - { - XCBButtonPressEvent *ev = (XCBButtonPressEvent *)e; - int button_num = 0; - - if ((ev->state | Button1Mask) == Button1Mask) - button_num = 1; - if ((ev->state | Button2Mask) == Button2Mask) - button_num = 2; - if ((ev->state | Button3Mask) == Button3Mask) - button_num = 3; - if ((ev->state | Button4Mask) == Button4Mask) - button_num = 4; - if ((ev->state | Button5Mask) == Button5Mask) - button_num = 5; - - switch (ev->detail.id) - { - case 4: - { - printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n", - ev->event.xid, ev->event_x, ev->event_y); - break; - } - case 5: - { - printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n", - ev->event.xid, ev->event_x, ev->event_y); - break; - } - default: - printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n", - ev->detail.id, ev->event.xid, ev->event_x, ev->event_y); - } - break; - } - case XCBButtonRelease: - { - XCBButtonReleaseEvent *ev = (XCBButtonReleaseEvent *)e; - int button_num = 0; - - if ((ev->state | Button1Mask) == Button1Mask) - button_num = 1; - if ((ev->state | Button2Mask) == Button2Mask) - button_num = 2; - if ((ev->state | Button3Mask) == Button3Mask) - button_num = 3; - if ((ev->state | Button4Mask) == Button4Mask) - button_num = 4; - if ((ev->state | Button5Mask) == Button5Mask) - button_num = 5; - - printf ("Button %d released in window %ld, at coordinates (%d,%d)\n", - ev->detail.id, ev->event.xid, ev->event_x, ev->event_y); - break; - } - case XCBMotionNotify: - { - XCBMotionNotifyEvent *ev = (XCBMotionNotifyEvent *)e; - - printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n", - ev->event.xid, ev->event_x, ev->event_y); - break; - } - case XCBEnterNotify: - { - XCBEnterNotifyEvent *ev = (XCBEnterNotifyEvent *)e; - - printf ("Mouse entered window %ld, at coordinates (%d,%d)\n", - ev->event.xid, ev->event_x, ev->event_y); - break; - } - case XCBLeaveNotify: - { - XCBLeaveNotifyEvent *ev = (XCBLeaveNotifyEvent *)e; - - printf ("Mouse leaved window %ld, at coordinates (%d,%d)\n", - ev->event.xid, ev->event_x, ev->event_y); - break; - } - case XCBKeyPress: - { - XCBKeyPressEvent *ev = (XCBKeyPressEvent *)e; - - printf ("Key pressed in window %ld\n", - ev->event.xid); - break; - } - case XCBKeyRelease: - { - XCBKeyReleaseEvent *ev = (XCBKeyReleaseEvent *)e; - - printf ("Key releaseed in window %ld\n", - ev->event.xid); - break; - } - default: - { - /* Unknown event type, ignore it */ - break; - } - } - /* Free the Generic Event */ - free (e); + xcb_map_window (c, win); + + xcb_flush (c); + + while ((e = xcb_wait_for_event (c))) { + switch (e->response_type & ~0x80) { + case XCB_EXPOSE: { + xcb_expose_event_t *ev = (xcb_expose_event_t *)e; + + printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n", + ev->window, ev->x, ev->y, ev->width, ev->height); + break; } + case XCB_BUTTON_PRESS: { + xcb_button_press_event_t *ev = (xcb_button_press_event_t *)e; + print_modifiers(ev->state); + + switch (ev->detail) { + case 4: + printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n", + ev->event, ev->event_x, ev->event_y); + break; + case 5: + printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n", + ev->event, ev->event_x, ev->event_y); + break; + default: + printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n", + ev->detail, ev->event, ev->event_x, ev->event_y); + } + break; + } + case XCB_BUTTON_RELEASE: { + xcb_button_release_event_t *ev = (xcb_button_release_event_t *)e; + print_modifiers(ev->state); + + printf ("Button %d released in window %ld, at coordinates (%d,%d)\n", + ev->detail, ev->event, ev->event_x, ev->event_y); + break; + } + case XCB_MOTION_NOTIFY: { + xcb_motion_notify_event_t *ev = (xcb_motion_notify_event_t *)e; + + printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n", + ev->event, ev->event_x, ev->event_y); + break; + } + case XCB_ENTER_NOTIFY: { + xcb_enter_notify_event_t *ev = (xcb_enter_notify_event_t *)e; - return 1; + printf ("Mouse entered window %ld, at coordinates (%d,%d)\n", + ev->event, ev->event_x, ev->event_y); + break; + } + case XCB_LEAVE_NOTIFY: { + xcb_leave_notify_event_t *ev = (xcb_leave_notify_event_t *)e; + + printf ("Mouse left window %ld, at coordinates (%d,%d)\n", + ev->event, ev->event_x, ev->event_y); + break; + } + case XCB_KEY_PRESS: { + xcb_key_press_event_t *ev = (xcb_key_press_event_t *)e; + print_modifiers(ev->state); + + printf ("Key pressed in window %ld\n", + ev->event); + break; + } + case XCB_KEY_RELEASE: { + xcb_key_release_event_t *ev = (xcb_key_release_event_t *)e; + print_modifiers(ev->state); + + printf ("Key released in window %ld\n", + ev->event); + break; + } + default: + /* Unknown event type, ignore it */ + printf("Unknown event: %d\n", e->response_type); + break; + } + /* Free the Generic Event */ + free (e); + } + + return 0; }
Besides drawing graphics on a window, we often want to draw text. Text strings have two major properties: the characters to @@ -2089,22 +2047,318 @@ main (int argc, char *argv[]) draw the text in a window, using the Graphic Context.
- In order to support flexible fonts, a font structure is - defined. You know what ? Its an Id: -
--typedef struct { - CARD32 xid; -} XCBFONT; +
+ In order to support flexible fonts, a font type is + defined. You know what ? It's an Id: +
++typedef uint32_t xcb_font_t; ++
+ It is used to contain information about a font, and is passed + to several functions that handle fonts selection and text drawing. + We ask the X server to attribute an Id to our font with the + function: +
++xcb_font_t xcb_generate_id (xcb_connection_t *c); ++
+ To open a font, we use the following function: +
++xcb_void_cookie_t xcb_open_font (xcb_connection_t *c, + xcb_font_t fid, + uint16_t name_len, + const char *name); ++
+ The fid parameter is the font Id + defined by xcb_generate_id() (see + above). The name parameter is the + name of the font you want to open. Use the command + xlsfonts in a terminal to know which + are the fonts available on your computer. The parameter + name_len is the length of the name + of the font (given by strlen()). +
++ Once a font is opened, you have to create a Graphic Context + that will contain the informations about the color of the + foreground and the background used when you draw a text in a + Drawable. Here is an exemple of a Graphic Context that will + allow us to draw an opened font with a black foreground and a + white background: +
++ /* + * c is the connection + * screen is the screen where the window is displayed + * window is the window in which we will draw the text + * font is the opened font + */ + + uint32_t value_list[3]; + xcb_gcontext_t gc; + uint32_t mask; + + gc = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT; + value_list[0] = screen->black_pixel; + value_list[1] = screen->white_pixel; + value_list[2] = font; + xcb_create_gc (c, gc, window, mask, value_list); + + /* The font is not needed anymore, so we close it */ + xcb_close_font (c, font); ++
+ To draw a text in a drawable, we use the following function: +
++xcb_void_cookie_t xcb_image_text_8 (xcb_connection_t *c, + uint8_t string_len, + xcb_drawable_t drawable, + xcb_gcontext_t gc, + int16_t x, + int16_t y, + const char *string); ++
+ The string parameter is the text to + draw. The location of the drawing is given by the parameters + x and y. + The base line of the text is exactly the parameter + y. +
++ This example draw a text at 10 pixels (for the base line) of + the bottom of a window. Pressing the Esc key exits the program. +
++#include <stdlib.h> +#include <stdio.h> +#include <string.h> + +#include <xcb/xcb.h> + +#define WIDTH 300 +#define HEIGHT 100 + + + +static xcb_gc_t gc_font_get (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + const char *font_name); + +static void text_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label); + +static void +text_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label) +{ + xcb_void_cookie_t cookie_gc; + xcb_void_cookie_t cookie_text; + xcb_generic_error_t *error; + xcb_gcontext_t gc; + uint8_t length; + + length = strlen (label); + + gc = gc_font_get(c, screen, window, "7x13"); + + cookie_text = xcb_image_text_8_checked (c, length, window, gc, + x1, + y1, label); + error = xcb_request_check (c, cookie_text); + if (error) { + fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_gc = xcb_free_gc (c, gc); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } +} + +static xcb_gc_t +gc_font_get (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + const char *font_name) +{ + uint32_t value_list[3]; + xcb_void_cookie_t cookie_font; + xcb_void_cookie_t cookie_gc; + xcb_generic_error_t *error; + xcb_font_t font; + xcb_gcontext_t gc; + uint32_t mask; + + font = xcb_generate_id (c); + cookie_font = xcb_open_font_checked (c, font, + strlen (font_name), + font_name); + + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + + gc = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT; + value_list[0] = screen->black_pixel; + value_list[1] = screen->white_pixel; + value_list[2] = font; + cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_font = xcb_close_font_checked (c, font); + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + return gc; +} + +int main () +{ + xcb_screen_iterator_t screen_iter; + xcb_connection_t *c; + const xcb_setup_t *setup; + xcb_screen_t *screen; + xcb_generic_event_t *e; + xcb_generic_error_t *error; + xcb_void_cookie_t cookie_window; + xcb_void_cookie_t cookie_map; + xcb_window_t window; + uint32_t mask; + uint32_t values[2]; + int screen_number; + + /* getting the connection */ + c = xcb_connect (NULL, &screen_number); + if (!c) { + fprintf (stderr, "ERROR: can't connect to an X server\n"); + return -1; + } + + /* getting the current screen */ + setup = xcb_get_setup (c); + + screen = NULL; + screen_iter = xcb_setup_roots_iterator (setup); + for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&screen_iter)) + if (screen_number == 0) + { + screen = screen_iter.data; + break; + } + if (!screen) { + fprintf (stderr, "ERROR: can't get the current screen\n"); + xcb_disconnect (c); + return -1; + } + + /* creating the window */ + window = xcb_generate_id (c); + mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK; + values[0] = screen->white_pixel; + values[1] = + XCB_EVENT_MASK_KEY_RELEASE | + XCB_EVENT_MASK_BUTTON_PRESS | + XCB_EVENT_MASK_EXPOSURE | + XCB_EVENT_MASK_POINTER_MOTION; + cookie_window = xcb_create_window_checked (c, + screen->root_depth, + window, screen->root, + 20, 200, WIDTH, HEIGHT, + 0, XCB_WINDOW_CLASS_INPUT_OUTPUT, + screen->root_visual, + mask, values); + cookie_map = xcb_map_window_checked (c, window); + + /* error managing */ + error = xcb_request_check (c, cookie_window); + if (error) { + fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + error = xcb_request_check (c, cookie_map); + if (error) { + fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + + xcb_flush(c); + + while (1) { + e = xcb_poll_for_event(c); + if (e) { + switch (e->response_type & ~0x80) { + case XCB_EXPOSE: { + char *text; + + text = "Press ESC key to exit..."; + text_draw (c, screen, window, 10, HEIGHT - 10, text); + break; + } + case XCB_KEY_RELEASE: { + xcb_key_release_event_t *ev; + + ev = (xcb_key_release_event_t *)e; + + switch (ev->detail) { + /* ESC */ + case 9: + free (e); + xcb_disconnect (c); + return 0; + } + } + } + free (e); + } + } + + return 0; +}-
- It is used to contain information about a font, and is passed - to several functions that handle fonts selection and text drawing. -
After we have seen how to create windows and draw on them, we take one step back, and look at how our windows are interacting @@ -2119,134 +2373,133 @@ typedef struct { treat our application's windows.
- Many of the parameters communicated to the window manager are - passed using data called "properties". These properties are - attached by the X server to different windows, and are stores - in a format that makes it possible to read them from different - machines that may use different architectures (remember that - an X client program may run on a remote machine). -
-- The property and its type (a string, an integer, etc) are - Id. Their type are XCBATOM: -
--typedef struct { - CARD32 xid; -} XCBATOM; --
- To change the property of a window, we use the following - function: -
--XCBVoidCookie XCBChangeProperty (XCBConnection *c, /* Connection to the X server */ - CARD8 mode, /* Property mode */ - XCBWINDOW window, /* Window */ - XCBATOM property, /* Property to change */ - XCBATOM type, /* Type of the property */ - CARD8 format, /* Format of the property (8, 16, 32) */ - CARD32 data_len, /* Length of the data parameter */ - const void *data); /* Data */ --
- The mode parameter coud be one of - the following value (defined in the X.h header file): -
-- The firt thing we want to do would be to set the name for our - window. This is done using the - XCBChangeProperty() function. This - name may be used by the window manager as the title of the - window (in the title bar), in a task list, etc. The property - atom to use to set the name of a window is - WM_NAME (and - WM_ICON_NAME for the iconified - window) and its type is STRING. Here - is an example of utilization: -
-+
+ Many of the parameters communicated to the window manager are + passed using data called "properties". These properties are + attached by the X server to different windows, and are stored + in a format that makes it possible to read them from different + machines that may use different architectures (remember that + an X client program may run on a remote machine). +
++ The property and its type (a string, an integer, etc) are + Id. Their type are xcb_atom_t: +
++typedef uint32_t xcb_atom_t; ++
+ To change the property of a window, we use the following + function: +
++xcb_void_cookie_t xcb_change_property (xcb_connection_t *c, /* Connection to the X server */ + uint8_t mode, /* Property mode */ + xcb_window_t window, /* Window */ + xcb_atom_t property, /* Property to change */ + xcb_atom_t type, /* Type of the property */ + uint8_t format, /* Format of the property (8, 16, 32) */ + uint32_t data_len, /* Length of the data parameter */ + const void *data); /* Data */ ++
+ The mode parameter coud be one of + the following values (defined in enumeration xcb_prop_mode_t in + the xproto.h header file): +
++ The first thing we want to do would be to set the name for our + window. This is done using the + xcb_change_property() function. This + name may be used by the window manager as the title of the + window (in the title bar), in a task list, etc. The property + atom to use to set the name of a window is + WM_NAME (and + WM_ICON_NAME for the iconified + window) and its type is STRING. Here + is an example of utilization: +
+#include <string.h> -#include <X11/XCB/xcb.h> -#include <X11/XCB/xcb_atom.h> +#include <xcb/xcb.h> +#include <xcb/xcb_atom.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBDRAWABLE win; - char *title = "Hello World !"; - char *title_icon = "Hello World ! (iconified)"; + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_window_t win; + char *title = "Hello World !"; + char *title_icon = "Hello World ! (iconified)"; + - /* Open the connection to the X server */ - c = XCBConnect (NULL, NULL); - + c = xcb_connect (NULL, NULL); + /* Get the first screen */ - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; /* Ask for our window's Id */ - win.window = XCBWINDOWNew(c); + win = xcb_generate_id (c); /* Create the window */ - XCBCreateWindow (c, /* Connection */ - 0, /* depth */ - win.window, /* window Id */ - screen->root, /* parent window */ - 0, 0, /* x, y */ - 250, 150, /* width, height */ - 10, /* border_width */ - InputOutput, /* class */ - screen->root_visual, /* visual */ - 0, NULL); /* masks, not used */ + xcb_create_window (c, /* Connection */ + 0, /* depth */ + win, /* window Id */ + screen->root, /* parent window */ + 0, 0, /* x, y */ + 250, 150, /* width, height */ + 10, /* border_width */ + XCB_WINDOW_CLASS_INPUT_OUTPUT, /* class */ + screen->root_visual, /* visual */ + 0, NULL); /* masks, not used */ /* Set the title of the window */ - XCBChangeProperty(c, PropModeReplace, win.window, - WM_NAME, STRING, 8, - strlen(title), title); + xcb_change_property (c, XCB_PROP_MODE_REPLACE, win, + WM_NAME, STRING, 8, + strlen (title), title); /* Set the title of the window icon */ - XCBChangeProperty(c, PropModeReplace, win.window, - WM_ICON_NAME, STRING, 8, - strlen(title_icon), title_icon); + xcb_change_property (c, XCB_PROP_MODE_REPLACE, win, + WM_ICON_NAME, STRING, 8, + strlen(title_icon), title_icon); /* Map the window on the screen */ - XCBMapWindow (c, win.window); + xcb_map_window (c, win); + + xcb_flush (c); - XCBSync (c, 0); - while (1) {} - return 1; + return 0; }-
Note: the use of the atoms needs our program to be compiled and linked against xcb_atom, so that we have to use -
-+ +
gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom`-
- for the program to compile fine. -
-One more thing we can do to our window is manipulate them on the screen (resize them, move them, raise or lower them, iconify @@ -2254,293 +2507,295 @@ gcc prog.c -o prog `pkg-config --cflags --libs xcb_atom` by XCB for this purpose.
- The first pair of operations we can apply on a window is - mapping it, or un-mapping it. Mapping a window causes the - window to appear on the screen, as we have seen in our simple - window program example. Un-mapping it causes it to be removed - from the screen (although the window as a logical entity still - exists). This gives the effect of making a window hidden - (unmapped) and shown again (mapped). For example, if we have a - dialog box window in our program, instead of creating it every - time the user asks to open it, we can create the window once, - in an un-mapped mode, and when the user asks to open it, we - simply map the window on the screen. When the user clicked the - 'OK' or 'Cancel' button, we simply un-map the window. This is - much faster than creating and destroying the window, however, - the cost is wasted resources, both on the client side, and on - the X server side. -
-- To map a window, you use the following function: -
--XCBVoidCookie XCBMapWindow(XCBConnection *c, XCBWINDOW window); --
- To have a simple example, see the example - above. The mapping operation will cause an - Expose event to be sent to our - application, unless the window is completely covered by other - windows. -
-- Un-mapping a window is also simple. You use the function -
--XCBVoidCookie XCBUnmapWindow(XCBConnection *c, XCBWINDOW window); --
- The utilization of this function is the same as - XCBMapWindow(). -
-- As we have seen when we have created our first window, in the - X Events subsection, we can set some attributes to the window - (that is, the position, the size, the events the window will - receive, etc). If we want to modify them, but the window is - already created, we can change them by using the following - function: -
--XCBVoidCookie XCBConfigureWindow (XCBConnection *c, /* The connection to the X server*/ - XCBWINDOW window, /* The window to configure */ - CARD16 value_mask, /* The mask */ - const CARD32 *value_list); /* The values to set */ --
- We set the value_mask to one or - several mask values that are in the X.h header: -
- We then give to value_mask the new - value. We now describe how to use - XCBConfigureWindow in some useful - situations. -
-- An operation we might want to do with windows is to move them - to a different location. This can be done like this: -
--const static CARD32 values[] = { 10, 20 }; +
+ The first pair of operations we can apply on a window is + mapping it, or un-mapping it. Mapping a window causes the + window to appear on the screen, as we have seen in our simple + window program example. Un-mapping it causes it to be removed + from the screen (although the window as a logical entity still + exists). This gives the effect of making a window hidden + (unmapped) and shown again (mapped). For example, if we have a + dialog box window in our program, instead of creating it every + time the user asks to open it, we can create the window once, + in an un-mapped mode, and when the user asks to open it, we + simply map the window on the screen. When the user clicked the + 'OK' or 'Cancel' button, we simply un-map the window. This is + much faster than creating and destroying the window, however, + the cost is wasted resources, both on the client side, and on + the X server side. +
++ To map a window, you use the following function: +
++xcb_void_cookie_t xcb_map_window (xcb_connection_t *c, + xcb_window_t window); ++
+ To have a simple example, see the example + above. The mapping operation will cause an + Expose event to be sent to our + application, unless the window is completely covered by other + windows. +
++ Un-mapping a window is also simple. You use the function +
++xcb_void_cookie_t xcb_unmap_window (xcb_connection_t *c, + xcb_window_t window); ++
+ The utilization of this function is the same as + xcb_map_window(). +
++ As we have seen when we have created our first window, in the + X Events subsection, we can set some attributes for the window + (that is, the position, the size, the events the window will + receive, etc). If we want to modify them, but the window is + already created, we can change them by using the following + function: +
++xcb_void_cookie_t xcb_configure_window (xcb_connection_t *c, /* The connection to the X server*/ + xcb_window_t window, /* The window to configure */ + uint16_t value_mask, /* The mask */ + const uint32_t *value_list); /* The values to set */ ++
+ We set the value_mask to one or + several mask values that are in the xcb_config_window_t enumeration in the xproto.h header: +
++ We then give to value_mask the new + value. We now describe how to use + xcb_configure_window_t in some useful + situations. +
++ An operation we might want to do with windows is to move them + to a different location. This can be done like this: +
++const static uint32_t values[] = { 10, 20 }; /* The connection c and the window win are supposed to be defined */ /* Move the window to coordinates x = 10 and y = 20 */ -XCBConfigureWindow (c, win, CWX | CWY, values); --
- Note that when the window is moved, it might get partially - exposed or partially hidden by other windows, and thus we - might get Expose events due to this - operation. -
-- Yet another operation we can do is to change the size of a - window. This is done using the following code: -
--const static CARD32 values[] = { 200, 300 }; +xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y, values); ++
+ Note that when the window is moved, it might get partially + exposed or partially hidden by other windows, and thus we + might get Expose events due to this + operation. +
++ Yet another operation we can do is to change the size of a + window. This is done using the following code: +
++const static uint32_t values[] = { 200, 300 }; /* The connection c and the window win are supposed to be defined */ /* Resize the window to width = 10 and height = 20 */ -XCBConfigureWindow (c, win, CWWidth | CWHeight, values); +xcb_configure_window (c, win, XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values);-
- We can also combine the move and resize operations using one - single call to XCBConfigureWindow: -
--const static CARD32 values[] = { 10, 20, 200, 300 }; ++ We can also combine the move and resize operations using one + single call to xcb_configure_window_t: +
++const static uint32_t values[] = { 10, 20, 200, 300 }; /* The connection c and the window win are supposed to be defined */ /* Move the window to coordinates x = 10 and y = 20 */ /* and resize the window to width = 10 and height = 20 */ -XCBConfigureWindow (c, win, CWX | CWY | CWWidth | CWHeight, values); --
- Until now, we changed properties of a single window. We'll see - that there are properties that relate to the window and other - windows. One of hem is the stacking order. That is, the order - in which the windows are layered on top of each other. The - front-most window is said to be on the top of the stack, while - the back-most window is at the bottom of the stack. Here is - how to manipulate our windows stack order: -
--const static CARD32 values[] = { Above }; +xcb_configure_window (c, win, XCB_CONFIG_WINDOW_X | XCB_CONFIG_WINDOW_Y | XCB_CONFIG_WINDOW_WIDTH | XCB_CONFIG_WINDOW_HEIGHT, values); ++
+ Until now, we changed properties of a single window. We'll see + that there are properties that relate to the window and other + windows. One of them is the stacking order. That is, the order + in which the windows are layered on top of each other. The + front-most window is said to be on the top of the stack, while + the back-most window is at the bottom of the stack. Here is + how to manipulate our windows stack order: +
++const static uint32_t values[] = { XCB_STACK_MODE_ABOVE }; /* The connection c and the window win are supposed to be defined */ /* Move the window on the top of the stack */ -XCBConfigureWindow (c, win, CWStackMode, values); +xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values);-
-const static CARD32 values[] = { Below }; ++const static uint32_t values[] = { XCB_STACK_MODE_BELOW }; /* The connection c and the window win are supposed to be defined */ /* Move the window on the bottom of the stack */ -XCBConfigureWindow (c, win, CWStackMode, values); --
- Just like we can set various attributes of our windows, we can - also ask the X server supply the current values of these - attributes. For example, we can check where a window is - located on the screen, what is its current size, whether it is - mapped or not, etc. The structure that contains some of this - information is -
-+xcb_configure_window (c, win, XCB_CONFIG_WINDOW_STACK_MODE, values); ++
+ Just like we can set various attributes of our windows, we can + also ask the X server supply the current values of these + attributes. For example, we can check where a window is + located on the screen, what is its current size, whether it is + mapped or not, etc. The structure that contains some of this + information is +
+typedef struct { - BYTE response_type; - CARD8 depth; /* depth of the window */ - CARD16 sequence; - CARD32 length; - XCBWINDOW root; /* Id of the root window *> - INT16 x; /* X coordinate of the window's location */ - INT16 y; /* Y coordinate of the window's location */ - CARD16 width; /* Width of the window */ - CARD16 height; /* Height of the window */ - CARD16 border_width; /* Width of the window's border */ -} XCBGetGeometryRep; --
- XCB fill this structure with two functions: -
--XCBGetGeometryCookie XCBGetGeometry (XCBConnection *c, - XCBDRAWABLE drawable); -XCBGetGeometryRep *XCBGetGeometryReply (XCBConnection *c, - XCBGetGeometryCookie cookie, - XCBGenericError **e); --
- You use them as follows: -
-- XCBConnection *c; - XCBDRAWABLE win; - XCBGetGeometryRep *geom; + uint8_t response_type; + uint8_t depth; /* depth of the window */ + uint16_t sequence; + uint32_t length; + xcb_window_t root; /* Id of the root window *> + int16_t x; /* X coordinate of the window's location */ + int16_t y; /* Y coordinate of the window's location */ + uint16_t width; /* Width of the window */ + uint16_t height; /* Height of the window */ + uint16_t border_width; /* Width of the window's border */ +} xcb_get_geometry_reply_t; ++
+ XCB fill this structure with two functions: +
++xcb_get_geometry_cookie_t xcb_get_geometry (xcb_connection_t *c, + xcb_drawable_t drawable); +xcb_get_geometry_reply_t *xcb_get_geometry_reply (xcb_connection_t *c, + xcb_get_geometry_cookie_t cookie, + xcb_generic_error_t **e); ++
+ You use them as follows: +
++ xcb_connection_t *c; + xcb_drawable_t win; + xcb_get_geometry_reply_t *geom; /* You initialize c and win */ - geom = XCBGetGeometryReply (c, XCBGetGeometry (c, win), 0); + geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL); /* Do something with the fields of geom */ - + free (geom);
- Remark that you have to free the structure, as - XCBGetGeometryReply allocates a - newly one. -
-- One problem is that the returned location of the window is - relative to its parent window. This makes these coordinates - rather useless for any window manipulation functions, like - moving it on the screen. In order to overcome this problem, we - need to take a two-step operation. First, we find out the Id - of the parent window of our window. We then translate the - above relative coordinates to the screen coordinates. -
-- To get the Id of the parent window, we need this structure: -
--typedef struct { - BYTE response_type; - CARD8 pad0; - CARD16 sequence; - CARD32 length; - XCBWINDOW root; - XCBWINDOW parent; /* Id of the parent window */ - CARD16 children_len; - CARD8 pad1[14]; -} XCBQueryTreeRep; --
- To fill this structure, we use these two functions: -
--XCBQueryTreeCookie XCBQueryTree (XCBConnection *c, - XCBWINDOW window); -XCBQueryTreeRep *XCBQueryTreeReply (XCBConnection *c, - XCBQueryTreeCookie cookie, - XCBGenericError **e); --
- The translated coordinates will be found in this structure: -
--typedef struct { - BYTE response_type; - BOOL same_screen; - CARD16 sequence; - CARD32 length; - XCBWINDOW child; - CARD16 dst_x; /* Translated x coordinate */ - CARD16 dst_y; /* Translated y coordinate */ -} XCBTranslateCoordinatesRep; --
- As usual, we need two functions to fill this structure: -
--XCBTranslateCoordinatesCookie XCBTranslateCoordinates (XCBConnection *c, - XCBWINDOW src_window, - XCBWINDOW dst_window, - INT16 src_x, - INT16 src_y); -XCBTranslateCoordinatesRep *XCBTranslateCoordinatesReply (XCBConnection *c, - XCBTranslateCoordinatesCookie cookie, - XCBGenericError **e); --
- We use them as follows: -
-- XCBConnection *c; - XCBDRAWABLE win; - XCBGetGeometryRep *geom; - XCBQueryTreeRep *tree; - XCBTranslateCoordinatesRep *trans; + Remark that you have to free the structure, as + xcb_get_geometry_reply_t allocates a + newly one. + ++ One problem is that the returned location of the window is + relative to its parent window. This makes these coordinates + rather useless for any window manipulation functions, like + moving it on the screen. In order to overcome this problem, we + need to take a two-step operation. First, we find out the Id + of the parent window of our window. We then translate the + above relative coordinates to the screen coordinates. +
++ To get the Id of the parent window, we need this structure: +
++typedef struct { + uint8_t response_type; + uint8_t pad0; + uint16_t sequence; + uint32_t length; + xcb_window_t root; + xcb_window_t parent; /* Id of the parent window */ + uint16_t children_len; + uint8_t pad1[14]; +} xcb_query_tree_reply_t; +++ To fill this structure, we use these two functions: +
++xcb_query_tree_cookie_t xcb_query_tree (xcb_connection_t *c, + xcb_window_t window); +xcb_query_tree_reply_t *xcb_query_tree_reply (xcb_connection_t *c, + xcb_query_tree_cookie_t cookie, + xcb_generic_error_t **e); +++ The translated coordinates will be found in this structure: +
++typedef struct { + uint8_t response_type; + uint8_t same_screen; + uint16_t sequence; + uint32_t length; + xcb_window_t child; + uint16_t dst_x; /* Translated x coordinate */ + uint16_t dst_y; /* Translated y coordinate */ +} xcb_translate_coordinates_reply_t; +++ As usual, we need two functions to fill this structure: +
++xcb_translate_coordinates_cookie_t xcb_translate_coordinates (xcb_connection_t *c, + xcb_window_t src_window, + xcb_window_t dst_window, + int16_t src_x, + int16_t src_y); +xcb_translate_coordinates_reply_t *xcb_translate_coordinates_reply (xcb_connection_t *c, + xcb_translate_coordinates_cookie_t cookie, + xcb_generic_error_t **e); +++ We use them as follows: +
++ xcb_connection_t *c; + xcb_drawable_t win; + xcb_get_geometry_reply_t *geom; + xcb_query_tree_reply_t *tree; + xcb_translate_coordinates_reply_t *trans; /* You initialize c and win */ - geom = XCBGetGeometryReply (c, XCBGetGeometry (c, win), 0); + geom = xcb_get_geometry_reply (c, xcb_get_geometry (c, win), NULL); if (!geom) return 0; - tree = XCBQueryTreeReply (c, XCBQueryTree (c, win), 0); + tree = xcb_query_tree_reply (c, xcb_query_tree (c, win), NULL); if (!tree) return 0; - trans = XCBTranslateCoordinatesReply (c, - XCBTranslateCoordinates (c, - win, - tree->parent, - geom->x, geom->y), - 0); + trans = xcb_translate_coordinates_reply (c, + xcb_translate_coordinates (c, + win, + tree->parent, + geom->x, geom->y), + NULL); if (!trans) return 0; @@ -2551,329 +2806,327 @@ XCBTranslateCoordinatesRep *XCBTranslateCoordinatesReply (XCBConnection free (geom);- Of course, as for geom, - tree and - trans have to be freed. -
-- The work is a bit hard, but XCB is a very low-level library. -
-- TODO: the utilization of these functions should be a - prog, which displays the coordinates of the window. -
-- There is another structure that gives informations about our window: -
-+ Of course, as for geom, + tree and + trans have to be freed. + ++ The work is a bit hard, but XCB is a very low-level library. +
++ TODO: the utilization of these functions should be a + prog, which displays the coordinates of the window. +
++ There is another structure that gives informations about our window: +
+typedef struct { - BYTE response_type; - CARD8 backing_store; - CARD16 sequence; - CARD32 length; - XCBVISUALID visual; /* Visual of the window */ - CARD16 _class; - CARD8 bit_gravity; - CARD8 win_gravity; - CARD32 backing_planes; - CARD32 backing_pixel; - BOOL save_under; - BOOL map_is_installed; - CARD8 map_state; /* Map state of the window */ - BOOL override_redirect; - XCBCOLORMAP colormap; /* Colormap of the window */ - CARD32 all_event_masks; - CARD32 your_event_mask; - CARD16 do_not_propagate_mask; -} XCBGetWindowAttributesRep; --- XCB supplies these two functions to fill it: -
--XCBGetWindowAttributesCookie XCBGetWindowAttributes (XCBConnection *c, - XCBWINDOW window); -XCBGetWindowAttributesRep *XCBGetWindowAttributesReply (XCBConnection *c, - XCBGetWindowAttributesCookie cookie, - XCBGenericError **e); --- You use them as follows: -
-- XCBConnection *c; - XCBDRAWABLE win; - XCBGetWindowAttributesRep *attr; + uint8_t response_type; + uint8_t backing_store; + uint16_t sequence; + uint32_t length; + xcb_visualid_t visual; /* Visual of the window */ + uint16_t _class; + uint8_t bit_gravity; + uint8_t win_gravity; + uint32_t backing_planes; + uint32_t backing_pixel; + uint8_t save_under; + uint8_t map_is_installed; + uint8_t map_state; /* Map state of the window */ + uint8_t override_redirect; + xcb_colormap_t colormap; /* Colormap of the window */ + uint32_t all_event_masks; + uint32_t your_event_mask; + uint16_t do_not_propagate_mask; +} xcb_get_window_attributes_reply_t; +++ XCB supplies these two functions to fill it: +
++xcb_get_window_attributes_cookie_t xcb_get_window_attributes (xcb_connection_t *c, + xcb_window_t window); +xcb_get_window_attributes_reply_t *xcb_get_window_attributes_reply (xcb_connection_t *c, + xcb_get_window_attributes_cookie_t cookie, + xcb_generic_error_t **e); +++ You use them as follows: +
++ xcb_connection_t *c; + xcb_drawable_t win; + xcb_get_window_attributes_reply_t *attr; /* You initialize c and win */ - attr = XCBGetWindowAttributesReply (c, XCBGetWindowAttributes (c, win), 0); + attr = xcb_get_window_attributes_reply (c, xcb_get_window_attributes (c, win), NULL); if (!attr) return 0; /* Do something with the fields of attr */ - + free (attr);- As for geom, - attr has to be freed. -
+ As for geom, + attr has to be freed. +
Up until now, all our painting operation were done using black and white. We will (finally) see now how to draw using colors.
- In the beginning, there were not enough colors. Screen - controllers could only support a limited number of colors - simultaneously (initially 2, then 4, 16 and 256). Because of - this, an application could not just ask to draw in a "light - purple-red" color, and expect that color to be available. Each - application allocated the colors it needed, and when all the - color entries (4, 16, 256 colors) were in use, the next color - allocation would fail. -
-- Thus, the notion of "a color map" was introduced. A color map - is a table whose size is the same as the number of - simultaneous colors a given screen controller. Each entry - contained the RGB (Red, Green and Blue) values of a different - color (all colors can be drawn using some combination of red, - green and blue). When an application wants to draw on the - screen, it does not specify which color to use. Rather, it - specifies which color entry of some color map to be used - during this drawing. Change the value in this color map entry - and the drawing will use a different color. -
-- In order to be able to draw using colors that got something to - do with what the programmer intended, color map allocation - functions are supplied. You could ask to allocate entry for a - color with a set of RGB values. If one already existed, you - would get its index in the table. If none existed, and the - table was not full, a new cell would be allocated to contain - the given RGB values, and its index returned. If the table was - full, the procedure would fail. You could then ask to get a - color map entry with a color that is closest to the one you - were asking for. This would mean that the actual drawing on - the screen would be done using colors similar to what you - wanted, but not the same. -
-- On today's more modern screens where one runs an X server with - support for 16 million colors, this limitation looks a little - silly, but remember that there are still older computers with - older graphics cards out there. Using color map, support for - these screen becomes transparent to you. On a display - supporting 16 million colors, any color entry allocation - request would succeed. On a display supporting a limited - number of colors, some color allocation requests would return - similar colors. It won't look as good, but your application - would still work. -
-- When you draw using XCB, you can choose to use the standard - color map of the screen your window is displayed on, or you - can allocate a new color map and apply it to a window. In the - latter case, each time the mouse moves onto your window, the - screen color map will be replaced by your window's color map, - and you'll see all the other windows on screen change their - colors into something quite bizzare. In fact, this is the - effect you get with X applications that use the "-install" - command line option. -
-- In XCB, a color map is (as often in X) an Id: -
--typedef struct { - CARD32 xid; -} XCBCOLORMAP; --
- In order to access the screen's default color map, you just - have to retrieve the default_colormap - field of the XCBSCREEN structure - (see Section - Checking basic information about a connection): -
-+
+ In the beginning, there were not enough colors. Screen + controllers could only support a limited number of colors + simultaneously (initially 2, then 4, 16 and 256). Because of + this, an application could not just ask to draw in a "light + purple-red" color, and expect that color to be available. Each + application allocated the colors it needed, and when all the + color entries (4, 16, 256 colors) were in use, the next color + allocation would fail. +
++ Thus, the notion of "a color map" was introduced. A color map + is a table whose size is the same as the number of + simultaneous colors a given screen controller. Each entry + contained the RGB (Red, Green and Blue) values of a different + color (all colors can be drawn using some combination of red, + green and blue). When an application wants to draw on the + screen, it does not specify which color to use. Rather, it + specifies which color entry of some color map to be used + during this drawing. Change the value in this color map entry + and the drawing will use a different color. +
++ In order to be able to draw using colors that got something to + do with what the programmer intended, color map allocation + functions are supplied. You could ask to allocate entry for a + color with a set of RGB values. If one already existed, you + would get its index in the table. If none existed, and the + table was not full, a new cell would be allocated to contain + the given RGB values, and its index returned. If the table was + full, the procedure would fail. You could then ask to get a + color map entry with a color that is closest to the one you + were asking for. This would mean that the actual drawing on + the screen would be done using colors similar to what you + wanted, but not the same. +
++ On today's more modern screens where one runs an X server with + support for 16 million colors, this limitation looks a little + silly, but remember that there are still older computers with + older graphics cards out there. Using color map, support for + these screen becomes transparent to you. On a display + supporting 16 million colors, any color entry allocation + request would succeed. On a display supporting a limited + number of colors, some color allocation requests would return + similar colors. It won't look as good, but your application + would still work. +
++ When you draw using XCB, you can choose to use the standard + color map of the screen your window is displayed on, or you + can allocate a new color map and apply it to a window. In the + latter case, each time the mouse moves onto your window, the + screen color map will be replaced by your window's color map, + and you'll see all the other windows on screen change their + colors into something quite bizzare. In fact, this is the + effect you get with X applications that use the "-install" + command line option. +
++ In XCB, a color map is (as often in X) an Id: +
++typedef uint32_t xcb_colormap_t; ++
+ In order to access the screen's default color map, you just + have to retrieve the default_colormap + field of the xcb_screen_t structure + (see Section + Checking basic information about a connection): +
+#include <stdio.h> -#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBCOLORMAP colormap; - + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_colormap_t colormap; + /* Open the connection to the X server and get the first screen */ - c = XCBConnect (NULL, NULL); - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + c = xcb_connect (NULL, NULL); + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; colormap = screen->default_colormap; - return 1; + return 0; }-
- This will return the color map used by default on the first - screen (again, remember that an X server may support several - different screens, each of which might have its own resources). -
-- The other option, that of allocating a new colormap, works as - follows. We first ask the X server to give an Id to our color - map, with this function: -
--XCBCOLORMAP XCBCOLORMAPNew (XCBConnection *c); --
- Then, we create the color map with -
--XCBVoidCookie XCBCreateColormap (XCBConnection *c, /* Pointer to the XCBConnection structure */ - BYTE alloc, /* Colormap entries to be allocated (AllocNone or AllocAll) */ - XCBCOLORMAP mid, /* Id of the color map */ - XCBWINDOW window, /* Window on whose screen the colormap will be created */ - XCBVISUALID visual); /* Id of the visual supported by the screen */ --
- Here is an example of creation of a new color map: -
--#include <X11/XCB/xcb.h> ++ This will return the color map used by default on the first + screen (again, remember that an X server may support several + different screens, each of which might have its own resources). +
++ The other option, that of allocating a new colormap, works as + follows. We first ask the X server to give an Id to our color + map, with this function: +
++xcb_colormap_t xcb_generate_id (xcb_connection_t *c); +++ Then, we create the color map with +
++xcb_void_cookie_t xcb_create_colormap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */ + uint8_t alloc, /* Colormap entries to be allocated (AllocNone or AllocAll) */ + xcb_colormap_t mid, /* Id of the color map */ + xcb_window_t window, /* Window on whose screen the colormap will be created */ + xcb_visualid_t visual); /* Id of the visual supported by the screen */ +++ Here is an example of creation of a new color map: +
++#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBWINDOW win; - XCBCOLORMAP cmap - + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_window_t win; + xcb_colormap_t cmap + /* Open the connection to the X server and get the first screen */ - c = XCBConnect (NULL, NULL); - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + c = xcb_connect (NULL, NULL); + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; /* We create the window win here*/ - cmap = XCBCOLORMAPNew (c); - XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual); + cmap = xcb_generate_id (c); + xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual); - return 1; + return 0; }- Note that the window parameter is only used to allow the X - server to create the color map for the given screen. We can - then use this color map for any window drawn on the same screen. -
-- To free a color map, it suffices to use this function: -
--XCBVoidCookie XCBFreeColormap (XCBConnection *c, /* The connection */ - XCBCOLORMAP cmap); /* The color map */ + Note that the window parameter is only used to allow the X + server to create the color map for the given screen. We can + then use this color map for any window drawn on the same screen. + ++ To free a color map, it suffices to use this function: +
++xcb_void_cookie_t xcb_free_colormap (xcb_connection_t *c, /* The connection */ + xcb_colormap_t cmap); /* The color map */- -- Comparison Xlib/XCB + Comparison Xlib/XCB +++++
+- XCreateColormap () +
+++
+- xcb_generate_id () +
- xcb_create_colormap () +
+++
+- XFreeColormap () +
+-+
- xcb_free_colormap () +
---
-- XCreateColormap ()
----
-- XCBCOLORMAPNew ()
-- XCBCreateColormap ()
----
-- XFreeColormap ()
---
-- XCBFreeColormap ()
-
- Once we got access to some color map, we can start allocating - colors. The informations related to a color are stored in the - following structure: -
-+
+
+ Once we got access to some color map, we can start allocating + colors. The informations related to a color are stored in the + following structure: +
+typedef struct { - BYTE response_type; - CARD8 pad0; - CARD16 sequence; - CARD32 length; - CARD16 red; /* The red component */ - CARD16 green; /* The green component */ - CARD16 blue; /* The blue component */ - CARD8 pad1[2]; - CARD32 pixel; /* The entry in the color map, supplied by the X server */ -} XCBAllocColorRep; + uint8_t response_type; + uint8_t pad0; + uint16_t sequence; + uint32_t length; + uint16_t red; /* The red component */ + uint16_t green; /* The green component */ + uint16_t blue; /* The blue component */ + uint8_t pad1[2]; + uint32_t pixel; /* The entry in the color map, supplied by the X server */ +} xcb_alloc_color_reply_t;
XCB supplies these two functions to fill it:
-XCBAllocColorCookie XCBAllocColor (XCBConnection *c, - XCBCOLORMAP cmap, - CARD16 red, - CARD16 green, - CARD16 blue); -XCBAllocColorRep *XCBAllocColorReply (XCBConnection *c, - XCBAllocColorCookie cookie, - XCBGenericError **e); +xcb_alloc_color_cookie_t xcb_alloc_color (xcb_connection_t *c, + xcb_colormap_t cmap, + uint16_t red, + uint16_t green, + uint16_t blue); +xcb_alloc_color_reply_t *xcb_alloc_color_reply (xcb_connection_t *c, + xcb_alloc_color_cookie_t cookie, + xcb_generic_error_t **e);
- The fuction XCBAllocColor() takes the + The fuction xcb_alloc_color() takes the 3 RGB components as parameters (red, green and blue). Here is an example of using these functions:
#include <malloc.h> -#include <X11/XCB/xcb.h> +#include <xcb/xcb.h> int -main (int argc, char *argv[]) +main () { - XCBConnection *c; - XCBSCREEN *screen; - XCBWINDOW win; - XCBCOLORMAP cmap; - XCBAllocColorRep *rep; - + xcb_connection_t *c; + xcb_screen_t *screen; + xcb_window_t win; + xcb_colormap_t cmap; + xcb_alloc_color_reply_t *rep; + /* Open the connection to the X server and get the first screen */ - c = XCBConnect (NULL, NULL); - screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data; + c = xcb_connect (NULL, NULL); + screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data; /* We create the window win here*/ - cmap = XCBCOLORMAPNew (c); - XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual); + cmap = xcb_generate_id (c); + xcb_create_colormap (c, XCB_COLORMAP_ALLOC_NONE, cmap, win, screen->root_visual); + + rep = xcb_alloc_color_reply (c, xcb_alloc_color (c, cmap, 65535, 0, 0), NULL); - rep = XCBAllocColorReply (c, XCBAllocColor (c, cmap, 65535, 0, 0), 0); - if (!rep) return 0; @@ -2881,18 +3134,18 @@ main (int argc, char *argv[]) free (rep); - return 1; + return 0; }
- As XCBAllocColorReply() allocates + As xcb_alloc_color_reply() allocates memory, you have to free rep.
TODO: Talk about freeing colors.
One thing many so-called "Multi-Media" applications need to do, is display images. In the X world, this is done using bitmaps @@ -2910,146 +3163,635 @@ main (int argc, char *argv[]) pixmaps).
- An X bitmap is a two-color image stored in a format specific - to the X window system. When stored in a file, the bitmap data - looks like a C source file. It contains variables defining the - width and the height of the bitmap, an array containing the - bit values of the bitmap (the size of the array is - weight*height), and an optional hot-spot location (that will - be explained later, when discussing mouse cursors). -
-- An X pixmap is a format used to stored images in the memory of - an X server. This format can store both black and white images - (such as x bitmaps) as well as color images. It is the only - image format supported by the X protocol, and any image to be - drawn on screen, should be first translated into this format. -
-- In actuality, an X pixmap can be thought of as a window that - does not appear on the screen. Many graphics operations that - work on windows, will also work on pixmaps. Indeed, the type - of X pixmap in XCB is an Id like a window: -
--typedef struct { - CARD32 xid; -} XCBPIXMAP; --
- In order to make the difference between a window and a pixmap, - XCB introduces a drawable type, which is a union -
--typedef union { - XCBWINDOW window; - XCBPIXMAP pixmap; -} XCBDRAWABLE; --
- in order to avoid confusion between a window and a pixmap. The - operations that will work indifferently on a window or a pixmap - will require a XCBDRAWABLE -
-- Remark: In Xlib, there is no specific difference between a - Drawable, a - Pixmap or a - Window: all are 32 bit long - integer. -
-- Sometimes we want to create an un-initialized pixmap, so we - can later draw into it. This is useful for image drawing - programs (creating a new empty canvas will cause the creation - of a new pixmap on which the drawing can be stored). It is - also useful when reading various image formats: we load the - image data into memory, create a pixmap on the server, and - then draw the decoded image data onto that pixmap. -
-- To create a new pixmap, we first ask the X server to give an - Id to our pixmap, with this function: -
--XCBPIXMAP XCBPIXMAPNew (XCBConnection *c); --
- Then, XCB supplies the following function to create new pixmaps: -
--XCBVoidCookie XCBCreatePixmap (XCBConnection *c, /* Pointer to the XCBConnection structure */ - CARD8 depth, /* Depth of the screen */ - XCBPIXMAP pid, /* Id of the pixmap */ - XCBDRAWABLE drawable, - CARD16 width, /* Width of the window (in pixels) */ - CARD16 height); /* Height of the window (in pixels) */ --
- TODO: Explain the drawable parameter, and give an - example (like xpoints.c) -
-- Once we got a handle to a pixmap, we can draw it on some - window, using the following function: -
--XCBVoidCookie XCBCopyArea (XCBConnection *c, /* Pointer to the XCBConnection structure */ - XCBDRAWABLE src_drawable, /* The Drawable we want to paste */ - XCBDRAWABLE dst_drawable, /* The Drawable on which we copy the previous Drawable */ - XCBGCONTEXT gc, /* A Graphic Context */ - INT16 src_x, /* Top left x coordinate of the region we want to copy */ - INT16 src_y, /* Top left y coordinate of the region we want to copy */ - INT16 dst_x, /* Top left x coordinate of the region where we want to copy */ - INT16 dst_y, /* Top left y coordinate of the region where we want to copy */ - CARD16 width, /* Width of the region we want to copy */ - CARD16 height); /* Height of the region we want to copy */ --
- As you can see, we could copy the whole pixmap, as well as - only a given rectangle of the pixmap. This is useful to - optimize the drawing speed: we could copy only what we have - modified in the pixmap. -
-- One important note should be made: it is possible to - create pixmaps with different depths on the same screen. When - we perform copy operations (a pixmap onto a window, etc), we - should make sure that both source and target have the same - depth. If they have a different depth, the operation would - fail. The exception to this is if we copy a specific bit plane - of the source pixmap using the - XCBCopyPlane function. In such an - event, we can copy a specific plain to the target window (in - actuality, setting a specific bit in the color of each pixel - copied). This can be used to generate strange graphic effects - in widow, but that is beyond the scope of this tutorial. -
-- Finally, when we are done using a given pixmap, we should free - it, in order to free resources of the X server. This is done - using this function: -
--XCBVoidCookie XCBFreePixmap (XCBConnection *c, /* Pointer to the XCBConnection structure */ - XCBPIXMAP pixmap); /* A given pixmap */ --
- Of course, after having freed it, we must not try accessing - the pixmap again. -
-- TODO: Give an example, or a link to xpoints.c -
++ An X bitmap is a two-color image stored in a format specific + to the X window system. When stored in a file, the bitmap data + looks like a C source file. It contains variables defining the + width and the height of the bitmap, an array containing the + bit values of the bitmap (the size of the array is + (width+7)/8*height and the bit and byte order are LSB), and + an optional hot-spot location (that will + be explained later, when discussing mouse cursors). +
++ An X pixmap is a format used to stored images in the memory of + an X server. This format can store both black and white images + (such as x bitmaps) as well as color images. It is the only + image format supported by the X protocol, and any image to be + drawn on screen, should be first translated into this format. +
++ In actuality, an X pixmap can be thought of as a window that + does not appear on the screen. Many graphics operations that + work on windows, will also work on pixmaps. Indeed, the type + of X pixmap in XCB is an Id like a window: +
++typedef uint32_t xcb_pixmap_t; ++
+ Like Xlib, there is no difference between a Drawable, a Window + or a Pixmap: +
++typedef uint32_t xcb_drawable_t; ++
+ in order to avoid confusion between a window and a pixmap. The + operations that will work the same on a window or a pixmap + will require a xcb_drawable_t +
++ Remark: In Xlib, there is no specific difference between a + Drawable, a + Pixmap or a + Window: all are 32 bit long + integer. XCB wraps all these different IDs in structures to + provide some measure of type-safety. +
++ Sometimes we want to create an un-initialized pixmap, so we + can later draw into it. This is useful for image drawing + programs (creating a new empty canvas will cause the creation + of a new pixmap on which the drawing can be stored). It is + also useful when reading various image formats: we load the + image data into memory, create a pixmap on the server, and + then draw the decoded image data onto that pixmap. +
++ To create a new pixmap, we first ask the X server to give an + Id to our pixmap, with this function: +
++xcb_pixmap_t xcb_generate_id (xcb_connection_t *c); ++
+ Then, XCB supplies the following function to create new pixmaps: +
++xcb_void_cookie_t xcb_create_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */ + uint8_t depth, /* Depth of the screen */ + xcb_pixmap_t pid, /* Id of the pixmap */ + xcb_drawable_t drawable, + uint16_t width, /* Width of the window (in pixels) */ + uint16_t height); /* Height of the window (in pixels) */ ++
+ TODO: Explain the drawable parameter, and give an + example (like xpoints.c) +
++ Once we got a handle to a pixmap, we can draw it on some + window, using the following function: +
++xcb_void_cookie_t xcb_copy_area (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */ + xcb_drawable_t src_drawable, /* The Drawable we want to paste */ + xcb_drawable_t dst_drawable, /* The Drawable on which we copy the previous Drawable */ + xcb_gcontext_t gc, /* A Graphic Context */ + int16_t src_x, /* Top left x coordinate of the region we want to copy */ + int16_t src_y, /* Top left y coordinate of the region we want to copy */ + int16_t dst_x, /* Top left x coordinate of the region where we want to copy */ + int16_t dst_y, /* Top left y coordinate of the region where we want to copy */ + uint16_t width, /* Width of the region we want to copy */ + uint16_t height); /* Height of the region we want to copy */ ++
+ As you can see, we could copy the whole pixmap, as well as + only a given rectangle of the pixmap. This is useful to + optimize the drawing speed: we could copy only what we have + modified in the pixmap. +
++ One important note should be made: it is possible to + create pixmaps with different depths on the same screen. When + we perform copy operations (a pixmap onto a window, etc), we + should make sure that both source and target have the same + depth. If they have a different depth, the operation would + fail. The exception to this is if we copy a specific bit plane + of the source pixmap using the + xcb_copy_plane_t function. In such an + event, we can copy a specific plane to the target window (in + actuality, setting a specific bit in the color of each pixel + copied). This can be used to generate strange graphic effects + in a window, but that is beyond the scope of this tutorial. +
++ Finally, when we are done using a given pixmap, we should free + it, in order to free resources of the X server. This is done + using this function: +
++xcb_void_cookie_t xcb_free_pixmap (xcb_connection_t *c, /* Pointer to the xcb_connection_t structure */ + xcb_pixmap_t pixmap); /* A given pixmap */ ++
+ Of course, after having freed it, we must not try accessing + the pixmap again. +
++ TODO: Give an example, or a link to xpoints.c +
++ It it possible to modify the shape of the mouse pointer (also + called the X pointer) when in certain states, as we otfen see in + programs. For example, a busy application would often display + the sand clock over its main window, to give the user a visual + hint that he should wait. Let's see how we can change the mouse + cursor of our windows. +
++ There are two methods for creating cursors. One of them is by + using a set of predefined cursors, that are supplied by the X + server, the other is by using a user-supplied bitmap. +
++ In the first method, we use a special font named "cursor", and + the function xcb_create_glyph_cursor: +
++xcb_void_cookie_t xcb_create_glyph_cursor (xcb_connection_t *c, + xcb_cursor_t cid, + xcb_font_t source_font, /* font for the source glyph */ + xcb_font_t mask_font, /* font for the mask glyph or XCB_NONE */ + uint16_t source_char, /* character glyph for the source */ + uint16_t mask_char, /* character glyph for the mask */ + uint16_t fore_red, /* red value for the foreground of the source */ + uint16_t fore_green, /* green value for the foreground of the source */ + uint16_t fore_blue, /* blue value for the foreground of the source */ + uint16_t back_red, /* red value for the background of the source */ + uint16_t back_green, /* green value for the background of the source */ + uint16_t back_blue) /* blue value for the background of the source */ ++
+ TODO: Describe source_char + and mask_char, for example by giving + an example on how to get the values. There is a list there: + X Font Cursors +
++ So we first open that font (see Loading a Font) + and create the new cursor. As for every X ressource, we have to + ask for an X id with xcb_generate_id + first: +
++xcb_font_t font; +xcb_cursor_t cursor; + +/* The connection is set */ + +font = xcb_generate_id (conn); +xcb_open_font (conn, font, strlen ("cursor"), "cursor"); + +cursor = xcb_generate_id (conn); +xcb_create_glyph_cursor (conn, cursor, font, font, + 58, 58 + 1, + 0, 0, 0, + 0, 0, 0); ++
+ We have created the cursor "right hand" by specifying 58 to + the source_font argument and 58 + 1 + to the mask_font. +
++ The cursor is destroyed by using the function +
++xcb_void_cookie_t xcb_free_cursor (xcb_connection_t *c, + xcb_cursor_t cursor); ++
+ In the second method, we create a new cursor by using a pair + of pixmaps, with depth of one (that is, two colors + pixmaps). One pixmap defines the shape of the cursor, while + the other works as a mask, specifying which pixels of the + cursor will be actually drawn. The rest of the pixels will be + transparent. +
++ TODO: give an example. +
++ Once the cursor is created, we can modify the cursor of our + window by using xcb_change_window_attributes + and using the XCB_CWCURSOR attribute: +
++uint32_t mask; +uint32_t value_list; + +/* The connection and window are set */ +/* The cursor is already created */ + +mask = XCB_CWCURSOR; +value_list = cursor; +xcb_change_window_attributes (conn, window, mask, &value_list); ++
+ Of course, the cursor and the font must be freed. +
++ The following example displays a window with a + button. When entering the window, the window cursor is changed + to an arrow. When clicking once on the button, the cursor is + changed to a hand. When clicking again on the button, the + cursor window gets back to the arrow. The Esc key exits the + application. +
++#include <stdlib.h> +#include <stdio.h> +#include <string.h> + +#include <xcb/xcb.h> + +#define WIDTH 300 +#define HEIGHT 150 + + + +static xcb_gc_t gc_font_get (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + const char *font_name); + +static void button_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label); + +static void text_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label); + +static void cursor_set (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int cursor_id); + + +static void +button_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label) +{ + xcb_point_t points[5]; + xcb_void_cookie_t cookie_gc; + xcb_void_cookie_t cookie_line; + xcb_void_cookie_t cookie_text; + xcb_generic_error_t *error; + xcb_gcontext_t gc; + int16_t width; + int16_t height; + uint8_t length; + int16_t inset; + + length = strlen (label); + inset = 2; + + gc = gc_font_get(c, screen, window, "7x13"); + + width = 7 * length + 2 * (inset + 1); + height = 13 + 2 * (inset + 1); + points[0].x = x1; + points[0].y = y1; + points[1].x = x1 + width; + points[1].y = y1; + points[2].x = x1 + width; + points[2].y = y1 - height; + points[3].x = x1; + points[3].y = y1 - height; + points[4].x = x1; + points[4].y = y1; + cookie_line = xcb_poly_line_checked (c, XCB_COORD_MODE_ORIGIN, + window, gc, 5, points); + + error = xcb_request_check (c, cookie_line); + if (error) { + fprintf (stderr, "ERROR: can't draw lines : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_text = xcb_image_text_8_checked (c, length, window, gc, + x1 + inset + 1, + y1 - inset - 1, label); + error = xcb_request_check (c, cookie_text); + if (error) { + fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_gc = xcb_free_gc (c, gc); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } +} + +static void +text_draw (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int16_t x1, + int16_t y1, + const char *label) +{ + xcb_void_cookie_t cookie_gc; + xcb_void_cookie_t cookie_text; + xcb_generic_error_t *error; + xcb_gcontext_t gc; + uint8_t length; + + length = strlen (label); + + gc = gc_font_get(c, screen, window, "7x13"); + + cookie_text = xcb_image_text_8_checked (c, length, window, gc, + x1, + y1, label); + error = xcb_request_check (c, cookie_text); + if (error) { + fprintf (stderr, "ERROR: can't paste text : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_gc = xcb_free_gc (c, gc); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't free gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } +} + +static xcb_gc_t +gc_font_get (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + const char *font_name) +{ + uint32_t value_list[3]; + xcb_void_cookie_t cookie_font; + xcb_void_cookie_t cookie_gc; + xcb_generic_error_t *error; + xcb_font_t font; + xcb_gcontext_t gc; + uint32_t mask; + + font = xcb_generate_id (c); + cookie_font = xcb_open_font_checked (c, font, + strlen (font_name), + font_name); + + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + + gc = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT; + value_list[0] = screen->black_pixel; + value_list[1] = screen->white_pixel; + value_list[2] = font; + cookie_gc = xcb_create_gc_checked (c, gc, window, mask, value_list); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cookie_font = xcb_close_font_checked (c, font); + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + return gc; +} + +static void +cursor_set (xcb_connection_t *c, + xcb_screen_t *screen, + xcb_window_t window, + int cursor_id) +{ + uint32_t values_list[3]; + xcb_void_cookie_t cookie_font; + xcb_void_cookie_t cookie_gc; + xcb_generic_error_t *error; + xcb_font_t font; + xcb_cursor_t cursor; + xcb_gcontext_t gc; + uint32_t mask; + uint32_t value_list; + + font = xcb_generate_id (c); + cookie_font = xcb_open_font_checked (c, font, + strlen ("cursor"), + "cursor"); + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't open font : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + cursor = xcb_generate_id (c); + xcb_create_glyph_cursor (c, cursor, font, font, + cursor_id, cursor_id + 1, + 0, 0, 0, + 0, 0, 0); + + gc = xcb_generate_id (c); + mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND | XCB_GC_FONT; + values_list[0] = screen->black_pixel; + values_list[1] = screen->white_pixel; + values_list[2] = font; + cookie_gc = xcb_create_gc_checked (c, gc, window, mask, values_list); + error = xcb_request_check (c, cookie_gc); + if (error) { + fprintf (stderr, "ERROR: can't create gc : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } + + mask = XCB_CW_CURSOR; + value_list = cursor; + xcb_change_window_attributes (c, window, mask, &value_list); + + xcb_free_cursor (c, cursor); + + cookie_font = xcb_close_font_checked (c, font); + error = xcb_request_check (c, cookie_font); + if (error) { + fprintf (stderr, "ERROR: can't close font : %d\n", error->error_code); + xcb_disconnect (c); + exit (-1); + } +} + +int main () +{ + xcb_screen_iterator_t screen_iter; + xcb_connection_t *c; + const xcb_setup_t *setup; + xcb_screen_t *screen; + xcb_generic_event_t *e; + xcb_generic_error_t *error; + xcb_void_cookie_t cookie_window; + xcb_void_cookie_t cookie_map; + xcb_window_t window; + uint32_t mask; + uint32_t values[2]; + int screen_number; + uint8_t is_hand = 0; + + /* getting the connection */ + c = xcb_connect (NULL, &screen_number); + if (!c) { + fprintf (stderr, "ERROR: can't connect to an X server\n"); + return -1; + } + + /* getting the current screen */ + setup = xcb_get_setup (c); + + screen = NULL; + screen_iter = xcb_setup_roots_iterator (setup); + for (; screen_iter.rem != 0; --screen_number, xcb_screen_next (&screen_iter)) + if (screen_number == 0) + { + screen = screen_iter.data; + break; + } + if (!screen) { + fprintf (stderr, "ERROR: can't get the current screen\n"); + xcb_disconnect (c); + return -1; + } + + /* creating the window */ + window = xcb_generate_id (c); + mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK; + values[0] = screen->white_pixel; + values[1] = + XCB_EVENT_MASK_KEY_RELEASE | + XCB_EVENT_MASK_BUTTON_PRESS | + XCB_EVENT_MASK_EXPOSURE | + XCB_EVENT_MASK_POINTER_MOTION; + cookie_window = xcb_create_window_checked (c, + screen->root_depth, + window, screen->root, + 20, 200, WIDTH, HEIGHT, + 0, XCB_WINDOW_CLASS_INPUT_OUTPUT, + screen->root_visual, + mask, values); + cookie_map = xcb_map_window_checked (c, window); + + /* error managing */ + error = xcb_request_check (c, cookie_window); + if (error) { + fprintf (stderr, "ERROR: can't create window : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + error = xcb_request_check (c, cookie_map); + if (error) { + fprintf (stderr, "ERROR: can't map window : %d\n", error->error_code); + xcb_disconnect (c); + return -1; + } + + cursor_set (c, screen, window, 68); + + xcb_flush(c); + + while (1) { + e = xcb_poll_for_event(c); + if (e) { + switch (e->response_type & ~0x80) { + case XCB_EXPOSE: { + char *text; + + text = "click here to change cursor"; + button_draw (c, screen, window, + (WIDTH - 7 * strlen(text)) / 2, + (HEIGHT - 16) / 2, text); + + text = "Press ESC key to exit..."; + text_draw (c, screen, window, 10, HEIGHT - 10, text); + break; + } + case XCB_BUTTON_PRESS: { + xcb_button_press_event_t *ev; + int length; + + ev = (xcb_button_press_event_t *)e; + length = strlen ("click here to change cursor"); + + if ((ev->event_x >= (WIDTH - 7 * length) / 2) && + (ev->event_x <= ((WIDTH - 7 * length) / 2 + 7 * length + 6)) && + (ev->event_y >= (HEIGHT - 16) / 2 - 19) && + (ev->event_y <= ((HEIGHT - 16) / 2))) + is_hand = 1 - is_hand; + + is_hand ? cursor_set (c, screen, window, 58) : cursor_set (c, screen, window, 68); + } + case XCB_KEY_RELEASE: { + xcb_key_release_event_t *ev; + + ev = (xcb_key_release_event_t *)e; + + switch (ev->detail) { + /* ESC */ + case 9: + free (e); + xcb_disconnect (c); + return 0; + } + } + } + free (e); + } + } + + return 0; +} +
The problem when you want to port an Xlib program to XCB is that you don't know if the Xlib function that you want to "translate" @@ -3058,236 +3800,246 @@ XCBVoidCookie XCBFreePixmap (XCBConnection *c, /* Pointer to the XCBConne provides. It's usually just a member of a structure.
In this section, we look at how to translate the macros that return some members of the Display structure. They are obtained by using a function that requires a - XCBConnection * or a member of the - XCBConnSetupSuccessRep structure - (via the function XCBGetSetup), or + xcb_connection_t * or a member of the + xcb_setup_t structure + (via the function xcb_get_setup), or a function that requires that structure. +
This number is the file descriptor that connects the client to the server. You just have to use that function:
-int XCBGetFileDescriptor(XCBConnection *c); +int xcb_get_file_descriptor (xcb_connection_t *c);-
That number is not stored by XCB. It is returned in the - second parameter of the function XCBConnect. + second parameter of the function xcb_connect. Hence, you have to store it yourself if you want to use - it. Then, to get the XCBSCREEN + it. Then, to get the xcb_screen_t structure, you have to iterate on the screens. The equivalent function of the Xlib's ScreenOfDisplay function can be - found below. OK, here is the + found below. This is also provided in the + xcb_aux_t library as xcb_aux_get_screen(). OK, here is the small piece of code to get that number:
-XCBConnection *c; -int screen_default_nbr; +xcb_connection_t *c; +int screen_default_nbr; -/* you pass the name of the display you want to XCBConnect */ +/* you pass the name of the display you want to xcb_connect_t */ -c = XCBConnect (display_name, &screen_default_nbr); +c = xcb_connect (display_name, &screen_default_nbr); /* screen_default_nbr contains now the number of the default screen */-
Not documented yet.
-+ However, this points out a basic difference in philosophy between + Xlib and XCB. Xlib has several functions for filtering and + manipulating the incoming and outgoing X message queues. XCB + wishes to hide this as much as possible from the user, which + allows for more freedom in implementation strategies. +
+You get the count of screens with the functions - XCBGetSetup + xcb_get_setup and - XCBConnSetupSuccessRepRootsIter + xcb_setup_roots_iterator (if you need to iterate):
-XCBConnection *c; -int screen_count; +xcb_connection_t *c; +int screen_count; /* you init the connection */ -screen_count = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).rem; +screen_count = xcb_setup_roots_iterator (xcb_get_setup (c)).rem; /* screen_count contains now the count of screens */
If you don't want to iterate over the screens, a better way to get that number is to use - XCBConnSetupSuccessRepRootsLength: + xcb_setup_roots_length_t:
-XCBConnection *c; -int screen_count; +xcb_connection_t *c; +int screen_count; /* you init the connection */ -screen_count = XCBConnSetupSuccessRepRootsLength (XCBGetSetup (c)); +screen_count = xcb_setup_roots_length (xcb_get_setup (c)); /* screen_count contains now the count of screens */-
You get the name of the vendor of the server hardware with - the functions XCBGetSetup + the functions xcb_get_setup and XCBConnSetupSuccessRepVendor. Beware + class="code">xcb_setup_vendor. Beware that, unlike Xlib, the string returned by XCB is not necessarily null-terminaled:
-XCBConnection *c; -char *vendor = NULL; -int length; +xcb_connection_t *c; +char *vendor = NULL; +int length; /* you init the connection */ -length = XCBConnSetupSuccessRepVendorLength (XCBGetSetup (c)); +length = xcb_setup_vendor_length (xcb_get_setup (c)); vendor = (char *)malloc (length + 1); if (vendor) -memcpy (vendor, XCBConnSetupSuccessRepVendor (XCBGetSetup (c)), length); +memcpy (vendor, xcb_setup_vendor (xcb_get_setup (c)), length); vendor[length] = '\0'; /* vendor contains now the name of the vendor. Must be freed when not used anymore */-
You get the major version of the protocol in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD16 protocol_major_version; +xcb_connection_t *c; +uint16_t protocol_major_version; /* you init the connection */ -protocol_major_version = XCBGetSetup (c)->protocol_major_version; +protocol_major_version = xcb_get_setup (c)->protocol_major_version; /* protocol_major_version contains now the major version of the protocol */-
You get the minor version of the protocol in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD16 protocol_minor_version; +xcb_connection_t *c; +uint16_t protocol_minor_version; /* you init the connection */ -protocol_minor_version = XCBGetSetup (c)->protocol_minor_version; +protocol_minor_version = xcb_get_setup (c)->protocol_minor_version; /* protocol_minor_version contains now the minor version of the protocol */-
You get the number of the release of the server hardware in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD32 release_number; +xcb_connection_t *c; +uint32_t release_number; /* you init the connection */ -release_number = XCBGetSetup (c)->release_number; +release_number = xcb_get_setup (c)->release_number; /* release_number contains now the number of the release of the server hardware */-
The name of the display is not stored in XCB. You have to store it by yourself.
-You get the bitmap scanline unit in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD8 bitmap_format_scanline_unit; +xcb_connection_t *c; +uint8_t bitmap_format_scanline_unit; /* you init the connection */ -bitmap_format_scanline_unit = XCBGetSetup (c)->bitmap_format_scanline_unit; +bitmap_format_scanline_unit = xcb_get_setup (c)->bitmap_format_scanline_unit; /* bitmap_format_scanline_unit contains now the bitmap scanline unit */-
You get the bitmap bit order in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD8 bitmap_format_bit_order; +xcb_connection_t *c; +uint8_t bitmap_format_bit_order; /* you init the connection */ -bitmap_format_bit_order = XCBGetSetup (c)->bitmap_format_bit_order; +bitmap_format_bit_order = xcb_get_setup (c)->bitmap_format_bit_order; /* bitmap_format_bit_order contains now the bitmap bit order */-
You get the bitmap scanline pad in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD8 bitmap_format_scanline_pad; +xcb_connection_t *c; +uint8_t bitmap_format_scanline_pad; /* you init the connection */ -bitmap_format_scanline_pad = XCBGetSetup (c)->bitmap_format_scanline_pad; +bitmap_format_scanline_pad = xcb_get_setup (c)->bitmap_format_scanline_pad; /* bitmap_format_scanline_pad contains now the bitmap scanline pad */-
You get the image byte order in the - XCBConnSetupSuccessRep - structure, with the function XCBGetSetup: + xcb_setup_t + structure, with the function xcb_get_setup:
-XCBConnection *c; -CARD8 image_byte_order; +xcb_connection_t *c; +uint8_t image_byte_order; /* you init the connection */ -image_byte_order = XCBGetSetup (c)->image_byte_order; +image_byte_order = xcb_get_setup (c)->image_byte_order; /* image_byte_order contains now the image byte order */
in Xlib, ScreenOfDisplay returns a Screen structure that contains several characteristics of your screen. XCB has a similar - structure (XCBSCREEN), + structure (xcb_screen_t), but the way to obtain it is a bit different. With Xlib, you just provide the number of the screen and you grab it from an array. With XCB, you iterate over all the screens to obtain the one you want. The complexity of this operation is O(n). So the best is to store this structure if you use - it often. See ScreenOfDisplay just below. + it often. See screen_of_display just below.
Xlib provides generally two functions to obtain the characteristics @@ -3295,26 +4047,26 @@ image_byte_order = XCBGetSetup (c)->image_byte_order; the screen, which calls ScreenOfDisplay, and the other that uses the Screen structure. This might be a bit confusing. As mentioned above, with XCB, it - is better to store the XCBSCREEN + is better to store the xcb_screen_t structure. Then, you have to read the members of this structure. That's why the Xlib functions are put by pairs (or more) as, with XCB, you will use the same code.
This function returns the Xlib Screen structure. With XCB, you iterate over all the screens and once you get the one you want, you return it:
-XCBSCREEN *ScreenOfDisplay (XCBConnection *c, - int screen) +xcb_screen_t *screen_of_display (xcb_connection_t *c, + int screen) { - XCBSCREENIter iter; + xcb_screen_iterator_t iter; - iter = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)); - for (; iter.rem; --screen, XCBSCREENNext (&iter)) + iter = xcb_setup_roots_iterator (xcb_get_setup (c)); + for (; iter.rem; --screen, xcb_screen_next (&iter)) if (screen == 0) return iter.data; @@ -3328,45 +4080,44 @@ XCBSCREEN *ScreenOfDisplay (XCBConnection *c,All the functions below will use the result of that function, as they just grab a specific member of the - XCBSCREEN structure. + xcb_screen_t structure.
-
It is the default screen that you obtain when you connect to - the X server. It suffices to call the ScreenOfDisplay + the X server. It suffices to call the screen_of_display function above with the connection and the number of the default screen.
-XCBConnection *c; -int screen_default_nbr; -XCBSCREEN *default_screen; /* the returned default screen */ +xcb_connection_t *c; +int screen_default_nbr; +xcb_screen_t *default_screen; /* the returned default screen */ -/* you pass the name of the display you want to XCBConnect */ +/* you pass the name of the display you want to xcb_connect_t */ -c = XCBConnect (display_name, &screen_default_nbr); -default_screen = ScreenOfDisplay (c, screen_default_nbr); +c = xcb_connect (display_name, &screen_default_nbr); +default_screen = screen_of_display (c, screen_default_nbr); /* default_screen contains now the default root window, or a NULL window if no screen is found */-
-
+-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -XCBWINDOW root_window = { 0 }; /* the returned window */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +xcb_window_t root_window = { 0 }; /* the returned window */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) root_window = screen->root; /* root_window contains now the root window, or a NULL window if no screen is found */-
It is the root window of the default screen. So, you call ScreenOfDisplay with the @@ -3374,390 +4125,385 @@ if (screen) root window as above:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_default_nbr; -XCBWINDOW root_window = { 0 }; /* the returned root window */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_default_nbr; +xcb_window_t root_window = { 0 }; /* the returned root window */ -/* you pass the name of the display you want to XCBConnect */ +/* you pass the name of the display you want to xcb_connect_t */ -c = XCBConnect (display_name, &screen_default_nbr); -screen = ScreenOfDisplay (c, screen_default_nbr); +c = xcb_connect (display_name, &screen_default_nbr); +screen = screen_of_display (c, screen_default_nbr); if (screen) root_window = screen->root; /* root_window contains now the default root window, or a NULL window if no screen is found */-
While a Visual is, in Xlib, a structure, in XCB, there are - two types: XCBVISUALID, which is - the Id of the visual, and XCBVISUALTYPE, + two types: xcb_visualid_t, which is + the Id of the visual, and xcb_visualtype_t, which corresponds to the Xlib Visual. To get the Id of the visual of a screen, just get the root_visual - member of a XCBSCREEN: + member of a xcb_screen_t:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -XCBVISUALID root_visual = { 0 }; /* the returned visual Id */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +xcb_visualid_t root_visual = { 0 }; /* the returned visual Id */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) root_visual = screen->root_visual; /* root_visual contains now the value of the Id of the visual, or a NULL visual if no screen is found */
- To get the XCBVISUALTYPE + To get the xcb_visualtype_t structure, it's a bit less easy. You have to get the - XCBSCREEN structure that you want, + xcb_screen_t structure that you want, get its root_visual member, - then iterate over the XCBDEPTHs - and the XCBVISUALTYPEs, and compare - the XCBVISUALID of these XCBVISUALTYPEs: + then iterate over the xcb_depth_ts + and the xcb_visualtype_ts, and compare + the xcb_visualid_t of these xcb_visualtype_ts: with root_visual:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -XCBVISUALID root_visual = { 0 }; -XCBVISUATYPE *visual_type = NULL; /* the returned visual type */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +xcb_visualid_t root_visual = { 0 }; +xcb_visualtype_t *visual_type = NULL; /* the returned visual type */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); -if (screen) - { - XCBDEPTHIter depth_iter; +screen = screen_of_display (c, screen_nbr); +if (screen) { + xcb_depth_iterator_t depth_iter; - depth_iter = XCBSCREENAllowedDepthsIter (screen); - for (; depth_iter.rem; XCBDEPTHNext (&depth_iter)) - { - XCBVISUALTYPEIter visual_iter; - - visual_iter = XCBDEPTHVisualsIter (depth_iter.data); - for (; visual_iter.rem; XCBVISUALTYPENext (&visual_iter)) - { - if (screen->root_visual.id == visual_iter.data->visual_id.id) - { - visual_type = visual_iter.data; - break; - } - } + depth_iter = xcb_screen_allowed_depths_iterator (screen); + for (; depth_iter.rem; xcb_depth_next (&depth_iter)) { + xcb_visualtype_iterator_t visual_iter; + + visual_iter = xcb_depth_visuals_iterator (depth_iter.data); + for (; visual_iter.rem; xcb_visualtype_next (&visual_iter)) { + if (screen->root_visual == visual_iter.data->visual_id) { + visual_type = visual_iter.data; + break; } + } } +} /* visual_type contains now the visual structure, or a NULL visual structure if no screen is found */-
This default Graphic Context is just a newly created Graphic Context, associated to the root window of a - XCBSCREEN, + xcb_screen_t, using the black white pixels of that screen:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -XCBGCONTEXT gc = { 0 }; /* the returned default graphic context */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +xcb_gcontext_t gc = { 0 }; /* the returned default graphic context */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); -if (screen) - { - XCBDRAWABLE draw; - CARD32 mask; - CARD32 values[2]; - - gc = XCBGCONTEXTNew (c); - draw.window = screen->root; - mask = GCForeground | GCBackground; - values[0] = screen->black_pixel; - values[1] = screen->white_pixel; - XCBCreateGC (c, gc, draw, mask, values); - } +screen = screen_of_display (c, screen_nbr); +if (screen) { + xcb_drawable_t draw; + uint32_t mask; + uint32_t values[2]; + + gc = xcb_generate_id (c); + draw = screen->root; + mask = XCB_GC_FOREGROUND | XCB_GC_BACKGROUND; + values[0] = screen->black_pixel; + values[1] = screen->white_pixel; + xcb_create_gc (c, gc, draw, mask, values); +} /* gc contains now the default graphic context */-
It is the Id of the black pixel, which is in the structure - of an XCBSCREEN. + of an xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 black_pixel = 0; /* the returned black pixel */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t black_pixel = 0; /* the returned black pixel */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) black_pixel = screen->black_pixel; /* black_pixel contains now the value of the black pixel, or 0 if no screen is found */-
It is the Id of the white pixel, which is in the structure - of an XCBSCREEN. + of an xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 white_pixel = 0; /* the returned white pixel */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t white_pixel = 0; /* the returned white pixel */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) white_pixel = screen->white_pixel; /* white_pixel contains now the value of the white pixel, or 0 if no screen is found */-
It is the width in pixels of the screen that you want, and which is in the structure of the corresponding - XCBSCREEN. + xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 width_in_pixels = 0; /* the returned width in pixels */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t width_in_pixels = 0; /* the returned width in pixels */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) width_in_pixels = screen->width_in_pixels; /* width_in_pixels contains now the width in pixels, or 0 if no screen is found */-
It is the height in pixels of the screen that you want, and which is in the structure of the corresponding - XCBSCREEN. + xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 height_in_pixels = 0; /* the returned height in pixels */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t height_in_pixels = 0; /* the returned height in pixels */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) height_in_pixels = screen->height_in_pixels; /* height_in_pixels contains now the height in pixels, or 0 if no screen is found */-
It is the width in millimeters of the screen that you want, and which is in the structure of the corresponding - XCBSCREEN. + xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 width_in_millimeters = 0; /* the returned width in millimeters */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t width_in_millimeters = 0; /* the returned width in millimeters */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) width_in_millimeters = screen->width_in_millimeters; /* width_in_millimeters contains now the width in millimeters, or 0 if no screen is found */-
It is the height in millimeters of the screen that you want, and which is in the structure of the corresponding - XCBSCREEN. + xcb_screen_t.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 height_in_millimeters = 0; /* the returned height in millimeters */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t height_in_millimeters = 0; /* the returned height in millimeters */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) height_in_millimeters = screen->height_in_millimeters; /* height_in_millimeters contains now the height in millimeters, or 0 if no screen is found */-
It is the depth (in bits) of the root window of the - screen. You get it from the XCBSCREEN structure. + screen. You get it from the xcb_screen_t structure.
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD8 root_depth = 0; /* the returned depth of the root window */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint8_t root_depth = 0; /* the returned depth of the root window */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) root_depth = screen->root_depth; /* root_depth contains now the depth of the root window, or 0 if no screen is found */-
This is the default colormap of the screen (and not the (default) colormap of the default screen !). As usual, you - get it from the XCBSCREEN structure: + get it from the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -XCBCOLORMAP default_colormap = { 0 }; /* the returned default colormap */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +xcb_colormap_t default_colormap = { 0 }; /* the returned default colormap */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) default_colormap = screen->default_colormap; /* default_colormap contains now the default colormap, or a NULL colormap if no screen is found */-
- You get the minimum installed colormaps in the XCBSCREEN structure: + You get the minimum installed colormaps in the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD16 min_installed_maps = 0; /* the returned minimum installed colormaps */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint16_t min_installed_maps = 0; /* the returned minimum installed colormaps */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) min_installed_maps = screen->min_installed_maps; /* min_installed_maps contains now the minimum installed colormaps, or 0 if no screen is found */-
- You get the maximum installed colormaps in the XCBSCREEN structure: + You get the maximum installed colormaps in the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD16 max_installed_maps = 0; /* the returned maximum installed colormaps */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint16_t max_installed_maps = 0; /* the returned maximum installed colormaps */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) max_installed_maps = screen->max_installed_maps; /* max_installed_maps contains now the maximum installed colormaps, or 0 if no screen is found */-
You know if save_unders is set, - by looking in the XCBSCREEN structure: + by looking in the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -BOOL save_unders = 0; /* the returned value of save_unders */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint8_t save_unders = 0; /* the returned value of save_unders */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) save_unders = screen->save_unders; /* save_unders contains now the value of save_unders, or FALSE if no screen is found */-
You know the value of backing_stores, - by looking in the XCBSCREEN structure: + by looking in the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -BYTE backing_stores = 0; /* the returned value of backing_stores */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint8_t backing_stores = 0; /* the returned value of backing_stores */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) backing_stores = screen->backing_stores; /* backing_stores contains now the value of backing_stores, or FALSE if no screen is found */-
To get the current input masks, - you look in the XCBSCREEN structure: + you look in the xcb_screen_t structure:
-XCBConnection *c; -XCBSCREEN *screen; -int screen_nbr; -CARD32 current_input_masks = 0; /* the returned value of current input masks */ +xcb_connection_t *c; +xcb_screen_t *screen; +int screen_nbr; +uint32_t current_input_masks = 0; /* the returned value of current input masks */ /* you init the connection and screen_nbr */ -screen = ScreenOfDisplay (c, screen_nbr); +screen = screen_of_display (c, screen_nbr); if (screen) current_input_masks = screen->current_input_masks; /* current_input_masks contains now the value of the current input masks, or FALSE if no screen is found */
+
in Xlib, the Screen structure stores its associated Display structure. This is not the case in the X Window protocol, hence, it's also not the case in XCB. So you have to store it by yourself.
-To get the colormap entries, - you look in the XCBVISUALTYPE + you look in the xcb_visualtype_t structure, that you grab like here:
-XCBConnection *c; -XCBVISUALTYPE *visual_type; -CARD16 colormap_entries = 0; /* the returned value of the colormap entries */ +xcb_connection_t *c; +xcb_visualtype_t *visual_type; +uint16_t colormap_entries = 0; /* the returned value of the colormap entries */ /* you init the connection and visual_type */