.\" Copyright (C) 2001 Information-technology Promotion Agency (IPA)
.\" Copyright (C) 2001-2011
.\"   National Institute of Advanced Industrial Science and Technology (AIST)
.\" This file is part of the m17n library documentation.
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Section, no Front-Cover Texts,
.\" and no Back-Cover Texts.  A copy of the license is included in the
.\" appendix entitled "GNU Free Documentation License".
.TH "Input Method (basic)" 3m17n "12 Jan 2011" "Version 1.6.2" "The m17n Library" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Input_Method_(basic) \- API for Input method.  

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBMInputDriver\fP"
.br
.RI "\fIStructure of input method driver. \fP"
.ti -1c
.RI "struct \fBMInputMethod\fP"
.br
.RI "\fIStructure of input method. \fP"
.ti -1c
.RI "struct \fBMInputContext\fP"
.br
.RI "\fIStructure of input context. \fP"
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef void(* \fBMInputCallbackFunc\fP )(\fBMInputContext\fP *ic, \fBMSymbol\fP command)"
.br
.RI "\fIType of input method callback functions. \fP"
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBMInputCandidatesChanged\fP { \fBMINPUT_CANDIDATES_LIST_CHANGED\fP =  1, \fBMINPUT_CANDIDATES_INDEX_CHANGED\fP =  2, \fBMINPUT_CANDIDATES_SHOW_CHANGED\fP =  4, \fBMINPUT_CANDIDATES_CHANGED_MAX\fP }"
.br
.RI "\fIBit-masks to specify how candidates of input method is changed. \fP"
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_method\fP"
.br
.RI "\fISymbol whose name is 'input-method'. \fP"
.ti -1c
.RI "\fBMInputDriver\fP \fBminput_default_driver\fP"
.br
.RI "\fIThe default driver for internal input methods. \fP"
.ti -1c
.RI "\fBMInputDriver\fP * \fBminput_driver\fP"
.br
.RI "\fIThe driver for internal input methods. \fP"
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_driver\fP"
.br
.in -1c
.SS "Variables: Predefined symbols for callback commands."
 These are the predefined symbols that are used as the \fCCOMMAND\fP argument of callback functions of an input method driver (see \fBMInputDriver::callback_list\fP).
.PP
Most of them do not require extra argument nor return any value; exceptions are these:
.PP
\fBMinput_get_surrounding_text:\fP When a callback function assigned for this command is called, the first element of \fBMInputContext::plist\fP has key \fBMinteger\fP 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.
.PP
If the surrounding text is currently supported, the callback function must set the key of this element to \fBMtext\fP 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.
.PP
If the surrounding text is not currently supported, the callback function should return without changing the first element of \fBMInputContext::plist\fP.
.PP
\fBMinput_delete_surrounding_text:\fP When a callback function assigned for this command is called, the first element of \fBMInputContext::plist\fP has key \fBMinteger\fP 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 \fBMInputContext::plist\fP. 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_preedit_start\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_preedit_done\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_preedit_draw\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_status_start\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_status_done\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_status_draw\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_candidates_start\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_candidates_done\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_candidates_draw\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_set_spot\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_toggle\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_reset\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_get_surrounding_text\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_delete_surrounding_text\fP"
.br
.in -1c
.SS "Variables: Predefined symbols for special input events."
 These are the predefined symbols that are used as the \fCKEY\fP argument of \fBminput_filter()\fP. 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_focus_out\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_focus_in\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMinput_focus_move\fP"
.br
.in -1c
.SS "Variables: Predefined symbols used in input method information."
 
.in +1c
.ti -1c
.RI "\fBMSymbol\fP \fBMinherited\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMcustomized\fP"
.br
.ti -1c
.RI "\fBMSymbol\fP \fBMconfigured\fP"
.br
.in -1c
.SS "Functions"
 
