Chapter 13 Locales and Internationalized Text Functions

13 章: ロケールと国際化テキスト関数群

地域化の機構の一つとして、Xlib には 国際化されたテキスト入力の関数インタフェースである X Input Method (XIM )と国際化されたテキスト出力の関数インタフェースである X Output Method (XOM )が用意されている。

X における国際化は、ロケール(locale)の概念に基づいている。 ロケールは、プログラムの地域化された動作を実行時に定義する。 ロケールは Xlib に以下の点で影響を及ぼす:

• 入力メソッドのテキストのエンコーディングと処理
• リソースファイルとリソース値のエンコーディング
• テキスト文字列のエンコーディングとイメージ化
• クライアント間通信におけるエンコーディングとデコーディング

各種言語の文字は、コンピュータにおいてはエンコーディングを用いて表現さ れる。 異なる言語は異なるエンコーディングを持つが、同じ言語の同じ文字について も異なる複数個のエンコーディングが存在することがある。

この章では、地域化されたテキストのイメージ化とテキスト入力への対応につ いての定義と、ロケールに依存する全ての Xlib 関数を制御するロケール機構 の説明を行う。 ホストの C 言語環境でサポートされる形式として、関数群は マルチバイトテキスト(char *)とワイドキャラクタテキスト(wchar_t)に対し て用意されている。 マルチバイト関数とワイドキャラクタ関数は、テキストを与える引き数の形式 を除くと全く同じものである。

Xlib の国際化関数はマルチリンガル対応アプリケーション(複数の言語が単一 のテキスト内に混在する)に対応する意図で用意されているものではないが、 独立したコンテクストで複数の言語を扱うという限定されたやり方で動作する アプリケーションを実装することは可能である。

この章では以下の内容を議論する:

• X におけるロケール管理
• ロケールとモディファイアの依存性
• 可変長引き数リスト
• 出力メソッド
• 入力メソッド
• 文字列定数

X におけるロケール管理

X はホスト環境で定義されている 1 つあるいはそれ以上のロケールをサポー トしている。 ANSI C ライブラリに準拠する実装においては、ロケールを通知する方法は setlocaleである。 この関数は C ライブラリと Xlib の両方のロケール動作を設定する。 Xlib の動作は LC_CTYPE カテゴリによって管理される。 これは現在のロケール(current locale)と呼ばれる。 実装においては、ロケールを通知する実装独立の機構を setlocale以外にも用意することが許されている。

ANSI C ライブラリに準拠しない実装では、ロケールを通知する方法は Xlib の実装に依存する。

特定のロケールについての Xlib のセマンティック動作を定義する機構は実装 依存である。

X はホストがサポートしている全てのロケールをサポートする必要はない。 X が現在のロケールをサポートしているかどうかを調べるには XSupportsLocaleを用いる。

Bool XSupportsLocale( )

関数 XSupportsLocaleは、Xlib 関数が現在のロケールで動作できる場合に Trueを返す。 この関数が Falseを返した場合、 返却ステータスとして XLocaleNotSupported が定義されている Xlib のロケール依存の関数は XLocaleNotSupportedを返す。 Xlib のその他のロケール依存関数は ``C'' ロケールで動作する。

クライアントにはロケールと X モディファイアを選択する責任がある。 クライアントは、クライアント起動の際にクライアントのロケール選択をユー ザが上書きする方法を用意すべきである。 ディスプレイを 1 つ使う X クライアントの大部分は、X とホスト処理環境の 両方に対して単一のロケールで動作する。 これらのクライアントは 3 つの関数を呼び出すことによってロケールを設定 する: すなわち、ホストのロケール設定関数、 XSupportsLocale ,XSetLocaleModifiersである。

X の国際化機能における特定のカテゴリの意味は、モディファイアを設定する ことにより設定することができる。 モディファイアは実装独立かつロケール依存の文字列によって指示される。 現時点におけるこの機能の唯一の標準的な使い方は、キーボードの入力メソッ ドの複数のスタイルから 1 つを選択することである。

現在のロケールに対する Xlib のロケールモディファイアを設定するには XSetLocaleModifiersを用いる。

char *XSetLocaleModifiers(modifier_list)
char *modifier_list;

modifier_list

モディファイアを指定する。

ローカルホストにおけるデフォルト値を与えるため、ローカルホストの X ロ ケールモディファイアアナウンサ(POSIX 準拠のシステムでは、環境変数 XMODIFIERS)は modifier_list に追加される。 与えられたカテゴリがリスト中に複数回現れる場合には、最初にリストに現れ たものが使われる。 与えられたカテゴリが完全なモディファイアのリストに含まれていない場合、 そのカテゴリには現在のロケールに対する実装依存のデフォルト値が設定され る。 あるカテゴリに対して空の値を設定することにより、実装依存のデフォルト値 を明示的に指定できる。

この関数が成功すると、文字列へのポインタ返される。 この文字列の内容は、後で(同じロケールにおいて)この文字列を使った呼び出 しを行うことにより、モディファイアを同じ設定に復元できるようなものであ る。 modifier_list が NULL ポインタである場合にも XSetLocaleModifiersはこのような文字列へのポインタを返し、現在のロケールモディファイアは変 更されない。

ロケールがサポートしている 1 つ以上のモディファイアカテゴリに対して不 正な値が指定された場合には、NULL ポインタが返され、現在のモディファイ アはどれも変更されない。

プログラムの起動時には、有効になっているモディファイアは、これらを設定 するための関数が最初に成功するまでは未指定である。ロケールが変更される と必ず、有効になっているモディファイアは、これらを設定するための関数が 次に成功するまでは未指定となる。 クライアントは必ず、ロケールを設定した後、かつロケール依存の Xlib 関数 の呼び出しを行う前に、NULL でない modifier_list を使って XSetLocaleModifiersを呼び出さなければならない。

現在定義されている唯一の標準のモディファイアカテゴリは ``im'' である。 これは利用したい入力メソッドを決める。 入力メソッドとして指定する値は標準化されていない。 単一のロケールで複数の入力メソッドを使うことができる。この場合にはユー ザが入力メソッドを制御することができる。 このモディファイアは有効になっている初期入力メソッドを指定することや、 入力メソッドの順序付きリストを指定することができる。 実装依存の方法により、1 つの im の文字列値で複数の入力メソッドを指定す ることができる。

返されるモディファイア文字列は Xlib が所有しているので、クライアントは これを変更したり解放したりしてはならない。 現在のロケールやモディファイアが変更された後、この値は Xlib が解放する 場合がある。 解放されるまでは、Xlib がこの値を変更することはない。

ロケールとモディファイアを初期化するためにクライアントが行うことが望ま しい手続きは、以下に優先度順に示したソースから、ロケールとモディファイ アのアナウンサを個別に取得することである:

• コマンドラインオプション
• リソース
• 空文字列("")

これらのうち、定義されている最初のものを使うべきである。 ロケールに関するコマンドラインオプションやロケールに関するリソースが定 義されている時は、全てのカテゴリが指定されたロケールに設定されるという 結果にならなくてはならない。その際には、ローカルのホスト環境におけるカ テゴリ依存の設定は全て上書きされるべきである。

ロケールとモディファイアの依存関係

Xlib の国際化関数は、ホスト環境と、 XSetLocaleModifiersあるいはその関数が与えられた何らかのオブジェクトが作成された時に設定さ れていたロケールとモディファイアによってセットされた X ロケールモディ ファイアで設定された現在のロケールで動作する。

元となるロケール	関数への影響	影響を与える場所
	ロケールの問い合わせ/設定:
setlocale	XSupportsLocale	問い合わせられるロケール
	XSetLocaleModifiers	変更されたロケール
	リソース:
setlocale	XrmGetFileDatabase	XrmDatabaseのロケール
	XrmGetStringDatabase
XrmDatabase	XrmPutFileDatabase	XrmDatabaseのロケール
	XrmLocaleOfDatabase
	標準プロパティの設定:
setlocale	XmbSetWMProperties	与えられるエンコーディング/返されるエンコーディング
		テキスト(環境のロケールにおける何
		らかの WM_ プロパティのテキスト)
setlocale	XmbTextPropertyToTextList	与えられるテキスト/返されるテキストのエンコーディング
	XwcTextPropertyToTextList
	XmbTextListToTextProperty
	XwcTextListToTextProperty
	テキスト入力:
setlocale	XOpenIM	XIM の入力メソッドの選択
	XRegisterIMInstantiateCallback	XIM の選択
	XUnregisterIMInstantiateCallback	XIM の選択
XIM	XCreateIC	XIC 入力メソッドの設定
	XLocaleOfIMなど	問い合わせるロケール
XIC	XmbLookupString	キーボードの配置
	XwcLookupString	返されるテキストのエンコーディング
	テキスト描画:
setlocale	XOpenOM	XOM 出力メソッドの選択
	XCreateFontSet	XFontSetにおける文字集合の選択
XOM	XCreateOC	XOC 出力メソッドの設定
	XLocaleOfOMなど	問い合わせるロケール
XFontSet	XmbDrawText ,	与えられたテキストのロケール
	XwcDrawTextなど	与えられたテキストのロケール
	XExtentsOfFontSetなど	ロケール依存の寸法
	XmbTextExtents ,XwcTextExtentsなど
	Xlib のエラー:
setlocale	XGetErrorDatabaseText	エラーメッセージのロケール
	XGetErrorText

クライアントは、X の関数が返した、ロケールに従ってエンコードされた テキスト文字列を C ライブラリルーチンに渡すことや、その逆を行うことは、 2 つの関数呼び出しの際のロケールが同じであれば可能であると仮定することが できる。

国際化された Xlib 関数が処理した全てのテキスト文字列は、 ロケールのエンコーディングが状態依存ならば、そのエンコーディングの初期 状態で始まるものとして扱われる。

全ての Xlib 関数は、現在のロケールや X モディファイアの設定を変更して いないかのように動作する。 (つまり、これらの関数がロケールを変更したり、NULL でない引き数を使って XSetLocaleModifiersを呼び出した場合、これらの関数はエントリの現在の状態の保存と復元を行っ てから終了しなければならない。) また、ANSI c ライブラリに準拠している実装上における Xlib 関数は、 ANSI C 関数( mblen , mbtowc , wctomb ,strtok)が持つグローバルな状態を変更することはない。

可変長引数リスト

この章で説明する様々な関数は、ANSI C における可変長引き数リスト呼び出 し規約に準拠する引き数を取る。 ``...'' という形式の引き数が示されている関数はそれぞれ、名前と値のペア の可変長リストを取る。ここでそれぞれの名前は文字列であり、値は XPointer型を持つ。 名前に当たる引き数を NULL にすることでリストの終わりが示される。

可変長引数リストは、入れ子リストを含むことができる。 引き数名の位置に XNVaNestedListという名前が指定された場合、それに続く値は XVaNestedListの値と解釈される。この値は、元々のリストにおける宣言された位置に論理的 に挿入する値のリストを指定する。 NULL は入れ子リストの終わりを示す。

入れ子になった可変長引き数リストを動的に割り当てるには XVaCreateNestedListを使う。

typedef void * XVaNestedList; XVaNestedList XVaCreateNestedList(dummy, ...)
int dummy;

dummy

使われない引き数を指定する(ANSI C において必要)。

...

可変長引き数リストを指定する。

出力メソッド

この章では X の出力メソッド(X Output Method, XOM)に関する以下の話題に ついて説明する:

• 出力メソッドの概要
• 出力メソッド関数
• 出力メソッドの値
• 出力コンテクスト関数
• 出力コンテクストの値
• フォントセットの生成と解放
• フォントセットの寸法の取得
• フォントセットを用いたテキスト描画

出力メソッドの概要

ロケール依存のテキストには、1 つあるいは複数のテキスト要素が含まれるこ とがあり、テキスト要素のそれぞれは異なるフォントと文字集合のエンコーディング を要求することがある。 言語によっては、各要素の描画方向が異なったり、隣接する文字との関係に基 づいて字形が変わるコンテクスト依存の文字が一部の要素に含まれることがあ る。

このようなロケール依存テキストを描画するときには、ロケール固有の知識が いくらか必要となる。 これは例えば、テキストを描画するときにどんなフォントが必要であるか、ど のようにテキストを要素に分割するか、それぞれの要素を描画するのにどのフォ ントを選ぶか等である。 さらに、描画方向が 2 つあるテキストを描画しなければならないときには、 テキストの内部表現の順序は描画のための視覚的な表現の順序に変えなければ ならない。

X の出力メソッドは、クライアントがこのようなロケール依存の細かい点を直 接処理しなくてもよいように関数インタフェースを提供する。 出力メソッドは以下の機能を提供する:

• ロケール依存テキストを描画するために必要なフォントの集合の生成。
• フォントセットを使い、呼び出し側はロケール依存性を意識する必要がないよ うなロケール依存テキストの描画。
• ロケール依存テキストの送り幅(escapement)と範囲(extent)のピクセル単位で の取得。
• 特定のロケールで特定のフォントセットを使う場合に、描画方向が 2 つあっ たり、コンテクスト依存の描画が必要であるかどうかの確認。

クライアントのための出力メソッドの表現では、2 つの異なる抽象層が用いら れている。

出力メソッドと通信するために使われる抽象層は、 XOMデータ型で表現される opaque なデータ構造体である。 特定の出力スレッドの状態を表現するための抽象層は 出力コンテクスト(output context)と呼ばれる。 出力コンテクストの Xlib での表現は XOCである。これは関数インタフェースという点では XFontSetと互換であるが、より広く、より一般化されている抽象層である。

出力メソッド関数

出力メソッドをオープンするには XOpenOMを用いる。

XOM XOpenOM(display, db, res_name, res_class)
Display *display;
XrmDatabase db;
char *res_name;
char *res_class;

display

X サーバへの接続を指定する。

db

リソースデータベースへのポインタを指定する。

res_name

アプリケーションの完全なリソース名を指定する。

res_class

アプリケーションの完全なクラス名を指定する。

この呼び出しが送られる特定の出力メソッドは、現在のロケールとモディファイア に基づいて識別する。 XOpenOMは、現在のロケールに対応するデフォルトの出力メソッドを識別する。 このデフォルト値は、 XSetLocaleModifiersを用いて出力メソッドのモディファイアを設定することにより変更できる。

引き数 db は、出力メソッドに対してプライベートなリソースを出力メソッド が参照するために使うリソースデータベースである。 出力コンテクストにおいて OC 値として設定できる値を検索するためにこのデー タベースが使われることは意図されていない。 db が NULL ならば、出力メソッドにはデータベースは渡されない。

引き数 res_name と res_class は、アプリケーションのリソース名とクラス を指定する。 これらの値は、この出力メソッドに対して生成されるかもしれない全ての 出力コンテクストに共通なリソースを検索する時に、出力メソッドが プレフィックスとして使うためのものである。 リソース名とクラスに対して用いる文字は、X ポータブル文字集合の文字でな ければならない。 res_name または res_class が NULL ならば、検索で見つかるリソースは完全 には指定されない。

引き数 res_name と res_class は、 XOpenOMの呼び出しの後にも存在することは仮定できない。 指定されたリソースデータベースは、出力メソッドが存在する間は存在するも のと仮定される。

XOpenOMは、出力メソッドを全くオープンできなければ NULL を返す。

出力メソッドをクローズするには XCloseOMを用いる。

Status XCloseOM(om)
XOM om;

om

出力メソッドを指定する。

出力メソッドの属性を設定するには XSetOMValuesを用いる。

char * XSetOMValues(om, ...)
XOM om;

om

出力メソッドを指定する。

...

XOM 値を設定するための可変長引き数リストを指定する。

現在の Xlib では標準的な引き数は定義されていない。

出力メソッドに関する問い合わせを行うには XGetOMValuesを用いる。

char * XGetOMValues(om, ...)
XOM om;

om

出力メソッドを指定する。

...

出力メソッドを取得するための可変長引き数リストを指定する。

出力メソッドに関連付けられたディスプレイを取得するには XDisplayOfOMを用いる。

Display * XDisplayOfOM(om)
XOM om;

om

出力メソッドを指定する。

出力メソッドに関連付けられたロケールを取得するには XLocaleOfOMを用いる。

char * XLocaleOfOM(om)
XOM om;

om

出力メソッドを指定する。

X 出力メソッドの値

以下の表には、出力メソッドがどのように XOM 値を解釈するかが示されてい る。 最初のカラムは XOM 値である。2 番目のカラムは、特定の出力スタイルが それぞれの XOM 値をどのように扱うかを示す。

以下のキーがこの表に適用される。

キー	説明
G	この値はXGetOMValuesで読むことができる。

XOM 値	キー
XNRequiredCharSet	G
XNQueryOrientation	G
XNDirectionalDependentDrawing	G
XNContextualDrawing	G

必要な文字集合

引き数 XNRequiredCharSetは、ロケールが必要とするフォントをロードするために必要な文字集合のリス トを返す。 この引き数の値は、 XOMCharSetList型の構造体へのポインタである。

XOMCharSetList構造体は以下のように定義されている:

typedef struct {
	int charset_count;
	char **charset_list;
} XOMCharSetList;

charset_list メンバは、NULL で終端する文字集合名の 1 つ以上のリストで あり、charset_count メンバは文字集合名の数である。

必要とされる文字集合のリストは Xlib が所有しているので、クライアントは これを変更したり解放してはならない。 このリストは、関連付けられた XOMを使った XCloseOMの呼び出しによって解放される。 解放されるまで、Xlib がリストの内容を変更することはない。

方向の問い合わせ

引き数 XNQueryOrientationはテキストの描画時のグローバルな方向を返す。 XOMOrientation_LTR_TTBを除くと、サポートされている方向の集合はロケール依存である。 この引き数の値は XOMOrientation型の構造体へのポインタである。 クライアントは XFreeを用いて XOMOrientation構造体を解放する責任を持つ。 これにより、構造体の中身も解放される。

typedef struct {
	int num_orientation;
	XOrientation *orientation;	/* 入力テキストの説明 */
} XOMOrientation;
typedef enum {
	XOMOrientation_LTR_TTB,
	XOMOrientation_RTL_TTB,	
	XOMOrientation_TTB_LTR,
	XOMOrientation_TTB_RTL,
	XOMOrientation_Context
} XOrientation;

XOrientation が取り得る値を以下に示す:

• XOMOrientation_LTR_TTB 左から右、グローバルな方向は上から下
• XOMOrientation_RTL_TTB 右から左、グローバルな方向は上から下
• XOMOrientation_TTB_LTR 上から下、グローバルな方向は左から右
• XOMOrientation_TTB_RTL 上から下、グローバルな方向は右から左
• XOMOrientation_Context グローバルな方向はコンテクストによる

方向依存の描画

引き数 XNDirectionalDependentDrawingは、テキスト描画関数に方向付きテキストの暗黙的な処理が実装されているか どうかを示す。この値が Trueならば、出力メソッドは方向的な依存性の知識を持っており、テキストの レンダリングを行う際にテキストの並べ替えを行う。この値が Falseならば、出力メソッドには方向付きテキストの処理は全く実装されておらず、 文字の方向は全て左から右であるものとして扱われる。

文字のレンダリングの順序の関わらず、全ての文字の原点は、描画の原点の 主描画方向側にある。

この OM 値は、関数 XDirectionalDependentDrawingと同じ機能を与える。

コンテクスト依存の描画

引き数 XNContextualDrawingは、テキスト描画関数に暗黙的なコンテクスト依存の描画が実装されているか どうかを示す。この値が Trueならば、出力メソッドはコンテクスト依存性についての知識を持っており、 必要に応じて字形の編集や単一の文字を表現するためのグリフの結合を行う。 実際の字形の編集は、ロケールの実装と使われるフォントセットに依存する。

この OM 値は、関数 XContextualDrawingと同じ機能を与える。

出力コンテクスト関数

