Input Method (basic)
SHELL API

API for Input method. More...

Collaboration diagram for Input Method (basic):

## Data Structures

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

## Typedefs

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

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

## Variables

MSymbol | Minput_method
| Symbol whose name is "input-method". More...
MInputDriver | minput_default_driver
| The default driver for internal input methods. More...
MInputDriver * | minput_driver
| The driver for internal input methods. More...
MSymbol | Minput_driver

## Variables: Predefined symbols for callback commands. <br>

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 do not 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 value is zero, it means that the caller just wants to know if the surrounding text is currently supported or not.

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 is 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. <br>

MSymbol | Minherited
MSymbol | Mcustomized
MSymbol | Mconfigured

## Functions

MInputMethod * | minput_open_im (MSymbol language, MSymbol name, void *arg)
| Open an input method. More...
void | minput_close_im (MInputMethod *im)
| Close an input method. More...
MInputContext * | minput_create_ic (MInputMethod *im, void *arg)
| Create an input context. More...
void | minput_destroy_ic (MInputContext *ic)
| Destroy an input context. More...
int | minput_filter (MInputContext *ic, MSymbol key, void *arg)
| Filter an input key. More...
int | minput_lookup (MInputContext *ic, MSymbol key, void *arg, MText *mt)
| Look up a text produced in the input context. More...
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. More...
void | minput_toggle (MInputContext *ic)
| Toggle input method. More...
void | minput_reset_ic (MInputContext *ic)
| Reset an input context. More...
MPlist * | minput_get_title_icon (MSymbol language, MSymbol name)
| Get title and icon filename of an input method. More...
MText * | minput_get_description (MSymbol language, MSymbol name)
| Get description text of an input method. More...
MPlist * | minput_get_command (MSymbol language, MSymbol name, MSymbol command)
int | minput_config_command (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseqlist)
MPlist * | minput_get_variable (MSymbol language, MSymbol name, MSymbol variable)
int | minput_config_variable (MSymbol language, MSymbol name, MSymbol variable, MPlist *value)
| Configure the value of an input method variable. More...
char * | minput_config_file ()
| Get the name of per-user customization file. More...
int | minput_save_config (void)
| Save configurations in per-user customization file. More...
MPlist * | minput_list (MSymbol language)

## Obsolete functions

MPlist * | minput_get_variables (MSymbol language, MSymbol name)
int | minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void *value)
| Set the initial value of an input method variable. More...
MPlist * | minput_get_commands (MSymbol language, MSymbol name)
| Get information about input method commands. More...
int | minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseq)
| Assign a key sequence to an input method command (obsolete). More...
MPlist * | minput_parse_im_names (MText *mt)
| Parse input method names. More...
int | minput_callback (MInputContext *ic, MSymbol command)
| Call a callback function. More...

## Detailed Description

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

## Typedef Documentation

## MInputCallbackFunc

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

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.

## Enumeration Type Documentation

## MInputCandidatesChanged

enum MInputCandidatesChanged

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 |

## Function Documentation

## minput_open_im()

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

Open an input method.

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.

## minput_close_im()

void minput_close_im | ( | MInputMethod * | im | ) |

Close an input method.

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

## minput_create_ic()

MInputContext* minput_create_ic | ( | MInputMethod * | im,
|  | void * | arg
| ) |  |

Create an input context.

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

## minput_destroy_ic()

void minput_destroy_ic | ( | MInputContext * | ic | ) |

Destroy an input context.

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.

## minput_filter()

int minput_filter | ( | MInputContext * | ic,
|  | MSymbol | key,
|  | void * | arg
| ) |  |

Filter an input key.

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.

## minput_lookup()

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

Look up a text produced in the input context.

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.

## minput_set_spot()

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.

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.

## minput_toggle()

void minput_toggle | ( | MInputContext * | ic | ) |

Toggle input method.

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

## minput_reset_ic()

void minput_reset_ic | ( | MInputContext * | ic | ) |

