入力メソッド (基本部分)

入力メソッド用API. [詳解]

データ構造
struct	MInputDriver
	入力ドライバ用構造体. [詳解]
struct	MInputMethod
	入力メソッドの構造体. [詳解]
struct	MInputContext
	入力コンテクスト用構造体. [詳解]

型定義
typedef void(*	MInputCallbackFunc) (MInputContext *ic, MSymbol command)
	入力メソッドコールバック関数の型宣言.

列挙型
enum	MInputCandidatesChanged {   MINPUT_CANDIDATES_LIST_CHANGED = 1 ,   MINPUT_CANDIDATES_INDEX_CHANGED = 2 ,   MINPUT_CANDIDATES_SHOW_CHANGED = 4 ,   MINPUT_CANDIDATES_CHANGED_MAX }
	入力メソッドの入力候補がどう変更されたかを示すビットマスク. [詳解]

変数
MSymbol	Minput_method
	"input-method" を名前として持つシンボル.
MInputDriver	minput_default_driver
	内部入力メソッド用デフォルトドライバ.
MInputDriver *	minput_driver
	内部入力メソッド用ドライバ.
MSymbol	Minput_driver

変数： コールバックコマンド用定義済みシンボル.
入力メソッドドライバのコールバック関数において COMMAND 引数として用いられる定義済みシンボル (MInputDriver::callback_list 参照)。 ほとんどは追加の引数を必要としないし値を返さないが、以下は例外である。 Minput_get_surrounding_text: このコマンドに割り当てられたコールバッ ク関数が呼ばれた際には、 MInputContext::plist の第一要素はキーとし て::Minteger をとり、その値はサラウンディングテキストのうちどの部分 を取って来るかを指定する。値が正であれば、現在のカーソル位置に続く 値の個数分の文字を取る。負であれば、カーソル位置に先行する値の絶対 値分の文字を取る。現在サラウンドテキストがサポートされているかどう かを知りたいだけであれば、この値はゼロでも良い。 サラウンディングテキストがサポートされていれば、コールバック関数は この要素のキーを Mtext に、値を取り込んだM-text に設定しなくてはな らない。もしテキストの長さが充分でなければ、この M-text の長さは要 求されている文字数より短くて良い。最悪の場合 0 でもよいし、アプリケー ション側で必要で効率的だと思えば長くても良い。 サラウンディングテキストがサポートされていなければ、コールバック関 数は MInputContext::plist の第一要素を変更してはならない。 Minput_delete_surrounding_text: このコマンドに割り当てられたコール バック関数が呼ばれた際には、::MInputContext::plist の第一要素は、キー として::Minteger をとり、値は削除するべきサラウンディングテキストを Minput_get_surrounding_text と同様のやり方で指定する。コールバック 関数は指定されたテキストを削除しなければならない。また 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

変数: 特別な入力イベント用定義済みシンボル.
minput_filter() の KEY 引数として用いられる定義済みシンボル。
MSymbol	Minput_focus_out
MSymbol	Minput_focus_in
MSymbol	Minput_focus_move

変数: 入力メソッド情報用定義済みシンボル.
MSymbol	Minherited
MSymbol	Mcustomized
MSymbol	Mconfigured

関数
MInputMethod *	minput_open_im (MSymbol language, MSymbol name, void *arg)
	入力メソッドをオープンする.
void	minput_close_im (MInputMethod *im)
	入力メソッドをクローズする.
MInputContext *	minput_create_ic (MInputMethod *im, void *arg)
	入力コンテクストを生成する.
void	minput_destroy_ic (MInputContext *ic)
	入力コンテクストを破壊する.
int	minput_filter (MInputContext *ic, MSymbol key, void *arg)
	入力キーをフィルタする.
int	minput_lookup (MInputContext *ic, MSymbol key, void *arg, MText *mt)
	入力コンテクスト中のテキストを探す.