出力コンテクストは、出力メソッドが必要とするデータと、そのデータを表示 するために必要な情報を両方とも含む抽象層である。 1 つの出力メソッドに対して複数の出力コンテクストが存在することができる。 出力コンテクストの生成、読み込み、修正のためのプログラミング インタフェースは、可変長引き数リストを用いる。 引数リストの名前要素は、XOC 値として参照される。 これは出力メソッドをこれらの XOC 値で制御するためのものである。 新しい XOC 値を作った場合は、X コンソーシアムに登録すべきである。 XOCは XFontSetが使えるところならどこでも使えるし、その逆も同じである。 XFontSetは過去のリリースとの互換性を保っている。 出力メソッドと出力コンテクストの概念は、フォントセットよりも広くて一般 的な抽象化がなされており、複雑で賢いテキスト描画に対応しており、複数の フォントだけでなくコンテクスト依存性も扱うことができる。 しかし XFontSetは色々なインタフェースで広く使われているので、 XOCは XFontSetと上位互換である型として定義されている。

出力コンテクストを生成するには XCreateOCを用いる。

XOC XCreateOC(om, ...)
XOM om;

om

出力メソッドを指定する。

...

XOC 値を設定するための可変長引き数リストを指定する。

ベースフォント名の引き数は生成時に必須であり、これが与えられないと出 力コンテクストは生成されない。 他の出力コンテクスト値は全て後で設定することができる。

XCreateOCは、出力コンテクストが生成できなければ NULL を返す。 以下の理由のいずれかに対して NULL が返される可能性がある:

• 必要な引き数が設定されていなかった。
• 読み取り専用の引き数が設定されていた。
• 引き数名が識別できない。
• 出力メソッドが、出力メソッドの実装依存のエラーに出会った。

XCreateOCはエラー BadAtomを生成することがある。

出力コンテクストを破棄するには XDestroyOCを用いる。

void XDestroyOC(oc)
XOC oc;

oc

出力コンテクストを指定する。

出力コンテクストに関連付けられた出力メソッドを取得するには XOMOfOCを用いる。

XOM XOMOfOC(oc)
XOC oc;

oc

出力コンテクストを指定する。

Xlib には、出力コンテクスト値の設定の関数 XSetOCValuesと、取得の関数 XGetOCValuesが用意されている。 どちらの関数も可変長引き数リストを取る。 この引き数リストでは、XOC 値の名前は全て、 X ポータブル文字集合を使った文字列で示さなければならない。

XOC 値を設定するには XSetOCValuesを用いる。

char * XSetOCValues(oc, ...)
XOC oc;

oc

出力コンテクストを指定する。

...

XOC 値を設定するための可変長引き数リストを指定する。

• 引き数が読み取り専用である。
• 引き数の名前が識別できない。
• 実装依存のエラーが発生した。

設定される値は適切なデータでなければならない。つまり、引き数の意味によっ て決められるデータ型に一致しなければならない。

XSetOCValuesはエラー BadAtom を生成することがある。

XOC 値を取得するには XGetOCValuesを用いる。

char * XGetOCValues(oc, ...)
XOC oc;

oc

出力コンテクストを指定する。

...

XOC 値を取得するための可変長引き数リストを指定する。

• 引き数名が識別できない。
• 実装依存のエラーが起こった。

名前の後に続く引き数の値はそれぞれ、値が格納されている場所を示さなけれ ばならない。

出力コンテクスト値

以下の表は、出力メソッドが XOC 値をどのように解釈するかを示す。 2 番目のカラムは、同じ機能を持ち、過去のリリースとの互換性のために用意 されている代替インタフェースを示す。 3 番目のカラムは、それぞれの XOC 値がどのように扱われるかを示す。

以下のキーがこの表に適用される。

キー	説明
C	この値はXCreateOCで設定しなければならない。
D	この値はXCreateOCを使って設定することもできる。設定されなければ、 デフォルト値が与えられる。
G	この値はXGetOCValuesを使って読むことができる。
S	この値はXSetOCValuesを使って設定しなければならない。

XOC 値	代替インタフェース	キー
BaseFontName	XCreateFontSet	C-G
MissingCharSet	XCreateFontSet	G
DefaultString	XCreateFontSet	G
Orientation	-	D-S-G
ResourceName	-	S-G
ResourceClass	-	S-G
FontInfo	XFontsOfFontSet	G
OMAutomatic	-	G

ベースフォント名

引き数 XNBaseFontNameは、Xlib がロケールにおいて必要となるフォントをロードするために使うベー スフォント名のリストである。 ベースフォント名はコンマ区切りのリストである。この文字列は NULL で終端 し、ホストポータブル文字エンコーディングであるものとして扱われる。 そうでない場合には、結果は実装依存である。 区切り文字のコンマの直前・直後にある空白文字は無視される。

XLFD フォント名を使うと、Xlib はロケールに依存しない単一のフォント名か ら様々な種類のロケールが必要とするフォント群を取得することができる。 単一のベースフォント名は、フォントのファミリ名を指していなければならず、 このファミリのメンバは、対象のロケールで必要な各種文字集合でエンコード されていなければならない。

XLFD のベースフォント名は、ロケールが必要とする文字集合を明示的に指す。 これによりユーザは、ロケールに必要とされる文字集合を使うための正確なフォ ントを、フォントの選択を完全に制御しながら指定することができる。

ベースフォント名が XLFD 名でなければ、Xlib はそのフォントのフォントプ ロパティから XLFD 名を取得しようとする。 Xlib がこれに成功すれば、関数 XGetOCValuesはクライアントが与えた名前ではなく、得られた XLFD 名を返す。

この引き数は生成時に設定しなければならず、後から変更することも許されな い。 必要とされる文字集合のいずれかに対するフォントが存在しない場合や、Xlib におけるロケールの定義では特定の文字集合に対してフォントが存在すること が必要なのに、その文字集合に対するフォントが見つからなかった場合には、 XCreateOCは NULL を返す。

XOC 値である XNBaseFontNameの問い合わせを行うとき、 XGetOCValuesは、ベースフォント名を一意に決める NULL で終端する文字列を返す。この文 字列は、そのロケールに対して必要なフォントをロードするために Xlib が使っ たものである。 この文字列は Xlib が所有しているので、クライアントは変更や解放をしては ならない。 この文字列は、対応する XOCを用いた XDestroyOCの呼び出しによって解放される。 解放されるまでは、Xlib がこの文字列の内容を変更することはない。

足りない文字集合

引き数 XNMissingCharSetは、必要な文字集合のうちフォントセットに欠けているもののリストを返す。 この引き数の値は、 XOMCharSetList型の構造体へのポインタである。

現在のロケールで必要な全ての文字集合に対してフォントが存在しているなら ば、charset_list には NULL が設定され、charset_count には 0 が設定され る。 必要な文字集合のうちの 1 つ以上に対して存在しないフォントがある場合、 charset_list には存在しない文字集合の名前(NULL で終端する)のリストが設 定され、charset_count には足りない文字集合の数が設定される。 文字集合は、ロケールのエンコーディングに対して必要な文字集合のリストか ら得られ、Xlib が必要な文字集合を再マップできるかもしれない文字集合は 全く含まない。

足りない文字集合のリストは Xlib が所有しているので、クライアントはこれ を変更・修正してはならない。 このリストは対応する XOCを使って XDestroyOCを呼び出すことにより解放される。 解放されるまでは、Xlib がこの内容を変更することはない。

デフォルト文字列

足りない文字集合がある XOCを使って描画関数または寸法を調べる関数が呼び出された時は、そのロケール の文字には描画できないものがある。 引き数 XNDefaultStringは、利用できるフォントの文字集合が、ある文字を描画するのに必要な全ての グリフを含んでいない時に、この XOCを使って描画されるグリフを表す文字列へのポインタを返す。 この文字列は必ずしも現在のロケールで有効な文字で成り立っているとは限ら ないし、必ずしもそのフォントセットに対してロードされたフォントで描画さ れるとも限らないが、クライアントはデフォルトのグリフを描画したり寸法を 調べることができる。これはこの文字列を、その XOCで描画あるいは寸法を調べる文字列に含めることによって行う。

引き数 XNDefaultStringが空文字列("")を返した場合、グリフは全く描画されず、送り幅は 0 である。 返される文字列は NULL で終端する。 この文字列は Xlib が所有しているので、クライアントは変更や解放を行って はならない。 この文字列は、対応する XOCを使って XDestroyOCを呼び出すことにより解放される。 解放されるまでは、Xlib が文字列の内容を変えることはない。

方向

引き数 XNOrientationは、描画におけるテキストの現在の方向を指定する。この引き数の値は、 XOrientationリストで指定されている XNQueryOrientationを引き数とした関数 XGetOMValuesが返す値のいずれかである。 この引き数の値の型は XOrientationである。 XNOrientationの問い合わせが行われた時、その値は現在の方向を指定する。 XNOrientationが設定された時、その値を使って現在の方向が設定される。

XOMOrientation_Contextが設定された時、テキストの方向は実装依存の方法(例えば、ISO 6429 制御シー ケンス)に従って決められる。また、ロケール依存の Xlib 関数におけるテキ ストの方向の初期値は、 XOMOrientation_LTR_TTBであるものとされる。

XNOrientationの値は、Xlib の描画関数の主描画方向を変えることはない。

リソース名とクラス

引き数 XNResourceNameと XNResourceClassは、クライアントが出力コンテクストのディスプレイに対するリソースを取得 するためにつかう完全な名前とクラスを指定する文字列である。 これらの値は、出力コンテクストに従って変化するかもしれないリソースを探 す時に、名前とクラスに対するプレフィックスとして使わなければならない。 これらの値が設定されていなければ、リソースは完全には指定されない。

これは、XOM として設定できる値をリソースとして設定するためのものではな い。

XOC 値 XNResourceName ,XNResourceClassを問い合わせる時、 XGetOCValuesは NULL で終端する文字列を返す。 この文字列は Xlib が所有しているので、クライアントはこれを修正したり 解放したりしてはならない。 この文字列は、対応する XOCを使って XDestroyOCを呼び出した時か、対応する値が XSetOCValuesによって変更された時に解放される。 解放されるまでは、この文字列の内容を Xlib が変更することはない。

フォント情報

引き数 XNFontInfoは、1 つあるいは複数の XFontStructのリストと、与えられた出力コンテクストが描画に使うフォントを示すフォン ト名のリストを指定する。 この引き数の値は、 XOMFontInfo型の構造体へのポインタである。

typedef struct {
	int num_font;
	XFontStruct **font_struct_list;
	char **font_name_list;
} XOMFontInfo;

XFontStruct構造体へのポインタのリストが font_struct_list に返される。 NULL で終端し、出力コンテクストのロケールにおいて完全に指定されたフォ ント名文字列が font_name_list に返される。 font_name_list の順序は、font_struct_list の順序に対応している。 XFontStruct構造体とフォント名の数が num_font に返される。

与えられた文字が単一のフォントグリフを用いてイメージ化されることは保証 されていないので、ある文字やデフォルト文字列が、その文字に使われるフォ ントについてどのようにフォント属性、フォント ID, 方向ヒントと対応する のかを前もって知ることはできない。 クライアントは XFontStructリストにアクセスして、現在使用中の全てのフォントに対してこれらの値を取 得することができる。 Xlib は、 XOCの生成時にフォントがサーバからロードされていることを保証していない。 Xlib はフォントデータをキャッシュすることにして、テキストの描画やテキ ストの寸法計算に必要な場合だけフォントをロードしてもよい。 したがって、 XFontStructSetに含まれる XFontStruct構造体の per_char 寸法があるかどうかは未定義である。 また、 XFontStruct構造体が持つ全ての属性は STRING エンコーディングである点にも注意するこ と。

クライアントは XOMFontInfo構造体を解放してはならない。この構造体は XOCがクローズされた時に解放される。

OM の自動決定

引き数 XNOMAutomaticは、対応する出力コンテクストが XCreateFontSetによって生成されたのかどうかを返す。関数 XFreeFontSetは出力コンテクストを破棄するだけでなく、これに関連する 陽に現われていない出力メソッドもクローズするので、 XCreateFontSetによって生成した出力コンテクストに対しては必ず XFreeFontSetを使わなければならない。 しかし、クライアントが出力コンテクストをどうやって生成したのかを知らな い可能性もある。 クライアントが出力メソッドを破棄する前には、出力コンテクストを破棄する ために XFreeFontSet あるいは XDestroyOCを使うべきかどうかを決定するために、 XNOMAutomaticが設定されているかどうかを問い合わせることができる。

フォントセットの生成と解放

Xlib の国際化テキスト描画は、テキストのロケールの必要に応じて、1 つあ るいは複数のフォントを用いて行われる。 フォントは、クライアントとロケールが必要とする文字集合によって与えられ たベースフォント名のリストに従ってロードされる。 XFontSetは特定の出力スレッドの状態を表す opaque な型であり、 XOC型と全く同じものである。

関数 XCreateFontSetは、デフォルト値だけを用いて出力コンテクストを生成するための簡易関数で ある。この関数が返す XFontSetは、 が暗黙的に生成された XOMを持つ。 この XOMは、自動的に Trueに設定された OM 値 XNOMAutomaticを持つ。これは、出力コンテクスト自身が XCreateOCと XCreateFontSetのどちらを使って生成されたかを示すためである。

XFontSet XCreateFontSet(display, base_font_name_list, missing_charset_list_return,
missing_charset_count_return, def_string_return)
Display *display;
char *base_font_name_list;
char ***missing_charset_list_return;
int *missing_charset_count_return;
char **def_string_return;

display

X サーバへの接続を指定する。

base_font_name_list

ベースフォント名を指定する。

missing_charset_list_return

不足している文字集合が返される。

missing_charset_count_return

不足している文字集合の数が返される。

def_string_return

不足している文字集合を描画するための文字列が返される。

引き数 base_font_name_list は、そのロケールで必要なフォントをロードす るために Xlib が用いるベースフォント名のリストである。 ベースフォント名はコンマ区切りのリストである。 この文字列は NULL で終端し、ホストポータブル文字エンコーディングである ものと仮定される。 そうでない場合の結果は実装依存である。 区切り文字のコンマの直前・直後の空白文字は無視される。

XLFD フォント名を使うことにより、Xlib がロケール独立の単一のベースフォ ント名から各種ロケールで必要なフォントを取得することが可能となる。 この単一のベースフォント名は、フォントの集合を指定しなければならず、 その構成要素は、対象としているロケールで必要な各種の文字集合でエンコー ドされてなければならない。

XLFD ベースフォント名は、ロケールで必要な文字集合を明示的に指定するこ とができる。 これによりユーザは、あるロケールで必要な文字集合と共に用いるフォントを、 フォント選択を完全に制御した状態で厳密に指定することができる。

ベースフォント名が XLFD 名でなければ、Xlib はそのフォントに対するフォ ント属性から XLFD 名を取得しようとする。 この処理で XLFD 名がうまく取得できれば、関数 XBaseFontNameListOfFontSetは、クライアントが与えた名前ではなく XLFD 名を返す。

Xlib は、 XFontSetを使ってテキスト表示を行うためのフォントを、以下のアルゴリズムを用いて 選択する。

ロケールが必要とするそれぞれのフォント文字集合について、以下のケースの いずれかに該当し、サーバが持っているフォントの集合を指定する最初のもの がベースフォント名リストから検索される:

• 必要とされる文字集合、または必要とされる文字集合を含む集合を CharSetRegistryと CharSetEncodingで指定している、XLFD 準拠のベースフォント名の最初のもの。 実装においては、指定された文字集合が必要な文字集合を含む集合であるよう なフォント名を使ってよい。例えば、ASCII 文字集合に対する ISO8859-1 フォントがこれに該当する。
• 再マップして必要な文字集合をサポートできる 1 つ以上の文字集合を指定す る、1 つ以上の XLFD 準拠のベースフォント名の集合の最初のもの。 Xlib の実装では、必要とされる文字集合から 1 つ以上の他の文字集合への 様々なマッピングを識別し、これらの文字集合のフォントを使うことができる。 例えば、JIS Roman は ASCII のチルダとバックスラッシュを円記号と 上線記号に置き換えたものである。 JIS Roman フォントが使用できなければ、Xlib は ISO8859-1 フォントをロー ドしてこの文字集合をサポートすることができる。
• (XLFD フォント名の CharSetRegistryフィールドや CharSetEncodingフィールドを置き換えて )XLFD フォント名を取得でき、必要な文字集合に結び付けられる最初の XLFD 準拠のフォント名、または最初の XLFD 非準拠のフォント名。 ケース 1 と同様に、実装においては必要な文字集合を含む文字集合を使って もよい。
• 何らかの実装依存の方法により、その文字集合におけるテキストのイメージ化 をサポートしている 1 つ以上のフォントにマッピングできる最初のフォント名。

例えば、ロケールが以下のフォントを必要としているものとする:

ISO8859-1
JISX0208.1983
JISX0201.1976
GB2312-1980.0

ユーザは文字集合を明示的に指定する base_font_name_list を与え、これら が存在すれば特定のフォントが使われることを保証できる。 例:

"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
-Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"

あるいは、ユーザは文字集合を省略した base_font_name_list を与え、 ロケールが必要とする文字集合を Xlib に選択させることもできる。 例:

"-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
-GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
-Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"

また、ユーザはベースフォント名を単に一つだけ与え、 特定最小限の XLFD 属性に関する要件を満たし、利用可能な全てのフォントの中 から Xlib に選択を行わせることもできる。 例:

"-*-*-*-R-Normal--*-180-100-100-*-*"

メモリが不十分なことや、現在のロケールがサポートしていないことが原因で XCreateFontSetでフォントを生成できなければ、 XCreateFontSetは NULL を返し、missing_charset_list_return に NULL が設定され、 missing_charset_count_return に 0 が設定される。 現在のロケールが必要とする文字集合の全てに対してフォントが存在していれば、 XCreateFontSetは有効な XFontSetを返し、missing_charset_list_return に NULL が設定され、 missing_charset_count_return に 0 が設定される。

必要とされる文字集合の 1 つ以上に対してフォントが存在しなければ、 XCreateFontSetはフォントが存在しない文字集合の名前のリストを missing_charset_list_return に設定し、足りないフォントの数を missing_charset_count_return に設定する。文字集合の名前は NULL で終端 する。 文字集合は、ロケールのエンコーディングに対して必要な文字集合のリストか ら取得され、Xlib が必要な文字集合に再マップできる文字集合は含まない。

必要とされる文字集合のいずれに対してもフォントが存在しない場合や、Xlib のロケール定義において、特定の文字集合に対してフォントが必要であるにも かかわらず、その文字集合に対するフォントが見つからない場合には、 XCreateFontSetは NULL を返す。 それ以外の場合には、 XCreateFontSetは有効な XFontSetを font_set に返す。

足りない文字集合がある XFontSetを使って Xmb/wc 描画関数や寸法取得関数が呼び出されると、そのロケールの一部 の文字は描画できない。 def_string_return が NULL でなければ、 XCreateFontSetは、あるコードポイントを描画するのに必要な全てのグリフが、利用可能なフォ ントの文字集合に含まれていない時に、この XFontSetを使って描画されるグリフを表現する文字列へのポインタを返す。 この文字列は必ずしも現在のロケールでの有効な文字列からなるとは限らない し、必ずしもそのフォントセットのためにロードされたフォントを使って描画 されるとも限らないが、 XFontSetを使って描画・寸法取得する文字列にこの文字列を含めることにより、クライ アントはデフォルトのグリフの描画や寸法取得が可能である。

def_string_return に返される文字列が空文字列("")ならば、グリフは全く 描画されず、文字の送り幅は 0 である。 返される文字列は NULL で終端している。 この文字列は Xlib が所有しており、クライアントは修正や解放をしてはなら ない。 この文字列は、対応する XFontSetを使って XFreeFontSetを呼び出すことによって解放される。 解放されるまでは、Xlib が文字列の内容を変更することはない。

足りない文字集合とデフォルト文字列の情報からエラーメッセージを作るのは クライアントの責任であり、またクライアントは一部のフォントが足りない場 合に動作を続けるかどうかを選ぶことができる。

