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

This is the "libchewing Reference Manual" corresponding to libchewing
version 0.4.0.

   Copyright (C) 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/).

1 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.

 -- Marco: char* LIBCHEWING_ENCODING
          Deprecated: 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"'.

2 Glassary
**********

"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.

3 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.

3.1 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.

3.2 API
=======

 -- Function: int chewing_Init (const char *DATAPATH, const char
          *HASHPATH)
          Deprecated: 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
          Deprecated: 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)
          Deprecated: 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'.

4 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.

          Deprecated: 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.

          Deprecated: 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'.

5 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_get_KBStr2Num'.  The returned pointer _must_ be
     freed by function 'chewing_free'.

 -- Function: int chewing_KBStr2Num (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'

     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 returnd 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: char* chewing_kbtype_String_static (ChewingContext *CTX)
     This function returns the current enumerated keyboard layout name.
     The returnd 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.

6 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.

 -- Marco: int CHINESE_MODE
 -- Marco: 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.

 -- Marco: int FULLSHAPE_MODE
 -- Marco: 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.

7 Candidates Selection
**********************

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

7.1 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.

          Note: 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)
          Deprecated: The 'chewing_cand_TotalPage' function could
          achieve the same effect.

     This function checks if the candidates selection has finished.

7.2 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, 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.

 -- Marco: int MAX_SELKEY
     The number of maximum candidates that are selectable via shortcut
     keys.  Its value is '10'.
 -- Marco: 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.

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

 -- Function: void chewing_set_hsuSelKeyType (ChewingContext *CTX, int
          MODE)
          Deprecated: This function is no-op now.  Use
          'chewing_set_selKey' instead.

 -- Function: int chewing_get_hsuSelKeyType (ChewingContext *CTX)
          Deprecated: This function is no-op now.  Use
          'chewing_get_selKey' instead.

7.3 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: 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.

8 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'.

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

 -- 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'.

          Deprecated: 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.

9 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.

10 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'.

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

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

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

 -- Marco: 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.