Main Page   Modules   Data Structures   Globals   Appendix  

Input Method (basic)
[SHELL API]

API for Input method. More...

Data Structures

struct  MInputDriver
 Structure of input method driver. More...
struct  MInputMethod
 Structure of input method. More...
struct  MInputContext
 Structure of input context. More...

Variables: Predefined symbols for callback commands.

These are the predefined symbols that are used as the COMMAND argument of callback functions of an input method driver (see MInputDriver::callback_list ).

MSymbol Minput_preedit_start
MSymbol Minput_preedit_done
MSymbol Minput_preedit_draw
MSymbol Minput_status_start
MSymbol Minput_status_done
MSymbol Minput_status_draw
MSymbol Minput_candidates_start
MSymbol Minput_candidates_done
MSymbol Minput_candidates_draw
MSymbol Minput_set_spot
MSymbol Minput_toggle
MSymbol Minput_reset

Typedefs

typedef MInputMethod MInputMethod
typedef MInputContext MInputContext
typedef void(* MInputCallbackFunc )(MInputContext *ic, MSymbol command)
 Type of input method callback functions.
typedef MInputDriver MInputDriver
 Structure of input method driver.

Functions

MInputMethodminput_open_im (MSymbol language, MSymbol name, void *arg)
 Open an input method.
void minput_close_im (MInputMethod *im)
 Close an input method.
MInputContextminput_create_ic (MInputMethod *im, void *arg)
 Create an input context.
void minput_destroy_ic (MInputContext *ic)
 Destroy an input context.
int minput_filter (MInputContext *ic, MSymbol key, void *arg)
 Filter an input key.
int minput_lookup (MInputContext *ic, MSymbol key, void *arg, MText *mt)
 Lookup a text produced in the input context.
void minput_set_spot (MInputContext *ic, int x, int y, int ascent, int descent, int fontsize, MText *mt, int pos)
 Set the spot of the input context.
void minput_toggle (MInputContext *ic)
 Toggle input method.
void minput_reset_ic (MInputContext *ic)
 Reset an input context.

Variables

MInputDriver minput_default_driver
 The default driver for internal input methods.
MSymbol Minput_driver
MInputDriverminput_driver
 The driver for internal input methods.
MSymbol Minput_preedit_start
MSymbol Minput_preedit_draw
MSymbol Minput_preedit_done
MSymbol Minput_status_start
MSymbol Minput_status_draw
MSymbol Minput_status_done
MSymbol Minput_candidates_start
MSymbol Minput_candidates_draw
MSymbol Minput_candidates_done
MSymbol Minput_set_spot
MSymbol Minput_toggle
MSymbol Minput_reset
MInputDriver minput_default_driver
 The default driver for internal input methods.
MInputDriverminput_driver
 The driver for internal input methods.
MSymbol Minput_driver

Detailed Description

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

PROCESSING FLOW

The typical processing flow of handling an input method is:


Typedef Documentation

typedef struct MInputMethod MInputMethod
 

typedef struct MInputContext MInputContext
 

typedef void(* MInputCallbackFunc)(MInputContext *ic, MSymbol command)
 

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.

typedef struct MInputDriver MInputDriver
 

The type MInputDriver is the structure of an input method driver that contains several functions to handle an input method.


Function Documentation

MInputMethod * minput_open_im MSymbol  language,
MSymbol  name,
void *  arg
 

The minput_open_im() function opens an input method that matches language language and name name, and returns a pointer to the input method object newly allocated.

This function at first decides an driver for the input method as below.

If language is not Mnil, the driver pointed by the variable minput_driver is used.

If language is Mnil and name has Minput_driver property, the driver pointed to by the property value is used to open the input method. If name has no such property, NULL is returned.

Then, the member MInputDriver::open_im() of the driver is called.

arg is set in the member arg of the structure MInputMethod so that the driver can refer to it.

void minput_close_im MInputMethod im  ) 
 

The minput_close_im() function closes the input method im, which must have been created by minput_open_im().

MInputContext * minput_create_ic MInputMethod im,
void *  arg
 

The minput_create_ic() function creates an input context object associated with input method im, and calls callback functions corresponding to Minput_preedit_start, Minput_status_start, and Minput_status_draw in this order.