返された XFontSetは XFreeFontSetを使って解放し、足りない文字集合のリストは XFreeStringListを使って解放しなければならない。 クライアントが与えた base_font_name_list は、 XCreateFontSetを呼び出した後なら解放しても構わない。

ある XFontSetから XFontStruct構造体のリストと完全なフォント名を取得するには、 XFontsOfFontSetを用いる。

int XFontsOfFontSet(font_set, font_struct_list_return, font_name_list_return)
XFontSet font_set;
XFontStruct ***font_struct_list_return;
char ***font_name_list_return;

font_set

フォントセットを指定する。

font_struct_list_return

フォント構造体のリストが返される。

font_name_list_return

フォント名のリストが返される。

与えられた文字が単一のフォントグリフだけでイメージ化されることは保証さ れていないので、その文字に対するフォントについて、文字やデフォルト文字 列からフォント属性、フォント ID, 描画方向ヒントへのマッピングを前もっ て知ることはできない。 クライアントは XFontStructのリストにアクセスし、現在使われている全てのフォントについて、これらの 値を取得できる。

Xlib は、 XFontSetの生成時にフォントがサーバからロードされることを保証していない。 Xlib は、フォントデータをキャッシュし、テキストの描画やテキストの寸法 の取得で必要になった時だけフォントデータをロードしてもよい。 したがって、 XFontStructSetが持つ XFontStruct構造体に per_char metrics 寸法が存在するかどうかは未定義である。 また、 XFontStruct構造体の全ての属性のエンコーディングは STRING である点に注意すること。

XFontStructとフォント名のリストは Xlib が所有しているので、クライアントはこれを 変更・解放してはならない。 これらは対応する XFontSetを使って XFreeFontSetを呼び出すことによって解放される。 解放されるまで、Xlib がこれらの内容を変更することはない。

与えられた XFontSetに対し、ベースフォント名のリストと選択されたフォント名のリストを取得す るには XBaseFontNameListOfFontSetを用いる。

char *XBaseFontNameListOfFontSet(font_set)
XFontSet font_set;

font_set

フォントセットを指定する。

XCreateFontSetが 非 XLFD ベース名によって指定されたフォントに対するフォント属性から XLFD 名を取得した場合、関数 XBaseFontNameListOfFontSetは非 XLFD ベース名でなく XLFD 名を返す。

ベースフォント名のリストは Xlib が所有しているので、クライアントはこれ を変更・解放してはならない。 これらは対応する XFontSetを使って XFreeFontSetを呼び出すことによって解放される。 解放されるまで、Xlib がこれらの内容を変更することはない。

XFontSetからロケール名を取得するには、 XLocaleOfFontSetを用いる。

char *XLocaleOfFontSet(font_set)
XFontSet font_set;

font_set

フォントセットを指定する。

返されたロケール名文字列は Xlib が所有しているので、クライアントはこれ を変更・解放してはならない。 これは対応する XFontSetを使って XFreeFontSetを呼び出すことによって解放される。 解放されるまで、Xlib がこの内容を変更することはない。

関数 XFreeFontSetは、出力コンテクストを解放するための簡易関数である。 出力コンテクストが XCreateFontSetによって生成されていた場合には、 XFreeFontSet は、対応する XOMも解放する。

void XFreeFontSet(display, font_set)
Display *display;
XFontSet font_set;

display

X サーバへの接続を指定する。

font_set

フォントセットを指定する。

フォントセットの寸法の取得

国際化されたテキスト描画関数の場合の寸法は、主描画方向について定義され る。主描画方向は、文字列中で文字が続いていく際に文字の原点が進んでいく デフォルトの方向である。 Xlib のインターフェースは現在、左から右の主描画方向しかサポートしない ように定義されている。 描画の原点は、テキストが描画される時に描画関数に渡される位置である。 ベースラインは描画の原点を通って主描画方向に平行な直線である。 文字インク(character ink)は前景色で描かれるピクセルであり、行間や 文字間の間隔やイメージテキストの背景ピクセルは含まない。

描画関数は、テキスト描画方向の暗黙的な制御を行い、主描画方向に沿って 文字を描画する順序を文字列のロケール固有の字句解析に従って逆順にするこ とが許される。

文字を描画する順序に関係なく、全ての文字の原点は描画の原点の主描画方向 側にある。 特定の文字イメージの画面上の位置は、 XmbTextPerCharExtentsまたは XwcTextPerCharExtentsを使って求めることができる。

描画関数はコンテクスト依存の描画を行うことが許される。 コンテクスト依存の描画においては、ある文字列に対して描画されるグリフは 個々の文字を表すグリフを単に並べたものではない。 2 文字からなる文字列を XmbDrawStringで描画した結果は、2 つの文字を別々の XmbDrawStringで描画した結果と異なってもよい。 クライアントが前に描画した文字列に文字の追加や挿入を行う場合、 適切な描画結果を得るためにはクライアントは隣接する何文字かを再描画する 必要があるかもしれない。

方向依存の描画について調べるには、 XDirectionalDependentDrawingを使う。

Bool XDirectionalDependentDrawing(font_set)
XFontSet font_set;

font_set

フォントセットを指定する。

コンテクスト依存の描画について調べるには XContextualDrawingを使う。

Bool XContextualDrawing(font_set)
XFontSet font_set;

font_set

フォントセットを指定する。

コンテクスト依存、あるいは方向依存の描画について調べるには XContextDependentDrawingを使う。

Bool XContextDependentDrawing(font_set)
XFontSet font_set;

font_set

フォントセットを指定する。

描画関数は改行、タブやその他の制御文字を解釈しない。 空白以外の非印刷文字が描画された時の動作は実装依存である。 テキストストリームに含まれる制御文字を解釈するのはクライアントの責任である。

テキスト描画層が使うフォントについての文字の最大領域は、 XFontSetExtents構造体によってアクセスできる:

typedef struct {
	XRectangle max_ink_extent;	/* 描画可能な全ての文字について */
	XRectangle max_logical_extent;	/* 描画可能な全ての文字について */
} XFontSetExtents;

フォント集合の寸法を返すために使われる XRectangle構造体は、Xlib の画面で使う通常の長方形である。 これは左上隅を示す x, y と常に正の値を取る幅と高さで表される。

max_ink_extent メンバは、この領域は前景色で描画される文字グリフのイメー ジを囲む長方形のうち、描画可能な全ての文字についての最大の領域を与える。 これは固定の原点に対する相対座標で表される。 詳しい意味については XmbTextExtentsと XwcTextExtentsを参照すること。

max_logical_extent メンバは、他のグラフィカルフィーチャとの最小間隔を 示す長方形のうち、描画可能な全ての文字についての最大の領域を与える。 これは固定の原点に対する相対座標で表される。 クライアントが描画する他のグラフィカルフィーチャ(例えばテキストを囲む 境界線)は、この長方形と交わってはならない。 max_logical_extent は、行の送り幅の最小値や、指定された数の任意の文字 をテキスト領域で描画できるようにするために必要な最小領域を計算するため に使うべきである。

コンテクスト依存の描画であるため、指定された文字を文字列に追加した時に 起こる文字列の領域の変化量は、その文字の単独の領域とは異なる場合がある。

文字列中の指定された文字に対する長方形は、 XmbPerCharExtentsまたは XwcPerCharExtentsによって取得できる。

与えられた XFontSetについて最大領域を表す構造体を得るには XExtentsOfFontSetを用いる。

XFontSetExtents *XExtentsOfFontSet(font_set)
XFontSet font_set;

font_set

フォント集合を指定する。

XFontSetExtents構造体は Xlib が所有しているので、クライアントはこれを変更・解放しては ならない。 この構造体は、対応する XFontSetを引き数とする XFreeFontSetの呼び出しによって解放される。 解放されるまでは、構造体の内容を Xlib が変更することはない。

テキストを値として指定して、その送り幅をピクセル単位で取得するには XmbTextEscapementまたは XwcTextEscapementを用いる。

int XmbTextEscapement(font_set, string, num_bytes)
XFontSet font_set;
char *string;
int num_bytes;

int XwcTextEscapement(font_set, string, num_wchars)
XFontSet font_set;
wchar_t *string;
int num_wchars;

font_set

フォント集合を指定する。

string

文字列を指定する。

num_bytes

string 引き数のバイト数を指定する。

num_wchars

string 引き数の文字数を指定する。

文字のレンダリングの順序に関わらず、送り幅は常に正である。

引き数 overall_ink_return と overall_logical_return, 文字列のイメージの全体のバウンディングボックスと 論理的なバウンディングボックスを取得するには、 XmbTextExtentsまたは XwcTextExtentsを用いる。

int XmbTextExtents(font_set, string, num_bytes, overall_ink_return, overall_logical_return)
XFontSet font_set;
char *string;
int num_bytes;
XRectangle *overall_ink_return;
XRectangle *overall_logical_return;

int XwcTextExtents(font_set, string, num_wchars, overall_ink_return, overall_logical_return)
XFontSet font_set;
wchar_t *string;
int num_wchars;
XRectangle *overall_ink_return;
XRectangle *overall_logical_return;

font_set

フォント集合を指定する。

string

文字列を指定する。

num_bytes

string 引き数のバイト数を指定する。

num_wchars

string 引き数の文字数を指定する。

overall_ink_return

全体のインク領域が返される。

overall_logical_return

全体の論理領域が返される。

引き数 overall_ink_return が NULL でなければ、この引き数には 文字列の文字インクのバウンディングボックスが設定される。 下向きに進まず、水平方向に描画される Latin 文字に対する overall_ink_return は、慣習的には完全にベースラインよりも上にある。 つまり verall_ink_return.height <= -overall_ink_return.y である。 カーニングされていない文字に対する overall_ink_return の位置は完全に、 原点またはそれより右である。 つまり overall_ink_return.x >= 0 である。 単一のピクセルからなる文字が原点にあるとすると、 overall_ink_return フィールドには y = 0, x = 0, width = 1, height = 1 が設定される。

引き数 overall_logical_return が NULL ならば、この引き数には 他のグラフィカルフィーチャとその文字列の最小間隔を与える バウンディングボックスが設定される。 他のグラフィカルフィーチャ(例えばテキストを囲む境界線)は、この長方形と 交わってはならない。

XFontSetに足りない文字集合がある場合、利用できない文字の寸法は XCreateFontSet が返すデフォルト文字列から取得される。 これは、この寸法が実際に描画される形のテキストを表すようにするためである。 コードポイントが不正な場合の動作は未定義である。

描画される文字列が含む、ある文字に対する効果的な描画の原点を求めるため には、クライアントは文字列全体に対して XmbTextPerCharExtentsを呼び出し、それからこの文字に対して XmbTextPerCharExtentsを呼び出し、この文字に対して返された長方形の x 座標の差分を取るべきで ある。 これは、1 行のうちの一部分を再描画する時、あるいは空白を入れて単語を揃える 際に役立つが、コンテクスト依存の描画の場合には、この文字を単独で再描画 しても同じ描画結果が得られることを仮定してはならない。

テキスト文字列について、文字ごとの情報を取得するには XmbTextPerCharExtentsまたは XwcTextPerCharExtentsを用いる。

Status XmbTextPerCharExtents(font_set, string, num_bytes, ink_array_return,
logical_array_return, array_size, num_chars_return, overall_ink_return, overall_logical_return)
XFontSet font_set;
char *string;
int num_bytes;
XRectangle *ink_array_return;
XRectangle *logical_array_return;
int array_size;
int *num_chars_return;
XRectangle *overall_ink_return;
XRectangle *overall_logical_return;

Status XwcTextPerCharExtents(font_set, string, num_wchars, ink_array_return,
logical_array_return, array_size, num_chars_return, overall_ink_return, overall_ink_return)
XFontSet font_set;
wchar_t *string;
int num_wchars;
XRectangle *ink_array_return;
XRectangle *logical_array_return;
int array_size;
int *num_chars_return;
XRectangle *overall_ink_return;
XRectangle *overall_logical_return;

font_set

フォント集合を指定する。

string

文字列を指定する。

num_bytes

string 引き数のバイト数を指定する。

num_wchars

string 引き数の文字数を指定する。

ink_array_return

それぞれの文字に対するインク領域が返される。

logical_array_return

それぞれの文字に対する論理領域が返される。

array_size

ink_array_return と logical_array_return の大きさを指定する。 呼び出し側はこの大きさの配列を渡さなければならない。

num_chars_return

string 引き数の文字数が返される。

overall_ink_return

文字列全体のインク領域が返される。

overall_logical_return

文字列全体の論理領域が返される。

ink_array_return の各要素には、対応する文字の前景色で描画される領域の バウンディングボックスが設定される。 logical_array_return の各要素には、対応する文字について、他の グラフィカルフィーチャとの最小距離を与えるバウンディングボックスが設定 される。 ここで他のグラフィカルフィーチャは、logical_array_return の長方形とい ずれとも交差してはならない。

XRectangleは文字の実際に有効な描画領域を示す点に注意すること。これは文字の描画に 使われるフォントグリフの数や、文字が描画される方向には関係ありません。 複数の文字が 1 つの文字グリフにマッピングされている場合は、これらの文 字についての全ての XRectanglesの領域は同じになります。

XFontSetに足りない文字集合がある場合、実際に描画されるテキストの寸法を表現する ため、利用できないそれぞれの文字の寸法は XCreateFontSetが返すデフォルト文字列から求める。 コードポイントが不正な場合の動作は未定義である。

与えられたテキストに含まれている文字の数に対して array_size が小さすぎ る場合には、この関数は 0 を返し、num_chars_return には必要とされる 長方形の数が返される。 それ以外の場合には、この関数は 0 でない値を返す。

引数 overall_ink_return または overall_logical_return が NULL でない 場合、 XmbTextPerCharExtentsと XwcTextPerCharExtentsは文字列の寸法の最大領域を overall_ink_return または overall_logical_return に返す。これは XmbTextExtentsや XwcTextExtentsと同じように行われる。

フォントセットを用いたテキストの描画

この節で定義される関数は、ドロウアブル上の指定された位置にテキストを 描画する。 これらの関数は XDrawText ,XDrawString ,XDrawImageStringに似ているが、単一のフォントでなくフォントセットを使う点と、 文字列の各バイトデータを直接フォントのインデックスとして扱うのではなく フォントセットのロケールに基づいてテキストを解釈する点が異なる。 グラフィックスコンテクスト(GC)の使い方と、起こり得るプロトコルエラーの 詳細については 8.6 節を参照すること。 BadFontエラーが生成された場合でも、問題を起こした文字の前までの文字は描画され ているかもしれない。

テキストは指定されたフォントセットに対してロードされたフォントを用いて 描画される。 したがって、GC に含まれているフォントは無視されるし、これらの関数によっ て変更されることもある。 全てのフォントが幅に関する何らかの規則に準拠していることの確認は行われ ない。

テキスト関数 XmbDrawTextおよび XwcDrawTextは以下の構造体を用いる:

typedef struct {
	char *chars;	/* 文字列へのポインタ */
	int nchars;	/* バイト数 */
	int delta;	/* 文字列の間のピクセル間隔 */
	XFontSet font_set; 	/* フォント。None は変更なしを意味する */
} XmbTextItem;

typedef struct {
	wchar_t *chars;	/* ワイド文字文字列へのポインタ */
	int nchars;	/* ワイド文字の数 */
	int delta;	/* 文字列間のピクセル間隔 */
	XFontSet font_set;	/* フォント。None は変更なしを意味する */
} XwcTextItem;

指定されたドロウアブル上で複数のフォントセットを用いて描画を行うには XmbDrawTextまたは XwcDrawTextを用いる。

void XmbDrawText(display, d, gc, x, y, items, nitems)
Display *display;
Drawable d;
GC gc;
int x, y;
XmbTextItem *items;
int nitems;

void XwcDrawText(display, d, gc, x, y, items, nitems)
Display *display;
Drawable d;
GC gc;
int x, y;
XwcTextItem *items;
int nitems;

display

X サーバへの接続を指定する。

d

ドロウアブルを指定する。

gc

GC を指定する。

x

y

x, y 座標を指定する。

items

テキスト要素の配列を指定する。

nitems

配列内のテキスト要素の数を指定する。

XmbDrawTextと XwcDrawTextは、テキストセグメントの間ではコンテクスト依存のレンダリングは全く行わ ない。 クライアントは、各テキストセグメントを XmbTextExtentsや XwcTextExtents、あるいは XmbTextPerCharExtentsや XwcTextPerCharExtentsに渡すことにより、描画寸法を計算できる。 XFontSetに足りない文字集合があった場合、利用できないそれぞれの文字は XCreateFontSetが返すデフォルト文字列で描画される。 コードポイントが不正な場合の動作は未定義である。

指定されたドロウアブルに単一のフォントセットを使って描画を行うには XmbDrawStringまたは XwcDrawStringを用いる。

void XmbDrawString(display, d, font_set, gc, x, y, string, num_bytes)
Display *display;
Drawable d;
XFontSet font_set;
GC gc;
int x, y;
char *string;
int num_bytes;

void XwcDrawString(display, d, font_set, gc, x, y, string, num_wchars)
Display *display;
Drawable d;
XFontSet font_set;
GC gc;
int x, y;
wchar_t *string;
int num_wchars;

display

X サーバへの接続を指定する。

d

ドロウアブルを指定する。

font_set

フォントセットを指定する。

gc

GC を指定する。

x

y

x, y 座標を指定する。

string

文字列を指定する。

num_bytes

string 引数に含まれるバイト数を指定する。

num_wchars

string 引数に含まれる文字数を指定する。

指定されたドロウアブルに単一のフォントセットを使って描画を行うには XmbDrawImageStringまたは XwcDrawImageStringを用いる。

void XmbDrawImageString(display, d, font_set, gc, x, y, string, num_bytes)
Display *display;
Drawable d;
XFontSet font_set;
GC gc;
int x, y;
char *string;
int num_bytes;

void XwcDrawImageString(display, d, font_set, gc, x, y, string, num_wchars)
Display *display;
Drawable d;
XFontSet font_set;
GC gc;
int x, y;
wchar_t *string;
int num_wchars;

display

X サーバへの接続を指定する。

d

ドロウアブルを指定する。

font_set

フォントセットを指定する。

gc

GC を指定する。

x

y

x, y 座標を指定する。

string

文字列を指定する。

num_bytes

string 引数に含まれるバイト数を指定する。

num_wchars

string 引数に含まれる文字数を指定する。

XFontSetに足りない文字集合があった場合、利用できないそれぞれの文字は XCreateFontSetが返すデフォルト文字列で描画される。 コードポイントが不正な場合の動作は未定義である。

入力メソッド

この節では、X 入力メソッド(X Input Method, XIM)について以下の内容を説 明する:

• 入力メソッドの概要
• 入力メソッドの管理
• 入力メソッド関数
• 入力メソッドの値
• 入力コンテクスト関数
• 入力コンテクストの値
• 入力メソッドのコールバックのセマンティクス
• イベントのフィルタリング
• キーボードからの入力の取得
• 入力メソッドの規約

入力メソッドの概要

この節では、国際化されたテキスト入力で用いる用語と概念の定義を行い、 Xlib が用意している機構の想定されている使い方の概要を説明する。

世界中で使われている言語の多くでは、少数のシンボル集合(文字)からなる アルファベットを使って単語を作る。 アルファベットを使う言語のテキストをコンピュータに入力するには、 ユーザは普通はアルファベットに対応する記号がキーに描かれているキーボード を使用する。 アルファベットを用いる言語でも、場合によっては一部の文字がキーボードに 載っていないことがある。 ラテン系アルファベットに基づく言語を使うコンピュータのユーザの多くは、 英語ベースのキーボードしか持っていない。 したがって、キーボードに直接用意されていない文字を入力するためには、 キーを組み合わせて叩く必要がある。 このような文字を入力するために、数多くのアルゴリズムが開発されている。 このようなものとしては、ヨーロッパ言語入力メソッド、 組み立て入力メソッド、デッドキー入力メソッド等が知られている。

