IIIMF_status iiimcf_initialize( | attr ) ; |
IIIMCF_attr | attr ; |
iiimcf_initialize
initializes IIIMCF library.
You MUST call this function once before using IIIMCF APIs, except for
iiimcf_attr_attr
, iiimcf_destroy_attr
,
iiimcf_attr_put_*_value
,
and iiimcf_attr_get_*_value
.
IIIMF_status iiimcf_finalize( | ) ; |
| ; |
iiimcf_finalize
initializes IIIMCF library.
This function releases all resources reserved or used by IIIMCF library.
Note that you MUST destroy all handles before calling this function.
IIIMF_status iiimcf_create_handle( | attr , | |
phandle) ; |
IIIMCF_attr | attr ; |
IIIMCF_handle* | phandle; |
iiimcf_create_handle
creates a handle, which is
used as a descriptor to manage IIIMCF operations.
IIIMCF_handle set to phandle
.
attr
specifies the additional attributes which can be
used for creating the handle. Currently effective attributes are the followings.
The corresponding value must be char* string that holds the address of IIIM server.
The corresponding value must be char* string that holds the service name of IIIM server.
The corresponding value must be char* string that holds username.
The corresponding value must be char* string that specifies the client type, which will be sent to IIIMSF as a part of client descriptor.
The corresponding value must be a number, and if it is non-0, the connection owned by the created handle will not be restored automatically. By default, libiiimcf will automatically restore a closed connection if it requires.
IIIMF_status iiimcf_finalize( | handle ) ; |
IIIMCF_handle | handle ; |
iiimcf_destroy_handle
destroys IIIMCF_handle,
handle
. That is, direct service providers to
finish all context, saves any required states like user dictionary or
something else.
IIIMF_status iiimcf_create_context( | handle, | |
attr , | ||
pcontext ) ; |
IIIMCF_handle | handle; |
IIIMCF_attr | attr ; |
IIIMCF_context* | pcontext ; |
iiimcf_create_context
creates input context related
to handle
.
attr
specifies the additional attributes that should be
compliant to a created input context.
Currently effective attributes are the followings.
The corresponding value must be IIIMCF_language. This attribute specifies the input language of required input context.
The corresponding value must be IIIMCF_input_method. This attribute specifies the input method of required input context.
The corresponding value must be a number. By default, IIIMCF library automatically turn the conversion mode on or off when accepting the trigger keys specified by IIIMSF. If this value is non-zero, IIIMCF library does not automatically treat such trigger keys.
IIIMF_status iiimcf_destroy_context( | context ) ; |
IIIMCF_context | context ; |
iiimcf_destroy_context
destroys
context
.
IIIMF_status iiimcf_context_get_attr( | context , | |
pattr ) ; |
IIIMCF_context | context ; |
IIIMCF_attr* | pattr ; |
iiimcf_context_get_attr
gets IIIMCF attribute that is
related to context
. Notice that the returned attribute
is not the same as what is given in iiimcf_create_context
.
This API is used for associating user's arbitrary data with a context. When the
user put values to the attribute, it remembers those values until the context
is destroyed.
IIIMCF has an attribute that holds zero or more of key and value pair(s). Key must be a number and some numbers are reserved by IIIMCF. However, users can freely use the range after IIIMCF_ATTR_PRIVATE_START.
IIIMCF_ATTR_NULL is a special attribute, which has no key and value pair. Use this attribute if you would like to specify no attribute in the argument of IIIMCF API function.
An value of IIIMCF attribute must be a number(int), a constant string(const char*), or a pointer(void*). When putting a value, the slot that has the value remembers what type of value is put, then if you try to get another type of value from the slot, IIIMCF returns IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_create_attr( | pattr) ; |
IIIMCF_attr* | pattr; |
iiimcf_create_attr
creates new IIIMCF attribute,
and set it to pattr.
IIIMF_status iiimcf_destroy_attr( | attr) ; |
IIIMCF_attr | attr; |
iiimcf_destroy_attr
destroys attr
.
IIIMF_status iiimcf_attr_put_string_value( | attr, | |
property, | ||
str) ; |
IIIMCF_attr | attr; |
int | property; |
const char* | str; |
iiimcf_attr_put_string_value
sets str
to property
of attr
as an
attribute value. You can access the value
by iiimcf_attr_get_string_value
. When already put value to
property
, the corresponding slot is overridden, but the type
of slot must be string. If the type is not string, this function returns
IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_attr_get_string_value( | attr, | |
property, | ||
pstr) ; |
IIIMCF_attr | attr; |
int | property; |
const char** | pstr; |
iiimcf_attr_get_string_value
sets the string associated with
property
of attr
to
pstr
. If attr
has no value
corresponds to property
, this function returns
IIIMF_STATUS_NO_ATTR_VALUE.
If the type of the value associated with property
is not
string, this function returns IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_attr_put_integer_value( | attr, | |
property, | ||
number) ; |
IIIMCF_attr | attr; |
int | property; |
int | number; |
iiimcf_attr_put_integer_value
sets number
to property
of attr
as an
attribute value. You can access the value
by iiimcf_attr_get_integer_value
. When already having put
value to property
, the corresponding slot is overridden,
but the type of slot must be integer. If the type is not integer, this function returns
IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_attr_get_integer_value( | attr, | |
property, | ||
pnumber) ; |
IIIMCF_attr | attr; |
int | property; |
int* | pnumber; |
iiimcf_attr_get_integer_value
set the integer associated with
property
of attr
to
pnumber
. If attr
has no value
corresponds to property
, this function returns
IIIMF_STATUS_NO_ATTR_VALUE.
If the type of the value associated with property
is not
integer, this function returns IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_attr_put_ptr_value( | attr, | |
property, | ||
ptr) ; |
IIIMCF_attr | attr; |
int | property; |
void* | ptr; |
iiimcf_attr_put_ptr_value
sets ptr
to property
of attr
as an
attribute value. You can access the value
by iiimcf_attr_get_ptr_value
. When already having put
value to property
, the corresponding slot is overridden,
but the type of slot must be pointer. If the type is not ptr, this function returns
IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_attr_get_ptr_value( | attr, | |
property, | ||
pptr) ; |
IIIMCF_attr | attr; |
int | property; |
void** | pptr; |
iiimcf_attr_get_ptr_value
set the pointer associated with
property
of attr
to
pptr
. If attr
has no value
corresponds to property
, this function returns
IIIMF_STATUS_NO_ATTR_VALUE.
If the type of the value associated with property
is not
pointer, this function returns IIIMF_STATUS_ARGUMENT.
IIIMCF_text is an opaque object that conveys structured text information, i.e., UTF-16 based string, character feedback attribute, and text property value associated with any intervals of the text. You can access them only via the following functions.
IIIMF_status iiimcf_get_text_utf16string( | text, | |
putf16) ; |
IIIMCF_text | text; |
const IIIMP_card16** | putf16; |
iiimcf_get_text_utf16string
set UTF-16 string of
text
to putf16
, which is
terminated by 0.
You MUST NOT change the obtained string in putf16
.
IIIMF_status iiimcf_get_text_length( | text, | |
plen) ; |
IIIMCF_text | text; |
int* | plen; |
iiimcf_get_text_length
set the length in UTF-16 element of
text
to plen
.
IIIMF_status iiimcf_get_char_with_feedback( | text, | |
pos, | ||
pch, | ||
pnum_feedbacks, | ||
pfeedback_id, | ||
pfeedback) ; |
IIIMCF_text | text; |
int | pos; |
IIIMP_card16* | pch; |
int* | pnum_feedbacks; |
const IIIMP_card32** | pfeedback_id; |
const IIIMP_card32** | pfeedback; |
iiimcf_get_char_with_feedback
sets a UTF-16 element
and the corresponding feedbacks in text
.
This function extract a UTF-16 element pch
where
pos
points in the UTF-16 string of
text
.
It also sets feedback information into pfeedback_id
and pfeedback
arrays. The size of both are equal to
*pnum_feedbacks
.
IIIMF_status iiimcf_duplicate_text( | src, | |
pduplicated) ; |
IIIMCF_text | src; |
IIIMCF_text* | pduplicated; |
iiimcf_duplicate_text
duplicates
src
and set it to pduplicated
.
When you don't need the duplicated text, you must destroy it by
iiimcf_destroy_text
in order to release
resources.
IIIMF_status iiimcf_destroy_text( | text) ; |
IIIMCF_text | text; |
iiimcf_destroy_text
destroys text
that must be duplicated by users.
Note that you MUST NOT destroy any texts other than duplicated ones, because such texts are managed by IIIMCF library.
IIIMCF_lookup_choice is an opaque object that conveys lookup choice data, i.e., candidates and their label texts. You can access them only via the following APIs.
IIIMF_status iiimcf_get_lookup_choice_size( | lookup_choice, | |
psize, | ||
pindex_of_first_candidate, | ||
pindex_of_last_candidate, | ||
pindex_of_current_candidate) ; |
IIIMCF_lookup_choice | lookup_choice; |
int* | psize; |
int* | pindex_of_first_candidate; |
int* | pindex_of_last_candidate; |
int* | pindex_of_current_candidate; |
iiimcf_get_lookup_choice_size
sets the number of items
in lookup_choice
to psize
,
the index of the first candidate to pindex_of_first_candidate
,
the index of the last candidate to pindex_of_last_candidate
,
the index of the current candidate to pindex_of_current_candidate
.
IIIMF_status iiimcf_get_lookup_choice_configuration( | lookup_choice, | |
pchoices_per_window, | ||
pnumber_of_rows, | ||
pdirection) ; |
IIIMCF_lookup_choice | lookup_choice; |
int* | pchoices_per_window; |
int* | pnumber_of_rows; |
int* | pdirection; |
iiimcf_get_lookup_choice_configuration
informs
how the lookup choice should be presented. This function sets the number
of choices in one window to pchoices_per_window
,
the number of rows to pnumber_of_rows
,
the number of columns to pnumber_of_columns
,
and the direction in which the lookup choice should be ordered to
pdirection
, which is one of the following:
That means the items should be ordered horizontally.
That means the items should be ordered vertically.
IIIMF_status iiimcf_get_lookup_choice_item( | lookup_choice, | |
idx, | ||
pcandidate, | ||
plabel, | ||
pflag) ; |
IIIMCF_lookup_choice | lookup_choice; |
int | idx; |
IIIMCF_text* | pcandidate; |
IIIMCF_text* | plabel; |
int* | pflag; |
iiimcf_get_lookup_choice_item
retrieves an item in
lookup_choice
. The item is identified by
idx
that ranges from 0 to the size of
lookup_choice
- 1.
This function stores a candidate text into pcandidate
,
a label text into plabel
, and flags of the item into
pflag
.
Currently flag is a combination of the following bits:
If this bit is set, the corresponding item is enabled. "Enabled" means user application must show the item in the lookup choice area. If it is not set, user application must not show the item.
If this bit is set, the corresponding item is now selected.
IIIMF_status iiimcf_get_lookup_choice_title( | lookup_choice, | |
ptitle) ; |
IIIMCF_lookup_choice | lookup_choice; |
IIIMCF_text* | ptitle; |
iiimcf_get_lookup_choice_title
sets the title in
lookup_choice
to ptitle
IIIMCF_language is an opaque object that conveys language information.
IIIMF_status iiimcf_get_language_id( | lang, | |
plangid) ; |
IIIMCF_language | lang; |
char* | plangid; |
iiimcf_get_language_id
gets a language id
registered by RFC1766. This function stored id to
plangid
.
IIIMCF_input_method is an opaque object that conveys input method information.
IIIMF_status iiimcf_get_input_method_desc( | input_method, | |
pinput_method_idname, | ||
pinput_method_hrn, | ||
pinput_method_domain) ; |
IIIMCF_input_method | input_method; |
const IIIMP_card16** | pinput_method_idname; |
const IIIMP_card16** | pinput_method_hrn; |
const IIIMP_card16** | pinput_method_domain; |
iiimcf_get_input_method_desc
gets a description of
input_method
.
This function stores the identifier name of the input method into
pinput_method_idname
,
a human readable name into pinput_method_hrn
,
a reverse domain name into pinput_method_domain
.
IIIMF_status iiimcf_get_input_method_languages( | input_method, | |
pinput_method_language_size, | ||
pplangages) ; |
IIIMCF_input_method | input_method; |
int* | pinput_method_language_size; |
IIIMCF_language** | pplangages; |
iiimcf_get_input_method_languages
gets list of
languages supported by input_method
.
This function stores an array of IIIMCF_language* into
pplanguages, and stores size of the array into
pinput_method_language_size
. That is, you could
access all elements of the array by something like the following code:
{ int i, size; const char *id; IIIMCF_language *plangs; if (iiimcf_get_input_method_languages(input_method, &size, &plangs) == IIIMF_STATUS_SUCCESS) { for (i = 0; i < size; i++) { if (iiimcf_get_language_id(plangs[i], &id) == IIIMF_STATUS_SUCCESS) { ... } ... } } }
IIIMCF supports object downloading, which is encapsulated by an opaque object of IIIMCF_downloaded_object.
IIIMF_status iiimcf_get_downloaded_object( | handle, | |
num_objs, | ||
ppdesc, | ||
pobjs) ; |
IIIMCF_handle | handle; |
int | num_objs; |
const IIIMCF_object_descriptor** | ppdesc; |
IIIMCF_downloaded_object* | pobjs; |
iiimcf_get_downloaded_object
gets downloadable objects from
IIIMSF.
num_objs
is a number of objects that must be equal to
the array length of ppdesc
and pobjs
.
ppdesc
is an array of the pointer of
IIIMCF_object_descriptor, which must consist of the pointers
returned by iiimcf_get_object_descriptor_list
. You MUST NOT
set the pointer of your own IIIMCF_object_descriptor .
If success, this function sets the corresponding IIIMCF_downloaded_object
to the array specified by pobjs
.
IIIMF_status iiimcf_get_downloaded_object_descriptor( | object, | |
ppdesc) ; |
IIIMCF_downloaded_object | object; |
const IIIMCF_object_descriptor** | ppdesc; |
iiimcf_get_downloaded_object_descriptor
gets the object descriptor
of object
, and set it to *ppdesc
.
IIIMF_status iiimcf_get_downloaded_object_filename( | object, | |
pfilename) ; |
IIIMCF_downloaded_object | object; |
const IIIMCF_card16** | pfilename; |
iiimcf_get_downloaded_object_filename
gets the filename
of object
.
Notice that object
must be a BINARYFILE_OBJECT defined
by IIIM Protocol Specification, i.e., it must be
IIIMP_IMATTRIBUTE_BINARY_GUI_OBJECT,
IIIMP_IMATTRIBUTE_BINARY_LIGHT_WEIGHT_ENGINE_OBJECT, or
IIIMP_IMATTRIBUTE_SCRIPT_LIGHT_WEIGHT_ENGINE_OBJECT.
IIIMF_status iiimcf_is_UIstate_changed( | context, | |
pflag) ; |
IIIMCF_context | context; |
int* | pflag; |
iiimcf_is_UIstate_changed
checks if the state of UI in
the current input context, and set the result to pflag
in bitwise pattern.
*pflag
has a combination of the following bits:
This bit is set if the preedit text is changed by the previous event forwarding.
This bit is set if the lookup choice is changed by the previous event forwarding.
This bit is set if the status text [1] is changed by the previous event forwarding.
This bit is set if the input method requires to commit resultant text from the previous event forwarding.
IIIMCF language is an opaque object that conveys version information of the library and protocol.
IIIMF_status iiimcf_get_version_number( | handle, | |
flag, | ||
pversion_number) ; |
IIIMCF_handle | handle; |
int | flag; |
int* | pversion_number; |
iiimcf_get_vesion_number
sets a version number to
*pversion_number
.
flag
specifies an item of which you want
to query the version, and also specifies the category of version
number like `major' or `minor'.
Flags for specifying an item is the followings:
get IIIMCF library version.
get IIIM protocol version currently enabled.
Flags for specifying category of version number:
get the minor part of version. If the entity has no minor
version, iiimcf_get_version_number
returns 0.
get major part of the version.
flag
must be a combination of both two sorts
of flags. If you specify an invalid flag, it will return
IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_get_supported_languages( | handle, | |
pnum_langs, | ||
pplangs) ; |
IIIMCF_handle | handle; |
int* | pnum_langs; |
IIIMCF_language** | pplangs; |
iiimcf_get_supported_languages
retrieves a language
list supported by the current input method service providers.
This function stores the number of languages into pnum_langs
,
and an array of IIIMCF_language* into pplangs
.
IIIMF_status iiimcf_get_supported_input_methods( | handle, | |
pnum_input_methods, | ||
ppinput_methods) ; |
IIIMCF_handle | handle; |
int* | pnum_input_methods; |
IIIMCF_input_method** | ppinput_methods; |
iiimcf_get_supported_input_methods
retrieves an input method
list supported by the current input method service providers.
This function stores the number of input methods into
pnum_input_methods
, and an array of
IIIMCF_input_method* into ppinput_methods
.
IIIMF_status iiimcf_get_object_descriptor_list( | handle, | |
pnum_object_descriptors, | ||
ppdesc) ; |
IIIMCF_handle | handle; |
int* | pnum_object_descriptors; |
const IIIMCF_object_descriptor** | ppdesc; |
iiimcf_get_object_descriptor_list
retrieves a list of object
descriptors. This function stores the number of object descriptors into
pnum_object_descriptors
, and an array of
IIIMCF_object_descriptor* into ppdesc
.
IIIMCF_object_descriptor is defined as follows:
typedef struct { int category; size_t size; int predefined_id; int dynamic_id; const IIIMP_card16 *domain; const IIIMP_card16 *hrn; const IIIMP_card16 *signature; const IIIMP_card16 *user; } IIIMCF_object_descriptor;
Each member corresponds to the item of OBJECTDESCRIPTOR defined by the IIIM protocol specification.
IIIMF_status iiimcf_get_current_conversion_mode( | context, | |
pflag) ; |
IIIMCF_context | context; |
int* | pflag; |
iiimcf_get_current_conversion_mode
get the current
conversion mode of context
.
This function stores non-zero value to *pflag
if the
current conversion mode is on; otherwise, stores zero.
IIIMF_status iiimcf_get_preedit_text( | context, | |
ptext, | ||
pcaret_position) ; |
IIIMCF_context | context; |
IIIMCF_text | ptext; |
int* | pcaret_position; |
iiimcf_get_preedit_text
get the current preedit text
and the current caret position of context
.
This function stores the preedit text into ptext
,
and the caret position into pcaret_position
.
If currently preedit text is not enabled, this function returns IIIMF_STATUS_NO_PREEDIT.
IIIMF_status iiimcf_get_status_text( | context, | |
ptext) ; |
IIIMCF_context | context; |
IIIMCF_text | ptext; |
iiimcf_get_preedit_text
gets the current status text
of context
.
This function stores the status text into ptext
.
If currently status text is not enabled, this function returns IIIMF_STATUS_NO_STATUS_TEXT.
IIIMF_status iiimcf_get_lookup_choice( | context, | |
plookup_choice) ; |
IIIMCF_context | context; |
IIIMCF_lookup_choice | plookup_choice; |
iiimcf_get_lookup_choice
gets the current lookup choice
of context
.
This function stores the lookup choice into plookup_choice
.
If currently lookup choice is not enabled, this function returns IIIMF_STATUS_NO_LOOKUP_CHOICE.
IIIMF_status iiimcf_get_committed_text( | context, | |
ptext) ; |
IIIMCF_context | context; |
IIIMCF_text | ptext; |
iiimcf_get_committed_text
gets the committed text by the
previous event forwarding or operation issuing in the input context specified
by context
.
This function stores the committed text into ptext
.
If currently context
has no valid committed text,
this function returns IIIMF_STATUS_NO_COMMITTED_TEXT.
IIIMF_status iiimcf_get_aux_draw_data( | context, | |
aux_name, | ||
class_idx, | ||
pnum_intvals, | ||
ppintvals, | ||
pnum_strvals, | ||
ppstrs) ; |
IIIMCF_context | context; |
const IIIMP_card16* | aux_name; |
IIIMP_card32 | class_idx; |
int* | pnum_intvals; |
const IIIMP_card32** | ppintvals; |
int* | pnum_strvals; |
const IIIMP_card16*** | ppstrs; |
Get the latest auxiliary data sent from IIIMSF.
iiimcf_get_aux_draw_data
retrieves auxiliary data which is
sent with IM_AUX_DRAW. This function can get only the latest one, i.e., cannot
get the data sent with the two previous IM_AUX_DRAW.
Users have to specify the auxiliary name to aux_name
and the
window class index to class_idx
. If the corresponding IM_AUX_DRAW
is not sent from the server, this function will return IIIMF_STATUS_NO_AUX.
iiimcf_get_aux_draw_data
sets a array of integer values
to ppintvals
, size of the array to
pnum_intvals
, and a array of string values to
ppstrs
, size of the array to
pnum_strvals
.
Because this function returns many values via given pointers, for convenience, users can set NULL to any of pnum_intvals, ppintvals, pnum_strvals, and ppstrs when they don't want to receive data. This function simply ignores to set the data that corresponds to the NULL pointer.
In IIIMCF API, event is used to delegate task(s) to other service providers or component. IIIMCF API has two sorts of event flow, one is forwarding, and the other is dispatching.
Event forwarding is used for sending events to IM service providers. IM service providers will deal with the forwarded event, and return the result as a response.
Event dispatchment is used for sending events to IIIMCF components that are
registered beforehand. IIIMCF component is ordered in tree structure. One
IIIMCF component has sub-components more than 0. We can regard IIIMCF library
as a top level component itself. iiimcf_dispatch_event
sends an event to all of sub-components that the current component has.
IIIMF_status iiimcf_get_event_type( | event, | |
pevent_type) ; |
IIIMCF_event | event; |
IIIMCF_event_type* | pevent_type; |
Each IIIMCF event has its own event type. Currently IIIMCF defines only one event type, but in future, we will append more event types.
It means the event is key event. One key event has 4 integer values, code, character code, modifier, time stamp.
IIIMCF_event_type is defined as a simple C enumerator.
iiimcf_get_event_type
gets the event type of
event
, and set it to pevent_type
.
Users can construct events by the following functions. Users MUST ignore, forward, or dispatch constructed events. IIIMCF event forwarder or dispatcher guarantee to destruct such events after processing the events.
IIIMF_status iiimcf_create_keyevent( | keyevent, | |
pevent) ; |
IIIMCF_keyevent | keyevent; |
IIIMCF_event* | pevent; |
iiimcf_create_keyevent
creates an event whose event type
is IIIMCF_EVENT_TYPE_KEYEVENT, and value is keyevent
.
The generated event is stored to pevent
.
IIIMCF_keyevent is a simple transparent C structure. The definition is:
typedef struct IIIMCF_keyevent { IIIMP_int32 keycode; IIIMP_int32 keychar; IIIMP_int32 modifier; IIIMP_int32 time_stamp; } IIIMCF_keyevent;
[2]
IIIMF_status iiimcf_create_trigger_notify_event( | flag, | |
pevent) ; |
int | flag; |
IIIMCF_event* | pevent; |
iiimcf_create_trigger_notify_event
creates an event of
IIIMCF_EVENT_TYPE_TRIGGER_NOTIFY.
The generated event is stored to pevent
.
Trigger notify event is used to turn the IM on or off. When trigger notify event
is forwarded to the server, the server would turn the IM conversion on if
flag
is 1, turn that off if flag
is 0.
If such event is dispatched to components, they should change the state
to turn the IM conversion on or off.
IIIMF_status iiimcf_create_aux_setvalues_event( | aux_name, | |
class_idx, | ||
num_intvals, | ||
pintvals, | ||
num_strvals, | ||
pstrs, | ||
pevent) ; |
IIIMP_card16* | aux_name; |
IIIMP_card32 | class_idx; |
int | num_intvals; |
const IIIMP_card32* | pintvals; |
int | num_strvals; |
const IIIMP_card16** | pstrs; |
IIIMCF_event* | pevent; |
iiimcf_create_aux_setvalues_event
creates an event of
IIIMCF_EVENT_TYPE_AUX_SETVALUES
.
The generated event is stored to pevent
.
AUX setvalues event is used to transfer the arbitrary information
from client to server. You can forward the created event with
iiimcf_forward_event
.
aux_name
is an auxiliary name.
class_idx
is a window class index.
pintvals
is an array of integer data, and
the array size must be set to num_intvals
.
pstrs
is an array of string(UTF-16) data
that must be terminated by 0, and the array size must be set to
num_strvals
.
Each IIIMCF event has its own value. The value type depends on its IIIMCF_event_type. Users can access values of an event by the following function.
IIIMF_status iiimcf_get_keyevent_value( | event, | |
pkeyevent) ; |
IIIMCF_event | event; |
IIIMCF_keyevent* | pkeyevent; |
iiimcf_get_keyevent_value
get key event value of
event
, and set it to pkeyevent
.
When event
is not
IIIMCF_EVENT_TYPE_KEYEVENT, this function
fails and return IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_get_trigger_notify_flag( | event, | |
pflag) ; |
IIIMCF_event | event; |
int* | pflag; |
iiimcf_get_trigger_notify_flag
gets the boolean flag of
the trigger notify event of event
, and set it to
pflag
.
When event
is not
IIIMCF_EVENT_TYPE_KEYEVENT, this function
fails and return IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_get_aux_event_value( | event, | |
paux_name, | ||
pclass_idx, | ||
pnum_intvals, | ||
ppintvals, | ||
pnum_strvals, | ||
ppstrs) ; |
IIIMCF_event | event; |
const IIIMP_card16** | paux_name; |
IIIMP_card32* | pclass_idx; |
int* | pnum_intvals; |
const IIIMP_card32** | ppintvals; |
int* | pnum_strvals; |
const IIIMP_card16*** | ppstrs; |
iiimcf_get_aux_event_value
gets the value of the
auxiliary event of event
.
This function sets the auxiliary name to paux_name
;
the window class index to pclass_idx
; the integer
array data to ppintvals
and its array size to
pnum_intvals
; and the string array data, each item
string is terminated by 0, to ppstrs
and its array
size to pnum_strvals
.
Because this function returns many values via given pointers, for convenience, users can set NULL to any of paux_name, pclass_idx, pnum_intvals, ppintvals, pnum_strvals, and ppstrs when they don't want to receive data. This function simply ignores to set the data that corresponds to the NULL pointer.
When event
is not a proper auxiliary event,
this function fails and return IIIMF_STATUS_ARGUMENT.
IIIMF_status iiimcf_forward_event( | context, | |
event) ; |
IIIMCF_context | context; |
IIIMCF_event | event; |
iiimcf_forward_event
forwards event
to input method service providers. The forwarded event is processed in
the input context specified by context
.
This function may change the various IM states. So normally, you need to check the state change by checking incoming events or by state checking APIs.
This function returns IIIMF_STATUS_EVENT_NOT_FORWARDED if the forwarded event has not been processed by any service provider(s). If it is, you maybe have to process the event by yourselves.
IIIMF_status iiimcf_dispatch_event( | context, | |
event) ; |
IIIMCF_context | context; |
IIIMCF_event | event; |
iiimcf_dispatch_event
dispatches event
to sub components owned by the current component. This function provides one only
method to invoke sub components.
IIIMF_status iiimcf_get_next_event( | context, | |
pevent) ; |
IIIMCF_context | context; |
IIIMCF_event* | pevent; |
iiimcf_get_next_event
retrieves the first new event,
and delete it from the queue. This function set the new event to
pevent
. context
identifies
the current input context and the current component. Note that this function
does NOT wait for a next event. If there are no incoming events, this function
immediately returns IIIMF_STATUS_NO_EVENT.
Note that you MUST ignore, dispatch, or forward the obtained event when you don't refer it afterwards.
IIIMF_status iiimcf_peek_next_event( | context, | |
pevent) ; |
IIIMCF_context | context; |
IIIMCF_event* | pevent; |
iiimcf_peek_next_event
retrieves the first new event,
but do NOT delete it from the queue. Other features are the same with
iiimcf_get_next_event
.
Note that you don't have to ignore, dispatch, or forward the peeked event.
IIIMF_status iiimcf_ignore_event( | event) ; |
IIIMCF_event | event; |
iiimcf_ignore_event
ignores event
.
After it, you cannot access event
any longer.
Currently IIIMCF_component consists of one name, one function pointer, one parental component, and attributes of IIIMCF_attr.
Component name must be an identifier. In other word, you cannot register two components in the same address.
As stated earlier, IIIMCF component is ordered in tree structure. Thus if you would like to register your own component, you have to specify the parent component.
IIIMF_status iiimcf_register_component( | name, | |
interface, | ||
parent, | ||
pcomp) ; |
const char* | name; |
IIIMCF_component_interface | interface; |
IIIMCF_component | parent; |
IIIMCF_component* | pcomp; |
iiimcf_register_component
registers user's component.
name
must be a unique identifier for the component.
interface
must be a function pointer. The function
prototype is the following:
typedef IIIMF_status (*IIIMCF_component_interface)(IIIMCF_context context, IIIMCF_event event, IIIMCF_component current, IIIMCF_component parent);
parent
must be a parental component. If it is
IIIMCF_ROOT_COMPONENT, IIIMCF library itself become a parent of
the created component.
This function stores the created component to pcomp
.
If name
has already been registered,
this function returns IIIMF_STATUS_COMPONENT_DUPLICATED_NAME.
The registered component will be invoked via interface
with four arguments. event
has the event currently processed
by the dispatchment. context
has the current input context.
current
has the invoked component itself.
parent
has the parental component.
This handler must return IIIMF_STATUS_SUCCESS if it can
successfully process the task. If it fails to process the task, the handler
should return IIIMF_STATUS_COMPONENT_FAIL. Otherwise,
it must return IIIMF_STATUS_COMPONENT_INDIFFERENT.
This function returns IIIMF_STATUS_COMPONENT_FAIL if any of the component returns IIIMF_STATUS_COMPONENT_FAIL. Meanwhile, this function returns IIIMF_STATUS_COMPONENT_INDIFFERENT if the current component has no subcomponent or all of the subcomponent returns IIIMF_STATUS_COMPONENT_INDIFFERENT.
IIIMF_status iiimcf_unregister_component( | component) ; |
IIIMCF_component | component; |
iiimcf_unregister_component
unregisters
component
.
IIIMF_status iiimcf_get_component( | name, | |
pcomponent) ; |
const char* | name; |
IIIMCF_component* | pcomponent; |
iiimcf_get_component
look up registered component by
name
.
If this function fail to find out a component named name
,
returns IIIMF_NO_COMPONENT.
IIIMF_status iiimcf_component_get_attr( | component, | |
pattr) ; |
IIIMCF_component | component; |
IIIMCF_attr* | pattr; |
iiimcf_component_get_attr
get the attributes of
IIIMCF_attr associated with the component,
component
. This function stores the attributes to
pattr
.
Note that users can edit component attribute in order to store users' private data.
This type of event will be broadcasted to all components whenever a context is being destroyed, and it has no value.
This type of event will be sent to components whenever they have to be reset their internal states associated with the context where being sent the event. This type of event is broadcasted to all of the components if the connection is shut down. For detail, refer to the section called “ connection shutdown ”.
This type of event has a keyevent value, which can be obtained with
iiimcf_get_keyevent_value
. It is often used
to forward a key event to or receive one from IM
service provider(s).
This type of event has a flag to specify the conversion mode, which is
obtained with iiimcf_get_trigger_notify_flag
.
It is often used to forward a trigger notify to or receive one from IM
service provider(s).
This type of event is used to notify a component to show the preedit text. It has no event value.
This type of event is used to notify a component to update the preedit text because that have been changed by IM service provider(s). This type of event has no event value.
This type of event is used to notify a component to hide or turn off the preedit text. It has no event value.
This type of event is used to notify a component to show lookup choice information. It has no event value.
This type of event is used to notify a component to update the lookup choice information because that have been changed by IM service provider(s). This type of event has no event value.
This type of event is used to notify a component to hide or turn off the lookup choice presentation. It has no event value.
This type of event is used to notify a component to show status information. It has no event value.
This type of event is used to notify a component to update the status information because that have been changed by IM service provider(s). This type of event has no event value.
This type of event is used to notify a component to hide or turn off the status presentation. It has no event value.
This type of event is used to notify a component to commit a new text sent from IM service provider(s). It has no event value.
This type of event is used to notify a auxiliary object to show the its own
presentation. It has a auxiliary name and a window class index, which are
obtained by iiimcf_get_aux_event_value
.
This type of event is used to notify a auxiliary object to show the its own
presentation. It has a auxiliary name, a window class index, an integer list,
and a string list, which are obtained by
iiimcf_get_aux_event_value
.
This type of event is used to send private data of an auxiliary object
to IM service provider(s) with iiimcf_forward_event
.
It has a auxiliary name, a window class index, an integer list,
and a string list, which are obtained by
iiimcf_get_aux_event_value
, and this type of event
can be constructed with iiimcf_create_aux_setvalues_event
.
This type of event is used to notify a auxiliary object to hide or turn off
the its own presentation. It has a auxiliary name and a window class index,
which are obtained by iiimcf_get_aux_event_value
.