void	minput_set_spot (MInputContext *ic, int x, int y, int ascent, int descent, int fontsize, MText *mt, int pos)
	入力コンテクストのスポットを設定する.
void	minput_toggle (MInputContext *ic)
	入力メソッドを切替える.
void	minput_reset_ic (MInputContext *ic)
	入力コンテクストをリセットする.
MPlist *	minput_get_title_icon (MSymbol language, MSymbol name)
	入力メソッドのタイトルとアイコン用ファイル名を得る.
MText *	minput_get_description (MSymbol language, MSymbol name)
	入力メソッドの説明テキストを得る.
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)
	入力メソッドの変数の値を設定する.
char *	minput_config_file ()
	ユーザ毎のカスタマイズファイルの名前を得る.
int	minput_save_config (void)
	設定をユーザ毎のカスタマイズファイルに保存する.
MPlist *	minput_list (MSymbol language)

Obsolete な関数
MPlist *	minput_get_variables (MSymbol language, MSymbol name)
int	minput_set_variable (MSymbol language, MSymbol name, MSymbol variable, void *value)
	入力メソッド変数の初期値を設定する.
MPlist *	minput_get_commands (MSymbol language, MSymbol name)
	入力メソッドのコマンドに関する情報を得る.
int	minput_assign_command_keys (MSymbol language, MSymbol name, MSymbol command, MPlist *keyseq)
	入力メソッドコマンドにキーシークエンスを割り当てる.
MPlist *	minput_parse_im_names (MText *mt)
int	minput_callback (MInputContext *ic, MSymbol command)

詳解

入力メソッド用API.

入力メソッドは多様な文字を入力するためのオブジェクトである。 入力メソッドはシンボル LANGUAGE と NAME の組によって識別され、 この組合せによって入力メソッドドライバが決定する。 入力メソッドドライバとは、ある入力メソッドを扱うための関数の集まりである。 入力メソッドには内部メソッドと外部メソッドの二種類がある。

• 内部入力メソッド

  内部入力メソッドとは 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 のドキュメントを参照のこと。

処理の流れ

入力メソッド処理の典型的な処理は以下のようになる。

• 入力メソッドのオープン
• その入力メソッドの入力コンテクストの生成
• 入力イベントのフィルタ
• 入力コンテクストでの生成テキストの検索

型定義詳解

MInputCallbackFunc

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

入力メソッドコールバック関数の型宣言.

入力メソッドから呼ばれるコールバック関数の型である。ic は入力コンテクストへのポインタ、command は関数が呼ばれるコールバックの名前である。

列挙型詳解

MInputCandidatesChanged

enum MInputCandidatesChanged

入力メソッドの入力候補がどう変更されたかを示すビットマスク.

列挙値
MINPUT_CANDIDATES_LIST_CHANGED
MINPUT_CANDIDATES_INDEX_CHANGED
MINPUT_CANDIDATES_SHOW_CHANGED
MINPUT_CANDIDATES_CHANGED_MAX

関数詳解

minput_open_im()

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 に設定され、ドライバから参照できる。

minput_close_im()

void minput_close_im

(

MInputMethod *

im

)

入力メソッドをクローズする.

関数 minput_close_im() は、入力メソッド im をクローズする。 この入力メソッド im は minput_open_im() によって作られたものでなければならない。

minput_create_ic()

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

入力コンテクストを生成する.

関数 minput_create_ic() は入力メソッド im に対応する入力コンテクストオブジェクトを生成し、 Minput_preedit_start, Minput_status_start, Minput_status_draw に対応するコールバック関数をこの順に呼ぶ。

戻り値:

入力コンテクストが生成された場合、minput_create_ic() はその入力コンテクストへのポインタを返す。失敗した場合は NULL を返す。

minput_destroy_ic()

void minput_destroy_ic

(

MInputContext *

ic

)

入力コンテクストを破壊する.