日本語は表音シンボルの集合を使う言語の例である。 このような言語では、各シンボルは特定の音声を表している。 日本語には 2 つの表音シンボル集合がある。すなわち片仮名と平仮名である。 一般的には、片仮名は外国語起源の言葉に対して使われ、平仮名は日本語に元々 ある単語を書き表すために使われる。 2 つのシンボル体系はまとめて「仮名」と呼ばれる。 どちらのシンボル集合も 48 文字からなる。

韓国語も表音シンボル集合を用いる。これはハングルと呼ばれている。 24 個の基本表音シンボル(14 個の子音と 10 個の母音)のそれぞれは特定の音 を表す。 シラブルは 2 つまたは 3 つの部分からなる。 すなわち語頭子音、母音、(ない場合もある)語尾子音である。 ハングルでは、シラブルはテキスト処理の基本単位として扱われる。 例えば、文字削除の操作は表音シンボルまたはシラブルに対して行われる。 韓国語のコード集合にはこういったシラブルが数千個含まれている。 ユーザは表音シンボルを入力し、その表音シンボルが入力される単語の シラブルとなる。 表示は各表音シンボルが入力されるたびに変化する。 例えば、シラブルの中で 2 つめの表音シンボルが入力されると、 最初の表音文字の形と大きさは変化することがある。 同様に、3 番目の表音シンボルが入力されると、最初の 2 つの表音シンボル の形と大きさは変化することがある。

必ずしも全ての言語がアルファベットや表音シンボルの体系だけに依存してい るわけではない。 日本語や韓国語を含む一部の言語では、表意シンボルの体系も持っている。 表意シンボルの体系では、少数のシンボルを色々組み合わせて単語を作るので はなく、それぞれの単語がひとつのユニークなシンボルからなる(複数個の シンボルからなることもよくある)。 シンボルの数は非常に大きいことがある。 例えば中国語の表意シンボル体系である漢字では、約 50,000 個のシンボルが ある。

表意シンボル体系をコンピュータで扱う場合の問題は大きく分けて 2 つある。 最初の問題は、日本、中国、韓国で使われている標準のコンピュータ文字集合 にはおよそ 8,000 文字が含まれているが、台湾で使われている文字集合には 15,000 から 30,000 文字が含まれている点である。 そのため、1 つの文字を表現するために複数個のバイトを使う必要がある。 次の問題は、ある言語の表意シンボルが全て載っているキーボードを使うのは 明らかに実用的でない点である。 したがって、それなりの数のキーが付いているキーボードならば文字が入力で きる機構が必要となる。 このような入力メソッドは普通は表音シンボルをベースにしているが、 文字の見た目に基づく方法も存在する。

日本では仮名と表意シンボル体系の漢字が使われている。 韓国ではハングルが使われているが、表意シンボル体系の漢字(Hanja)が使わ れることもある。 ここで、日本、韓国、中国、台湾の表意シンボルを入力を考えることにする。

日本では、仮名や英語の文字を入力すると、ある領域が(場合によっては自動 的に)漢字変換のために選択される。 複数の漢字が同じ表音表現を持つ(読み方が同じ)ことがある。 文字列が入力されると、その文字に対応する文字のメニューが表示され、 ユーザはその中から適切な文字を一つ選ぶ。 最初から選択の必要がない場合や、ユーザが文字を選んだ場合は、 入力メソッドは文字列をテキストに直接挿入する。 ラテン文字を仮名や漢字に変換する手法はローマ字変換と呼ばれる。

韓国語では、普通は韓国語のテキストをハングルの形のままにすることは認め られるが、漢字由来の単語はハングルでなく漢字を使って書くことを選ぶ人も いる。 ハングルを漢字に変換するには、ユーザは変換のための領域を選択した後、 日本語で説明したのと同じ基本手法を用いる。

おそらくは日本語や韓国語には広く受け入れられた表音的記法体系があるため、 これらの国々では表意シンボルの入力のための入力メソッドはかなり標準的で ある。 キーボードのキーには英語の文字と表音シンボルが書かれており、ユーザは この 2 つのセットを切り替えることができる。

状況は中国では異なる。 専門家が広めようとしているピンインという表音体系が存在するが、中国語の テキスト入力に使うという合意はされていない。 ベンダによっては(ピンイン、あるいは別の)音声分解を使っているし、 中国語の単語の表意文字分解を使っているベンダもある。 また、実装やキーボード配列も様々である。 よく知られた入力メソッドは 16 個程度あるが、その中のどれかが標準である とははっきり言えない。

また、使われている表意シンボル集合は実際には 2 種類ある: 繁体字(昔から書かれていた中国語表記)と簡体字である。 数年前、中国政府は一部の表意文字を簡略化し、冗長なものを消してしまう キャンペーンを立ち上げた。 この計画では、文字は 5 年ごとに簡素化されることになっていた。 現在までに文字は何回か改訂され、その結果小さく簡単な集合となり、 これが簡体字となった。

入力メソッドのアーキテクチャ

前の節で示したように、言語や文化、歴史の違いにより現在使われている 入力メソッドにはたくさんの種類がある。 多くの入力メソッドが共通して持っている特徴は、ユーザはひとつの文字 (あるいは何個かの文字)を入力するために複数回のキー入力を行うかもしれな い点である。 キー入力を元に文字を作る作業は「前編集(preediting)」と呼ばれる。 前編集には複雑なアルゴリズムと巨大な辞書が必要な場合があり、 コンピュータの資源をかなり使うことがある。

入力メソッドは、実際のキー入力のフィードバック表示や ユーザによる選択候補の絞り込み、辞書の一覧表示などのための領域を 1 つ あるいはそれ以上必要とする場合がある。 関係がある入力メソッド領域は以下の通りである:

• ステータス(status)領域は物理的キーボードに付いている LED を論理的に拡張した ものである。 このウィンドウの目的は、ユーザにとって重要な入力メソッドの状態を表示す ることである。 ステータス領域はテキストデータやビットマップ、あるいはこれらを何個か 組み合わせて作られることがある。
• 前編集(preedit)領域は、クライアントが処理する前にデータを組み立 てる必要がある言語のために、中間的なテキストを表示する。
• 補助(auxiliary)領域は、入力メソッドが必要とするかもしれない ポップアップメニューやカスタマイズ設定ダイアログに使う領域である。 一つの入力メソッドは複数個の補助領域を持てる。 補助領域はクライアントは独立に入力メソッドが管理する。 補助領域は別ダイアログであると仮定される。このダイアログは入力メソッド が管理している。

前編集におけるユーザ対話のスタイルには色々なものがある。 Xlib がサポートしているスタイルは以下の通りである:

• on-the-spot 入力メソッドの場合は、 前編集データはアプリケーションウィンドウに直接表示される。 挿入される場所に前編集データが表示できるようにアプリケーションデータは 移動する。
• over-the-spot 前編集では、データは挿入位置の上に配置される前編集 ウィンドウに表示される。
• off-the-spot の前編集では、前編集ウィンドウはアプリケーション ウィンドウ内部に表示されるが、表示位置は挿入位置と異なる。 多くの場合、このタイプのウィンドウはアプリケーションウィンドウの一番下 の部分に配置される。
• root-window 前編集は、前編集ウィンドウが RootWindowの子ウィンドウである入力メソッドを指す。

もし移植性の高いプログラムは世界中の全ての言語用の入力メソッドを持たな ければならないとしたら、大量の計算リソースが必要になってしまう。 これを避けるために、別プロセスが持つ入力メソッドと通信できることが Xlib の設計の目標となっている。 このようなプロセスは入力サーバ(input server)と呼ばれる。 アプリケーションが接続すべきサーバは、アプリケーションが起動した環境に 依存する。つまり、ユーザの言語とその言語で実際に使われるエンコーディング に依存する。 入力メソッドの接続はロケール依存(locale-dependent)であると言われる。 入力メソッドの接続はユーザ依存でもある。 ある言語において、ユーザは入力メソッドのインタフェースのスタイルを (いくつか選択肢があれば)ある程度選ぶことができる。

入力サーバを使うということは通信のオーバーヘッドがかかるということであ るが、アプリケーションは再リンクすることなしに他の環境に持って行ける。 入力メソッドは入力サーバに通信するスタブとして実装してもよいし、 ローカルのライブラリとして実装してもよい。

入力メソッドはフロントエンドかバックエンドのアーキテクチャ に基づいてよい。 フロントエンドのアーキテクチャでは、X サーバに対する 2 つの別々の接続 がある: キー入力は片方に接続している入力メソッドに対して X サーバから直接送ら れ、残りのイベントは通常のクライアント接続に対して送られる。 入力メソッドはフィルタとして動作し、構成された文字列をクライアントに 送信する。 フロントエンドのアーキテクチャでは、キーイベントの消失やロッキングの問 題を避けるために 2 つの接続の間で同期を取る必要がある。

バックエンドのアーキテクチャでは、X サーバへの接続は 1 つだけ使われる。 配送機構はこのチャネルにおいて、適切なキー入力を選び出して 入力メソッドに送らなければならない。 例えば、配送機構は Help キーの入力を保持できる。 入力機構が別プロセス(つまりサーバ)の場合には、バックエンドのクライアント と入力サーバの間には特殊な通信プロトコルが必要である。

フロントエンドアーキテクチャでは、同期の問題と 文字でないキーの入力(ファンクションキー、Help など)をフィルタリングす る機構が導入される。 バックエンドのアーキテクチャは、大きな通信のオーバーヘッドを伴ったり、 プロセス切り替えを伴うことが多い。 3 つ全てのプロセス(X サーバ、入力サーバ、クライアント)が全て同一のサー バ上で動作しているならば、 バックエンドアーキテクチャではキーストロークごとに 2 回のプロセス切り 替えが起こるが、フロントエンドのアーキテクチャでは 1 回しか起こらない。 クライアントが入力メソッドとの通信に使う抽象化層はは、 XIMデータ型で表される opaque なデータ構造体である。 このデータ構造体は XOpenIM関数が返す。この関数は、指定されたディスプレイ上でい入力メソッドを オープンする関数である。 それ以降、このデータ構造体に対する操作はクライアントと入力メソッドの間 の全ての通信をカプセル化する。 X クライアントは、入力メソッドを使うためにネットワークライブラリや 自然言語パッケージを使用する必要はない。

1 つの入力サーバを 1 つ以上の言語で使い、1 つ以上のエンコーディング 方法をサポートしてもよい。 しかし、入力メソッドが返す文字列は必ず XIMオブジェクトに対応する(単一の)ロケールでエンコードされていなければなら ない。

入力コンテクスト

Xlib には、テキスト入力のためにマルチスレッドの状態を管理する機能が 用意されている。 クライアントは複数個のウィンドウを使い、それぞれのウィンドウには複数個 のテキスト入力領域があり、ユーザはこれらを任意のタイミングで切り替える かもしれない。 特定の入力スレッドの状態を表す抽象化データは入力コンテクスト(input context) と呼ばれる。 入力コンテクストの Xlib における表現は XICである。

入力コンテクストは、クライアントと入力メソッドの間の状態、属性、 セマンティクスを保持する抽象データである。 入力コンテクストは、入力メソッド、 返す文字列のエンコーディングを指定するロケール、 クライアントのウィンドウ、内部状態に関する情報、 配置や見栄えに関する各種特性を組み合わせたものである。 入力に対する入力コンテクストの概念には、グラフィックス出力に対する グラフィックスコンテクストの抽象化といくらか一致する部分がある。

1 つの入力コンテクストは必ずただ 1 つの入力メソッドに属する。 異なる入力コンテクストが同じ入力メソッドに対応する(そして多分、 クライアントのウィンドウも同じ)ことがあるかもしれない。 XICは XCreateIC関数を使って作成する。この際には XIMを引数として与え、入力コンテクストを生存期間の間入力メソッドに関連付け る。 入力メソッドを XCloseIMで閉じるときには、関連付けられているどの入力コンテクストも使用中であっ てはならない(入力メソッドを閉じる前に破棄されていることが望ましい)。

複数のテキスト入力領域を持っているクライアントの例を考えた場合、 アプリケーションプログラマは例えば以下のような実装を選択できるだろう:

• テキスト入力領域と同じ数の入力コンテクストが生成され、 クライアントは各コンテクストを参照するたびに各コンテクストに蓄積された 入力を取得する。
• 1 つのコンテクストがアプリケーションのトップレベルウィンドウに対して 生成される。 このようなウィンドウに複数個のテキスト入力領域がある場合は、 クライアントはユーザが他のテキスト入力領域に移動する度にコンテクストの 変更を行わなければならない。

アプリケーション設計者は、入力コンテクストを 1 つ使うか複数個使うかに ついて、アプリケーションのニーズに応じて広い範囲の選択が可能である。

キーボード入力の取得

入力メソッドから文字を取得するには、クライアントは その入力メソッドから生成した入力コンテクストを使って XmbLookupString関数または XwcLookupString関数を呼ばなければならない。 入力メソッドには、入力メソッドがオープンされた際のロケールとディスプレイ が関連付けられており、入力コンテクストはこのロケールとディスプレイを 継承している。 XmbLookupStringと XwcLookupStringが返す全ての文字列はそのロケールでエンコードされている。

フォーカスの管理

XmbLookupString関数と XwcLookupString関数が使われているそれぞれのテキスト入力領域には、対応する 入力コンテクストが存在する。

アプリケーションのフォーカスがテキスト入力領域に移動すると、 アプリケーションは入力コンテクストのフォーカスを その領域に対応する入力コンテクストに設定しなければならない。 入力コンテクストのフォーカスは、 適切な入力コンテクストを引数にして XSetICFocusを呼ぶことによって設定できる。

また、アプリケーションのフォーカスがテキスト入力領域の外に出たときには、 アプリケーションは対応する入力コンテクストに対するフォーカスを XUnsetICFocus を呼び出すことによって解除しなければならない。 最適化処理として、2 つの異なる入力コンテクストに対して続けて XSetICFocusを呼び出した場合には、2 番目のフォーカスの設定により最初のフォーカスは 自動的に解除される。

入力コンテクストのフォーカスの設定と解除を正しく行うためには、 アプリケーションレベルでフォーカスの変化を追いかける必要がある。 このようなフォーカスの変化は、必ずしも X サーバのフォーカスの変化とは 一致しない。

単独の入力コンテクストを使って複数のテキスト入力領域への入力を行ってい る場合には、フォーカスウィンドウが変化する度に 入力コンテクストのフォーカスウィンドウも設定する必要がある。

ジオメトリの管理

ほとんどの入力メソッドのアーキテクチャにおいては(on-the-spot は大きな 例外である)、入力メソッドは独自のデータを表示する。 視覚的に近い場所に配置するため、入力メソッドの領域はクライアント内部に 埋め込まれていると望ましいことも多い。 これを行うためには、クライアントは入力メソッドのために場所を割り当てる 必要がある。 Xlib はクライアントが与えた位置と大きさの入力メソッド用領域を使う 機能をサポートしている。 ジオメトリ管理がサポートされている入力メソッド領域は、ステータス領域と 前編集領域である。

入力メソッドのウィンドウのジオメトリ管理に関する基本的な概念は、 クライアント(またはツールキット)と入力メソッドの間での責任の適正な分担 に基づいている。

• クライアントは入力メソッドのウィンドウのジオメトリについて責任を持つ。
• 入力メソッドは、入力メソッドのウィンドウの内容について責任を持つ。

入力メソッドはクライアントにサイズの提案はできるが、位置の提案はできな い。 また、入力メソッドはサイズは提案しかできない。 入力メソッドはサイズを決定することはできず、与えられたサイズは受け入れ るしかない。

入力メソッドに対するジオメトリ管理をクライアントに行わせる前には、 ジオメトリ管理が本当に必要かどうかをはっきりさせること。 入力メソッドは、 XGetIMValuesが返す XIMStyles値に XIMPreeditAreaや XIMStatusAreaを設定することによってジオメトリ管理が必要かどうかを示す。 入力メソッドに対してジオメトリ管理を行うことをクライアントが決めると、 クライアントは XICの XNInputStyleを設定することによってその決定を示す。

クライアントが自分がジオメトリ管理を行う入力メソッドと接続すると、 クライアントは入力メソッドとジオメトリに関する調整を行わなければならな い。 ジオメトリは以下の手順で調整される:

• クライアントは、 XNAreaNeeded値に領域を設定することにより入力メソッドに領域を提案する。 クライアントが入力メソッドに対する制約条件(constraint)を持っていなけれ ば、クライアントは領域を提案しないか、幅と高さに 0 を設定する。 それ以外の場合には、クライアントはいずれかの値を設定する。
• クライアントは XIC 値 XNAreaNeededを取得する。 入力メソッドは、提案されたサイズをこの値に設定して返す。 入力メソッドは、クライアントが提案した全ての制約条件に注意すべきである。
• クライアントは XIC 値 XNAreaを設定し、入力メソッドにクライアントのウィンドウのジオメトリを知らせる。 クライアントは入力メソッドが要求したジオメトリをできるだけ尊重すべきで ある。 入力メソッドはこのジオメトリを受け入れなければならない。

ジオメトリ管理を行っているクライアントは、他の XIC 値を設定すると入力 メソッドが要求しているジオメトリが影響を受けるかもしれない点に注意する こと。 例えば、 XNFontSetと XNLineSpacingは入力メソッドが要求したジオメトリを変えるかもしれない。

XIC 値の表(13.5.6 節を参照)は、設定されると要求されたジオメトリを変更 する可能性がある値を示している。 必要に応じて入力メソッドのウィンドウのジオメトリを再調整するのは クライアントの責任である。

さらに、入力メソッドからジオメトリの変化を起こせるようなジオメトリ管理 用のコールバックが提供されている。

イベントのフィルタリング

フィルタリングの機構は、入力メソッドがクライアントに対して透過的に X のイベントを捕捉できるようにするために用意されている。 XmbLookupStringや XwcLookupString を使っているツールキット(またはクライアント)には、イベント処理機構のど こかでこのフィルタを呼び出し、入力メソッドが必要とするイベントを必ずそ の入力メソッドがフィルタリングすることが期待される。

フィルタがなければ、入力メソッドが正しく機能するために必要なイベントは クライアントが受信して破棄してしまう。 このようなイベントの例をいくつか以下に示す:

• ローカルモードの前編集ウィンドウの expose イベント。
• イベントは入力メソッドが入力サーバと通信するために使われるかもしれない。 クライアントのコードの邪魔をしたくないのであれば、このような入力サーバ のプロトコル関係のイベントは途中で止めなければならない。
• 重要なイベントは、X ツールキットイントリンシクスのライブラリが提供して いるようなトランスレーションに関連付けられる前にフィルタに送ることができる。

クライアントは XIC 値 XNFilterEventsを取得することと、そのイベントマスクを持つクライアントウィンドウに対す るイベントマスクを増加させることが期待されている。

コールバック

on-the-spot 入力メソッドが実装されている時は、クライアントだけがしかる べき場所にある前編集データの挿入や削除を行えるし、既にあるテキストを スクロールさせることもできると思われる。 つまり、キー入力のエコーバックはクライアント自身が、入力メソッドの論理 と深く結び付いた形で実現しなければならないということである。

ユーザがキー入力を行うと、クライアントは XmbLookupStringまたは XwcLookupStringを呼び出す。 on-the-spot の場合、この時点ではまだ、前編集におけるキー入力のエコーバック は行われていない。 クライアントに入力文字を処理するロジックを返す前には、検索関数は新しい キー入力を挿入するためにエコーを行うロジックを呼び出さなければならない。 それまでのキー入力による文字が作られた場合には、入力されたキー入力を削 除する必要があり、作られた文字が返される。 したがって、以下の動作が起こる。すなわち、クライアントのコードから呼び 出されているにも関わらず、入力メソッドのロジックは復帰する前に クライアントをコールバックしなければならない。 クライアントのコード、つまりコールバック手続きは入力メソッドのロジック から呼び出される。

