1 /* 2 3 Copyright (c) 2003-2013 uim Project https://github.com/uim/uim 4 5 All rights reserved. 6 7 Redistribution and use in source and binary forms, with or without 8 modification, are permitted provided that the following conditions 9 are met: 10 11 1. Redistributions of source code must retain the above copyright 12 notice, this list of conditions and the following disclaimer. 13 2. Redistributions in binary form must reproduce the above copyright 14 notice, this list of conditions and the following disclaimer in the 15 documentation and/or other materials provided with the distribution. 16 3. Neither the name of authors nor the names of its contributors 17 may be used to endorse or promote products derived from this software 18 without specific prior written permission. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND 21 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE 24 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30 SUCH DAMAGE. 31 32 */ 33 34 /* API and ABI is unstable */ 35 #ifndef UIM_H 36 #define UIM_H 37 38 #include <stdlib.h> 39 40 #include "version.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 #define UIM_VERSION_REQUIRE(major, minor, patchlevel) \ 47 ((major) < UIM_VERSION_MAJOR \ 48 || ((major) == UIM_VERSION_MAJOR && (minor) < UIM_VERSION_MINOR) \ 49 || ((major) == UIM_VERSION_MAJOR && (minor) == UIM_VERSION_MINOR \ 50 && (patchlevel) <= UIM_VERSION_PATCHLEVEL)) 51 52 #ifndef UIM_BOOL_DEFINED 53 /* 54 * A boolean type for uim to explicitly indicate intention about values 55 * 56 * *** IMPORTANT *** 57 * 58 * Do not test a value with (val == UIM_TRUE). The UIM_TRUE is only A TYPICAL 59 * VALUE FOR TRUE. Use (val) or (val != UIM_FALSE) instead. 60 * 61 */ 62 typedef int uim_bool; 63 64 #define UIM_FALSE 0 65 #define UIM_TRUE 1 66 67 #define UIM_BOOL_DEFINED 1 68 #endif /* UIM_BOOL_DEFINED */ 69 70 71 typedef struct uim_context_ *uim_context; 72 73 typedef struct uim_candidate_ *uim_candidate; 74 75 enum UKey { 76 UKey_0 = 48, 77 UKey_1 = 49, 78 UKey_2 = 50, 79 UKey_3 = 51, 80 UKey_4 = 52, 81 UKey_5 = 53, 82 UKey_6 = 54, 83 UKey_7 = 55, 84 UKey_8 = 56, 85 UKey_9 = 57, 86 87 /* non-ASCII Latin-1 characters */ 88 UKey_nobreakspace = 0x00a0, 89 UKey_exclamdown = 0x00a1, 90 UKey_cent = 0x00a2, 91 UKey_sterling = 0x00a3, 92 UKey_currency = 0x00a4, 93 UKey_Yen = 0x00a5, /* == 165 */ 94 UKey_brokenbar = 0x00a6, 95 UKey_section = 0x00a7, 96 UKey_diaeresis = 0x00a8, 97 UKey_copyright = 0x00a9, 98 UKey_ordfeminine = 0x00aa, 99 UKey_guillemotleft = 0x00ab, 100 UKey_notsign = 0x00ac, 101 UKey_hyphen = 0x00ad, 102 UKey_registered = 0x00ae, 103 UKey_macron = 0x00af, 104 UKey_degree = 0x00b0, 105 UKey_plusminus = 0x00b1, 106 UKey_twosuperior = 0x00b2, 107 UKey_threesuperior = 0x00b3, 108 UKey_acute = 0x00b4, 109 UKey_mu = 0x00b5, 110 UKey_paragraph = 0x00b6, 111 UKey_periodcentered = 0x00b7, 112 UKey_cedilla = 0x00b8, 113 UKey_onesuperior = 0x00b9, 114 UKey_masculine = 0x00ba, 115 UKey_guillemotright = 0x00bb, 116 UKey_onequarter = 0x00bc, 117 UKey_onehalf = 0x00bd, 118 UKey_threequarters = 0x00be, 119 UKey_questiondown = 0x00bf, 120 UKey_Agrave = 0x00c0, 121 UKey_Aacute = 0x00c1, 122 UKey_Acircumflex = 0x00c2, 123 UKey_Atilde = 0x00c3, 124 UKey_Adiaeresis = 0x00c4, 125 UKey_Aring = 0x00c5, 126 UKey_AE = 0x00c6, 127 UKey_Ccedilla = 0x00c7, 128 UKey_Egrave = 0x00c8, 129 UKey_Eacute = 0x00c9, 130 UKey_Ecircumflex = 0x00ca, 131 UKey_Ediaeresis = 0x00cb, 132 UKey_Igrave = 0x00cc, 133 UKey_Iacute = 0x00cd, 134 UKey_Icircumflex = 0x00ce, 135 UKey_Idiaeresis = 0x00cf, 136 UKey_ETH = 0x00d0, 137 UKey_Eth = 0x00d0, 138 UKey_Ntilde = 0x00d1, 139 UKey_Ograve = 0x00d2, 140 UKey_Oacute = 0x00d3, 141 UKey_Ocircumflex = 0x00d4, 142 UKey_Otilde = 0x00d5, 143 UKey_Odiaeresis = 0x00d6, 144 UKey_multiply = 0x00d7, 145 UKey_Oslash = 0x00d8, 146 UKey_Ooblique = 0x00d8, 147 UKey_Ugrave = 0x00d9, 148 UKey_Uacute = 0x00da, 149 UKey_Ucircumflex = 0x00db, 150 UKey_Udiaeresis = 0x00dc, 151 UKey_Yacute = 0x00dd, 152 UKey_THORN = 0x00de, 153 UKey_Thorn = 0x00de, 154 UKey_ssharp = 0x00df, 155 UKey_agrave = 0x00e0, 156 UKey_aacute = 0x00e1, 157 UKey_acircumflex = 0x00e2, 158 UKey_atilde = 0x00e3, 159 UKey_adiaeresis = 0x00e4, 160 UKey_aring = 0x00e5, 161 UKey_ae = 0x00e6, 162 UKey_ccedilla = 0x00e7, 163 UKey_egrave = 0x00e8, 164 UKey_eacute = 0x00e9, 165 UKey_ecircumflex = 0x00ea, 166 UKey_ediaeresis = 0x00eb, 167 UKey_igrave = 0x00ec, 168 UKey_iacute = 0x00ed, 169 UKey_icircumflex = 0x00ee, 170 UKey_idiaeresis = 0x00ef, 171 UKey_eth = 0x00f0, 172 UKey_ntilde = 0x00f1, 173 UKey_ograve = 0x00f2, 174 UKey_oacute = 0x00f3, 175 UKey_ocircumflex = 0x00f4, 176 UKey_otilde = 0x00f5, 177 UKey_odiaeresis = 0x00f6, 178 UKey_division = 0x00f7, 179 UKey_oslash = 0x00f8, 180 UKey_ooblique = 0x00f8, 181 UKey_ugrave = 0x00f9, 182 UKey_uacute = 0x00fa, 183 UKey_ucircumflex = 0x00fb, 184 UKey_udiaeresis = 0x00fc, 185 UKey_yacute = 0x00fd, 186 UKey_thorn = 0x00fe, 187 UKey_ydiaeresis = 0x00ff, 188 189 UKey_Escape = 256, 190 UKey_Tab, 191 UKey_Backspace, 192 UKey_Delete, 193 UKey_Insert, 194 UKey_Return, 195 UKey_Left, 196 UKey_Up , 197 UKey_Right , 198 UKey_Down , 199 UKey_Prior , /* page up */ 200 UKey_Next , /* page down */ 201 UKey_Home, 202 UKey_End, 203 204 UKey_Multi_key, /* multi-key character compose */ 205 UKey_Codeinput, 206 UKey_SingleCandidate, 207 UKey_MultipleCandidate, 208 UKey_PreviousCandidate, 209 UKey_Mode_switch, /* charcter set switch */ 210 211 /* Japanese keyboard */ 212 UKey_Kanji, /* kanji, kanji convert */ 213 UKey_Muhenkan, /* cancel conversion */ 214 UKey_Henkan_Mode, /* start/stop conversion */ 215 UKey_Henkan = UKey_Henkan_Mode, /* alias for Henkan_Mode */ 216 UKey_Romaji, 217 UKey_Hiragana, 218 UKey_Katakana, 219 UKey_Hiragana_Katakana, /* hiragana/katakana toggle */ 220 UKey_Zenkaku, 221 UKey_Hankaku, 222 UKey_Zenkaku_Hankaku, /* zenkaku/hankaku toggle */ 223 UKey_Touroku, 224 UKey_Massyo, 225 UKey_Kana_Lock, 226 UKey_Kana_Shift, 227 UKey_Eisu_Shift, /* alphanumeric shift */ 228 UKey_Eisu_toggle, /* alphanumeric toggle */ 229 230 /* Korean keyboard */ 231 UKey_Hangul, 232 UKey_Hangul_Start, 233 UKey_Hangul_End, 234 UKey_Hangul_Hanja, 235 UKey_Hangul_Jamo, 236 UKey_Hangul_Romaja, 237 UKey_Hangul_Codeinput, 238 UKey_Hangul_Jeonja, 239 UKey_Hangul_Banja, 240 UKey_Hangul_PreHanja, 241 UKey_Hangul_PostHanja, 242 UKey_Hangul_SingleCandidate, 243 UKey_Hangul_MultipleCandidate, 244 UKey_Hangul_PreviousCandidate, 245 UKey_Hangul_Special, 246 247 /* function keys */ 248 UKey_F1, 249 UKey_F2, 250 UKey_F3, 251 UKey_F4, 252 UKey_F5, 253 UKey_F6, 254 UKey_F7, 255 UKey_F8, 256 UKey_F9, 257 UKey_F10, 258 UKey_F11, 259 UKey_F12, 260 UKey_F13, 261 UKey_F14, 262 UKey_F15, 263 UKey_F16, 264 UKey_F17, 265 UKey_F18, 266 UKey_F19, 267 UKey_F20, 268 UKey_F21, 269 UKey_F22, 270 UKey_F23, 271 UKey_F24, 272 UKey_F25, 273 UKey_F26, 274 UKey_F27, 275 UKey_F28, 276 UKey_F29, 277 UKey_F30, 278 UKey_F31, 279 UKey_F32, 280 UKey_F33, 281 UKey_F34, 282 UKey_F35, /* X, Gtk and Qt supports up to F35 */ 283 284 /* dead keys */ 285 UKey_Dead_Grave, 286 UKey_Dead_Acute, 287 UKey_Dead_Circumflex, 288 UKey_Dead_Tilde, 289 UKey_Dead_Macron, 290 UKey_Dead_Breve, 291 UKey_Dead_Abovedot, 292 UKey_Dead_Diaeresis, 293 UKey_Dead_Abovering, 294 UKey_Dead_Doubleacute, 295 UKey_Dead_Caron, 296 UKey_Dead_Cedilla, 297 UKey_Dead_Ogonek, 298 UKey_Dead_Iota, 299 UKey_Dead_VoicedSound, 300 UKey_Dead_SemivoicedSound, 301 UKey_Dead_Belowdot, 302 UKey_Dead_Hook, 303 UKey_Dead_Horn, 304 305 /* Japanese Kana keys */ 306 UKey_Kana_Fullstop, 307 UKey_Kana_OpeningBracket, 308 UKey_Kana_ClosingBracket, 309 UKey_Kana_Comma, 310 UKey_Kana_Conjunctive, 311 UKey_Kana_WO, 312 UKey_Kana_a, 313 UKey_Kana_i, 314 UKey_Kana_u, 315 UKey_Kana_e, 316 UKey_Kana_o, 317 UKey_Kana_ya, 318 UKey_Kana_yu, 319 UKey_Kana_yo, 320 UKey_Kana_tsu, 321 UKey_Kana_ProlongedSound, 322 UKey_Kana_A, 323 UKey_Kana_I, 324 UKey_Kana_U, 325 UKey_Kana_E, 326 UKey_Kana_O, 327 UKey_Kana_KA, 328 UKey_Kana_KI, 329 UKey_Kana_KU, 330 UKey_Kana_KE, 331 UKey_Kana_KO, 332 UKey_Kana_SA, 333 UKey_Kana_SHI, 334 UKey_Kana_SU, 335 UKey_Kana_SE, 336 UKey_Kana_SO, 337 UKey_Kana_TA, 338 UKey_Kana_CHI, 339 UKey_Kana_TSU, 340 UKey_Kana_TE, 341 UKey_Kana_TO, 342 UKey_Kana_NA, 343 UKey_Kana_NI, 344 UKey_Kana_NU, 345 UKey_Kana_NE, 346 UKey_Kana_NO, 347 UKey_Kana_HA, 348 UKey_Kana_HI, 349 UKey_Kana_FU, 350 UKey_Kana_HE, 351 UKey_Kana_HO, 352 UKey_Kana_MA, 353 UKey_Kana_MI, 354 UKey_Kana_MU, 355 UKey_Kana_ME, 356 UKey_Kana_MO, 357 UKey_Kana_YA, 358 UKey_Kana_YU, 359 UKey_Kana_YO, 360 UKey_Kana_RA, 361 UKey_Kana_RI, 362 UKey_Kana_RU, 363 UKey_Kana_RE, 364 UKey_Kana_RO, 365 UKey_Kana_WA, 366 UKey_Kana_N, 367 UKey_Kana_VoicedSound, 368 UKey_Kana_SemivoicedSound, 369 370 /* non-standard platform specific keys (e.g. Zaurus PDA) */ 371 UKey_Private1, 372 UKey_Private2, 373 UKey_Private3, 374 UKey_Private4, 375 UKey_Private5, 376 UKey_Private6, 377 UKey_Private7, 378 UKey_Private8, 379 UKey_Private9, 380 UKey_Private10, 381 UKey_Private11, 382 UKey_Private12, 383 UKey_Private13, 384 UKey_Private14, 385 UKey_Private15, 386 UKey_Private16, 387 UKey_Private17, 388 UKey_Private18, 389 UKey_Private19, 390 UKey_Private20, 391 UKey_Private21, 392 UKey_Private22, 393 UKey_Private23, 394 UKey_Private24, 395 UKey_Private25, 396 UKey_Private26, 397 UKey_Private27, 398 UKey_Private28, 399 UKey_Private29, 400 UKey_Private30, 401 402 /* modifier keys */ 403 UKey_Shift = 0x8000, 404 UKey_Control, 405 UKey_Alt, 406 UKey_Meta, 407 UKey_Super, 408 UKey_Hyper, 409 410 /* lock modifier keys: unstable */ 411 UKey_Caps_Lock = 0x9000, 412 UKey_Num_Lock, 413 UKey_Scroll_Lock, 414 415 #if 1 416 /* Deprecated. Please replace with UKey_Shift and so on. */ 417 UKey_Shift_key = UKey_Shift, 418 UKey_Control_key = UKey_Control, 419 UKey_Alt_key = UKey_Alt, 420 UKey_Meta_key = UKey_Meta, 421 UKey_Super_key = UKey_Super, 422 UKey_Hyper_key = UKey_Hyper, 423 #endif 424 425 UKey_Other = 0x10000 426 }; 427 428 enum UKeyModifier { 429 UMod_Shift = 1, 430 UMod_Control = 2, 431 UMod_Alt = 4, 432 UMod_Meta = 8, 433 UMod_Pseudo0 = 16, 434 UMod_Pseudo1 = 32, 435 UMod_Super = 64, 436 UMod_Hyper = 128 437 }; 438 439 enum UPreeditAttr { 440 UPreeditAttr_None = 0, 441 UPreeditAttr_UnderLine = 1, 442 UPreeditAttr_Reverse = 2, 443 UPreeditAttr_Cursor = 4, 444 UPreeditAttr_Separator = 8 445 }; 446 447 /* Cursor of clipboard text is always positioned at end. */ 448 enum UTextArea { 449 UTextArea_Unspecified = 0, 450 UTextArea_Primary = 1, /* primary text area which IM commits to */ 451 UTextArea_Selection = 2, /* user-selected region of primary text area */ 452 UTextArea_Clipboard = 4 /* clipboard text */ 453 }; 454 455 enum UTextOrigin { 456 UTextOrigin_Unspecified = 0, 457 UTextOrigin_Cursor = 1, /* current position of the cursor */ 458 UTextOrigin_Beginning = 2, /* beginning of the text */ 459 UTextOrigin_End = 3 /* end of the text */ 460 }; 461 462 /* 463 * Text extent specifiers 464 * 465 * All bridges that support the text acquisition API must implement the 466 * handlings for these 'required' text extent specifiers. 467 * 468 * required: 469 * - zero and positive numbers 470 * - UTextExtent_Full 471 * - UTextExtent_Line 472 * 473 * Zero and positive numbers are interpreted as string length (counted in 474 * characters, not bytes). 475 * 476 * 477 * Following language-specific extent specifiers are recommended to be 478 * implemented although experimental. Input methods that use these specifiers 479 * should separate the features based on the specifiers as "experimental 480 * features" and off by default. And do not assume correct result is always 481 * returned. These specifiers may be re-categorized as 'required' when we have 482 * been well-experimented and it is considered as appropriate. 483 * 484 * recommended: 485 * - UTextExtent_Paragraph 486 * - UTextExtent_Sentence 487 * - UTextExtent_Word 488 * 489 * 490 * These specifiers are experimental and reserved for future use. 491 * 492 * experimental: 493 * - UTextExtent_CharFrags 494 * - UTextExtent_DispRect 495 * - UTextExtent_DispLine 496 * 497 * UTextExtent_CharFrags stands for "character fragments" such as Thai 498 * combining marks, Hangul jamo, Japanese voiced consonant marks etc. It is 499 * supposed to be used for the "surrounding text" acquisition. Bridges should 500 * supply only such combinable characters if this specifier is passed. 501 */ 502 enum UTextExtent { 503 UTextExtent_Unspecified = -1, /* invalid */ 504 505 /* logical extents */ 506 UTextExtent_Full = -2, /* beginning or end of the whole text */ 507 UTextExtent_Paragraph = -3, /* the paragraph which the origin is included */ 508 UTextExtent_Sentence = -5, /* the sentence which the origin is included */ 509 UTextExtent_Word = -9, /* the word which the origin is included */ 510 UTextExtent_CharFrags = -17, /* character fragments around the origin */ 511 512 /* physical extents */ 513 UTextExtent_DispRect = -33, /* the text region displayed in the widget */ 514 UTextExtent_DispLine = -65, /* displayed line (eol: linebreak) */ 515 UTextExtent_Line = -129 /* real line (eol: newline char) */ 516 }; 517 518 /* abstracting platform-dependent character code conversion method */ 519 struct uim_code_converter { 520 int (*is_convertible)(const char *tocode, const char *fromcode); 521 void *(*create)(const char *tocode, const char *fromcode); 522 char *(*convert)(void *obj, const char *str); 523 void (*release)(void *obj); 524 }; 525 526 /** 527 * Initialize and allocate resources to start to input. This function 528 * must be called before any other uim functions are called. The 529 * second calling of this function makes no sense. This function 530 * performs setlocale(3). Be careful if your code also performs it. 531 * 532 * @return 0 on success, otherwise -1 533 */ 534 long 535 uim_init(void); 536 537 /** 538 * Finalize uim library by freeing all resources allocated by uim. 539 */ 540 void 541 uim_quit(void); 542 543 /** 544 * Create new input context. 545 * param lang and engine is used to specify appropriate input method tied to returning input context. 546 * Currently selected input method is used if you specify both as NULL. 547 * 548 * @param ptr cookie value which is passed as an argument of uim's callback functions. 549 * @param enc iconv-acceptable name of client encoding. Say "UTF-8" to use most of input methods. 550 * @param lang name language you want to input 551 * @param engine name of conversion engine you want to use 552 * @param conv character code converter. Say "uim_iconv" or place your own platform-specific, preferable implementation. See struct uim_code_converter. 553 * @param commit_cb callback function which is called when there comes somestring to commit. 1st argument of this callback function is "ptr" and 2nd argument the string to commit. 554 * 555 * @return uim_context which newly created. 556 */ 557 uim_context 558 uim_create_context(void *ptr, 559 const char *enc, 560 const char *lang, 561 const char *engine, 562 struct uim_code_converter *conv, 563 void (*commit_cb)(void *ptr, const char *str)); 564 565 /** 566 * Release input context which is created by uim_create_context. 567 * 568 * @param uc input cotext to be released. 569 * @see uim_create_context 570 */ 571 void 572 uim_release_context(uim_context uc); 573 574 /** 575 * Reset input context to neutral state. 576 * 577 * This handler MUST NOT commit a string and/or update the preedit. If a 578 * preedit string is existing on a GUI toolkit-level reset, the bridge is 579 * responsible to clear it. Internal state that considered as 'global' is 580 * permitted to be kept. 581 * 582 * @param uc input context to be reset 583 */ 584 void 585 uim_reset_context(uim_context uc); 586 587 /** 588 * Notify input context that the textarea is being focused in. 589 * 590 * The input context is permitted to commit a string and/or update the 591 * preedit. 592 * 593 * @param uc input context 594 */ 595 void 596 uim_focus_in_context(uim_context uc); 597 598 /** 599 * Notify input context that the textarea is being focused out. 600 * 601 * The input context is permitted to commit a string and/or update the 602 * preedit. 603 * 604 * @param uc input context 605 */ 606 void 607 uim_focus_out_context(uim_context uc); 608 609 /** 610 * Notify input context that the input point has been relocated. 611 * 612 * This notifies an input context that the input point (textarea and/or cursor 613 * position) has been relocated. The input context is permitted to commit a 614 * string and/or update the preedit. 615 * 616 * @param uc input context 617 */ 618 void 619 uim_place_context(uim_context uc); 620 621 /** 622 * Notify input context that the input at the position has been discontinued. 623 * 624 * This notifies an input context that input at current input point (textarea 625 * and/or cursor position) has been discontinued. The input context is 626 * permitted to commit a string, but must not update/clear the 627 * preedit. Bridge-level preedit must be cleared by bridge itself. uim-level 628 * preedit is permitted to be preserved for subsequent 'place' handler call, 629 * or else silently cleared. 630 * 631 * @param uc input context 632 */ 633 void 634 uim_displace_context(uim_context uc); 635 636 /** 637 * Set callback functions to be called when the preedit string changes. 638 * Preedit string is passed to applications by sequential calls of pushback_cb, between the calls of clear_cb and update_cb. 639 * Each callback's 1st argument "ptr" corresponds to the 1st argument of uim_create_context. 640 * 641 * @param uc input context 642 * @param clear_cb called when preedit string should be cleared. 643 * @param pushback_cb called when additional preedit string comes. 2nd argument is the attribute of preedit string and 3rd argument is additonal preedit string. 644 * @param update_cb called when the changes of preedit string should be updated graphically. 645 * 646 * @see uim_create_context 647 */ 648 void 649 uim_set_preedit_cb(uim_context uc, 650 void (*clear_cb)(void *ptr), 651 void (*pushback_cb)(void *ptr, 652 int attr, 653 const char *str), 654 /* page change cb .. etc will be here */ 655 void (*update_cb)(void *ptr)); 656 657 /* dealing pressing key */ 658 /** 659 * Send key press event to uim context 660 * 661 * @param uc input context which event goes to 662 * @param key keycode and value is 32 to 126. 663 * @param state keystate 664 * 665 * @return 0 if IM not handle the event, otherwise the event is handled by IM so please stop key event handling. 666 */ 667 int 668 uim_press_key(uim_context uc, int key, int state); 669 /** 670 * Send key press release to uim context 671 * 672 * @param uc input context which event goes to 673 * @param key keycode and valued is 32 to 126. 674 * @param state keystate 675 * 676 * @return 0 if IM not handle the event, otherwise the event is handled by IM so please stop key event handling. 677 */ 678 int 679 uim_release_key(uim_context uc, int key, int state); 680 681 /** 682 * Change client encoding of an input context. 683 * 684 * @param uc input context 685 * @param encoding client encoding name 686 * 687 * @see uim_create_context 688 */ 689 void uim_set_client_encoding(uim_context uc, const char *encoding); 690 691 692 /* im list */ 693 /** 694 * Get the number of input methods with same encoding and language of the passed context. 695 * 696 * @param uc input context 697 * 698 * @return number of input methods 699 */ 700 int uim_get_nr_im(uim_context uc); 701 702 /** 703 * Get the name of nth input method. 704 * 705 * @warning you must not free the result. 706 * 707 * @param uc input context 708 * @param nth index of input method. 709 * 710 * @return name of nth input method. only valid until next uim API call. 711 */ 712 const char *uim_get_im_name(uim_context uc, int nth); 713 714 /** 715 * Get the language of nth input method. 716 * 717 * @warning you must not free the result. 718 * 719 * @param uc input context 720 * @param nth index of input method. only valid until next uim API call. 721 */ 722 const char *uim_get_im_language(uim_context uc, int nth); 723 724 /** 725 * Get the short description of nth input method. 726 * 727 * @warning you must not free the result. 728 * 729 * @param uc input context 730 * @param nth index of input method. only valid until next uim API call. 731 */ 732 const char *uim_get_im_short_desc(uim_context uc, int nth); 733 734 /** 735 * Get the encoding of nth input method. 736 * 737 * @warning you must not free the result 738 * 739 * @param uc input context 740 * @param nth index of input method 741 * 742 * @return nth input method's encoding. only valid until next uim API call. 743 */ 744 const char *uim_get_im_encoding(uim_context uc, int nth); 745 746 747 /** 748 * Get the default input method engine name. 749 * 750 * @warning you must not free the result 751 * 752 * @param localename locale name 753 * 754 * @return input method name. only valid until next uim API call. 755 */ 756 const char *uim_get_default_im_name(const char *localename); 757 758 /** 759 * Get the most preferable input method engine name for the localename. 760 * 761 * @warning you must not free the result 762 * 763 * @param localename locale name 764 * 765 * @return input method name. only valid until next uim API call. 766 */ 767 const char *uim_get_im_name_for_locale(const char *localename); 768 769 /* candidate */ 770 /** 771 * Set callback functions to be called when the candidate-selection occurs. 772 * Each callback's 1st argument "ptr" corresponds to the 1st argument of uim_create_context. 773 * 774 * @param uc input context 775 * @param activate_cb called when candidate window should be activated. 776 * @param select_cb called when a candidate is selected and its index is 2nd argument. 777 * @param shift_page_cb 778 * @param deactivate_cb called when candidate window should be deactivated. 779 * 780 * @see uim_create_context 781 */ 782 void uim_set_candidate_selector_cb(uim_context uc, 783 void (*activate_cb)(void *ptr, 784 int nr, 785 int display_limit), 786 void (*select_cb)(void *ptr, int index), 787 void (*shift_page_cb)(void *ptr, 788 int direction), 789 void (*deactivate_cb)(void *ptr)); 790 791 /** 792 * Set callback function to support delay showing candidate-selection. 793 * 794 * @param uc input context 795 * @param delay_activate_cb called when candidate window should be activated with delay. 796 * 797 * @see uim_create_context 798 */ 799 void uim_set_delay_candidate_selector_cb(uim_context uc, 800 void (*delay_activate_cb)(void *ptr, 801 int delay)); 802 803 /** 804 * Notify that the candidate selector is being activated after delay. 805 * 806 * The input context must update number of candidates, 807 * display limit and selected index. 808 * 809 * @param uc input context 810 * @param nr [out] total number of candidates 811 * @param display_limit [out] number of candidates to show on one page 812 * @param selected_index [out] index of selected candidate 813 */ 814 void uim_delay_activating(uim_context uc, int *nr, int *display_limit, int *selected_index); 815 816 /** 817 * Get candidate data. 818 * 819 * @param uc input context 820 * @param index index of the candidate you want to get 821 * @param accel_enumeration_hint index of the first candidate displayed in 822 * the candidate selector 823 * 824 * @warning You must free the result by uim_candidate_free 825 * 826 * @see uim_candidate_free 827 * 828 * @return data of candidate 829 */ 830 uim_candidate uim_get_candidate(uim_context uc, int index, int accel_enumeration_hint); 831 /** 832 * Free the result of uim_get_candidate. 833 * 834 * @param cand the data you want to free 835 */ 836 void uim_candidate_free(uim_candidate cand); 837 838 int uim_get_candidate_index(uim_context uc); 839 /** 840 * Select the candidate by specifying $index 841 * 842 * @param uc input context 843 * @param index index of the candidate you want to select 844 */ 845 void uim_set_candidate_index(uim_context uc, int index); 846 847 /** 848 * Get the string of candidate. 849 * 850 * @warning You must not free the result. All datas are freed by calling uim_candidate_free. 851 * 852 * @param cand the data you got by calling uim_get_candidate 853 * 854 * @see uim_get_candidate 855 * 856 * @return string of candidate data 857 */ 858 const char *uim_candidate_get_cand_str(uim_candidate cand); 859 /** 860 * Get the string of candidate's heading label. 861 * 862 * @warning You must not free the result. All datas are freed by calling uim_candidate_free. 863 * 864 * @param cand the data you got by uim_get_candidate 865 * 866 * @see uim_get_candidate 867 * 868 * @return string of candidate data's heading label 869 */ 870 const char *uim_candidate_get_heading_label(uim_candidate cand); 871 872 /** 873 * Get the string of candidate's annotation. 874 * 875 * @warning You must not free the result. All datas are freed by calling uim_candidate_free. 876 * @warning If no data is available, return string is "" (empty string). 877 * 878 * @param cand the data you got by uim_get_candidate 879 * 880 * @see uim_get_candidate 881 * 882 * @return string of candidate's annotation str 883 */ 884 const char *uim_candidate_get_annotation_str(uim_candidate cand); 885 886 /*property*/ 887 /** 888 * Set callback function to be called when property list is updated. 889 * 890 * @param uc input context 891 * @param update_cb called when property list is updated. 892 * 1st argument "ptr" corresponds to the 1st argument of uim_create_context. 893 * 2nd argument is the message to be sent to the helper server with "prop_list_update" command and charset info. 894 */ 895 void 896 uim_set_prop_list_update_cb(uim_context uc, 897 void (*update_cb)(void *ptr, const char *str)); 898 /** 899 * Force to input context to update property list. 900 * 901 * @param uc input context 902 */ 903 void 904 uim_prop_list_update(uim_context uc); 905 906 /** 907 * Obsolete. Only existing for Backward compatibility and should not 908 * be called. 909 */ 910 void 911 uim_set_prop_label_update_cb(uim_context uc, 912 void (*update_cb)(void *ptr, const char *str)); 913 /** 914 * Obsolete. Only existing for Backward compatibility and should not 915 * be called. 916 */ 917 void 918 uim_prop_label_update(uim_context uc); 919 void 920 uim_prop_activate(uim_context uc, const char *str); 921 void 922 uim_prop_update_custom(uim_context uc, const char *custom, const char *val); 923 uim_bool 924 uim_prop_reload_configs(void); 925 926 /* mode is obsoleted by property, so please use property API instead of mode API */ 927 int 928 uim_get_current_mode(uim_context uc); 929 void 930 uim_set_mode(uim_context uc, int nth); 931 void 932 uim_set_mode_cb(uim_context uc, void (*update_cb)(void *ptr, 933 int mode)); 934 /* mode list */ 935 int 936 uim_get_nr_modes(uim_context uc); 937 /* you must not free the result. and only valid until next uim API call */ 938 const char * 939 uim_get_mode_name(uim_context uc, int nth); 940 void 941 uim_set_mode_list_update_cb(uim_context uc, 942 void (*update_cb)(void *ptr)); 943 944 /* text acquisition */ 945 /* 946 * Consideration about text update interface 947 * 948 * In under-development composer framework, a single commit event of a 949 * composer instance can commit a text, update the preedit, and delete 950 * surrounding texts atomically to reduce text flicker. But because 951 * introducing this interface to current uim breaks backward compatibility 952 * completely, adding separated surrounding text deletion interface is better 953 * solution at now. -- YamaKen 2006-10-07 954 * 955 * https://github.com/uim/uim/blob/composer/scm/event.scm 956 * 957 * (define-event 'commit 958 * upward-event-rec-spec 959 * '((utext ()) ;; can include cursor position info 960 * (preedit-updated #t) ;; can also update preedit as atomic event 961 * (former-del-len 0) ;; for surrounding text operation 962 * (latter-del-len 0))) ;; for surrounding text operation 963 */ 964 /** 965 * Set callback functions for text acquisition and modification. 966 * 967 * All "former_len" and "latter_len" can be specified by zero, positive 968 * numbers or enum UTextExtent. The text length is counted in singlebyte or 969 * multibyte characters (not counted in bytes). Bridges may return a string 970 * shorter than requested if the text is actually shorter than the requested 971 * length, or the target textarea does not have the text acquisition 972 * ability. Otherwise exact length string must be returned. 973 * 974 * Both @a acquire_cb and @a delete_cb returns zero if succeeded, otherwise 975 * returns a negative integer if the bridge does not support the specified 976 * text operation. But even if zero is returned, actual length of acquired 977 * strings cannot be assumed (i.e. may be shorter than requested). 978 * 979 * @param uc input context 980 * @param acquire_cb called back when the input context want to acquire a 981 * bridge-side text. 982 * 1st argument "ptr" passes back the 1st argument of 983 * uim_create_context. 984 * 2nd argument "text_id" specifies a textarea having target text. 985 * 3rd argument "origin" specifies the origin which former_len and 986 * latter_len refers. 987 * 4th argument "former_len" specifies length of the text preceding the 988 * text origin to be acquired. 989 * 5th argument "latter_len" specifies length of the text following the 990 * text origin to be acquired. 991 * 6th argument "former" passes a pointer reference to receive the 992 * former part of the acquired text. The returned pointer 993 * may be NULL and object ownership is transferred to 994 * libuim. 995 * 7th argument "latter" passes a pointer reference to receive the 996 * latter part of the acquired text. The returned pointer 997 * may be NULL and object ownership is transferred to 998 * libuim. 999 * @param delete_cb called back when the input context want to delete a 1000 * bridge-side text. 1001 * 1st argument "ptr" passes back the 1st argument of 1002 * uim_create_context. 1003 * 2nd argument "text_id" specifies a textarea which is going to be 1004 * operated on. 1005 * 3rd argument "origin" specifies the origin which former_len and 1006 * latter_len refers. 1007 * 4th argument "former_len" specifies length of the text preceding the 1008 * text origin to be deleted. 1009 * 5th argument "latter_len" specifies length of the text following the 1010 * text origin to be deleted. 1011 */ 1012 void 1013 uim_set_text_acquisition_cb(uim_context uc, 1014 int (*acquire_cb)(void *ptr, 1015 enum UTextArea text_id, 1016 enum UTextOrigin origin, 1017 int former_len, int latter_len, 1018 char **former, char **latter), 1019 int (*delete_cb)(void *ptr, 1020 enum UTextArea text_id, 1021 enum UTextOrigin origin, 1022 int former_len, int latter_len)); 1023 1024 /** 1025 * Input arbitrary string into input context. 1026 * 1027 * @param uc the input context tied with the text area. 1028 * @param str the string to be input into. 1029 * 1030 * @return true if @a str is accepted (consumed) by the input context. 1031 */ 1032 uim_bool 1033 uim_input_string(uim_context uc, const char *str); 1034 1035 /* 1036 * Set callback function to be called when configuration of input 1037 * context is changed. 1038 * 1039 * @param uc input context 1040 * @param changed_cb called when configuration of the input context is changed. 1041 * 1st argument "ptr" corresponds to the 1st argument of uim_create_context. 1042 */ 1043 void 1044 uim_set_configuration_changed_cb(uim_context uc, 1045 void (*changed_cb)(void *ptr)); 1046 1047 1048 /* For plugins implementation. Bridges should not use these functions. */ 1049 void uim_fatal_error(const char *msg); /* Disables uim */ 1050 void *uim_malloc(size_t size); 1051 void *uim_realloc(void *p, size_t size); 1052 void *uim_calloc(size_t nmemb, size_t size); 1053 char *uim_strdup(const char *s); 1054 int uim_asprintf(char **, const char *, ...); 1055 1056 1057 #ifdef __cplusplus 1058 } 1059 #endif 1060 1061 #endif /* UIM_H */ 1062