summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAlexander Golubev <fatzer2@gmail.com>2024-03-17 03:48:08 +0300
committerPeter Hutterer <peter.hutterer@who-t.net>2024-03-18 11:26:28 +1000
commit948cbfb38a76df395e7d9458c472901bcfefb969 (patch)
tree82b0949e894adc3e53246fe4a7681d4e40a61b0d
parent6afd4ae4473e7c1701ae3be9813ca2857395f2a5 (diff)
Document XkbRF_VarDefsRec and some related functions
Document next symbols: - XkbRF_VarDefsRec - XkbRF_GetNamesProp() - XkbRF_SetNamesProp() - _XKB_RF_NAMES_PROP_ATOM Signed-off-by: Alexander Golubev <fatzer2@gmail.com>
-rw-r--r--include/X11/extensions/XKBrules.h77
1 files changed, 62 insertions, 15 deletions
diff --git a/include/X11/extensions/XKBrules.h b/include/X11/extensions/XKBrules.h
index 8580b55..e729a2d 100644
--- a/include/X11/extensions/XKBrules.h
+++ b/include/X11/extensions/XKBrules.h
@@ -29,15 +29,26 @@
/***====================================================================***/
+/**
+ * @brief xkb rules definitions
+ *
+ * The structure is used to query xkb rules definitions used to construct
+ * keyboard mapping. Those defs could be either set by the xorg.conf (with
+ * XkbModel, XkbLayout, XkbVariant and XkbOptions) or by client utility
+ * like setxkbmap.
+ *
+ * @see XkbRF_GetNamesProp, XkbRF_SetNamesProp, XkbRF_FreeVarDefs,
+ * man setxkbmap
+ */
typedef struct _XkbRF_VarDefs {
- char * model;
- char * layout;
- char * variant;
- char * options;
- unsigned short sz_extra;
- unsigned short num_extra;
- char * extra_names;
- char ** extra_values;
+ char * model; /**< keyboard model e.g. "pc104" */
+ char * layout; /**< layout list e.g. "us,ru" */
+ char * variant; /**< layout variants list e.g. "dvorak," */
+ char * options; /**< xkb options e.g "grp:toggle,misc:typo" */
+ unsigned short sz_extra; /**< unused */
+ unsigned short num_extra; /**< unused */
+ char * extra_names; /**< unused */
+ char ** extra_values; /**< unused */
} XkbRF_VarDefsRec,*XkbRF_VarDefsPtr;
typedef struct _XkbRF_VarDesc {
@@ -175,20 +186,56 @@ extern void XkbRF_Free(
/***====================================================================***/
+/** Name of the atom of the root window used to store/query xkb rules */
#define _XKB_RF_NAMES_PROP_ATOM "_XKB_RULES_NAMES"
#define _XKB_RF_NAMES_PROP_MAXLEN 1024
-
+/**
+ * @brief Queries X server's xkb rules
+ * @param[in] dpy - X Display
+ * @param[out] rules_file_rtrn
+ * if not NULL returns a pointer to the name of xkb rule file used by the
+ * X server (usually located in /usr/share/X11/xkb/rules/). The string
+ * shall be explicitly freed by the caller using free().
+ * @param[out] var_defs_rtrn
+ * a pointer to a @struct XkbRF_VarDefsRec where a data queried from the
+ * server will be stored. Some data in the structure will be dynamically
+ * allocated and shall be later explicitly freed by the caller using
+ * XkbRF_FreeVarDefs().
+ * @return @c True on success, @c False on failure
+ *
+ * Queries X server's xkb rules using the "_XKB_RULES_NAMES" atom of the
+ * root window. As of 2024 (and been like that for a long time) this is not
+ * officially documented in the form of an extension to X11 protocol, but
+ * it's provided by the reference xorg implementation and used by several
+ * utilities like setxkbmap.
+ */
extern Bool XkbRF_GetNamesProp(
- Display * /* dpy */,
- char ** /* rules_file_rtrn */,
- XkbRF_VarDefsPtr /* var_defs_rtrn */
+ Display * /* dpy */,
+ char ** /* rules_file_rtrn */,
+ XkbRF_VarDefsPtr /* var_defs_rtrn */
);
+/**
+ * @brief Sets the X server's xkb rules property
+ * @param[in] dpy - X Display
+ * @param[in] rules_file - a rules file used to compile xkb key mapping
+ * @param[in] var_defs - list of xkb rules
+ * @return @c True on success, @c False on failure
+ *
+ * Sets X server's xkb rules property stored in the "_XKB_RULES_NAMES" atom
+ * of root window.
+ *
+ * @note Setting this property doesn't change the layout configuration.
+ * It's only used to tell other clients which rules were used to compile
+ * the current layout configuration. In order to actually construct and
+ * set configuration based on rules @see XkbRF_GetComponents() and
+ * XkbGetKeyboardByName() (from Xkblib)
+ */
extern Bool XkbRF_SetNamesProp(
- Display * /* dpy */,
- char * /* rules_file */,
- XkbRF_VarDefsPtr /* var_defs */
+ Display * /* dpy */,
+ char * /* rules_file */,
+ XkbRF_VarDefsPtr /* var_defs */
);
/**