内部入力メソッドとは LANGUAGE が Mnil 以外のものであり、その本体 はm17n データベースに<Minput_method, LANGUAGE, NAME> というタグを付 けて定義されている。この種の入力メソッドに対して、m17n ライブラリで はCUI 用と GUI 用それぞれの入力メソッドドライバをあらかじめ定義して いる。これらのドライバは m17n ライブラリ自体の入力処理エンジンを利 用する。m17n データベースには、特定の言語専用でない入力メソッドを定 義することもでき、そのような入力メソッドの LANGUAGE は Mt である。
内部入力メソッドは、ユーザの入力イベントに対応したシンボルである入 力キーを受け取る。m17n ライブラリ は入力イベントがアプリケー ションプログラムでどう表現されているかを知ることができないので、入 力イベントから入力キーへの変換はアプリケーションプログラマの責任で 行わなくてはならない。詳細については関数 minput_event_to_key() の 説明を参照。
外部入力メソッドとは LANGUAGE が Mnil のものであり、その本体は外 部のリソースとして定義される。（たとえばX Window System のXIM な ど。) この種の入力メソッドでは、シンボル NAME はMinput_driver を キーとするプロパティを持ち、その値は入力メソッドドライバへのポイン タである。このことにより、適切なドライバを準備することによって、い かなる種類の入力メソッドもm17n ライブラリ の枠組の中で扱う事 ができる。
利便性の観点から、m17n X ライブラリは XIM の OverTheSpot の入力スタ イルを実現する入力メソッドドライバを提供し、またシンボル Mxim の Minput_driver プロパティの値としてそのドライバへのポインタを保持 している。詳細については m17n GUI API のドキュメントを参照のこと。
処理の流れ
入力メソッド処理の典型的な処理は以下のようになる。
| typedef struct MInputMethod MInputMethod |
| typedef struct MInputContext MInputContext |
| typedef void(*) MInputCallbackFunc(MInputContext *ic, MSymbol command) |
入力メソッドから呼ばれるコールバック関数の型である。IC は入力コンテクストへのポインタ、COMMAND は関数が呼ばれるコールバックの名前である。
| MInputMethod * minput_open_im | ( | MSymbol | language, | |
| MSymbol | name, | |||
| void * | arg | |||
| ) |
関数 minput_open_im() は言語 language と名前 name に合致する入力メソッドをオープンし、新たに割り当てられた入力メソッドオブジェクトへのポインタを返す。
この関数は、まず入力メソッド用のドライバを以下のようにして決定する。
language が Mnil でなければ、変数 minput_driver で指されているドライバを用いる。
language が Mnil であり、name が Minput_driver プロパティを持つ場合には、そのプロパティの値で指されている入力ドライバを用いて入力メソッドをオープンする。 name にそのようなプロパティが無かった場合は NULL を返す。
次いで、ドライバのメンバ MInputDriver::open_im() が呼ばれる。
arg は構造体 MInputMethod のメンバ arg に設定され、ドライバから参照できる。
| void minput_close_im | ( | MInputMethod * | im | ) |
関数 minput_close_im() は、入力メソッド im をクローズする。 この入力メソッド im は minput_open_im() によって作られたものでなければならない。
| MInputContext * minput_create_ic | ( | MInputMethod * | im, | |
| void * | arg | |||
| ) |
関数 minput_create_ic() は入力メソッド im に対応する入力コンテクストオブジェクトを生成し、 Minput_preedit_start, Minput_status_start, Minput_status_draw に対応するコールバック関数をこの順に呼ぶ。
NULL を返す。 | void minput_destroy_ic | ( | MInputContext * | ic | ) |
関数 minput_destroy_ic() は、入力コンテクスト ic を破壊する。 この入力コンテクストは minput_create_ic() によって作られたものでなければならない。この関数は Minput_preedit_done, Minput_status_done, Minput_candidates_done に対応するコールバック関数をこの順に呼ぶ。
| int minput_filter | ( | MInputContext * | ic, | |
| MSymbol | key, | |||
| void * | arg | |||
| ) |
関数 minput_filter() は入力キー key を入力コンテクスト ic に応じてフィルタし、preedit テキスト、ステータス、現時点での候補が変化した時点で、それぞれ Minput_preedit_draw, Minput_status_draw, Minput_candidates_draw に対応するコールバック関数を呼ぶ。
| int minput_lookup | ( | MInputContext * | ic, | |
| MSymbol | key, | |||
| void * | arg, | |||
| MText * | mt | |||
| ) |
関数 minput_lookup() は入力コンテクスト ic 中のテキストを探す。 key は関数 minput_filter() への直前の呼び出しに用いられたものと同じでなくてはならない。
テキストが入力メソッドによって生成されていれば、テキストは M-text mt に連結される。
この関数は、MInputDriver::lookup を呼ぶ。
| void minput_set_spot | ( | MInputContext * | ic, | |
| int | x, | |||
| int | y, | |||
| int | ascent, | |||
| int | descent, | |||
| int | fontsize, | |||
| MText * | mt, | |||
| int | pos | |||
| ) |
関数 minput_set_spot() は、入力コンテクスト ic のスポットを、座標 (x, y ) の位置に 、高さ ascent、 descent で設定する。 これらの値の意味は入力メソッドドライバに依存する。
たとえば CUI 環境で動作するドライバは x と y をそれぞれ列と行の番号として用い、ascent と descent を無視するかもしれない。 またウィンドウシステム用のドライバは x と y をクライアントウィンドウの原点からのオフセットをピクセル単位で表したものとして扱い、 ascent と descent を (x . y ) の列のアセントとディセントをピクセル単位で表したものとして扱うかもしれない。
fontsize には preedit テキストのフォントサイズを 1/10 ポイント単位で指定する。
mt と pos はそのスポットの M-text と文字位置である。mt は NULL でもよく、その場合には入力メソッドはスポット周辺のテキストに関する情報を得ることができない。
| void minput_toggle | ( | MInputContext * | ic | ) |
関数 minput_toggle() は入力コンテクスト ic に対応付けられた入力メソッドをトグルする。
| void minput_reset_ic | ( | MInputContext * | ic | ) |
関数 minput_reset_ic() は Minput_reset に対応するコールバック関数 を呼ぶことによって入力コンテクスト ic をリセットする。リセットとは、 実際には入力メソッドを初期状態に移すことである。現在入力中のテキス トはコミットされることなく削除されるので、アプリケーションプログラ ムは、必要ならば予め minput_filter() を引数 key Mnil で呼んで 強制的にプリエディットテキストをコミットさせること。
関数 minput_get_description() は、language と name によって指定 された入力メソッドを説明する M-text を返す。
NULL を返す。 関数 minput_get_title_icon() は、 language と name で指定される 入力メソッドのタイトルと（あれば）アイコン用ファイルを含む plist を 返す。
plist の第一要素は、Mtext をキーに持ち、値は入力メソッドを識別する タイトルを表す M-text である。第二要素があれば、キーは Mtext であ り、値は識別用アイコン画像ファイルの絶対パスを表す M-text である。
関数 minput_get_command() は、language と name で指定される入力 メソッドのコマンド command に関する情報を返す。入力メソッドのコマ ンドとは、疑似キーイベントであり、１つ以上の実際の入力キーシークエ ンスが割り当てられる。
コマンドには、グローバルとローカルの２種類がある。グローバルなコマンド はグローバルに定義され、ローカルなコマンドはその説明とキー割り当て を継承することができる。各入力メソッドはローカルなキー割当を持つロー カルなコマンドを定義する。また同名のグローバルなコマンドの定義を継 承するローカルなコマンドを宣言することもできる。
language が Mt で name が Mnil の場合は、この関数はグローバルコ マンドに関する情報を返す。そうでなければローカルコマンドに関するも のを返す。
command が Mnil の場合は、すべてのコマンドに関する情報を返す。
戻り値は以下の形式の well-formed plist (プロパティリスト) である。
((NAME DESCRIPTION STATUS [KEYSEQ ...]) ...)
NAME はコマンド名を示すシンボルである。
DESCRIPTION はコマンドを説明する M-text であるか、説明が無い場合に は Mnil である。
STATUS はキー割り当てがどのように定められるかをあらわすシンボル であり、その値は Mnil （デフォルトの割り当て）, Mcustomized （ユー ザ毎のカスタマイズファイルによってカスタマイズされた割り当て）, Mconfigured （minput_config_command()を呼ぶことによって設定される 割り当て）のいずれかである。ローカルコマンドの場合には、 Minherited （対応するグローバルコマンドからの継承による割り当て） でもよい。
KEYSEQ は１つ以上のシンボルからなる plist であり、各シンボルはコマ ンドに割り当てられているキーシークエンスを表す。KEYSEQ が無い場合は、 そのコマンドは現状で使用不能である。（すなわちコマンドの動作を起 動できるキーシークエンスが無い。）
command が Mnil でなければ、返される plist の最初の要素は、 command に関する情報を含む。
そうでなければ、すなわち指定の入力メソッドやコマンドが存在しなければ NULL を返す。
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 STATUS KEY-SEQ ...) */ plist = mplist_next (plist); /* (DESCRIPTION STATUS KEY-SEQ ...) */ return (mplist_key (plist) == Mtext ? (MText *) mplist_value (plist) : NULL); }
関数 minput_config_command() はキーシークエンスのリスト keyseqlist を、language と name によって指定される入力メソッドの コマンド command に割り当てる。
keyseqlist が空リストでなければ、キーシークエンスのリストであり、 各キーシークエンスはシンボルの plist である。
keyseqlist が空の plist ならば、そのコマンドの設定やカスタマイズは すべてキャンセルされ、デフォルトのキーシークエンスが有効になる。
keyseqlist が NULL であれば、そのコマンドの設定はキャンセルされ、 元のキーシークエンス（ユーザ毎のカスタマイズファイルに保存されてい るもの、あるいはデフォルトのもの）が有効になる。
後のふたつの場合には、command は Mnil をとることができ、指定の入 力メソッドの全てのコマンド設定のキャンセルを意味する。
name が Mnil ならば、この関数は個々の入力メソッドではなくグローバ ルなコマンドのキー割り当てを設定する。
これらの設定は、現行のセッション中で入力メソッドがオープン（または 再オープン）された時点で有効になる。将来のセッション中でも有効にす るためには、関数 minput_save_config() を用いてユーザ毎のカスタマイ ズファイルに保存しなくてはならない。
/* 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_get_variable() は、language と name で指定される入力 メソッドの変数 variable に関する情報を返す。入力メソッドの変数とは、 入力メソッドの振舞を制御するものである。
変数には、グローバルとローカルの２種類がある。グローバルな変数はグ ローバルに定義され、ローカルな変数はその説明と値を継承することがで きる。各入力メソッドはローカルな値を持つローカルな変数を定義する。 また同名のグローバルな変数の定義を継承するローカルな変数を宣言する こともできる。
language が Mt で name が Mnil の場合は、この関数はグローバル変 数に関する情報を返す。そうでなければローカル変数に関するものを返す。
variable が Mnil の場合は、すべてのコマンドに関する情報を返す。
戻り値は以下の形式の well-formed plist (プロパティリスト) である。
((NAME DESCRIPTION STATUS VALUE [VALID-VALUE ...]) ...)
NAME は変数の名前を示すシンボルである。
DESCRIPTION は変数を説明する M-text であるか、説明が無い場合には Mnil である。
STATUS は値がどのように定められるかをあらわすシンボルであり、 STATUS の値は Mnil （デフォルトの値）, Mcustomized （ユーザ毎の カスタマイズファイルによってカスタマイズされた値）, Mconfigured （minput_config_variable()を呼ぶことによって設定される値）のいずれ かである。ローカル変数の場合には、Minherited （対応するグローバル 変数から継承した値）でもよい。
VALUE は変数の初期値である。この要素のキーがMt であれば初期値を持 たない。そうでなければ、キーは Minteger, Msymbol, Mtext のいずれ かであり、値はそれぞれ対応する型のものである。
VALID-VALUE はもしあれば、変数の取り得る値を指定する。これは VALUE と同じ型(すなわち同じキーを持つ) であるが、例外として VALUE が integer の場合は VALID-VALUE は可能な値の範囲を示す二つの整数から なる plist となることができる。
VALID-VALUE がなければ、変数は VALUE と同じ型である限りいかなる値も とることができる。
variable が Mnil でなければ、返される plist の最初の要素は variable に関する情報を含む。
そうでなければ、すなわち指定の入力メソッドや変数が存在しなければ NULL を返す。
関数 minput_config_variable() は値 value を、language と name によって指定される入力メソッドの変数 variable に割り当てる。
value が 空リストでなければ、１要素の plist であり、そのキーは Minteger, Msymbol, Mtext のいずれか、値は対応する型のものである。 この値が変数 variable に割り当てられる。
value が 空リストであれば、変数の設定とカスタマイズがキャンセルさ れ、デフォルト値が変数 variable に割り当てられる。
value が NULL であれば、変数の設定はキャンセルされ、元の値（ユーザ 毎のカスタマイズファイル中の値、またはデフォルトの値）が割り当てられる。
後のふたつの場合には、variable は Mnil をとることができ、指定され た入力メソッドの全ての変数設定のキャンセルを意味する。
name が Mnil ならば、この関数は個々の入力メソッドではなくグローバ ルな変数の値を設定する。
これらの設定は、現行のセッション中で入力メソッドがオープン（または 再オープン）された時点で有効になる。将来のセッション中でも有効にす るためには、関数 minput_save_config() を用いてユーザ毎のカスタマイ ズファイルに保存しなくてはならない。
| char * minput_config_file | ( | ) |
関数 minput_config_file() は、関数 minput_save_config() が設定を 保存するユーザ毎のカスタマイズファイルへの絶対パス名を返す。通常は、ユーザ のホームディレクトリの下のディレクトリ ".m17n.d" にある"config.mic" となる。返された名前のファイルが存在するか、読み書きで きるかは保証されない。関数minput_save_config() が失敗して -1 を返 した場合には、アプリケーションプログラムはファイルの存在を確認し、 （できれば）書き込み可能にし再度minput_save_config() を試すことが できる。
| int minput_save_config | ( | void | ) |
関数 minput_save_config() は現行のセッションでこれまでに行った設定 をユーザ毎のカスタマイズファイルに保存する。
| int minput_callback | ( | MInputContext * | ic, | |
| MSymbol | command | |||
| ) |
関数 minput_get_variables() は、language と name によって指定さ れた入力メソッドの振る舞いを制御する変数のプロパティリスト (MPlist) を返す。このリストは well-formed であり(プロパティリスト) 以 下の形式である。
(VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
...)
VARNAME は変数の名前を示すシンボルである。
DOC-MTEXT は変数を説明する M-text である。
DEFAULT-VALUE は変数のデフォルト値であり、シンボル、整数もしくは M-text である。
VALUE は、もし指定されていれば変数の取り得る値を示す。もし DEFAULT-VALUE が整数なら、 VALUE は (FROM TO) という形 のリストでも良い。この場合 FROM と TO は可能な値の範囲を示す。
例として、ある入力メソッドが次のような変数を持つ場合を考えよう。
(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" ""))
NULL を返す。 関数 minput_get_commands() は、 language と name によって指定さ れた入力メソッドの入力メソッドコマンドに関する情報を返す。入力メソッ ドコマンドとは、疑似キーイベントであり、それぞれに１つ以上の実際の 入力キーシークエンスが割り当てられているものを指す。
コマンドにはグローバルとローカルの２種類がある。グローバルコマンド は複数の入力メソッドにおいて、同じ目的で、グローバルなキー割り当て で用いられる。ローカルコマンドは特定の入力メソッドでのみ、ローカル なキー割当で使用される。
個々の入力メソッドはグローバルコマンドのキー割当を変更することもで きる。グローバルコマンド用のグローバルキー割り当ては、使用する入力 メソッドにおいてそのコマンド用のローカルなキー割当が存在しない場合 にのみ有効である。
name が Mnil であれば、グローバルコマンドに関する情報を返す。この 場合、language は無視される。
name が Mnil でなければ、language と name によって指定される入 力メソッドに置けるローカルなキー割り当てを持つコマンドに関する情報 を返す。
NULL を返す。COMMAND-INFO の第一要素のキーは Mtext または Msymbol である。キー が Mtext なら、値はそのコマンドを説明する M-text である。キーが Msymbol なら値は Mnil であり、このコマンドは説明テキストを持たな いことになる。
それ以外の要素が無ければ、このコマンドに対してキーシークエンスが割 り当てられていないことを意味する。そうでなければ、残りの各要素はキ ーとしてMplist を、値としてプロパティリストを持つ。このプロパティ リストのキーは Msymbol であり、値は現在そのコマンドに割り当てられ ている入力キーを表すシンボルである。
返されるプロパティリストはライブラリによって管理されており、呼び出 し側で変更したり解放したりしてはならない。
関数 minput_assign_command_keys() は、 language と name によって 指定された入力メソッド用の入力メソッドコマンド command に対して、 入力キーシークエンス keyseq を割り当てる。 name が Mnil ならば、 language に関係なく、入力キーシークエンスはグローバルに割り当てら れる。そうでなれば、割り当てはローカルである。
keyseq の各要素はキーとして msymbol を、値として入力キーを表すシ ンボルを持たなくてはならない。
keyseq は NULL でもよい。この場合、グローバルもしくはローカルな すべての割り当てが消去される。
この割り当ては、割り当て以降新しくオープンされた入力メソッドから有 効になる。
関数 minput_get_variables() は、language と name によって指定さ れた入力メソッドの振る舞いを制御する変数のプロパティリスト (MPlist) を返す。このリストは well-formed であり(プロパティリスト) 以 下の形式である。
(VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
VARNAME (DOC-MTEXT DEFAULT-VALUE [ VALUE ... ] )
...)
VARNAME は変数の名前を示すシンボルである。
DOC-MTEXT は変数を説明する M-text である。
DEFAULT-VALUE は変数のデフォルト値であり、シンボル、整数もしくは M-text である。
VALUE は、もし指定されていれば変数の取り得る値を示す。もし DEFAULT-VALUE が整数なら、 VALUE は (FROM TO) という形 のリストでも良い。この場合 FROM と TO は可能な値の範囲を示す。
例として、ある入力メソッドが次のような変数を持つ場合を考えよう。
(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" ""))
NULL を返す。 関数 minput_set_variable() は、language と name によって指定された入力メソッドの入力メソッド変数 variable の初期値を、 value に設定する。
デフォルトの初期値は 0 である。
この設定は、新しくオープンされた入力メソッドから有効となる。
変数 minput_default_driver は内部入力メソッド用のデフォルトのドライバを表す。
メンバ MInputDriver::open_im() は m17n データベース中からタグ < Minput_method, language, name> に合致する入力メソッドを探し、それをロードする。
メンバ MInputDriver::callback_list() は NULL であり、 したがって、プログラマ側で責任を持って 適切なコールバック関数の plist に設定しなくてはならない。さもないと、preedit テキストなどのフィードバック情報がユーザに表示されない。
マクロ M17N_INIT() は変数 minput_driver をこのドライバへのポインタに設定し、全ての内部入力メソッドがこのドライバを使うようにする。
したがって、minput_driver がデフォルト値のままであれば、minput_ で始まる関数のドライバに依存する引数 arg はすべて無視される。
変数 minput_driver は内部入力メソッドによって使用されている入力メ ソッドドライバへのポインタである。マクロ M17N_INIT() はこのポイン タをminput_default_driver (<m17n.h> が include されている 時) に初期化する。
変数 minput_default_driver は内部入力メソッド用のデフォルトのドライバを表す。
メンバ MInputDriver::open_im() は m17n データベース中からタグ < Minput_method, language, name> に合致する入力メソッドを探し、それをロードする。
メンバ MInputDriver::callback_list() は NULL であり、 したがって、プログラマ側で責任を持って 適切なコールバック関数の plist に設定しなくてはならない。さもないと、preedit テキストなどのフィードバック情報がユーザに表示されない。
マクロ M17N_INIT() は変数 minput_driver をこのドライバへのポインタに設定し、全ての内部入力メソッドがこのドライバを使うようにする。
したがって、minput_driver がデフォルト値のままであれば、minput_ で始まる関数のドライバに依存する引数 arg はすべて無視される。
変数 minput_driver は内部入力メソッドによって使用されている入力メ ソッドドライバへのポインタである。マクロ M17N_INIT() はこのポイン タをminput_default_driver (<m17n.h> が include されている 時) に初期化する。