.in +1c
.ti -1c
.RI "\fBMInputMethod\fP * \fBminput_open_im\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, void *arg)"
.br
.RI "\fIOpen an input method. \fP"
.ti -1c
.RI "void \fBminput_close_im\fP (\fBMInputMethod\fP *im)"
.br
.RI "\fIClose an input method. \fP"
.ti -1c
.RI "\fBMInputContext\fP * \fBminput_create_ic\fP (\fBMInputMethod\fP *im, void *arg)"
.br
.RI "\fICreate an input context. \fP"
.ti -1c
.RI "void \fBminput_destroy_ic\fP (\fBMInputContext\fP *ic)"
.br
.RI "\fIDestroy an input context. \fP"
.ti -1c
.RI "int \fBminput_filter\fP (\fBMInputContext\fP *ic, \fBMSymbol\fP key, void *arg)"
.br
.RI "\fIFilter an input key. \fP"
.ti -1c
.RI "int \fBminput_lookup\fP (\fBMInputContext\fP *ic, \fBMSymbol\fP key, void *arg, \fBMText\fP *mt)"
.br
.RI "\fILook up a text produced in the input context. \fP"
.ti -1c
.RI "void \fBminput_set_spot\fP (\fBMInputContext\fP *ic, int x, int y, int ascent, int descent, int fontsize, \fBMText\fP *mt, int pos)"
.br
.RI "\fISet the spot of the input context. \fP"
.ti -1c
.RI "void \fBminput_toggle\fP (\fBMInputContext\fP *ic)"
.br
.RI "\fIToggle input method. \fP"
.ti -1c
.RI "void \fBminput_reset_ic\fP (\fBMInputContext\fP *ic)"
.br
.RI "\fIReset an input context. \fP"
.ti -1c
.RI "\fBMPlist\fP * \fBminput_get_title_icon\fP (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.br
.RI "\fIGet title and icon filename of an input method. \fP"
.ti -1c
.RI "\fBMText\fP * \fBminput_get_description\fP (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.br
.RI "\fIGet description text of an input method. \fP"
.ti -1c
.RI "\fBMPlist\fP * \fBminput_get_command\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP command)"
.br
.RI "\fIGet information about input method command(s). \fP"
.ti -1c
.RI "int \fBminput_config_command\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP command, \fBMPlist\fP *keyseqlist)"
.br
.RI "\fIConfigure the key sequence of an input method command. \fP"
.ti -1c
.RI "\fBMPlist\fP * \fBminput_get_variable\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP variable)"
.br
.RI "\fIGet information about input method variable(s). \fP"
.ti -1c
.RI "int \fBminput_config_variable\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP variable, \fBMPlist\fP *value)"
.br
.RI "\fIConfigure the value of an input method variable. \fP"
.ti -1c
.RI "char * \fBminput_config_file\fP ()"
.br
.RI "\fIGet the name of per-user customization file. \fP"
.ti -1c
.RI "int \fBminput_save_config\fP (void)"
.br
.RI "\fISave configurations in per-user customization file. \fP"
.in -1c
.SS "Obsolete functions"
 
.in +1c
.ti -1c
.RI "\fBMPlist\fP * \fBminput_get_variables\fP (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.br
.RI "\fIGet a list of variables of an input method (obsolete). \fP"
.ti -1c
.RI "int \fBminput_set_variable\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP variable, void *value)"
.br
.RI "\fISet the initial value of an input method variable. \fP"
.ti -1c
.RI "\fBMPlist\fP * \fBminput_get_commands\fP (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.br
.RI "\fIGet information about input method commands. \fP"
.ti -1c
.RI "int \fBminput_assign_command_keys\fP (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP command, \fBMPlist\fP *keyseq)"
.br
.RI "\fIAssign a key sequence to an input method command (obsolete). \fP"
.ti -1c
.RI "int \fBminput_callback\fP (\fBMInputContext\fP *ic, \fBMSymbol\fP command)"
.br
.RI "\fICall a callback function. \fP"
.in -1c
.SH "Detailed Description"
.PP 
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.
.PP
.PD 0
.IP "\(bu" 2
Internal Input Method
.PP
An internal input method has non \fCMnil\fP 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 \fCMt\fP as LANGUAGE of those input methods.
.PP
An internal input method accepts an input key which is a symbol associated with an input event. As there is no way for the \fCm17n\fP \fClibrary\fP 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 \fBminput_event_to_key()\fP for the detail.
.PP

.IP "\(bu" 2
Foreign Input Method 
.PP
A foreign input method has \fCMnil\fP 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 \fBMinput_driver\fP, 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 \fCm17n\fP \fClibrary\fP.
.PP
For convenience, the m17n\-X library provides an input method driver that enables the input style of OverTheSpot for XIM, and stores \fBMinput_driver\fP property of the symbol \fCMxim\fP with a pointer to the driver. See the documentation of m17n GUI API for the detail.
.PP

