xkbcommon/xkbcommon-x11.h

   1 /*
   2  * Copyright © 2013 Ran Benita
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the "Software"),
   6  * to deal in the Software without restriction, including without limitation
   7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8  * and/or sell copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice (including the next
  12  * paragraph) shall be included in all copies or substantial portions of the
  13  * Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21  * DEALINGS IN THE SOFTWARE.
  22  */
  23
  24 #ifndef _XKBCOMMON_X11_H
  25 #define _XKBCOMMON_X11_H
  26
  27 #include <xcb/xcb.h>
  28 #include <xkbcommon/xkbcommon.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif
  33
  34 /**
  35  * @file
  36  * libxkbcommon-x11 API - Additional X11 support for xkbcommon.
  37  */
  38
  39 /**
  40  * @defgroup x11 X11 support
  41  * Additional X11 support for xkbcommon.
  42  * @since 0.4.0
  43  *
  44  * @{
  45  */
  46
  47 /**
  48  * @page x11-overview Overview
  49  * @parblock
  50  *
  51  * The xkbcommon-x11 module provides a means for creating an xkb_keymap
  52  * corresponding to the currently active keymap on the X server.  To do
  53  * so, it queries the XKB X11 extension using the xcb-xkb library.  It
  54  * can be used as a replacement for Xlib's keyboard handling.
  55  *
  56  * Following is an example workflow using xkbcommon-x11.  A complete
  57  * example may be found in the test/interactive-x11.c file in the
  58  * xkbcommon source repository.  On startup:
  59  *
  60  * 1. Connect to the X server using xcb_connect().
  61  * 2. Setup the XKB X11 extension.  You can do this either by using the
  62  *    xcb_xkb_use_extension() request directly, or by using the
  63  *    xkb_x11_setup_xkb_extension() helper function.
  64  *
  65  * The XKB extension supports using separate keymaps and states for
  66  * different keyboard devices.  The devices are identified by an integer
  67  * device ID and are managed by another X11 extension, XInput (or its
  68  * successor, XInput2).  The original X11 protocol only had one keyboard
  69  * device, called the "core keyboard", which is still supported as a
  70  * "virtual device".
  71  *
  72  * 3. We will use the core keyboard as an example.  To get its device ID,
  73  *    use either the xcb_xkb_get_device_info() request directly, or the
  74  *    xkb_x11_get_core_keyboard_device_id() helper function.
  75  * 4. Create an initial xkb_keymap for this device, using the
  76  *    xkb_x11_keymap_new_from_device() function.
  77  * 5. Create an initial xkb_state for this device, using the
  78  *    xkb_x11_state_new_from_device() function.
  79  *
  80  * Next, you need to react to state changes (e.g. a modifier was pressed,
  81  * the layout was changed) and to keymap changes (e.g. a tool like xkbcomp,
  82  * setxkbmap or xmodmap was used):
  83  *
  84  * 6. Select to listen to at least the following XKB events:
  85  *    NewKeyboardNotify, MapNotify, StateNotify; using the
  86  *    xcb_xkb_select_events_aux() request.
  87  * 7. When NewKeyboardNotify or MapNotify are received, recreate the
  88  *    xkb_keymap and xkb_state as described above.
  89  * 8. When StateNotify is received, update the xkb_state accordingly
  90  *    using the xkb_state_update_mask() function.
  91  *
  92  * Finally, when a key event is received, you can use ordinary xkbcommon
  93  * functions, like xkb_state_key_get_one_sym() and xkb_state_key_get_utf8(),
  94  * as you normally would.
  95  *
  96  * Note: There is no need to call xkb_state_update_key(); the state is
  97  * already synchronized.
  98  *
  99  * @endparblock
 100  */
 101
 102 /**
 103  * The minimal compatible major version of the XKB X11 extension which
 104  * this library can use.
 105  */
 106 #define XKB_X11_MIN_MAJOR_XKB_VERSION 1
 107 /**
 108  * The minimal compatible minor version of the XKB X11 extension which
 109  * this library can use (for the minimal major version).
 110  */
 111 #define XKB_X11_MIN_MINOR_XKB_VERSION 0
 112
 113 /** Flags for the xkb_x11_setup_xkb_extension() function. */
 114 enum xkb_x11_setup_xkb_extension_flags {
 115     /** Do not apply any flags. */
 116     XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS = 0
 117 };
 118
 119 /**
 120  * Setup the XKB X11 extension for this X client.
 121  *
 122  * The xkbcommon-x11 library uses various XKB requests.  Before doing so,
 123  * an X client must notify the server that it will be using the extension.
 124  * This function (or an XCB equivalent) must be called before any other
 125  * function in this library is used.
 126  *
 127  * Some X servers may not support or disable the XKB extension.  If you
 128  * want to support such servers, you need to use a different fallback.
 129  *
 130  * You may call this function several times; it is idempotent.
 131  *
 132  * @param connection
 133  *     An XCB connection to the X server.
 134  * @param major_xkb_version
 135  *     See @p minor_xkb_version.
 136  * @param minor_xkb_version
 137  *     The XKB extension version to request.  To operate correctly, you
 138  *     must have (major_xkb_version, minor_xkb_version) >=
 139  *     (XKB_X11_MIN_MAJOR_XKB_VERSION, XKB_X11_MIN_MINOR_XKB_VERSION),
 140  *     though this is not enforced.
 141  * @param flags
 142  *     Optional flags, or 0.
 143  * @param[out] major_xkb_version_out
 144  *     See @p minor_xkb_version_out.
 145  * @param[out] minor_xkb_version_out
 146  *     Backfilled with the compatible XKB extension version numbers picked
 147  *     by the server.  Can be NULL.
 148  * @param[out] base_event_out
 149  *     Backfilled with the XKB base (also known as first) event code, needed
 150  *     to distinguish XKB events.  Can be NULL.
 151  * @param[out] base_error_out
 152  *     Backfilled with the XKB base (also known as first) error code, needed
 153  *     to distinguish XKB errors.  Can be NULL.
 154  *
 155  * @returns 1 on success, or 0 on failure.
 156  */
 157 int
 158 xkb_x11_setup_xkb_extension(xcb_connection_t *connection,
 159                             uint16_t major_xkb_version,
 160                             uint16_t minor_xkb_version,
 161                             enum xkb_x11_setup_xkb_extension_flags flags,
 162                             uint16_t *major_xkb_version_out,
 163                             uint16_t *minor_xkb_version_out,
 164                             uint8_t *base_event_out,
 165                             uint8_t *base_error_out);
 166
 167 /**
 168  * Get the keyboard device ID of the core X11 keyboard.
 169  *
 170  * @param connection An XCB connection to the X server.
 171  *
 172  * @returns A device ID which may be used with other xkb_x11_* functions,
 173  *          or -1 on failure.
 174  */
 175 int32_t
 176 xkb_x11_get_core_keyboard_device_id(xcb_connection_t *connection);
 177
 178 /**
 179  * Create a keymap from an X11 keyboard device.
 180  *
 181  * This function queries the X server with various requests, fetches the
 182  * details of the active keymap on a keyboard device, and creates an
 183  * xkb_keymap from these details.
 184  *
 185  * @param context
 186  *     The context in which to create the keymap.
 187  * @param connection
 188  *     An XCB connection to the X server.
 189  * @param device_id
 190  *     An XInput 1 device ID (in the range 0-255) with input class KEY.
 191  *     Passing values outside of this range is an error.
 192  * @param flags
 193  *     Optional flags for the keymap, or 0.
 194  *
 195  * @returns A keymap retrieved from the X server, or NULL on failure.
 196  *
 197  * @memberof xkb_keymap
 198  */
 199 struct xkb_keymap *
 200 xkb_x11_keymap_new_from_device(struct xkb_context *context,
 201                                xcb_connection_t *connection,
 202                                int32_t device_id,
 203                                enum xkb_keymap_compile_flags flags);
 204
 205 /**
 206  * Create a new keyboard state object from an X11 keyboard device.
 207  *
 208  * This function is the same as xkb_state_new(), only pre-initialized
 209  * with the state of the device at the time this function is called.
 210  *
 211  * @param keymap
 212  *     The keymap for which to create the state.
 213  * @param connection
 214  *     An XCB connection to the X server.
 215  * @param device_id
 216  *     An XInput 1 device ID (in the range 0-255) with input class KEY.
 217  *     Passing values outside of this range is an error.
 218  *
 219  * @returns A new keyboard state object, or NULL on failure.
 220  *
 221  * @memberof xkb_state
 222  */
 223 struct xkb_state *
 224 xkb_x11_state_new_from_device(struct xkb_keymap *keymap,
 225                               xcb_connection_t *connection,
 226                               int32_t device_id);
 227
 228 /** @} */
 229
 230 #ifdef __cplusplus
 231 } /* extern "C" */
 232 #endif
 233
 234 #endif /* _XKBCOMMON_X11_H */