\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename libchewing.info
@settitle libchewing
@c %**end of header
@include version.texi
@dircategory Localization
@direntry
* libchewing: (libchewing).           The libchewing reference manual.
@end direntry
@copying
This is the ``libchewing Reference Manual'' corresponding to libchewing
version @value{VERSION}.

Copyright @copyright{} 2012, 2013, 2014  libchewing Core Team

@quotation
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.
@end quotation

The document was typeset with
@uref{http://www.texinfo.org/, GNU Texinfo}.

@end copying

@titlepage
@title libchewing Reference Manual
@subtitle API collection of Chewing intelligent Chinese phonetic input method
@author libchewing Core Team
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of the contents at the beginning.
@contents

@ifnottex
@node Top, Overview, (dir), (dir)
@top libchewing Reference Manual

@insertcopying
@end ifnottex

@c Generate the nodes for this menu with `C-c C-u C-m'.
@menu
* Overview::
* Glossary::
* Setup::
* Input Handling::
* Layout Settings::
* Operating Modes::
* Candidates Selection::
* Output Handling::
* Userphrase Handling::
* Global Settings::
* Variable Index::
* Function Index::
* Concept Index::
@end menu

@c Update all node entries with `C-c C-u C-n'.
@c Insert new nodes with `C-c C-c n'.
@node Overview
@chapter Overview

@c TODO: Rewrite this paragraph
@cindex Chewing IM
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 @dfn{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.

@deftypevr Macro char* LIBCHEWING_ENCODING
@quotation Deprecated
Not used anywhere. Will be removed soon.
@end quotation

Indicate the internal encoding of data processing.
Defined since version 0.3.0. Currently it is always @code{"UTF-8"}.
@end deftypevr

@node Glossary
@chapter Glossary

@table @dfn
@item Bopomofo
@cindex zuin, Zhuyin
@cindex Bopomofo
The word ``Bopomofo'' is a phonetic system for transcribing Chinese,
especially Mandarin. The word ``zuin'', ``Zhuyin'' are obsolete terms for
``Bopomofo''.
@end table

@table @dfn
@item bopomofo buffer
@cindex 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.
@end table

@table @dfn
@item preedit buffer
@cindex 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.
@end table

@table @dfn
@item commit buffer
@cindex commit buffer
The commit buffer contains string which is finalized. A finalized string will
not be modified by input method.
@end table

@node Setup
@chapter Setup

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

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

    /* do something */

    chewing_delete( ctx );

    return 0;
@}
@end example

@noindent
creates the context and deletes it after use.

@section Environment Variables

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

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

@section API

@deftypefun int chewing_Init (const char *@var{dataPath}, const char *@var{hashPath})
@quotation Deprecated
The @code{chewing_Init} function is no-op now. This function exists only for
backword compatibility.
@end quotation

The return value is always @code{0}.
@end deftypefun

@deftp {Data Type} ChewingContext
Context handle used for Chewing @acronym{IM} @acronym{API}s
@end deftp

@deftypefun ChewingContext* chewing_new ()
The @code{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 @code{chewing_new2}, @code{chewing_delete} functions.
@end deftypefun

@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})
The @code{chewing_new2} function creates a new instance of the Chewing IM. The
@var{syspath} is the directory path to system dictionary. The @var{userpath} is
file path to user dictionary. User shall have enough permission to update this
file. The @var{logger} and @var{loggerdata} is logger function and its data.

All parameters will be default if set to @code{NULL}.

The return value is a pointer to the new Chewing IM instance. See also
the @code{chewing_new}, @code{chewing_delete} function.
@end deftypefun

@deftypefun void chewing_delete (ChewingContext *@var{ctx})
This function releases the resources used by the given Chewing IM
instance.
@end deftypefun

@deftp {Data Type} ChewingConfigData
@quotation Deprecated
Use the @code{chewing_set_*} function series to set parameters
instead.
@end quotation

This data type stores some parameters used by the Chewing IM. See also
function @code{chewing_Configure}.
@end deftp

@deftypefun int chewing_Configure (ChewingContext *@var{ctx}, ChewingConfigData *@var{pcd})
@quotation Deprecated
Use the @code{chewing_set_*} function series to set parameters
instead.
@end quotation

This function sets the @code{selectAreaLen}, @code{maxChiSymbolLen} and
@code{selKey} parameter from @var{pcd}.

The @var{pcd} argument is a pointer to a Chewing configuration data
structure. See also the @code{ChewingConfigData} data type.

The return value is @code{0} on success and @code{-1} on failure.
@end deftypefun

@deftypefun int chewing_Reset (ChewingContext *@var{ctx})
This function resets all settings in the given Chewing IM instance.

The return value is @code{0} on success and @code{-1} on failure.
@end deftypefun

@deftypefun void chewing_free (void *@var{ptr})
The @code{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 @emph{must} be
freed to avoid memory leak. To avoid memory allocator mismatch between
the Chewing IM and the caller, use this function to free the resource.

Do nothing if @var{ptr} is @code{NULL}.
@end deftypefun

@deftypefun void chewing_set_logger (ChewingContext *@var{ctx}, void (*@var{logger})(void *@var{data}, int @var{level}, const char *@var{fmt}, ... ), void *@var{data})

This function sets the logger function @var{logger}. The logger function is
used to provide log inside Chewing IM for debugging. The @var{data} in
@code{chewing_set_logger} is passed directly to @var{data} in @var{logger} when
logging. The following example shows how to use @var{data}:

@example
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);
    ...
@}
@end example

The @var{level} is log level. The symbolic names and their values are listed as
following:
@deftypevr  Macro int CHEWING_LOG_VERBOSE
Its value is @code{1}.
@end deftypevr
@deftypevr  Macro int CHEWING_LOG_DEBUG
Its value is @code{2}.
@end deftypevr
@deftypevr  Macro int CHEWING_LOG_INFO
Its value is @code{3}.
@end deftypevr
@deftypevr  Macro int CHEWING_LOG_WARN
Its value is @code{4}.
@end deftypevr
@deftypevr  Macro int CHEWING_LOG_ERROR
Its value is @code{5}.
@end deftypevr
@end deftypefun

@node Input Handling
@chapter Input Handling

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

@c TODO: Add prose and examples to show how to use these functions.
@c TODO: Sort functions by name and key type.

@deftypefun int chewing_handle_Default (ChewingContext *@var{ctx}, int @var{key})
This function handles all @var{key}s that do not have dedicated methods.

The value of of @var{key} can be any printable @acronym{ASCII} characters.
@end deftypefun

@deftypefun int chewing_handle_Backspace (ChewingContext *@var{ctx})
This function handles the input key @kbd{BS}.
@end deftypefun

@deftypefun int chewing_handle_Capslock (ChewingContext *@var{ctx})
This function handles the input key @kbd{CAPS}.
@end deftypefun

@deftypefun int chewing_handle_CtrlNum (ChewingContext *@var{ctx}, int @var{key})
This function handles the input holding key @kbd{CTRL} and number key
@var{key}.

The value of @var{key} should be in the range between ASCII character
code from @code{0} to @code{9}.
@end deftypefun

@deftypefun int chewing_handle_Del (ChewingContext *@var{ctx})
This function handles the input key @kbd{DELETE}.
@end deftypefun

@deftypefun int chewing_handle_Enter (ChewingContext *@var{ctx})
This function handles the input key @kbd{RET}.
@end deftypefun

@deftypefun int chewing_handle_Esc (ChewingContext *@var{ctx})
This function handles the input key @kbd{ESC}.
@end deftypefun

@deftypefun int chewing_handle_Space (ChewingContext *@var{ctx})
This function handles the input key @kbd{SPC}.
@end deftypefun

@deftypefun int chewing_handle_Tab (ChewingContext *@var{ctx})
This function handles the input key @kbd{TAB}.
@end deftypefun

@deftypefun int chewing_handle_Home (ChewingContext *@var{ctx})
This function handles the input key @kbd{HOME}.
@end deftypefun

@deftypefun int chewing_handle_End (ChewingContext *@var{ctx})
This function handles the input key @kbd{END}.
@end deftypefun

@deftypefun int chewing_handle_Left (ChewingContext *@var{ctx})
This function handles the input key @kbd{LEFT}.
@end deftypefun

@deftypefun int chewing_handle_Right (ChewingContext *@var{ctx})
This function handles the input key @kbd{RIGHT}.
@end deftypefun

@deftypefun int chewing_handle_Up (ChewingContext *@var{ctx})
This function handles the input key @kbd{UP}. @kbd{UP} is used to close
candidate window.

@quotation Deprecated
Use @code{chewing_cand_close} to close candidate window. The keyboard oriented
API is not suggested to use anymore.
@end quotation
@end deftypefun

@deftypefun int chewing_handle_Down (ChewingContext *@var{ctx})
This function handles the input key @kbd{DOWN}. @kbd{DOWN} is used to open
candidate window.

@quotation Deprecated
Use @code{chewing_cand_open} to open candidate window. The keyboard oriented
API is not suggested to use anymore.
@end quotation
@end deftypefun

@deftypefun int chewing_handle_ShiftLeft (ChewingContext *@var{ctx})
This function handles the input key holding @kbd{SHIFT} and @kbd{LEFT} simultaneously.
@end deftypefun

@deftypefun int chewing_handle_ShiftRight (ChewingContext *@var{ctx})
This function handles the input key holding @kbd{SHIFT} and @kbd{RIGHT} simultaneously.
@end deftypefun

@deftypefun int chewing_handle_ShiftSpace (ChewingContext *@var{ctx})
This function handles the input key holding @kbd{SHIFT} and @kbd{SPC} simultaneously.
@end deftypefun

@deftypefun int chewing_handle_PageUp (ChewingContext *@var{ctx})
This function handles the input key @kbd{PAGEUP}.
@end deftypefun

@deftypefun int chewing_handle_PageDown (ChewingContext *@var{ctx})
This function handles the input key @kbd{PAGEDOWN}.
@end deftypefun

@deftypefun int chewing_handle_DblTab (ChewingContext *@var{ctx})
This function handles the input key double @kbd{TAB}.
@end deftypefun

@deftypefun int chewing_handle_Numlock (ChewingContext *@var{ctx}, int @var{key})
This function handles the input key when @var{key} is from keypad.

The value of @var{key} should be in the range between ASCII character
code from @code{0} to @code{9}.
@end deftypefun

@node Layout Settings
@chapter Layout Settings

@c This API is horrible, we should fix it.

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

@deftypefun int chewing_set_KBType (ChewingContext *@var{ctx}, int @var{kbtype})
This functions sets the current keyboard layout for @var{ctx}. The
@var{kbtype} argument should be a value returned from function
@code{chewing_KBStr2Num}.

The return value is @code{0} on success and @code{-1} on failure. The keyboard
type will set to @code{KB_DEFAULT} if return value is @code{-1}.
@end deftypefun

@c Seems not very useful, no?
@deftypefun int chewing_get_KBType (const ChewingContext *@var{ctx})
This functions gets the current keyboard layout index for
@var{ctx}.

The return value is the layout index.
@end deftypefun

@deftypefun char* chewing_get_KBString (const ChewingContext *@var{ctx})
This function returns the the current layout name string of @var{ctx}. This
function returns @code{NULL} when no memory.

The return value is the name of the current layout, see also function
@code{chewing_KBStr2Num}. The returned pointer @emph{must} be
freed by function @code{chewing_free}.
@end deftypefun

@deftypefun int chewing_KBStr2Num (const char @var{str}[])
This function converts the keyboard layout name to corresponding
layout index. If the string does not match any layout, this function returns
@code{KB_DEFAULT}.

@c Call cannot know if the string of keyboard layout is KB_DEFAULT, or no such
@c layout. We shall fix it.

The string @var{str} might be one of the following layouts:
@itemize
@item @code{KB_DEFAULT}
@item @code{KB_HSU}
@item @code{KB_IBM}
@item @code{KB_GIN_YIEH}
@item @code{KB_ET}
@item @code{KB_ET26}
@item @code{KB_DVORAK}
@item @code{KB_DVORAK_HSU}
@item @code{KB_DVORAK_CP26}
@item @code{KB_HANYU_PINYIN}
@item @code{KB_THL_PINYIN}
@item @code{KB_MPS2_PINYIN}
@item @code{KB_CARPALX}
@item @code{KB_COLEMAK}
@item @code{KB_COLEMAK_DH_ANSI}
@item @code{KB_COLEMAK_DH_ORTH}
@end itemize

See also the @code{chewing_kbtype_*} enumeration functions.
@end deftypefun

@deftypefun int chewing_kbtype_Total (const ChewingContext *@var{ctx})
This function returns the number of keyboard layouts supported by the
Chewing IM.
@end deftypefun

@deftypefun void chewing_kbtype_Enumerate (ChewingContext *@var{ctx})
This function starts the enumeration of the keyboard layouts.
@end deftypefun

@deftypefun int chewing_kbtype_hasNext (ChewingContext *@var{ctx})
This function checks whether or not there are more keyboard layouts to
enumerate.
@end deftypefun

@deftypefun char* chewing_kbtype_String (ChewingContext *@var{ctx})
This function returns the current enumerated keyboard layout name. The returned
string is emtpy string when enumeration is over. This function returns
@code{NULL} when no memory.

The returned value is a pointer to a character string. The memory
@emph{must} be freed by the caller using function @code{chewing_free}.
@end deftypefun

@deftypefun const char* chewing_kbtype_String_static (ChewingContext *@var{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.
@end deftypefun

@node Operating Modes
@chapter 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.

@c TODO: We should have ENGLISH_MODE, no?
@deftypevr  Macro int CHINESE_MODE
@deftypevrx Macro int SYMBOL_MODE
Indicate whether the input mode is translating keystrokes to Chinese
character or not.
@end deftypevr

@deftypefun void chewing_set_ChiEngMode (ChewingContext *@var{ctx}, int @var{mode})
This function set the current Chinese/English mode.

The @var{mode} argument is one of the @code{CHINESE_MODE} and
@code{SYMBOL_MODE} macros.
@end deftypefun

@deftypefun int chewing_get_ChiEngMode (const ChewingContext *@var{ctx})
This function returns the current Chinese/English mode setting.
@end deftypefun

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

@deftypefun void chewing_set_ShapeMode (ChewingContext *@var{ctx}, int @var{mode})
This function set the current punctuation input mode.

The @var{mode} argument is one of the @code{FULLSHAPE_MODE} and
@code{HALFSHAPE_MODE} macros.
@end deftypefun

@deftypefun int chewing_get_ShapeMode (const ChewingContext *@var{ctx})
This function returns the current punctuation mode.
@end deftypefun

@node Candidates Selection
@chapter Candidates Selection

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

@menu
* Get Candidates::
* Candidates Behavior::
* Keyboardless APIs::
@end menu

@node Get Candidates
@section Get Candidates

@deftypefun int chewing_cand_TotalPage (const ChewingContext *@var{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.
@end deftypefun

@deftypefun int chewing_cand_CurrentPage (const ChewingContext *@var{ctx})
This function returns the current candidate page number.

For example the candidates pagination could be displayed as:

@example
sprintf(@var{buf}, "[%d / %d]",
        chewing_cand_CurrentPage(@var{ctx}),
        chewing_cand_TotalPage(@var{ctx}));
@end example

@end deftypefun

@deftypefun int chewing_cand_ChoicePerPage (const ChewingContext *@var{ctx})
This function returns the number of the choices per page.

See also the @code{chewing_set_candPerPage} function.
@c API inconsistency.
@end deftypefun

@deftypefun int chewing_cand_TotalChoice (const ChewingContext *@var{ctx})
This function returns the number of the available choices.
@end deftypefun

@deftypefun void chewing_cand_Enumerate (ChewingContext *@var{ctx})
This function starts the enumeration of the candidates starting from
the first one in the current page.
@end deftypefun

@deftypefun int chewing_cand_hasNext (ChewingContext *@var{ctx})
This function checks if there are more candidates to enumerate.

@quotation Note
The @code{chewing_cand_hasNext} function checks the end of total
choices instead of the end of current page.
@end quotation
@end deftypefun

@deftypefun char* chewing_cand_String (ChewingContext *@var{ctx})
This function returns the current enumerated candidate string. This function
returns @code{NULL} when no memory.

The return value @emph{must} be freed by the @code{chewing_free}
function.
@end deftypefun

@deftypefun char* chewing_cand_String_static (ChewingContext *@var{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.
@end deftypefun

@deftypefun int chewing_cand_CheckDone (const ChewingContext *@var{ctx})
@quotation Deprecated
The @code{chewing_cand_TotalPage} function could achieve the same
effect.
@end quotation

This function checks if the candidates selection has finished.
@end deftypefun

@node Candidates Behavior
@section Candidates Behavior

@deftypefun void chewing_set_candPerPage (ChewingContext *@var{ctx}, int @var{n})
This function sets the candidates per page to @var{n}. If MIN_SELKEY <=
@var{n} <= @code{MAX_SELKEY} is not true or the number of selection keys is
not enough, the @var{n} will be ignored. The default candidates per page is
@code{MAX_SELKEY}.
@end deftypefun

@deftypefun int chewing_get_candPerPage (const ChewingContext *@var{ctx})
This function returns the candidates per page.
@end deftypefun

@deftypevr Macro int MAX_SELKEY
The number of maximum candidates that are selectable via shortcut keys. Its
value is @code{10}.
@end deftypevr
@deftypevr Macro int MIN_SELKEY
The number of minimum candidates that are selectable via shortcut keys. Its
value is @code{1}.
@end deftypevr

@deftypefun void chewing_set_selKey (ChewingContext *@var{ctx}, const int *@var{selkeys}, int @var{len})
This function sets the selection key to @var{selkeys}, an integer array of
length @code{MAX_SELKEY}. The @var{len} is ignored by this function.

For example the default selection key is @code{1234567890}.
@end deftypefun

@deftypefun int* chewing_get_selKey (const ChewingContext *@var{ctx})
This function returns the current selection key setting. This function returns
@code{NULL} when no memory.

The return value @emph{must} be freed by the @code{chewing_free}
function.
@end deftypefun

@deftypevr  Macro int HSU_SELKEY_TYPE1
@deftypevrx Macro int HSU_SELKEY_TYPE2
Use `asdfjkl789' or `asdfzxcv89' as selection key.
@end deftypevr

@deftypefun void chewing_set_hsuSelKeyType (ChewingContext *@var{ctx}, int @var{mode})
@quotation Deprecated
This function is no-op now. Use @code{chewing_set_selKey} instead.
@end quotation
@end deftypefun

@deftypefun int chewing_get_hsuSelKeyType (ChewingContext *@var{ctx})
@quotation Deprecated
This function is no-op now. Use @code{chewing_get_selKey} instead.
@end quotation
@end deftypefun

@node Keyboardless APIs
@section 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.

@deftypefun int chewing_cand_open (ChewingContext *@var{ctx})
This function opens the candidate windows. It returns @code{0} when success,
@code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_cand_close (ChewingContext *@var{ctx})
This function closes the candidate windows. It returns @code{0} when success,
@code{-1} otherwise.
@end deftypefun

@deftypefun const char* chewing_cand_string_by_index_static (ChewingContext *@var{ctx}, int
@var{index})
This function returns the candidate string by its index. The range of
@var{index} shall be @code{0} <= @var{index} <
@code{chewing_cand_TotalChoice}. This function returns @code{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.
@end deftypefun

@deftypefun int chewing_cand_choose_by_index (ChewingContext *@var{ctx}, int
@var{index})
This function chooses the candidate by its index. The range of @var{index}
shall be @code{0} <= @var{index} < @code{chewing_cand_TotalChoice}. This
function returns @code{0} when success, @code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_first (ChewingContext *@var{ctx})
This function sets the candidate list to the first (longest) candidate list.

This function returns @code{0} when success, @code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_last (ChewingContext *@var{ctx})
This function sets the candidate list to the last (shortest) candidate list.

This function returns @code{0} when success, @code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_has_next (ChewingContext *@var{ctx})
This function checks whether or not there is a next (shorter) candidate list.

The return value is @code{1} when there is a next candidate list, @code{0}
otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_has_prev (ChewingContext *@var{ctx})
This function checks whether or not there is a prev (longer) candidate list.

The return value is @code{1} when there is a prev candidate list, @code{0}
otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_next (ChewingContext *@var{ctx})
This function changes current candidate list to next candidate list.

This function returns @code{0} when success, @code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_cand_list_prev (ChewingContext *@var{ctx})
This function changes current candidate list to prev candidate list.

This function returns @code{0} when success, @code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_commit_preedit_buf (ChewingContext *@var{ctx})
This function commits the current preedit buffer content to commit buffer.

This function returns @code{0} when string is committed to commit buffer,
@code{-1} otherwise.
@end deftypefun

@deftypefun int chewing_clean_preedit_buf (ChewingContext *@var{ctx})
This function cleans the content in preedit buffer.

This function returns @code{0} when preedit buffer is cleaned, @code{-1}
otherwise.
@end deftypefun

@deftypefun int chewing_clean_bopomofo_buf (ChewingContext *@var{ctx})
This function cleans the content in bopomofo buffer.

This function returns @code{0} when bopomofo buffer is cleaned, @code{-1}
otherwise.
@end deftypefun

@node Output Handling
@chapter Output Handling

@c TODO: The return value here is not consistent with the other APIs.

@deftypefun int chewing_commit_Check (const ChewingContext *@var{ctx})
This function checks whether or not the commit buffer has a output to
commit.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun char* chewing_commit_String (const ChewingContext *@var{ctx})
This function returns the string in the commit buffer. This function returns
@code{NULL} when no memory.

The return value is a pointer to a character string. The memory
@emph{must} be freed by the caller using function @code{chewing_free}.
@end deftypefun

@deftypefun const char* chewing_commit_String_static (const ChewingContext *@var{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.
@end deftypefun


@deftypefun int chewing_keystroke_CheckIgnore (const ChewingContext *@var{ctx})
This function checks whether the previous keystroke is ignored or not.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun int chewing_keystroke_CheckAbsorb (const ChewingContext *@var{ctx})
This function checks whether the previous keystroke is absorbed or
not.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun int chewing_buffer_Check (ChewingContext *@var{ctx})
This function checks whether there is output in the pre-edit buffer.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun int chewing_buffer_Len (const ChewingContext *@var{ctx})
This function returns the length of the string in current pre-edit
buffer.
@end deftypefun

@deftypefun char* chewing_buffer_String (const ChewingContext *@var{ctx})
This function returns the current output in the pre-edit buffer. This function
returns @code{NULL} when no memory.

The return value is a pointer to a character string. The memory
@emph{must} be freed by the caller using function @code{chewing_free}.
@end deftypefun

@deftypefun const char* chewing_buffer_String_static (const ChewingContext *@var{ctx})
This function returns the current output in the pre-edit buffer. This function
returns @code{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.
@end deftypefun

@deftypefun int chewing_bopomofo_Check (const ChewingContext *@var{ctx})
This function returns whether there are phonetic pre-edit string in the
buffer.

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

@end deftypefun

@deftypefun int chewing_zuin_Check (const ChewingContext *@var{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 @code{0} when there are phonetic pre-edit string, @code{1}
otherwise.

@strong{CAUTION}: The return value of this function is different from
@code{chewing_commit_Check}, @code{chewing_buffer_Check}, and
@code{chewing_aux_Check}.

@quotation Deprecated
This @code{chewing_zuin_Check} function is superseded by @code{chewing_bopomofo_Check}
because it provides more consistent interface
@end quotation
@end deftypefun

@deftypefun const char* chewing_bopomofo_String_static (const ChewingContext *@var{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.
@end deftypefun

@deftypefun char* chewing_zuin_String (ChewingContext *@var{ctx}, int *@var{bopomofo_count})
This function returns the phonetic characters in the pre-edit buffer.

The @var{bopomofo_count} argument is a output argument. It will contain
the number of phonetic characters in the returned string. This function returns
@code{NULL} when no memory.

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

@quotation Deprecated
This @code{chewing_zuin_String} function is superseded by @code{chewing_bopomofo_String_static}
because it provides more consistent interface
@end quotation
@end deftypefun

@deftypefun int chewing_cursor_Current (const ChewingContext *@var{ctx})
This function returns the current cursor position in the pre-edit
buffer.
@end deftypefun

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

@table @code
@item int @var{from}
Starting position of certain interval.
@item int @var{to}
Ending position of certain interval.
@end table
@end deftp

@deftypefun void chewing_interval_Enumerate (ChewingContext *@var{ctx})
This function starts the enumeration of intervals of recognized phrases.
@end deftypefun

@deftypefun int chewing_interval_hasNext (ChewingContext *@var{ctx})
This function checks whether there are more intervals or not.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun void chewing_interval_Get (ChewingContext *@var{ctx}, IntervalType *@var{it})
This function returns the current enumerated interval.

The @var{it} argument is a output argument. See also
@code{IntervalType}.
@end deftypefun

@deftypefun int chewing_aux_Check (const ChewingContext *@var{ctx})
This function checks whether there is auxiliary string in the
auxiliary buffer.

The return value is @code{1} on success, @code{0} on failure.
@end deftypefun

@deftypefun int chewing_aux_Length (const ChewingContext *@var{ctx})
This function returns the length of the auxiliary string in the
auxiliary buffer.
@end deftypefun

@deftypefun char* chewing_aux_String (const ChewingContext *@var{ctx})
This function returns the current auxiliary string.

The return value is a pointer to a character string. The memory
@emph{must} be freed by the caller using function @code{chewing_free}.
@end deftypefun

@deftypefun const char* chewing_aux_String_static (const ChewingContext *@var{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.
@end deftypefun

@deftypefun {unsigned short*} chewing_get_phoneSeq (const ChewingContext *@var{ctx})
This function returns the phonetic sequence in the Chewing IM internal
state machine.

The return value is a pointer to a @code{unsigned short} array. The
values in the array is encoded Bopomofo phone. The memory @emph{must} be
freed by the caller using function @code{chewing_free}.
@end deftypefun

@deftypefun int chewing_get_phoneSeqLen (const ChewingContext *@var{ctx})
This function returns the length of the phonetic sequence in the
Chewing IM internal state machine.
@end deftypefun

@deftypefun int chewing_phone_to_bopomofo (unsigned short @var{phone}, char *@var{buf}, unsigned short @var{len})
This function converts the phone to bopomofo.

If both of the buf and the len are 0, this function will return buf length for bopomofo including
the null character so that caller can prepare enough buffer for it.

The return value is '0' on success, '-1' on failure.
@end deftypefun

@node Userphrase Handling
@chapter Userphrase Handling

@deftypefun int chewing_userphrase_enumerate (ChewingContext *@var{ctx})
This function starts a userphrase enumeration. Caller shall call this function
prior @code{chewing_userphrase_has_next} and @code{chewing_userphrase_get} in
order to enumerate userphrase correctly.

The return value is @code{0} on success, @code{-1} on failure.

The following example shows how to enumerate userphrase:
@example
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 */
@}
@end example
@end deftypefun

@deftypefun int chewing_userphrase_has_next (ChewingContext *@var{ctx}, unsigned
int *@var{phrase_len}, unsigned int *@var{bopomofo_len})

This function checks if there is another userphrase in current enumeration. The
*@var{phrase_len} and *@var{bopomofo_len} are output buffer lengths needed by
userphrase and its bopomofo representation.

The return value is @code{1} if there is another userphrase present, @code{0}
otherwise.
@end deftypefun

@deftypefun int chewing_userphrase_get (ChewingContext *@var{ctx}, char
*@var{phrase_buf}, unsigned int @var{phrase_len}, char *@var{bopomofo_buf},
unsigned int @var{bopomofo_len})

This function gets the current enumerated userphrase. The @var{phrase_buf} and
@var{bopomofo_buf} are userphrase and its bopomofo buffers provided by caller.
The length of buffer @var{phrase_len} and @var{bopomofo_len} can be get by
@code{chewing_userphrase_has_next}.

The return value is @code{0} on success, @code{-1} on failure.
@end deftypefun

@deftypefun int chewing_userphrase_add (ChewingContext *@var{ctx}, const char
*@var{phrase_buf}, const char *@var{bopomofo_buf})

This function adds new userphrase @var{phrase_buf}(@var{bopomofo_buf}).

The return value is how many phrases are added, @code{-1} on failure.
@end deftypefun

@deftypefun int chewing_userphrase_remove (ChewingContext *@var{ctx}, const
char *@var{phrase_buf}, const char *@var{bopomofo_buf})

This function removes new userphrase @var{phrase_buf}(@var{bopomofo_buf}).

The return value is how many phrases are removed, @code{-1} on failure.
@end deftypefun

@deftypefun int chewing_userphrase_lookup (ChewingContext *@var{ctx}, const
char *@var{phrase_buf}, const char *@var{bopomofo_buf})

This function lookups if userphrase @var{phrase_buf}(@var{bopomofo_buf}) is in
userphrase.

The return value is @code{1} if userphrase @var{phrase_buf}(@var{bopomofo_buf})
is present, @code{0} otherwise.
@end deftypefun

@node Global Settings
@chapter Global Settings

@c TODO: Document default settings.

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

@deftypefun void chewing_set_maxChiSymbolLen (ChewingContext *@var{ctx}, int @var{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 @var{n}
shall between @code{MIN_CHI_SYMBOL_LEN} and @code{MAX_CHI_SYMBOL_LEN}.
@end deftypefun

@deftypevr Macro int MIN_CHI_SYMBOL_LEN
The minimal size of pre-edit buffer. Its value is @code{0}.
@end deftypevr

@deftypevr Macro int MAX_CHI_SYMBOL_LEN
The maximum size of pre-edit buffer. Its value is
@code{MAX_PHONE_SEQ_LEN - MAX_PHRASE_LEN}.
@end deftypevr

@deftypevr Macro int MAX_PHONE_SEQ_LEN
The size of internal buffer for pre-edit buffer. Its value is @code{50}.
@end deftypevr

@deftypevr Macro int MAX_PHRASE_LEN
The maximum phrase size. Its value is @code{11}.
@end deftypevr

@deftypefun int chewing_get_maxChiSymbolLen (const ChewingContext *@var{ctx})
This function returns the maximum number of the Chinese characters in
the pre-edit buffer.
@end deftypefun

@c TODO: The @var{direction} argument should use a enum.
@deftypefun void chewing_set_addPhraseDirection (ChewingContext *@var{ctx}, int @var{direction})
This function sets the direction to add new phrases when typing
@kbd{CTRL}-@var{n}.

The @var{direction} argument is @code{0} when the direction is
backward and @code{1} when the direction is forward.
@end deftypefun

@deftypefun int chewing_get_addPhraseDirection (const ChewingContext *@var{ctx})
This function returns the direction to add new phrases when typing
@kbd{CTRL}-@var{n}.

The return value is @code{0} when the direction is backward and
@code{1} when the direction is forward.
@end deftypefun

@deftypefun void chewing_set_spaceAsSelection (ChewingContext *@var{ctx}, int @var{mode})
This function sets whether @kbd{SPC} key is treated as a selection
key.

When the @var{mode} argument is @code{1}, the @kbd{SPC} key will
initiate the candidates selection mode.
@end deftypefun

@deftypefun int chewing_get_spaceAsSelection (const ChewingContext *@var{ctx})
This function returns the space as selection mode setting.
@end deftypefun

@deftypefun void chewing_set_escCleanAllBuf (ChewingContext *@var{ctx}, int @var{mode})
This function sets whether @kbd{ESC} key will flush the current
pre-edit buffer.

When the @var{mode} argument is @code{1}, the @kbd{ESC} key will flush
the pre-edit buffer.
@end deftypefun

@deftypefun int chewing_get_escCleanAllBuf (const ChewingContext *@var{ctx})
This function returns the @kbd{ESC} key setting.
@end deftypefun

@deftypefun void chewing_set_autoShiftCur (ChewingContext *@var{ctx}, int @var{mode})
This function sets whether the Chewing IM will automatically shift
cursor after selection.
@end deftypefun

@deftypefun int chewing_get_autoShiftCur (const ChewingContext *@var{ctx})
This function returns the auto shift cursor setting.
@end deftypefun

@deftypefun void chewing_set_easySymbolInput (ChewingContext *@var{ctx}, int @var{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 @file{swkb.dat}. The
format of @file{swkb.dat} is key symbol 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 @file{swkb.dat}. However, in easy symbol mode, only [0-9A-Z] are
accepted.

The @var{mode} argument is @code{0} for normal mode or @code{other} for easy
symbol mode.

@strong{TODO}: Need a macro for @var{mode}.
@end deftypefun

@deftypefun int chewing_get_easySymbolInput (const ChewingContext *@var{ctx})
This function gets the current easy symbol mode.
@end deftypefun

@deftypefun void chewing_set_phraseChoiceRearward (ChewingContext *@var{ctx}, int @var{mode})
This function sets whether the phrase for candidates selection is
before the cursor or after the cursor.
@end deftypefun

@deftypefun int chewing_get_phraseChoiceRearward (const ChewingContext *@var{ctx})
This function returns the phrase choice rearward setting.
@end deftypefun

@deftypefun void chewing_set_autoLearn (ChewingContext *@var{ctx}, int @var{mode})
This function can be used to enable or disable the automatic learning.

The @var{mode} argument is be one of the @code{AUTOLEARN_ENABLED} and @code{AUTOLEARN_DISABLED} macros.
@end deftypefun

@deftypevr  Macro int AUTOLEARN_ENABLED
@deftypevrx Macro int AUTOLEARN_DISABLED
Indicate whether the automatic learning is enabled or not.
@end deftypevr

@deftypefun int chewing_get_autoLearn (const ChewingContext *@var{ctx})
This function returns whether the automatic learning is enabled or disabled.
@end deftypefun

@node Variable Index
@unnumbered Variable Index

@printindex vr

@node Function Index
@unnumbered Function Index

@printindex fn

@node Concept Index
@unnumbered Concept Index

@printindex cp

@bye

@c libchewing.texi ends here