入力メソッドのロジックがクライアントをコールバックしなければならない場 合はたくさんある。 これらのケースのそれぞれは明確なコールバック動作に対応付けされている。 クライアントがそれぞれの入力コンテクストに対し、各動作についてどの コールバックが呼び出されるかを指定することは可能である。

ステータス情報をフィードバックするために用意されたコールバックや、 入力メソッドにジオメトリ要求をさせるためのコールバックも存在する。

可視位置フィードバックマスク

on-the-spot 入力スタイルでは、利用可能な空間より長い文字列を前編集領域 に描画しようとする際に問題が起きる。一度表示領域を超えると、前編集文字 列を表示する最善の方法は明らかではなくなる。 XIMTextの可視位置フィードバックマスクを使うと、前編集文字列の重要な部分を示す ヒントの指定を入力メソッドに許すことにより、この問題を解決できる。 例えばこのようなヒントを利用すると、開発者は短い表示領域での長い前編集 領域のスクロール表示を実装できる。

前編集文字列の管理

先に強調したように、入力メソッドのアーキテクチャには前編集機能が用意さ れている。この機能は、入力する文字列を作るためのある種のプリプロセッサ をサポートする。 この場合の入力文字列の作成は、キーイベント列の解釈および、受け取った文字列を XmbLookupStringまたは XwcLookupStringを通じて返すことからなる。 これが入力メソッドの基本部分となる。

キーイベントに基づく前編集の他にも、クライアント内のテキストに基づくさ らに進んだ前編集を必要とするクライアントのための汎用的な枠組が用意され ている。この枠組は文字列変換(string conversion)と呼ばれ、 XIC 値を使って提供されている。 文字列変換の基本的な概念は、入力メソッドがユーザの前編集操作と独立に クライアントのテキストを操作できるようにすることである。

文字列変換の必要性は、言語からの必要と入力メソッドの機能に基づいている。 文字列変換の例を以下にいくつか示す:

• 音訳に基づく変換は入力メソッド内で言語固有の変換を与える。 韓国語を入力する場合には、ユーザは前編集の時、前編集の後、あるいはそれ 以外の状況(例えば、選択した文字列の変換)でハングル文字列を漢字文字列に 変換したいと考える。 変換はユーザがハングル-漢字のキーシーケンス(これは入力メソッドごとに違 うかもしれない)を入力したときに起きる。 ユーザは前編集を終えた後や、自分が選択した文字列に対して変換を行いたい と考えることもある。 したがって、変換される文字列はアプリケーションのバッファ内にあり、 入力メソッドの前編集領域には存在しない。文字列変換サービスを使うと、 クライアントはこの音訳に基づく変換を入力メソッドに要求できるようになる。 他にも色々な言語に対して音訳に基づく変換がたくさん定義されている。 例えば、日本語のかな-漢字変換などである。

  覚えておくべき重要な点は、音訳に基づく変換はユーザのリクエストの時点で 引き起こされ、入力メソッドの前編集領域に影響を与えることなく即座に クライアントに返されることである。

• 以前に確定した文字列や選択した文字列の再変換は、多くの入力メソッドが ユーザの利便のために対応している。 例えば、ユーザは前編集の際に確定キーを間違って押すこともよくある。この ような場合、入力メソッドによっては確定した文字列の「再変換」操作を 要求する特殊なキーシーケンスが用意されている。これはほとんどのテキスト エディタが持っているアンドゥ機能に似ている。 別の例は、文書の校正の際に前編集の時点での変換ミスを直したい場合である。 このような再変換は、ユーザが何らかの特別な操作を呼び出すことによって行 われるが、再変換は前編集領域の状態に影響を与えてはならない。
• 言語や入力メソッドによっては、クライアントのバッファ内で現在の スポット位置(カーソルの位置)の周りのテキストを取得できる入力メソッドが 必要な文脈依存の変換が必要となる。 このようなテキストは、前編集操作が周りの文字列(普通はスポット位置の前 の文字列)に依存するときに必要となる。 例えばタイ語の入力では特定の文字シーケンスは誤りとなるので、ある文字が 正しい単語を作るかどうかを入力メソッドでチェックさせたいことがある。 このような文脈依存のチェックをおこなう入力メソッドは、単語全体を得るた めにカーソルの現在位置の周りの文字を取得する必要がある。

  他の変換と異なり、この変換はユーザが明示的に要求することはない。 このような文脈依存の変換の機能を持つ入力メソッドは、常に文脈を クライアントに要求する必要があり、スポット位置の文脈が変化するとこの変 換にも影響を与えるかもしれない。 ユーザがカーソルを動かしたり、ふたたび編集を始めるとクライアントの文脈 が必要となるだろう。

  この理由により、この種類の変換をサポートしている入力メソッドは クライアントがいつ XmbResetICや XwcResetIC呼ぶかに注意しなければならない。普通はこれらの呼び出しは、文脈の変化を 示すからである。

文脈依存の変換の場合は単にクライアントのテキストをコピーすればよいが、 他の種類の変換では再変換や読みによる変換を実現するためには クライアントのテキストを新しいテキストに置き換える必要がある。 しかし全ての場合、変換の結果は直接得られるものでも前編集を経て得られる ものでも XmbLookupStringや XwcLookupString関数から返される。

文字列変換のサポートは XNStringConversionや XNStringConversionCallback が使えるかどうかとは独立である。 入力メソッドは文字列変換をサポートしていないかもしれないので、 クライアントは IM 値 XNQueryICValuesListを使って XGetIMValuesを呼び出してからサポートされている XIC 値をチェックすることにより、 文字列変換操作が可能かどうかを問い合わせなければならない。

これらの 2 つの値の違いは、変換を呼び出すのがクライアントであるか 入力メソッドであるかという点である。 XIC 値 XNStringConversionは、クライアントが入力メソッドに文字列変換を要求するときに使う。 クライアントはどのイベントを使って文字列変換を引き起こすかと、変換され た文字列をコピーするか削除するかを決める点について責任を持つ。 クライアントができるのは変換すべき文字列を渡すことだけである。 クライアントは、 XNStringConversionが設定されている時には XNStringConversionCallbackが行われないことを保証されている。したがって、クライアントは これらの値のいずれかを設定するだけでよい。

XIC 値 XNStringConversionCallbackは、クライアントが入力メソッドからの文字列変換についての要求を受け付け ることをクライアントから入力メソッドに通知するために使われる。 この値が設定されている場合は、どのイベントを使って文字列変換を起こすの かを決めるのは入力メソッドの責任です。 このようなイベントが起こると、入力メソッドはクライアントが用意した手続 きの呼び出しを発行し、変換すべき文字列を取得します。クライアントの コールバック手続きは文字列をコピーするか削除するかの通知を受け、 必要とされるテキストの分量についてのヒントを与えられます。 XIMStringConversionCallbackStructはどのテキストを入力メソッドに返すべきなのか指定します。

最後になりますが、コールバックから返された文字列が変換をうまく行うには 不十分な場合には、入力メソッドはクライアントの XNStringConversionCallbackを複数回呼び出すかもしれません。クライアントの手続きへの引数を使うと、 入力メソッドはクライアントのカーソル位置からの相対座標での位置(文字単 位)と必要とされるテキストのサイズを定義できます。後に続く コールバックで必要なテキストの位置とサイズを変えることにより、入力メソッ ドは追加のテキストを取得できます。

入力メソッドの管理

入力メソッドへのインタフェースが現われるのは入力メソッドの作成 (XOpenIM )と入力メソッドの解放 (XCloseIM )の時だけかもしれない。 しかし、入力メソッドは入力メソッドサーバ(IM サーバ)と複雑な通信を行う 必要がある。例を以下に示す:

• X サーバ、IM サーバ、X クライアントが非同期に動作している場合には、 完全に動き出す前の IM サーバにクライアントが接続しようとして失敗するこ とがあるかもしれない。 したがって、機構によっては IM サーバが動作開始したことをクライアントが わかるようにする必要がある。

IM サーバが利用できない時にどうすべきか決めるのはクライアントである(例: 待つ、あるいは他の IM サーバを利用する)。

• 入力メソッドによっては裏で動いている IM サーバを切り替えることができる。 このようなカスタマイズは、クライアントを立ち上げ直さなくても行えること が望ましい。

このような場合に入力メソッドの管理を行うため、以下の関数が用意されてい る:

XRegisterIMInstantiateCallback	この関数を使うと、クライアントは IM サーバが起動して利用可能になったことを Xlib が検出したときに呼び出されるコールバック手続きを登録できる。
XOpenIM	クライアントは呼び出されているコールバックの結果としてこの関数を呼び出す。
XSetIMValue ,XSetICValue	これらの関数は XIM 値、XIC 値、XNDestroyCallbackを用い、オープンされている入力メソッドに対応する IM サーバが利用できなくなったことを Xlib が検出したときに呼び出されるコールバック手続きをクライアントが登録できるようにする。さらにこの関数を使って、このような機能をサポートしている入力メソッドに対する IM サーバを切り替えることができる。IM サーバを切り替えるためのIM 値は実装依存である。後述の IM サーバ切り替えに関する説明を参照すること。
XUnregisterIMInstantiateCallback	この関数はクライアントが登録したコールバック手続きを削除する。

IM サーバの切り替えをサポートしている入力メソッドには副作用があるかも しれない:

• 入力メソッドは、任意の新しい IM サーバが既に入力メソッドに対応付けられ ている入力コンテクストが使っている入力スタイルのいずれかをサポートして いることを保証する。 しかし、サポートされている入力スタイルのリストは異なるかもしれない。

• 以前に作成された入力コンテクストに対するジオメトリ管理の要求は、 新しい IM サーバが始めるかもしれない。

ホットキー

クライアントによっては、入力メソッドの状態に関わらず 入力メソッドを抜けるために使えるキーを保証する必要がある。 例えば、クライアント固有のヘルプキーや、入力フォーカスを移動させるキー 等である。 ホットキー機構を使うと、クライアントはこの目的に使えるキーの集合を指定 できる。しかし、入力メソッドはクライアントがホットキーを指定することは 許していない。 したがって、クライアントは IM 値 XNQueryICValuesListを使って XGetIMValuesを呼び出してサポートされている XIC 値のリストをチェックすることにより、 ホットキーの対応を問い合わせなければならない。 入力メソッドのキー割り当てとぶつかっているホットキーが指定されている場 合は、ホットキーの方が入力メソッドのキー割り当てよりも優先される。

前編集状態操作

入力メソッドは、実装やロケールによって複数の内部状態を持つことがある。 しかし、ロケールと実装に独立な状態の一つに、入力メソッドが現在前編集操 作を行っているかどうかがある。 Xlib はアプリケーションがプログラム的に前編集状態を管理する方法を提供 している。入力コンテクストの前編集状態を取得する方法は 2 つ用意されて いる。 方法の一つは、XIC 値 XNPreeditStateを使って XGetICValuesを呼び出して状態を問い合わせる方法である。 もう一つの方法は、前編集状態が変化したときに必ず通知を受け取れるように する方法である。このような通知を受けるには、アプリケーションは XIC 値 XNPreeditStateNotifyCallbackを使って XSetICValuesを呼び出すことによってコールバックを登録する必要がある。 前編集状態をプログラム的に変更するには、アプリケーションは XNPreeditStateを使って XSetICValuesを呼び出す必要がある。

前編集状態を利用できるかどうかは入力メソッドによって異なる。 入力メソッドは状態の設定や取得をプログラム的に行う方法を用意していない かもしれない。したがって、クライアントは前編集状態の操作ができるかどう かを問い合わせなければならない。問い合わせを行うには、IM 値 XNQueryICValuesListを使って XGetIMValuesを呼び出し、サポートされている XIC 値のリストをチェックする。

入力メソッドの関数

接続をオープンするには XOpenIMを用いる。

XIM XOpenIM(display, db, res_name, res_class)
Display *display;
XrmDatabase db;
char *res_name;
char *res_class;

display

X サーバへの接続を指定する。

db

リソースデータベースへのポインタを指定する。

res_name

アプリケーションの完全なリソース名を指定する。

res_class

アプリケーションの完全なクラス名を指定する。

この呼び出しの送り先となる特定の入力メソッドは 現在のロケールに基づいて識別される。 XOpenIMは現在のロケールに対応するデフォルトの入力メソッドを識別する。 このデフォルト値は、 入力メソッドモディファイアに対して XSetLocaleModifiersを用いることにより変更できる。

引数 db は入力メソッドが入力メソッドのプライベートなリソースを探すため に使うリソースデータベースである。 入力コンテクストの IC 値として設定できる値をこのデータベースを使って検 索するという使い方は想定されていない。 db が NULL ならば、入力メソッドにはデータベースは渡されない。

引数 res_name と res_class はアプリケーションのリソース名と リソースクラスである。 これらの引数は、この入力メソッドに対して作成された全ての入力コンテクスト で共通して使うリソースを検索するために入力メソッドがプレフィックスとし て使うための値である。 リソース名とリソースクラスに使うも時は、X ポータブル文字集合に含まれて いなければならない。 res_name や res_class が NULL ならば、検索されるリソースは完全には指定 されない。

引数 res_name と res_class は、 XOpenIMを呼び出した後に残っていることは仮定できない。 指定されたリソースデータベースは、入力メソッドの生存期間の間は存在する ことが仮定できる。

入力メソッドをオープンできなければ、 XOpenIMは NULL を返す。

接続を閉じるには XCloseIMを用いる。

Status XCloseIM(im)
XIM im;

im

入力メソッドを指定する。

入力メソッドの属性を設定するには XSetIMValuesを用いる。

char * XSetIMValues(im, ...)
XIM im;

im

入力メソッドを指定する。

...

XIM 値を指定するための可変長引数を指定する。

入力メソッドへの問い合わせを行うには XGetIMValuesを用いる。

char * XGetIMValues(im, ...)
XIM im;

im

入力メソッドを指定する。

...

XIM 値を取得するための可変長引数リストを指定する。

XIM 値を持つ引数(名前の後にある)はそれぞれ、XIM 値が格納される場所を指 していなければならない。 つまり、XIM 値の型が T ならば、引数の型は T* でなければならない。 T そのものがポインタ型であれば、 XGetIMValuesは実際のデータを格納するためのメモリを割り当てる。この場合、 返されたポインタを使って XFreeを呼び出してデータを解放するのはクライアントの責任である。

入力メソッドに対応するディスプレイを取得するには、 XDisplayOfIMを用いる。

Display * XDisplayOfIM(im)
XIM im;

im

入力メソッドを指定する。

入力メソッドに対応するロケールを取得するには、 XLocaleOfIMを用いる。

char * XLocaleOfIM(im)
XIM im;

im

入力メソッドを指定する。

入力メソッドのインスタンス化コールバックを登録するには、 XRegisterIMInstantiateCallbackを用いる。

Bool XRegisterIMInstantiateCallback(display, db, res_name, res_class, callback, client_data)
Display *display;
XrmDatabase db;
char *res_name;
char *res_class;
XIMProc callback;
XPointer *client_data;

display

X サーバへの接続を指定する。

db

リソースデータベースへのポインタを指定する。

res_name

アプリケーションの完全なリソース名を指定する。

res_class

アプリケーションの完全なクラス名を指定する。

callback

入力メソッドのインスタンス化コールバックへのポインタを指定する。

client_data

追加的なクライアントデータを指定する。

この関数は成功時には Trueを返す。それ以外の場合には Falseを返す。

一般的なプロトタイプは以下の通りである:

void IMInstantiateCallback(display, client_data, call_data)
Display *display;
XPointer client_data;
XPointer call_data;

display

X サーバへの接続を指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われないので、常に NULL を渡すこと。

Bool XUnregisterIMInstantiateCallback(display, db, res_name, res_class, callback, client_data)
Display *display;
XrmDatabase db;
char *res_name;
char *res_class;
XIMProc callback;
XPointer *client_data;

display

db

X サーバへの接続を指定する。 リソースデータベースへのポインタを指定する。

res_name

アプリケーションの完全なリソース名を指定する。

res_class

アプリケーションの完全なクラス名を指定する。

callback

入力メソッドのインスタンス化コールバックへのポインタを指定する。

client_data

追加のクライアントデータを指定する。

入力メソッド値

以下の表は、入力メソッドが XIM 値をどのように解釈するかを示している。 最初のカラムには XIM 値が列挙されている。 2 番目のカラムは、その入力スタイルがそれぞれの XIM 値をどのように扱う かを示す。

この表には以下のキーが適用される。

キー	説明
D	この値はXSetIMValuesを使って設定できる。 この値が設定されていなければ、デフォルト値が与えられる。
S	この値はXSetIMValues を使って設定できる。
G	この値は、XGetIMValuesを使って読み出せる。

XIM 値	キー
XNQueryInputStyle	G
XNResourceName	D-S-G
XNResourceClass	D-S-G
XNDestroyCallback	D-S-G
XNQueryIMValuesList	G
XNQueryICValuesList	G
XNVisiblePosition	G
XNR6PreeditCallbackBehavior	D-S-G

XNR6PreeditCallbackBehaviorは古い値なので、使わないことが推奨される(13.5.4.6 節を参照)。

入力スタイルの問い合わせ

クライアントはどの入力スタイルがサポートされているかを調べるため、必ず 入力メソッドに問い合わせるべきである。 その後でクライアントはその中から自身がサポートできる入力スタイルを見つ けるべきである。

クライアントはサポートできる入力スタイルが見つけられなかった場合、クラ イアントはプログラムの動作継続についてユーザに問い合わせるべきである (終了、他の入力メソッドの選択など)。

引数は返された値が格納される場所を指すポインタでなければならない。 返される値は XIMStyles型の構造体へのポインタである。 クライアントは XIMStyles構造体を解放する責任を持つ。 構造体を解放するには XFreeを用いる。

XIMStyles構造体は以下のように定義されている:

typedef unsigned long XIMStyle;

#define	XIMPreeditArea	0x0001L
#define	XIMPreeditCallbacks	0x0002L
#define	XIMPreeditPosition	0x0004L
#define	XIMPreeditNothing	0x0008L
#define	XIMPreeditNone	0x0010L
#define	XIMStatusArea	0x0100L
#define	XIMStatusCallbacks	0x0200L
#define	XIMStatusNothing	0x0400L
#define	XIMStatusNone	0x0800L

typedef struct {
	unsigned short count_styles;
	XIMStyle * supported_styles;
} XIMStyles;

XIMStyles構造体は、サポートされている入力スタイルの数を count_styles フィールドに持っている。 この値は配列 supported_styles の大きさでもある。

サポートされているスタイルはビットマスクを組合せたもののリストであり、 サポートされている領域のそれぞれについてスタイルの組合せを示す。 これらの領域については後述する。 リスト中の各要素の値としては、各領域のビットマスク値のいずれかを選択し なければならない。 このリストはサポートされている組合せの完全な集合を示す。 入力メソッドがサポートしているのは、これらの組合せだけである。

前編集カテゴリは、入力メソッドが前編集情報のために用意している サポートの種類を定義する。

XIMPreeditArea	これを選ぶと、入力メソッドは前編集に使う領域を示す何らかの値をクライアントに要求する。XIC 値XNAreaおよびXNAreaNeededを参照すること。
XIMPreeditPosition	この値を選ぶと、入力メソッドは位置に関する値をクライアントに要求する。XIC 値XNSpotLocationおよびXNFocusWindowを参照すること。
XIMPreeditCallbacks	この値を選ぶと、入力メソッドは前編集コールバックの集合を定義することをクライアントに要求する。XIC 値XNPreeditStartCallback ,XNPreeditDoneCallback , XNPreeditDrawCallback ,XNPreeditCaretCallbackを参照すること。
XIMPreeditNothing	この値を選ぶと、入力メソッドは前編集に関する値がない状態で動作できる。
XIMPreeditNone	入力メソッドは前編集に関するフィードバックをまったく行わない。前編集に関する全ての値は無視される。このスタイルは、他の前編集スタイルとお互いに排他である。

状態カテゴリは入力メソッドが状態情報のために提供する サポートの種類を定義する。

