[Xcb-commit] tutorial.mdwn
XCB site
xcb at freedesktop.org
Sun Nov 11 20:42:17 PST 2007
tutorial.mdwn | 98 ++++++++++++++++++++++++++++------------------------------
1 file changed, 48 insertions(+), 50 deletions(-)
New commits:
commit c6e082d0d67a5d32bb555515d2e1bf837c125734
Author: brian.thomas.will <brian.thomas.will at gmail.com>
Date: Sun Nov 11 20:42:16 2007 -0800
refactored section 9.4 ("registering for event types); mostly formatting cleanup
diff --git a/tutorial.mdwn b/tutorial.mdwn
index d83d4c8..8df123e 100644
--- a/tutorial.mdwn
+++ b/tutorial.mdwn
@@ -815,68 +815,66 @@ TODO: Use screen->root_depth for depth parameter.
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
+###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 "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:
+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 (c);
- xcb_create_window (c, depth, win, root->root,
- 0, 0, 150, 150, 10,
- XCB_WINDOW_CLASS_INPUT_OUTPUT, root->root_visual,
- mask, valwin);
+ 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:
+XCB\_EVENT\_MASK\_EXPOSURE is a constant defined in the xcbeventmaskt 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);
+ 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 };
+The values that a mask could take are given by the xcb\_cw\_t enumeration:
- /* The connection c and the window win are supposed to be defined */
+ 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 (c, win, XCB_CW_EVENT_MASK, values);
+ xcb_configure_window (connection, window, XCB_CW_EVENT_MASK, 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.
+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
More information about the xcb-commit
mailing list