Provided by: libcanna1g-dev_3.7p3-14_amd64 
名前
UILib intro - ユーザインタフェースライブラリイントロ
説明
ユーザインタフェースライブラリは，１文字の入力，１キーの入力に対応して， 未確定文字列，確
定文字列，注目文節位置，ステータス表示のための文字列， 候補一覧のための文字列などを返還す
るライブラリです．アプリケーションプ ログラムは，返還された情報によって表示を行います．ア
プリケーションプロ グラムは，キー入力以外のトリガーによって(例えばマウスによる選択な
ど)モー ドの遷移を制御することもできます．
ユーザインタフェースライブラリでは，TTYベース でjrKanjiStringおよびjrKanjiControl，Ｘウィ
ンドウベースで XLookupKanjiStringおよびXKanjiControlを提供します．
ユーザインタフェースライブラリを使用する場合には以下のファイルが必要に なります．
・ TTYベース
関数 jrKanjiString, jrKanjiControl
ヘッダファイル canna/jrkanji.h
ライブラリ libcanna.a, libcanna.so
・ Xウィンドウベース
関数 XLookupKanjiString, XKanjiControl
ヘッダファイル canna/kanji.h
ライブラリ libXn.a, libXn.so, libcanna.a, libcanna.so
概要
jrKanjiString TTYからの入力，Ｘでの入力，基本ウィンドウでの入力など一般的なキーボー
ド入力に対して漢字文字列への変換を行います．
jrKanjiControl jrKanjiStringでの制御を指定されたパラメタにより行います．
XLookupKanjiString Ｘウィンドウシステムにおいて，キーボード入力(キーイベント)の漢字文字列
への変換を行います．
XKanjiControl XLookupKanjiStringでの制御を指定されたパラメタにより行います．
名前
jrKanjiString - 一般的名キーボード入力に対してのかな漢字変換
形式
#include <canna/jrkanji.h>
int jrKanjiString(context_id, ch, buffer_return, bytes_buffer, kanji_status_return)
int context_id;
int ch;
char *buffer_return;
int bytes_buffer;
jrKanjiStatus *kanji_status_return;
説明
jrKanjiStringはTTYからの入力，Ｘでの入力，基本ウィンドウでの入力など， 一般的なキーボード
入力に対して漢字文字列への変換を行う関数です．
jrKanjiStringは，アスキーコードで表されるキー入力を日本語文字列に対応 させる簡易ルーチン
で，入力されたキーを表すコードをchにて与えるこ とにより，表示すべき文字列を返しま
す．jrKanjiStringの内部においてロー マ字かな変換，かな漢字変換が行われます．
ファンクションキーや，カーソルキーなどのキーについては，それらのキーの 発生するエスケープ
シーケンスの 代わりにファンクションキーの項で示す特別の コードをjrKanjiStringに与えて下さ
い．
context_idで与えるコンテクスト識別子は，実際にはそのままの値が用 いられるわけではな
く，context_idで与えられるコンテクスト識別子を キーとしたコンテクストが作成され，用いられ
ることになります．したがって アプリケーションプログラマはjrKanjiStringに与えるコンテクスト
識別子に ついては，適当な値を与えれば良く，入力ポートのファイルディスクリプタを 与えるのが
適当と考えられます．ただし，0を与えた時は特別で，システムに デフォルトで準備されているコン
テクストが用いられます．コンテクストに特 別の配慮を行わない場合には0を指定するのが適当で
す．
入力に対応して，ローマ字かな変換，かな漢字変換の中間結果を表示する必要 がありますが，表示
すべき中間結果はkanji_status_returnを介して， アプリケーションに返されます．
アプリケーションはkanji_status_returnに返される情報にしたがって 中間結果を表示しなければな
りま せん．kanji_status_returnはjrKanjiStatus型の構造体です．
jrKanjiStatus構造体は以下のように定義されます．
typedef struct {
unsigned char *echoStr; /* ローカルエコーのための文字列 */
int length; /* ローカルエコー文字列の長さ */
int revPos; /* ローカルエコー文字列のうち反転表示部分へのオフセット */
int revLen; /* ローカルエコー文字列のうち反転表示部分の長さ */
unsigned long info; /* その他の情報 */
unsigned char *mode; /* モード情報 */
struct {
unsigned char *line; /* 候補一覧の文字列 */
int length; /* 候補一覧文字列の長さ */
int revPos; /* 候補一覧文字列のうち反転表示部分へのオフセット */
int revLen; /* 候補一覧文字列のうち反転表示部分の長さ */
} gline; /* 候補一覧に関する情報 */
} jrKanjiStatus;
かな漢字変換を用いた日本語入力時には変換の対象となる読みなどをローカル エコーする必要があ
ります．jrKanjiStringはローカルエコーなど表示に関す ることは何も行わず，代わりにローカルエ
コーするべき 文字列をjrKanjiStatus構造体を用いてアプリケーション側に返します．
変換が確定するまでは，ローマ字かな変換されている文字や，変換候補文字な ど，ローカルエコー
すべき(EUC)文字列がechoStrメンバにより返されま す．このとき，ローカルエコー文字列の長
さ，リバース表示の 開始位置と長さ(バイト単位)が， それぞれ，lengthメンバ，revPos，revLenメ
ンバにて返されます．ロー カルエコーすべき文字列のためのバッファはjrKanjiStringによって自動
的に 確保されますが，その領域は読みとりのみに用いられるべきであり，その領域 に文字列を書き
込んではいけません．
ローカルエコーすべき文字列がない場合はlengthメンバに０が返ります．
ローカルエコーすべき内容が前回のjrKanjiStringの呼出しの時と変わらない 場合(例えばコント
ロール文字が押され，そのキーが無効であった 場合など)はlengthメンバに-1が返ります．
モードの変更や，候補一覧に関する情報の有無は，infoメンバによって 渡されます．infoメンバ
のKanjiModeInfoビットがonで あれば，modeに新しいモードを示す文字列が返されます．infoメ ン
バのKanjiGLineInfoビットがonであれば，gline構造体に候補一覧等 の情報が格納されています．
gline構造体のlineメンバには候補一覧表示のための文字列が返 されます．gline構造体
のline,revPos,revLenの各メンバは，候 補一覧文字列のそれぞれ，長さ，リバース表示の開始位
置，リバース表示の長 さが返されます．
変換中に確定した(EUC)文字列がある場合は， その文字列がbuffer_returnで指定したバッファに格
納され，その文字 列の長さ(バイト単位)が返されます．確定した文字列が無い場合は戻り 値は0に
なります．確定文字列を格納するバッファbuffer_returnの大き さをbytes_bufferにて与えます．
確定文字列の長さがbytes_bufferよりも長い場合には， 確定文字列のうち，bytes_buffer分 だけ
がbuffer_returnに格納され，jrKanjiStringの戻り値と して，bytes_bufferで与えた値が返りま
す．
ファンクションキー
エスケープシーケンスを発行するようなファンクションキーに関しては，ファ ンクションキーによ
るエスケープシーケンスの変わりに以下のマクロ名で示さ れるコードをchとして与えて下さい．
論理名 コード
Nfer CANNA_KEY_Nfer
Xfer CANNA_KEY_Xfer
Up CANNA_KEY_Up
Left CANNA_KEY_Left
Right CANNA_KEY_Right
Down CANNA_KEY_Down
Insert CANNA_KEY_Insert
Rollup CANNA_KEY_Rollup
Rolldown CANNA_KEY_Rolldown
Home CANNA_KEY_Home
Help CANNA_KEY_Help
S-Nfer CANNA_KEY_Shift_Nfer
S-Xfer CANNA_KEY_Shift_Xfer
S-Up CANNA_KEY_Shift_Up
S-Left CANNA_KEY_Shift_Left
S-Right CANNA_KEY_Shift_Right
S-Down CANNA_KEY_Shift_Down
C-Nfer CANNA_KEY_Control_Nfer
C-Xfer CANNA_KEY_Control_Xfer
C-Up CANNA_KEY_Control_Up
C-Left CANNA_KEY_Control_Left
C-Right CANNA_KEY_Control_Right
C-Down CANNA_KEY_Control_Down
F1 CANNA_KEY_F1
PF1 CANNA_KEY_PF1
関連情報
jrKanjiControl(3)
戻り値
入力処理中何らかのエラーが発生した場合は，この関数の戻り値として-1が返 され，外部変数(char
*)jrKanjiErrorに，エラーメッセージが格納されます．
この関数の呼出しにより確定した文字列がある場合は確定した文字列のバイト 長が返ります．
それ以外の場合は0が返ります．
名前
jrKanjiControl - jrKanjiStringでのモードや，処理の制御を行う
形式
#include <canna/jrkanji.h>
int jrKanjiControl(context_id, request, arg)
int context_id;
int request;
char *arg;
説明
jrKanjiControlはcontext_idで示される変換コンテクストに 関して，requestで示される処理を行い
ます．処理によっては，引数を 伴う場合があり，その場合，引数はargにて与えます．
jrKanjiControlで制御される機能としては以下の５つがあります．
request名 機能
KC_INITIALIZE かな漢字変換を初期化する．
KC_CHANGEMODE 入力モードを変更する．
KC_SETWIDTH 候補一覧表示の時の幅を指定する．
KC_FINALIZE かな漢字変換の終了処理．
KC_SETUNDEFKEYFUNCTION
未定義キーに対する機能の設定を行う．
KC_SETMODEINFOSTYLE
モード情報を数値で表現するかどうかを指定する．
KC_KAKUTEI 入力中の文字列を確定する．
KC_KILL 入力中の文字列を削除する．
KC_QUERYMODE 現在のモードを問い合わせる．
KC_SETSERVERNAME 接続するサーバを指定する．
KC_SETINITFILENAME
カスタマイズファイルを指定する．
KC_CLOSEUICONTEXT コンテクストをクローズする．
KC_QUERYMAXMODESTR
モード表示文字列の最大長を求める．
jrKanjiControlの作用は基本的にはコンテクストで指定されたものに対しての み作用します．ただ
し，初期化の処理や終了の処理に関してはその限りではあ りません．
jrKanjiControlの操作によって未確定文字列の状態が変化したり，モードの状 態が変わることがあ
ります．そのような可能性がある場合はarg部分に変化し た情報を格納できるような構造体へのポイ
ンタを渡します．その構造体の定義 は以下のようになります．
typedef struct {
int val; /* バッファに格納された文字列の長さが返る */
unsigned char *buffer; /* 確定文字列を格納するためのバッファを与える */
int bytes_buffer; /* 上記のバッファの大きさを与える */
jrKanjiStatus *ks; /* 未確定文字列の情報を格納する構造体へのポインタ */
} jrKanjiStatusWithValue;
jrKanjiControlのそれぞれの機能の実行のしかたは以下の通りです．
(1) KC_INITIALIZE - かな漢字変換の初期化
KC_INITIALIZEをrequest部で指定することにより，かな漢字変換の初期 化を行います．argに
はwarningメッセージを 格納するための(char **)型の変数へのポインタまたはNULLを指定し
ます．初 期化の処理は基本的にはjrKanjiString(3)が最初に呼ばれた時に自動的に行わ れま
すが，jrKanjiControlを用いて初期化する ことにより，jrKanjiString(3)での初期化処理は
行われなくなります．
jrKanjiString(3)の使用に先立ってjrKanjiControlを用いてかな漢字変換に関 する制御を行
う時などは，漢字変換の初期化を行う必要があります．
正常終了時にはjrKanjiControlの戻り値として0が返り，異常終了時には-1が 返ります．
KC_INITIALIZEを行った場合，エラーとまではいかなくとも何らかのwarningが 発生すること
があります．warningが発生した場合はargにて与えられた 変数に対してwarning文字列の配列
へのポインタが格納され 返されます．warningがないときはNULLが格納され返されます．
(例)
int res; /* エラーが返ってくる場合に備える */
char **warning;
.....
res = jrKanjiControl(0, KC_INITIALIZE, &warning);
if (warning) {
char **p;
for (p = warning ; *p ; p++) {
fprintf(stderr, "%s0, *p);
}
}
第３引数に返されるwarningメッセージはライブラリの内部でmallocされます． これは，次
にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます．アプ リケーションプログラマ
が勝手にfreeしてはいけません．warningは今のとこ ろ最大64メッセージに限定されます．そ
れ以上のメッセージは切捨てられます．
メッセージに含まれる可能性のあるwarningには以下のものがあります．
・ カスタマイズファイルがシステムのものも含めてすべて利用できない．
・ カスタマイズファイルにシンタックスエラーがある．
・ ローマ字かな変換辞書が利用できない．
・ かな漢字変換辞書が利用できない．
・ かな漢字変換サーバに接続できない．
第３引数としてNULLを指定した場合warningメッセージは捨てられます．
(2) KC_CHANGEMODE - 入力モードの変更
入力モードをアプリケーションから変更します．requestの 部分にはKC_CHANGEMODEを指定
し，argにjrKanjiStatusWithValue構造体 を指定して下さい．jrKanjiStatusWithValue構造体
のvalメンバにてモー ド番号を指定することにより日本語モードが切り替わります．モード番
号は以 下のマクロで示されます．
マクロ番号 モード
CANNA_MODE_AlphaMode アルファベットモード
CANNA_MODE_HenkanMode 変換入力モード
CANNA_MODE_KigoMode 記号入力モード
CANNA_MODE_ZenHiraKakuteiMode
全角ひらがな確定入力モード
CANNA_MODE_ZenKataKakuteiMode
全角カタカナ確定入力モード
CANNA_MODE_HanKataKakuteiMode
半角カタカナ確定入力モード
CANNA_MODE_ZenAlphaKakuteiMode
全角アルファベット確定入力モード
CANNA_MODE_HanAlphaKakuteiMode
半角アルファベット確定入力モード
CANNA_MODE_HexMode 16進コード入力モード
CANNA_MODE_BushuMode 部首入力モード
CANNA_MODE_TorokuMode 単語登録モード
この機能によりモードを変更するとモード名を始めとして多くの表示が変化を 受けます．表
示の変更はargとして指定したjrKanjiStatusWithValue構造体に て返されます．
(例)
jrKanjiStatus ks;
jrKanjiStatusWithValue ksv;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
ksv.val = CANNA_MODE_HexMode;
jrKanjiControl(context, KC_CHANGEMODE, &ksv);
len = ksv.val;
.....
/* 未確定文字列や確定文字列の情報がksvにより返されます． */
(3) KC_SETWIDTH - 候補一覧表示のための幅を指定
候補一覧のために用いられる領域のコラム数を指定します．１コラムの幅はア ルファベット
文字あるいは半角カタカナ１文字の文字幅であり，全角漢字は２ コラム占めることになりま
す．候補一覧表示のための幅を 指定するためにrequest部分に指定する値はKC_SETWIDTHで，
このときargにコラム数を指定します．
(例)
jrKanjiControl(0, KC_SETWIDTH, (char *)60);
(4) KC_FINALIZE - かな漢字変換の終了処理．
プログラムを終了するなどの局面でかな漢字変換も終了することを指定します． かな漢字変
換処理を終了させる時は必ずこの処理を行って下さい．終わるにあ たって今まで学習した内
容がファイルに登録されます．request部分に はKC_FINALIZEを指定します．
正常終了時に0，異常終了時に-1が戻り値として返ります．
KC_FINALIZEを行った場合，エラーとまでいかなくとも何らかのwarningが発生 することがあ
ります．warningが発生した場合はargにて与えられた 変数にwarning文字列の配列へのポイン
タが格納され返されます．warningがな い場合にはNULLポインタが格納され返されます．
(例)
int res; /* エラーが返る場合に備える */
char **warning;
.....
res = jrKanjiControl(0, KC_FINALIZE, &warning);
if (warning) {
char **p;
for (p = warning ; *p ; p++) {
fprintf(stderr, "%s0, *p);
}
}
第３引数に返されるwarningメッセージは，ライブラリの内部でmallocされま す．これは，次
にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます． アプリケーションプログラマ
が勝手にfreeしてはいけません．
warningは今のところ最大64メッセージに限定されます．それ以上のメッセー ジは切捨てられ
ます．
メッセージに含まれる可能性のあるwarningには次のものがあります．
・ 辞書がアンマウントできない．
第３引数としてNULLを指定した場合，warningメッセージは捨てられます．
(5) KC_SETUNDEFKEYFUNCTION - 未定義キーに対する機能の設定
読みを入力している状態でC-tを打ったときのように未定義キーを入力した時 に取られる処理
を指定します．未定義キーに対応して行われる処理としては以 下の処理があります．
マクロ名 処理
kc_normal ビープ
kc_through アプリケーションプログラムに渡す
kc_kakutei 確定しアプリケーションプログラムに渡す
kc_kill 消去しアプリケーションプログラムに渡す
kc_normalを指定した場合，外部変数jrBeepFuncに設定された関数が未定義キー 入力時にライ
ブラリによって自動的に呼び出されます．jrBeepFuncに値を設定 しない場合には(jrBeepFunc
== NULLの場合には)何も起こりません．
(例)
extern (*jrBeepFunc)(), beep();
jrBeepFunc = beep;
jrKanjiControl(0, KC_SETUNDEFKEYFUNCTION, kc_normal);
(6) KC_SETMODEINFOSTYLE - モード情報の表現
モード情報を文字列ではなくビットマップなどのデータで表示したい場合があ ります．その
ような場合にはモード情報として数値データが返ってくると処理 がしやすくなりま
す．jrKanjiControlでKC_SETMODEINFOSTYLEを 指定し，argに１を渡すことによってそれ以後
はjrKanjiStatus構造体 のmodeメンバにはモードを表す数値に'@'(0x40)を加えた１文字が返
さ れるようになります．モードを表す数値に変換する場合には返ってきた文字列 か
ら'@'(0x40)を引きます．モードを表す数値については入力モードの 変
更((2)KC_CHANGEMODE)のこうを参照して下さい．
(7) KC_KAKUTEI，(8) KC_KILL - 入力中の文字列の放棄
入力中の文字列を何らかの都合で放棄したい場合があります．放棄する場合に 入力中の文字
列を確定文字列として取り込んでから放棄したい場合と全く捨て てしまってから放棄したい
場合があります．確定する 場合にはjrKanjiControlにてKC_KAKUTEIを指定し，放棄する 場合
にはKC_KILLを指定します．
この処理は表示に影響を与えるので第３引数にはjrKanjiStatusWithValue構造 体を指定しな
ければなりません．
(例)
jrKanjiStatusWithValue ksv;
jrKanjiStatus ks;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
jrKanjiControl(context, KC_KAKUTEI, &ksv);
len = ksv.val;
.....
(9) KC_QUERYMODE - モードの問い合わせ
現在のモードを問い合わせるにはjrKanjiControlでKC_QUERYMODEを指定します．
第３引数にはモード文字列を格納するための文字配列のポインタを指定します． モード文字
列はヌル文字で終わる文字列です．ここに数値が返るようにするに
はjrKanjiControlでKC_SETMODEINFOSTYLEを指定してモード文字列のスタイル を変更しておき
ます．
(例)
char currentMode[MAXMODELEN];
.....
jrKanjiControl(0, KC_QUERYMODE, currentMode);
.....
(10) KC_SETSERVERNAME - サーバの指定
かな漢字変換サーバとしてどのサーバを使うかをアプリケーションプログラム を終了するこ
となしに切替えることが可能です．かな漢字変換サーバとして接 続するべきサーバを指定す
るにはjrKanjiControlでKC_SETSERVERNAMEを指定し ます．第３引数には接続したいサーバ名
を指定します．
(11) KC_SETINITFILENAME - カスタマイズファイルの指定
カスタマイズファイルをアプリケーションプログラム側から変更することがで きます．カス
タマイズファイルの変更はjrKanjiControlの 第２引数にKC_SETINITFILENAMEを指定
し，第３引数にファイル名文字列を指定 することにより行います．この処理を行う場合
はKC_INITIALIZEに先立って実 行しておかなければなりません．
(例)
char *inifile = "app-own.canna"
.....
jrKanjiControl(0, KC_SETINITFILENAME, initfile);
.....
(12) KC_CLOSEUICONTEXT - コンテクストのクローズ
変換コンテクストを表すコンテクストIDは任意の整数を割り当てることができ ます．今まで
使われていない コンテクストIDをjrKanjiStringあるいはjrKanjiControlに与えることが可能
であり，その場合，そのコンテクスト用のイニシャライズが行われ必要なメ モリが確保され
ます．
それまで使用していた入力ポートが使われなくなった場合に，そのポートに割 り当てて使っ
ていたコンテクストID用に確保されたメモリを 開放するにはjrKanjiControlを第２引数
にKC_CLOSEUICONTEXTを指定して呼び 出します．
この処理は表示の変化をともなうので第３引数にはjrKanjiStatusWithValue構 造体を与えま
す．
(例)
jrKanjiStatusWithValue ksv;
jrKanjiStatus ks;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
jrKanjiControl(0, KC_CLOSEUICONTEXT, &ksv);
.....
(13) KC_QUERYMAXMODESTR - モード表示文字列の最大長を求める．
初期化ファイルにてモード表示文字列がカスタマイズできますが，カスタマイ ズされた結果
モード表示文字列にどれだけの表示領域を確保するかを調べる必 要がある場合がありま
す．jrKanjiControlを第２引数にKC_QUERYMAXMODESTRを 指定して呼び出すことにより，モー
ド表示文字列として何コラム必要かが返り 値として返されます．ここで言うコラムとは半角
英数文字の文字幅を１とした ときの値を示します．
第３引数は用いられないのでダミー値として0を与えます．
(例)
int max_mode_columns;
.....
max_mode_columns = jrKanjiControl(0, KC_QUERYMAXMODESTR, 0);
.....
名称
XLookupKanjiString - キーボード入力の漢字文字列への変換
記述形式
#include <X11/Xlib.h>
#include <X11/kanji.h>
int
XLookupKanjiString(event_struct, buffer_return, bytes_buffer,
keysym_return, status_return, kanji_status_return)
XKeyEvent *event_struct;
char *buffer_return;
int bytes_buffer;
KeySym *keysym_return;
XComposeStatus *status_return;
XKanjiStatus *kanji_status_return;
引数
event_struct キーイベントを指定します。
buffer_return 変換した漢字文字列が返されます。
bytes_buffer バッファの長さを指定します。
keysym_return キーシンボルを返します。NULLを指定することもできます。
status_return XCompose構造体へのポインタを指定します。
kanji_status_return
かな漢字変換の様子が返されます。
説明
XLookupKanjiStringは、キーイベントを日本語文字列に 対応させる簡易ルーチンで、 キーイベント
の修飾キービットを使用してシフト、ロック、 コントロール等の処理を行います。
XLookupKanjiStringによって8bitアルファベット文字 及び16bit日本語文字を取り扱うことができま
す。
アルファベット文字の取り扱いについては、 XLookupKanjiStringはXLookupStringと同様の動作にな
ります。
日本語文字の取り扱いについては、 この関数の内部においてローマ字かな変換、 かな漢字変換が行
われます。 日本語の入力時にXKanjiStatus構造体が用いられます。XKanjiStatus構造体は 以下のよ
うに定義されます。
typedef struct _XKanjiStatus {
unsigned char *echoStr; /* local echo string */
int length; /* length of echo string */
int revPos; /* reverse position */
int revLen; /* reverse length */
unsigned long info; /* other information */ │
unsigned char *mode; /* mode information */ │
struct { │
unsigned char *line; /* a grance of Kanji characters */ │
int length; /* length of it */ │
int revPos; /* reverse position of it */ │
int revLen; /* reverse length of it */ │
} gline; /* a grancing line information */ │
} XKanjiStatus;
#define KanjiModeInfo 01 │
#define KanjiGLineInfo 02 │
かな漢字変換を用いた日本語入力時には変換の対象となる読みなどを ローカルエコーする必要があ
ります。XLookupKanjiStringはローカル エコーなど表示に関することは何も行わず、代わりにロー
カルエコー するべき文字列をXKanjiStatus構造体を用いて アプリケーション側に返します。
変換が確定するまでは、ローマ字かな変換されている文字や、 変換候補文字など、ローカルエコー
すべき(EUC) 文字列がechoStrメンバに より返されます。このとき、ローカルエコー文字列の 長
さ、リバース表示の開始位置と長さ（バイト単位）が、 それぞれ、lengthメン
バ、revPos、revLenメンバにて 返されます。 ローカルエコーすべき文字列のためのバッファ
はXLookupKanjiStringに よって自動的に確保されますが、その領域は読み取りのみに用いられるべ
きであり、 その領域に文字列を書き込んではいけません。
ローカルエコーすべき文字列が無い場合はlengthメンバに０が返ります。
ローカルエコーすべき内容が前回のXLookupKanjiStringの呼び出しのときと 変わらない場合（例え
ばシフトキーが押された場合など）はlengthメンバに −１が返ります。 │
モードの変更や、候補一覧に関する情報の有無は、infoメンバによって渡され ます。infoメンバ │
のKanjiModeInfoビットがonであれば、modeに新しいモード を示す文字列が返されます。infoメンバ │
のKanjiGLineInfoビットがonであれば、 gline構造体に候補一覧等の情報が格納されています。 │
gline構造体のlineメンバには候補一覧表示のための文字列が返されます。 gline構造体 │
のline,revPos,revLenの各メンバは、候補一覧文字列のそれぞれ、 長さ、リバース表示の開始位 │
置、リバース表示の長さが返されます。
変換中に確定した(EUC)文字列がある場合は、 その文字列がbuffer_returnに格納され、 その文字列
の長さ（バイト単位）がこの関数の戻り値として返されます。 確定した文字列が無い場合は戻り値
は０になります。
名前
XKanjiControl - XLookupKanjiStringでのモードや，処理の制御を行う
形式
#include <X11/kanji.h>
int XKanjiControl(dpy, win, request, arg)
Display dpy;
Window win;
int request;
char *arg;
説明
XKanjiControlはdpy, winで示されるウィンドウにおける日本語入力に 関して，requestで示される
処理を行います．処理によっては，引数を 伴う場合があり，その場合，引数はargにて与えます．
XKanjiControlで制御される機能としては以下があります．
request名 機能
KC_INITIALIZE かな漢字変換を初期化する．
KC_CHANGEMODE 入力モードを変更する．
KC_SETWIDTH 候補一覧表示の時の幅を指定する．
KC_FINALIZE かな漢字変換の終了処理．
KC_SETUNDEFKEYFUNCTION
未定義キーに対する機能の設定を行う．
KC_SETMODEINFOSTYLE
モード情報を数値で表現するかどうかを指定する．
KC_KAKUTEI 入力中の文字列を確定する．
KC_KILL 入力中の文字列を削除する．
KC_QUERYMODE 現在のモードを問い合わせる．
KC_SETSERVERNAME 接続するサーバを指定する．
KC_SETINITFILENAME
カスタマイズファイルを指定する．
KC_CLOSEUICONTEXT コンテクストをクローズする．
KC_QUERYMAXMODESTR
モード表示文字列の最大長を求める．
XKanjiControlの作用は基本的にはdpy, winで指定されたウィンドウで の日本語入力に対しての み
作用します．ただし，初期化の処理や終了の処理に関してはその限りではあ りません．
XKanjiControlの操作によって未確定文字列の状態が変化したり，モードの状 態が変わることがあり
ます．そのような可能性がある場合はarg部分に変化し た情報を格納できるような構造体へのポイン
タを渡します．その構造体の定義 は以下のようになります．
typedef struct {
int val; /* バッファに格納された文字列の長さが返る */
unsigned char *buffer; /* 確定文字列を格納するためのバッファを与える */
int bytes_buffer; /* 上記のバッファの大きさを与える */
XKanjiStatus *ks; /* 未確定文字列の情報を格納する構造体へのポインタ */
} XKanjiStatusWithValue;
XKanjiControlのそれぞれの機能の実行のしかたは以下の通りです．
(1) KC_INITIALIZE - かな漢字変換の初期化
KC_INITIALIZEをrequest部で指定することにより，かな漢字変換の初期 化を行います．argに
はwarningメッセージを 格納するための(char **)型の変数へのポインタまたはNULLを指定し
ます．初 期化の処理は基本的にはXKanjiString(3)が最初に呼ばれた時に自動的に行わ れま
すが，XKanjiControlを用いて初期化する ことにより，XKanjiString(3)での初期化処理は行
われなくなります．
XKanjiString(3)の使用に先立ってXKanjiControlを用いてかな漢字変換に関 する制御を行う
時などは，漢字変換の初期化を行う必要があります．
正常終了時にはXKanjiControlの戻り値として0が返り，異常終了時には-1が 返ります．
KC_INITIALIZEを行った場合，エラーとまではいかなくとも何らかのwarningが 発生すること
があります．warningが発生した場合はargにて与えられた 変数に対してwarning文字列の配列
へのポインタが格納され 返されます．warningがないときはNULLが格納され返されます．
(例)
int res; /* エラーが返ってくる場合に備える */
char **warning;
.....
res = XKanjiControl(dpy, win, KC_INITIALIZE, &warning);
if (warning) {
char **p;
for (p = warning ; *p ; p++) {
fprintf(stderr, "%s0, *p);
}
}
第4引数に返されるwarningメッセージはライブラリの内部でmallocされます． これは，次
にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます．アプ リケーションプログラマ
が勝手にfreeしてはいけません．warningは今のとこ ろ最大64メッセージに限定されます．そ
れ以上のメッセージは切捨てられます．
メッセージに含まれる可能性のあるwarningには以下のものがあります．
・ カスタマイズファイルがシステムのものも含めてすべて利用できない．
・ カスタマイズファイルにシンタックスエラーがある．
・ ローマ字かな変換辞書が利用できない．
・ かな漢字変換辞書が利用できない．
・ かな漢字変換サーバに接続できない．
第4引数としてNULLを指定した場合warningメッセージは捨てられます．
(2) KC_CHANGEMODE - 入力モードの変更
入力モードをアプリケーションから変更します．requestの 部分にはKC_CHANGEMODEを指定
し，argにXKanjiStatusWithValue構造体 を指定して下さい．XKanjiStatusWithValue構造体
のvalメンバにてモー ド番号を指定することにより日本語モードが切り替わります．モード番
号は以 下のマクロで示されます．
マクロ番号 モード
CANNA_MODE_AlphaMode アルファベットモード
CANNA_MODE_HenkanMode 変換入力モード
CANNA_MODE_KigoMode 記号入力モード
CANNA_MODE_ZenHiraKakuteiMode
全角ひらがな確定入力モード
CANNA_MODE_ZenKataKakuteiMode
全角カタカナ確定入力モード
CANNA_MODE_HanKataKakuteiMode
半角カタカナ確定入力モード
CANNA_MODE_ZenAlphaKakuteiMode
全角アルファベット確定入力モード
CANNA_MODE_HanAlphaKakuteiMode
半角アルファベット確定入力モード
CANNA_MODE_HexMode 16進コード入力モード
CANNA_MODE_BushuMode 部首入力モード
CANNA_MODE_TorokuMode 単語登録モード
この機能によりモードを変更するとモード名を始めとして多くの表示が変化を 受けます．表
示の変更はargとして指定したXKanjiStatusWithValue構造体に て返されます．
(例)
XKanjiStatus ks;
XKanjiStatusWithValue ksv;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
ksv.val = CANNA_MODE_HexMode;
XKanjiControl(dpy, win, KC_CHANGEMODE, &ksv);
len = ksv.val;
.....
/* 未確定文字列や確定文字列の情報がksvにより返されます． */
(3) KC_SETWIDTH - 候補一覧表示のための幅を指定
候補一覧のために用いられる領域のコラム数を指定します．１コラムの幅はア ルファベット
文字あるいは半角カタカナ１文字の文字幅であり，全角漢字は２ コラム占めることになりま
す．候補一覧表示のための幅を 指定するためにrequest部分に指定する値はKC_SETWIDTHで，
このときargにコラム数を指定します．
(例)
XKanjiControl(dpy, win, KC_SETWIDTH, (char *)60);
(4) KC_FINALIZE - かな漢字変換の終了処理．
プログラムを終了するなどの局面でかな漢字変換も終了することを指定します． かな漢字変
換処理を終了させる時は必ずこの処理を行って下さい．終わるにあ たって今まで学習した内
容がファイルに登録されます．request部分に はKC_FINALIZEを指定します．
正常終了時に0，異常終了時に-1が戻り値として返ります．
KC_FINALIZEを行った場合，エラーとまでいかなくとも何らかのwarningが発生 することがあ
ります．warningが発生した場合はargにて与えられた 変数にwarning文字列の配列へのポイン
タが格納され返されます．warningがな い場合にはNULLポインタが格納され返されます．
(例)
int res; /* エラーが返る場合に備える */
char **warning;
.....
res = XKanjiControl(dpy, win, KC_FINALIZE, &warning);
if (warning) {
char **p;
for (p = warning ; *p ; p++) {
fprintf(stderr, "%s0, *p);
}
}
第4引数に返されるwarningメッセージは，ライブラリの内部でmallocされま す．これは，次
にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます． アプリケーションプログラマ
が勝手にfreeしてはいけません．
warningは今のところ最大64メッセージに限定されます．それ以上のメッセー ジは切捨てられ
ます．
メッセージに含まれる可能性のあるwarningには次のものがあります．
・ 辞書がアンマウントできない．
第4引数としてNULLを指定した場合，warningメッセージは捨てられます．
(5) KC_SETUNDEFKEYFUNCTION - 未定義キーに対する機能の設定
読みを入力している状態でC-tを打ったときのように未定義キーを入力した時 に取られる処理
を指定します．未定義キーに対応して行われる処理としては以 下の処理があります．
マクロ名 処理
kc_normal ビープ
kc_through アプリケーションプログラムに渡す
kc_kakutei 確定しアプリケーションプログラムに渡す
kc_kill 消去しアプリケーションプログラムに渡す
kc_normalを指定した場合，外部変数jrBeepFuncに設定された関数が未定義キー 入力時にライ
ブラリによって自動的に呼び出されます．jrBeepFuncに値を設定 しない場合には(jrBeepFunc
== NULLの場合には)何も起こりません．
(例)
extern (*jrBeepFunc)(), beep();
jrBeepFunc = beep;
XKanjiControl(dpy, win, KC_SETUNDEFKEYFUNCTION, kc_normal);
(6) KC_SETMODEINFOSTYLE - モード情報の表現
モード情報を文字列ではなくビットマップなどのデータで表示したい場合があ ります．その
ような場合にはモード情報として数値データが返ってくると処理 がしやすくなりま
す．XKanjiControlでKC_SETMODEINFOSTYLEを 指定し，argに１を渡すことによってそれ以後
はXKanjiStatus構造体 のmodeメンバにはモードを表す数値に'@'(0x40)を加えた１文字が返さ
れるようになります．モードを表す数値に変換する場合には返ってきた文字列 か
ら'@'(0x40)を引きます．モードを表す数値については入力モードの 変
更((2)KC_CHANGEMODE)のこうを参照して下さい．
(7) KC_KAKUTEI，(8) KC_KILL - 入力中の文字列の放棄
入力中の文字列を何らかの都合で放棄したい場合があります．放棄する場合に 入力中の文字
列を確定文字列として取り込んでから放棄したい場合と全く捨て てしまってから放棄したい
場合があります．確定する 場合にはXKanjiControlにてKC_KAKUTEIを指定し，放棄する 場合
にはKC_KILLを指定します．
この処理は表示に影響を与えるので第4引数にはXKanjiStatusWithValue構造 体を指定しなけ
ればなりません．
XKanjiStatusWithValue ksv;
XKanjiStatus ks;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
XKanjiControl(dpy, win, KC_KAKUTEI, &ksv);
len = ksv.val;
.....
(9) KC_QUERYMODE - モードの問い合わせ
現在のモードを問い合わせるにはXKanjiControlでKC_QUERYMODEを指定します．
第4引数にはモード文字列を格納するための文字配列のポインタを指定します． モード文字列
はヌル文字で終わる文字列です．ここに数値が返るようにするに
はXKanjiControlでKC_SETMODEINFOSTYLEを指定してモード文字列のスタイル を変更しておき
ます．
(例)
char currentMode[MAXMODELEN];
.....
XKanjiControl(dpy, win, KC_QUERYMODE, currentMode);
.....
(10) KC_SETSERVERNAME - サーバの指定
かな漢字変換サーバとしてどのサーバを使うかをアプリケーションプログラム を終了するこ
となしに切替えることが可能です．かな漢字変換サーバとして接 続するべきサーバを指定す
るにはXKanjiControlでKC_SETSERVERNAMEを指定し ます．第4引数には接続したいサーバ名を
指定します．
(11) KC_SETINITFILENAME - カスタマイズファイルの指定
カスタマイズファイルをアプリケーションプログラム側から変更することがで きます．カス
タマイズファイルの変更はXKanjiControlの 第3引数にKC_SETINITFILENAMEを指定し，第4引数
にファイル名文字列を指定 することにより行います．この処理を行う場合はKC_INITIALIZEに
先立って実 行しておかなければなりません．
(例)
char *inifile = "app-own.canna"
.....
XKanjiControl(dpy, win, KC_SETINITFILENAME, initfile);
.....
(12) KC_CLOSEUICONTEXT - コンテクストのクローズ
XKanjiControlやXKanjiStringを呼び出すと，dpy, winの組み合わせに 対してひとつの変換コ
ンテクストを割り当てます． 今まで使われていないdpy, winの 組み合わせをXKanjiStringあ
るいはXKanjiControlに与えることが可能 であり，その場合，そのウィンドウ用に新たにコン
テクストが作成され必要なメ モリが確保されます．
それまで使用していたウィンドウが使われなくなった場合に，そのウィンドウに割 り当てて
使っていたコンテクスト用に確保されたメモリを 開放するにはXKanjiControlを第3引数
にKC_CLOSEUICONTEXTを指定して呼び 出します．
この処理は表示の変化をともなうので第4引数にはXKanjiStatusWithValue構 造体を与えま
す．
(例)
XKanjiStatusWithValue ksv;
XKanjiStatus ks;
unsigned char buf[SOMESIZE];
.....
ksv.ks = &ks;
ksv.buffer = buf;
ksv.bytes_buffer = SOMESIZE;
XKanjiControl(dpy, win, KC_CLOSEUICONTEXT, &ksv);
.....
(13) KC_QUERYMAXMODESTR - モード表示文字列の最大長を求める．
初期化ファイルにてモード表示文字列がカスタマイズできますが，カスタマイ ズされた結果
モード表示文字列にどれだけの表示領域を確保するかを調べる必 要がある場合がありま
す．XKanjiControlを第3引数にKC_QUERYMAXMODESTRを 指定して呼び出すことにより，モード
表示文字列として何コラム必要かが返り 値として返されます．ここで言うコラムとは半角英
数文字の文字幅を１とした ときの値を示します．
第4引数は用いられないのでダミー値として0を与えます．
(例)
int max_mode_columns;
.....
max_mode_columns = XKanjiControl(dpy, win, KC_QUERYMAXMODESTR, 0);
.....
4 April 1991 XKANJICONTROL(3)