Return value:
If an input context is successfully created, minput_create_ic() returns a pointer to it. Otherwise it returns NULL.

void minput_destroy_ic MInputContext ic  ) 
 

The minput_destroy_ic() function destroys the input context ic, which must have been created by minput_create_ic(). It calls callback functions corresponding to Minput_preedit_done, Minput_status_done, and Minput_candidates_done in this order.

int minput_filter MInputContext ic,
MSymbol  key,
void *  arg
 

The minput_filter() function filters input key key according to input context ic, and calls callback functions corresponding to Minput_preedit_draw, Minput_status_draw, and Minput_candidates_draw if the preedit text, the status, and the current candidate are changed respectively.

Return value:
If key is filtered out, this function returns 1. In that case, the caller should discard the key. Otherwise, it returns 0, and the caller should handle the key, for instance, by calling the function minput_lookup() with the same key.

int minput_lookup MInputContext ic,
MSymbol  key,
void *  arg,
MText mt
 

The minput_lookup() function looks up a text in the input context ic. key must be the same one provided to the previous call of minput_filter().

If a text was produced by the input method, it is concatenated to M-text mt.

This function calls MInputDriver::lookup .

Return value:
If key was correctly handled by the input method, this function returns 0. Otherwise, returns -1, even in that case, some text may be produced in mt.

void minput_set_spot MInputContext ic,
int  x,
int  y,
int  ascent,
int  descent,
int  fontsize,
MText mt,
int  pos
 

The minput_set_spot() function set the spot of input context ic to coordinate (x, y ) with the height ascent and descent . The semantics of these values depend on the input method driver. fontsize specfies the fontsize of a preedit text in 1/10 point.

For instance, an driver designed to work in CUI environment may use x and y as column and row numbers, and ignore ascent and descent . An driver designed to work on a window system may treat x and y as pixel offsets relative to the origin of the client window, and treat ascent and descent as ascent and descent pixels of a line at (x . y ).

mt and pos is an M-text and a character position at the spot. mt may be NULL, in which case, the input method cannot get information about the text around the spot.

void minput_toggle MInputContext ic  ) 
 

The minput_toggle() function toggles the input method associated with the input context ic.

void minput_reset_ic MInputContext ic  ) 
 

The minput_reset_ic() function resets the input context ic by calling a callback functions corresponding to Minput_reset. It actually shifts the state to the initial one, and thus the current preediting text (if any) is committed. If necessary, a program can extract that text by calling minput_lookup() just after the call of minput_reset_ic(). In that case, the arguments KEY and ARG of minput_lookup() are ignored.


Variable Documentation

MInputDriver minput_default_driver
 

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 begin with "minput_" are all ignored.

MSymbol Minput_driver
 

MInputDriver* minput_driver
 

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) or to minput_gui_driver (if <m17n-gui.h> is included).

MSymbol Minput_preedit_start
 

MSymbol Minput_preedit_draw
 

MSymbol Minput_preedit_done
 

MSymbol Minput_status_start
 

MSymbol Minput_status_draw
 

MSymbol Minput_status_done
 

MSymbol Minput_candidates_start
 

MSymbol Minput_candidates_draw
 

MSymbol Minput_candidates_done
 

MSymbol Minput_set_spot
 

MSymbol Minput_toggle
 

MSymbol Minput_reset
 

MSymbol Minput_preedit_start
 

MSymbol Minput_preedit_done
 

MSymbol Minput_preedit_draw
 

MSymbol Minput_status_start
 

MSymbol Minput_status_done
 

MSymbol Minput_status_draw
 

MSymbol Minput_candidates_start
 

MSymbol Minput_candidates_done
 

MSymbol Minput_candidates_draw
 

MSymbol Minput_set_spot
 

MSymbol Minput_toggle
 

MSymbol Minput_reset
 

MInputDriver minput_default_driver
 

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 begin with "minput_" are all ignored.

MInputDriver* minput_driver
 

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) or to minput_gui_driver (if <m17n-gui.h> is included).

MSymbol Minput_driver
 


Top of this page

Main Page   Modules   Data Structures   Globals   Appendix  

mulemark mule-aist@m17n.org