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

Most of them don't require extra argument nor return any value; exceptions are these:

Minput_get_surrounding_text: When a callback function assigned for this command is called, the first element of MInputContext::plist has key Minteger and the value specifies which portion of the surrounding text should be retrieved. If the value is positive, it specifies the number of characters following the current cursor position. If the value is negative, the absolute value specifies the number of characters preceding the current cursor position.

If the surrounding text is currently supported, the callback function must set the key of this element to Mtext and the value to the retrieved M-text. The length of the M-text may be shorter than the requested number of characters, if the available text is not that long. The length can be zero in the worst case. Or, the length may be longer if an application thinks it's more efficient to return that length).

If the surrounding text is not currently supported, the callback function should return without changing the first element of MInputContext::plist.

Minput_delete_surrounding_text: When a callback function assigned for this command is called, the first element of MInputContext::plist has key Minteger and the value specifies which portion of the surrounding text should be deleted in the same way as the case of Minput_get_surrounding_text. The callback function must delete the specified text. It should not alter MInputContext::plist.

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
MSymbol Minput_get_surrounding_text
MSymbol Minput_delete_surrounding_text

Variables: Predefined symbols for special input events.

These are the predefined symbols that are used as the KEY argument of minput_filter().

MSymbol Minput_focus_out
MSymbol Minput_focus_in
MSymbol Minput_focus_move

Variables: Predefined symbols used in input method information.

These are the predefined symbols describing status of input method command and variable, and are used in a return value of minput_get_command() and minput_get_variable().

MSymbol Minherited
MSymbol Mcustomized
MSymbol Mconfigured

Typedefs

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

Enumerations

enum  MInputCandidatesChanged {
  MINPUT_CANDIDATES_LIST_CHANGED = 1,
  MINPUT_CANDIDATES_INDEX_CHANGED = 2,
  MINPUT_CANDIDATES_SHOW_CHANGED = 4,
  MINPUT_CANDIDATES_CHANGED_MAX
}
 Bit-masks to specify how candidates of input method is changed. More...

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)
 Look up 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.
MTextminput_get_description (MSymbol language, MSymbol name)
 Get description text of an input method.
MPlistminput_get_title_icon (MSymbol language, MSymbol name)
 Get title and icon filename of an input method.
MPlistminput_get_command (MSymbol language, MSymbol name, MSymbol command)
 Get information about input method command(s).
int minput_config_command (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseq)
MPlistminput_get_variable (MSymbol language, MSymbol name, MSymbol variable)
int minput_config_variable (MSymbol language, MSymbol name, MSymbol variable, MPlist *value)
int minput_save_config (void)
MPlistminput_get_commands (MSymbol language, MSymbol name)
int minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist *keys)
MPlistminput_get_variables (MSymbol language, MSymbol name)
int minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void *value)

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
MSymbol Minput_get_surrounding_text
MSymbol Minput_delete_surrounding_text
MSymbol Minput_focus_move
MSymbol Minput_focus_in
MSymbol Minput_focus_out
MSymbol Minherited
MSymbol Mcustomized
MSymbol Mconfigured
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 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.

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.


Enumeration Type Documentation

enum MInputCandidatesChanged

Enumerator:
MINPUT_CANDIDATES_LIST_CHANGED 
MINPUT_CANDIDATES_INDEX_CHANGED 
MINPUT_CANDIDATES_SHOW_CHANGED 
MINPUT_CANDIDATES_CHANGED_MAX 


Function Documentation

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

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

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

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

If language is Mnil and name has the property Minput_driver, the driver pointed to by the property value is used to open the input method. If name has no such a 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.

To make the input method commit the current preedit text (if any) and shift to the initial state, call this function with Mnil as key.

To inform the input method about the focus-out event, call this function with Minput_focus_out as key.

To inform the input method about the focus-in event, call this function with Minput_focus_in as key.

To inform the input method about the focus-move event (i.e. input spot change within the same input context), call this function with Minput_focus_move as key.

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 identical to the one that was used in 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, it returns -1, even though some text might 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 sets the spot of input context ic to coordinate (x, y ) with the height specified by ascent and descent . The semantics of these values depends on the input method driver.

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

fontsize specifies the fontsize of preedit text in 1/10 point.

mt and pos are the M-text and the 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 input context ic.

void minput_reset_ic ( MInputContext ic  ) 

The minput_reset_ic() function resets input context ic by calling a callback function corresponding to Minput_reset. It resets the status of ic to its initial one. As the current preedit text is deleted without commitment, if necessary, call minput_filter() with the arg key Mnil to force the input method to commit the preedit in advance.