.PP
.PP
PROCESSING FLOW
.PP
The typical processing flow of handling an input method is:
.PP
.PD 0
.IP "\(bu" 2
open an input method 
.IP "\(bu" 2
create an input context for the input method 
.IP "\(bu" 2
filter an input key 
.IP "\(bu" 2
look up a produced text in the input context 
.PP

.SH "Data Structure Documentation"
.SS MInputDriver
.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fBint(* \fBMInputDriver::open_im\fP)(\fBMInputMethod\fP *im)\fP
.PP
Open an input method. This function opens the input method \fBim\fP. It is called from the function \fBminput_open_im()\fP after all member of \fBim\fP but <info> set. If opening \fBim\fP succeeds, it returns 0. Otherwise, it returns \-1. The function can setup \fBim\->info\fP to keep various information that is referred by the other driver functions. 
.PP
\fBvoid(* \fBMInputDriver::close_im\fP)(\fBMInputMethod\fP *im)\fP
.PP
Close an input method. This function closes the input method \fBim\fP. It is called from the function \fBminput_close_im()\fP. It frees all memory allocated for \fBim\->info\fP (if any) after finishing all the tasks of closing the input method. But, the other members of \fBim\fP should not be touched. 
.PP
\fBint(* \fBMInputDriver::create_ic\fP)(\fBMInputContext\fP *ic)\fP
.PP
Create an input context. This function creates the input context \fBic\fP. It is called from the function \fBminput_create_ic()\fP after all members of \fBic\fP but <info> are set. If creating \fBic\fP succeeds, it returns 0. Otherwise, it returns \-1. The function can setup \fBic\->info\fP to keep various information that is referred by the other driver functions. 
.PP
\fBvoid(* \fBMInputDriver::destroy_ic\fP)(\fBMInputContext\fP *ic)\fP
.PP
Destroy an input context. This function is called from the function \fBminput_destroy_ic()\fP and destroys the input context \fBic\fP. It frees all memory allocated for \fBic\->info\fP (if any) after finishing all the tasks of destroying the input method. But, the other members of \fBic\fP should not be touched. 
.PP
\fBint(* \fBMInputDriver::filter\fP)(\fBMInputContext\fP *ic, \fBMSymbol\fP key, void *arg)\fP
.PP
Filter an input key. This function is called from the function \fBminput_filter()\fP and filters an input key. \fBkey\fP and \fBarg\fP are the same as what given to \fBminput_filter()\fP.
.PP
The task of the function is to handle \fBkey\fP, update the internal state of \fBic\fP. If \fBkey\fP is absorbed by the input method and no text is produced, it returns 1. Otherwise, it returns 0.
.PP
It may update \fBic\->status\fP, \fBic\->preedit\fP, \fBic\->cursor_pos\fP, \fBic\->ncandidates\fP, \fBic\->candidates\fP, and \fBic\->produced\fP if that is necessary for the member <callback>.
.PP
The meaning of \fBarg\fP depends on the input method river. See the documentation of \fCminput_default_driver\fP and \fCminput_gui_driver\fP for instance. 
.PP
\fBint(* \fBMInputDriver::lookup\fP)(\fBMInputContext\fP *ic, \fBMSymbol\fP key, void *arg, \fBMText\fP *mt)\fP
.PP
Lookup a produced text in an input context. It is called from the function \fBminput_lookup()\fP and looks up a produced text in the input context \fBic\fP. This function concatenate a text produced by the input key \fBkey\fP (if any) to M\-text \fBmt\fP. If \fBkey\fP was correctly handled by the input method of \fBic\fP, it returns 0. Otherwise, it returns 1.
.PP
The meaning of \fBarg\fP depends on the input method driver. See the documentation of \fCminput_default_driver\fP and \fCminput_gui_driver\fP for instance. 
.PP
\fB\fBMPlist\fP* \fBMInputDriver::callback_list\fP\fP
.PP
List of callback functions. List of callback functions. Keys are one of \fBMinput_preedit_start\fP, \fBMinput_preedit_draw\fP, \fBMinput_preedit_done\fP, \fBMinput_status_start\fP, \fBMinput_status_draw\fP, \fBMinput_status_done\fP, \fBMinput_candidates_start\fP, \fBMinput_candidates_draw\fP, \fBMinput_candidates_done\fP, \fBMinput_set_spot\fP, \fBMinput_toggle\fP, \fBMinput_reset\fP, \fBMinput_get_surrounding_text\fP, \fBMinput_delete_surrounding_text\fP. Values are functions of type \fBMInputCallbackFunc\fP. 

