Provided by: libcanna1g-dev_3.7p3-17_amd64 bug

名前

       UILib intro - ユーザインタフェースライブラリイントロ

説明

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

       ユーザインタフェースライブラリでは,TTYベース  でjrKanjiStringおよびjrKanjiControl,Xウィ
       ンドウベースで 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からの入力,Xでの入力,基本ウィンドウでの入力など一般的なキーボー
                           ド入力に対して漢字文字列への変換を行います.

       jrKanjiControl      jrKanjiStringでの制御を指定されたパラメタにより行います.

       XLookupKanjiString  Xウィンドウシステムにおいて,キーボード入力(キーイベント)の漢字文字列
                           への変換を行います.

       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からの入力,Xでの入力,基本ウィンドウでの入力など,  一般的なキーボード
       入力に対して漢字文字列への変換を行う関数です.

       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メンバに0が返ります.

       ローカルエコーすべき内容が前回の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で制御される機能としては以下の5つがあります.

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

             第3引数に返されるwarningメッセージはライブラリの内部でmallocされます.   これは,次
             にKC_INITIALIZEやKC_FINALIZEが行われた時に開放されます.アプ  リケーションプログラマ
             が勝手にfreeしてはいけません.warningは今のとこ ろ最大64メッセージに限定されます.そ
             れ以上のメッセージは切捨てられます.

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

             ・ カスタマイズファイルがシステムのものも含めてすべて利用できない.

             ・ カスタマイズファイルにシンタックスエラーがある.

             ・ ローマ字かな変換辞書が利用できない.

             ・ かな漢字変換辞書が利用できない.

             ・ かな漢字変換サーバに接続できない.

             第3引数として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 - 候補一覧表示のための幅を指定

             候補一覧のために用いられる領域のコラム数を指定します.1コラムの幅はア  ルファベット
             文字あるいは半角カタカナ1文字の文字幅であり,全角漢字は2  コラム占めることになりま
             す.候補一覧表示のための幅を  指定するために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);
                 }
               }

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

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

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

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

             第3引数として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に1を渡すことによってそれ以後
             はjrKanjiStatus構造体  のmodeメンバにはモードを表す数値に'@'(0x40)を加えた1文字が返
             さ     れるようになります.モードを表す数値に変換する場合には返ってきた文字列     か
             ら'@'(0x40)を引きます.モードを表す数値については入力モードの                     変
             更((2)KC_CHANGEMODE)のこうを参照して下さい.

       (7)   KC_KAKUTEI,(8) KC_KILL - 入力中の文字列の放棄

             入力中の文字列を何らかの都合で放棄したい場合があります.放棄する場合に  入力中の文字
             列を確定文字列として取り込んでから放棄したい場合と全く捨て  てしまってから放棄したい
             場合があります.確定する 場合にはjrKanjiControlにてKC_KAKUTEIを指定し,放棄する 場合
             にはKC_KILLを指定します.

             この処理は表示に影響を与えるので第3引数には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を指定します.

             第3引数にはモード文字列を格納するための文字配列のポインタを指定します.  モード文字
             列はヌル文字で終わる文字列です.ここに数値が返るようにするに
             はjrKanjiControlでKC_SETMODEINFOSTYLEを指定してモード文字列のスタイル を変更しておき
             ます.

             (例)
               char currentMode[MAXMODELEN];
               .....
               jrKanjiControl(0, KC_QUERYMODE, currentMode);
               .....

       (10)  KC_SETSERVERNAME - サーバの指定

             かな漢字変換サーバとしてどのサーバを使うかをアプリケーションプログラム  を終了するこ
             となしに切替えることが可能です.かな漢字変換サーバとして接  続するべきサーバを指定す
             るにはjrKanjiControlでKC_SETSERVERNAMEを指定し  ます.第3引数には接続したいサーバ名
             を指定します.

       (11)  KC_SETINITFILENAME - カスタマイズファイルの指定

             カスタマイズファイルをアプリケーションプログラム側から変更することがで  きます.カス
             タマイズファイルの変更はjrKanjiControlの          第2引数にKC_SETINITFILENAMEを指定
             し,第3引数にファイル名文字列を指定      することにより行います.この処理を行う場合
             はKC_INITIALIZEに先立って実 行しておかなければなりません.

             (例)
               char *inifile = "app-own.canna"
               .....
               jrKanjiControl(0, KC_SETINITFILENAME, initfile);
               .....

       (12)  KC_CLOSEUICONTEXT - コンテクストのクローズ

             変換コンテクストを表すコンテクストIDは任意の整数を割り当てることができ  ます.今まで
             使われていない コンテクストIDをjrKanjiStringあるいはjrKanjiControlに与えることが可能
             であり,その場合,そのコンテクスト用のイニシャライズが行われ必要なメ  モリが確保され
             ます.

             それまで使用していた入力ポートが使われなくなった場合に,そのポートに割  り当てて使っ
             ていたコンテクストID用に確保されたメモリを      開放するにはjrKanjiControlを第2引数
             にKC_CLOSEUICONTEXTを指定して呼び 出します.

             この処理は表示の変化をともなうので第3引数には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を第2引数にKC_QUERYMAXMODESTRを  指定して呼び出すことにより,モー
             ド表示文字列として何コラム必要かが返り  値として返されます.ここで言うコラムとは半角
             英数文字の文字幅を1とした ときの値を示します.

             第3引数は用いられないのでダミー値として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日本語文字を取り扱うことができま
       す。

       アルファベット文字の取り扱いについては、 XLookupKanjiStringXLookupStringと同様の動作にな
       ります。

       日本語文字の取り扱いについては、 この関数の内部においてローマ字かな変換、 かな漢字変換が行
       われます。 日本語の入力時に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メン
       バ、revPosrevLenメンバにて    返されます。    ローカルエコーすべき文字列のためのバッファ
       はXLookupKanjiStringに  よって自動的に確保されますが、その領域は読み取りのみに用いられるべ
       きであり、 その領域に文字列を書き込んではいけません。

       ローカルエコーすべき文字列が無い場合はlengthメンバに0が返ります。

       ローカルエコーすべき内容が前回のXLookupKanjiStringの呼び出しのときと  変わらない場合(例え
       ばシフトキーが押された場合など)はlengthメンバに −1が返ります。                           │

       モードの変更や、候補一覧に関する情報の有無は、infoメンバによって渡され    ます。infoメンバ │
       のKanjiModeInfoビットがonであれば、modeに新しいモード を示す文字列が返されます。infoメンバ │
       のKanjiGLineInfoビットがonであれば、 gline構造体に候補一覧等の情報が格納されています。     │

       gline構造体のlineメンバには候補一覧表示のための文字列が返されます。            gline構造体 │
       のline,revPos,revLenの各メンバは、候補一覧文字列のそれぞれ、    長さ、リバース表示の開始位 │
       置、リバース表示の長さが返されます。

       変換中に確定した(EUC)文字列がある場合は、 その文字列がbuffer_returnに格納され、 その文字列
       の長さ(バイト単位)がこの関数の戻り値として返されます。  確定した文字列が無い場合は戻り値
       は0になります。

名前

       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 - 候補一覧表示のための幅を指定

             候補一覧のために用いられる領域のコラム数を指定します.1コラムの幅はア  ルファベット
             文字あるいは半角カタカナ1文字の文字幅であり,全角漢字は2  コラム占めることになりま
             す.候補一覧表示のための幅を  指定するために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に1を渡すことによってそれ以後
             はXKanjiStatus構造体 のmodeメンバにはモードを表す数値に'@'(0x40)を加えた1文字が返さ
             れるようになります.モードを表す数値に変換する場合には返ってきた文字列            か
             ら'@'(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を  指定して呼び出すことにより,モード
             表示文字列として何コラム必要かが返り  値として返されます.ここで言うコラムとは半角英
             数文字の文字幅を1とした ときの値を示します.

             第4引数は用いられないのでダミー値として0を与えます.

             (例)
               int max_mode_columns;
               .....
               max_mode_columns = XKanjiControl(dpy, win, KC_QUERYMAXMODESTR, 0);
               .....

                                           4 April 1991                          XKANJICONTROL(3)