関数 minput_destroy_ic() は、入力コンテクスト ic を破壊する。 この入力コンテクストは minput_create_ic() によって作られたものでなければならない。この関数は Minput_preedit_done, Minput_status_done, Minput_candidates_done に対応するコールバック関数をこの順に呼ぶ。

minput_filter()

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

入力キーをフィルタする.

関数 minput_filter() は入力キー key を入力コンテクスト ic に応じてフィルタし、preedit テキスト、ステータス、現時点での候補が変化した時点で、それぞれ Minput_preedit_draw, Minput_status_draw, Minput_candidates_draw に対応するコールバック関数を呼ぶ。

戻り値:

key がフィルタされれば、この関数は 1 を返す。 この場合呼び出し側はこのキーを捨てるべきである。 そうでなければ 0 を返し、呼び出し側は、たとえば同じキーで関数 minput_lookup() を呼ぶなどして、このキーを処理する。

minput_lookup()

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

入力コンテクスト中のテキストを探す.

関数 minput_lookup() は入力コンテクスト ic 中のテキストを探す。 key は関数 minput_filter() への直前の呼び出しに用いられたものと同じでなくてはならない。

テキストが入力メソッドによって生成されていれば、テキストは M-text mt に連結される。

この関数は、::MInputDriver::lookup を呼ぶ。

戻り値:

key が入力メソッドによって適切に処理できれば、この関数は 0 を返す。 そうでなければ -1 を返す。 この場合でも mt に何らかのテキストが生成されていることがある。

minput_set_spot()

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 でもよく、その場合には入力メソッドはスポット周辺のテキストに関する情報を得ることができない。

minput_toggle()

void minput_toggle

(

MInputContext *

ic

)

入力メソッドを切替える.

関数 minput_toggle() は入力コンテクスト ic に対応付けられた入力メソッドをトグルする。

minput_reset_ic()

void minput_reset_ic

(

MInputContext *

ic

)

入力コンテクストをリセットする.

関数 minput_reset_ic() は Minput_reset に対応するコールバック関数 を呼ぶことによって入力コンテクスト ic をリセットする。リセットとは、 実際には入力メソッドを初期状態に移すことである。現在入力中のテキス トはコミットされることなく削除されるので、アプリケーションプログラ ムは、必要ならば予め minput_filter() を引数 key Mnil で呼んで 強制的にプリエディットテキストをコミットさせること。

minput_get_title_icon()

MPlist * minput_get_title_icon	(	MSymbol	language,
		MSymbol	name
	)

入力メソッドのタイトルとアイコン用ファイル名を得る.

関数 minput_get_title_icon() は、 language と name で指定される 入力メソッドのタイトルと（あれば）アイコン用ファイルを含む plist を 返す。

plist の第一要素は、::Mtext をキーに持ち、値は入力メソッドを識別する タイトルを表す M-text である。第二要素があれば、キーは Mtext であ り、値は識別用アイコン画像ファイルの絶対パスを表す M-text である。

戻り値:

指定の入力メソッドが存在し、タイトルが定義されていれば plist を返す。そうでなければ NULL を返す。呼出側は 関数 m17n_object_unref() を用いて plist を解放しなくてはならない。

minput_get_description()

MText * minput_get_description	(	MSymbol	language,
		MSymbol	name
	)

入力メソッドの説明テキストを得る.

関数 minput_get_description() は、language と name によって指定 された入力メソッドを説明する M-text を返す。

戻り値:

指定された入力メソッドが説明するテキストを持っていれば、 MText へのポインタを返す。呼び出し側は、それを m17n_object_unref () を用いて解放しなくてはならない。入力メソッドに説明テキストが無け ればNULL を返す。

minput_get_command()

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

@brief 入力メソッドのコマンドに関する情報を得る.

関数 minput_get_command() は、@b language と @b name で指定される入力
メソッドのコマンド @b command に関する情報を返す。入力メソッドのコマ
ンドとは、疑似キーイベントであり、１つ以上の実際の入力キーシークエ
ンスが割り当てられる。