.SS MInputMethod
.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fB\fBMSymbol\fP \fBMInputMethod::language\fP\fP
.PP
\fB\fBMSymbol\fP \fBMInputMethod::name\fP\fP
.PP
\fB\fBMInputDriver\fP \fBMInputMethod::driver\fP\fP
.PP
\fBvoid* \fBMInputMethod::arg\fP\fP
.PP
\fBvoid* \fBMInputMethod::info\fP\fP

.SS MInputContext
.PP
.ad l
.nh
.PP
\fBFIELD DOCUMENTATION:\fP
.PP 
.PP
\fB\fBMInputMethod\fP* \fBMInputContext::im\fP\fP
.PP
\fB\fBMText\fP* \fBMInputContext::produced\fP\fP
.PP
\fBvoid* \fBMInputContext::arg\fP\fP
.PP
\fBint \fBMInputContext::active\fP\fP
.PP
\fBint \fBMInputContext::x\fP\fP
.PP
\fBint \fBMInputContext::y\fP\fP
.PP
\fBint \fBMInputContext::ascent\fP\fP
.PP
\fBint \fBMInputContext::descent\fP\fP
.PP
\fBint \fBMInputContext::fontsize\fP\fP
.PP
\fB\fBMText\fP* \fBMInputContext::mt\fP\fP
.PP
\fBint \fBMInputContext::pos\fP\fP
.PP
\fBstruct { ... }   \fBMInputContext::spot\fP\fP
.PP
\fBvoid* \fBMInputContext::info\fP\fP
.PP
\fB\fBMText\fP* \fBMInputContext::status\fP\fP
.PP
\fBint \fBMInputContext::status_changed\fP\fP
.PP
\fB\fBMText\fP* \fBMInputContext::preedit\fP\fP
.PP
\fBint \fBMInputContext::preedit_changed\fP\fP
.PP
\fBint \fBMInputContext::cursor_pos\fP\fP
.PP
\fBint \fBMInputContext::cursor_pos_changed\fP\fP
.PP
\fB\fBMPlist\fP* \fBMInputContext::candidate_list\fP\fP
.PP
\fBint \fBMInputContext::candidate_index\fP\fP
.PP
\fBint \fBMInputContext::candidate_from\fP\fP
.PP
\fBint \fBMInputContext::candidate_to\fP\fP
.PP
\fBint \fBMInputContext::candidate_show\fP\fP
.PP
\fBint \fBMInputContext::candidates_changed\fP\fP
.PP
\fB\fBMPlist\fP* \fBMInputContext::plist\fP\fP

.SH "Typedef Documentation"
.PP 
.SS "typedef void(* \fBMInputCallbackFunc\fP)(\fBMInputContext\fP *ic, \fBMSymbol\fP command)"
.PP
Type of input method callback functions. This is the type of callback functions called from input method drivers. \fBic\fP is a pointer to an input context, \fBcommand\fP is a name of callback for which the function is called. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBMInputCandidatesChanged\fP"
.PP
Bit\-masks to specify how candidates of input method is changed. 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fIMINPUT_CANDIDATES_LIST_CHANGED \fP\fP
.TP
\fB\fIMINPUT_CANDIDATES_INDEX_CHANGED \fP\fP
.TP
\fB\fIMINPUT_CANDIDATES_SHOW_CHANGED \fP\fP
.TP
\fB\fIMINPUT_CANDIDATES_CHANGED_MAX \fP\fP

