include/xkbcommon/xkbcommon-compose.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_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.
  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 keysyms 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  *
 163  * As such, functions like xkb_compose_table_new_from_locale() require
 164  * a `locale` parameter.  This will usually be the current locale (see
 165  * locale(7) for more details).  You may also want to allow the user to
 166  * explicitly configure it, so he can use the Compose file of a given
 167  * locale, but not use that locale for other things.
 168  *
 169  * You may query the current locale as follows:
 170  * @code
 171  *     const char *locale;
 172  *     locale = setlocale(LC_CTYPE, NULL);
 173  * @endcode
 174  *
 175  * This will only give useful results if the program had previously set
 176  * the current locale using setlocale(3), with `LC_CTYPE` or `LC_ALL`
 177  * and a non-NULL argument.
 178  *
 179  * If you prefer not to use the locale system of the C runtime library,
 180  * you may nevertheless obtain the user's locale directly using
 181  * environment variables, as described in locale(7).  For example,
 182  * @code
 183  *     const char *locale;
 184  *     locale = getenv("LC_ALL");
 185  *     if (!locale || !*locale)
 186  *         locale = getenv("LC_CTYPE");
 187  *     if (!locale || !*locale)
 188  *         locale = getenv("LANG");
 189  *     if (!locale || !*locale)
 190  *         locale = "C";
 191  * @endcode
 192  *
 193  * Note that some locales supported by the C standard library may not
 194  * have a Compose file assigned.
 195  *
 196  * @endparblock
 197  */
 198
 199 /**
 200  * Create a compose table for a given locale.
 201  *
 202  * The locale is used for searching the file-system for an appropriate
 203  * Compose file.  The search order is described in Compose(5).  It is
 204  * affected by the following environment variables:
 205  *
 206  * 1. `XCOMPOSEFILE` - see Compose(5).
 207  * 2. `XDG_CONFIG_HOME` - before `$HOME/.XCompose` is checked,
 208  *    `$XDG_CONFIG_HOME/XCompose` is checked (with a fall back to
 209  *    `$HOME/.config/XCompose` if `XDG_CONFIG_HOME` is not defined).
 210  *    This is a libxkbcommon extension to the search procedure in
 211  *    Compose(5) (since libxkbcommon 1.0.0). Note that other
 212  *    implementations, such as libX11, might not find a Compose file in
 213  *    this path.
 214  * 3. `HOME` - see Compose(5).
 215  * 4. `XLOCALEDIR` - if set, used as the base directory for the system's
 216  *    X locale files, e.g. `/usr/share/X11/locale`, instead of the
 217  *    preconfigured directory.
 218  *
 219  * @param context
 220  *     The library context in which to create the compose table.
 221  * @param locale
 222  *     The current locale.  See @ref compose-locale.
 223  *     \n
 224  *     The value is copied, so it is safe to pass the result of getenv(3)
 225  *     (or similar) without fear of it being invalidated by a subsequent
 226  *     setenv(3) (or similar).
 227  * @param flags
 228  *     Optional flags for the compose table, or 0.
 229  *
 230  * @returns A compose table for the given locale, or NULL if the
 231  * compilation failed or a Compose file was not found.
 232  *
 233  * @memberof xkb_compose_table
 234  */
 235 struct xkb_compose_table *
 236 xkb_compose_table_new_from_locale(struct xkb_context *context,
 237                                   const char *locale,
 238                                   enum xkb_compose_compile_flags flags);
 239
 240 /**
 241  * Create a new compose table from a Compose file.
 242  *
 243  * @param context
 244  *     The library context in which to create the compose table.
 245  * @param file
 246  *     The Compose file to compile.
 247  * @param locale
 248  *     The current locale.  See @ref compose-locale.
 249  * @param format
 250  *     The text format of the Compose file to compile.
 251  * @param flags
 252  *     Optional flags for the compose table, or 0.
 253  *
 254  * @returns A compose table compiled from the given file, or NULL if
 255  * the compilation failed.
 256  *
 257  * @memberof xkb_compose_table
 258  */
 259 struct xkb_compose_table *
 260 xkb_compose_table_new_from_file(struct xkb_context *context,
 261                                 FILE *file,
 262                                 const char *locale,
 263                                 enum xkb_compose_format format,
 264                                 enum xkb_compose_compile_flags flags);
 265
 266 /**
 267  * Create a new compose table from a memory buffer.
 268  *
 269  * This is just like xkb_compose_table_new_from_file(), but instead of
 270  * a file, gets the table as one enormous string.
 271  *
 272  * @see xkb_compose_table_new_from_file()
 273  * @memberof xkb_compose_table
 274  */
 275 struct xkb_compose_table *
 276 xkb_compose_table_new_from_buffer(struct xkb_context *context,
 277                                   const char *buffer, size_t length,
 278                                   const char *locale,
 279                                   enum xkb_compose_format format,
 280                                   enum xkb_compose_compile_flags flags);
 281
 282 /**
 283  * Take a new reference on a compose table.
 284  *
 285  * @returns The passed in object.
 286  *
 287  * @memberof xkb_compose_table
 288  */
 289 struct xkb_compose_table *
 290 xkb_compose_table_ref(struct xkb_compose_table *table);
 291
 292 /**
 293  * Release a reference on a compose table, and possibly free it.
 294  *
 295  * @param table The object.  If it is NULL, this function does nothing.
 296  *
 297  * @memberof xkb_compose_table
 298  */
 299 void
 300 xkb_compose_table_unref(struct xkb_compose_table *table);
 301
 302 /**
 303  * @struct xkb_compose_table_entry
 304  * Opaque Compose table entry object.
 305  *
 306  * Represents a single entry in a Compose file in the iteration API.
 307  * It is immutable.
 308  *
 309  * @sa xkb_compose_table_iterator_new
 310  * @since 1.6.0
 311  */
 312 struct xkb_compose_table_entry;
 313
 314 /**
 315  * Get the left-hand keysym sequence of a Compose table entry.
 316  *
 317  * For example, given the following entry:
 318  *
 319  * ```
 320  * <dead_tilde> <space> : "~" asciitilde # TILDE
 321  * ```
 322  *
 323  * it will return `{XKB_KEY_dead_tilde, XKB_KEY_space}`.
 324  *
 325  * @param[in]  entry The compose table entry object to process.
 326  *
 327  * @param[out] sequence_length Number of keysyms in the sequence.
 328  *
 329  * @returns The array of left-hand side keysyms.  The number of keysyms
 330  * is returned in the @p sequence_length out-parameter.
 331  *
 332  * @memberof xkb_compose_table_entry
 333  * @since 1.6.0
 334  */
 335 const xkb_keysym_t *
 336 xkb_compose_table_entry_sequence(struct xkb_compose_table_entry *entry,
 337                                  size_t *sequence_length);
 338
 339 /**
 340  * Get the right-hand result keysym of a Compose table entry.
 341  *
 342  * For example, given the following entry:
 343  *
 344  * ```
 345  * <dead_tilde> <space> : "~" asciitilde # TILDE
 346  * ```
 347  *
 348  * it will return `XKB_KEY_asciitilde`.
 349  *
 350  * The keysym is optional; if the entry does not specify a keysym,
 351  * returns `XKB_KEY_NoSymbol`.
 352  *
 353  * @memberof xkb_compose_table_entry
 354  * @since 1.6.0
 355  */
 356 xkb_keysym_t
 357 xkb_compose_table_entry_keysym(struct xkb_compose_table_entry *entry);
 358
 359 /**
 360  * Get the right-hand result string of a Compose table entry.
 361  *
 362  * The string is UTF-8 encoded and NULL-terminated.
 363  *
 364  * For example, given the following entry:
 365  *
 366  * ```
 367  * <dead_tilde> <space> : "~" asciitilde # TILDE
 368  * ```
 369  *
 370  * it will return `"~"`.
 371  *
 372  * The string is optional; if the entry does not specify a string,
 373  * returns the empty string.
 374  *
 375  * @memberof xkb_compose_table_entry
 376  * @since 1.6.0
 377  */
 378 const char *
 379 xkb_compose_table_entry_utf8(struct xkb_compose_table_entry *entry);
 380
 381 /**
 382  * @struct xkb_compose_table_iterator
 383  * Iterator over a compose table’s entries.
 384  *
 385  * @sa xkb_compose_table_iterator_new()
 386  * @since 1.6.0
 387  */
 388 struct xkb_compose_table_iterator;
 389
 390 /**
 391  * Create a new iterator for a compose table.
 392  *
 393  * Intended use:
 394  *
 395  * ```c
 396  * struct xkb_compose_table_iterator *iter = xkb_compose_table_iterator_new(compose_table);
 397  * struct xkb_compose_table_entry *entry;
 398  * while ((entry = xkb_compose_table_iterator_next(iter))) {
 399  *     // ...
 400  * }
 401  * xkb_compose_table_iterator_free(iter);
 402  * ```
 403  *
 404  * @returns A new compose table iterator, or `NULL` on failure.
 405  *
 406  * @memberof xkb_compose_table_iterator
 407  * @sa xkb_compose_table_iterator_free()
 408  * @since 1.6.0
 409  */
 410 struct xkb_compose_table_iterator *
 411 xkb_compose_table_iterator_new(struct xkb_compose_table *table);
 412
 413 /**
 414  * Free a compose iterator.
 415  *
 416  * @memberof xkb_compose_table_iterator
 417  * @since 1.6.0
 418  */
 419 void
 420 xkb_compose_table_iterator_free(struct xkb_compose_table_iterator *iter);
 421
 422 /**
 423  * Get the next compose entry from a compose table iterator.
 424  *
 425  * The entries are returned in lexicographic order of the left-hand
 426  * side of entries. This does not correspond to the order in which
 427  * the entries appear in the Compose file.
 428  *
 429  * @attention The return value is valid until the next call to this function.
 430  *
 431  * Returns `NULL` in case there is no more entries.
 432  *
 433  * @memberof xkb_compose_table_iterator
 434  * @since 1.6.0
 435  */
 436 struct xkb_compose_table_entry *
 437 xkb_compose_table_iterator_next(struct xkb_compose_table_iterator *iter);
 438
 439 /** Flags for compose state creation. */
 440 enum xkb_compose_state_flags {
 441     /** Do not apply any flags. */
 442     XKB_COMPOSE_STATE_NO_FLAGS = 0
 443 };
 444
 445 /**
 446  * Create a new compose state object.
 447  *
 448  * @param table
 449  *     The compose table the state will use.
 450  * @param flags
 451  *     Optional flags for the compose state, or 0.
 452  *
 453  * @returns A new compose state, or NULL on failure.
 454  *
 455  * @memberof xkb_compose_state
 456  */
 457 struct xkb_compose_state *
 458 xkb_compose_state_new(struct xkb_compose_table *table,
 459                       enum xkb_compose_state_flags flags);
 460
 461 /**
 462  * Take a new reference on a compose state object.
 463  *
 464  * @returns The passed in object.
 465  *
 466  * @memberof xkb_compose_state
 467  */
 468 struct xkb_compose_state *
 469 xkb_compose_state_ref(struct xkb_compose_state *state);
 470
 471 /**
 472  * Release a reference on a compose state object, and possibly free it.
 473  *
 474  * @param state The object.  If NULL, do nothing.
 475  *
 476  * @memberof xkb_compose_state
 477  */
 478 void
 479 xkb_compose_state_unref(struct xkb_compose_state *state);
 480
 481 /**
 482  * Get the compose table which a compose state object is using.
 483  *
 484  * @returns The compose table which was passed to xkb_compose_state_new()
 485  * when creating this state object.
 486  *
 487  * This function does not take a new reference on the compose table; you
 488  * must explicitly reference it yourself if you plan to use it beyond the
 489  * lifetime of the state.
 490  *
 491  * @memberof xkb_compose_state
 492  */
 493 struct xkb_compose_table *
 494 xkb_compose_state_get_compose_table(struct xkb_compose_state *state);
 495
 496 /** Status of the Compose sequence state machine. */
 497 enum xkb_compose_status {
 498     /** The initial state; no sequence has started yet. */
 499     XKB_COMPOSE_NOTHING,
 500     /** In the middle of a sequence. */
 501     XKB_COMPOSE_COMPOSING,
 502     /** A complete sequence has been matched. */
 503     XKB_COMPOSE_COMPOSED,
 504     /** The last sequence was cancelled due to an unmatched keysym. */
 505     XKB_COMPOSE_CANCELLED
 506 };
 507
 508 /** The effect of a keysym fed to xkb_compose_state_feed(). */
 509 enum xkb_compose_feed_result {
 510     /** The keysym had no effect - it did not affect the status. */
 511     XKB_COMPOSE_FEED_IGNORED,
 512     /** The keysym started, advanced or cancelled a sequence. */
 513     XKB_COMPOSE_FEED_ACCEPTED
 514 };
 515
 516 /**
 517  * Feed one keysym to the Compose sequence state machine.
 518  *
 519  * This function can advance into a compose sequence, cancel a sequence,
 520  * start a new sequence, or do nothing in particular.  The resulting
 521  * status may be observed with xkb_compose_state_get_status().
 522  *
 523  * Some keysyms, such as keysyms for modifier keys, are ignored - they
 524  * have no effect on the status or otherwise.
 525  *
 526  * The following is a description of the possible status transitions, in
 527  * the format CURRENT STATUS => NEXT STATUS, given a non-ignored input
 528  * keysym `keysym`:
 529  *
 530    @verbatim
 531    NOTHING or CANCELLED or COMPOSED =>
 532       NOTHING   if keysym does not start a sequence.
 533       COMPOSING if keysym starts a sequence.
 534       COMPOSED  if keysym starts and terminates a single-keysym sequence.
 535
 536    COMPOSING =>
 537       COMPOSING if keysym advances any of the currently possible
 538                 sequences but does not terminate any of them.
 539       COMPOSED  if keysym terminates one of the currently possible
 540                 sequences.
 541       CANCELLED if keysym does not advance any of the currently
 542                 possible sequences.
 543    @endverbatim
 544  *
 545  * The current Compose formats do not support multiple-keysyms.
 546  * Therefore, if you are using a function such as xkb_state_key_get_syms()
 547  * and it returns more than one keysym, consider feeding XKB_KEY_NoSymbol
 548  * instead.
 549  *
 550  * @param state
 551  *     The compose state object.
 552  * @param keysym
 553  *     A keysym, usually obtained after a key-press event, with a
 554  *     function such as xkb_state_key_get_one_sym().
 555  *
 556  * @returns Whether the keysym was ignored.  This is useful, for example,
 557  * if you want to keep a record of the sequence matched thus far.
 558  *
 559  * @memberof xkb_compose_state
 560  */
 561 enum xkb_compose_feed_result
 562 xkb_compose_state_feed(struct xkb_compose_state *state,
 563                        xkb_keysym_t keysym);
 564
 565 /**
 566  * Reset the Compose sequence state machine.
 567  *
 568  * The status is set to XKB_COMPOSE_NOTHING, and the current sequence
 569  * is discarded.
 570  *
 571  * @memberof xkb_compose_state
 572  */
 573 void
 574 xkb_compose_state_reset(struct xkb_compose_state *state);
 575
 576 /**
 577  * Get the current status of the compose state machine.
 578  *
 579  * @see xkb_compose_status
 580  * @memberof xkb_compose_state
 581  **/
 582 enum xkb_compose_status
 583 xkb_compose_state_get_status(struct xkb_compose_state *state);
 584
 585 /**
 586  * Get the result Unicode/UTF-8 string for a composed sequence.
 587  *
 588  * See @ref compose-overview for more details.  This function is only
 589  * useful when the status is XKB_COMPOSE_COMPOSED.
 590  *
 591  * @param[in] state
 592  *     The compose state.
 593  * @param[out] buffer
 594  *     A buffer to write the string into.
 595  * @param[in] size
 596  *     Size of the buffer.
 597  *
 598  * @warning If the buffer passed is too small, the string is truncated
 599  * (though still NUL-terminated).
 600  *
 601  * @returns
 602  *   The number of bytes required for the string, excluding the NUL byte.
 603  *   If the sequence is not complete, or does not have a viable result
 604  *   string, returns 0, and sets `buffer` to the empty string (if possible).
 605  * @returns
 606  *   You may check if truncation has occurred by comparing the return value
 607  *   with the size of `buffer`, similarly to the `snprintf`(3) function.
 608  *   You may safely pass NULL and 0 to `buffer` and `size` to find the
 609  *   required size (without the NUL-byte).
 610  *
 611  * @memberof xkb_compose_state
 612  **/
 613 int
 614 xkb_compose_state_get_utf8(struct xkb_compose_state *state,
 615                            char *buffer, size_t size);
 616
 617 /**
 618  * Get the result keysym for a composed sequence.
 619  *
 620  * See @ref compose-overview for more details.  This function is only
 621  * useful when the status is XKB_COMPOSE_COMPOSED.
 622  *
 623  * @returns The result keysym.  If the sequence is not complete, or does
 624  * not specify a result keysym, returns XKB_KEY_NoSymbol.
 625  *
 626  * @memberof xkb_compose_state
 627  **/
 628 xkb_keysym_t
 629 xkb_compose_state_get_one_sym(struct xkb_compose_state *state);
 630
 631 /** @} */
 632
 633 #ifdef __cplusplus
 634 } /* extern "C" */
 635 #endif
 636
 637 #endif /* _XKBCOMMON_COMPOSE_H */