名前

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を指定します．初 期化の処理は基本的にはが最初に呼ばれた時に自動的に行わ れますが，jrKanjiControlを用いて初期化する ことにより，での初期化処理は行われなくなります．
の使用に先立って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);
  .....
 

Recommended readings

Pages related to jrKanjiString you should read also:
XKanjiString(3) jrKanjiControl(3)

Questions & Answers

Helpful answers and articles about jrKanjiString you may found on these sites:
Stack Overflow Server Fault Super User Unix & Linux Ask Ubuntu Network Engineering DevOps Raspberry Pi Webmasters Google Search