1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename libchewing.info 4@settitle libchewing 5@c %**end of header 6@include version.texi 7@dircategory Localization 8@direntry 9* libchewing: (libchewing). The libchewing reference manual. 10@end direntry 11@copying 12This is the ``libchewing Reference Manual'' corresponding to libchewing 13version @value{VERSION}. 14 15Copyright @copyright{} 2012, 2013, 2014 libchewing Core Team 16 17@quotation 18Copying and distribution of this file, with or without modification, 19are permitted in any medium without royalty provided the copyright 20notice and this notice are preserved. 21@end quotation 22 23The document was typeset with 24@uref{http://www.texinfo.org/, GNU Texinfo}. 25 26@end copying 27 28@titlepage 29@title libchewing Reference Manual 30@subtitle API collection of Chewing intelligent Chinese phonetic input method 31@author libchewing Core Team 32@page 33@vskip 0pt plus 1filll 34@insertcopying 35@end titlepage 36 37@c Output the table of the contents at the beginning. 38@contents 39 40@ifnottex 41@node Top, Overview, (dir), (dir) 42@top libchewing Reference Manual 43 44@insertcopying 45@end ifnottex 46 47@c Generate the nodes for this menu with `C-c C-u C-m'. 48@menu 49* Overview:: 50* Glossary:: 51* Setup:: 52* Input Handling:: 53* Layout Settings:: 54* Operating Modes:: 55* Candidates Selection:: 56* Output Handling:: 57* Userphrase Handling:: 58* Global Settings:: 59* Variable Index:: 60* Function Index:: 61* Concept Index:: 62@end menu 63 64@c Update all node entries with `C-c C-u C-n'. 65@c Insert new nodes with `C-c C-c n'. 66@node Overview 67@chapter Overview 68 69@c TODO: Rewrite this paragraph 70@cindex Chewing IM 71As far as we expect, input method (in fact, the way for text input and 72output, especially in multi-lingual environments) implementations are 73becoming more and more complex in system integration. The emerging 74standard for practical and flexible development cycles is required, so that 75we are facing the impacts from various Chinese input method implementations 76and the integration into existing framework or system designs. At the 77result, Chewing Input Method (abbreviated as @dfn{Chewing IM}) attempts to 78be one of the approaches to solve and ease the problems with the inclusion 79of base classes, on the basis of cross-platform, and 80cross-operating-environment derivative classes, which are built as the 81abstract backbone of intelligent Chinese phonetic input method 82implementations. From the perspectives, Chewing defines the abstract 83behavior how an intelligent phonetic IM should works via the common 84interface, and Chewing permits the extra parameters and properties for the 85input method implementations to extend their specific functionality. 86 87@deftypevr Macro char* LIBCHEWING_ENCODING 88@quotation Deprecated 89Not used anywhere. Will be removed soon. 90@end quotation 91 92Indicate the internal encoding of data processing. 93Defined since version 0.3.0. Currently it is always @code{"UTF-8"}. 94@end deftypevr 95 96@node Glossary 97@chapter Glossary 98 99@table @dfn 100@item Bopomofo 101@cindex zuin, Zhuyin 102@cindex Bopomofo 103The word ``Bopomofo'' is a phonetic system for transcribing Chinese, 104especially Mandarin. The word ``zuin'', ``Zhuyin'' are obsolete terms for 105``Bopomofo''. 106@end table 107 108@table @dfn 109@item bopomofo buffer 110@cindex bopomofo buffer 111The bopomofo buffer contains bopomofo symbols in current status. After a 112completed bopomofo sequence is provided, the content of bopomofo buffer will 113be cleaned and a word will be added to preedit buffer. 114@end table 115 116@table @dfn 117@item preedit buffer 118@cindex preedit buffer 119The preedit buffer contains string which is not finalized. The string can be 120updated by selecting new one with candidate selecting APIs. Normally, the 121content in preedit buffer will be displayed with underline. 122@end table 123 124@table @dfn 125@item commit buffer 126@cindex commit buffer 127The commit buffer contains string which is finalized. A finalized string will 128not be modified by input method. 129@end table 130 131@node Setup 132@chapter Setup 133 134Most of the Chewing IM APIs require a @code{ChewingContext}. To create 135a @code{ChewingContext} you must use the @code{chewing_new} 136function. For example, 137 138@example 139#include <chewing.h> 140int main(int argc, char *argv[]) 141@{ 142 ChewingContext *ctx = chewing_new(); 143 144 /* do something */ 145 146 chewing_delete( ctx ); 147 148 return 0; 149@} 150@end example 151 152@noindent 153creates the context and deletes it after use. 154 155@section Environment Variables 156 157@table @env 158@item CHEWING_PATH 159The @env{CHEWING_PATH} environment variable is used to set the search 160path of static data used by the Chewing IM. The format of 161@env{CHEWING_PATH} is the same as @env{PATH}, which is multiple paths 162separated by `:' on POSIX and Unix-like platforms, or separated by `;' 163on Windows platform. The directories in @env{CHEWING_PATH} could be 164read-only. 165 166@item CHEWING_USER_PATH 167The @env{CHEWING_USER_PATH} environment variable is used to specifies the path 168where user-defined hash data stores. This path @emph{should} be writable by the 169user, or the Chewing IM will lose the ability to remember the learned phrases. 170@end table 171 172@section API 173 174@deftypefun int chewing_Init (const char *@var{dataPath}, const char *@var{hashPath}) 175@quotation Deprecated 176The @code{chewing_Init} function is no-op now. This function exists only for 177backword compatibility. 178@end quotation 179 180The return value is always @code{0}. 181@end deftypefun 182 183@deftp {Data Type} ChewingContext 184Context handle used for Chewing @acronym{IM} @acronym{API}s 185@end deftp 186 187@deftypefun ChewingContext* chewing_new () 188The @code{chewing_new} function creates a new instance of the Chewing IM. 189 190The return value is a pointer to the new Chewing IM instance. See also 191the @code{chewing_new2}, @code{chewing_delete} functions. 192@end deftypefun 193 194@deftypefun ChewingContext* chewing_new2 ( const char *@var{syspath}, const char *@var{userpath}, void (*@var{logger})( void *data, int level, const char *fmt, ... ), void *@var{loggerdata}) 195The @code{chewing_new2} function creates a new instance of the Chewing IM. The 196@var{syspath} is the directory path to system dictionary. The @var{userpath} is 197file path to user dictionary. User shall have enough permission to update this 198file. The @var{logger} and @var{loggerdata} is logger function and its data. 199 200All parameters will be default if set to @code{NULL}. 201 202The return value is a pointer to the new Chewing IM instance. See also 203the @code{chewing_new}, @code{chewing_delete} function. 204@end deftypefun 205 206@deftypefun void chewing_delete (ChewingContext *@var{ctx}) 207This function releases the resources used by the given Chewing IM 208instance. 209@end deftypefun 210 211@deftp {Data Type} ChewingConfigData 212@quotation Deprecated 213Use the @code{chewing_set_*} function series to set parameters 214instead. 215@end quotation 216 217This data type stores some parameters used by the Chewing IM. See also 218function @code{chewing_Configure}. 219@end deftp 220 221@deftypefun int chewing_Configure (ChewingContext *@var{ctx}, ChewingConfigData *@var{pcd}) 222@quotation Deprecated 223Use the @code{chewing_set_*} function series to set parameters 224instead. 225@end quotation 226 227This function sets the @code{selectAreaLen}, @code{maxChiSymbolLen} and 228@code{selKey} parameter from @var{pcd}. 229 230The @var{pcd} argument is a pointer to a Chewing configuration data 231structure. See also the @code{ChewingConfigData} data type. 232 233The return value is @code{0} on success and @code{-1} on failure. 234@end deftypefun 235 236@deftypefun int chewing_Reset (ChewingContext *@var{ctx}) 237This function resets all settings in the given Chewing IM instance. 238 239The return value is @code{0} on success and @code{-1} on failure. 240@end deftypefun 241 242@deftypefun void chewing_free (void *@var{ptr}) 243The @code{chewing_free} function releases the memory allocated by the 244Chewing IM and returned to the caller. 245 246There are functions returning pointers of strings or other data 247structures that are allocated on the heap. These memory @emph{must} be 248freed to avoid memory leak. To avoid memory allocator mismatch between 249the Chewing IM and the caller, use this function the free the resource. 250 251Do nothing if @var{ptr} is @code{NULL}. 252@end deftypefun 253 254@deftypefun void chewing_set_logger (ChewingContext *@var{ctx}, void (*@var{logger})(void *@var{data}, int @var{level}, const char *@var{fmt}, ... ), void *@var{data}) 255 256This function sets the logger function @var{logger}. The logger function is 257used to provide log inside Chewing IM for debugging. The @var{data} in 258@code{chewing_set_logger} is passed directly to @var{data} in @var{logger} when 259logging. The following example shows how to use @var{data}: 260 261@example 262void logger( void *data, int level, const char *fmt, ... ) 263@{ 264 FILE *fd = (FILE *) data; 265 ... 266@} 267 268int main() 269@{ 270 ChewingContext *ctx; 271 FILE *fd; 272 ... 273 chewing_set_logger(ctx, logger, fd); 274 ... 275@} 276@end example 277 278The @var{level} is log level. The symbolic names and their values are listed as 279following: 280@deftypevr Macro int CHEWING_LOG_VERBOSE 281Its value is @code{1}. 282@end deftypevr 283@deftypevr Macro int CHEWING_LOG_DEBUG 284Its value is @code{2}. 285@end deftypevr 286@deftypevr Macro int CHEWING_LOG_INFO 287Its value is @code{3}. 288@end deftypevr 289@deftypevr Macro int CHEWING_LOG_WARN 290Its value is @code{4}. 291@end deftypevr 292@deftypevr Macro int CHEWING_LOG_ERROR 293Its value is @code{5}. 294@end deftypevr 295@end deftypefun 296 297@node Input Handling 298@chapter Input Handling 299 300Functions to handle key strokes. The return value of these functions 301is @code{0} on success and @code{-1} on failure. 302 303@c TODO: Add prose and examples to show how to use these functions. 304@c TODO: Sort functions by name and key type. 305 306@deftypefun int chewing_handle_Default (ChewingContext *@var{ctx}, int @var{key}) 307This function handles the default key @var{key}. 308 309The value of of @var{key} should be in the range between 310@acronym{ASCII} character code from @code{a} to @code{z} and from 311@code{0} to @code{9}. 312@end deftypefun 313 314@deftypefun int chewing_handle_Backspace (ChewingContext *@var{ctx}) 315This function handles the input key @kbd{BS}. 316@end deftypefun 317 318@deftypefun int chewing_handle_Capslock (ChewingContext *@var{ctx}) 319This function handles the input key @kbd{CAPS}. 320@end deftypefun 321 322@deftypefun int chewing_handle_CtrlNum (ChewingContext *@var{ctx}, int @var{key}) 323This function handles the input holding key @kbd{CTRL} and number key 324@var{key}. 325 326The value of @var{key} should be in the range between ASCII character 327code from @code{0} to @code{9}. 328@end deftypefun 329 330@deftypefun int chewing_handle_Del (ChewingContext *@var{ctx}) 331This function handles the input key @kbd{DELETE}. 332@end deftypefun 333 334@deftypefun int chewing_handle_Enter (ChewingContext *@var{ctx}) 335This function handles the input key @kbd{RET}. 336@end deftypefun 337 338@deftypefun int chewing_handle_Esc (ChewingContext *@var{ctx}) 339This function handles the input key @kbd{ESC}. 340@end deftypefun 341 342@deftypefun int chewing_handle_Space (ChewingContext *@var{ctx}) 343This function handles the input key @kbd{SPC}. 344@end deftypefun 345 346@deftypefun int chewing_handle_Tab (ChewingContext *@var{ctx}) 347This function handles the input key @kbd{TAB}. 348@end deftypefun 349 350@deftypefun int chewing_handle_Home (ChewingContext *@var{ctx}) 351This function handles the input key @kbd{HOME}. 352@end deftypefun 353 354@deftypefun int chewing_handle_End (ChewingContext *@var{ctx}) 355This function handles the input key @kbd{END}. 356@end deftypefun 357 358@deftypefun int chewing_handle_Left (ChewingContext *@var{ctx}) 359This function handles the input key @kbd{LEFT}. 360@end deftypefun 361 362@deftypefun int chewing_handle_Right (ChewingContext *@var{ctx}) 363This function handles the input key @kbd{RIGHT}. 364@end deftypefun 365 366@deftypefun int chewing_handle_Up (ChewingContext *@var{ctx}) 367This function handles the input key @kbd{UP}. @kbd{UP} is used to close 368candidate window. 369 370@quotation Deprecated 371Use @code{chewing_cand_close} to close candidate window. The keyboard oriented 372API is not suggested to use anymore. 373@end quotation 374@end deftypefun 375 376@deftypefun int chewing_handle_Down (ChewingContext *@var{ctx}) 377This function handles the input key @kbd{DOWN}. @kbd{DOWN} is used to open 378candidate window. 379 380@quotation Deprecated 381Use @code{chewing_cand_open} to open candidate window. The keyboard oriented 382API is not suggested to use anymore. 383@end quotation 384@end deftypefun 385 386@deftypefun int chewing_handle_ShiftLeft (ChewingContext *@var{ctx}) 387This function handles the input key holding @kbd{SHIFT} and @kbd{LEFT} simultaneously. 388@end deftypefun 389 390@deftypefun int chewing_handle_ShiftRight (ChewingContext *@var{ctx}) 391This function handles the input key holding @kbd{SHIFT} and @kbd{RIGHT} simultaneously. 392@end deftypefun 393 394@deftypefun int chewing_handle_ShiftSpace (ChewingContext *@var{ctx}) 395This function handles the input key holding @kbd{SHIFT} and @kbd{SPC} simultaneously. 396@end deftypefun 397 398@deftypefun int chewing_handle_PageUp (ChewingContext *@var{ctx}) 399This function handles the input key @kbd{PAGEUP}. 400@end deftypefun 401 402@deftypefun int chewing_handle_PageDown (ChewingContext *@var{ctx}) 403This function handles the input key @kbd{PAGEDOWN}. 404@end deftypefun 405 406@deftypefun int chewing_handle_DblTab (ChewingContext *@var{ctx}) 407This function handles the input key double @kbd{TAB}. 408@end deftypefun 409 410@deftypefun int chewing_handle_Numlock (ChewingContext *@var{ctx}, int @var{key}) 411This function handles the input key when @var{key} is from keypad. 412 413The value of @var{key} should be in the range between ASCII character 414code from @code{0} to @code{9}. 415@end deftypefun 416 417@node Layout Settings 418@chapter Layout Settings 419 420@c This API is horrible, we should fix it. 421 422The Chewing IM supports many different keyboard layout and 423variants. Use @code{chewing_set_KBType} to set the current keyboard 424layout for the context. 425 426@deftypefun int chewing_set_KBType (ChewingContext *@var{ctx}, int @var{kbtype}) 427This functions sets the current keyboard layout for @var{ctx}. The 428@var{kbtype} argument should be a value returned from function 429@code{chewing_KBStr2Num}. 430 431The return value is @code{0} on success and @code{-1} on failure. The keyboard 432type will set to @code{KB_DEFAULT} if return value is @code{-1}. 433@end deftypefun 434 435@c Seems not very useful, no? 436@deftypefun int chewing_get_KBType (const ChewingContext *@var{ctx}) 437This functions gets the current keyboard layout index for 438@var{ctx}. 439 440The return value is the layout index. 441@end deftypefun 442 443@deftypefun char* chewing_get_KBString (const ChewingContext *@var{ctx}) 444This function returns the the current layout name string of @var{ctx}. This 445function returns @code{NULL} when no memory. 446 447The return value is the name of the current layout, see also function 448@code{chewing_KBStr2Num}. The returned pointer @emph{must} be 449freed by function @code{chewing_free}. 450@end deftypefun 451 452@deftypefun int chewing_KBStr2Num (const char @var{str}[]) 453This function converts the keyboard layout name to corresponding 454layout index. If the string does not match any layout, this function returns 455@code{KB_DEFAULT}. 456 457@c Call cannot know if the string of keyboard layout is KB_DEFAULT, or no such 458@c layout. We shall fix it. 459 460The string @var{str} might be one of the following layouts: 461@itemize 462@item @code{KB_DEFAULT} 463@item @code{KB_HSU} 464@item @code{KB_IBM} 465@item @code{KB_GIN_YIEH} 466@item @code{KB_ET} 467@item @code{KB_ET26} 468@item @code{KB_DVORAK} 469@item @code{KB_DVORAK_HSU} 470@item @code{KB_DVORAK_CP26} 471@item @code{KB_HANYU_PINYIN} 472@item @code{KB_THL_PINYIN} 473@item @code{KB_MPS2_PINYIN} 474@item @code{KB_CARPALX} 475@end itemize 476 477See also the @code{chewing_kbtype_*} enumeration functions. 478@end deftypefun 479 480@deftypefun int chewing_kbtype_Total (const ChewingContext *@var{ctx}) 481This function returns the number of keyboard layouts supported by the 482Chewing IM. 483@end deftypefun 484 485@deftypefun void chewing_kbtype_Enumerate (ChewingContext *@var{ctx}) 486This function starts the enumeration of the keyboard layouts. 487@end deftypefun 488 489@deftypefun int chewing_kbtype_hasNext (ChewingContext *@var{ctx}) 490This function checks whether or not there are more keyboard layouts to 491enumerate. 492@end deftypefun 493 494@deftypefun char* chewing_kbtype_String (ChewingContext *@var{ctx}) 495This function returns the current enumerated keyboard layout name. The returned 496string is emtpy string when enumeration is over. This function returns 497@code{NULL} when no memory. 498 499The returned value is a pointer to a character string. The memory 500@emph{must} be freed by the caller using function @code{chewing_free}. 501@end deftypefun 502 503@deftypefun const char* chewing_kbtype_String_static (ChewingContext *@var{ctx}) 504This function returns the current enumerated keyboard layout name. The returned 505string is emtpy string when enumeration is over. 506 507The return value is a const pointer to a character string. The memory will 508be invalid after internal state changed. 509@end deftypefun 510 511@node Operating Modes 512@chapter Operating Modes 513 514The Chewing IM can switch between Chinese input mode or English 515mode. The English mode supports input English characters 516directly. These functions set the current input mode. 517 518@c TODO: We should have ENGLISH_MODE, no? 519@deftypevr Macro int CHINESE_MODE 520@deftypevrx Macro int SYMBOL_MODE 521Indicate whether the input mode is translating keystrokes to Chinese 522character or not. 523@end deftypevr 524 525@deftypefun void chewing_set_ChiEngMode (ChewingContext *@var{ctx}, int @var{mode}) 526This function set the current Chinese/English mode. 527 528The @var{mode} argument is one of the @code{CHINESE_MODE} and 529@code{SYMBOL_MODE} macros. 530@end deftypefun 531 532@deftypefun int chewing_get_ChiEngMode (const ChewingContext *@var{ctx}) 533This function returns the current Chinese/English mode setting. 534@end deftypefun 535 536@deftypevr Macro int FULLSHAPE_MODE 537@deftypevrx Macro int HALFSHAPE_MODE 538Indicate whether the input mode is translating the latin and 539punctuation characters to double-width characters or not. 540@end deftypevr 541 542@deftypefun void chewing_set_ShapeMode (ChewingContext *@var{ctx}, int @var{mode}) 543This function set the current punctuation input mode. 544 545The @var{mode} argument is one of the @code{FULLSHAPE_MODE} and 546@code{HALFSHAPE_MODE} macros. 547@end deftypefun 548 549@deftypefun int chewing_get_ShapeMode (const ChewingContext *@var{ctx}) 550This function returns the current punctuation mode. 551@end deftypefun 552 553@node Candidates Selection 554@chapter Candidates Selection 555 556These are the functions to handle candidates selection. It means there 557are candidates when @code{chewing_cand_TotalPage} is greater than 558zero. 559 560@menu 561* Get Candidates:: 562* Candidates Behavior:: 563* Keyboardless APIs:: 564@end menu 565 566@node Get Candidates 567@section Get Candidates 568 569@deftypefun int chewing_cand_TotalPage (const ChewingContext *@var{ctx}) 570This function returns the number of pages of the candidates. 571 572If the return value is greater than zero, then the IM interface should 573display a selection window of the candidates for the user to choose a 574candidate. Otherwise hide the selection window. 575@end deftypefun 576 577@deftypefun int chewing_cand_CurrentPage (const ChewingContext *@var{ctx}) 578This function returns the current candidate page number. 579 580For example the candidates pagination could be displayed as: 581 582@example 583sprintf(@var{buf}, "[%d / %d]", 584 chewing_cand_CurrentPage(@var{ctx}), 585 chewing_cand_TotalPage(@var{ctx})); 586@end example 587 588@end deftypefun 589 590@deftypefun int chewing_cand_ChoicePerPage (const ChewingContext *@var{ctx}) 591This function returns the number of the choices per page. 592 593See also the @code{chewing_set_candPerPage} function. 594@c API inconsistency. 595@end deftypefun 596 597@deftypefun int chewing_cand_TotalChoice (const ChewingContext *@var{ctx}) 598This function returns the number of the available choices. 599@end deftypefun 600 601@deftypefun void chewing_cand_Enumerate (ChewingContext *@var{ctx}) 602This function starts the enumeration of the candidates starting from 603the first one in the current page. 604@end deftypefun 605 606@deftypefun int chewing_cand_hasNext (ChewingContext *@var{ctx}) 607This function checks if there are more candidates to enumerate. 608 609@quotation Note 610The @code{chewing_cand_hasNext} function checks the end of total 611choices instead of the end of current page. 612@end quotation 613@end deftypefun 614 615@deftypefun char* chewing_cand_String (ChewingContext *@var{ctx}) 616This function returns the current enumerated candidate string. This function 617returns @code{NULL} when no memory. 618 619The return value @emph{must} be freed by the @code{chewing_free} 620function. 621@end deftypefun 622 623@deftypefun char* chewing_cand_String_static (ChewingContext *@var{ctx}) 624This function returns the current enumerated candidate string. 625 626The return value is a const pointer to a character string. The memory will 627be invalid after internal state changed. 628@end deftypefun 629 630@deftypefun int chewing_cand_CheckDone (const ChewingContext *@var{ctx}) 631@quotation Deprecated 632The @code{chewing_cand_TotalPage} function could achieve the same 633effect. 634@end quotation 635 636This function checks if the candidates selection has finished. 637@end deftypefun 638 639@node Candidates Behavior 640@section Candidates Behavior 641 642@deftypefun void chewing_set_candPerPage (ChewingContext *@var{ctx}, int @var{n}) 643This function sets the candidates per page to @var{n}. If MIN_SELKEY @leq{} 644@var{n} @leq{} @code{MAX_SELKEY} is not true or the number of selection keys is 645not enough, the @var{n} will be ignored. The default candidates per page is 646@code{MAX_SELKEY}. 647@end deftypefun 648 649@deftypefun int chewing_get_candPerPage (const ChewingContext *@var{ctx}) 650This function returns the candidates per page. 651@end deftypefun 652 653@deftypevr Macro int MAX_SELKEY 654The number of maximum candidates that are selectable via shortcut keys. Its 655value is @code{10}. 656@end deftypevr 657@deftypevr Macro int MIN_SELKEY 658The number of minimum candidates that are selectable via shortcut keys. Its 659value is @code{1}. 660@end deftypevr 661 662@deftypefun void chewing_set_selKey (ChewingContext *@var{ctx}, const int *@var{selkeys}, int @var{len}) 663This function sets the selection key to @var{selkeys}, an integer array of 664length @code{MAX_SELKEY}. The @var{len} is ignored by this function. 665 666For example the default selection key is @code{1234567890}. 667@end deftypefun 668 669@deftypefun int* chewing_get_selKey (const ChewingContext *@var{ctx}) 670This function returns the current selection key setting. This function returns 671@code{NULL} when no memory. 672 673The return value @emph{must} be freed by the @code{chewing_free} 674function. 675@end deftypefun 676 677@deftypevr Macro int HSU_SELKEY_TYPE1 678@deftypevrx Macro int HSU_SELKEY_TYPE2 679Use `asdfjkl789' or `asdfzxcv89' as selection key. 680@end deftypevr 681 682@deftypefun void chewing_set_hsuSelKeyType (ChewingContext *@var{ctx}, int @var{mode}) 683@quotation Deprecated 684This function is no-op now. Use @code{chewing_set_selKey} instead. 685@end quotation 686@end deftypefun 687 688@deftypefun int chewing_get_hsuSelKeyType (ChewingContext *@var{ctx}) 689@quotation Deprecated 690This function is no-op now. Use @code{chewing_get_selKey} instead. 691@end quotation 692@end deftypefun 693 694@node Keyboardless APIs 695@section Keyboardless APIs 696 697The traditional chewing APIs are coupling to keyboard. They cause some problems 698if the program like to design its own keyboard scheme, or if a platform does 699not have certain keyboard keys (ex: mobile device). To overcome these problems, 700the new keyboardless APIs are provided. With these APIs, program can have 701better control over libchewing, instead of hacking libchewing via fake keyboard 702event. 703 704@deftypefun int chewing_cand_open (ChewingContext *@var{ctx}) 705This function opens the candidate windows. It returns @code{0} when success, 706@code{-1} otherwise. 707@end deftypefun 708 709@deftypefun int chewing_cand_close (ChewingContext *@var{ctx}) 710This function closes the candidate windows. It returns @code{0} when success, 711@code{-1} otherwise. 712@end deftypefun 713 714@deftypefun const char* chewing_cand_string_by_index_static (ChewingContext *@var{ctx}, int 715@var{index}) 716This function returns the candidate string by its index. The range of 717@var{index} shall be @code{0} @leq{} @var{index} < 718@code{chewing_cand_TotalChoice}. This function returns @code{NULL} when no 719memory. 720 721The return value is a const pointer to a character string. The memory will 722be freed by the next time be used. 723@end deftypefun 724 725@deftypefun int chewing_cand_choose_by_index (ChewingContext *@var{ctx}, int 726@var{index}) 727This function chooses the candidate by its index. The range of @var{index} 728shall be @code{0} @leq{} @var{index} < @code{chewing_cand_TotalChoice}. This 729function returns @code{0} when success, @code{-1} otherwise. 730@end deftypefun 731 732@deftypefun int chewing_cand_list_first (ChewingContext *@var{ctx}) 733This function sets the candidate list to the first (longest) candidate list. 734 735This function returns @code{0} when success, @code{-1} otherwise. 736@end deftypefun 737 738@deftypefun int chewing_cand_list_last (ChewingContext *@var{ctx}) 739This function sets the candidate list to the last (shortest) candidate list. 740 741This function returns @code{0} when success, @code{-1} otherwise. 742@end deftypefun 743 744@deftypefun int chewing_cand_list_has_next (ChewingContext *@var{ctx}) 745This function checks whether or not there is a next (shorter) candidate list. 746 747The return value is @code{1} when there is a next candidate list, @code{0} 748otherwise. 749@end deftypefun 750 751@deftypefun int chewing_cand_list_has_prev (ChewingContext *@var{ctx}) 752This function checks whether or not there is a prev (longer) candidate list. 753 754The return value is @code{1} when there is a prev candidate list, @code{0} 755otherwise. 756@end deftypefun 757 758@deftypefun int chewing_cand_list_next (ChewingContext *@var{ctx}) 759This function changes current candidate list to next candidate list. 760 761This function returns @code{0} when success, @code{-1} otherwise. 762@end deftypefun 763 764@deftypefun int chewing_cand_list_prev (ChewingContext *@var{ctx}) 765This function changes current candidate list to prev candidate list. 766 767This function returns @code{0} when success, @code{-1} otherwise. 768@end deftypefun 769 770@deftypefun int chewing_commit_preedit_buf (ChewingContext *@var{ctx}) 771This function commits the current preedit buffer content to commit buffer. 772 773This function returns @code{0} when string is committed to commit buffer, 774@code{-1} otherwise. 775@end deftypefun 776 777@deftypefun int chewing_clean_preedit_buf (ChewingContext *@var{ctx}) 778This function cleans the content in preedit buffer. 779 780This function returns @code{0} when preedit buffer is cleaned, @code{-1} 781otherwise. 782@end deftypefun 783 784@deftypefun int chewing_clean_bopomofo_buf (ChewingContext *@var{ctx}) 785This function cleans the content in bopomofo buffer. 786 787This function returns @code{0} when bopomofo buffer is cleaned, @code{-1} 788otherwise. 789@end deftypefun 790 791@node Output Handling 792@chapter Output Handling 793 794@c TODO: The return value here is not consistent with the other APIs. 795 796@deftypefun int chewing_commit_Check (const ChewingContext *@var{ctx}) 797This function checks whether or not the commit buffer has a output to 798commit. 799 800The return value is @code{1} on success, @code{0} on failure. 801@end deftypefun 802 803@deftypefun char* chewing_commit_String (const ChewingContext *@var{ctx}) 804This function returns the string in the commit buffer. This function returns 805@code{NULL} when no memory. 806 807The return value is a pointer to a character string. The memory 808@emph{must} be freed by the caller using function @code{chewing_free}. 809@end deftypefun 810 811@deftypefun const char* chewing_commit_String_static (const ChewingContext *@var{ctx}) 812This function returns the string in the commit buffer. 813 814The return value is a const pointer to a character string. The memory will 815be invalid after internal state changed. 816@end deftypefun 817 818 819@deftypefun int chewing_keystroke_CheckIgnore (const ChewingContext *@var{ctx}) 820This function checks whether the previous keystroke is ignored or not. 821 822The return value is @code{1} on success, @code{0} on failure. 823@end deftypefun 824 825@deftypefun int chewing_keystroke_CheckAbsorb (const ChewingContext *@var{ctx}) 826This function checks whether the previous keystroke is absorbed or 827not. 828 829The return value is @code{1} on success, @code{0} on failure. 830@end deftypefun 831 832@deftypefun int chewing_buffer_Check (ChewingContext *@var{ctx}) 833This function checks whether there is output in the pre-edit buffer. 834 835The return value is @code{1} on success, @code{0} on failure. 836@end deftypefun 837 838@deftypefun int chewing_buffer_Len (const ChewingContext *@var{ctx}) 839This function returns the length of the string in current pre-edit 840buffer. 841@end deftypefun 842 843@deftypefun char* chewing_buffer_String (const ChewingContext *@var{ctx}) 844This function returns the current output in the pre-edit buffer. This function 845returns @code{NULL} when no memory. 846 847The return value is a pointer to a character string. The memory 848@emph{must} be freed by the caller using function @code{chewing_free}. 849@end deftypefun 850 851@deftypefun const char* chewing_buffer_String_static (const ChewingContext *@var{ctx}) 852This function returns the current output in the pre-edit buffer. This function 853returns @code{NULL} when no memory. 854 855The return value is a const pointer to a character string. The memory will 856be freed by the next time be used. 857@end deftypefun 858 859@deftypefun int chewing_bopomofo_Check (const ChewingContext *@var{ctx}) 860This function returns whether there are phonetic pre-edit string in the 861buffer. 862 863The return value is @code{1} when there are phonetic pre-edit string, @code{0} 864otherwise. 865 866@end deftypefun 867 868@deftypefun int chewing_zuin_Check (const ChewingContext *@var{ctx}) 869This function returns whether there are phonetic pre-edit string in the 870buffer. Here ``zuin'' means bopomofo, a phonetic system for transcribing 871Chinese, especially Mandarin. 872 873The return value is @code{0} when there are phonetic pre-edit string, @code{1} 874otherwise. 875 876@strong{CAUTION}: The return value of this function is different from 877@code{chewing_commit_Check}, @code{chewing_buffer_Check}, and 878@code{chewing_aux_Check}. 879 880@quotation Deprecated 881This @code{chewing_zuin_Check} function is superseded by @code{chewing_bopomofo_Check} 882because it provides more consistent interface 883@end quotation 884@end deftypefun 885 886@deftypefun char* chewing_bopomofo_String (ChewingContext *@var{ctx}) 887This function returns the phonetic characters in the pre-edit buffer. This 888function returns @code{NULL} when no memory. 889 890The return value @emph{must} be freed by the @code{chewing_free} 891function. 892@end deftypefun 893 894@deftypefun const char* chewing_bopomofo_String_static (const ChewingContext *@var{ctx}) 895This function returns the phonetic characters in the pre-edit buffer. 896 897The return value is a const pointer to a character string. The memory will be 898invalid after internal state changed. 899@end deftypefun 900 901@deftypefun char* chewing_zuin_String (ChewingContext *@var{ctx}, int *@var{bopomofo_count}) 902This function returns the phonetic characters in the pre-edit buffer. 903 904The @var{bopomofo_count} argument is a output argument. It will contain 905the number of phonetic characters in the returned string. This function returns 906@code{NULL} when no memory. 907 908The return value is a pointer to a character string. This function returns 909@code{NULL} when no memory. The memory @emph{must} be freed by the caller using 910function @code{chewing_free}. 911 912@quotation Deprecated 913This @code{chewing_zuin_String} function is superseded by @code{chewing_bopomofo_String_static} 914because it provides more consistent interface 915@end quotation 916@end deftypefun 917 918@deftypefun int chewing_cursor_Current (const ChewingContext *@var{ctx}) 919This function returns the current cursor position in the pre-edit 920buffer. 921@end deftypefun 922 923@deftp {Data Type} IntervalType 924The @code{IntervalType} type specifies the interval of a phrase 925segment in the pre-editng area and has following members: 926 927@table @code 928@item int @var{from} 929Starting position of certain interval. 930@item int @var{to} 931Ending position of certain interval. 932@end table 933@end deftp 934 935@deftypefun void chewing_interval_Enumerate (ChewingContext *@var{ctx}) 936This function starts the enumeration of intervals of recognized phrases. 937@end deftypefun 938 939@deftypefun int chewing_interval_hasNext (ChewingContext *@var{ctx}) 940This function checks whether there are more intervals or not. 941 942The return value is @code{1} on success, @code{0} on failure. 943@end deftypefun 944 945@deftypefun void chewing_interval_Get (ChewingContext *@var{ctx}, IntervalType *@var{it}) 946This function returns the current enumerated interval. 947 948The @var{it} argument is a output argument. See also 949@code{IntervalType}. 950@end deftypefun 951 952@deftypefun int chewing_aux_Check (const ChewingContext *@var{ctx}) 953This function checks whether there is auxiliary string in the 954auxiliary buffer. 955 956The return value is @code{1} on success, @code{0} on failure. 957@end deftypefun 958 959@deftypefun int chewing_aux_Length (const ChewingContext *@var{ctx}) 960This function returns the length of the auxiliary string in the 961auxiliary buffer. 962@end deftypefun 963 964@deftypefun char* chewing_aux_String (const ChewingContext *@var{ctx}) 965This function returns the current auxiliary string. 966 967The return value is a pointer to a character string. The memory 968@emph{must} be freed by the caller using function @code{chewing_free}. 969@end deftypefun 970 971@deftypefun const char* chewing_aux_String_static (const ChewingContext *@var{ctx}) 972This function returns the current auxiliary string. 973 974The return value is a const pointer to a character string. The memory will 975be invalid after internal state changed. 976@end deftypefun 977 978@deftypefun {unsigned short*} chewing_get_phoneSeq (const ChewingContext *@var{ctx}) 979This function returns the phonetic sequence in the Chewing IM internal 980state machine. 981 982The return value is a pointer to a @code{unsigned short} array. The 983values in the array is encoded Bopomofo phone. The memory @emph{must} be 984freed by the caller using function @code{chewing_free}. 985@end deftypefun 986 987@deftypefun int chewing_get_phoneSeqLen (const ChewingContext *@var{ctx}) 988This function returns the length of the phonetic sequence in the 989Chewing IM internal state machine. 990@end deftypefun 991 992@node Userphrase Handling 993@chapter Userphrase Handling 994 995@deftypefun int chewing_userphrase_enumerate (ChewingContext *@var{ctx}) 996This function starts a userphrase enumeration. Caller shall call this function 997prior @code{chewing_userphrase_has_next} and @code{chewing_userphrase_get} in 998order to enumerate userphrase correctly. 999 1000The return value is @code{0} on success, @code{-1} on failure. 1001 1002The following example shows how to enumerate userphrase: 1003@example 1004chewing_userphrase_enumerate(ctx); 1005while (chewing_userphrase_has_next(ctx, &phrase_len, &bopomofo_len)) @{ 1006 phrase = malloc(phrase_len); 1007 if (!phrase) goto error; 1008 bopomofo = malloc(bopomofo_len); 1009 if (!bopomofo) goto error; 1010 1011 chewing_userphrase_get(ctx, phrase, phrase_len, bopomofo, bopomofo_len); 1012 /* do somthing */ 1013@} 1014@end example 1015@end deftypefun 1016 1017@deftypefun int chewing_userphrase_has_next (ChewingContext *@var{ctx}, unsigned 1018int *@var{phrase_len}, unsigned int *@var{bopomofo_len}) 1019 1020This function checks if there is another userphrase in current enumeration. The 1021*@var{phrase_len} and *@var{bopomofo_len} are output buffer lengths needed by 1022userphrase and its bopomofo representation. 1023 1024The return value is @code{1} if there is another userphrase present, @code{0} 1025otherwise. 1026@end deftypefun 1027 1028@deftypefun int chewing_userphrase_get (ChewingContext *@var{ctx}, char 1029*@var{phrase_buf}, unsigned int @var{phrase_len}, char *@var{bopomofo_buf}, 1030unsigned int @var{bopomofo_len}) 1031This function gets the current enumerated userphrase. The @var{phrase_buf} and 1032@var{bopomofo_buf} are userphrase and its bopomofo buffers provided by caller. 1033The length of buffer @var{phrase_len} and @var{bopomofo_len} can be get by 1034@code{chewing_userphrase_has_next}. 1035 1036The return value is @code{0} on success, @code{-1} on failure. 1037@end deftypefun 1038 1039@deftypefun int chewing_userphrase_add (ChewingContext *@var{ctx}, const char 1040*@var{phrase_buf}, const char *@var{bopomofo_buf}) 1041This function adds new userphrase @var{phrase_buf}(@var{bopomofo_buf}). 1042 1043The return value is how many phrases are added, @code{-1} on failure. 1044@end deftypefun 1045 1046@deftypefun int chewing_userphrase_remove (ChewingContext *@var{ctx}, const 1047char *@var{phrase_buf}, const char *@var{bopomofo_buf}) 1048This function removes new userphrase @var{phrase_buf}(@var{bopomofo_buf}). 1049 1050The return value is how many phrases are removed, @code{-1} on failure. 1051@end deftypefun 1052 1053@deftypefun int chewing_userphrase_lookup (ChewingContext *@var{ctx}, const 1054char *@var{phrase_buf}, const char *@var{bopomofo_buf}) 1055This function lookups if userphrase @var{phrase_buf}(@var{bopomofo_buf}) is in 1056userphrase. 1057 1058The return value is @code{1} if userphrase @var{phrase_buf}(@var{bopomofo_buf}) 1059is present, @code{0} otherwise. 1060@end deftypefun 1061 1062@node Global Settings 1063@chapter Global Settings 1064 1065@c TODO: Document default settings. 1066 1067The Chewing IM could be customized in some small details. These 1068functions provide the configuration interfaces to the front-end. 1069 1070@deftypefun void chewing_set_maxChiSymbolLen (ChewingContext *@var{ctx}, int @var{n}) 1071This function sets the maximum number of the Chinese characters in the 1072pre-edit buffer. If the pre-edit string is longer than this number 1073then the leading part will be committed automatically. The range of @var{n} 1074shall between @code{MIN_CHI_SYMBOL_LEN} and @code{MAX_CHI_SYMBOL_LEN}. 1075@end deftypefun 1076 1077@deftypevr Macro int MIN_CHI_SYMBOL_LEN 1078The minimal size of pre-edit buffer. Its value is @code{0}. 1079@end deftypevr 1080 1081@deftypevr Macro int MAX_CHI_SYMBOL_LEN 1082The maximum size of pre-edit buffer. Its value is 1083@code{MAX_PHONE_SEQ_LEN - MAX_PHRASE_LEN}. 1084@end deftypevr 1085 1086@deftypevr Macro int MAX_PHONE_SEQ_LEN 1087The size of internal buffer for pre-edit buffer. Its value is @code{50}. 1088@end deftypevr 1089 1090@deftypevr Macro int MAX_PHRASE_LEN 1091The maximum phrase size. Its value is @code{11}. 1092@end deftypevr 1093 1094@deftypefun int chewing_get_maxChiSymbolLen (const ChewingContext *@var{ctx}) 1095This function returns the maximum number of the Chinese characters in 1096the pre-edit buffer. 1097@end deftypefun 1098 1099@c TODO: The @var{direction} argument should use a enum. 1100@deftypefun void chewing_set_addPhraseDirection (ChewingContext *@var{ctx}, int @var{direction}) 1101This function sets the direction to add new phrases when typing 1102@kbd{CTRL}-@var{n}. 1103 1104The @var{direction} argument is @code{0} when the direction is 1105backward and @code{1} when the direction is forward. 1106@end deftypefun 1107 1108@deftypefun int chewing_get_addPhraseDirection (const ChewingContext *@var{ctx}) 1109This function returns the direction to add new phrases when typing 1110@kbd{CTRL}-@var{n}. 1111 1112The return value is @code{0} when the direction is backward and 1113@code{1} when the direction is forward. 1114@end deftypefun 1115 1116@deftypefun void chewing_set_spaceAsSelection (ChewingContext *@var{ctx}, int @var{mode}) 1117This function sets whether @kbd{SPC} key is treated as a selection 1118key. 1119 1120When the @var{mode} argument is @code{1}, the @kbd{SPC} key will 1121initiate the candidates selection mode. 1122@end deftypefun 1123 1124@deftypefun int chewing_get_spaceAsSelection (const ChewingContext *@var{ctx}) 1125This function returns the space as selection mode setting. 1126@end deftypefun 1127 1128@deftypefun void chewing_set_escCleanAllBuf (ChewingContext *@var{ctx}, int @var{mode}) 1129This function sets whether @kbd{ESC} key will flush the current 1130pre-edit buffer. 1131 1132When the @var{mode} argument is @code{1}, the @kbd{ESC} key will flush 1133the pre-edit buffer. 1134@end deftypefun 1135 1136@deftypefun int chewing_get_escCleanAllBuf (const ChewingContext *@var{ctx}) 1137This function returns the @kbd{ESC} key setting. 1138@end deftypefun 1139 1140@deftypefun void chewing_set_autoShiftCur (ChewingContext *@var{ctx}, int @var{mode}) 1141This function sets whether the Chewing IM will automatically shift 1142cursor after selection. 1143@end deftypefun 1144 1145@deftypefun int chewing_get_autoShiftCur (const ChewingContext *@var{ctx}) 1146This function returns the auto shift cursor setting. 1147@end deftypefun 1148 1149@deftypefun void chewing_set_easySymbolInput (ChewingContext *@var{ctx}, int @var{mode}) 1150This function sets the current normal/easy symbol mode. In easy symbol mode, 1151the key be will changed to its related easy symbol in @file{swkb.dat}. The 1152format of @file{swkb.dat} is key symble pair per line. The valid value of key 1153is [0-9A-Z]. The lower case character in key will be changed to upper case when 1154loading @file{swkb.dat}. However, in easy symbol mode, only [0-9A-Z] are 1155accepted. 1156 1157The @var{mode} argument is @code{0} for normal mode or @code{other} for easy 1158symbol mode. 1159 1160@strong{TODO}: Need a macro for @var{mode}. 1161@end deftypefun 1162 1163@deftypefun int chewing_get_easySymbolInput (const ChewingContext *@var{ctx}) 1164This function gets the current easy symbol mode. 1165@end deftypefun 1166 1167@deftypefun void chewing_set_phraseChoiceRearward (ChewingContext *@var{ctx}, int @var{mode}) 1168This function sets whether the phrase for candidates selection is 1169before the cursor or after the cursor. 1170@end deftypefun 1171 1172@deftypefun int chewing_get_phraseChoiceRearward (const ChewingContext *@var{ctx}) 1173This function returns the phrase choice rearward setting. 1174@end deftypefun 1175 1176@node Variable Index 1177@unnumbered Variable Index 1178 1179@printindex vr 1180 1181@node Function Index 1182@unnumbered Function Index 1183 1184@printindex fn 1185 1186@node Concept Index 1187@unnumbered Concept Index 1188 1189@printindex cp 1190 1191@bye 1192 1193@c libchewing.texi ends here 1194