man UILib intro (3): ユーザインタフェースライブラリイントロ

説明

ユーザインタフェースライブラリは，１文字の入力，１キーの入力に対応して，未確定文字列，確定文字列，注目文節位置，ステータス表示のための文字列，候補一覧のための文字列などを返還するライブラリです．アプリケーションプログラムは，返還された情報によって表示を行います．アプリケーションプログラムは，キー入力以外のトリガーによって(例えばマウスによる選択など)モードの遷移を制御することもできます．

ユーザインタフェースライブラリでは，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

戻り値

入力処理中何らかのエラーが発生した場合は，この関数の戻り値として-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, "%s, *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, "%s, *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が返ります．

(例)

  int res; /* エラーが返ってくる場合に備える */
  char **warning;
  .....
  res = XKanjiControl(dpy, win, KC_INITIALIZE, &warning);
  if (warning) {
    char **p;
    for (p = warning ; *p ; p++) {
      fprintf(stderr, "%s, *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 - 候補一覧表示のための幅を指定

(例)

  XKanjiControl(dpy, win, KC_SETWIDTH, (char *)60);

(4)

KC_FINALIZE - かな漢字変換の終了処理．

正常終了時に0，異常終了時に-1が戻り値として返ります．

(例)

  int res; /* エラーが返る場合に備える */
  char **warning;
  .....
  res = XKanjiControl(dpy, win, KC_FINALIZE, &warning);
  if (warning) {
    char **p;

    for (p = warning ; *p ; p++) {
      fprintf(stderr, "%s, *p);
    }
  }

第4引数に返されるwarningメッセージは，ライブラリの内部でmallocされます．これは，次にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます．アプリケーションプログラマが勝手にfreeしてはいけません．

warningは今のところ最大64メッセージに限定されます．それ以上のメッセージは切捨てられます．

メッセージに含まれる可能性のあるwarningには次のものがあります．

・: 辞書がアンマウントできない．

第4引数としてNULLを指定した場合，warningメッセージは捨てられます．

(5)

KC_SETUNDEFKEYFUNCTION - 未定義キーに対する機能の設定

マクロ名: 処理
kc_normal: ビープ
kc_through: アプリケーションプログラムに渡す
kc_kakutei: 確定しアプリケーションプログラムに渡す
kc_kill: 消去しアプリケーションプログラムに渡す

(例)

  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);
  .....

説明

概要

名前

形式

説明

ファンクションキー

関連情報

戻り値

名前

形式

説明

名称

記述形式

引数

説明

名前

形式

説明

最後に検索