diff options
Diffstat (limited to 'src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h')
-rw-r--r-- | src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h | 78 |
1 files changed, 74 insertions, 4 deletions
diff --git a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h index d9e2a4f11a..cf244d2559 100644 --- a/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h +++ b/src/3rdparty/xkbcommon/xkbcommon/xkbcommon-x11.h @@ -39,11 +39,76 @@ extern "C" { /** * @defgroup x11 X11 support * Additional X11 support for xkbcommon. + * @since 0.4.0 * * @{ */ /** + * @page x11-overview Overview + * @parblock + * + * The xkbcommon-x11 module provides a means for creating an xkb_keymap + * corresponding to the currently active keymap on the X server. To do + * so, it queries the XKB X11 extension using the xcb-xkb library. It + * can be used as a replacement for Xlib's keyboard handling. + * + * Following is an example workflow using xkbcommon-x11. A complete + * example may be found in the test/interactive-x11.c file in the + * xkbcommon source repository. On startup: + * + * 1. Connect to the X server using xcb_connect(). + * 2. Setup the XKB X11 extension. You can do this either by using the + * xcb_xkb_use_extension() request directly, or by using the + * xkb_x11_setup_xkb_extension() helper function. + * + * The XKB extension supports using separate keymaps and states for + * different keyboard devices. The devices are identified by an integer + * device ID and are managed by another X11 extension, XInput. The + * original X11 protocol only had one keyboard device, called the "core + * keyboard", which is still supported as a "virtual device". + * + * 3. We will use the core keyboard as an example. To get its device ID, + * use either the xcb_xkb_get_device_info() request directly, or the + * xkb_x11_get_core_keyboard_device_id() helper function. + * 4. Create an initial xkb_keymap for this device, using the + * xkb_x11_keymap_new_from_device() function. + * 5. Create an initial xkb_state for this device, using the + * xkb_x11_state_new_from_device() function. + * + * @note At this point, you may consider setting various XKB controls and + * XKB per-client flags. For example, enabling detectable autorepeat: \n + * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Detectable_Autorepeat + * + * Next, you need to react to state changes (e.g. a modifier was pressed, + * the layout was changed) and to keymap changes (e.g. a tool like xkbcomp, + * setxkbmap or xmodmap was used): + * + * 6. Select to listen to at least the following XKB events: + * NewKeyboardNotify, MapNotify, StateNotify; using the + * xcb_xkb_select_events_aux() request. + * 7. When NewKeyboardNotify or MapNotify are received, recreate the + * xkb_keymap and xkb_state as described above. + * 8. When StateNotify is received, update the xkb_state accordingly + * using the xkb_state_update_mask() function. + * + * @note It is also possible to use the KeyPress/KeyRelease @p state + * field to find the effective modifier and layout state, instead of + * using XkbStateNotify: \n + * https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Computing_A_State_Field_from_an_XKB_State + * \n However, XkbStateNotify is more accurate. + * + * @note There is no need to call xkb_state_update_key(); the state is + * already synchronized. + * + * Finally, when a key event is received, you can use ordinary xkbcommon + * functions, like xkb_state_key_get_one_sym() and xkb_state_key_get_utf8(), + * as you normally would. + * + * @endparblock + */ + +/** * The minimal compatible major version of the XKB X11 extension which * this library can use. */ @@ -75,14 +140,18 @@ enum xkb_x11_setup_xkb_extension_flags { * * @param connection * An XCB connection to the X server. - * @param major_xkb_version, minor_xkb_version + * @param major_xkb_version + * See @p minor_xkb_version. + * @param minor_xkb_version * The XKB extension version to request. To operate correctly, you * must have (major_xkb_version, minor_xkb_version) >= * (XKB_X11_MIN_MAJOR_XKB_VERSION, XKB_X11_MIN_MINOR_XKB_VERSION), * though this is not enforced. * @param flags * Optional flags, or 0. - * @param[out] major_xkb_version_out, minor_xkb_version_out + * @param[out] major_xkb_version_out + * See @p minor_xkb_version_out. + * @param[out] minor_xkb_version_out * Backfilled with the compatible XKB extension version numbers picked * by the server. Can be NULL. * @param[out] base_event_out @@ -127,8 +196,9 @@ xkb_x11_get_core_keyboard_device_id(xcb_connection_t *connection); * @param connection * An XCB connection to the X server. * @param device_id - * An XInput 1 device ID (in the range 0-255) with input class KEY. - * Passing values outside of this range is an error. + * An XInput device ID (in the range 0-127) with input class KEY. + * Passing values outside of this range is an error (the XKB protocol + * predates the XInput2 protocol, which first allowed IDs > 127). * @param flags * Optional flags for the keymap, or 0. * |