XIMStatusArea	入力メソッドは、状態のフィードバックを行うための領域に関する何らかの値をクライアントに要求する。XNAreaおよびXNAreaNeededを参照すること。
XIMStatusCallbacks	入力メソッドは状態コールバックの集合を定義することをクライアントに要求する。状態コールバックにはXNStatusStartCallback , XNStatusDoneCallback ,XNStatusDrawCallbackがある。
XIMStatusNothing	入力メソッドは状態値が全くなくても機能できるようになる。
XIMStatusNone	入力メソッドは状態フィードバックをまったく行わなくなる。この値を選ぶと、状態値は無視される。このスタイルは他の状態スタイルと互いに排他である。

リソースの名称とクラス

引数 XNResourceNameと XNResourceClassは入力メソッドが使う名前とクラスを完全に指定する文字列である。 これらの値は、入力メソッドごとに変わるリソースを検索する時に 名前とクラスに対するプレフィックスとして使われなければならない。 これらの値が設定されていなければ、リソースは完全には指定されない。

XIM 値として設定できる値をリソースとして設定する使い方は意図されていな い。

コールバックの破棄

引数 XNDestroyCallback は XIMCallback型の構造体へのポインタである。 XNDestroyCallbackは、入力メソッドが何らかの理由でサービスを停止した時に起こる。 コールバックが呼び出された後、入力メソッドはクローズされ、 これに対応する入力コンテクスト(複数個の場合もある)は Xlib によって破棄 される。 したがって、クライアントは XCloseIMや XDestroyICを呼んではならない。

このコールバック関数の一般的なプロトタイプは以下の通りである:

void DestroyCallback(im, client_data, call_data)
XIM im;
XPointer client_data;
XPointer call_data;

im

入力メソッドを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われないので、常に NULL を渡すこと。

IM 値/IC 値のリストの問い合わせ

XNQueryIMValuesListと XNQueryICValuesListは、入力メソッドがサポートしている XIM 値と XIC 値について問い合わせる ために使われる。

引数の値は返される値が格納される場所を指すポインタでなければならない。 返される値は、 XIMValuesList型の構造体へのポインタである。 クライアントは XIMValuesList構造体を解放する責任を持つ。 解放するには XFreeを用いる。

XIMValuesList構造体の定義は以下の通りである:

typedef struct {
	unsigned short count_values;
	char **supported_values;
} XIMValuesList;

視覚的な位置

引数 XNVisiblePositionは、 XIMText内の XIMFeedbackの視覚的な位置のマスクが利用可能かどうかを示す。

この引数の値は返される値が格納される場所を指すポインタでなければならな い。返される値は Bool型である。 返された値が Trueならば、入力メソッドは XIMText内の XIMFeedbackの視覚的な位置のマスクを用いる。 それ以外の場合には、入力メソッドはマスクを使わない。

XIM 値は省略可能なので、クライアントはこの引数を使う前には 引数 XNQueryIMValuesを使って XGetIMValuesを呼び出さなければならない。 XNQueryIMValuesが返した IM 値のリスト内に XNVisiblePositionが存在しない場合は、 XIMText内の XIMFeedbackの視覚的な位置のマスクは、視覚的な位置を示すためには使われない。

前編集コールバックの動作

元々は X11R6 の仕様に含まれていた引数 XNR6PreeditCallbackBehaviorは、使われないことになっている。 X11R6 の仕様の策定の間、R6 の PreeditDrawCallbacks の動作は R5 の コールバックの動作と大きく変わりかけた。 後になっての仕様変更で R5 と R6 の動作はまとめられたため、 XNR6PreeditCallbackBehaviorは不要になった。 残念ながら、この引数は R6 の仕様が公開される前に削除されなかった。 .FE

引数 XNR6PreeditCallbackBehaviorは、 XIMPreeditDrawCallbackStruct値に関する前編集コールバックの動作がリリース 5 とリリース 6 のどちらの セマンティクスに従うかを示す。

この値は Bool型である。 XNR6PreeditCallbackBehaviorを問い合わせた時に返された値が Trueならば、入力メソッドはリリース 6 の動作を行う。 そうでなければ、入力メソッドはリリース 5 の動作を行う。 デフォルト値は Falseである。 リリース 6 のセマンティクスを用いるためには、 XNR6PreeditCallbackBehaviorの値を Trueに設定しなければならない。

XIM 値は省略可能なので、クライアントはこの引数を使う前に XNQueryIMValuesを引数として XGetIMValuesを呼び出さなければならない。 XNQueryIMValuesが返した IM 値のリスト内に XNR6PreeditCallbackBehaviorが存在しなければ、PreeditCallback の動作はリリース 5 のセマンティクス である。

入力コンテクストの関数

入力コンテクストは、(もしあれば)入力メソッドが必要とするデータとそのデー タを表示するために必要な情報を持つために用いられる抽象化層である。 1 つの入力メソッドに対して複数の入力コンテクストが存在することができる。 入力コンテクストの生成、読み込み、修正のためのプログラミング インタフェースは、可変長引き数リストを用いる。 引数リストの名前要素は、XIC 値として参照される。 これは入力メソッドをこれらの XIC 値で制御するためのものである。 新しい XIC 値を作った場合は、X コンソーシアムに登録すべきである。

入力コンテクストを生成するには XCreateICを用いる。

XIC XCreateIC(im, ...)
XIM im;

im

入力メソッドを指定する。

...

XIC 値を設定するための可変長引数リストを指定する。

一部の引数は生成時に必須であり、必須の引数が指定されなければ、 入力コンテクストは生成されない。 必須の引数は入力スタイルと、テキストコールバックの集合である(後者が必 要となるのはコールバックを必要とする入力スタイルを選んだ場合)。 他の全ての入力コンテクスト値は後から設定できる。

入力コンテクストを生成できなければ、 XCreateICは NULL を返す。 NULL は以下のいずれかの理由によっても返されることがある:

• 必要な引数が設定されていない。
• 読み取り専用の引数( XNFilterEvents)を設定しようとした。
• 引数の名前が認識できない。
• 入力メソッドが、入力メソッドの実装依存のエラーに出会った。

XCreateICはエラー BadAtom ,BadColor ,BadPixmap ,BadWindowを起こすことがある。

入力コンテクストを破棄するには XDestroyICを用いる。

void XDestroyIC(ic)
XIC ic;

ic

入力コンテクストを指定する。

クライアント側からのキーボードフォーカスの変更について 入力メソッドと通信したり同期を取るには、 XSetICFocusと XUnsetICFocusを用いること。

void XSetICFocus(ic)
XIC ic;

ic

入力コンテクストを指定する。

XSetICFocusを呼び出しても、フォーカスウィンドウ値には影響を与えない。

void XUnsetICFocus(ic)
XIC ic;

ic

入力コンテクストを指定する。

XUnsetICFocusを呼び出してもフォーカスウィンドウには影響を与えない。 この関数が呼び出されても、クライアントはフォーカスウィンドウに送られる イベントを入力メソッドから受け取ることができる。

入力コンテクストの状態を初期状態にリセットするには XmbResetICまたは XwcResetICを用いる。

char * XmbResetIC(ic)
XIC ic;

wchar_t * XwcResetIC(ic)
XIC ic;

ic

入力コンテクストを指定する。

XmbResetICの戻り値としては、現在の前編集文字列がマルチバイト文字列として返される。 前編集領域にテキストが書かれていたりユーザに見えている場合には、 これらの手続きは NULL でない文字列を返さなければならない。 見える状態の前編集テキストがない場合には、 これらの手続きが NULL でない文字列を返すか NULL を返すかは入力メソッド の実装依存である。

クライアントは XFreeを呼び出して返された文字列を解放しなければならない。

入力メソッドに対応付けられた入力メソッドを取得するには XIMOfIC を用いる。

XIM XIMOfIC(ic)
XIC ic;

ic

入力コンテクストを指定する。

XIC 値の設定と読み取りを行うため、Xlib には XSetICValuesと XGetICValuesという 2 つの関数が用意されている。 どちらの関数も可変長引数リストを取る。 この引数リストの中では、XIC 値の全ての名前は X ポータブル文字集合を使った文字列で書かなければならない。

XIC 値を設定するには XSetICValuesを用いる。

char * XSetICValues(ic, ...)
XIC ic;

ic

入力コンテクストを指定する。

...

XIC 値を設定するための可変長引数リストを指定する。

• 引数が読み取り専用だった(例えば XNFilterEventsだった)。
• 引数の名前が識別できない。
• 実装依存のエラーが起きた。

設定されるそれぞれの値は、引数のセマンティクスによって決まるデータ型に 一致する適切なデータでなければならない。

XSetICValuesはエラー BadAtom ,BadColor ,BadCursor ,BadPixmap ,BadWindow を起こすことがある。

XIC 値を取得するには XGetICValues を用いる。

char * XGetICValues(ic, ...)
XIC ic;

ic

入力コンテクストを指定する。

...

XIC 値を取得するための可変長引数リストを指定する。

• 引数の名前が識別できなかった。
• 入力メソッドが実装依存のエラーに出会った。

引数となる各 IC 値(名前の後に続く)は、IC 値を格納すべき場所を指してい なければならない。 つまり IC 値の型が T ならば引数の型は T* でなければならない。 T 自身がポインタ型の場合は、 XGetICValuesは実際のデータを格納するメモリを割り当てる。 クライアントは返されたポインタを使って XFreeを呼び出し、このデータを解放する責任を持つ。 この規則の例外は XVaNestedList型の IC 値(前編集と状態の属性)の場合である。 この場合には、引数の型は XVaNestedListでなければならない。 そして、型 T を T* に変える規則と、割り当てられたデータを解放する規則 は、入れ子になったリストのそれぞれの要素に適用される。

入力コンテクストの値

以下の表は、ユーザが選択した入力スタイルによって入力メソッドの XIC 値 の解釈がどうなるかを示している。

最初のカラムは XIC 値である。 2 番目のカラムは、どの値が入力メソッドのウィンドウのジオメトリの影響、 調整、設定の対象となるかを示す。 3 番めのカラムにある副項目は、サポートされている別の入力メソッドを指し ている。 これらのカラムのそれぞれは、その入力スタイルによる各 XIC 値の扱いを示 す。

表では以下のキーが適用される。

キー	説明
C	この値はXCreateIC を使って設定しなければならない。
D	この値はXCreateICを使って設定してもよい。設定されなければ、デフォルト値が使われる。
G	この値はXGetICValuesを使って読み出せる。
GN	この値は、XCreateICやXSetICValuesを使って値を設定するとジオメトリの調整を起こすことがある。
GR	この値は、いずれかの GN 値が変更されたときに、入力メソッドの応答となる。
GS	この値は、入力メソッドのウィンドウのジオメトリの設定を起こす。
O	この値はただ 1 度だけ設定しなければならない。生成時に設定する必要はない。
S	この値はXSetICValues を使って設定できる。
無視	指定された入力スタイルに対する入力メソッドは、この値を無視する。

l c c c c c c
		入力スタイル
XIC 値	ジオメトリ	前編集	前編集	前編集	前編集	前編集
	管理	コールバック	位置	領域	なし	なし
入力スタイル		C-G	C-G	C-G	C-G	C-G	クライアントウィンドウ		O-G	O-G
O-G	O-G	無視	フォーカスウィンドウ	GN	D-S-G	D-S-G	D-S-G	D-S-G	無視	リソース名
	無視	D-S-G	D-S-G	D-S-G	無視	リソースクラス		無視	D-S-G	D-S-G
D-S-G	無視	ジオメトリコールバック		無視	無視	D-S-G	無視	無視	フィルタイベント
G	G	G	G	無視	破棄コールバック		D-S-G	D-S-G	D-S-G	D-S-G
D-S-G	文字列変換コールバック		S-G	S-G	S-G	S-G	S-G	文字列変換		D-S-G
D-S-G	D-S-G	D-S-G	D-S-G	状態リセット		D-S-G	D-S-G	D-S-G	D-S-G	無視
ホットキー		S-G	S-G	S-G	S-G	無視	ホットキーの状態		D-S-G	D-S-G
D-S-G	D-S-G	無視	前編集	領域	GS	無視	D-S-G	D-S-G	無視	無視
必要な領域	GN-GR	無視	無視	S-G	無視	無視	スポット位置		無視	D-S-G
無視	無視	無視	カラーマップ		無視	D-S-G	D-S-G	D-S-G	無視	前景色
	無視	D-S-G	D-S-G	D-S-G	無視	背景色		無視	D-S-G	D-S-G
D-S-G	無視	背景ピックスマップ		無視	D-S-G	D-S-G	D-S-G	無視	フォントセット	GN
無視	D-S-G	D-S-G	D-S-G	無視	行間隔	GN	無視	D-S-G	D-S-G	D-S-G
無視	カーソル		無視	D-S-G	D-S-G	D-S-G	無視	前編集の状態		D-S-G
D-S-G	D-S-G	D-S-G	無視	前編集状態通知コールバック		S-G	S-G	S-G	S-G	無視
前編集コールバック		C-S-G	無視	無視	無視	無視

l c c c c c
		入力スタイル
XIC 値	ジオメトリ	状態	状態	状態	状態
	管理	コールバック	領域	なし	なし
入力スタイル		C-G	C-G	C-G	C-G	クライアントウィンドウ		O-G	O-G
O-G	無視	フォーカスウィンドウ	GN	D-S-G	D-S-G	D-S-G	無視	リソース名
無視	D-S-G	D-S-G	無視	リソースクラス		無視	D-S-G	D-S-G	無視
ジオメトリコールバック		無視	D-S-G	無視	無視	フィルタイベント		G	G
G	G	ステータス	領域	GS	無視	D-S-G	無視	無視	必要な領域
GN-GR	無視	S-G	無視	無視	カラーマップ		無視	D-S-G	D-S-G
無視	前景色		無視	D-S-G	D-S-G	無視	背景色		無視
D-S-G	D-S-G	無視	背景ピックスマップ		無視	D-S-G	D-S-G	無視	フォントセット
GN	無視	D-S-G	D-S-G	無視	行間隔	GN	無視	D-S-G	D-S-G
無視	カーソル		無視	D-S-G	D-S-G	無視	状態コールバック		C-S-G
無視	無視	無視

入力スタイル

引数 XNInputStyleは使用する入力スタイルを指定する。 引数の値は、 supported_styles リストに引数 XNQueryInputStyleを指定して関数 XGetIMValuesを呼んだ際に返される値のいずれかでなければならない。

この引数は生成時に設定する点と変更してはならない点に注意すること。

クライアントウィンドウ

引数 XNClientWindowは、入力メソッドがデータを表示できるかサブウィンドウを表示できる クライアントウィンドウを入力メソッドに対して指定する。 入力メソッド領域に対するジオメトリ値は、クライアントウィンドウについて 与えられる。 クライアントウィンドウの動的な変更はサポートされていない。 この引数は一度しか設定できない。また、この入力コンテクストを使って 何らかの入力が行われる前に設定すべきである。 設定されていなければ入力メソッドは正しく動作しないかもしれない。

XSetICValuesを使ってこの値を 2 回目に設定しようとすると、文字列 XNClientWindowが XSetICValuesから返され、クライアントウィンドウは変化しない。

クライアントウィンドウがディスプレイ上で正しいウィンドウ ID を持ってい なければ、入力メソッドがこの値を使ったときにエラー BadWindow が生成される場合がある。

フォーカスウィンドウ

引数 XNFocusWindowはフォーカスウィンドウを指定する。 XNFocusWindowの主目的は、入力が構成された時にキーイベントを受け取るウィンドウを識別 することである。 これに加えて、入力メソッドはフォーカスウィンドウに以下のような影響を与 えることがある:

• フォーカスウィンドウでイベントを選択する
• フォーカスウィンドウにイベントを送る
• フォーカスウィンドウの属性を変更する
• そのウィンドウ内のキーボードをグラブする

対応する値の型は Windowでなければならない。 フォーカスウィンドウがディスプレイ上で入力メソッドに割り当てられた正し いウィンドウIDを持たない場合、この値を入力メソッドが用いるとエラー BadWindowが生成されることがある。

この XIC 値が指定されずに残された場合、入力メソッドはクライアントの ウィンドウをデフォルトのフォーカスウィンドウとして用いる。

リソース名とクラス

引数 XNResourceNameと XNResourceClassは、クライアントがクライアントウィンドウのためのリソースを取得するため に使う完全な名前とクラスを指定する文字列である。 これらの値は、入力コンテクストによって変わることがあるリソースを探すた めに名前やクラスのプレフィックスとして使うべきである。 これらの値が設定されていなければ、リソースは完全には指定されない。

XIC 値として設定できる値をリソースとして設定することは意図されていない。

ジオメトリコールバック

引数は XNGeometryCallbackXIMCallback 型の構造体である(13.5.6.13.12 節を参照)。

引数 XNGeometryCallbackはクライアントが設定できるジオメトリコールバックを指定する。 このコールバックは入力メソッドやクライアントが正しい動作を行うために 必ず必要なわけではない。 このコールバックは、ユーザインタフェースの方針により入力メソッドが 入力メソッドのウィンドウの動的な変化を要求することが許されている クライアントのために設定できる。 動的に変化する入力メソッドは、変更を開始するために使う全てのイベントを フィルタリングする必要がある。

フィルタイベント

引数 XNFilterEventsは、入力メソッドが選択している必要があるイベントマスクを返す。 クライアントはクライアントウィンドウに対して、 このマスクを使って独自のイベントマスクを増やすことが期待される。

この引数は読み取り専用であり、生成時に入力メソッドが生成し、それ以降は 変更されることはない。

この引数の型は unsignedlongである。 この値を設定するとエラーとなる。

破棄コールバック

引数 XNDestroyCallback は XIMCallback 型の構造体へのポインタである。このコールバックは、入力メソッドが何らか の理由でサービスを停止したときに引き起こされる。例えば、 IM サーバとの接続が切れた場合などである。破棄コールバックが呼ばれた後 は、入力コンテクストは破棄され、入力メソッドはクローズされる。 したがって、クライアントは XDestroyICや XCloseIMを呼び出してはならない。

文字列変換コールバック

引数 XNStringConversionCallbackは XIMCallback 型の構造体である(13.5.6.13.12 節を参照)。

引数 XNStringConversionCallbackは文字列変換コールバックを指定する。このコールバックは入力メソッドや クライアントが正しい動作を行うために必ずしも必要ではない。この コールバックは、入力メソッド側から要求する文字列変換に対応するために クライアントが設定する。文字列変換を行う入力メソッドは、変換を始めるた めに使う全てのイベントをフィルタリングする。

XIC 値は省略可能なので、クライアントはこの引数を使う前には 引数 XNQueryICValuesListを使って XGetIMValuesを呼び出さなければならない。

文字列変換

引数 XNStringConversionは XIMStringConversionText型の構造体である。

引数 XNStringConversionは入力メソッドに変換させる文字列を指定する。 この引数は入力メソッドやクライアントが正しく動作するためには必ずしも必 要ない。

文字列変換は、前編集と独立なテキストの操作を容易にする。 一部の入力メソッドとクライアントにとっては、コンテクスト依存の変換や 再変換、読みによる変換によってテキストを操作することは重要である。

XIC 値は省略可能なので、クライアントはこの引数を使う前には XNQueryICValuesList引数を使って XGetIMValuesを呼び出さなければならない。

XIMStringConversionText構造体の定義は以下の通りである:

typedef struct _XIMStringConversionText {
	unsigned short length;
	XIMStringConversionFeedback *feedback;
	Bool encoding_is_wchar;
	union {
		char	*mbs;
		wchar_t *wcs;
	} string;
} XIMStringConversionText;
typedef unsigned long XIMStringConversionFeedback;

feedback メンバは将来使うために予約されている。変換すべきテキストは string メンバと length メンバを使って定義する。length メンバの長さは 文字数で表す。初期化されていないポインタが指しているメモリをライブラリ が解放してしまうのを避けるため、クライアントは feedback メンバに NULL を設定すべきである。

状態リセット