.SH "Variable Documentation"
.PP 
.SS "\fBMSymbol\fP \fBMinput_method\fP"
.PP
Symbol whose name is 'input\-method'. 
.SS "\fBMSymbol\fP \fBMinput_preedit_start\fP"
.SS "\fBMSymbol\fP \fBMinput_preedit_done\fP"
.SS "\fBMSymbol\fP \fBMinput_preedit_draw\fP"
.SS "\fBMSymbol\fP \fBMinput_status_start\fP"
.SS "\fBMSymbol\fP \fBMinput_status_done\fP"
.SS "\fBMSymbol\fP \fBMinput_status_draw\fP"
.SS "\fBMSymbol\fP \fBMinput_candidates_start\fP"
.SS "\fBMSymbol\fP \fBMinput_candidates_done\fP"
.SS "\fBMSymbol\fP \fBMinput_candidates_draw\fP"
.SS "\fBMSymbol\fP \fBMinput_set_spot\fP"
.SS "\fBMSymbol\fP \fBMinput_toggle\fP"
.SS "\fBMSymbol\fP \fBMinput_reset\fP"
.SS "\fBMSymbol\fP \fBMinput_get_surrounding_text\fP"
.SS "\fBMSymbol\fP \fBMinput_delete_surrounding_text\fP"
.SS "\fBMSymbol\fP \fBMinput_focus_out\fP"
.SS "\fBMSymbol\fP \fBMinput_focus_in\fP"
.SS "\fBMSymbol\fP \fBMinput_focus_move\fP"
.SS "\fBMSymbol\fP \fBMinherited\fP"These are the predefined symbols describing status of input method command and variable, and are used in a return value of \fBminput_get_command()\fP and \fBminput_get_variable()\fP. 
.SS "\fBMSymbol\fP \fBMcustomized\fP"
.SS "\fBMSymbol\fP \fBMconfigured\fP"
.SS "\fBMInputDriver\fP \fBminput_default_driver\fP"
.PP
The default driver for internal input methods. The variable \fBminput_default_driver\fP is the default driver for internal input methods.
.PP
The member \fBMInputDriver::open_im()\fP searches the m17n database for an input method that matches the tag < \fBMinput_method\fP, \fBlanguage\fP, \fBname>\fP and loads it.
.PP
The member \fBMInputDriver::callback_list()\fP is \fCNULL\fP. 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.
.PP
The macro \fBM17N_INIT()\fP sets the variable \fBminput_driver\fP to the pointer to this driver so that all internal input methods use it.
.PP
Therefore, unless \fCminput_driver\fP is set differently, the driver dependent arguments \fBarg\fP of the functions whose name begins with 'minput_' are all ignored. 
.SS "\fBMInputDriver\fP* \fBminput_driver\fP"
.PP
The driver for internal input methods. The variable \fBminput_driver\fP is a pointer to the input method driver that is used by internal input methods. The macro \fBM17N_INIT()\fP initializes it to a pointer to \fBminput_default_driver\fP if <m17n\fI\fP.h> is included. 
.SS "\fBMSymbol\fP \fBMinput_driver\fP"The variable \fBMinput_driver\fP is a symbol for a foreign input method. See \fBforeign input method\fP for the detail. 
.SH "Author"
.PP 
Generated automatically by Doxygen for The m17n Library from the source code.
.SH "Function Documentation"
.PP
.SS "\fBMPlist\fP* minput_get_variables (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.PP
Get a list of variables of an input method (obsolete). This function is obsolete. Use \fBminput_get_variable()\fP instead.
.PP
The \fBminput_get_variables()\fP function returns a plist (\fBMPlist\fP) of variables used to control the behavior of the input method specified by \fBlanguage\fP and \fBname\fP. The plist is \fIwell\-formed\fP (\fBProperty List\fP) of the following format:
.PP
.PP
.nf

    (VARNAME (DOC\-MTEXT DEFAULT\-VALUE [ VALUE ... ] )
     VARNAME (DOC\-MTEXT DEFAULT\-VALUE [ VALUE ... ] )
     ...)