Reset an input context.

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.

## minput_get_title_icon()

MPlist* minput_get_title_icon | ( | MSymbol | language,
|  | MSymbol | name
| ) |  |

Get title and icon filename of an input method.

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

## minput_get_description()

MText* minput_get_description | ( | MSymbol | language,
|  | MSymbol | name
| ) |  |

Get description text of an input method.

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.

## minput_get_command()

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

    @brief Get information about input method command(s).

    The minput_get_command() function returns information about
    the command @b command of the input method specified by @b language and
    @b 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 a local key assignment.  It may
    also declare a local command that inherits the definition of a
    global command of the same name.

    If @b language is #Mt and @b name is #Mnil, this function returns
    information about a global command.  Otherwise information about a
    local command is returned.

    If @b command is #Mnil, information about all commands is returned.

    The return value is a @e well-formed plist (@ref 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 customized 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.

Otherwise (the specified input method or the specified command does not 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 (language, name, command);
  MPlist *plist;
  if (! cmds)
  return NULL;
  plist = mplist_value (cmds); /* (NAME DESCRIPTION STATUS KEY-SEQ ...) */
  plist = mplist_next (plist); /* (DESCRIPTION STATUS KEY-SEQ ...) */
  return (mplist_key (plist) == Mtext
  ? (MText *) mplist_value (plist)
  : NULL);
  }
  minput_get_command
  MPlist * minput_get_command(MSymbol language, MSymbol name, MSymbol command)
  Definition: input.c:4356
  Mtext
  MSymbol Mtext
  Symbol whose name is "mtext".
  Definition: plist.c:734
  mplist_next
  MPlist * mplist_next(MPlist *plist)
  Return the next sublist of a property list.
  Definition: plist.c:1012
  mplist_key
  MSymbol mplist_key(MPlist *plist)
  Return the key of the first property in a property list.
  Definition: plist.c:1075
  mplist_value
  void * mplist_value(MPlist *plist)
  Return the value of the first property in a property list.
  Definition: plist.c:1087
  MPlist
  Type of property list objects.
  Definition: plist.h:4
  MText
  Type of M-texts.
  Definition: internal.h:287

## minput_config_command()

int minput_config_command | ( | MSymbol | language,
|  | MSymbol | name,
|  | MSymbol | command,
|  | MPlist * | keyseqlist
| ) |  |

    @brief Configure the key sequence of an input method command.

    The minput_config_command() function assigns a list of key
    sequences @b keyseqlist to the command @b command of the input method
    specified by @b language and @b name.

    If @b keyseqlist is a non-empty plist, it must be a list of key
    sequences, and each key sequence must be a plist of symbols.

    If @b keyseqlist is an empty plist, any configuration and
    customization of the command are cancelled, and default key
    sequences become effective.

    If @b keyseqlist is NULL, the configuration of the command is
    canceled, and the original key sequences (what saved in per-user
    customization file, or the default one) become effective.

    In the latter two cases, @b command can be #Mnil to make all the
    commands of the input method the target of the operation.

    If @b name is #Mnil, this function configures the key assignment of a
    global command, not that of a specific input method.

    The configuration takes effect for input methods opened or
    re-opened later in the current session.  In order to make the
    configuration take effect for the future session, it must be saved
    in a per-user customization file by the function
    minput_save_config().

    @par Return value:
    If the operation was successful, this function returns 0,
    otherwise returns -1.  The operation fails in these cases:
    <ul>
    <li>@b keyseqlist is not in a valid form.
    <li>@b command is not available for the input method.
    <li>@b language and @b name do not specify an existing input method.
    </ul>

    @par See Also:
    minput_get_commands(), minput_save_config().

Example:
  /* Add "C-x u" to the "start" command of Unicode input method. */
  {
  MSymbol start_command = msymbol ("start");
  MSymbol unicode = msymbol ("unicode");
  MPlist *cmd, *plist, *key_seq_list, *key_seq;
  /* At first get the current key-sequence assignment. */
  cmd = minput_get_command (Mt, unicode, start_command);
  if (! cmd)
  {
  /* The input method does not have the command "start". Here
  should come some error handling code. */
  }
  /* Now CMD == ((start DESCRIPTION STATUS KEY-SEQUENCE ...) ...).
  Extract the part (KEY-SEQUENCE ...). */
  plist = mplist_next (mplist_next (mplist_next (mplist_value (cmd))));
  /* Copy it because we should not modify it directly. */
  key_seq_list = mplist_copy (plist);
  key_seq = mplist();
  mplist_add (key_seq, Msymbol, msymbol ("C-x"));
  mplist_add (key_seq, Msymbol, msymbol ("u"));
  mplist_add (key_seq_list, Mplist, key_seq);
  m17n_object_unref (key_seq);
  minput_config_command (Mt, unicode, start_command, key_seq_list);
  m17n_object_unref (key_seq_list);
  }
  minput_config_command
  int minput_config_command(MSymbol language, MSymbol name, MSymbol command, MPlist *keyseq)
  Definition: input.c:4446
  m17n_object_unref
  int m17n_object_unref(void *object)
  Decrement the reference count of a managed object.
  Definition: m17n-core.c:599
  mplist_copy
  MPlist * mplist_copy(MPlist *plist)
  Copy a property list.
  Definition: plist.c:768
  mplist
  MPlist * mplist()
  Create a property list object.
  Definition: plist.c:748
  Mplist
  MSymbol Mplist
  Symbol whose name is "plist".
  Definition: plist.c:726
  mplist_add
  MPlist * mplist_add(MPlist *plist, MSymbol key, void *val)
  Add a property at the end of a property list.
  Definition: plist.c:891
  msymbol
  MSymbol msymbol(const char *name)
  Get a symbol.
  Definition: symbol.c:249
  Msymbol
  MSymbol Msymbol
  Symbol whose name is "symbol".
  Definition: symbol.c:228
  Mt
  MSymbol Mt
  Symbol whose name is "t".
  Definition: symbol.c:212

## minput_get_variable()

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

    @brief Get information about input method variable(s).

    The minput_get_variable() function returns information about
    variable @b variable of the input method specified by @b language and @b name.
    An input method variable controls behavior of an input method.

    There are two kinds of variables, global and local.  A global
    variable has a global definition, and the description and the value
    may be inherited by a local variable.  Each input method defines a
    local variable which has local value.  It may also declare a
    local variable that inherits definition of a global variable of
    the same name.

    If @b language is #Mt and @b name is #Mnil, information about a global
    variable is returned.  Otherwise information about a local variable
    is returned.

    If @b variable is #Mnil, information about all variables is
    returned.

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

      ((NAME DESCRIPTION STATUS VALUE [VALID-VALUE ...]) ...)

`NAME` is a symbol representing the variable name.

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

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

`VALUE` is the initial value of the variable. If the key of this element is Mt, the variable has no initial value. Otherwise, the key is Minteger, Msymbol, or Mtext and the value is of the corresponding type.

`VALID-VALUEs` (if any) specify which values the variable can have. They have the same type (i.e. having the same key) as `VALUE` except for the case that VALUE is an integer. In that case, `VALID-VALUE` may be a plist of two integers specifying the range of possible values.

If there no `VALID-VALUE`, the variable can have any value as long as the type is the same as `VALUE`.

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

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.

Otherwise (the specified input method or the specified variable does not exist), `NULL` is returned.

## minput_config_variable()

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

Configure the value of an input method variable.

The minput_config_variable() function assigns value to the variable variable of the input method specified by language and name.

If value is a non-empty plist, it must be a plist of one element whose key is Minteger, Msymbol, or Mtext, and the value is of the corresponding type. That value is assigned to the variable.

If value is an empty plist, any configuration and customization of the variable are canceled, and the default value is assigned to the variable.

If value is NULL, the configuration of the variable is canceled, and the original value (what saved in per-user customization file, or the default value) is assigned to the variable.

In the latter two cases, variable can be Mnil to make all the variables of the input method the target of the operation.

If name is Mnil, this function configures the value of global variable, not that of a specific input method.

The configuration takes effect for input methods opened or re-opened later in the current session. To make the configuration take effect for the future session, it must be saved in a per-user customization file by the function minput_save_config().

Return value:

If the operation was successful, this function returns 0, otherwise returns -1. The operation fails in these cases:

- value is not in a valid form, the type does not match the definition, or the value is our of range.
- variable is not available for the input method.
- language and name do not specify an existing input method.

See Also:
  minput_get_variable(), minput_save_config().

## minput_config_file()

char* minput_config_file | ( | void |  | ) |

Get the name of per-user customization file.

The minput_config_file() function returns the absolute path name of per-user customization file into which minput_save_config() save configurations. It is usually `config.mic` under the directory `${HOME}/.m17n.d` (${HOME} is user's home directory). It is not assured that the file of the returned name exists nor is readable/writable. If minput_save_config() fails and returns -1, an application program might check the file, make it writable (if possible), and try minput_save_config() again.

Return value:

This function returns a string. As the string is kept in the library, the caller must not modify nor free it.

See Also:
  minput_save_config()

## minput_save_config()

int minput_save_config | ( | void |  | ) |

Save configurations in per-user customization file.

The minput_save_config() function saves the configurations done so far in the current session into the per-user customization file.

Return value:

If the operation was successful, 1 is returned. If the per-user customization file is currently locked, 0 is returned. In that case, the caller may wait for a while and try again. If the configuration file is not writable, -1 is returned. In that case, the caller may check the name of the file by calling minput_config_file(), make it writable if possible, and try again.

See Also:
  minput_config_file()

## minput_list()

MPlist* minput_list | ( | MSymbol | language | ) |

    @brief List available input methods.

    The minput_list() function returns a list of currently available
    input methods whose language is @b language.  If @b language is #Mnil,
    all input methods are listed.

    @par Return value:
    The returned value is a plist of this form:
    ((LANGUAGE-NAME INPUT-METHOD-NAME SANE) ...)
    The third element SANE of each input method is #Mt if it can be
    successfully used, or #Mnil if it has some problem (e.g. syntax
    error of MIM file, unavailable external module, unavailable
    including input method).

Example:
  #include <stdio.h>
  #include <string.h>
  #include <m17n.h>
  int
  main (int argc, char **argv)
  {
  MPlist *imlist, *pl;
  M17N_INIT();
  imlist = minput_list ((argc > 1) ? msymbol (argv[1]) : Mnil);
  for (pl = imlist; mplist_key (pl) != Mnil; pl = mplist_next (pl))
  {
  MPlist *p = mplist_value (pl);
  MSymbol lang, name, sane;
  lang = mplist_value (p);
  p = mplist_next (p);
  name = mplist_value (p);
  p = mplist_next (p);
  sane = mplist_value (p);
  printf ("%s %s %s\n", msymbol_name (lang), msymbol_name (name),
  sane == Mt ? "ok" : "no");
  }
  m17n_object_unref (imlist);
  M17N_FINI();
  exit (0);
  }
  minput_list
  MPlist * minput_list(MSymbol lang)
  Definition: input.c:5079
  M17N_INIT
  #define M17N_INIT()
  Initialize the m17n library.
  Definition: m17n-core.c:170
  M17N_FINI
  #define M17N_FINI()
  Finalize the m17n library.
  Definition: m17n-core.c:185
  Mnil
  MSymbol Mnil
  Symbol whose name is "nil".
  Definition: symbol.c:205
  msymbol_name
  char * msymbol_name(MSymbol symbol)
  Definition: symbol.c:379
  m17n.h

## minput_get_variables()

MPlist* minput_get_variables | ( | MSymbol | language,
|  | MSymbol | name
| ) |  |

    @brief 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 @b language and @b name.  The plist is @e well-formed
    (@ref m17nPlist) of the following format:

        (VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
         VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
         ...)

    @c VARNAME is a symbol representing the variable name.

    @c DOC-MTEXT is an M-text describing the variable.

    @c DEFAULT-VALUE is the default value of the variable.  It is a
    symbol, integer, or M-text.

    @c VALUEs (if any) specifies the possible values of the variable.
    If @c DEFAULT-VALUE is an integer, @c VALUE may be a plist (@c FROM
    @c TO), where @c FROM and @c TO specifies a range of possible
    values.

    For instance, suppose an input method has the variables:

    @li name:intvar, description:"value is an integer",
         initial value:0, value-range:0..3,10,20

    @li name:symvar, description:"value is a symbol",
         initial value:nil, value-range:a, b, c, nil

    @li 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" ""))

    @par 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, @c NULL is returned.

## minput_set_variable()

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

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

## minput_get_commands()

MPlist* minput_get_commands | ( | MSymbol | language,
|  | MSymbol | name
| ) |  |

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.

## minput_assign_command_keys()

int minput_assign_command_keys | ( | MSymbol | language,
|  | MSymbol | name,
|  | MSymbol | command,
|  | MPlist * | keyseq
| ) |  |

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

## minput_parse_im_names()

MPlist* minput_parse_im_names | ( | MText * | mt | ) |

Parse input method names.

The minput_parse_im_names() function parses M-text mt and returns a list of input method names. Input method names in mt must be separated by comma (","). Input methods whose language is Mt can be specified by its name only (i.e. just "latn-post" instead of "t-latn-post").

Return value:
  The minput_parse_im_names() returns a plist of which elements are plist of LANGUAGE and NAME of input methods as below: ((LANGUAGE1 NAME1) (LANGUAGE2 NAME2) ...) Both LANGUAGEn and NAMEn are symbols. LANGUAGEn is Mt if the corresponding input method is not limited to a specific language. If a specified input method doesn't exist, the corresponding element in the above plist is a sub-part of mt for that non-existing input method name. For instance, if "symbol,unknown,unicode" is specified as mt and "unknown" doesn't exist, the return value is: ((t symbol) "unknown" (t unicode))

## minput_callback()

int minput_callback | ( | MInputContext * | ic,
|  | MSymbol | command
| ) |  |

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.

## Variable Documentation

## Minput_method

MSymbol Minput_method

Symbol whose name is "input-method".

## Minput_preedit_start

MSymbol Minput_preedit_start

## Minput_preedit_done

MSymbol Minput_preedit_done

## Minput_preedit_draw

MSymbol Minput_preedit_draw

## Minput_status_start

MSymbol Minput_status_start

## Minput_status_done

MSymbol Minput_status_done

## Minput_status_draw

MSymbol Minput_status_draw

## Minput_candidates_start

MSymbol Minput_candidates_start

## Minput_candidates_done

MSymbol Minput_candidates_done

## Minput_candidates_draw

MSymbol Minput_candidates_draw

## Minput_set_spot

MSymbol Minput_set_spot

## Minput_toggle

MSymbol Minput_toggle

## Minput_reset

MSymbol Minput_reset

## Minput_get_surrounding_text

MSymbol Minput_get_surrounding_text

## Minput_delete_surrounding_text

MSymbol Minput_delete_surrounding_text

## Minput_focus_out

MSymbol Minput_focus_out

## Minput_focus_in

MSymbol Minput_focus_in

## Minput_focus_move

MSymbol Minput_focus_move

## Minherited

MSymbol Minherited

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

## Mcustomized

MSymbol Mcustomized

## Mconfigured

MSymbol Mconfigured

## minput_default_driver

MInputDriver minput_default_driver

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.

## minput_driver

MInputDriver* minput_driver

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.

## Minput_driver

MSymbol Minput_driver

The variable Minput_driver is a symbol for a foreign input method. See foreign input method for the detail.