- 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 @@ -184,16 +185,16 @@
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:
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,
@@ -305,7 +306,7 @@
- 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 @@ -321,7 +322,8 @@ 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 + 'XCBConnection'. 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. @@ -329,7 +331,7 @@
- To ask informations to the X server, we have to make a request + 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 @@ -527,11 +529,12 @@ main () 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 + 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 epends on the event type. + read the event's data depends on the event type.
+ 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:
@@ -597,7 +606,7 @@ main (int argc, char *argv[]) { XCBConnection *c; - /* Open the connection to the X server. use the DISPLAY environment variable as the default display name */ + /* Open the connection to the X server. Use the DISPLAY environment variable as the default display name */ c = XCBConnect (NULL, NULL); return 1; @@ -638,11 +647,11 @@ void XCBDisconnect (XCBConnection *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 XCBSCREEN structure:
@@ -713,7 +722,7 @@ main (int argc, char *argv[])
- 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:
@@ -761,7 +770,7 @@ XCBVoidCookie XCBMapWindow (XCBConnection *c, XCBWINDOW window); 150x150 pixels, positioned at the top-left corner of the screen:
-#include <unistd.h>
+#include <unistd.h> /* pause() */
#include <X11/XCB/xcb.h>
@@ -783,28 +792,29 @@ main (int argc, char *argv[])
/* Create the window */
XCBCreateWindow (c, /* Connection */
- 0, /* depth */
+ XCBCopyFromParent, /* depth (same as root)*/
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
- InputOutput, /* class */
+ XCBWindowClassInputOutput,/* class */
screen->root_visual, /* visual */
0, NULL); /* masks, not used yet */
/* Map the window on the screen */
XCBMapWindow (c, win.window);
- XCBSync (c, 0);
+ /* Make sure commands are sent before we pause, so window is shown */
+ XCBFlush (c);
- pause ();
+ pause (); /* hold client until Ctrl-C */
return 1;
}
- In this code, you see one more function - XCBSync(), not explained + In this code, you see one more function - XCBFlush(), 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(): @@ -836,7 +846,7 @@ int XCBSync(XCBConnection *c, XCBGenericError **e); 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.
@@ -903,7 +913,7 @@ XCBVoidCookie XCBCreateGC (XCBConnection *c,We give now an example on how to allocate a graphic context - that specifies that each drawing functions that use it will + that specifies that each drawing function that uses it will draw in foreground with a black color.
@@ -926,7 +936,7 @@ main (int argc, char *argv[]) /* Create a black graphic context for drawing in the foreground */ win.window = screen->root; black = XCBGCONTEXTNew (c); - mask = GCForeground; + mask = XCBGCForeground; value[0] = screen->black_pixel; XCBCreateGC (c, black, win, mask, value); @@ -986,32 +996,32 @@ XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */
The value_mask parameter could take - these values: + any combination of these masks from the XCBGC enumeration:
It is possible to set several attributes at the same @@ -1019,7 +1029,8 @@ XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */ 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 + 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.
@@ -1033,7 +1044,7 @@ XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */
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 + functions, collectively called "drawing primitives". Let see how they are used.
@@ -1041,7 +1052,7 @@ XCBVoidCookie XCBChangeGC (XCBConnection *c, /* The XCB Connection */
XCBVoidCookie XCBPolyPoint (XCBConnection *c, /* The connection to the X server */
- BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */
+ BYTE coordinate_mode, /* Coordinate mode, usually set to XCBCoordModeOrigin */
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 */
@@ -1052,10 +1063,14 @@ XCBVoidCookie XCBPolyPoint (XCBConnection *c, /* The connection t
specifies the coordinate mode. Available values are
+ If XCBCoordModePrevious is used, then all points but the first one + are relative to the immediately previous point. +
+The XCBPOINT type is just a structure with two fields (the coordinates of the point):
@@ -1073,7 +1088,7 @@ typedef struct {
XCBVoidCookie XCBPolyLine (XCBConnection *c, /* The connection to the X server */
- BYTE coordinate_mode, /* Coordinate mode, usually set to CoordModeOrigin */
+ BYTE coordinate_mode, /* Coordinate mode, usually set to XCBCoordModeOrigin */
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 */
@@ -1130,9 +1145,8 @@ typedef struct {
CARD16 height;
} XCBRECTANGLE;
- - TODO: there's no coordinate_mode. Is it normal ? -
+ +To draw an elliptical arc, or several elliptical arcs, we use
@@ -1167,13 +1181,11 @@ typedef struct { 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 @@ -1198,9 +1210,9 @@ XCBVoidCookie XCBFillPoly (XCBConnection *c, values are
To fill one or several rectangles, we use
@@ -1223,12 +1235,19 @@ XCBVoidCookie XCBPolyFillArc (XCBConnection *c,
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.
++ TODO: Use screen->root_depth for depth parameter. +
++ TODO: Remove get_depth(). It isn't used! +
#include <stdlib.h>
#include <stdio.h>
@@ -1279,9 +1298,9 @@ main (int argc, char *argv[])
XCBPOINT polyline[] = {
{50, 10},
- {55, 30},
- {80, 10},
- {90, 20}};
+ { 5, 20}, /* rest of points are relative */
+ {25,-20},
+ {10, 10}};
XCBSEGMENT segments[] = {
{100, 10, 140, 30},
@@ -1292,8 +1311,8 @@ main (int argc, char *argv[])
{ 80, 50, 10, 40}};
XCBARC arcs[] = {
- {10, 100, 60, 40, 0, 90 << 6},
- {90, 100, 55, 40, 0, 270 << 6}};
+ {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);
@@ -1301,11 +1320,11 @@ main (int argc, char *argv[])
/* Get the first screen */
screen = XCBConnSetupSuccessRepRootsIter (XCBGetSetup (c)).data;
- /* Create black (foregroung) graphic context */
+ /* Create black (foreground) graphic context */
win.window = screen->root;
foreground = XCBGCONTEXTNew (c);
- mask = GCForeground | GCGraphicsExposures;
+ mask = XCBGCForeground | XCBGCGraphicsExposures;
values[0] = screen->black_pixel;
values[1] = 0;
XCBCreateGC (c, foreground, win, mask, values);
@@ -1316,15 +1335,15 @@ main (int argc, char *argv[])
/* Create the window */
mask = XCBCWBackPixel | XCBCWEventMask;
values[0] = screen->white_pixel;
- values[1] = ExposureMask;
+ values[1] = XCBEventMaskExposure;
XCBCreateWindow (c, /* Connection */
- 0, /* depth */
+ XCBCopyFromParent, /* depth */
win.window, /* window Id */
screen->root, /* parent window */
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
- InputOutput, /* class */
+ XCBWindowClassInputOutput,/* class */
screen->root_visual, /* visual */
mask, values); /* masks */
@@ -1333,19 +1352,19 @@ main (int argc, char *argv[])
/* We flush the request */
- XCBSync (c, 0);
+ XCBFlush (c);
- while ((e = XCBWaitEvent (c)))
+ while ((e = XCBWaitForEvent (c)))
{
- switch (e->response_type)
+ switch (e->response_type & ~0x80)
{
case XCBExpose:
{
/* We draw the points */
- XCBPolyPoint (c, CoordModeOrigin, win, foreground, 4, points);
+ XCBPolyPoint (c, XCBCoordModeOrigin, win, foreground, 4, points);
/* We draw the polygonal line */
- XCBPolyLine (c, CoordModeOrigin, win, foreground, 4, polyline);
+ XCBPolyLine (c, XCBCoordModePrevious, win, foreground, 4, polyline);
/* We draw the segements */
XCBPolySegment (c, win, foreground, 2, segments);
@@ -1357,7 +1376,7 @@ main (int argc, char *argv[])
XCBPolyArc (c, win, foreground, 2, arcs);
/* We flush the request */
- XCBSync (c, 0);
+ XCBFlush (c);
break;
}
@@ -1405,30 +1424,30 @@ main (int argc, char *argv[])
mask = XCBCWEventMask;
- valwin[0] = ExposureMask;
+ valwin[0] = XCBEventMaskExposure;
win.window = XCBWINDOWNew (c);
XCBCreateWindow (c, depth, win.window, root->root,
0, 0, 150, 150, 10,
- InputOutput, root->root_visual,
+ XCBWindowClassInputOutput, root->root_visual,
mask, valwin);
- ExposureMask is a constant defined
- in the "X.h" header file. If we wanted to register to several
+ XCBEventMaskExposure is a constant defined
+ in the XCBEventMask enumeration in the "xproto.h" header file. If we wanted to register for several
event types, we can logically "or" them, as follows:
mask = XCBCWEventMask;
- valwin[0] = ExposureMask | ButtonPressMask;
+ valwin[0] = XCBEventMaskExposure | XCBEventMaskButtonPress;
win.window = XCBWINDOWNew (c);
XCBCreateWindow (c, depth, win.window, root->root,
0, 0, 150, 150, 10,
- InputOutput, root->root_visual,
+ XCBWindowClassInputOutput, root->root_visual,
mask, valwin);
This registers for Expose events as
- well as for mouse button presses insode the created
+ well as for mouse button presses inside the created
window. You should note that a mask may represent several
event sub-types.
@@ -1464,9 +1483,9 @@ typedef enum {
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 */
+ valwin[0] = XCBNone; /* for XCBCWBackPixmap (whose value is 1) */
+ valwin[1] = XCBEventMaskExposure | XCBEventMaskButtonPress; /* for XCBCWEventMask, whose value (2048) */
+ /* is greater than the one of XCBCWBackPixmap */
If the window has already been created, we can use the
@@ -1476,10 +1495,10 @@ typedef enum {
prototype. As an example, here is a piece of code that
configures the window to receive the
Expose and
- ButtonPressMask events:
+ ButtonPress events:
-const static CARD32 values[] = { ExposureMask | ButtonPressMask };
+const static CARD32 values[] = { XCBEventMaskExposure | XCBEventMaskButtonPress };
/* The connection c and the window win are supposed to be defined */
@@ -1501,11 +1520,11 @@ XCBConfigureWindow (c, win, XCBCWEventMask, values);
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:
+ 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 + first one uses XCBWaitForEvent, which is similar to an event Xlib loop using only XNextEvent:
XCBGenericEvent *e;
- while ((e = XCBWaitEvent (c)))
+ while ((e = XCBWaitForEvent (c)))
{
- switch (e->response_type)
+ switch (e->response_type & ~0x80)
{
case XCBExpose:
{
@@ -1570,7 +1588,8 @@ XCBConfigureWindow (c, win, XCBCWEventMask, values);
You will certainly want to use XCBPollForEvent(XCBConnection *c, int
*error) if, in Xlib, you use XPending:
+ class="code">XPending or
+ XCheckMaskEvent:
while (XPending (display))
@@ -1595,7 +1614,7 @@ XCBConfigureWindow (c, win, XCBCWEventMask, values);
The events are managed in the same way as with XCBWaitEvent.
+ class="code">XCBWaitForEvent.
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.
@@ -1611,19 +1630,18 @@ XCBConfigureWindow (c, win, XCBCWEventMask, values);
- - XCBWaitEvent ()
+
- XCBWaitForEvent ()
- - XPending ()
-
- XNextEvent ()
+
- XPending ()
+ - XCheckMaskEvent ()
- XCBPollForEvent ()
-
@@ -1688,9 +1706,9 @@ typedef struct {
(or more) of the following masks when we create our window:
@@ -1724,22 +1742,23 @@ typedef XCBButtonPressEvent XCBButtonReleaseEvent;
The state field is a mask of the buttons held down during - the event. It is a bitwise OR of any of the following: + the event. It is a bitwise OR of any of the following (from the XCBButtonMask and + XCBModMask enumerations):
Their names are self explanatory, where the first 5 refer to @@ -1763,20 +1782,20 @@ typedef XCBButtonPressEvent XCBButtonReleaseEvent; during the creation of our window:
@@ -1803,18 +1822,18 @@ typedef struct {
Another type of event that applications might be interested - at, is a mouse pointer entering a window the program + 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 tht the applications is now in + 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 detail field refer to the + The detail field refers to the physical key on the keyboard.
@@ -1906,18 +1925,33 @@ typedef XCBKeyPressEvent XCBKeyReleaseEvent;
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 + 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 <malloc.h>
+#include <stdlib.h>
#include <stdio.h>
#include <X11/XCB/xcb.h>
+void
+print_modifiers(CARD32 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 (int argc, char *argv[])
{
@@ -1940,9 +1974,10 @@ main (int argc, char *argv[])
/* Create the window */
mask = XCBCWBackPixel | XCBCWEventMask;
values[0] = screen->white_pixel;
- values[1] = ExposureMask | ButtonPressMask | ButtonReleaseMask |
- PointerMotionMask | EnterWindowMask | LeaveWindowMask |
- KeyPressMask | KeyReleaseMask;
+ values[1] = XCBEventMaskExposure | XCBEventMaskButtonPress
+ | XCBEventMaskButtonRelease | XCBEventMaskPointerMotion
+ | XCBEventMaskEnterWindow | XCBEventMaskLeaveWindow
+ | XCBEventMaskKeyPress | XCBEventMaskKeyRelease;
XCBCreateWindow (c, /* Connection */
0, /* depth */
win.window, /* window Id */
@@ -1950,17 +1985,18 @@ main (int argc, char *argv[])
0, 0, /* x, y */
150, 150, /* width, height */
10, /* border_width */
- InputOutput, /* class */
+ XCBWindowClassInputOutput,/* 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)))
+ XCBFlush (c);
+
+ while ((e = XCBWaitForEvent (c)))
{
- switch (e->response_type)
+ switch (e->response_type & ~0x80)
{
case XCBExpose:
{
@@ -1973,18 +2009,7 @@ main (int argc, char *argv[])
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;
+ print_modifiers(ev->state);
switch (ev->detail.id)
{
@@ -2009,18 +2034,7 @@ main (int argc, char *argv[])
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;
+ print_modifiers(ev->state);
printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
ev->detail.id, ev->event.xid, ev->event_x, ev->event_y);
@@ -2046,13 +2060,14 @@ main (int argc, char *argv[])
{
XCBLeaveNotifyEvent *ev = (XCBLeaveNotifyEvent *)e;
- printf ("Mouse leaved window %ld, at coordinates (%d,%d)\n",
+ printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
ev->event.xid, ev->event_x, ev->event_y);
break;
}
case XCBKeyPress:
{
XCBKeyPressEvent *ev = (XCBKeyPressEvent *)e;
+ print_modifiers(ev->state);
printf ("Key pressed in window %ld\n",
ev->event.xid);
@@ -2061,14 +2076,16 @@ main (int argc, char *argv[])
case XCBKeyRelease:
{
XCBKeyReleaseEvent *ev = (XCBKeyReleaseEvent *)e;
+ print_modifiers(ev->state);
- printf ("Key releaseed in window %ld\n",
+ printf ("Key released in window %ld\n",
ev->event.xid);
break;
}
default:
{
/* Unknown event type, ignore it */
+ printf("Unknown event: %d\n", e->response_type);
break;
}
}
@@ -2093,7 +2110,7 @@ main (int argc, char *argv[])
In order to support flexible fonts, a font structure is - defined. You know what ? Its an Id: + defined. You know what ? It's an Id:
typedef struct {
@@ -2104,6 +2121,10 @@ typedef struct {
It is used to contain information about a font, and is passed
to several functions that handle fonts selection and text drawing.
+
+ TODO: example for picking a font and displaying some text.
+ Even better, also demonstrate translating keypresses to text.
+
@@ -2124,7 +2145,7 @@ typedef struct {
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 + 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). @@ -2154,17 +2175,18 @@ XCBVoidCookie XCBChangeProperty (XCBConnection *c, /* Connection to the X serve
The mode parameter coud be one of - the following value (defined in the X.h header file): + the following values (defined in enumeration XCBPropMode in + the xproto.h header file):
- The firt thing we want to do would be to set the name for our + The first 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 @@ -2209,24 +2231,24 @@ main (int argc, char *argv[]) 0, 0, /* x, y */ 250, 150, /* width, height */ 10, /* border_width */ - InputOutput, /* class */ + XCBWindowClassInputOutput,/* class */ screen->root_visual, /* visual */ 0, NULL); /* masks, not used */ /* Set the title of the window */ - XCBChangeProperty(c, PropModeReplace, win.window, + XCBChangeProperty(c, XCBPropModeReplace, win.window, WM_NAME, STRING, 8, strlen(title), title); /* Set the title of the window icon */ - XCBChangeProperty(c, PropModeReplace, win.window, + XCBChangeProperty(c, XCBPropModeReplace, win.window, WM_ICON_NAME, STRING, 8, strlen(title_icon), title_icon); /* Map the window on the screen */ XCBMapWindow (c, win.window); - XCBSync (c, 0); + XCBFlush (c); while (1) {} @@ -2299,7 +2321,7 @@ XCBVoidCookie XCBUnmapWindow(XCBConnection *c, XCBWINDOW window);
As we have seen when we have created our first window, in the - X Events subsection, we can set some attributes to the window + 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 @@ -2313,16 +2335,16 @@ XCBVoidCookie XCBConfigureWindow (XCBConnection *c, /* The connection
We set the value_mask to one or - several mask values that are in the X.h header: + several mask values that are in the XCBConfigWindow enumeration in the xproto.h header:
We then give to value_mask the new @@ -2341,7 +2363,7 @@ const static CARD32 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); +XCBConfigureWindow (c, win, XCBConfigWindowX | XCBConfigWindowY, values);
Note that when the window is moved, it might get partially @@ -2360,7 +2382,7 @@ const static CARD32 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); +XCBConfigureWindow (c, win, XCBConfigWindowWidth | XCBConfigWindowHeight, values);
We can also combine the move and resize operations using one @@ -2373,33 +2395,33 @@ const static CARD32 values[] = { 10, 20, 200, 300 }; /* 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); +XCBConfigureWindow (c, win, XCBConfigWindowX | XCBConfigWindowY | XCBConfigWindowWidth | XCBConfigWindowHeight, 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 + 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 CARD32 values[] = { Above };
+const static CARD32 values[] = { XCBStackModeAbove };
/* 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);
+XCBConfigureWindow (c, win, XCBConfigWindowStackMode, values);
-const static CARD32 values[] = { Below };
+const static CARD32 values[] = { XCBStackModeBelow };
/* 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);
+XCBConfigureWindow (c, win, XCBConfigWindowStackMode, values);
@@ -2769,7 +2791,7 @@ main (int argc, char *argv[]) /* We create the window win here*/ cmap = XCBCOLORMAPNew (c); - XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual); + XCBCreateColormap (c, XCBColormapAllocNone, cmap, win, screen->root_visual); return 1; } @@ -2871,7 +2893,7 @@ main (int argc, char *argv[]) /* We create the window win here*/ cmap = XCBCOLORMAPNew (c); - XCBCreateColormap (c, AllocNone, cmap, win, screen->root_visual); + XCBCreateColormap (c, XCBColormapAllocNone, cmap, win, screen->root_visual); rep = XCBAllocColorReply (c, XCBAllocColor (c, cmap, 65535, 0, 0), 0); @@ -2918,7 +2940,8 @@ main (int argc, char *argv[]) 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 + (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).
@@ -2951,7 +2974,7 @@ typedef union {
in order to avoid confusion between a window and a pixmap. The - operations that will work indifferently on a window or a pixmap + operations that will work the same on a window or a pixmap will require a XCBDRAWABLE
TODO: Explain the drawable parameter, and give an - example (like xpoints.c) + example (like xpoints.c)
@@ -3027,10 +3051,10 @@ XCBVoidCookie XCBCopyArea (XCBConnection *c, /* Pointer to the XCBCo 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 + 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 widow, but that is beyond the scope of this tutorial. + in a window, but that is beyond the scope of this tutorial.
@@ -3085,7 +3109,8 @@ int XCBGetFileDescriptor(XCBConnection *c); 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 + XCBAux library as XCBAuxGetScreen(). OK, here is the small piece of code to get that number:
@@ -3102,6 +3127,13 @@ c = XCBConnect (display_name, &screen_default_nbr);
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 @@ -3480,7 +3512,7 @@ if (screen) gc = XCBGCONTEXTNew (c); draw.window = screen->root; - mask = GCForeground | GCBackground; + mask = XCBGCForeground | XCBGCBackground; values[0] = screen->black_pixel; values[1] = screen->white_pixel; XCBCreateGC (c, gc, draw, mask, values);