Api for input method.
API for Input method.
An input method is an object to enable inputting various characters. An input method is identified by a pair of symbols, LANGUAGE and NAME. This pair decides an input method driver of the input method. An input method driver is a set of functions for handling the input method. There are two kinds of input methods; internal one and foreign one.
Internal Input Method
An internal input method has non Mnil LANGUAGE, and its body is defined in the m17n database by the tag <Minput_method, LANGUAGE, NAME>. For this kind of input methods, the m17n library uses two predefined input method drivers, one for CUI use and the other for GUI use. Those drivers utilize the input processing engine provided by the m17n library itself. The m17n database may provide input methods that are not limited to a specific language. The database uses Mt as LANGUAGE of those input methods.
An internal input method accepts an input key which is a symbol associated with an input event. As there is no way for the m17n library to know how input events are represented in an application program, an application programmer has to convert an input event to an input key by himself. See the documentation of the function minput_event_to_key() for the detail.
Foreign Input Method
A foreign input method has Mnil LANGUAGE, and its body is defined in an external resource (e.g. XIM of X Window System). For this kind of input methods, the symbol NAME must have a property of key Minput_driver, and the value must be a pointer to an input method driver. Therefore, by preparing a proper driver, any kind of input method can be treated in the framework of the m17n library.
For convenience, the m17n-X library provides an input method driver that enables the input style of OverTheSpot for XIM, and stores Minput_driver property of the symbol Mxim with a pointer to the driver. See the documentation of m17n GUI API for the detail.
PROCESSING FLOW
The typical processing flow of handling an input method is:
open an input method
create an input context for the input method
filter an input key
look up a produced text in the input context
FIELD DOCUMENTATION:
int(* MInputDriver::open_im)(MInputMethod *im)
Open an input method. This function opens the input method im. It is called from the function minput_open_im() after all member of im but <info> set. If opening im succeeds, it returns 0. Otherwise, it returns -1. The function can setup im->info to keep various information that is referred by the other driver functions.
void(* MInputDriver::close_im)(MInputMethod *im)
Close an input method. This function closes the input method im. It is called from the function minput_close_im(). It frees all memory allocated for im->info (if any) after finishing all the tasks of closing the input method. But, the other members of im should not be touched.
int(* MInputDriver::create_ic)(MInputContext *ic)
Create an input context. This function creates the input context ic. It is called from the function minput_create_ic() after all members of ic but <info> are set. If creating ic succeeds, it returns 0. Otherwise, it returns -1. The function can setup ic->info to keep various information that is referred by the other driver functions.
void(* MInputDriver::destroy_ic)(MInputContext *ic)
Destroy an input context. This function is called from the function minput_destroy_ic() and destroys the input context ic. It frees all memory allocated for ic->info (if any) after finishing all the tasks of destroying the input method. But, the other members of ic should not be touched.
int(* MInputDriver::filter)(MInputContext *ic, MSymbol key, void *arg)
Filter an input key. This function is called from the function minput_filter() and filters an input key. key and arg are the same as what given to minput_filter().
The task of the function is to handle key, update the internal state of ic. If key is absorbed by the input method and no text is produced, it returns 1. Otherwise, it returns 0.
It may update ic->status, ic->preedit, ic->cursor_pos, ic->ncandidates, ic->candidates, and ic->produced if that is necessary for the member <callback>.
The meaning of arg depends on the input method river. See the documentation of minput_default_driver and minput_gui_driver for instance.
int(* MInputDriver::lookup)(MInputContext *ic, MSymbol key, void *arg, MText *mt)
Lookup a produced text in an input context. It is called from the function minput_lookup() and looks up a produced text in the input context ic. This function concatenate a text produced by the input key key (if any) to M-text mt. If key was correctly handled by the input method of ic, it returns 0. Otherwise, it returns 1.
The meaning of arg depends on the input method driver. See the documentation of minput_default_driver and minput_gui_driver for instance.
MPlist* MInputDriver::callback_list
List of callback functions. List of callback functions. Keys are one of Minput_preedit_start, Minput_preedit_draw, Minput_preedit_done, Minput_status_start, Minput_status_draw, Minput_status_done, Minput_candidates_start, Minput_candidates_draw, Minput_candidates_done, Minput_set_spot, Minput_toggle, Minput_reset, Minput_get_surrounding_text, Minput_delete_surrounding_text. Values are functions of type MInputCallbackFunc.
FIELD DOCUMENTATION:
MSymbol MInputMethod::language
MSymbol MInputMethod::name
MInputDriver MInputMethod::driver
void* MInputMethod::arg
void* MInputMethod::info
FIELD DOCUMENTATION:
MInputMethod* MInputContext::im
MText* MInputContext::produced
void* MInputContext::arg
int MInputContext::active
int MInputContext::x
int MInputContext::y
int MInputContext::ascent
int MInputContext::descent
int MInputContext::fontsize
MText* MInputContext::mt
int MInputContext::pos
struct { ... } MInputContext::spot
void* MInputContext::info
MText* MInputContext::status
int MInputContext::status_changed
MText* MInputContext::preedit
int MInputContext::preedit_changed
int MInputContext::cursor_pos
int MInputContext::cursor_pos_changed
MPlist* MInputContext::candidate_list
int MInputContext::candidate_index
int MInputContext::candidate_from
int MInputContext::candidate_to
int MInputContext::candidate_show
int MInputContext::candidates_changed
MPlist* MInputContext::plist
Type of input method callback functions. This is the type of callback functions called from input method drivers. ic is a pointer to an input context, command is a name of callback for which the function is called.
Bit-masks to specify how candidates of input method is changed.
Enumerator:
MINPUT_CANDIDATES_LIST_CHANGED
MINPUT_CANDIDATES_INDEX_CHANGED
MINPUT_CANDIDATES_SHOW_CHANGED
MINPUT_CANDIDATES_CHANGED_MAX
Symbol whose name is 'input-method'.
The default driver for internal input methods. The variable minput_default_driver is the default driver for internal input methods.
The member MInputDriver::open_im() searches the m17n database for an input method that matches the tag < Minput_method, language, name> and loads it.
The member MInputDriver::callback_list() is NULL. Thus, it is programmers responsibility to set it to a plist of proper callback functions. Otherwise, no feedback information (e.g. preedit text) can be shown to users.
The macro M17N_INIT() sets the variable minput_driver to the pointer to this driver so that all internal input methods use it.
Therefore, unless minput_driver is set differently, the driver dependent arguments arg of the functions whose name begins with 'minput_' are all ignored.
The driver for internal input methods. The variable minput_driver is a pointer to the input method driver that is used by internal input methods. The macro M17N_INIT() initializes it to a pointer to minput_default_driver if <m17n.h> is included.
Generated automatically by Doxygen for The m17n Library from the source code.
Get a list of variables of an input method (obsolete). This function is obsolete. Use minput_get_variable() instead.
The minput_get_variables() function returns a plist (MPlist) of variables used to control the behavior of the input method specified by language and name. The plist is well-formed (Property List) of the following format:
(VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
...)
VARNAME is a symbol representing the variable name.
DOC-MTEXT is an M-text describing the variable.
DEFAULT-VALUE is the default value of the variable. It is a symbol, integer, or M-text.
VALUEs (if any) specifies the possible values of the variable. If DEFAULT-VALUE is an integer, VALUE may be a plist (FROM TO), where FROM and TO specifies a range of possible values.
For instance, suppose an input method has the variables:
name:intvar, description:'value is an integer', initial value:0, value-range:0..3,10,20
name:symvar, description:'value is a symbol', initial value:nil, value-range:a, b, c, nil
name:txtvar, description:'value is an M-text', initial value:empty text, no value-range (i.e. any text)
Then, the returned plist is as follows.
(intvar ("value is an integer" 0 (0 3) 10 20)
symvar ("value is a symbol" nil a b c nil)
txtvar ("value is an M-text" ""))
RETURN VALUE
If the input method uses any variables, a pointer to MPlist is returned. As the plist is kept in the library, the caller must not modify nor free it. If the input method does not use any variable, NULL is returned.
Set the initial value of an input method variable. The minput_set_variable() function sets the initial value of input method variable variable to value for the input method specified by language and name.
By default, the initial value is 0.
This setting gets effective in a newly opened input method.
RETURN VALUE
If the operation was successful, 0 is returned. Otherwise -1 is returned, and merror_code is set to MERROR_IM.
Get information about input method commands. The minput_get_commands() function returns information about input method commands of the input method specified by language and name. An input method command is a pseudo key event to which one or more actual input key sequences are assigned.
There are two kinds of commands, global and local. Global commands are used by multiple input methods for the same purpose, and have global key assignments. Local commands are used only by a specific input method, and have only local key assignments.
Each input method may locally change key assignments for global commands. The global key assignment for a global command is effective only when the current input method does not have local key assignments for that command.
If name is Mnil, information about global commands is returned. In this case language is ignored.
If name is not Mnil, information about those commands that have local key assignments in the input method specified by language and name is returned.
RETURN VALUE
If no input method commands are found, this function returns NULL.
Otherwise, a pointer to a plist is returned. The key of each element in the plist is a symbol representing a command, and the value is a plist of the form COMMAND-INFO described below.
The first element of COMMAND-INFO has the key Mtext, and the value is an M-text describing the command.
If there are no more elements, that means no key sequences are assigned to the command. Otherwise, each of the remaining elements has the key Mplist, and the value is a plist whose keys are Msymbol and values are symbols representing input keys, which are currently assigned to the command.
As the returned plist is kept in the library, the caller must not modify nor free it.
Assign a key sequence to an input method command (obsolete). This function is obsolete. Use minput_config_command() instead.
The minput_assign_command_keys() function assigns input key sequence keyseq to input method command command for the input method specified by language and name. If name is Mnil, the key sequence is assigned globally no matter what language is. Otherwise the key sequence is assigned locally.
Each element of keyseq must have the key msymbol and the value must be a symbol representing an input key.
keyseq may be NULL, in which case, all assignments are deleted globally or locally.
This assignment gets effective in a newly opened input method.
RETURN VALUE
If the operation was successful, 0 is returned. Otherwise -1 is returned, and merror_code is set to MERROR_IM.
Call a callback function. The minput_callback() functions calls a callback function command assigned for the input context ic. The caller must set specific elements in ic->plist if the callback function requires.
RETURN VALUE
If there exists a specified callback function, 0 is returned. Otherwise -1 is returned. By side effects, ic->plist may be modified.
Copyright (C) 2001 Information-technology Promotion Agency (IPA)
Copyright (C) 2001-2011 National Institute of Advanced Industrial Science and Technology (AIST)
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License <http://www.gnu.org/licenses/fdl.html>.