コマンドには、グローバルとローカルの２種類がある。グローバルなコマンド
はグローバルに定義され、ローカルなコマンドはその説明とキー割り当て
を継承することができる。各入力メソッドはローカルなキー割当を持つロー
カルなコマンドを定義する。また同名のグローバルなコマンドの定義を継
承するローカルなコマンドを宣言することもできる。

@b language が #Mt で @b name が #Mnil の場合は、この関数はグローバルコ
マンドに関する情報を返す。そうでなければローカルコマンドに関するも
のを返す。

@b command が #Mnil の場合は、すべてのコマンドに関する情報を返す。

戻り値は以下の形式の @e well-formed plist (@ref m17nPlist) である。

  ((NAME DESCRIPTION STATUS [KEYSEQ ...]) ...)

NAME はコマンド名を示すシンボルである。

DESCRIPTION はコマンドを説明する M-text であるか、説明が無い場合に は Mnil である。

STATUS はキー割り当てがどのように定められるかをあらわすシンボル であり、その値は Mnil （デフォルトの割り当て）, Mcustomized （ユー ザ毎のカスタマイズファイルによってカスタマイズされた割り当て）, Mconfigured （minput_config_command()を呼ぶことによって設定される 割り当て）のいずれかである。ローカルコマンドの場合には、 Minherited （対応するグローバルコマンドからの継承による割り当て） でもよい。

KEYSEQ は１つ以上のシンボルからなる plist であり、各シンボルはコマ ンドに割り当てられているキーシークエンスを表す。KEYSEQ が無い場合は、 そのコマンドは現状で使用不能である。（すなわちコマンドの動作を起 動できるキーシークエンスが無い。）

command が Mnil でなければ、返される plist の最初の要素は、 command に関する情報を含む。

戻り値:

求められた情報が見つかれば、空でない plist へのポインタを返す。リス トはライブラリが管理しているので、呼出側が変更したり解放したりする ことはできない。

