chewing_capi/
lib.rs

1#![deny(unsafe_op_in_unsafe_fn)]
2#![allow(unsafe_code)]
3#![allow(deprecated)]
4
5//! C compatible APIs for libchewing.
6//!
7//! All items are available via the C header file `<chewing.h>`.
8//!
9//! Function symbols are exposed from the libchewing shared library.
10//!
11//! Functions are organized into several modules according to the services
12//! provided by them.
13//!
14//! # Overview
15//!
16//! As far as we expect, input method (in fact, the way for text input and
17//! output, especially in multi-lingual environments) implementations are
18//! becoming more and more complex in system integrations.  The emerging
19//! standard for practical and flexible development cycles is required, so that
20//! we are facing the impacts from various Chinese input method implementations
21//! and the integration into existing framework or system designs.  At the
22//! result, Chewing Input Method (abbreviated as "Chewing") attempts to be one
23//! of the approaches to solve and ease the problems with the inclusion of base
24//! classes, on the basis of cross-platform, and cross-operating-environment
25//! derivative classes, which are built as the abstract backbone of intelligent
26//! Chinese phonetic input method implementations.  From the perspectives,
27//! Chewing defines the abstract behavior how an intelligent phonetic IM should
28//! works via the common interface, and Chewing permits the extra parameters and
29//! properties for the input method implementations to extend their specific
30//! functionality.
31
32mod io;
33mod logger;
34mod public;
35
36pub mod version;
37
38/// Initializes chewing context and environment settings.
39///
40/// Most of the Chewing IM APIs require a
41/// [ChewingContext][setup::ChewingContext]. To create a ChewingContext you must
42/// use the [chewing_new][setup::chewing_new] function.
43///
44/// # Examples
45///
46/// Create a chewing context and deletes it after use.
47///
48/// ```c
49/// #include <chewing.h>
50/// int main(int argc, char *argv[])
51/// {
52///     ChewingContext *ctx = chewing_new();
53///
54///     // do something
55///
56///     chewing_delete( ctx );
57///
58///     return 0;
59/// }
60/// ```
61///
62/// # Environment variables
63///
64/// * `CHEWING_PATH`
65///     * The CHEWING_PATH environment variable is used to set the search path
66///       of static data used by the Chewing IM. The format of CHEWING_PATH is
67///       the same as PATH, which is multiple paths separated by ‘:’ on POSIX
68///       and Unix-like platforms, or separated by ‘;’ on Windows platform. The
69///       directories in CHEWING_PATH could be read-only.
70/// * `CHEWING_USER_PATH`
71///     * The CHEWING_USER_PATH environment variable is used to specifies the
72///       path where user-defined hash data stores. This path should be writable
73///       by the user, or the Chewing IM will lose the ability to remember the
74///       learned phrases.
75pub mod setup {
76    pub use super::io::chewing_Configure;
77    pub use super::io::chewing_Init;
78    pub use super::io::chewing_Reset;
79    pub use super::io::chewing_Terminate;
80    pub use super::io::chewing_delete;
81    pub use super::io::chewing_free;
82    pub use super::io::chewing_get_defaultDictionaryNames;
83    pub use super::io::chewing_new;
84    pub use super::io::chewing_new2;
85    pub use super::io::chewing_new3;
86    pub use super::io::chewing_set_logger;
87    pub use super::public::CHEWING_LOG_DEBUG;
88    pub use super::public::CHEWING_LOG_ERROR;
89    pub use super::public::CHEWING_LOG_INFO;
90    pub use super::public::CHEWING_LOG_VERBOSE;
91    pub use super::public::CHEWING_LOG_WARN;
92    pub use super::public::ChewingContext;
93}
94
95/// Keyboard input handling.
96///
97/// Functions to handle key strokes. The return value of these functions is 0 on
98/// success and -1 on failure.
99pub mod input {
100    pub use super::io::chewing_handle_Backspace;
101    pub use super::io::chewing_handle_Capslock;
102    pub use super::io::chewing_handle_CtrlNum;
103    pub use super::io::chewing_handle_DblTab;
104    pub use super::io::chewing_handle_Default;
105    pub use super::io::chewing_handle_Del;
106    pub use super::io::chewing_handle_Down;
107    pub use super::io::chewing_handle_End;
108    pub use super::io::chewing_handle_Enter;
109    pub use super::io::chewing_handle_Esc;
110    pub use super::io::chewing_handle_Home;
111    pub use super::io::chewing_handle_KeyboardEvent;
112    pub use super::io::chewing_handle_Left;
113    pub use super::io::chewing_handle_Numlock;
114    pub use super::io::chewing_handle_PageDown;
115    pub use super::io::chewing_handle_PageUp;
116    pub use super::io::chewing_handle_Right;
117    pub use super::io::chewing_handle_ShiftLeft;
118    pub use super::io::chewing_handle_ShiftRight;
119    pub use super::io::chewing_handle_ShiftSpace;
120    pub use super::io::chewing_handle_Space;
121    pub use super::io::chewing_handle_Tab;
122    pub use super::io::chewing_handle_Up;
123    pub use super::public::KEYSTROKE_ABSORB;
124    pub use super::public::KEYSTROKE_BELL;
125    pub use super::public::KEYSTROKE_COMMIT;
126    pub use super::public::KEYSTROKE_IGNORE;
127}
128
129/// Keyboard layout and variants setting.
130///
131/// The Chewing IM supports many different keyboard layout and variants. Use
132/// functions in this module to set the current keyboard layout for the context.
133pub mod layout {
134    pub use super::io::chewing_KBStr2Num;
135    pub use super::io::chewing_get_KBString;
136    pub use super::io::chewing_get_KBType;
137    pub use super::io::chewing_kbtype_Enumerate;
138    pub use super::io::chewing_kbtype_String;
139    pub use super::io::chewing_kbtype_String_static;
140    pub use super::io::chewing_kbtype_Total;
141    pub use super::io::chewing_kbtype_hasNext;
142    pub use super::io::chewing_set_KBType;
143    pub use super::public::KB;
144}
145
146/// Input mode settings.
147///
148/// The Chewing IM can switch between Chinese input mode or English mode. The
149/// English mode supports input English characters directly. These functions set
150/// the current input mode.
151pub mod modes {
152    pub use super::io::chewing_get_ChiEngMode;
153    pub use super::io::chewing_get_ShapeMode;
154    pub use super::io::chewing_set_ChiEngMode;
155    pub use super::io::chewing_set_ShapeMode;
156    pub use super::public::CHINESE_MODE;
157    pub use super::public::FULLSHAPE_MODE;
158    pub use super::public::HALFSHAPE_MODE;
159    pub use super::public::SYMBOL_MODE;
160}
161
162/// Candidate selection related functions.
163///
164/// These functions can be used to transit the Chewing IM into candidate
165/// selection state and enumerate candidates.
166///
167/// # Keyboardless APIs
168///
169/// The traditional chewing APIs are coupled to keyboards. They cause some
170/// problems if the program like to design its own keyboard scheme, or if a
171/// platform does not have certain keyboard keys (ex: mobile device). To
172/// overcome these problems, the new keyboardless APIs are provided. With these
173/// APIs, program can have better control over libchewing, instead of hacking
174/// libchewing via fake keyboard event.
175pub mod candidates {
176    pub use super::io::chewing_cand_CheckDone;
177    pub use super::io::chewing_cand_ChoicePerPage;
178    pub use super::io::chewing_cand_CurrentPage;
179    pub use super::io::chewing_cand_Enumerate;
180    pub use super::io::chewing_cand_String;
181    pub use super::io::chewing_cand_String_static;
182    pub use super::io::chewing_cand_TotalChoice;
183    pub use super::io::chewing_cand_TotalPage;
184    pub use super::io::chewing_cand_choose_by_index;
185    pub use super::io::chewing_cand_close;
186    pub use super::io::chewing_cand_hasNext;
187    pub use super::io::chewing_cand_list_first;
188    pub use super::io::chewing_cand_list_has_next;
189    pub use super::io::chewing_cand_list_has_prev;
190    pub use super::io::chewing_cand_list_last;
191    pub use super::io::chewing_cand_list_next;
192    pub use super::io::chewing_cand_list_prev;
193    pub use super::io::chewing_cand_open;
194    pub use super::io::chewing_cand_string_by_index;
195    pub use super::io::chewing_cand_string_by_index_static;
196    pub use super::io::chewing_get_candPerPage;
197    pub use super::io::chewing_get_hsuSelKeyType;
198    pub use super::io::chewing_get_selKey;
199    pub use super::io::chewing_set_candPerPage;
200    pub use super::io::chewing_set_hsuSelKeyType;
201    pub use super::io::chewing_set_selKey;
202    pub use super::public::HSU_SELKEY_TYPE1;
203    pub use super::public::HSU_SELKEY_TYPE2;
204    pub use super::public::MAX_SELKEY;
205    pub use super::public::MIN_SELKEY;
206}
207
208/// Output handling.
209pub mod output {
210    pub use super::io::chewing_ack;
211    pub use super::io::chewing_aux_Check;
212    pub use super::io::chewing_aux_Length;
213    pub use super::io::chewing_aux_String;
214    pub use super::io::chewing_aux_String_static;
215    pub use super::io::chewing_bopomofo_Check;
216    pub use super::io::chewing_bopomofo_String;
217    pub use super::io::chewing_bopomofo_String_static;
218    pub use super::io::chewing_buffer_Check;
219    pub use super::io::chewing_buffer_Len;
220    pub use super::io::chewing_buffer_String;
221    pub use super::io::chewing_buffer_String_static;
222    pub use super::io::chewing_clean_bopomofo_buf;
223    pub use super::io::chewing_clean_preedit_buf;
224    pub use super::io::chewing_commit_Check;
225    pub use super::io::chewing_commit_String;
226    pub use super::io::chewing_commit_String_static;
227    pub use super::io::chewing_commit_preedit_buf;
228    pub use super::io::chewing_cursor_Current;
229    pub use super::io::chewing_get_phoneSeq;
230    pub use super::io::chewing_get_phoneSeqLen;
231    pub use super::io::chewing_interval_Enumerate;
232    pub use super::io::chewing_interval_Get;
233    pub use super::io::chewing_interval_hasNext;
234    pub use super::io::chewing_keystroke_CheckAbsorb;
235    pub use super::io::chewing_keystroke_CheckIgnore;
236    pub use super::io::chewing_phone_to_bopomofo;
237    pub use super::io::chewing_zuin_Check;
238    pub use super::io::chewing_zuin_String;
239    pub use super::public::IntervalType;
240}
241
242/// Userphrase handling.
243pub mod userphrase {
244    pub use super::io::chewing_userphrase_add;
245    pub use super::io::chewing_userphrase_enumerate;
246    pub use super::io::chewing_userphrase_get;
247    pub use super::io::chewing_userphrase_has_next;
248    pub use super::io::chewing_userphrase_lookup;
249    pub use super::io::chewing_userphrase_remove;
250}
251
252/// Global settings.
253///
254/// The Chewing IM could be customized in some small details. These functions
255/// provide the configuration interfaces to the front-end.
256pub mod globals {
257    pub use super::io::chewing_config_get_int;
258    pub use super::io::chewing_config_get_str;
259    pub use super::io::chewing_config_has_option;
260    pub use super::io::chewing_config_set_int;
261    pub use super::io::chewing_config_set_str;
262    pub use super::io::chewing_get_addPhraseDirection;
263    pub use super::io::chewing_get_autoLearn;
264    pub use super::io::chewing_get_autoShiftCur;
265    pub use super::io::chewing_get_easySymbolInput;
266    pub use super::io::chewing_get_escCleanAllBuf;
267    pub use super::io::chewing_get_maxChiSymbolLen;
268    pub use super::io::chewing_get_phraseChoiceRearward;
269    pub use super::io::chewing_get_spaceAsSelection;
270    pub use super::io::chewing_set_addPhraseDirection;
271    pub use super::io::chewing_set_autoLearn;
272    pub use super::io::chewing_set_autoShiftCur;
273    pub use super::io::chewing_set_easySymbolInput;
274    pub use super::io::chewing_set_escCleanAllBuf;
275    pub use super::io::chewing_set_maxChiSymbolLen;
276    pub use super::io::chewing_set_phraseChoiceRearward;
277    pub use super::io::chewing_set_spaceAsSelection;
278    pub use super::public::AUTOLEARN_DISABLED;
279    pub use super::public::AUTOLEARN_ENABLED;
280    pub use super::public::MAX_CHI_SYMBOL_LEN;
281    pub use super::public::MAX_PHONE_SEQ_LEN;
282    pub use super::public::MAX_PHRASE_LEN;
283    pub use super::public::MIN_CHI_SYMBOL_LEN;
284}
chewing_capi/lib.rs

chewing_capi/
lib.rs
