Move include files to include/ subdirectory

This way we don't specify `include_directorories('.')` which brings in
more than needed.

Signed-off-by: Ran Benita <ran@unusedvar.com>

1 files changed, 244 insertions, 0 deletions

diff --git a/include/xkbcommon/xkbcommon-x11.h b/include/xkbcommon/xkbcommon-x11.h
new file mode 100644
index 0000000..4eb716a
--- /dev/null
+++ b/include/xkbcommon/xkbcommon-x11.h
@@ -0,0 +1,244 @@
+/*
+ * Copyright © 2013 Ran Benita
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef _XKBCOMMON_X11_H
+#define _XKBCOMMON_X11_H
+
+#include <xcb/xcb.h>
+#include <xkbcommon/xkbcommon.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @file
+ * libxkbcommon-x11 API - Additional X11 support for xkbcommon.
+ */
+
+/**
+ * @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 tools/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.
+ */
+#define XKB_X11_MIN_MAJOR_XKB_VERSION 1
+/**
+ * The minimal compatible minor version of the XKB X11 extension which
+ * this library can use (for the minimal major version).
+ */
+#define XKB_X11_MIN_MINOR_XKB_VERSION 0
+
+/** Flags for the xkb_x11_setup_xkb_extension() function. */
+enum xkb_x11_setup_xkb_extension_flags {
+    /** Do not apply any flags. */
+    XKB_X11_SETUP_XKB_EXTENSION_NO_FLAGS = 0
+};
+
+/**
+ * Setup the XKB X11 extension for this X client.
+ *
+ * The xkbcommon-x11 library uses various XKB requests.  Before doing so,
+ * an X client must notify the server that it will be using the extension.
+ * This function (or an XCB equivalent) must be called before any other
+ * function in this library is used.
+ *
+ * Some X servers may not support or disable the XKB extension.  If you
+ * want to support such servers, you need to use a different fallback.
+ *
+ * You may call this function several times; it is idempotent.
+ *
+ * @param connection
+ *     An XCB connection to the X server.
+ * @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
+ *     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
+ *     Backfilled with the XKB base (also known as first) event code, needed
+ *     to distinguish XKB events.  Can be NULL.
+ * @param[out] base_error_out
+ *     Backfilled with the XKB base (also known as first) error code, needed
+ *     to distinguish XKB errors.  Can be NULL.
+ *
+ * @returns 1 on success, or 0 on failure.
+ */
+int
+xkb_x11_setup_xkb_extension(xcb_connection_t *connection,
+                            uint16_t major_xkb_version,
+                            uint16_t minor_xkb_version,
+                            enum xkb_x11_setup_xkb_extension_flags flags,
+                            uint16_t *major_xkb_version_out,
+                            uint16_t *minor_xkb_version_out,
+                            uint8_t *base_event_out,
+                            uint8_t *base_error_out);
+
+/**
+ * Get the keyboard device ID of the core X11 keyboard.
+ *
+ * @param connection An XCB connection to the X server.
+ *
+ * @returns A device ID which may be used with other xkb_x11_* functions,
+ *          or -1 on failure.
+ */
+int32_t
+xkb_x11_get_core_keyboard_device_id(xcb_connection_t *connection);
+
+/**
+ * Create a keymap from an X11 keyboard device.
+ *
+ * This function queries the X server with various requests, fetches the
+ * details of the active keymap on a keyboard device, and creates an
+ * xkb_keymap from these details.
+ *
+ * @param context
+ *     The context in which to create the keymap.
+ * @param connection
+ *     An XCB connection to the X server.
+ * @param device_id
+ *     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.
+ *
+ * @returns A keymap retrieved from the X server, or NULL on failure.
+ *
+ * @memberof xkb_keymap
+ */
+struct xkb_keymap *
+xkb_x11_keymap_new_from_device(struct xkb_context *context,
+                               xcb_connection_t *connection,
+                               int32_t device_id,
+                               enum xkb_keymap_compile_flags flags);
+
+/**
+ * Create a new keyboard state object from an X11 keyboard device.
+ *
+ * This function is the same as xkb_state_new(), only pre-initialized
+ * with the state of the device at the time this function is called.
+ *
+ * @param keymap
+ *     The keymap for which to create the state.
+ * @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.
+ *
+ * @returns A new keyboard state object, or NULL on failure.
+ *
+ * @memberof xkb_state
+ */
+struct xkb_state *
+xkb_x11_state_new_from_device(struct xkb_keymap *keymap,
+                              xcb_connection_t *connection,
+                              int32_t device_id);
+
+/** @} */
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* _XKBCOMMON_X11_H */