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_COMPOSE_H 25 #define _XKBCOMMON_COMPOSE_H 26 27 #include <xkbcommon/xkbcommon.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * @file 35 * libxkbcommon Compose API - support for Compose and dead-keys. 36 */ 37 38 /** 39 * @defgroup compose Compose and dead-keys support 40 * Support for Compose and dead-keys. 41 * @since 0.5.0 42 * 43 * @{ 44 */ 45 46 /** 47 * @page compose-overview Overview 48 * @parblock 49 * 50 * Compose and dead-keys are a common feature of many keyboard input 51 * systems. They extend the range of the keysysm that can be produced 52 * directly from a keyboard by using a sequence of key strokes, instead 53 * of just one. 54 * 55 * Here are some example sequences, in the libX11 Compose file format: 56 * 57 * <dead_acute> <a> : "" aacute # LATIN SMALL LETTER A WITH ACUTE 58 * <Multi_key> <A> <T> : "@" at # COMMERCIAL AT 59 * 60 * When the user presses a key which produces the \<dead_acute> keysym, 61 * nothing initially happens (thus the key is dubbed a "dead-key"). But 62 * when the user enters <a>, "" is "composed", in place of "a". If 63 * instead the user had entered a keysym which does not follow 64 * \<dead_acute\> in any compose sequence, the sequence is said to be 65 * "cancelled". 66 * 67 * Compose files define many such sequences. For a description of the 68 * common file format for Compose files, see the Compose(5) man page. 69 * 70 * A successfuly-composed sequence has two results: a keysym and a UTF-8 71 * string. At least one of the two is defined for each sequence. If only 72 * a keysym is given, the keysym's string representation is used for the 73 * result string (using xkb_keysym_to_utf8()). 74 * 75 * This library provides low-level support for Compose file parsing and 76 * processing. Higher-level APIs (such as libX11's Xutf8LookupString(3)) 77 * may be built upon it, or it can be used directly. 78 * 79 * @endparblock 80 */ 81 82 /** 83 * @page compose-conflicting Conflicting Sequences 84 * @parblock 85 * 86 * To avoid ambiguity, a sequence is not allowed to be a prefix of another. 87 * In such a case, the conflict is resolved thus: 88 * 89 * 1. A longer sequence overrides a shorter one. 90 * 2. An equal sequence overrides an existing one. 91 * 3. A shorter sequence does not override a longer one. 92 * 93 * Sequences of length 1 are allowed, although they are not common. 94 * 95 * @endparblock 96 */ 97 98 /** 99 * @page compose-cancellation Cancellation Behavior 100 * @parblock 101 * 102 * What should happen when a sequence is cancelled? For example, consider 103 * there are only the above sequences, and the input kesysms are 104 * \<dead_acute\> \<b\>. There are a few approaches: 105 * 106 * 1. Swallow the cancelling keysym; that is, no keysym is produced. 107 * This is the approach taken by libX11. 108 * 2. Let the cancelling keysym through; that is, \<b\> is produced. 109 * 3. Replay the entire sequence; that is, \<dead_acute\> \<b\> is produced. 110 * This is the approach taken by Microsoft Windows (approximately; 111 * instead of \<dead_acute\>, the underlying key is used. This is 112 * difficult to simulate with XKB keymaps). 113 * 114 * You can program whichever approach best fits users' expectations. 115 * 116 * @endparblock 117 */ 118 119 /** 120 * @struct xkb_compose_table 121 * Opaque Compose table object. 122 * 123 * The compose table holds the definitions of the Compose sequences, as 124 * gathered from Compose files. It is immutable. 125 */ 126 struct xkb_compose_table; 127 128 /** 129 * @struct xkb_compose_state 130 * Opaque Compose state object. 131 * 132 * The compose state maintains state for compose sequence matching, such 133 * as which possible sequences are being matched, and the position within 134 * these sequences. It acts as a simple state machine wherein keysyms are 135 * the input, and composed keysyms and strings are the output. 136 * 137 * The compose state is usually associated with a keyboard device. 138 */ 139 struct xkb_compose_state; 140 141 /** Flags affecting Compose file compilation. */ 142 enum xkb_compose_compile_flags { 143 /** Do not apply any flags. */ 144 XKB_COMPOSE_COMPILE_NO_FLAGS = 0 145 }; 146 147 /** The recognized Compose file formats. */ 148 enum xkb_compose_format { 149 /** The classic libX11 Compose text format, described in Compose(5). */ 150 XKB_COMPOSE_FORMAT_TEXT_V1 = 1 151 }; 152 153 /** 154 * @page compose-locale Compose Locale 155 * @parblock 156 * 157 * Compose files are locale dependent: 158 * - Compose files are written for a locale, and the locale is used when 159 * searching for the appropriate file to use. 160 * - Compose files may reference the locale internally, with directives 161 * such as %L. 162 * As such, functions like xkb_compose_table_new_from_locale() require 163 * a @p locale parameter. This will usually be the current locale (see 164 * locale(7) for more details). You may also want to allow the user to 165 * explicitly configure it, so he can use the Compose file of a given 166 * locale, but not use that locale for other things. 167 * 168 * You may query the current locale as follows: 169 * @code 170 * const char *locale; 171 * locale = setlocale(LC_CTYPE, NULL); 172 * @endcode 173 * 174 * This will only give useful results if the program had previously set 175 * the current locale using setlocale(3), with LC_CTYPE or LC_ALL and a 176 * non-NULL argument. 177 * 178 * If you prefer not to use the locale system of the C runtime library, 179 * you may nevertheless obtain the user's locale directly using 180 * environment variables, as described in locale(7). For example, 181 * @code 182 * locale = getenv("LC_ALL"); 183 * if (!locale) 184 * locale = getenv("LC_CTYPE"); 185 * if (!locale) 186 * locale = getenv("LANG"); 187 * if (!locale) 188 * locale = "C"; 189 * @endcode 190 * 191 * Note that some locales supported by the C standard library may not 192 * have a Compose file assigned. 193 * 194 * @endparblock 195 */ 196 197 /** 198 * Create a compose table for a given locale. 199 * 200 * The locale is used for searching the file-system for an appropriate 201 * Compose file. The search order is described in Compose(5). It is 202 * affected by the following environment variables: 203 * XCOMPOSEFILE, HOME, XLOCALEDIR. 204 * 205 * @param context 206 * The library context in which to create the compose table. 207 * @param locale 208 * The current locale. See @ref compose-locale. 209 * @param flags 210 * Optional flags for the compose table, or 0. 211 * 212 * @returns A compose table for the given locale, or NULL if the 213 * compilation failed or a Compose file was not found. 214 * 215 * @memberof xkb_compose_table 216 */ 217 struct xkb_compose_table * 218 xkb_compose_table_new_from_locale(struct xkb_context *context, 219 const char *locale, 220 enum xkb_compose_compile_flags flags); 221 222 /** 223 * Create a new compose table from a Compose file. 224 * 225 * @param context 226 * The library context in which to create the compose table. 227 * @param file 228 * The Compose file to compile. 229 * @param locale 230 * The current locale. See @ref compose-locale. 231 * @param format 232 * The text format of the Compose file to compile. 233 * @param flags 234 * Optional flags for the compose table, or 0. 235 * 236 * @returns A compose table compiled from the given file, or NULL if 237 * the compilation failed. 238 * 239 * @memberof xkb_compose_table 240 */ 241 struct xkb_compose_table * 242 xkb_compose_table_new_from_file(struct xkb_context *context, 243 FILE *file, 244 const char *locale, 245 enum xkb_compose_format format, 246 enum xkb_compose_compile_flags flags); 247 248 /** 249 * Create a new compose table from a memory buffer. 250 * 251 * This is just like xkb_compose_table_new_from_file(), but instead of 252 * a file, gets the table as one enormous string. 253 * 254 * @see xkb_compose_table_new_from_file() 255 * @memberof xkb_compose_table 256 */ 257 struct xkb_compose_table * 258 xkb_compose_table_new_from_buffer(struct xkb_context *context, 259 const char *buffer, size_t length, 260 const char *locale, 261 enum xkb_compose_format format, 262 enum xkb_compose_compile_flags flags); 263 264 /** 265 * Take a new reference on a compose table. 266 * 267 * @returns The passed in object. 268 * 269 * @memberof xkb_compose_table 270 */ 271 struct xkb_compose_table * 272 xkb_compose_table_ref(struct xkb_compose_table *table); 273 274 /** 275 * Release a reference on a compose table, and possibly free it. 276 * 277 * @param table The object. If it is NULL, this function does nothing. 278 * 279 * @memberof xkb_compose_table 280 */ 281 void 282 xkb_compose_table_unref(struct xkb_compose_table *table); 283 284 /** Flags for compose state creation. */ 285 enum xkb_compose_state_flags { 286 /** Do not apply any flags. */ 287 XKB_COMPOSE_STATE_NO_FLAGS = 0 288 }; 289 290 /** 291 * Create a new compose state object. 292 * 293 * @param table 294 * The compose table the state will use. 295 * @param flags 296 * Optional flags for the compose state, or 0. 297 * 298 * @returns A new compose state, or NULL on failure. 299 * 300 * @memberof xkb_compose_state 301 */ 302 struct xkb_compose_state * 303 xkb_compose_state_new(struct xkb_compose_table *table, 304 enum xkb_compose_state_flags flags); 305 306 /** 307 * Take a new reference on a compose state object. 308 * 309 * @returns The passed in object. 310 * 311 * @memberof xkb_compose_state 312 */ 313 struct xkb_compose_state * 314 xkb_compose_state_ref(struct xkb_compose_state *state); 315 316 /** 317 * Release a reference on a compose state object, and possibly free it. 318 * 319 * @param state The object. If NULL, do nothing. 320 * 321 * @memberof xkb_compose_state 322 */ 323 void 324 xkb_compose_state_unref(struct xkb_compose_state *state); 325 326 /** 327 * Get the compose table which a compose state object is using. 328 * 329 * @returns The compose table which was passed to xkb_compose_state_new() 330 * when creating this state object. 331 * 332 * This function does not take a new reference on the compose table; you 333 * must explicitly reference it yourself if you plan to use it beyond the 334 * lifetime of the state. 335 * 336 * @memberof xkb_compose_state 337 */ 338 struct xkb_compose_table * 339 xkb_compose_state_get_compose_table(struct xkb_compose_state *state); 340 341 /** Status of the Compose sequence state machine. */ 342 enum xkb_compose_status { 343 /** The initial state; no sequence has started yet. */ 344 XKB_COMPOSE_NOTHING, 345 /** In the middle of a sequence. */ 346 XKB_COMPOSE_COMPOSING, 347 /** A complete sequence has been matched. */ 348 XKB_COMPOSE_COMPOSED, 349 /** The last sequence was cancelled due to an unmatched keysym. */ 350 XKB_COMPOSE_CANCELLED 351 }; 352 353 /** The effect of a keysym fed to xkb_compose_state_feed(). */ 354 enum xkb_compose_feed_result { 355 /** The keysym had no effect - it did not affect the status. */ 356 XKB_COMPOSE_FEED_IGNORED, 357 /** The keysym started, advanced or cancelled a sequence. */ 358 XKB_COMPOSE_FEED_ACCEPTED 359 }; 360 361 /** 362 * Feed one keysym to the Compose sequence state machine. 363 * 364 * This function can advance into a compose sequence, cancel a sequence, 365 * start a new sequence, or do nothing in particular . The resulting 366 * status may be observed with xkb_compose_state_get_status(). 367 * 368 * Some keysyms, such as keysysm for modifier keys, are ignored - they 369 * have no effect on the status or otherwise. 370 * 371 * The following is a description of the possible status transitions, in 372 * the format CURRENT STATUS => NEXT STATUS, given a non-ignored input 373 * keysym @p keysym: 374 * 375 @verbatim 376 NOTHING or CANCELLED or COMPOSED => 377 NOTHING if keysym does not start a sequence. 378 COMPOSING if keysym starts a sequence. 379 COMPOSED if keysym starts and terminates a single-keysym sequence. 380 381 COMPOSING => 382 COMPOSING if keysym advances any of the currently possible 383 sequences but does not terminate any of them. 384 COMPOSED if keysym terminates one of the currently possible 385 sequences. 386 CANCELLED if keysym does not advance any of the currently 387 possible sequences. 388 @endverbatim 389 * 390 * The current Compose formats do not support multiple-keysyms. 391 * Therefore, if you are using a function such as xkb_state_key_get_syms() 392 * and it returns more than one keysym, consider feeding 393 * @p XKB_KEY_NoSymbol instead. 394 * 395 * @param state 396 * The compose state object. 397 * @param keysym 398 * A keysym, usually obtained after a key-press event, with a 399 * function such as xkb_state_key_get_one_sym(). 400 * 401 * @returns Whether the keysym was ignored. This is useful, for example, 402 * if you want to keep a record of the sequence matched thus far. 403 * 404 * @memberof xkb_compose_state 405 */ 406 enum xkb_compose_feed_result 407 xkb_compose_state_feed(struct xkb_compose_state *state, 408 xkb_keysym_t keysym); 409 410 /** 411 * Reset the Compose sequence state machine. 412 * 413 * The status is set to XKB_COMPOSE_NOTHING, and the current sequence 414 * is discarded. 415 * 416 * @memberof xkb_compose_state 417 */ 418 void 419 xkb_compose_state_reset(struct xkb_compose_state *state); 420 421 /** 422 * Get the current status of the compose state machine. 423 * 424 * @see xkb_compose_status 425 * @memberof xkb_compose_state 426 **/ 427 enum xkb_compose_status 428 xkb_compose_state_get_status(struct xkb_compose_state *state); 429 430 /** 431 * Get the result Unicode/UTF-8 string for a composed sequence. 432 * 433 * See @ref compose-overview for more details. This function is only 434 * useful when the status is XKB_COMPOSE_COMPOSED. 435 * 436 * @param[in] state 437 * The compose state. 438 * @param[out] buffer 439 * A buffer to write the string into. 440 * @param[in] size 441 * Size of the buffer. 442 * 443 * @warning If the buffer passed is too small, the string is truncated 444 * (though still NUL-terminated). 445 * 446 * @returns 447 * The number of bytes required for the string, excluding the NUL byte. 448 * If the sequence is not complete, or does not have a viable result 449 * string, returns 0, and sets @p buffer to the empty string (if 450 * possible). 451 * @returns 452 * You may check if truncation has occurred by comparing the return value 453 * with the size of @p buffer, similarly to the snprintf(3) function. 454 * You may safely pass NULL and 0 to @p buffer and @p size to find the 455 * required size (without the NUL-byte). 456 * 457 * @memberof xkb_compose_state 458 **/ 459 int 460 xkb_compose_state_get_utf8(struct xkb_compose_state *state, 461 char *buffer, size_t size); 462 463 /** 464 * Get the result keysym for a composed sequence. 465 * 466 * See @ref compose-overview for more details. This function is only 467 * useful when the status is XKB_COMPOSE_COMPOSED. 468 * 469 * @returns The result keysym. If the sequence is not complete, or does 470 * not specify a result keysym, returns XKB_KEY_NoSymbol. 471 * 472 * @memberof xkb_compose_state 473 **/ 474 xkb_keysym_t 475 xkb_compose_state_get_one_sym(struct xkb_compose_state *state); 476 477 /** @} */ 478 479 #ifdef __cplusplus 480 } /* extern "C" */ 481 #endif 482 483 #endif /* _XKBCOMMON_COMPOSE_H */ 484
