[Xcb-commit] tutorial tutorial.mdwn
XCB site
xcb at freedesktop.org
Mon Nov 12 00:26:58 PST 2007
tutorial.mdwn | 900 ---------------------------------------------------
tutorial/events.mdwn | 453 +++++++++++++++++++++++++
2 files changed, 457 insertions(+), 896 deletions(-)
New commits:
commit 85358751f89dad74440aff224e4b7cac1048c08f
Author: brian.thomas.will <brian.thomas.will at gmail.com>
Date: Mon Nov 12 00:26:58 2007 -0800
split events and basic windows and drawing into separate pages
diff --git a/tutorial.mdwn b/tutorial.mdwn
index 844a150..682d76e 100644
--- a/tutorial.mdwn
+++ b/tutorial.mdwn
@@ -1,6 +1,9 @@
**This page is being formatted. A readable copy is [here](http://gitweb.freedesktop.org/?p=xcb/libxcb.git;a=blob_plain;f=doc/tutorial/index.html)**
-* [[tutorial/Fonts]]
+* [[BasicWindowsAndDrawing]]
+* [[Events]]
+* [[TextAndFonts|Fonts]]
+
# 1. Introduction
@@ -372,901 +375,6 @@ Here is a small program that shows how to use this function:
return 0;
}
-# 8. Creating a basic window - the "hello world" program
-
-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 uint32_t xcb_window_t;
-
-We first ask for a new Id for our window, with this function:
-
- xcb_window_t xcb_generate_id (xcb_connection_t *c);
-
-Then, XCB supplies the following function to create new windows:
-
- 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 prototype is
-
- 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> /* pause() */
-
- #include <xcb/xcb.h>
-
- int
- main ()
- {
- /* Open the connection to the X server */
- xcb_connection_t *connection = xcb_connect (NULL, NULL);
-
-
- /* Get the first screen */
- const xcb_setup_t *setup = xcb_get_setup (connection);
- xcb_screen_iterator_t iter = xcb_setup_roots_iterator (setup);
- xcb_screen_t *screen = iter.data;
-
-
- /* Create the window */
- xcb_window_t window = xcb_generate_id (connection);
- xcb_create_window (c, /* Connection */
- XCB_COPY_FROM_PARENT, /* depth (same as root)*/
- window, /* 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 */
- xcb_map_window (connection, window);
-
-
- /* Make sure commands are sent before we pause so that the window gets shown */
- xcb_flush (connection);
-
-
- pause (); /* hold client until Ctrl-C */
-
- xcb_disconnection (connection);
-
- return 0;
- }
-
-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():
-
- 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 xcbauxsync():
-
- 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.
-
-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 described yet. See the subsections Configuring a window or Registering for event types using event masks 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.
-
-TODO: one should tell what these functions return and about the generic error
-
-Comparison Xlib/XCB:
-
-* XCreateWindow () =>
-
- xcb_generate_id ()
- xcb_create_window ()
-
-# 9. Drawing in a window
-
-Drawing in a window can be done using various graphical functions (drawing pixels, lines, rectangles, etc). In order to draw in a window, we first need to define various general drawing parameters (what line width to use, which color to draw with, etc). This is done using a graphical context.
-
-###9.1 Allocating a Graphics 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:
-
- typedef uint32_t xcb_gcontext_t;
-
-We first ask the X server to attribute an Id to our graphic context with this function:
-
- xcb_gcontext_t xcb_generate_id (xcb_connection_t *c);
-
-Then, we set the attributes of the graphic context with this function:
-
- 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 function that uses it will draw in foreground with a black color.
-
- #include <xcb/xcb.h>
-
- int
- main ()
- {
- /* Open the connection to the X server and get the first screen */
- xcb_connection_t *connection = xcb_connect (NULL, NULL);
- xcb_screen_t *screen = xcb_setup_roots_iterator (xcb_get_setup (connection)).data;
-
- /* Create a black graphic context for drawing in the foreground */
- xcb_drawable_t window = screen->root;
- xcb_gcontext_t black = xcb_generate_id (connection);
- uint32_t mask = XCB_GC_FOREGROUND;
- uint32_t value[] = { screen->black_pixel };
-
- xcb_create_gc (connection, black, window, mask, value);
-
- return 0;
- }
-
-Note should be taken regarding the role of "valuemask" and "valuelist" 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 "valuemask" parameter is for. We then use the "valuelist" parameter to specify actual values for the attribute we defined in "valuemask". Thus, for each constant used in "valuelist", 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 () =>
-
- xcb_generate_id ()
- xcb_create_gc ()
-
-### 9.2 Changing the attributes of a Graphics Context
-
-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 valuemask parameter could take any combination of these masks from the xcbgc_t enumeration:
-
- XCB_GC_FUNCTION
- XCB_GC_PLANE_MASK
- XCB_GC_FOREGROUND
- XCB_GC_BACKGROUND
- XCB_GC_LINE_WIDTH
- XCB_GC_LINE_STYLE
- XCB_GC_CAP_STYLE
- XCB_GC_JOIN_STYLE
- XCB_GC_FILL_STYLE
- XCB_GC_FILL_RULE
- XCB_GC_TILE
- XCB_GC_STIPPLE
- XCB_GC_TILE_STIPPLE_ORIGIN_X
- XCB_GC_TILE_STIPPLE_ORIGIN_Y
- XCB_GC_FONT
- XCB_GC_SUBWINDOW_MODE
- XCB_GC_GRAPHICS_EXPOSURES
- XCB_GC_CLIP_ORIGIN_X
- XCB_GC_CLIP_ORIGIN_Y
- XCB_GC_CLIP_MASK
- XCB_GC_DASH_OFFSET
- XCB_GC_DASH_LIST
- XCB_GC_ARC_MODE
-
-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 valuemask. Then valuelist 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.
-
-
-### 9.3 Drawing primitives: point, line, box, circle,...
-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:
-
- XCB_COORD_MODE_ORIGIN
- XCB_COORD_MODE_PREVIOUS
-
-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_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_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_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_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:
-
- XCB_POLY_SHAPE_COMPLEX
- XCB_POLY_SHAPE_NONCONVEX
- XCB_POLY_SHAPE_CONVEX
-
-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 <xcb/xcb.h>
-
- int
- main ()
- {
- /* geometric objects */
- xcb_point_t points[] = {
- {10, 10},
- {10, 20},
- {20, 10},
- {20, 20}};
-
- xcb_point_t polyline[] = {
- {50, 10},
- { 5, 20}, /* rest of points are relative */
- {25,-20},
- {10, 10}};
-
- xcb_segment_t segments[] = {
- {100, 10, 140, 30},
- {110, 25, 130, 60}};
-
- xcb_rectangle_t rectangles[] = {
- { 10, 50, 40, 20},
- { 80, 50, 10, 40}};
-
- 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 */
- xcb_connection_t *connection = xcb_connect (NULL, NULL);
-
- /* Get the first screen */
- xcb_screen_t *screen = xcb_setup_roots_iterator (xcb_get_setup (connection)).data;
-
- /* Create black (foreground) graphic context */
- xcb_drawable_t window = screen->root;
- xcb_gcontext_t foreground = xcb_generate_id (connection);
- uint32_t mask = XCB_GC_FOREGROUND | XCB_GC_GRAPHICS_EXPOSURES;
- uint32_t values[2] = {screen->black_pixel, 0};
-
- xcb_create_gc (connection, foreground, window, mask, values);
-
-
- /* Create a window */
-
- window = xcb_generate_id (connection);
-
- mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
- values[0] = screen->white_pixel;
- values[1] = XCB_EVENT_MASK_EXPOSURE;
-
- xcb_create_window (connection, /* connection */
- XCB_COPY_FROM_PARENT, /* depth */
- window, /* 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 and flush*/
- xcb_map_window (connection, window);
- xcb_flush (connection);
-
-
- /* draw primitives */
-
- xcb_generic_event_t *event;
- while (event = xcb_wait_for_event (connection)) {
- switch (event->response_type & ~0x80) {
- case XCB_EXPOSE:
- /* We draw the points */
- xcb_poly_point (connection, XCB_COORD_MODE_ORIGIN, window, foreground, 4, points);
-
- /* We draw the polygonal line */
- xcb_poly_line (connection, XCB_COORD_MODE_PREVIOUS, window, foreground, 4, polyline);
-
- /* We draw the segements */
- xcb_poly_segment (connection, window, foreground, 2, segments);
-
- /* draw the rectangles */
- xcb_poly_rectangle (connection, window, foreground, 2, rectangles);
-
- /* draw the arcs */
- xcb_poly_arc (connection, window, foreground, 2, arcs);
-
- /* flush the request */
- xcb_flush (connection);
-
- break;
- default:
- /* Unknown event type, ignore it */
- break;
- }
-
- /* Free the Generic Event */
- free (event);
- }
-
- return 0;
- }
-
-
-# 10. X Events
-
-In an X program, everything is driven by events. Event painting on the screen is sometimes done as a response to an event (an Expose event). If part of a program's window that was hidden, gets exposed (e.g. the window was raised above other widows), the X server will send an "expose" event to let the program know it should repaint that part of the window. User input (key presses, mouse movement, etc) is also received as a set of events.
-
-###10.1 Registering for event types using event masks
-
-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 "valuemask" and "valuelist" 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 (connection);
- xcb_create_window (connection, depth, window, 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 (connection);
- xcb_create_window (connection, depth, window, 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 {
- XCB_CW_BACK_PIXMAP = 1L<<0,
- XCB_CW_BACK_PIXEL = 1L<<1,
- XCB_CW_BORDER_PIXMAP = 1L<<2,
- XCB_CW_BORDER_PIXEL = 1L<<3,
- XCB_CW_BIT_GRAVITY = 1L<<4,
- XCB_CW_WIN_GRAVITY = 1L<<5,
- XCB_CW_BACKING_STORE = 1L<<6,
- XCB_CW_BACKING_PLANES = 1L<<7,
- XCB_CW_BACKING_PIXEL = 1L<<8,
- XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
- XCB_CW_SAVE_UNDER = 1L<<10,
- XCB_CW_EVENT_MASK = 1L<<11,
- XCB_CW_DONT_PROPAGATE = 1L<<12,
- XCB_CW_COLORMAP = 1L<<13,
- XCB_CW_CURSOR = 1L<<14
- } xcb_cw_t;
-
-Note: we must be careful when setting the values of the valwin parameter, as they have to follow the order the xcb\_cw\_t enumeration. Here is an example:
-
- 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 };
-
- xcb_configure_window (connection, window, XCB_CW_EVENT_MASK, values);
-
-Note: A common programmer oversight is adding code to handle new event types while forgetting to add the masks for these events in the creation of the window. This leads to programmers debugging for hours, wondering "Why doesn't my program notice that I released the button?", only to find that they reigstered button press events but not button release events.
-
-### 10.2 Receiving events: writing the events loop
-
-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:
-
-The blocking way:
-
- xcb_generic_event_t *xcb_wait_for_event (xcb_connection_t *c);
-
-...blocks until an event is queued in the X server, then deques it from the queue, then returns it as a newly allocated structure (which is your responsibility to free). May return NULL in event of an error.
-
-The non-blocking way:
-
- xcb_generic_event_t *xcb_poll_for_event (xcb_connection_t *c, int *error);
-
-...immediately dequeus and returns an event, but returns NULL if no event is available at the time of the call. If an error occurs, the parameter error will be filled with the error status.
-
-Here's how you might use xcb_wait_for_event:
-
- xcb_generic_event_t *event;
-
- while (event = xcb_wait_for_event (connection)) {
- switch (event->response_type & ~0x80) {
- case XCB_EXPOSE:
- xcb_expose_event_t *expose = (xcb_expose_event_t *)event;
- /* ...do stuff */
- break;
- case XCB_BUTTON_PRESS:
- xcb_button_press_event_t *press = (xcb_button_press_event_t *)event;
- /* ...do stuff */
- break;
- default:
- /* Unknown event type, ignore it */
- break;
- }
-
- free (event);
- }
-
-Non-blocking handling in Xlib looks like this:
-
- while (XPending (display)) {
- XEvent event;
- XNextEvent(display, &event);
- /* ...handle the event */
- }
-
-The equivalent in XCB looks like:
-
- xcb_generic_event_t *event;
-
- while (event = xcb_poll_for_event (connection, 0)) {
- /* ...handle the event */
- }
-
-Basically, the events are managed in the same way as with xcb\_wait\_for\_event. Obviously, your endless event handling loop 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.
-
-Comparison Xlib/XCB:
-
-* XNextEvent () =>
-
- xcb_wait_for_event ()
-
-* XPending () , XCheckMaskEvent () =>
-
- xcb_poll_for_event ()
-
-
-
-### 10.3 Expose events
-
-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:
-
-* A window that covered part of our window has moved away, exposing part (or all) of our window.
-* Our window was raised above other windows.
-* Our window was mapped for the first time.
-* Our window was de-iconified (to 'iconify' a window is to minimize it or send it to the tray such that it is not shown at all)
-
-Note the implicit assumption here: the content of our window is lost when it is being obscured (covered) by other windows. The reason the X server does not save this content is to save memory. After all, the number of windows on a display at a given time may be very large, so 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.)
-
-Expose event definition:
-
- 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;
-
-### 10.4 Getting user input
-
-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.
-
-###10.4.1 Mouse button press and release events
-
-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:
-
- XCB_EVENT_MASK_BUTTON_PRESS //notify us of any button that was pressed in one of our windows.
- XCB_EVENT_MASK_BUTTON_RELEASE //notify us of any button that was released in one of our windows.
-
-Both kinds of events are represented with the same structure, but for the sake of self-documentation, it goes by two names:
-
- 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 xcbbuttonmaskt and xcbmodmaskt enumerations):
-
- XCB_BUTTON_MASK_1
- XCB_BUTTON_MASK_2
- XCB_BUTTON_MASK_3
- XCB_BUTTON_MASK_4
- XCB_BUTTON_MASK_5
- XCB_MOD_MASK_SHIFT
- XCB_MOD_MASK_LOCK
- XCB_MOD_MASK_CONTROL
- XCB_MOD_MASK_1
- XCB_MOD_MASK_2
- XCB_MOD_MASK_3
- XCB_MOD_MASK_4
- XCB_MOD_MASK_5
-
-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 (Mod mask 1 is usually the 'Alt' key or the 'Meta' key).
-
-TODO: Problem: it seems that the state does not change when clicking with various buttons.
-
-##### 10.4.2 Mouse movement events
-
-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 to register for these events:
-
- XCB_EVENT_MASK_POINTER_MOTION // motion with no mouse button held
- XCB_EVENT_MASK_BUTTON_MOTION // motion with one or more mouse buttons held
- XCB_EVENT_MASK_BUTTON_1_MOTION // motion while only 1st mouse button is held
- XCB_EVENT_MASK_BUTTON_2_MOTION // and so on...
- XCB_EVENT_MASK_BUTTON_3_MOTION
- XCB_EVENT_MASK_BUTTON_4_MOTION
- XCB_EVENT_MASK_BUTTON_5_MOTION
-
-These all generate events of this type:
-
- 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;
-
-##### 10.4.3 Mouse pointer enter and leave events
-
-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:
-
-* xcb_event_enter_window_t: notify us when the mouse pointer enters any of our controlled windows.
-* xcb_event_leave_window_t: notify us when the mouse pointer leaves any of our controlled windows.
-
-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;
-
-##### 10.4.4 The keyboard focus
-
-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...).
-
-##### 10.4.5 Keyboard press and release events
-
-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:
-
- XCB_EVENT_MASK_KEY_PRESS // key was pressed while any of our controlled windows had the keyboard focus
- XCB_EVENT_MASK_KEY_RELEASE // key was released while any of our controlled windows had the keyboard focus
-
-These generate events of the same type, which goes by two names:
-
- typedef struct {
- uint8_t response_type; /* The type of the event */
- xcb_keycode_t detail; /* the physical key on the keyboard */
- 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;
-
-TODO: Talk about getting the ASCII code from the key code.
-
-### 10.5 X events: a complete example
-
-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>
-
- /* print names of modifiers present in mask */
- void
- print_modifiers (uint32_t mask)
- {
- const char *MODIFIERS[] = {
- "Shift", "Lock", "Ctrl", "Alt",
- "Mod2", "Mod3", "Mod4", "Mod5",
- "Button1", "Button2", "Button3", "Button4", "Button5"
- };
-
- printf ("Modifier mask: ");
- for (char **modifier = MODIFIERS ; mask; mask >>= 1, ++modifier) {
- if (mask & 1) {
- printf (*modifier);
- }
- }
- printf ("\n");
- }
-
- int
- main ()
- {
- /* Open the connection to the X server */
- xcb_connection_t *connection = xcb_connect (NULL, NULL);
-
- /* Get the first screen */
- xcb_screen_t *screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
-
-
- /* Create the window */
- xcb_window_t window = xcb_generate_id (connection);
-
- uint32_t mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
- uint32_t values[2] = {screen->white_pixel,
- 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 (connection,
- 0, /* depth */
- window,
- 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 */
- xcb_map_window (c, win);
-
- xcb_flush (c);
-
- xcb_generic_event_t *event;
- while (event = xcb_wait_for_event (connection)) {
- switch (event->response_type & ~0x80) {
- case XCB_EXPOSE:
- xcb_expose_event_t *expose = (xcb_expose_event_t *)event;
-
- printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
- expose->window, expose->x, expose->y, expose->width, expose->height );
- break;
-
- case XCB_BUTTON_PRESS:
- xcb_button_press_event_t *bp = (xcb_button_press_event_t *)event;
- print_modifiers (bp->state);
-
- switch (press->detail) {
- case 4:
- printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
- bp->event, bp->event_x, bp->event_y );
- break;
- case 5:
- printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
- bp->event, bp->event_x, bp->event_y );
- break;
- default:
- printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
- bp->detail, bp->event, bp->event_x, bp->event_y );
- break;
- }
- break;
- case XCB_BUTTON_RELEASE:
- xcb_button_release_event_t *br = (xcb_button_release_event_t *)event;
- print_modifiers(release->state);
-
- printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
- br->detail, br->event, br->event_x, br->event_y );
- break;
-
- case XCB_MOTION_NOTIFY:
- xcb_motion_notify_event_t *motion = (xcb_motion_notify_event_t *)event;
-
- printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
- motion->event, motion->event_x, motion->event_y );
- break;
-
- case XCB_ENTER_NOTIFY:
- xcb_enter_notify_event_t *enter = (xcb_enter_notify_event_t *)event;
-
- printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
- enter->event, enter->event_x, enter->event_y );
- break;
-
- case XCB_LEAVE_NOTIFY:
- xcb_leave_notify_event_t *leave = (xcb_leave_notify_event_t *)event;
-
- printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
- leave->event, leave->event_x, leave->event_y );
- break;
-
- case XCB_KEY_PRESS:
- xcb_key_press_event_t *kp = (xcb_key_press_event_t *)event;
- print_modifiers(kp->state);
-
- printf ("Key pressed in window %ld\n",
- kp->event);
- break;
-
- case XCB_KEY_RELEASE:
- xcb_key_release_event_t *kr = (xcb_key_release_event_t *)event;
- print_modifiers(kr->state);
-
- printf ("Key released in window %ld\n",
- kr->event);
- break;
-
- default:
- /* Unknown event type, ignore it */
- printf ("Unknown event: %d\n",
- event->response_type);
- break;
- }
-
- free (event);
- }
-
- return 0;
- }
-
# 12. Windows hierarchy
diff --git a/tutorial/events.mdwn b/tutorial/events.mdwn
new file mode 100644
index 0000000..f13b4c5
--- /dev/null
+++ b/tutorial/events.mdwn
@@ -0,0 +1,453 @@
+# 10. X Events
+
+In an X program, everything is driven by events. Event painting on the screen is sometimes done as a response to an event (an Expose event). If part of a program's window that was hidden, gets exposed (e.g. the window was raised above other widows), the X server will send an "expose" event to let the program know it should repaint that part of the window. User input (key presses, mouse movement, etc) is also received as a set of events.
+
+###10.1 Registering for event types using event masks
+
+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 "valuemask" and "valuelist" 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 (connection);
+ xcb_create_window (connection, depth, window, 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 (connection);
+ xcb_create_window (connection, depth, window, 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 {
+ XCB_CW_BACK_PIXMAP = 1L<<0,
+ XCB_CW_BACK_PIXEL = 1L<<1,
+ XCB_CW_BORDER_PIXMAP = 1L<<2,
+ XCB_CW_BORDER_PIXEL = 1L<<3,
+ XCB_CW_BIT_GRAVITY = 1L<<4,
+ XCB_CW_WIN_GRAVITY = 1L<<5,
+ XCB_CW_BACKING_STORE = 1L<<6,
+ XCB_CW_BACKING_PLANES = 1L<<7,
+ XCB_CW_BACKING_PIXEL = 1L<<8,
+ XCB_CW_OVERRIDE_REDIRECT = 1L<<9,
+ XCB_CW_SAVE_UNDER = 1L<<10,
+ XCB_CW_EVENT_MASK = 1L<<11,
+ XCB_CW_DONT_PROPAGATE = 1L<<12,
+ XCB_CW_COLORMAP = 1L<<13,
+ XCB_CW_CURSOR = 1L<<14
+ } xcb_cw_t;
+
+Note: we must be careful when setting the values of the valwin parameter, as they have to follow the order the xcb\_cw\_t enumeration. Here is an example:
+
+ 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 };
+
+ xcb_configure_window (connection, window, XCB_CW_EVENT_MASK, values);
+
+Note: A common programmer oversight is adding code to handle new event types while forgetting to add the masks for these events in the creation of the window. This leads to programmers debugging for hours, wondering "Why doesn't my program notice that I released the button?", only to find that they reigstered button press events but not button release events.
+
+### 10.2 Receiving events: writing the events loop
+
+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:
+
+The blocking way:
+
+ xcb_generic_event_t *xcb_wait_for_event (xcb_connection_t *c);
+
+...blocks until an event is queued in the X server, then deques it from the queue, then returns it as a newly allocated structure (which is your responsibility to free). May return NULL in event of an error.
+
+The non-blocking way:
+
+ xcb_generic_event_t *xcb_poll_for_event (xcb_connection_t *c, int *error);
+
+...immediately dequeus and returns an event, but returns NULL if no event is available at the time of the call. If an error occurs, the parameter error will be filled with the error status.
+
+Here's how you might use xcb_wait_for_event:
+
+ xcb_generic_event_t *event;
+
+ while (event = xcb_wait_for_event (connection)) {
+ switch (event->response_type & ~0x80) {
+ case XCB_EXPOSE:
+ xcb_expose_event_t *expose = (xcb_expose_event_t *)event;
+ /* ...do stuff */
+ break;
+ case XCB_BUTTON_PRESS:
+ xcb_button_press_event_t *press = (xcb_button_press_event_t *)event;
+ /* ...do stuff */
+ break;
+ default:
+ /* Unknown event type, ignore it */
+ break;
+ }
+
+ free (event);
+ }
+
+Non-blocking handling in Xlib looks like this:
+
+ while (XPending (display)) {
+ XEvent event;
+ XNextEvent(display, &event);
+ /* ...handle the event */
+ }
+
+The equivalent in XCB looks like:
+
+ xcb_generic_event_t *event;
+
+ while (event = xcb_poll_for_event (connection, 0)) {
+ /* ...handle the event */
+ }
+
+Basically, the events are managed in the same way as with xcb\_wait\_for\_event. Obviously, your endless event handling loop 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.
+
+Comparison Xlib/XCB:
+
+* XNextEvent () =>
+
+ xcb_wait_for_event ()
+
+* XPending () , XCheckMaskEvent () =>
+
+ xcb_poll_for_event ()
+
+
+
+### 10.3 Expose events
+
+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:
+
+* A window that covered part of our window has moved away, exposing part (or all) of our window.
+* Our window was raised above other windows.
+* Our window was mapped for the first time.
+* Our window was de-iconified (to 'iconify' a window is to minimize it or send it to the tray such that it is not shown at all)
+
+Note the implicit assumption here: the content of our window is lost when it is being obscured (covered) by other windows. The reason the X server does not save this content is to save memory. After all, the number of windows on a display at a given time may be very large, so 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.)
+
+Expose event definition:
+
+ 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;
+
+### 10.4 Getting user input
+
+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.
+
+###10.4.1 Mouse button press and release events
+
+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:
+
+ XCB_EVENT_MASK_BUTTON_PRESS //notify us of any button that was pressed in one of our windows.
+ XCB_EVENT_MASK_BUTTON_RELEASE //notify us of any button that was released in one of our windows.
+
+Both kinds of events are represented with the same structure, but for the sake of self-documentation, it goes by two names:
+
+ 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 xcbbuttonmaskt and xcbmodmaskt enumerations):
+
+ XCB_BUTTON_MASK_1
+ XCB_BUTTON_MASK_2
+ XCB_BUTTON_MASK_3
+ XCB_BUTTON_MASK_4
+ XCB_BUTTON_MASK_5
+ XCB_MOD_MASK_SHIFT
+ XCB_MOD_MASK_LOCK
+ XCB_MOD_MASK_CONTROL
+ XCB_MOD_MASK_1
+ XCB_MOD_MASK_2
+ XCB_MOD_MASK_3
+ XCB_MOD_MASK_4
+ XCB_MOD_MASK_5
+
+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 (Mod mask 1 is usually the 'Alt' key or the 'Meta' key).
+
+TODO: Problem: it seems that the state does not change when clicking with various buttons.
+
+##### 10.4.2 Mouse movement events
+
+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 to register for these events:
+
+ XCB_EVENT_MASK_POINTER_MOTION // motion with no mouse button held
+ XCB_EVENT_MASK_BUTTON_MOTION // motion with one or more mouse buttons held
+ XCB_EVENT_MASK_BUTTON_1_MOTION // motion while only 1st mouse button is held
+ XCB_EVENT_MASK_BUTTON_2_MOTION // and so on...
+ XCB_EVENT_MASK_BUTTON_3_MOTION
+ XCB_EVENT_MASK_BUTTON_4_MOTION
+ XCB_EVENT_MASK_BUTTON_5_MOTION
+
+These all generate events of this type:
+
+ 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;
+
+##### 10.4.3 Mouse pointer enter and leave events
+
+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:
+
+* xcb_event_enter_window_t: notify us when the mouse pointer enters any of our controlled windows.
+* xcb_event_leave_window_t: notify us when the mouse pointer leaves any of our controlled windows.
+
+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;
+
+##### 10.4.4 The keyboard focus
+
+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...).
+
+##### 10.4.5 Keyboard press and release events
+
+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:
+
+ XCB_EVENT_MASK_KEY_PRESS // key was pressed while any of our controlled windows had the keyboard focus
+ XCB_EVENT_MASK_KEY_RELEASE // key was released while any of our controlled windows had the keyboard focus
+
+These generate events of the same type, which goes by two names:
+
+ typedef struct {
+ uint8_t response_type; /* The type of the event */
+ xcb_keycode_t detail; /* the physical key on the keyboard */
+ 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;
+
+TODO: Talk about getting the ASCII code from the key code.
+
+### 10.5 X events: a complete example
+
+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>
+
+ /* print names of modifiers present in mask */
+ void
+ print_modifiers (uint32_t mask)
+ {
+ const char *MODIFIERS[] = {
+ "Shift", "Lock", "Ctrl", "Alt",
+ "Mod2", "Mod3", "Mod4", "Mod5",
+ "Button1", "Button2", "Button3", "Button4", "Button5"
+ };
+
+ printf ("Modifier mask: ");
+ for (char **modifier = MODIFIERS ; mask; mask >>= 1, ++modifier) {
+ if (mask & 1) {
+ printf (*modifier);
+ }
+ }
+ printf ("\n");
+ }
+
+ int
+ main ()
+ {
+ /* Open the connection to the X server */
+ xcb_connection_t *connection = xcb_connect (NULL, NULL);
+
+ /* Get the first screen */
+ xcb_screen_t *screen = xcb_setup_roots_iterator (xcb_get_setup (c)).data;
+
+
+ /* Create the window */
+ xcb_window_t window = xcb_generate_id (connection);
+
+ uint32_t mask = XCB_CW_BACK_PIXEL | XCB_CW_EVENT_MASK;
+ uint32_t values[2] = {screen->white_pixel,
+ 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 (connection,
+ 0, /* depth */
+ window,
+ 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 */
+ xcb_map_window (c, win);
+
+ xcb_flush (c);
+
+ xcb_generic_event_t *event;
+ while (event = xcb_wait_for_event (connection)) {
+ switch (event->response_type & ~0x80) {
+ case XCB_EXPOSE:
+ xcb_expose_event_t *expose = (xcb_expose_event_t *)event;
+
+ printf ("Window %ld exposed. Region to be redrawn at location (%d,%d), with dimension (%d,%d)\n",
+ expose->window, expose->x, expose->y, expose->width, expose->height );
+ break;
+
+ case XCB_BUTTON_PRESS:
+ xcb_button_press_event_t *bp = (xcb_button_press_event_t *)event;
+ print_modifiers (bp->state);
+
+ switch (press->detail) {
+ case 4:
+ printf ("Wheel Button up in window %ld, at coordinates (%d,%d)\n",
+ bp->event, bp->event_x, bp->event_y );
+ break;
+ case 5:
+ printf ("Wheel Button down in window %ld, at coordinates (%d,%d)\n",
+ bp->event, bp->event_x, bp->event_y );
+ break;
+ default:
+ printf ("Button %d pressed in window %ld, at coordinates (%d,%d)\n",
+ bp->detail, bp->event, bp->event_x, bp->event_y );
+ break;
+ }
+ break;
+ case XCB_BUTTON_RELEASE:
+ xcb_button_release_event_t *br = (xcb_button_release_event_t *)event;
+ print_modifiers(release->state);
+
+ printf ("Button %d released in window %ld, at coordinates (%d,%d)\n",
+ br->detail, br->event, br->event_x, br->event_y );
+ break;
+
+ case XCB_MOTION_NOTIFY:
+ xcb_motion_notify_event_t *motion = (xcb_motion_notify_event_t *)event;
+
+ printf ("Mouse moved in window %ld, at coordinates (%d,%d)\n",
+ motion->event, motion->event_x, motion->event_y );
+ break;
+
+ case XCB_ENTER_NOTIFY:
+ xcb_enter_notify_event_t *enter = (xcb_enter_notify_event_t *)event;
+
+ printf ("Mouse entered window %ld, at coordinates (%d,%d)\n",
+ enter->event, enter->event_x, enter->event_y );
+ break;
+
+ case XCB_LEAVE_NOTIFY:
+ xcb_leave_notify_event_t *leave = (xcb_leave_notify_event_t *)event;
+
+ printf ("Mouse left window %ld, at coordinates (%d,%d)\n",
+ leave->event, leave->event_x, leave->event_y );
+ break;
+
+ case XCB_KEY_PRESS:
+ xcb_key_press_event_t *kp = (xcb_key_press_event_t *)event;
+ print_modifiers(kp->state);
+
+ printf ("Key pressed in window %ld\n",
+ kp->event);
+ break;
+
+ case XCB_KEY_RELEASE:
+ xcb_key_release_event_t *kr = (xcb_key_release_event_t *)event;
+ print_modifiers(kr->state);
+
+ printf ("Key released in window %ld\n",
+ kr->event);
+ break;
+
+ default:
+ /* Unknown event type, ignore it */
+ printf ("Unknown event: %d\n",
+ event->response_type);
+ break;
+ }
+
+ free (event);
+ }
+
+ return 0;
+ }
More information about the xcb-commit
mailing list