MText * minput_get_description ( MSymbol  language,
MSymbol  name 
)

The minput_get_description() function returns an M-text that describes the input method specified by language and name.

Return value:
If the specified input method has a description text, a pointer to MText is returned. The caller has to free it by m17n_object_unref(). If the input method does not have a description text, NULL is returned.

MPlist * minput_get_title_icon ( MSymbol  language,
MSymbol  name 
)

The minput_get_title_icon() function returns a plist containing a title and icon filename (if any) of an input method specified by language and name.

The first element of the plist has key Mtext and the value is an M-text of the title for identifying the input method. The second element (if any) has key Mtext and the value is an M-text of the icon image (absolute) filename for the same purpose.

Return value:
If there exists a specified input method and it defines an title, a plist is returned. Otherwise, NULL is returned. The caller must free the plist by m17n_object_unref().

MPlist * minput_get_command ( MSymbol  language,
MSymbol  name,
MSymbol  command 
)

The minput_get_command() function returns information about command 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. A global command has a global definition, and the description and the key assignment may be inherited by a local command. Each input method defines a local command which has local key assignment. It may also declares a local command that inherits definition of a global command of the same name.

If language is Mt and name is Mnil, information about a global command is returned. Othewise information about a local command is returned.

If command is Mnil, information about all commands is returned.

The return value is a well-formed plist (m17nPlist) of this format:

  ((NAME DESCRIPTION STATUS [KEYSEQ ...]) ...)
NAME is a symbol representing the command name.

DESCRIPTION is an M-text describing the command, or Mnil if the command has no description.

STATUS is a symbol representing how the key assignment is decided. The value is Mnil (the default key assignment), Mcustomized (the key assignment is set by per-user customization file), or Mconfigured (the key assignment is set by the call of minput_config_command()). For a local command only, it may also be Minherited (the key assignment is inherited from the corresponding global command).

KEYSEQ is a plist of one or more symbols representing a key sequence assigned to the command. If there's no KEYSEQ, the command is currently disabled (i.e. no key sequence can trigger actions of the command).

If command is not Mnil, the first element of the returned plist contains the information about command.

Return value:
If the requested information was found, a pointer to a non-empty plist is returned. As the plist is kept in the library, the caller must not modify nor free it.

Otherwide (the specified input method or the specified command doesn't exist), NULL is returned.

Example:
MText *
get_im_command_description (MSymbol language, MSymbol name, MSymbol command)
{
  /* Return a description of the command COMMAND of the input method */
  /* specified by LANGUAGE and NAME.  */
  MPlist *cmd = minput_get_command (langauge, name, command);
  MPlist *plist;

  if (! cmds)
    return NULL;
  plist = mplist_value (cmds);  /* (NAME DESCRIPTION KEY-SEQ ...) */
  plist = mplist_next (plist);  /* (DESCRIPTION KEY-SEQ ...) */
  return  (mplist_key (plist) == Mtext
           ? (MText *) mplist_value (plist)
           : NULL);
}

int minput_config_command ( MSymbol  language,
MSymbol  name,
MSymbol  command,
MPlist keyseq 
)

MPlist* minput_get_variable ( MSymbol  language,
MSymbol  name,
MSymbol  variable 
)

int minput_config_variable ( MSymbol  language,
MSymbol  name,
MSymbol  variable,
MPlist value 
)

int minput_save_config ( void   ) 

MPlist* minput_get_commands ( MSymbol  language,
MSymbol  name 
)

int minput_assign_command_keys ( MSymbol  language,
MSymbol  name,
MSymbol  command,
MPlist keys 
)

MPlist* minput_get_variables ( MSymbol  language,
MSymbol  name 
)

int minput_set_variable ( MSymbol  language,
MSymbol  name,
MSymbol  variable,
void *  value 
)


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

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_get_surrounding_text

MSymbol Minput_delete_surrounding_text

MSymbol Minput_focus_move

MSymbol Minput_focus_in

MSymbol Minput_focus_out

MSymbol Minherited

MSymbol Mcustomized

MSymbol Mconfigured

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

MSymbol Minput_get_surrounding_text

MSymbol Minput_delete_surrounding_text

MSymbol Minput_focus_out

MSymbol Minput_focus_in

MSymbol Minput_focus_move

MSymbol Minherited

MSymbol Mcustomized

MSymbol Mconfigured

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

MSymbol Minput_driver


Top of this page

Main Page   Modules   Data Structures   Globals   Appendix  

mulemark