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  * The minimal compatible major version of the XKB X11 extension which
  49  * this library can use.
  50  */
  51 #define XKB_X11_MIN_MAJOR_XKB_VERSION 1
  52 /**
  53  * The minimal compatible minor version of the XKB X11 extension which
  54  * this library can use (for the minimal major version).
  55  */
  56 #define XKB_X11_MIN_MINOR_XKB_VERSION 0
  57
  58 /** Flags for the xkb_x11_setup_xkb_extension() function. */
  59 enum xkb_x11_setup_xkb_extension_flags {
  60     /** Do not apply any flags. */
  61     XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS = 0
  62 };
  63
  64 /**
  65  * Setup the XKB X11 extension for this X client.
  66  *
  67  * The xkbcommon-x11 library uses various XKB requests.  Before doing so,
  68  * an X client must notify the server that it will be using the extension.
  69  * This function (or an XCB equivalent) must be called before any other
  70  * function in this library is used.
  71  *
  72  * Some X servers may not support or disable the XKB extension.  If you
  73  * want to support such servers, you need to use a different fallback.
  74  *
  75  * You may call this function several times; it is idempotent.
  76  *
  77  * @param connection
  78  *     An XCB connection to the X server.
  79  * @param major_xkb_version, minor_xkb_version
  80  *     The XKB extension version to request.  To operate correctly, you
  81  *     must have (major_xkb_version, minor_xkb_version) >=
  82  *     (XKB_X11_MIN_MAJOR_XKB_VERSION, XKB_X11_MIN_MINOR_XKB_VERSION),
  83  *     though this is not enforced.
  84  * @param flags
  85  *     Optional flags, or 0.
  86  * @param[out] major_xkb_version_out, minor_xkb_version_out
  87  *     Backfilled with the compatible XKB extension version numbers picked
  88  *     by the server.  Can be NULL.
  89  * @param[out] base_event_out
  90  *     Backfilled with the XKB base (also known as first) event code, needed
  91  *     to distinguish XKB events.  Can be NULL.
  92  * @param[out] base_error_out
  93  *     Backfilled with the XKB base (also known as first) error code, needed
  94  *     to distinguish XKB errors.  Can be NULL.
  95  *
  96  * @returns 1 on success, or 0 on failure.
  97  */
  98 int
  99 xkb_x11_setup_xkb_extension(xcb_connection_t *connection,
 100                             uint16_t major_xkb_version,
 101                             uint16_t minor_xkb_version,
 102                             enum xkb_x11_setup_xkb_extension_flags flags,
 103                             uint16_t *major_xkb_version_out,
 104                             uint16_t *minor_xkb_version_out,
 105                             uint8_t *base_event_out,
 106                             uint8_t *base_error_out);
 107
 108 /**
 109  * Get the keyboard device ID of the core X11 keyboard.
 110  *
 111  * @param connection An XCB connection to the X server.
 112  *
 113  * @returns A device ID which may be used with other xkb_x11_* functions,
 114  *          or -1 on failure.
 115  */
 116 int32_t
 117 xkb_x11_get_core_keyboard_device_id(xcb_connection_t *connection);
 118
 119 /**
 120  * Create a keymap from an X11 keyboard device.
 121  *
 122  * This function queries the X server with various requests, fetches the
 123  * details of the active keymap on a keyboard device, and creates an
 124  * xkb_keymap from these details.
 125  *
 126  * @param context
 127  *     The context in which to create the keymap.
 128  * @param connection
 129  *     An XCB connection to the X server.
 130  * @param device_id
 131  *     An XInput 1 device ID (in the range 0-255) with input class KEY.
 132  *     Passing values outside of this range is an error.
 133  * @param flags
 134  *     Optional flags for the keymap, or 0.
 135  *
 136  * @returns A keymap retrieved from the X server, or NULL on failure.
 137  *
 138  * @memberof xkb_keymap
 139  */
 140 struct xkb_keymap *
 141 xkb_x11_keymap_new_from_device(struct xkb_context *context,
 142                                xcb_connection_t *connection,
 143                                int32_t device_id,
 144                                enum xkb_keymap_compile_flags flags);
 145
 146 /**
 147  * Create a new keyboard state object from an X11 keyboard device.
 148  *
 149  * This function is the same as xkb_state_new(), only pre-initialized
 150  * with the state of the device at the time this function is called.
 151  *
 152  * @param keymap
 153  *     The keymap for which to create the state.
 154  * @param connection
 155  *     An XCB connection to the X server.
 156  * @param device_id
 157  *     An XInput 1 device ID (in the range 0-255) with input class KEY.
 158  *     Passing values outside of this range is an error.
 159  *
 160  * @returns A new keyboard state object, or NULL on failure.
 161  *
 162  * @memberof xkb_state
 163  */
 164 struct xkb_state *
 165 xkb_x11_state_new_from_device(struct xkb_keymap *keymap,
 166                               xcb_connection_t *connection,
 167                               int32_t device_id);
 168
 169 /** @} */
 170
 171 #ifdef __cplusplus
 172 } /* extern "C" */
 173 #endif
 174
 175 #endif /* _XKBCOMMON_X11_H */