     [file version.texi not included]

libchewing Reference Manual
***************************

This is the ``libchewing Reference Manual'' corresponding to libchewing version VERSION.

Copyright © 2012, 2013, 2014  libchewing Core Team

     Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved.

The document was typeset with GNU Texinfo (http://www.texinfo.org/).

Overview
********

As far as we expect, input method (in fact, the way for text input and output, especially in multi-lingual environments) implementations are becoming more and more complex in system integration.  The emerging standard for practical and flexible development cycles is required, so that we are facing the impacts from various Chinese input method implementations and the integration into existing framework or system designs.  At the result, Chewing Input Method (abbreviated as Chewing IM) attempts to be one of the approaches to solve and ease the problems with the inclusion of base classes, on the basis of cross-platform, and cross-operating-environment derivative classes, which are built as the abstract backbone of intelligent Chinese phonetic input method implementations.  From the perspectives, Chewing defines the abstract behavior how an intelligent phonetic IM should works via the common interface, and Chewing permits the extra parameters and properties for the input method implementations to extend their specific functionality.

 -- Macro: char* LIBCHEWING_ENCODING

          Not used anywhere. Will be removed soon.

     Indicate the internal encoding of data processing. Defined since version 0.3.0. Currently it is always "UTF-8".

Glossary
********

Bopomofo
     The word ``Bopomofo'' is a phonetic system for transcribing Chinese, especially Mandarin. The word ``zuin'', ``Zhuyin'' are obsolete terms for ``Bopomofo''.

bopomofo buffer
     The bopomofo buffer contains bopomofo symbols in current status. After a completed bopomofo sequence is provided, the content of bopomofo buffer will be cleaned and a word will be added to preedit buffer.

preedit buffer
     The preedit buffer contains string which is not finalized. The string can be updated by selecting new one with candidate selecting APIs. Normally, the content in preedit buffer will be displayed with underline.

commit buffer
     The commit buffer contains string which is finalized. A finalized string will not be modified by input method.

Setup
*****

Most of the Chewing IM APIs require a ChewingContext. To create a ChewingContext you must use the chewing_new function. For example,

     #include <chewing.h>
     int main(int argc, char *argv[])
     {
         ChewingContext *ctx = chewing_new();

         /* do something */

         chewing_delete( ctx );

         return 0;
     }

creates the context and deletes it after use.

Environment Variables
=====================

CHEWING_PATH
     The CHEWING_PATH environment variable is used to set the search path of static data used by the Chewing IM. The format of CHEWING_PATH is the same as PATH, which is multiple paths separated by `:' on POSIX and Unix-like platforms, or separated by `;' on Windows platform. The directories in CHEWING_PATH could be read-only.

CHEWING_USER_PATH
     The CHEWING_USER_PATH environment variable is used to specifies the path where user-defined hash data stores. This path should be writable by the user, or the Chewing IM will lose the ability to remember the learned phrases.

API
===

 -- Function: int chewing_Init (const char *DATAPATH, const char *HASHPATH)

          The chewing_Init function is no-op now. This function exists only for backword compatibility.

     The return value is always 0.

 -- Data Type: ChewingContext
     Context handle used for Chewing IM APIs

 -- Function: ChewingContext* chewing_new ()
     The chewing_new function creates a new instance of the Chewing IM.

     The return value is a pointer to the new Chewing IM instance. See also the chewing_new2, chewing_delete functions.

 -- Function: ChewingContext* chewing_new2 ( const char *SYSPATH, const char *USERPATH, void (*LOGGER)( void *data, int level, const char *fmt, ... ), void *LOGGERDATA)
     The chewing_new2 function creates a new instance of the Chewing IM. The SYSPATH is the directory path to system dictionary. The USERPATH is file path to user dictionary. User shall have enough permission to update this file. The LOGGER and LOGGERDATA is logger function and its data.

     All parameters will be default if set to NULL.

     The return value is a pointer to the new Chewing IM instance. See also the chewing_new, chewing_delete function.

 -- Function: void chewing_delete (ChewingContext *CTX)
     This function releases the resources used by the given Chewing IM instance.

 -- Data Type: ChewingConfigData

          Use the chewing_set_* function series to set parameters instead.

     This data type stores some parameters used by the Chewing IM. See also function chewing_Configure.

 -- Function: int chewing_Configure (ChewingContext *CTX, ChewingConfigData *PCD)

          Use the chewing_set_* function series to set parameters instead.

     This function sets the selectAreaLen, maxChiSymbolLen and selKey parameter from PCD.

     The PCD argument is a pointer to a Chewing configuration data structure. See also the ChewingConfigData data type.

     The return value is 0 on success and -1 on failure.

 -- Function: int chewing_Reset (ChewingContext *CTX)
     This function resets all settings in the given Chewing IM instance.

     The return value is 0 on success and -1 on failure.

 -- Function: void chewing_free (void *PTR)
     The chewing_free function releases the memory allocated by the Chewing IM and returned to the caller.

     There are functions returning pointers of strings or other data structures that are allocated on the heap. These memory must be freed to avoid memory leak. To avoid memory allocator mismatch between the Chewing IM and the caller, use this function the free the resource.

     Do nothing if PTR is NULL.

 -- Function: void chewing_set_logger (ChewingContext *CTX, void (*LOGGER)(void *DATA, int LEVEL, const char *FMT, ... ), void *DATA)

     This function sets the logger function LOGGER. The logger function is used to provide log inside Chewing IM for debugging. The DATA in chewing_set_logger is passed directly to DATA in LOGGER when logging. The following example shows how to use DATA:

          void logger( void *data, int level, const char *fmt, ... )
          {
              FILE *fd = (FILE *) data;
              ...
          }

          int main()
          {
              ChewingContext *ctx;
              FILE *fd;
              ...
              chewing_set_logger(ctx, logger, fd);
              ...
          }

     The LEVEL is log level. The symbolic names and their values are listed as following:
      -- Macro: int CHEWING_LOG_VERBOSE
          Its value is 1.

      -- Macro: int CHEWING_LOG_DEBUG
          Its value is 2.

      -- Macro: int CHEWING_LOG_INFO
          Its value is 3.

      -- Macro: int CHEWING_LOG_WARN
          Its value is 4.

      -- Macro: int CHEWING_LOG_ERROR
          Its value is 5.

Input Handling
**************

Functions to handle key strokes. The return value of these functions is 0 on success and -1 on failure.

 -- Function: int chewing_handle_Default (ChewingContext *CTX, int KEY)
     This function handles the default key KEY.

     The value of of KEY should be in the range between ASCII character code from a to z and from 0 to 9.

 -- Function: int chewing_handle_Backspace (ChewingContext *CTX)
     This function handles the input key BS.

 -- Function: int chewing_handle_Capslock (ChewingContext *CTX)
     This function handles the input key CAPS.

 -- Function: int chewing_handle_CtrlNum (ChewingContext *CTX, int KEY)
     This function handles the input holding key CTRL and number key KEY.

     The value of KEY should be in the range between ASCII character code from 0 to 9.

 -- Function: int chewing_handle_Del (ChewingContext *CTX)
     This function handles the input key DELETE.

 -- Function: int chewing_handle_Enter (ChewingContext *CTX)
     This function handles the input key RET.

 -- Function: int chewing_handle_Esc (ChewingContext *CTX)
     This function handles the input key ESC.

 -- Function: int chewing_handle_Space (ChewingContext *CTX)
     This function handles the input key SPC.

 -- Function: int chewing_handle_Tab (ChewingContext *CTX)
     This function handles the input key TAB.

 -- Function: int chewing_handle_Home (ChewingContext *CTX)
     This function handles the input key HOME.

 -- Function: int chewing_handle_End (ChewingContext *CTX)
     This function handles the input key END.

 -- Function: int chewing_handle_Left (ChewingContext *CTX)
     This function handles the input key LEFT.

 -- Function: int chewing_handle_Right (ChewingContext *CTX)
     This function handles the input key RIGHT.

 -- Function: int chewing_handle_Up (ChewingContext *CTX)
     This function handles the input key UP. UP is used to close candidate window.

          Use chewing_cand_close to close candidate window. The keyboard oriented API is not suggested to use anymore.

 -- Function: int chewing_handle_Down (ChewingContext *CTX)
     This function handles the input key DOWN. DOWN is used to open candidate window.

          Use chewing_cand_open to open candidate window. The keyboard oriented API is not suggested to use anymore.

 -- Function: int chewing_handle_ShiftLeft (ChewingContext *CTX)
     This function handles the input key holding SHIFT and LEFT simultaneously.

 -- Function: int chewing_handle_ShiftRight (ChewingContext *CTX)
     This function handles the input key holding SHIFT and RIGHT simultaneously.

 -- Function: int chewing_handle_ShiftSpace (ChewingContext *CTX)
     This function handles the input key holding SHIFT and SPC simultaneously.

 -- Function: int chewing_handle_PageUp (ChewingContext *CTX)
     This function handles the input key PAGEUP.

 -- Function: int chewing_handle_PageDown (ChewingContext *CTX)
     This function handles the input key PAGEDOWN.

 -- Function: int chewing_handle_DblTab (ChewingContext *CTX)
     This function handles the input key double TAB.

 -- Function: int chewing_handle_Numlock (ChewingContext *CTX, int KEY)
     This function handles the input key when KEY is from keypad.

     The value of KEY should be in the range between ASCII character code from 0 to 9.

Layout Settings
***************

The Chewing IM supports many different keyboard layout and variants. Use chewing_set_KBType to set the current keyboard layout for the context.

 -- Function: int chewing_set_KBType (ChewingContext *CTX, int KBTYPE)
     This functions sets the current keyboard layout for CTX. The KBTYPE argument should be a value returned from function chewing_KBStr2Num.

     The return value is 0 on success and -1 on failure. The keyboard type will set to KB_DEFAULT if return value is -1.

 -- Function: int chewing_get_KBType (const ChewingContext *CTX)
     This functions gets the current keyboard layout index for CTX.

     The return value is the layout index.

 -- Function: char* chewing_get_KBString (const ChewingContext *CTX)
     This function returns the the current layout name string of CTX. This function returns NULL when no memory.

     The return value is the name of the current layout, see also function chewing_KBStr2Num. The returned pointer must be freed by function chewing_free.

 -- Function: int chewing_KBStr2Num (const char STR[])
     This function converts the keyboard layout name to corresponding layout index. If the string does not match any layout, this function returns KB_DEFAULT.

     The string STR might be one of the following layouts:

       * KB_DEFAULT

       * KB_HSU

       * KB_IBM

       * KB_GIN_YIEH

       * KB_ET

       * KB_ET26

       * KB_DVORAK

       * KB_DVORAK_HSU

       * KB_DVORAK_CP26

       * KB_HANYU_PINYIN

       * KB_THL_PINYIN

       * KB_MPS2_PINYIN

       * KB_CARPALX

     See also the chewing_kbtype_* enumeration functions.

 -- Function: int chewing_kbtype_Total (const ChewingContext *CTX)
     This function returns the number of keyboard layouts supported by the Chewing IM.

 -- Function: void chewing_kbtype_Enumerate (ChewingContext *CTX)
     This function starts the enumeration of the keyboard layouts.

 -- Function: int chewing_kbtype_hasNext (ChewingContext *CTX)
     This function checks whether or not there are more keyboard layouts to enumerate.

 -- Function: char* chewing_kbtype_String (ChewingContext *CTX)
     This function returns the current enumerated keyboard layout name. The returned string is emtpy string when enumeration is over. This function returns NULL when no memory.

     The returned value is a pointer to a character string. The memory must be freed by the caller using function chewing_free.

 -- Function: const char* chewing_kbtype_String_static (ChewingContext *CTX)
     This function returns the current enumerated keyboard layout name. The returned string is emtpy string when enumeration is over.

     The return value is a const pointer to a character string. The memory will be invalid after internal state changed.

Operating Modes
***************

The Chewing IM can switch between Chinese input mode or English mode. The English mode supports input English characters directly. These functions set the current input mode.

 -- Macro: int CHINESE_MODE
 -- Macro: int SYMBOL_MODE
     Indicate whether the input mode is translating keystrokes to Chinese character or not.

 -- Function: void chewing_set_ChiEngMode (ChewingContext *CTX, int MODE)
     This function set the current Chinese/English mode.

     The MODE argument is one of the CHINESE_MODE and SYMBOL_MODE macros.

 -- Function: int chewing_get_ChiEngMode (const ChewingContext *CTX)
     This function returns the current Chinese/English mode setting.

 -- Macro: int FULLSHAPE_MODE
 -- Macro: int HALFSHAPE_MODE
     Indicate whether the input mode is translating the latin and punctuation characters to double-width characters or not.

 -- Function: void chewing_set_ShapeMode (ChewingContext *CTX, int MODE)
     This function set the current punctuation input mode.

     The MODE argument is one of the FULLSHAPE_MODE and HALFSHAPE_MODE macros.

 -- Function: int chewing_get_ShapeMode (const ChewingContext *CTX)
     This function returns the current punctuation mode.

Candidates Selection
********************

These are the functions to handle candidates selection. It means there are candidates when chewing_cand_TotalPage is greater than zero.

Get Candidates
==============

 -- Function: int chewing_cand_TotalPage (const ChewingContext *CTX)
     This function returns the number of pages of the candidates.

     If the return value is greater than zero, then the IM interface should display a selection window of the candidates for the user to choose a candidate. Otherwise hide the selection window.

 -- Function: int chewing_cand_CurrentPage (const ChewingContext *CTX)
     This function returns the current candidate page number.

     For example the candidates pagination could be displayed as:

          sprintf(BUF, "[%d / %d]",
                  chewing_cand_CurrentPage(CTX),
                  chewing_cand_TotalPage(CTX));

 -- Function: int chewing_cand_ChoicePerPage (const ChewingContext *CTX)
     This function returns the number of the choices per page.

     See also the chewing_set_candPerPage function.

 -- Function: int chewing_cand_TotalChoice (const ChewingContext *CTX)
     This function returns the number of the available choices.

 -- Function: void chewing_cand_Enumerate (ChewingContext *CTX)
     This function starts the enumeration of the candidates starting from the first one in the current page.

 -- Function: int chewing_cand_hasNext (ChewingContext *CTX)
     This function checks if there are more candidates to enumerate.

          The chewing_cand_hasNext function checks the end of total choices instead of the end of current page.

 -- Function: char* chewing_cand_String (ChewingContext *CTX)
     This function returns the current enumerated candidate string. This function returns NULL when no memory.

     The return value must be freed by the chewing_free function.

 -- Function: char* chewing_cand_String_static (ChewingContext *CTX)
     This function returns the current enumerated candidate string.

     The return value is a const pointer to a character string. The memory will be invalid after internal state changed.

 -- Function: int chewing_cand_CheckDone (const ChewingContext *CTX)

          The chewing_cand_TotalPage function could achieve the same effect.

     This function checks if the candidates selection has finished.

Candidates Behavior
===================

 -- Function: void chewing_set_candPerPage (ChewingContext *CTX, int N)
     This function sets the candidates per page to N. If MIN_SELKEY ≤ N ≤ MAX_SELKEY is not true or the number of selection keys is not enough, the N will be ignored. The default candidates per page is MAX_SELKEY.

 -- Function: int chewing_get_candPerPage (const ChewingContext *CTX)
     This function returns the candidates per page.

 -- Macro: int MAX_SELKEY
     The number of maximum candidates that are selectable via shortcut keys. Its value is 10.

 -- Macro: int MIN_SELKEY
     The number of minimum candidates that are selectable via shortcut keys. Its value is 1.

 -- Function: void chewing_set_selKey (ChewingContext *CTX, const int *SELKEYS, int LEN)
     This function sets the selection key to SELKEYS, an integer array of length MAX_SELKEY. The LEN is ignored by this function.

     For example the default selection key is 1234567890.

 -- Function: int* chewing_get_selKey (const ChewingContext *CTX)
     This function returns the current selection key setting. This function returns NULL when no memory.

     The return value must be freed by the chewing_free function.

 -- Macro: int HSU_SELKEY_TYPE1
 -- Macro: int HSU_SELKEY_TYPE2
     Use `asdfjkl789' or `asdfzxcv89' as selection key.

 -- Function: void chewing_set_hsuSelKeyType (ChewingContext *CTX, int MODE)

          This function is no-op now. Use chewing_set_selKey instead.

 -- Function: int chewing_get_hsuSelKeyType (ChewingContext *CTX)

          This function is no-op now. Use chewing_get_selKey instead.

Keyboardless APIs
=================

The traditional chewing APIs are coupling to keyboard. They cause some problems if the program like to design its own keyboard scheme, or if a platform does not have certain keyboard keys (ex: mobile device). To overcome these problems, the new keyboardless APIs are provided. With these APIs, program can have better control over libchewing, instead of hacking libchewing via fake keyboard event.

 -- Function: int chewing_cand_open (ChewingContext *CTX)
     This function opens the candidate windows. It returns 0 when success, -1 otherwise.

 -- Function: int chewing_cand_close (ChewingContext *CTX)
     This function closes the candidate windows. It returns 0 when success, -1 otherwise.

 -- Function: const char* chewing_cand_string_by_index_static (ChewingContext *CTX, int
     INDEX) This function returns the candidate string by its index. The range of INDEX shall be 0 ≤ INDEX < chewing_cand_TotalChoice. This function returns NULL when no memory.

     The return value is a const pointer to a character string. The memory will be freed by the next time be used.

 -- Function: int chewing_cand_choose_by_index (ChewingContext *CTX, int
     INDEX) This function chooses the candidate by its index. The range of INDEX shall be 0 ≤ INDEX < chewing_cand_TotalChoice. This function returns 0 when success, -1 otherwise.

 -- Function: int chewing_cand_list_first (ChewingContext *CTX)
     This function sets the candidate list to the first (longest) candidate list.

     This function returns 0 when success, -1 otherwise.

 -- Function: int chewing_cand_list_last (ChewingContext *CTX)
     This function sets the candidate list to the last (shortest) candidate list.

     This function returns 0 when success, -1 otherwise.

 -- Function: int chewing_cand_list_has_next (ChewingContext *CTX)
     This function checks whether or not there is a next (shorter) candidate list.

     The return value is 1 when there is a next candidate list, 0 otherwise.

 -- Function: int chewing_cand_list_has_prev (ChewingContext *CTX)
     This function checks whether or not there is a prev (longer) candidate list.

     The return value is 1 when there is a prev candidate list, 0 otherwise.

 -- Function: int chewing_cand_list_next (ChewingContext *CTX)
     This function changes current candidate list to next candidate list.

     This function returns 0 when success, -1 otherwise.

 -- Function: int chewing_cand_list_prev (ChewingContext *CTX)
     This function changes current candidate list to prev candidate list.

     This function returns 0 when success, -1 otherwise.

 -- Function: int chewing_commit_preedit_buf (ChewingContext *CTX)
     This function commits the current preedit buffer content to commit buffer.

     This function returns 0 when string is committed to commit buffer, -1 otherwise.

 -- Function: int chewing_clean_preedit_buf (ChewingContext *CTX)
     This function cleans the content in preedit buffer.

     This function returns 0 when preedit buffer is cleaned, -1 otherwise.

 -- Function: int chewing_clean_bopomofo_buf (ChewingContext *CTX)
     This function cleans the content in bopomofo buffer.

     This function returns 0 when bopomofo buffer is cleaned, -1 otherwise.

Output Handling
***************

 -- Function: int chewing_commit_Check (const ChewingContext *CTX)
     This function checks whether or not the commit buffer has a output to commit.

     The return value is 1 on success, 0 on failure.

 -- Function: char* chewing_commit_String (const ChewingContext *CTX)
     This function returns the string in the commit buffer. This function returns NULL when no memory.

     The return value is a pointer to a character string. The memory must be freed by the caller using function chewing_free.

 -- Function: const char* chewing_commit_String_static (const ChewingContext *CTX)
     This function returns the string in the commit buffer.

     The return value is a const pointer to a character string. The memory will be invalid after internal state changed.

 -- Function: int chewing_keystroke_CheckIgnore (const ChewingContext *CTX)
     This function checks whether the previous keystroke is ignored or not.

     The return value is 1 on success, 0 on failure.

 -- Function: int chewing_keystroke_CheckAbsorb (const ChewingContext *CTX)
     This function checks whether the previous keystroke is absorbed or not.

     The return value is 1 on success, 0 on failure.

 -- Function: int chewing_buffer_Check (ChewingContext *CTX)
     This function checks whether there is output in the pre-edit buffer.

     The return value is 1 on success, 0 on failure.

 -- Function: int chewing_buffer_Len (const ChewingContext *CTX)
     This function returns the length of the string in current pre-edit buffer.

 -- Function: char* chewing_buffer_String (const ChewingContext *CTX)
     This function returns the current output in the pre-edit buffer. This function returns NULL when no memory.

     The return value is a pointer to a character string. The memory must be freed by the caller using function chewing_free.

 -- Function: const char* chewing_buffer_String_static (const ChewingContext *CTX)
     This function returns the current output in the pre-edit buffer. This function returns NULL when no memory.

     The return value is a const pointer to a character string. The memory will be freed by the next time be used.

 -- Function: int chewing_bopomofo_Check (const ChewingContext *CTX)
     This function returns whether there are phonetic pre-edit string in the buffer.

     The return value is 1 when there are phonetic pre-edit string, 0 otherwise.

 -- Function: int chewing_zuin_Check (const ChewingContext *CTX)
     This function returns whether there are phonetic pre-edit string in the buffer.  Here ``zuin'' means bopomofo, a phonetic system for transcribing Chinese, especially Mandarin.

     The return value is 0 when there are phonetic pre-edit string, 1 otherwise.

     CAUTION: The return value of this function is different from chewing_commit_Check, chewing_buffer_Check, and chewing_aux_Check.

          This chewing_zuin_Check function is superseded by chewing_bopomofo_Check because it provides more consistent interface

 -- Function: char* chewing_bopomofo_String (ChewingContext *CTX)
     This function returns the phonetic characters in the pre-edit buffer. This function returns NULL when no memory.

     The return value must be freed by the chewing_free function.

 -- Function: const char* chewing_bopomofo_String_static (const ChewingContext *CTX)
     This function returns the phonetic characters in the pre-edit buffer.

     The return value is a const pointer to a character string. The memory will be invalid after internal state changed.

 -- Function: char* chewing_zuin_String (ChewingContext *CTX, int *BOPOMOFO_COUNT)
     This function returns the phonetic characters in the pre-edit buffer.

     The BOPOMOFO_COUNT argument is a output argument. It will contain the number of phonetic characters in the returned string. This function returns NULL when no memory.

     The return value is a pointer to a character string. This function returns NULL when no memory. The memory must be freed by the caller using function chewing_free.

          This chewing_zuin_String function is superseded by chewing_bopomofo_String_static because it provides more consistent interface

 -- Function: int chewing_cursor_Current (const ChewingContext *CTX)
     This function returns the current cursor position in the pre-edit buffer.

 -- Data Type: IntervalType
     The IntervalType type specifies the interval of a phrase segment in the pre-editng area and has following members:

     int FROM
          Starting position of certain interval.

     int TO
          Ending position of certain interval.

 -- Function: void chewing_interval_Enumerate (ChewingContext *CTX)
     This function starts the enumeration of intervals of recognized phrases.

 -- Function: int chewing_interval_hasNext (ChewingContext *CTX)
     This function checks whether there are more intervals or not.

     The return value is 1 on success, 0 on failure.

 -- Function: void chewing_interval_Get (ChewingContext *CTX, IntervalType *IT)
     This function returns the current enumerated interval.

     The IT argument is a output argument. See also IntervalType.

 -- Function: int chewing_aux_Check (const ChewingContext *CTX)
     This function checks whether there is auxiliary string in the auxiliary buffer.

     The return value is 1 on success, 0 on failure.

 -- Function: int chewing_aux_Length (const ChewingContext *CTX)
     This function returns the length of the auxiliary string in the auxiliary buffer.

 -- Function: char* chewing_aux_String (const ChewingContext *CTX)
     This function returns the current auxiliary string.

     The return value is a pointer to a character string. The memory must be freed by the caller using function chewing_free.

 -- Function: const char* chewing_aux_String_static (const ChewingContext *CTX)
     This function returns the current auxiliary string.

     The return value is a const pointer to a character string. The memory will be invalid after internal state changed.

 -- Function: unsigned short* chewing_get_phoneSeq (const ChewingContext *CTX)
     This function returns the phonetic sequence in the Chewing IM internal state machine.

     The return value is a pointer to a unsigned short array. The values in the array is encoded Bopomofo phone. The memory must be freed by the caller using function chewing_free.

 -- Function: int chewing_get_phoneSeqLen (const ChewingContext *CTX)
     This function returns the length of the phonetic sequence in the Chewing IM internal state machine.

Userphrase Handling
*******************

 -- Function: int chewing_userphrase_enumerate (ChewingContext *CTX)
     This function starts a userphrase enumeration. Caller shall call this function prior chewing_userphrase_has_next and chewing_userphrase_get in order to enumerate userphrase correctly.

     The return value is 0 on success, -1 on failure.

     The following example shows how to enumerate userphrase:

          chewing_userphrase_enumerate(ctx);
          while (chewing_userphrase_has_next(ctx, &phrase_len, &bopomofo_len)) {
              phrase = malloc(phrase_len);
              if (!phrase) goto error;
              bopomofo = malloc(bopomofo_len);
              if (!bopomofo) goto error;

              chewing_userphrase_get(ctx, phrase, phrase_len, bopomofo, bopomofo_len);
              /* do somthing */
          }

 -- Function: int chewing_userphrase_has_next (ChewingContext *CTX, unsigned
     int *PHRASE_LEN, unsigned int *BOPOMOFO_LEN)

     This function checks if there is another userphrase in current enumeration. The *PHRASE_LEN and *BOPOMOFO_LEN are output buffer lengths needed by userphrase and its bopomofo representation.

     The return value is 1 if there is another userphrase present, 0 otherwise.

 -- Function: int chewing_userphrase_get (ChewingContext *CTX, char
     *PHRASE_BUF, unsigned int PHRASE_LEN, char *BOPOMOFO_BUF, unsigned int BOPOMOFO_LEN) This function gets the current enumerated userphrase. The PHRASE_BUF and BOPOMOFO_BUF are userphrase and its bopomofo buffers provided by caller. The length of buffer PHRASE_LEN and BOPOMOFO_LEN can be get by chewing_userphrase_has_next.

     The return value is 0 on success, -1 on failure.

 -- Function: int chewing_userphrase_add (ChewingContext *CTX, const char
     *PHRASE_BUF, const char *BOPOMOFO_BUF) This function adds new userphrase PHRASE_BUF(BOPOMOFO_BUF).

     The return value is how many phrases are added, -1 on failure.

 -- Function: int chewing_userphrase_remove (ChewingContext *CTX, const
     char *PHRASE_BUF, const char *BOPOMOFO_BUF) This function removes new userphrase PHRASE_BUF(BOPOMOFO_BUF).

     The return value is how many phrases are removed, -1 on failure.

 -- Function: int chewing_userphrase_lookup (ChewingContext *CTX, const
     char *PHRASE_BUF, const char *BOPOMOFO_BUF) This function lookups if userphrase PHRASE_BUF(BOPOMOFO_BUF) is in userphrase.

     The return value is 1 if userphrase PHRASE_BUF(BOPOMOFO_BUF) is present, 0 otherwise.

Global Settings
***************

The Chewing IM could be customized in some small details. These functions provide the configuration interfaces to the front-end.

 -- Function: void chewing_set_maxChiSymbolLen (ChewingContext *CTX, int N)
     This function sets the maximum number of the Chinese characters in the pre-edit buffer. If the pre-edit string is longer than this number then the leading part will be committed automatically. The range of N shall between MIN_CHI_SYMBOL_LEN and MAX_CHI_SYMBOL_LEN.

 -- Macro: int MIN_CHI_SYMBOL_LEN
     The minimal size of pre-edit buffer. Its value is 0.

 -- Macro: int MAX_CHI_SYMBOL_LEN
     The maximum size of pre-edit buffer. Its value is MAX_PHONE_SEQ_LEN - MAX_PHRASE_LEN.

 -- Macro: int MAX_PHONE_SEQ_LEN
     The size of internal buffer for pre-edit buffer. Its value is 50.

 -- Macro: int MAX_PHRASE_LEN
     The maximum phrase size. Its value is 11.

 -- Function: int chewing_get_maxChiSymbolLen (const ChewingContext *CTX)
     This function returns the maximum number of the Chinese characters in the pre-edit buffer.

 -- Function: void chewing_set_addPhraseDirection (ChewingContext *CTX, int DIRECTION)
     This function sets the direction to add new phrases when typing CTRL-N.

     The DIRECTION argument is 0 when the direction is backward and 1 when the direction is forward.

 -- Function: int chewing_get_addPhraseDirection (const ChewingContext *CTX)
     This function returns the direction to add new phrases when typing CTRL-N.

     The return value is 0 when the direction is backward and 1 when the direction is forward.

 -- Function: void chewing_set_spaceAsSelection (ChewingContext *CTX, int MODE)
     This function sets whether SPC key is treated as a selection key.

     When the MODE argument is 1, the SPC key will initiate the candidates selection mode.

 -- Function: int chewing_get_spaceAsSelection (const ChewingContext *CTX)
     This function returns the space as selection mode setting.

 -- Function: void chewing_set_escCleanAllBuf (ChewingContext *CTX, int MODE)
     This function sets whether ESC key will flush the current pre-edit buffer.

     When the MODE argument is 1, the ESC key will flush the pre-edit buffer.

 -- Function: int chewing_get_escCleanAllBuf (const ChewingContext *CTX)
     This function returns the ESC key setting.

 -- Function: void chewing_set_autoShiftCur (ChewingContext *CTX, int MODE)
     This function sets whether the Chewing IM will automatically shift cursor after selection.

 -- Function: int chewing_get_autoShiftCur (const ChewingContext *CTX)
     This function returns the auto shift cursor setting.

 -- Function: void chewing_set_easySymbolInput (ChewingContext *CTX, int MODE)
     This function sets the current normal/easy symbol mode. In easy symbol mode, the key be will changed to its related easy symbol in swkb.dat. The format of swkb.dat is key symble pair per line. The valid value of key is [0-9A-Z]. The lower case character in key will be changed to upper case when loading swkb.dat. However, in easy symbol mode, only [0-9A-Z] are accepted.

     The MODE argument is 0 for normal mode or other for easy symbol mode.

     TODO: Need a macro for MODE.

 -- Function: int chewing_get_easySymbolInput (const ChewingContext *CTX)
     This function gets the current easy symbol mode.

 -- Function: void chewing_set_phraseChoiceRearward (ChewingContext *CTX, int MODE)
     This function sets whether the phrase for candidates selection is before the cursor or after the cursor.

 -- Function: int chewing_get_phraseChoiceRearward (const ChewingContext *CTX)
     This function returns the phrase choice rearward setting.