そうでなければ、すなわち指定の入力メソッドやコマンドが存在しなければ 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 (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_config_command()

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

@brief 入力メソッドのコマンドのキーシークエンスを設定する.

関数 minput_config_command() はキーシークエンスのリスト
@b keyseqlist を、@b language と @b name によって指定される入力メソッドの
コマンド @b command に割り当てる。

@b keyseqlist が空リストでなければ、キーシークエンスのリストであり、
各キーシークエンスはシンボルの plist である。

@b keyseqlist が空の plist ならば、そのコマンドの設定やカスタマイズは
すべてキャンセルされ、デフォルトのキーシークエンスが有効になる。

@b keyseqlist が NULL であれば、そのコマンドの設定はキャンセルされ、
元のキーシークエンス（ユーザ毎のカスタマイズファイルに保存されてい
るもの、あるいはデフォルトのもの）が有効になる。

後のふたつの場合には、@b command は #Mnil をとることができ、指定の入
力メソッドの全てのコマンド設定のキャンセルを意味する。

@b name が #Mnil ならば、この関数は個々の入力メソッドではなくグローバ
ルなコマンドのキー割り当てを設定する。

これらの設定は、現行のセッション中で入力メソッドがオープン（または
再オープン）された時点で有効になる。将来のセッション中でも有効にす
るためには、関数 minput_save_config() を用いてユーザ毎のカスタマイ
ズファイルに保存しなくてはならない。

@par 戻り値:

この関数は、処理が成功すれば 0 を、失敗すれば -1 を返す。失敗とは以下の場合である。
<ul>
<li>@b keyseqlist が有効な形式でない。
<li>@b command が指定の入力メソッドで利用できない。
<li>@b language と @b name で指定される入力メソッドが存在しない。
</ul>

@par 参照:
minput_get_commands(), 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()

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

@brief 入力メソッドの変数に関する情報を得る.

関数 minput_get_variable() は、@b language と @b name で指定される入力
メソッドの変数 @b variable に関する情報を返す。入力メソッドの変数とは、
入力メソッドの振舞を制御するものである。

変数には、グローバルとローカルの２種類がある。グローバルな変数はグ
ローバルに定義され、ローカルな変数はその説明と値を継承することがで
きる。各入力メソッドはローカルな値を持つローカルな変数を定義する。
また同名のグローバルな変数の定義を継承するローカルな変数を宣言する
こともできる。

@b language が #Mt で @b name が #Mnil の場合は、この関数はグローバル変
数に関する情報を返す。そうでなければローカル変数に関するものを返す。

@b variable が #Mnil の場合は、すべてのコマンドに関する情報を返す。

戻り値は以下の形式の @e well-formed plist (@ref m17nPlist) である。

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

@c NAME は変数の名前を示すシンボルである。

@c DESCRIPTION は変数を説明する M-text であるか、説明が無い場合には
#Mnil である。

@c STATUS は値がどのように定められるかをあらわすシンボルであり、
@c STATUS の値は #Mnil （デフォルトの値）, @b Mcustomized （ユーザ毎の
カスタマイズファイルによってカスタマイズされた値）, @b Mconfigured
（minput_config_variable()を呼ぶことによって設定される値）のいずれ
かである。ローカル変数の場合には、@b Minherited （対応するグローバル
変数から継承した値）でもよい。

@c VALUE は変数の初期値である。この要素のキーが#Mt であれば初期値を持
たない。そうでなければ、キーは #Minteger, #Msymbol, #Mtext のいずれ
かであり、値はそれぞれ対応する型のものである。

@c VALID-VALUE はもしあれば、変数の取り得る値を指定する。これは @c VALUE
と同じ型(すなわち同じキーを持つ) であるが、例外として @c VALUE が
integer の場合は @c VALID-VALUE は可能な値の範囲を示す二つの整数から
なる plist となることができる。

@c VALID-VALUE がなければ、変数は @c VALUE と同じ型である限りいかなる値も
とることができる。

@b variable が #Mnil でなければ、返される plist の最初の要素は
@b variable に関する情報を含む。

@par 戻り値:

求められた情報が見つかれば、空でない plist へのポインタを返す。リス
トはライブラリが管理しているので、呼出側が変更したり解放したりする
ことはできない。

そうでなければ、すなわち指定の入力メソッドや変数が存在しなければ
@c NULL を返す。

minput_config_variable()

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

入力メソッドの変数の値を設定する.

関数 minput_config_variable() は値 value を、language と name によって指定される入力メソッドの変数 variable に割り当てる。

value が 空リストでなければ、１要素の plist であり、そのキーは Minteger, Msymbol, Mtext のいずれか、値は対応する型のものである。 この値が変数 variable に割り当てられる。

value が 空リストであれば、変数の設定とカスタマイズがキャンセルさ れ、デフォルト値が変数 variable に割り当てられる。

value が NULL であれば、変数の設定はキャンセルされ、元の値（ユーザ 毎のカスタマイズファイル中の値、またはデフォルトの値）が割り当てられる。

後のふたつの場合には、variable は Mnil をとることができ、指定され た入力メソッドの全ての変数設定のキャンセルを意味する。

name が Mnil ならば、この関数は個々の入力メソッドではなくグローバ ルな変数の値を設定する。

これらの設定は、現行のセッション中で入力メソッドがオープン（または 再オープン）された時点で有効になる。将来のセッション中でも有効にす るためには、関数 minput_save_config() を用いてユーザ毎のカスタマイ ズファイルに保存しなくてはならない。

戻り値:

この関数は、処理が成功すれば 0 を、失敗すれば -1 を返す。失敗とは以下の場合である。

• valueが有効な形式でない。型が定義に合わない、または値が範囲外である。
• variable が指定の入力メソッドで利用できない。
• language と name で指定される入力メソッドが存在しない。

参照:

minput_get_commands(), minput_save_config().

minput_config_file()

char * minput_config_file

(

void

)

ユーザ毎のカスタマイズファイルの名前を得る.

関数 minput_config_file() は、関数 minput_save_config() が設定を 保存するユーザ毎のカスタマイズファイルへの絶対パス名を返す。通常は、ユーザ のホームディレクトリの下のディレクトリ ".m17n.d" にある"config.mic" となる。返された名前のファイルが存在するか、読み書きで きるかは保証されない。関数minput_save_config() が失敗して -1 を返 した場合には、アプリケーションプログラムはファイルの存在を確認し、 （できれば）書き込み可能にし再度minput_save_config() を試すことが できる。

戻り値:

この関数は文字列を返す。文字列はライブラリが管理しているので、呼出 側が修正したり解放したりすることはできない。

参照:

minput_save_config()

minput_save_config()

int minput_save_config

(

void

)

設定をユーザ毎のカスタマイズファイルに保存する.

関数 minput_save_config() は現行のセッションでこれまでに行った設定 をユーザ毎のカスタマイズファイルに保存する。

戻り値:

成功すれば 1 を返す。ユーザ毎のカスタマイズファイルがロックされてい れば 0 を返す。この場合、呼出側はしばらく待って再試行できる。設定ファ イルが書き込み不可の場合、-1 を返す。この場合、minput_config_file () を呼んでファイル名をチェックし、できれば書き込み可能にし、再試行 できる。

参照:

minput_config_file()

minput_list()

MPlist * minput_list

(

MSymbol

language

)

例：

#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_get_variables()

MPlist * minput_get_variables	(	MSymbol	language,
		MSymbol	name
	)

@brief 入力メソッドの変数リストを得る.

関数 minput_get_variables() は、@b language と @b name によって指定さ
れた入力メソッドの振る舞いを制御する変数のプロパティリスト
(#MPlist) を返す。このリストは @e well-formed であり(@ref m17nPlist) 以
下の形式である。

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

@c VARNAME は変数の名前を示すシンボルである。

@c DOC-MTEXT は変数を説明する M-text である。

@c DEFAULT-VALUE は変数のデフォルト値であり、シンボル、整数もしくは
M-text である。

@c VALUE は、もし指定されていれば変数の取り得る値を示す。もし
@c DEFAULT-VALUE が整数なら、 @c VALUE は (@c FROM @c TO) という形
のリストでも良い。この場合 @c FROM と @c TO は可能な値の範囲を示す。

例として、ある入力メソッドが次のような変数を持つ場合を考えよう。

@li name:intvar, 説明:"value is an integer",
    初期値:0, 値の範囲:0..3,10,20

@li name:symvar, 説明:"value is a symbol",
     初期値:nil, 値の範囲:a, b, c, nil

@li name:txtvar, 説明:"value is an M-text",
    初期値:empty text, 値の範囲なし(どんな M-text でも可)

この場合、返されるリストは以下のようになる。

    (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 戻り値: 
入力メソッドが何らかの変数を使用していれば #MPlist へのポインタを返す。
返されるプロパティリストはライブラリによって管理されており、呼び出し側で変更したり解放したりしてはならない。
入力メソッドが変数を一切使用してなければ、@c NULL を返す。

minput_set_variable()

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

入力メソッド変数の初期値を設定する.

関数 minput_set_variable() は、language と name によって指定された入力メソッドの入力メソッド変数 variable の初期値を、 value に設定する。

デフォルトの初期値は 0 である。

この設定は、新しくオープンされた入力メソッドから有効となる。

戻り値:

処理が成功すれば 0 を返す。そうでなければ -1 を返し、 merror_code を MERROR_IM に設定する。

minput_get_commands()

MPlist * minput_get_commands	(	MSymbol	language,
		MSymbol	name
	)

入力メソッドのコマンドに関する情報を得る.

関数 minput_get_commands() は、 language と name によって指定さ れた入力メソッドの入力メソッドコマンドに関する情報を返す。入力メソッ ドコマンドとは、疑似キーイベントであり、それぞれに１つ以上の実際の 入力キーシークエンスが割り当てられているものを指す。

コマンドにはグローバルとローカルの２種類がある。グローバルコマンド は複数の入力メソッドにおいて、同じ目的で、グローバルなキー割り当て で用いられる。ローカルコマンドは特定の入力メソッドでのみ、ローカル なキー割当で使用される。

個々の入力メソッドはグローバルコマンドのキー割当を変更することもで きる。グローバルコマンド用のグローバルキー割り当ては、使用する入力 メソッドにおいてそのコマンド用のローカルなキー割当が存在しない場合 にのみ有効である。

name が Mnil であれば、グローバルコマンドに関する情報を返す。この 場合、language は無視される。

name が Mnil でなければ、language と name によって指定される入 力メソッドに置けるローカルなキー割り当てを持つコマンドに関する情報 を返す。

戻り値:

入力メソッドコマンドが見つからなければ、この関数は NULL を返す。

そうでなければプロパティリストへのポインタを返す。リストの各要素の キーは個々のコマンドを示すシンボルであり、値は下記の COMMAND-INFO の形式のプロパティリストである。

COMMAND-INFO の第一要素のキーは Mtext または Msymbol である。キー が Mtext なら、値はそのコマンドを説明する M-text である。キーが Msymbol なら値は Mnil であり、このコマンドは説明テキストを持たな いことになる。

それ以外の要素が無ければ、このコマンドに対してキーシークエンスが割 り当てられていないことを意味する。そうでなければ、残りの各要素はキ ーとして::Mplist を、値としてプロパティリストを持つ。このプロパティ リストのキーは Msymbol であり、値は現在そのコマンドに割り当てられ ている入力キーを表すシンボルである。

返されるプロパティリストはライブラリによって管理されており、呼び出 し側で変更したり解放したりしてはならない。

minput_assign_command_keys()

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

入力メソッドコマンドにキーシークエンスを割り当てる.

関数 minput_assign_command_keys() は、 language と name によって 指定された入力メソッド用の入力メソッドコマンド command に対して、 入力キーシークエンス keyseq を割り当てる。 name が Mnil ならば、 language に関係なく、入力キーシークエンスはグローバルに割り当てら れる。そうでなれば、割り当てはローカルである。

keyseq の各要素はキーとして msymbol を、値として入力キーを表すシ ンボルを持たなくてはならない。

keyseq は NULL でもよい。この場合、グローバルもしくはローカルな すべての割り当てが消去される。

この割り当ては、割り当て以降新しくオープンされた入力メソッドから有 効になる。

戻り値:

処理が成功すれば 0 を返す。そうでなければ -1 を返し、 merror_code を MERROR_IM に設定する。

minput_parse_im_names()

MPlist * minput_parse_im_names

(

MText *

mt

)

minput_callback()

int minput_callback	(	MInputContext *	ic,
		MSymbol	command
	)

変数詳解

Minput_method

MSymbol Minput_method

"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

入力メソッドのコマンドや変数の状態を表し、minput_get_command() と minput_get_variable() の戻り値として用いられる定義済みシンボル。

Mcustomized

MSymbol Mcustomized

Mconfigured

MSymbol Mconfigured

minput_default_driver

MInputDriver minput_default_driver

内部入力メソッド用デフォルトドライバ.

変数 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

MInputDriver* minput_driver

内部入力メソッド用ドライバ.

変数 minput_driver は内部入力メソッドによって使用されている入力メ ソッドドライバへのポインタである。マクロ M17N_INIT() はこのポイン タを::minput_default_driver (<m17n.h> が include されている 時) に初期化する。

Minput_driver

MSymbol Minput_driver

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