.fi
.PP
.PP
\fCVARNAME\fP is a symbol representing the variable name.
.PP
\fCDOC\-MTEXT\fP is an M\-text describing the variable.
.PP
\fCDEFAULT\-VALUE\fP is the default value of the variable. It is a symbol, integer, or M\-text.
.PP
\fCVALUEs\fP (if any) specifies the possible values of the variable. If \fCDEFAULT\-VALUE\fP is an integer, \fCVALUE\fP may be a plist (\fCFROM\fP \fCTO\fP), where \fCFROM\fP and \fCTO\fP specifies a range of possible values.
.PP
For instance, suppose an input method has the variables:
.PP
.PD 0
.IP "\(bu" 2
name:intvar, description:'value is an integer', initial value:0, value\-range:0..3,10,20
.PP
.PD 0
.IP "\(bu" 2
name:symvar, description:'value is a symbol', initial value:nil, value\-range:a, b, c, nil
.PP
.PD 0
.IP "\(bu" 2
name:txtvar, description:'value is an M\-text', initial value:empty text, no value\-range (i.e. any text)
.PP
Then, the returned plist is as follows.
.PP
.PP
.nf

    (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" ""))
.fi
.PP
.PP

\fBRETURN VALUE\fp
.RS 4
If the input method uses any variables, a pointer to \fBMPlist\fP 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, \fCNULL\fP is returned. 
.RE
.PP

.SS "int minput_set_variable (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP variable, void * value)"
.PP
Set the initial value of an input method variable. The \fBminput_set_variable()\fP function sets the initial value of input method variable \fBvariable\fP to \fBvalue\fP for the input method specified by \fBlanguage\fP and \fBname\fP.
.PP
By default, the initial value is 0.
.PP
This setting gets effective in a newly opened input method.
.PP

\fBRETURN VALUE\fp
.RS 4
If the operation was successful, 0 is returned. Otherwise \-1 is returned, and \fBmerror_code\fP is set to \fCMERROR_IM\fP. 
.RE
.PP

.SS "\fBMPlist\fP* minput_get_commands (\fBMSymbol\fP language, \fBMSymbol\fP name)"
.PP
Get information about input method commands. The \fBminput_get_commands()\fP function returns information about input method commands of the input method specified by \fBlanguage\fP and \fBname\fP. An input method command is a pseudo key event to which one or more actual input key sequences are assigned.
.PP
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.
.PP
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.
.PP
If \fBname\fP is \fBMnil\fP, information about global commands is returned. In this case \fBlanguage\fP is ignored.
.PP
If \fBname\fP is not \fBMnil\fP, information about those commands that have local key assignments in the input method specified by \fBlanguage\fP and \fBname\fP is returned.
.PP

\fBRETURN VALUE\fp
.RS 4
If no input method commands are found, this function returns \fCNULL\fP.
.RE
.PP
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.
.PP
The first element of COMMAND\-INFO has the key \fBMtext\fP, and the value is an M\-text describing the command.
.PP
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 \fBMplist\fP, and the value is a plist whose keys are \fBMsymbol\fP and values are symbols representing input keys, which are currently assigned to the command.
.PP
As the returned plist is kept in the library, the caller must not modify nor free it. 
.SS "int minput_assign_command_keys (\fBMSymbol\fP language, \fBMSymbol\fP name, \fBMSymbol\fP command, \fBMPlist\fP * keyseq)"
.PP
Assign a key sequence to an input method command (obsolete). This function is obsolete. Use \fBminput_config_command()\fP instead.
.PP
The \fBminput_assign_command_keys()\fP function assigns input key sequence \fBkeyseq\fP to input method command \fBcommand\fP for the input method specified by \fBlanguage\fP and \fBname\fP. If \fBname\fP is \fBMnil\fP, the key sequence is assigned globally no matter what \fBlanguage\fP is. Otherwise the key sequence is assigned locally.
.PP
Each element of \fBkeyseq\fP must have the key \fBmsymbol\fP and the value must be a symbol representing an input key.
.PP
\fBkeyseq\fP may be \fCNULL\fP, in which case, all assignments are deleted globally or locally.
.PP
This assignment gets effective in a newly opened input method.
.PP

\fBRETURN VALUE\fp
.RS 4
If the operation was successful, 0 is returned. Otherwise \-1 is returned, and \fBmerror_code\fP is set to \fCMERROR_IM\fP. 
.RE
.PP

.SS "int minput_callback (\fBMInputContext\fP * ic, \fBMSymbol\fP command)"
.PP
Call a callback function. The \fBminput_callback()\fP functions calls a callback function \fBcommand\fP assigned for the input context \fBic\fP. The caller must set specific elements in \fBic\->plist\fP if the callback function requires.
.PP

\fBRETURN VALUE\fp
.RS 4
If there exists a specified callback function, 0 is returned. Otherwise \-1 is returned. By side effects, \fBic\->plist\fP may be modified. 
.RE
.PP

.SH COPYRIGHT
Copyright (C) 2001 Information\-technology Promotion Agency (IPA)
.br
Copyright (C) 2001\-2011 National Institute of Advanced Industrial Science and Technology (AIST)
.br
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>.