引数 XNResetStateは、 XmbResetICや XwcResetICを呼び出した後に入力コンテクストが戻る状態を指定する。

XCreateICが呼ばれたときの XNPreeditState値の設定によっては、 XIC 値は初期値に設定されるかもしれないし、現在の状態を保持するように 設定されるかもしれない。

XIMResetStateの有効なマスク指定は以下の通りである:

typedef unsigned long XIMResetState;

#define	XIMInitialState	(1L)
#define	XIMPreserveState	(1L<<1)

XIMInitialStateが設定されていると、 XmbResetICと XwcResetICは XIC に対して XNPreeditStateの初期値を返す。

XIMPreserveStateが設定されていると、 XmbResetICと XwcResetICは XIC の現在の状態を保つ。

XNResetStateが指定されていなければ、デフォルト値は XIMInitialStateである。

XIMResetState値が先に仕様説明した以外の値ならば、デフォルト値の XIMInitialStateとなる。

この XIC 値は省略できるので、クライアントはこの引数を使う前には引数 XNQueryICValuesListを使って XGetIMValuesを呼び出さなければならない。

ホットキー

引数 XNHotKeyは、XIC に対してホットキーのリストを指定する。 ホットキーのリストは XIMHotKeyTriggers型の構造体へのポインタである。この構造体は入力メソッドの割り込みを受け ることなく受け取らなければならないキーイベントを指定する。 この引数に設定されたホットキーのリストを利用するためには、 クライアントは XNHotKeyStateを XIMHotKeyStateONに設定する必要もある。

XIC 値は省略できるので、クライアントはこの機能を使う前には引数 XNQueryICValuesListを使って XGetIMValuesを呼び出さなければならない。

この引数の値は XIMHotKeyTriggers型の構造体を指すポインタでなければならない。

ホットキーのリストに含まれるキーに対するイベントが検出された場合は、 プロセスはこのイベントを受け取ってクライアントの内部で処理する。

typedef struct {
	KeySym keysym;
	unsigned int modifier;
	unsigned int modifier_mask;
} XIMHotKeyTrigger;
typedef struct {
	int num_hot_key;
	XIMHotKeyTrigger *key;
} XIMHotKeyTriggers;

modifier と modifier_mask の組合せは、各モディファイアの 3 つの状態の いずれかを表すために使われる: 3 つの状態とは、「モディファイアはオンでなければならない」、「モディファイア はオフでなければならない」、「モディファイアは『気にしない』――つまり オンでもオフでもかまわない」である。 modifier_mask のビットが 0 に設定されていると、これに対応する モディファイアは、そのキーがホットキーかどうかを評価する際に無視される。

モディファイアビット	マスクビット	意味
0	1	モディファイアはオフでなければならない。
1	1	モディファイアはオンでなければならない。
n/a	0	モディファイアがオンかオフかは気にしない。

ホットキーの状態

引数 XNHotKeyStateは入力メソッドのホットキーの状態を指定する。 この引数は普通、入力メソッドでホットキーに対応する動作と通常の入力処理 を切り替えるために使う。

この引数の値は XIMHotKeyState型の構造体へのポインタである。

typedef unsigned long XIMHotKeyState;

#define	XIMHotKeyStateON	(0x0001L)
#define	XIMHotKeyStateOFF	(0x0002L)

この引数が指定されていなければ、デフォルト値は XIMHotKeyStateOFFとなる。

前編集属性と状態属性

引数 XNPreeditAttributesと XNStatusAttributesは、前編集領域と状態表示領域(もしあれば)に適用する属性を入力メソッドに 対して指定する。 これらの属性は、入れ子になった可変長のリストとして XSetICValuesと XGetICValuesに渡される。 これらのリストで使われる名前については以下の節で説明する。

領域

引数 XNAreaは XRectangle型の構造体へのポインタでなければならない。 引数 XNAreaの解釈は、設定される入力メソッドのスタイルに依存する。

入力メソッドのスタイルが XIMPreeditPositionならば、 XNAreaは前編集が起こるクリップ領域を指定する。 フォーカスウィンドウが設定されていると、座標はフォーカスウィンドウに対 する相対座標とされる。 設定されていない場合は、座標はクライアントのウィンドウに対する相対座標 とされる。 どちらも設定されていなければ、結果は未定義である。

XNAreaが指定されていない場合や NULL が設定されている場合、あるいは不正である 場合には、入力メソッドはデフォルトでクリッピング領域を XNFocusWindowのジオメトリに設定する。 領域が NULL または不正である場合の結果は未定義である。

入力スタイルが XIMPreeditAreaまたは XIMStatusAreaの場合、 XNAreaはクライアントが入力メソッドに与えたジオメトリを指定する。 入力メソッドはこの領域を使ってデータを表示してよい。 これは指定された領域によって前編集領域または状態領域となる。 入力メソッドは、 XNAreaに適合するディメンジョンを持つクライアントウィンドウの子ウィンドウとし てウィンドウを生成できる。 この座標はクライアントウィンドウに対する相対座標である。 クライアントウィンドウがまだ設定されていなければ、 入力メソッドはこれらの値を保存し、クライアントウィンドウが設定された時 にこれらの値を適用しなければならない。 XNAreaが指定されていない場合や NULL が設定されている場合、あるいは不正な場合 には、結果は未定義となる。

必要な領域

引数 XNAreaNeededが設定されていると、この引数はこの領域(前編集領域または状態領域)に対し てクライアントが提示しているジオメトリを指定する。 この引数に対応する値は XRectangle型の構造体へのポインタでなければならない。 x, y の値は使われない点と、0 でない値を幅と高さに設定される クライアントが入力メソッドに希望する制約となる点に注意すること。

読み込んだとき、引数 XNAreaNeededは入力メソッドがその領域に対して希望している望ましいジオメトリを指定する。

この引数は、入力メソッドが XIMPreeditAreaまたは XIMStatusAreaの場合に限って有効である。 この引数はクライアントと入力メソッドの間のジオメトリ調整に使われ、それ 以外の影響を入力メソッドに与えることはない(13.5.1.5 節を参照)。

スポット位置

引数 XNSpotLocationは、 XNInputStyleに XIMPreeditPositionが設定されて動作している入力メソッドに使用されるスポットの座標を 入力メソッドに対して指定する。 XIMPreeditPosition以外の入力メソッドに対して指定されたときは、この XIC 値は無視される。

x 座標は次の文字が挿入される場所を指定する。 y 座標はフォーカスウィンドウないの現在のテキスト行が使うベースラインの 位置を指定する。 x, y 座標はフォーカスウィンドウが設定されていれば、これに対する 相対座標となる。 設定されていない場合はクライアントウィンドウに対する相対座標となる。 フォーカスウィンドウとクライアントウィンドウのいずれも設定されていなけ れば、結果は未定義である。

引数の値は XPoint型の構造体へのポインタとなる。

カラーマップ

色、カラーマップの ID, 標準のカラーマップ名を割り当てるために 入力メソッドがどのカラーマップを使うべきかを示すために、2 つの異なる引 数を使用できる。

引数 XNColormapはカラーマップの ID を指定するために使われる。 この引数の値は Colormap型である。 不正な引数を指定すると、引数を入力メソッドが使ったときに BadColorエラーが生成されるかもしれない。

引数 XNStdColormapは、入力メソッドが色の割り当てに使う標準カラーマップの名前を示すために 使われる。 この引数の値は Atomであり、 XGetRGBColormapsの呼び出しに正しく使えるアトムでなければならない。 不正な引数を指定すると、この引数を入力メソッドが使った際に BadAtomが起きることがある。

カラーマップが指定されていないままだと、クライアントウィンドウの カラーマップはデフォルトとなる。

前景色と背景色

引数 XNForeground値は前景色ピクセルを示し、引数 XNBackgroundは背景色ピクセルを表す。 この引数の型は unsignedlongである。 この引数は、入力メソッドのカラーマップにおける正しいピクセルでなければ ならない。

これらの値が指定されないままであれば、入力メソッドがデフォルト値を 決定する。

背景ピックスマップ

引数 XNBackgroundPixmapは、ウィンドウの背景として使われる背景ピックスマップを指定する。 この値の型は Pixmapでなければならない。 不正な引数を与えると、入力メソッドが使おうとした時に BadPixmapエラーが起こることがある。

値が指定されないままであれば、入力メソッドがデフォルト値を決定する。

フォントセット

引数 XNFontSetは使用するフォントを入力メソッドに対して指定する。 この引数の値の型は XFontSetである。

値が指定されないままであれば、入力メソッドがデフォルト値を決定する。

行間隔

引数 XNLineSpaceは、前編集ウィンドウで複数行にわたる表示が行われる場合に使用する行間隔 を入力メソッドに対して指定する。 この引数の型は intである。

この値が指定されないままであれば、入力メソッドがデフォルト値を決定する。

カーソル

引数 XNCursorは、指定されたウィンドウで使われるカーソルを入力メソッドに対して指定す る。 この引数の型は Cursorである。

不正な引数を指定すると、この引数を入力メソッドが使った時に BadCursorエラーが起こるかもしれない。 この値が指定されないままであれば、入力メソッドがデフォルト値を指定する。

前編集状態

引数 XNPreeditStateは、入力メソッドに対して入力前編集の状態を指定する。 入力の前編集はオンまたはオフにできる。

XNPreeditStateに対して有効なマスク名は以下の通りである:

typedef unsigned long XIMPreeditState;

#define	XIMPreeditUnknown	0L
#define	XIMPreeditEnable	1L
#define	XIMPreeditDisable	(1L<<1)

XIMPreeditEnableが値として設定されていると、入力メソッドは入力前編集をオンにする。

XIMPreeditDisableが値として設定されていると、入力メソッドは入力前編集をオフにする。

XNPreeditStateが指定されていない場合には、この状態は実装依存となる。

XNResetStateに XIMInitialStateが設定されていると、生成時に指定される XNPreeditStateは XmbResetICや XwcResetICに対する初期状態として反映されるようになる。

XIC 値は省略できるので、この引数を使う前には引数 XNQueryICValuesListを使って XGetIMValuesを呼び出さなければならない。

前編集状態通知コールバック

前編集状態通知コールバックは、前編集状態が変化したときに入力メソッドに よって引き起こされる。 引数 XNPreeditStateNotifyCallbackの値は XIMCallback型の構造体へのポインタである。 コールバックの一般的なプロトタイプは以下の通りである:

void PreeditStateNotifyCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XIMPreeditStateNotifyCallbackStruct *call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

現在の前編集状態を指定する。

typedef struct _XIMPreeditStateNotifyCallbackStruct {
	XIMPreeditState state;
} XIMPreeditStateNotifyCallbackStruct;

XIC 値は省略できるので、クライアントはこの引数を使う前に引数 XNQueryICValuesListを使って XGetIMValuesを呼び出さなければならない。

前編集コールバックと状態コールバック

入力スタイル XIMPreeditCallbacksに対応しようとするクライアントは、ある決められた前編集コールバック群を 入力メソッドに提供しなければならない。

XNPreeditStartCallback	このコールバックは入力メソッドが前編集を開始したときに呼ばれる。
XNPreeditDoneCallback	このコールバックは入力メソッドが前編集を停止したときに呼ばれる。
XNPreeditDrawCallback	このコールバックは、多くの前編集キーストロークをエコー表示しなければならない時に呼ばれる。
XNPreeditCaretCallback	このコールバックは、前編集文字列の内部でテキスト挿入ポイントを動かすために呼び出される。

入力スタイル XIMStatusCallbacksに対応しようとするクライアントは、ある決められた状態コールバック群を 入力メソッドに提供しなければならない。

XNStatusStartCallback	このコールバックは入力メソッドが状態領域を初期化したときに呼び出される。
XNStatusDoneCallback	このコールバックは入力メソッドが状態領域を必要としなくなった時に呼び出される。
XNStatusDrawCallback	このコールバックは状態領域の更新が必要なときに呼び出される。

状態と前編集関する引数の値は、 XIMCallback 型の構造体へのポインタでなければならない。

typedef void (*XIMProc)();
typedef struct {
	XPointer client_data;
	XIMProc callback;
} XIMCallback;

それぞれのコールバックはいくつか固有のセマンティクスを持ち、 クライアントに必要な環境を表すデータを特定のデータ構造に移す。 この段落は、コールバックの設定に使われる引数だけを説明している。

前編集を行っている時にこれらの値のいずれかを設定すると、予期しない結果 が起こることがある。

入力状態コールバックのセマンティクス

XIM コールバックはクライアントかテキスト描画パッケージが定義する手続き であり、選択されたイベントが発生したときに入力メソッドから呼び出される。 ほとんどのクライアントはテキスト編集パッケージかツールキットを使ってい るため、こういったコールバックを定義する必要はない。 この節では、コールバックが引き起こされた時のセマンティクスと引数の内容 についてのセマンティクスを定義する。 この情報が役立つのはほぼ X ツールキットを実装する場合くらいである。

コールバックはほとんど提供されているので、クライアント(またはテキスト 編集パッケージ)は自分のウィンドウの中に on-the-spot の前編集を実装でき る。 この場合、入力メソッドはクライアントと通信したり同期を取る必要がある。 前編集ウィンドウがクライアントの制御かにある時は、入力メソッドは前編集 ウィンドウ内の変化を伝える必要がある。 これらのコールバックを使うとクライアントは前編集領域の初期化、 新しい前編集文字列の表示、前編集の際のテキスト挿入位置の移動、 前編集の終了、状態領域の更新を行える。

コールバック手続きは以下の一般的なプロトタイプに従う:

void CallbackPrototype(ic, client_data, call_data)
XIC ic;
XPointer client_data;
SomeType call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

コールバックに固有のデータを指定する。

以下の段落では、別の理由に対応するプログラミングのセマンティクスおよび 固有のデータ構造を説明する。

ジオメトリコールバック

ジオメトリコールバックは、入力メソッドがクライアントとジオメトリの調整 をしたいときに入力メソッドが引き起こす。 一般的なプロトタイプは以下の通りである:

void GeometryCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われず、常に NULL が渡される。

破棄コールバック

破棄コールバックは、入力メソッドが何らかの理由でサービスを停止する時に 入力メソッドが引き起こす。 コールバックが呼び出された後は、入力メソッドは Xlib によって解放される。 コールバックの一般的なプロトタイプは以下の通りである:

void DestroyCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックは使われず、常に NULL が渡される。

文字列変換コールバック

文字列変換コールバックは、変換された文字列を返すようにクライアントに 要求するために入力メソッドによって引き起こされる。 返された文字列はマルチバイト文字列の場合もワイド文字文字列の場合もある。 この文字列は入力コンテクストに関連付けられたロケールに一致する エンコーディングがなされている。 コールバックのプロトタイプは以下の通りである:

void StringConversionCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XIMStringConversionCallbackStruct *call_data;

ic

入力文字列を指定する。

client_data

追加のクライアントデータを指定する。

call_data

変換される文字列の量を指定する。

XIMStringConversionCallbackStruct構造体の定義は以下の通りである:

typedef struct _XIMStringConversionCallbackStruct {
	XIMStringConversionPosition position;		
	XIMCaretDirection direction;
	short factor;
	XIMStringConversionOperation operation;
	XIMStringConversionText *text;
} XIMStringConversionCallbackStruct;
typedef short XIMStringConversionPosition;
typedef unsigned short XIMStringConversionOperation;

#define	XIMStringConversionSubstitution	(0x0001)
#define	XIMStringConversionRetrieval	(0x0002)

XIMStringConversionPositionは XIMStringConversionText構造体に返される文字列の開始位置を指定する。 この値はクライアントのバッファ内のクライアントのカーソル位置に対する 相対位置で位置を指定する。位置は文字単位で表される。

テキストバッファの終了位置は、direction メンバと factor メンバによって 決定される。特に、この位置は XIMCaretDirectionで定義された開始位置に対して相対的に表される文字の位置である。 XIMStringConversionCallbackStruct の factor メンバは適用される XIMCaretDirection 位置の数を指定する。例えば、direction が XIMLineEndを指定し、 XIMLineEndと factor が 1 であれば、現在の表示行の開始位置から終了位置までの全て の文字が返される。もし direction が XIMForwardCharや XIMBackwardCharを指定していれば、factor は開始位置からの相対位置を文字単位で示す。

XIMStringConversionOperationは、変換される文字列がクライアントのバッファから削除されるか(置き換え) コピーされるか(取得)を指定する。 XIMStringConversionOperationが XIMStringConversionSubstitutionならば、クライアントは変換される文字列を自身が持っているバッファから削 除しなければならない。 XIMStringConversionOperationが XIMStringConversionRetrievalならば、クライアントは変換される文字列を自身のバッファから削除してはな らない。 置き換え操作は普通は再変換と読みに基づく変換のために使われ、 取得操作は普通はコンテクスト依存の変換のために使われる。

前編集状態コールバック

入力メソッドが前編集をオンまたはオフにしたとき、 ツールキットに前編集領域の初期化や整理を行わせるために PreeditStartCallbackコールバックや PreeditDoneCallbackコールバックが引き起こされる。

int PreeditStartCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われず、必ず NULL が渡される。

void PreeditDoneCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コールバックを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われず、常に NULL を渡すこと。

PreeditStartCallbackは前編集情報の表示とさらなる PreeditDrawCallbackコールバックの処理に必要な適切なデータの初期化を行わなければならない。 一度 PreeditStartCallbackが呼ばれると、 PreeditDoneCallbackが呼び出されるまでは再びこのコールバックが呼ばれることはない。

前編集描画コールバック

このコールバックは、前編集領域内の前編集テキストの描画、挿入、削除、 置換のために引き起こされる。 前編集テキストには日本語の仮名のような変換されていない入力テキストや、 日本語の漢字のような変換済みのテキスト、あるいはその両方が含まれる。 この文字列はマルチバイト文字列かワイド文字文字列であり、その エンコーディングは入力コンテクストに関連付けられたロケールに一致する。 このコールバックのプロトタイプは以下の通りである:

void PreeditDrawCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XIMPreeditDrawCallbackStruct *call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

前編集の描画に関する情報を指定する。

XIMPreeditDrawCallbackStruct構造体は以下のように定義されている:

typedef struct _XIMPreeditDrawCallbackStruct {
	int caret;	/* 前編集文字列内でのカーソルのオフセット */
	int chg_first;	/* 変更の開始位置 */
	int chg_length;	/* 文字数で数えた変化した部分の長さ */
	XIMText *text;
} XIMPreeditDrawCallbackStruct;

クライアントは前編集テキストのバッファとそのバッファ内のインデックスを 参照しているコールバック引数をを更新し続けなければならない。 call_data フィールドは動作によって以下のような固有の意味を持つ:

• テキストの削除を示すには、call_data メンバでは text フィールドに NULL を指定する。 削除されるテキストは、バッファ内の現在のテキストの(0 から数えて) chg_first の位置から chg_length 文字である。
• text が NULL でない時は、バッファ内のテキストの挿入または置換を示す。 .IP chg_length メンバは、この呼び出しで影響を受ける現在の前編集バッファで の文字数を示す。 chg_length が正の場合は、chg_first から数えて chg_length 個の文字が 削除されるか text によって置き換えられることを示す。text の長さは XIMText構造体で指定される。 .IP chg_length 値が 0 の場合は text は chg_first が指す位置にちょうど挿入 されなければならない。 chg_first の値が 0 の場合はバッファ中の最初の文字が指定される。 .IP chg_length と chg_first を組み合わせて前編集バッファに必要な変更が示さ れる。chg_first から始まる chg_length 個の文字が XIMText構造体で与えられるテキストと置き換えられる。例えば、前編集バッファに "ABCDE" という文字列が含まれる場合を考える。 .IP

  .ft C テキスト: A B C D E ^ ^ ^ ^ ^ ^ 文字の位置: 0 1 2 3 4 5

  .ft P

  表の「文字の位置」は文字に対しての文字の位置を示す。 .IP chg_first の値が 1 であり、chg_length の値が 3 ならば、これは文字の位 置 1 から始まる 3 文字を XIMText構造体に含まれる文字列で置き換えるという意味になる。 つまり、「BCD」の部分が構造体に含まれる値で置き換えられる。 .IP chg_length と chg_first はどちらも符号付きの整数であるが、負の値を取る ことは決してない。
