Commit 3a0adc0f5c1e79c333477e81efe77134a84f473d
2013-07-31T10:38:30
doc: try to clarify some subtle points Which to choose: xkb_state_update_key() / xkb_state_update_mask(). If you use update_mask(), you don't (and shouldn't) use update_key(). If you use update_key(), be careful not to have unmatched UP/DOWN calls; this can bring about stuck modifiers etc. Probably want to use XKB_STATE_{MODS,LAYOUT}_EFFECTIVE. The others are only useful in very special cases. Signed-off-by: Ran Benita <ran234@gmail.com>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130
diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index ff2ce68..c9b84b2 100644
--- a/xkbcommon/xkbcommon.h
+++ b/xkbcommon/xkbcommon.h
@@ -1110,7 +1110,8 @@ enum xkb_state_component {
* lock has been pressed again. */
XKB_STATE_MODS_LOCKED = (1 << 2),
/** Effective modifiers, i.e. currently active and affect key
- * processing (derived from the other state components). */
+ * processing (derived from the other state components).
+ * Use this unless you explictly care how the state came about. */
XKB_STATE_MODS_EFFECTIVE = (1 << 3),
/** Depressed layout, i.e. a key is physically holding it. */
XKB_STATE_LAYOUT_DEPRESSED = (1 << 4),
@@ -1121,7 +1122,8 @@ enum xkb_state_component {
* has been pressed again. */
XKB_STATE_LAYOUT_LOCKED = (1 << 6),
/** Effective layout, i.e. currently active and affects key processing
- * (derived from the other state components). */
+ * (derived from the other state components).
+ * Use this unless you explictly care how the state came about. */
XKB_STATE_LAYOUT_EFFECTIVE = (1 << 7),
/** LEDs (derived from the other state components). */
XKB_STATE_LEDS = (1 << 8)
@@ -1131,16 +1133,65 @@ enum xkb_state_component {
* Update the keyboard state to reflect a given key being pressed or
* released.
*
+ * This entry point is intended for programs which track the keyboard state
+ * explictly (like an evdev client). If the state is serialized to you by
+ * a master process (like an X server, a Wayland compositor) you should
+ * use xkb_state_update_mask() instead. The two functins should not
+ * generally be used together.
+ *
+ * A series of calls to this function should be consistent; that is, a call
+ * with XKB_KEY_DOWN for a key should be matched by an XKB_KEY_UP; if a key
+ * is pressed twice, it should be released twice; etc. Otherwise (e.g. due
+ * to missed input events), situations like "stuck modifiers" may occur.
+ *
* @returns A mask of state components that have changed as a result of
* the update. If nothing in the state has changed, returns 0.
*
* @memberof xkb_state
+ *
+ * @sa xkb_state_update_mask()
*/
enum xkb_state_component
xkb_state_update_key(struct xkb_state *state, xkb_keycode_t key,
enum xkb_key_direction direction);
/**
+ * Update a keyboard state from a set of explicit masks.
+ *
+ * This entry point is intended for window systems and the like, where a
+ * master process holds an xkb_state, then serializes it over a wire
+ * protocol, and clients then use the serialization to feed in to their own
+ * xkb_state.
+ *
+ * All parameters must always be passed, or the resulting state may be
+ * incoherent.
+ *
+ * The serialization is lossy and will not survive round trips; it must only
+ * be used to feed slave state objects, and must not be used to update the
+ * master state.
+ *
+ * If you do not fit the description above, you should use
+ * xkb_state_update_key() instead. The two functions should not generally be
+ * used together.
+ *
+ * @returns A mask of state components that have changed as a result of
+ * the update. If nothing in the state has changed, returns 0.
+ *
+ * @memberof xkb_state
+ *
+ * @sa xkb_state_component
+ * @sa xkb_state_update_key
+ */
+enum xkb_state_component
+xkb_state_update_mask(struct xkb_state *state,
+ xkb_mod_mask_t depressed_mods,
+ xkb_mod_mask_t latched_mods,
+ xkb_mod_mask_t locked_mods,
+ xkb_layout_index_t depressed_layout,
+ xkb_layout_index_t latched_layout,
+ xkb_layout_index_t locked_layout);
+
+/**
* Get the keysyms obtained from pressing a particular key in a given
* keyboard state.
*
@@ -1244,39 +1295,6 @@ enum xkb_state_match {
};
/**
- * Update a keyboard state from a set of explicit masks.
- *
- * This entry point is really only for window systems and the like, where a
- * master process holds an xkb_state, then serializes it over a wire
- * protocol, and clients then use the serialization to feed in to their own
- * xkb_state.
- *
- * All parameters must always be passed, or the resulting state may be
- * incoherent.
- *
- * The serialization is lossy and will not survive round trips; it must only
- * be used to feed slave state objects, and must not be used to update the
- * master state.
- *
- * Please do not use this unless you fit the description above.
- *
- * @returns A mask of state components that have changed as a result of
- * the update. If nothing in the state has changed, returns 0.
- *
- * @memberof xkb_state
- *
- * @sa xkb_state_component
- */
-enum xkb_state_component
-xkb_state_update_mask(struct xkb_state *state,
- xkb_mod_mask_t depressed_mods,
- xkb_mod_mask_t latched_mods,
- xkb_mod_mask_t locked_mods,
- xkb_layout_index_t depressed_layout,
- xkb_layout_index_t latched_layout,
- xkb_layout_index_t locked_layout);
-
-/**
* The counterpart to xkb_state_update_mask for modifiers, to be used on
* the server side of serialization.
*