| 1 | #ifndef _XKBRULES_H_ |
| 2 | #define _XKBRULES_H_ 1 |
| 3 | |
| 4 | /************************************************************ |
| 5 | Copyright (c) 1996 by Silicon Graphics Computer Systems, Inc. |
| 6 | |
| 7 | Permission to use, copy, modify, and distribute this |
| 8 | software and its documentation for any purpose and without |
| 9 | fee is hereby granted, provided that the above copyright |
| 10 | notice appear in all copies and that both that copyright |
| 11 | notice and this permission notice appear in supporting |
| 12 | documentation, and that the name of Silicon Graphics not be |
| 13 | used in advertising or publicity pertaining to distribution |
| 14 | of the software without specific prior written permission. |
| 15 | Silicon Graphics makes no representation about the suitability |
| 16 | of this software for any purpose. It is provided "as is" |
| 17 | without any express or implied warranty. |
| 18 | |
| 19 | SILICON GRAPHICS DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS |
| 20 | SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
| 21 | AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SILICON |
| 22 | GRAPHICS BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL |
| 23 | DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, |
| 24 | DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE |
| 25 | OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH |
| 26 | THE USE OR PERFORMANCE OF THIS SOFTWARE. |
| 27 | |
| 28 | ********************************************************/ |
| 29 | |
| 30 | /***====================================================================***/ |
| 31 | |
| 32 | /** |
| 33 | * @brief xkb rules definitions |
| 34 | * |
| 35 | * The structure is used to query xkb rules definitions used to construct |
| 36 | * keyboard mapping. Those defs could be either set by the xorg.conf (with |
| 37 | * XkbModel, XkbLayout, XkbVariant and XkbOptions) or by client utility |
| 38 | * like setxkbmap. |
| 39 | * |
| 40 | * @see XkbRF_GetNamesProp, XkbRF_SetNamesProp, XkbRF_FreeVarDefs, |
| 41 | * man setxkbmap |
| 42 | */ |
| 43 | typedef struct _XkbRF_VarDefs { |
| 44 | char * model; /**< keyboard model e.g. "pc104" */ |
| 45 | char * layout; /**< layout list e.g. "us,ru" */ |
| 46 | char * variant; /**< layout variants list e.g. "dvorak," */ |
| 47 | char * options; /**< xkb options e.g "grp:toggle,misc:typo" */ |
| 48 | unsigned short sz_extra; /**< unused */ |
| 49 | unsigned short num_extra; /**< unused */ |
| 50 | char * extra_names; /**< unused */ |
| 51 | char ** extra_values; /**< unused */ |
| 52 | } XkbRF_VarDefsRec,*XkbRF_VarDefsPtr; |
| 53 | |
| 54 | typedef struct _XkbRF_VarDesc { |
| 55 | char * name; |
| 56 | char * desc; |
| 57 | } XkbRF_VarDescRec, *XkbRF_VarDescPtr; |
| 58 | |
| 59 | typedef struct _XkbRF_DescribeVars { |
| 60 | int sz_desc; |
| 61 | int num_desc; |
| 62 | XkbRF_VarDescPtr desc; |
| 63 | } XkbRF_DescribeVarsRec,*XkbRF_DescribeVarsPtr; |
| 64 | |
| 65 | typedef struct _XkbRF_Rule { |
| 66 | int number; |
| 67 | int layout_num; |
| 68 | int variant_num; |
| 69 | char * model; |
| 70 | char * layout; |
| 71 | char * variant; |
| 72 | char * option; |
| 73 | /* yields */ |
| 74 | char * keycodes; |
| 75 | char * symbols; |
| 76 | char * types; |
| 77 | char * compat; |
| 78 | char * geometry; |
| 79 | char * keymap; |
| 80 | unsigned flags; |
| 81 | } XkbRF_RuleRec,*XkbRF_RulePtr; |
| 82 | |
| 83 | typedef struct _XkbRF_Group { |
| 84 | int number; |
| 85 | char * name; |
| 86 | char * words; |
| 87 | } XkbRF_GroupRec, *XkbRF_GroupPtr; |
| 88 | |
| 89 | #define XkbRF_PendingMatch (1L<<1) |
| 90 | #define XkbRF_Option (1L<<2) |
| 91 | #define XkbRF_Append (1L<<3) |
| 92 | #define XkbRF_Normal (1L<<4) |
| 93 | #define XkbRF_Invalid (1L<<5) |
| 94 | |
| 95 | typedef struct _XkbRF_Rules { |
| 96 | XkbRF_DescribeVarsRec models; |
| 97 | XkbRF_DescribeVarsRec layouts; |
| 98 | XkbRF_DescribeVarsRec variants; |
| 99 | XkbRF_DescribeVarsRec options; |
| 100 | unsigned short sz_extra; |
| 101 | unsigned short num_extra; |
| 102 | char ** extra_names; |
| 103 | XkbRF_DescribeVarsPtr extra; |
| 104 | |
| 105 | unsigned short sz_rules; |
| 106 | unsigned short num_rules; |
| 107 | XkbRF_RulePtr rules; |
| 108 | unsigned short sz_groups; |
| 109 | unsigned short num_groups; |
| 110 | XkbRF_GroupPtr groups; |
| 111 | } XkbRF_RulesRec, *XkbRF_RulesPtr; |
| 112 | |
| 113 | /***====================================================================***/ |
| 114 | |
| 115 | _XFUNCPROTOBEGIN |
| 116 | |
| 117 | extern Bool XkbRF_GetComponents( |
| 118 | XkbRF_RulesPtr /* rules */, |
| 119 | XkbRF_VarDefsPtr /* var_defs */, |
| 120 | XkbComponentNamesPtr /* names */ |
| 121 | ); |
| 122 | |
| 123 | extern XkbRF_RulePtr XkbRF_AddRule( |
| 124 | XkbRF_RulesPtr /* rules */ |
| 125 | ); |
| 126 | |
| 127 | extern XkbRF_GroupPtr XkbRF_AddGroup(XkbRF_RulesPtr rules); |
| 128 | |
| 129 | extern Bool XkbRF_LoadRules( |
| 130 | FILE * /* file */, |
| 131 | XkbRF_RulesPtr /* rules */ |
| 132 | ); |
| 133 | |
| 134 | extern Bool XkbRF_LoadRulesByName( |
| 135 | char * /* base */, |
| 136 | char * /* locale */, |
| 137 | XkbRF_RulesPtr /* rules */ |
| 138 | ); |
| 139 | |
| 140 | /***====================================================================***/ |
| 141 | |
| 142 | extern XkbRF_VarDescPtr XkbRF_AddVarDesc( |
| 143 | XkbRF_DescribeVarsPtr /* vars */ |
| 144 | ); |
| 145 | |
| 146 | extern XkbRF_VarDescPtr XkbRF_AddVarDescCopy( |
| 147 | XkbRF_DescribeVarsPtr /* vars */, |
| 148 | XkbRF_VarDescPtr /* copy_from */ |
| 149 | ); |
| 150 | |
| 151 | extern XkbRF_DescribeVarsPtr XkbRF_AddVarToDescribe( |
| 152 | XkbRF_RulesPtr /* rules */, |
| 153 | char * /* name */ |
| 154 | ); |
| 155 | |
| 156 | extern Bool XkbRF_LoadDescriptions( |
| 157 | FILE * /* file */, |
| 158 | XkbRF_RulesPtr /* rules */ |
| 159 | ); |
| 160 | |
| 161 | extern Bool XkbRF_LoadDescriptionsByName( |
| 162 | char * /* base */, |
| 163 | char * /* locale */, |
| 164 | XkbRF_RulesPtr /* rules */ |
| 165 | ); |
| 166 | |
| 167 | extern XkbRF_RulesPtr XkbRF_Load( |
| 168 | char * /* base */, |
| 169 | char * /* locale */, |
| 170 | Bool /* wantDesc */, |
| 171 | Bool /* wantRules */ |
| 172 | ); |
| 173 | |
| 174 | extern XkbRF_RulesPtr XkbRF_Create( |
| 175 | int /* sz_rules */, |
| 176 | int /* sz_extra */ |
| 177 | ); |
| 178 | |
| 179 | /***====================================================================***/ |
| 180 | |
| 181 | extern void XkbRF_Free( |
| 182 | XkbRF_RulesPtr /* rules */, |
| 183 | Bool /* freeRules */ |
| 184 | ); |
| 185 | |
| 186 | |
| 187 | /***====================================================================***/ |
| 188 | |
| 189 | /** Name of the atom of the root window used to store/query xkb rules */ |
| 190 | #define _XKB_RF_NAMES_PROP_ATOM "_XKB_RULES_NAMES" |
| 191 | #define _XKB_RF_NAMES_PROP_MAXLEN 1024 |
| 192 | |
| 193 | /** |
| 194 | * @brief Queries X server's xkb rules |
| 195 | * @param[in] dpy - X Display |
| 196 | * @param[out] rules_file_rtrn |
| 197 | * if not NULL returns a pointer to the name of xkb rule file used by the |
| 198 | * X server (usually located in /usr/share/X11/xkb/rules/). The string |
| 199 | * shall be explicitly freed by the caller using free(). |
| 200 | * @param[out] var_defs_rtrn |
| 201 | * a pointer to a @struct XkbRF_VarDefsRec where a data queried from the |
| 202 | * server will be stored. Some data in the structure will be dynamically |
| 203 | * allocated and shall be later explicitly freed by the caller using |
| 204 | * XkbRF_FreeVarDefs(). |
| 205 | * @return @c True on success, @c False on failure |
| 206 | * |
| 207 | * Queries X server's xkb rules using the "_XKB_RULES_NAMES" atom of the |
| 208 | * root window. As of 2024 (and been like that for a long time) this is not |
| 209 | * officially documented in the form of an extension to X11 protocol, but |
| 210 | * it's provided by the reference xorg implementation and used by several |
| 211 | * utilities like setxkbmap. |
| 212 | */ |
| 213 | extern Bool XkbRF_GetNamesProp( |
| 214 | Display * /* dpy */, |
| 215 | char ** /* rules_file_rtrn */, |
| 216 | XkbRF_VarDefsPtr /* var_defs_rtrn */ |
| 217 | ); |
| 218 | |
| 219 | /** |
| 220 | * @brief Sets the X server's xkb rules property |
| 221 | * @param[in] dpy - X Display |
| 222 | * @param[in] rules_file - a rules file used to compile xkb key mapping |
| 223 | * @param[in] var_defs - list of xkb rules |
| 224 | * @return @c True on success, @c False on failure |
| 225 | * |
| 226 | * Sets X server's xkb rules property stored in the "_XKB_RULES_NAMES" atom |
| 227 | * of root window. |
| 228 | * |
| 229 | * @note Setting this property doesn't change the layout configuration. |
| 230 | * It's only used to tell other clients which rules were used to compile |
| 231 | * the current layout configuration. In order to actually construct and |
| 232 | * set configuration based on rules @see XkbRF_GetComponents() and |
| 233 | * XkbGetKeyboardByName() (from Xkblib) |
| 234 | */ |
| 235 | extern Bool XkbRF_SetNamesProp( |
| 236 | Display * /* dpy */, |
| 237 | char * /* rules_file */, |
| 238 | XkbRF_VarDefsPtr /* var_defs */ |
| 239 | ); |
| 240 | |
| 241 | /** |
| 242 | * @brief Destroy @struct XkbRF_VarDefsRec |
| 243 | * @param[in] var_defs - a XkbRF_VarDefsRec to clean up |
| 244 | * @param[in] freeVarDefs - if @c True also free the @p var_defs itself |
| 245 | * |
| 246 | * Frees the memory associated with the @p var_defs. If @p free_var_defs is |
| 247 | * @c True also frees the @p var_defs pointer itself. |
| 248 | */ |
| 249 | extern void XkbRF_FreeVarDefs( |
| 250 | XkbRF_VarDefsPtr /* var_defs */, |
| 251 | Bool /* freeVarDefs */ |
| 252 | ); |
| 253 | |
| 254 | _XFUNCPROTOEND |
| 255 | |
| 256 | #endif /* _XKBRULES_H_ */ |