• caret メンバは、前編集バッファの変更が完了した後にカーソルが置かれてい る前の文字の位置を示す。 例えば、caret が 0 ならば、カーソルはバッファの先頭にある。caret が 1 ならば、カーソルは最初の文字と 2 番目の文字の間にある。

typedef struct _XIMText {
	unsigned short length;
	XIMFeedback * feedback;
	Bool encoding_is_wchar; 
	union {
		char * multi_byte;
		wchar_t * wide_char;
	} string; 
} XIMText;

渡されるテキスト文字列は実際には以下の内容を指定する構造体である:

• length メンバは文字単位でのテキストの長さである。
• encoding_is_wchar メンバは、テキスト文字列がワイド文字形式と マルチバイト形式のどちらでエンコードされているのかを示す値である。 テキスト文字列はマルチバイトで渡してもワイド文字で渡してもよい。 入力メソッドはどちらの形式のデータが渡されるかを制御する。 クライアントのコールバックルーチンは、どちらの形式で渡されたデータでも 処理できなければならない。
• string メンバはテキスト文字列である。
• feedback メンバは、string メンバの各文字についてのレンダリングの種類を 示す。 もし string が NULL ならば(既にある前編集バッファのハイライト表示部分 だけを更新すべきことを示す)、feedback は既存の前編集バッファに適用すべ きハイライト要素の長さを指す。長さは chg_first の位置から数える。

feedback メンバは、テキスト描画の時にコールバックが適用されるレンダリ ングによるフィードバックの種類を表す。 描画されるテキストのレンダリングは、汎用的な方法(例えばプライマリ、 セカンダリ)か特定の方法(反転や下線)で指定される。 汎用的な指定が与えられた時は、クライアントは自由にレンダリングのスタイ ルを選べる。 しかし、プライマリとセカンダリは 2 つの区別できるレンダリング形式に対 応付けることが必要である。

もし入力メソッドが前編集文字列の表示を制御したければ、入力メソッドは 特定の方法のフィードバックを用いて見え方のヒントを指示できる。 XIMVisibleToForward ,XIMVisibleToBackward ,XIMVisibleCenterマスクは見え方のヒントを示すために排他的に使われる。 XIMVisibleToForwardマスクは、前編集テキストが前編集領域内のキャレットの位置から主描画方向 に表示されることが望ましいことを示す。 XIMVisibleToBackwardマスクは、前編集テキストが前編集領域内のキャレットの位置から主描画方向 の逆向きに表示されることが望ましいことを示す。 XIMVisibleCenterマスクは、キャレットの位置が前編集領域の中央に来るように 前編集テキストが表示されるのが望ましいことを示す。

見え方のヒントを使った場合は、前編集文字列の挿入位置が可視領域の外にな ることもあり得る。 マスクのうちのひとつだけが全体の前編集文字列に対して正しい。また、指定 された入力コンテクストについて 1 文字だけがこれらのフィードバックのど れかひとつを同時に保持できる。 このフィードバックは、他のハイライト部分(例えば XIMReverse)との論理和を取ることができる。 有効なフィードバックは一番最後に設定したものだけであり、以前の フィードバックは全て自動的に無効にされる。これはクライアントに対するヒ ントであり、クライアントは前編集文字列の表示方法を自由に選べる。

feedback メンバは、text 引数のレンダリングをどのように実行すべきかも指 定する。 feedback が NULL ならば、コールバックは前編集領域の周りの文字に対して 使われたのと同じフィードバックを適用すべきである。chg_first が ハイライト部分の境界にあれば、クライアントは 2 つのハイライト領域のど ちらを使うかを選択できる。 feedback が NULL でなければ、feedback は文字列中のそれぞれの文字の レンダリング方法を定義する配列と、この配列の長さを指定する。

入力メソッドが前編集テキストの内容を変更することなく前編集テキストの フィードバックだけを更新したい場合には、 XIMText構造体の string フィールドは NULL となり、影響を受ける文字数(chg_fisrt からの数える)が length フィールドに格納され、feedback フィールドは XIMFeedbackの配列を指す。

feedback の配列は XIMFeedback型の値で表されるビットマスクである。 正しいマスク名は以下の通りである:

typedef unsigned long XIMFeedback;

#define	XIMReverse	1L
#define	XIMUnderline	(1L<<1)
#define	XIMHighlight	(1L<<2)
#define	XIMPrimary	(1L<<5)\(dg
#define	XIMSecondary	(1L<<6)\(dg
#define	XIMTertiary	(1L<<7)\(dg
#define	XIMVisibleToForward	(1L<<8)
#define	XIMVisibleToBackward	(1L<<9)
#define	XIMVisibleCenter	(1L<<10)

XIMReverseハイライトで描画される文字は、通常のハイライトされていない文字を表示す る際の前景色と背景色を入れ換えて描画しなければならない。 XIMUnderlineハイライトで描画される文字は下線付きにしなければならない。 XIMHighlight ,XIMPrimary ,XIMSecondary ,XIMTertiaryハイライトで描画される文字は、 XIMReverseや XIMUnderlineと異なる何らかのユニークな方法で描画しなければならない。 .FS \(dg XIMPrimary ,XIMSecondary ,XIMTertiaryの値は X11R5 の仕様では誤って定義されていた。 X コンソーシアムの X11R5 の実装ではこれらのハイライトに対する値は正し く実装されていた。 これらのハイライトの値に関する仕様は、X コンソーシアムの X11R5 と X11R6 の実装における値と一致するように訂正された。 .FE

前編集キャレットコールバック

入力メソッドは独自のナビゲーションキーを持ち、前編集領域のテキスト挿入 位置をユーザが動かすことを許してもよい(例えば前後への移動)。 したがって、入力メソッドはテキスト挿入位置を動かすことをクライアントに 示す必要がある。 この時に入力メソッドは PreeditCaretCallback を呼び出す。

void PreeditCaretCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XIMPreeditCaretCallbackStruct *call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

前編集キャレット情報を指定する。

The XIMPreeditCaretCallbackStruct構造体の定義は以下の通りである:

typedef struct _XIMPreeditCaretCallbackStruct {
	int position;	/* 前変数文字列におけるキャレットのオフセット */
	XIMCaretDirection direction;	/* キャレットが動く方向 */
	XIMCaretStyle style;	/* キャレットのフィードバック */
} XIMPreeditCaretCallbackStruct;

XIMCaretStyle構造体の定義は以下の通りである:

typedef enum {
	XIMIsInvisible,	/* キャレットのフィードバックを無効にする */ 
	XIMIsPrimary,	/* UI で定義されたキャレットのフィードバック */
	XIMIsSecondary,	/* UI で定義されたキャレットのフィードバック */
} XIMCaretStyle;

XIMCaretDirection構造体の定義は以下の通りである:

typedef enum {
	XIMForwardChar, XIMBackwardChar,
	XIMForwardWord, XIMBackwardWord,
	XIMCaretUp, XIMCaretDown,
	XIMNextLine, XIMPreviousLine,
	XIMLineStart, XIMLineEnd, 
	XIMAbsolutePosition,
	XIMDontChange,
 } XIMCaretDirection;

これらの値は以下のように定義されている:

XIMForwardChar	キャレットの位置を 1 文字分前に移動させる。
XIMBackwardChar	キャレットの位置を 1 文字分後ろに移動させる。
XIMForwardWord	キャレットを前に 1 単語分移動させる。
XIMBackwardWord	キャレットを後ろに 1 単語分移動させる。
XIMCaretUp	水平位置のオフセットを保ったまま、キャレットを 1 行上に移動させる。
XIMCaretDown	水平位置のオフセットを保ったまま、キャレットを 1 行下に移動させる。
XIMPreviousLine	キャレットを前の行の先頭に移動させる。
XIMNextLine	キャレットを次の行の先頭に移動させる。
XIMLineStart	キャレットを含む現在の表示行の先頭にキャレットを移動させる。
XIMLineEnd	キャレットを含む現在の表示行の最後にキャレットを移動させる。
XIMAbsolutePosition	キャレットはコールバックデータの position フィールドで指定された位置に移動しなければならない。位置は前編集テキストの先頭から数えて文字単位で示す。したがって、値が 0 の場合は前編集テキストの先頭に移動することになる。
XIMDontChange	キャレットの位置は変わらない。

状態コールバック

入力メソッドは、3 つの状態コールバックを使って入力コンテクストの状態の 変化(例えば生成、破棄、フォーカスの変化)を伝えることができる。3 つの 状態コールバックは StatusStartCallback, StatusDoneCallback, StatusDrawCallback である。

入力コンテクストが生成されるかフォーカスを得ると、入力メソッドは StatusStartCallback コールバックを呼び出す。

void StatusStartCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われない。常に NULL を渡す。

入力コンテクストが破棄されるかフォーカスを失うと、入力メソッドは StatusDoneCallback を呼び出す。

void StatusDoneCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XPointer call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

このコールバックでは使われない。常に NULL を渡す。

入力コンテクストを更新しなければならないとき、入力メソッドは StatusDrawCallback を呼び出す。

void StatusDrawCallback(ic, client_data, call_data)
XIC ic;
XPointer client_data;
XIMStatusDrawCallbackStruct *call_data;

ic

入力コンテクストを指定する。

client_data

追加のクライアントデータを指定する。

call_data

状態の描画に関する情報を指定する。

XIMStatusDataType構造体と XIMStatusDrawCallbackStruct構造体の定義は以下の通りである:

typedef enum {
	XIMTextType,
	XIMBitmapType,
} XIMStatusDataType;
typedef struct _XIMStatusDrawCallbackStruct {
	XIMStatusDataType type;
	union {
		XIMText *text;
		Pixmap  bitmap;
	} data;
} XIMStatusDrawCallbackStruct;

フィードバックのスタイル XIMVisibleToForward ,XIMVisibleToBackward ,XIMVisibleToCenterは関係がないので、 XIMText構造体の XIMFeedback要素には表れない。

イベントのフィルタリング

Xlib には、入力メソッドが Xlib の内部にフィルタを登録できる機能が用意 されている。 このフィルタはクライアント(またはツールキット)が XNextEventを呼んだ後に XFilterEventを呼ぶことによって呼び出される。 XIMインタフェースを用いる全てのクライアントは、入力メソッドがクライアント の配送機構を知らなくてもイベントを処理できるようにするために XFilterEventを呼び出さなければならない。 クライアントのユーザインタフェースのポリシーは、 他のイベント処理機構(例えばモーダルグラブ等)に対するイベントフィルタの 優先度を決めることができる。

クライアントは存在するフィルタの数を知らないかもしれないし、もし フィルタがあってもフィルタがどのように動作するのかを知らないかもしれな い。 クライアントが知っているのは、イベントが XFilterEventが返す値としてフィルタリングされていることだけかもしれない。 クライアントはフィルタリングされたイベントを破棄するべきである。

イベントをフィルタリングするには XFilterEventを用いる。

Bool XFilterEvent(event, w)
XEvent *event;
Window w;

event

フィルタリングするイベントを指定する。

w

フィルタが適用されるウィンドウを指定する。

XFilterEventが Trueを返した場合、入力メソッドによっては既にイベントをフィルタリングしてい るので、クライアントはこのイベントを破棄すべきである。 XFilterEventが Falseを返した場合は、クライアントはイベントの処理を続けるべきである。

クライアント内でグラブが起こり、 XFilterEventが Trueを返した場合は、クライアントはキーボードのグラブを解除すべきである。

キーボード入力の取得

構成された入力を入力メソッドから得るには、 XmbLookupStringか XwcLookupStringを用いる。

int XmbLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)
XIC ic;
XKeyPressedEvent *event;
char *buffer_return;
int bytes_buffer;
KeySym *keysym_return;
Status *status_return;

int XwcLookupString(ic, event, buffer_return, bytes_buffer, keysym_return, status_return)
XIC ic;
XKeyPressedEvent *event;
wchar_t *buffer_return;
int wchars_buffer;
KeySym *keysym_return;
Status *status_return;

ic

入力コンテクストを指定する。

event

使用するキーイベントを指定する。

buffer_return

入力メソッドからマルチバイト文字列かワイド文字文字列が(もしあれば)返さ れる。

bytes_buffer

wchars_buffer

返却バッファ内で使用できる容量を指定する。

keysym_return

この引数が NULL でなければ、イベントから計算した KeySym が返される。

status_return

どんな種類のデータが返されたのかを示す値が返される。

keysym_return が NULL でなく、かつ引数 status_return が KeySym が返さ れたことを示している場合は、イベントから得た KeyCode がマップされた KeySym が引数 keysym_return が指す領域に返される。 文字列と KeySym の両方が返されても、KeySym 値は必ずしも返された文字列 に対応しない。

XmbLookupStringは文字列の長さをバイト単位で返し、 XwcLookupStringは文字列の長さを文字単位で返す。 XmbLookupStringと XwcLookupStringはどちらも、指定された入力コンテクストの入力メソッドに関連付けられた ロケールのエンコーディングでテキストを返す。

XmbLookupStringと XwcLookupStringが返すそれぞれの文字列は、そのロケールのエンコーディングの初期状態で始 まる(そのロケールのエンコーディングが状態依存の場合)。

: 正しい入力処理を保証するためには、 クライアントが KeyPressイベントだけを XmbLookupStringや XwcLookupStringに送ることが重要である。 クライアントがこれらの関数に KeyReleaseイベントを渡した時の動作は未定義である。

クライアントは返された他の値を使う前に引数 status_return をチェックす べきである。 これらの 2 つの関数はどちらも、他の引数に何が返されたのかを示す値を status_return に返す。 返される可能性がある値は以下の通りである:

XBufferOverflow	返された入力文字列が長すぎて与えられた buffer_return に入らない。必要なサイズ(XmbLookupStringの場合はバイト単位、XwcLookupStringの場合は文字単位)が関数の値として返され、buffer_return と keysym_return の内容は変化しない。クライアントは同じイベントと文字列を取得するために十分な大きさのバッファを指定してこの関数を再度呼び出さなければならない。
XLookupNone	今のところきちんとした入力が構成されていない。buffer_return と keysym_return の内容は変更されず、関数は 0 を返す。
XLookupChars	何らかの文字が構成されている。この文字列は引数 buffer_return に格納され、文字列の長さが関数の値として返される。この文字列は入力コンテクストに関連付けられたロケールでエンコードされている。引数 keysym_return の内容は変更されない。
XLookupKeySym	文字列ではなく KeySym が返されている。この KeyshSym は keysym_return に返される。引数 buffer_return の内容は変更されず、関数は 0 を返す。
XLookupBoth	KeySym と文字列の両方が返された。XLookupCharsとXLookupKeySymが同時に起こる。

引数として XmbLookupStringや XwcLookupStringに渡した入力コンテクストが現在フォーカスを持っていても持っていなくても 違いはない。 入力は入力コンテクストがフォーカスを失う前に入力コンテクスト内に作られ ていることがあり、入力コンテクストがもうキーボードフォーカスを失ってい ても、その入力は後で XmbLookupStringや XwcLookupStringを呼び出した時に返されることがある。

入力メソッドの規約

入力メソッドのアーキテクチャはクライアントに対して透過的である。 しかし、クライアントを正しく動作させるためにはたくさんの規約を守るべき である。 クライアントはまた、入力サーバがリモートにある場合にの入力メソッドとラ イブラリの間の同期による影響にも注意しなければならない。

クライアントの規約

うまく動作するクライアント(またはツールキット)はまず入力メソッドのスタ イルの問い合わせを行うべきである。 対応しているスタイル(ジオメトリ管理やコールバックについて)に関する要求 をクライアントが満たせない場合は、クライアントはプログラムの実行の継続 についてユーザに問い合わせるか、何らかの例外やエラーを起こすべきである。

同期に関する規約

KeyCode が 0 である KeyPressイベントは、 XmbLookupStringや XwcLookupStringで返せる入力を入力メソッドが構成したことの信号として排他的に使われる。 これ以外には KeyCode を 0 とした KeyPressイベントを使うことはない。

このようなイベントはフロントエンドの入力メソッドでもバックエンドの 入力メソッドでも実装依存の方法で生成できる。 このイベントを生成する方法には以下の内容を含むものがある:

• 入力メソッドサーバから送られた人工的なイベント
• 入力メソッドのフィルタが生成し、クライアントのイベントキューに入れられ た人工的なイベント
• KeyCode 値が入力メソッドのフィルタに変更されている KeyPressイベント

クライアントがコールバック対応を指定している場合は、入力メソッドが明示 的にコールバックを行って応答が得られなかった場合(コールバックが指定さ れていないか、不正なデータが返された)を除いて入力メソッドは動作を起こ さない。

文字列に関する規約

文字列定数に対する以下のシンボルは <X11/Xlib.h >で定義されている。 これらのシンボルは特定のマクロ定義とともに示されているが、これらは マクロとして実装されることもあるし、グローバルなシンボルや両者を混ぜて 実装されることもある。文字列へのポインタ値そのものは重要ではない。 クライアントは、2 つの値の違っても、そのことが実際の文字列が違うことを 意味するとみなしてはならない。

#define	XNVaNestedList	"XNVaNestedList"
#define	XNSeparatorofNestedList	"separatorofNestedList"
#define	XNQueryInputStyle	"queryInputStyle"
#define	XNClientWindow	"clientWindow"
#define	XNInputStyle	"inputStyle"
#define	XNFocusWindow	"focusWindow"
#define	XNResourceName	"resourceName"
#define	XNResourceClass	"resourceClass"
#define	XNGeometryCallback	"geometryCallback"
#define	XNDestroyCallback	"destroyCallback"
#define	XNFilterEvents	"filterEvents"
#define	XNPreeditStartCallback	"preeditStartCallback"
#define	XNPreeditDoneCallback	"preeditDoneCallback"
#define	XNPreeditDrawCallback	"preeditDrawCallback"
#define	XNPreeditCaretCallback	"preeditCaretCallback"
#define	XNPreeditStateNotifyCallback	"preeditStateNotifyCallback"
#define	XNPreeditAttributes	"preeditAttributes"

#define	XNStatusStartCallback	"statusStartCallback"
#define	XNStatusDoneCallback	"statusDoneCallback"
#define	XNStatusDrawCallback	"statusDrawCallback"
#define	XNStatusAttributes	"statusAttributes"
#define	XNArea	"area"
#define	XNAreaNeeded	"areaNeeded"
#define	XNSpotLocation	"spotLocation"
#define	XNColormap	"colorMap"
#define	XNStdColormap	"stdColorMap"
#define	XNForeground	"foreground"
#define	XNBackground	"background"
#define	XNBackgroundPixmap	"backgroundPixmap"
#define	XNFontSet	"fontSet"
#define	XNLineSpace	"lineSpace"
#define	XNCursor	"cursor"

#define	XNQueryIMValuesList	"queryIMValuesList"
#define	XNQueryICValuesList	"queryICValuesList"
#define	XNStringConversionCallback	"stringConversionCallback"
#define	XNStringConversion	"stringConversion"
#define	XNResetState	"resetState"
#define	XNHotKey	"hotkey"
#define	XNHotKeyState	"hotkeyState"
#define	XNPreeditState	"preeditState"
#define	XNVisiblePosition	"visiblePosition"
#define	XNR6PreeditCallbackBehavior	"r6PreeditCallback"

#define	XNRequiredCharSet	"requiredCharSet"
#define	XNQueryOrientation	"queryOrientation"
#define	XNDirectionalDependentDrawing	"directionalDependentDrawing"
#define	XNContextualDrawing	"contextualDrawing"
#define	XNBaseFontName	"baseFontName"
#define	XNMissingCharSet	"missingCharSet"
#define	XNDefaultString	"defaultString"
#define	XNOrientation	"orientation"
#define	XNFontInfo	"fontInfo"
#define	XNOMAutomatic	"omAutomatic"