この章では,IMLIBルーチンについて説明します。
IMLIBルーチンとは,ユーザが, かな漢字変換のキー定義をできるようなアプリケーションを作成するためのルーチンです。
IMLIBルーチンは,C言語用のインターフェイスを提供します。
IMLIBを使うアプリケーションは,まず最初にPROFILEをオープンします (OPEN PROFILE)。 OPEN PROFILEをしなければ,IMLIBの機能を使うことはできません。 通常はアプリケーションの起動時にOPEN PROFILEが実行されます。 OPEN PROFILEによってPROFILEの情報は,すべてメモリ中に読み込まれます。 OPEN PROFILEが返す整数値UNIT IDは,IMLIBの他のルーチンを呼ぶときに使われます。 UNIT IDによって複数のコンテキストをコントロールします。
アプリケーションは,IMLIBを使い終った後でPROFILEをクローズします(CLOSE PROFILE)。 CLOSE PROFILEを行った後は,IMLIBの機能を使うことはできません。 通常はアプリケーションの終了時に CLOSE PROFILEを実行します。
PROFILEに書かれたデータを検索するには,GET PROFILE DATAを使います。 GET PROFILE DATAは,OPEN PROFILEによってメモリ中に読み込まれたデータを検索して,値を返します。
アプリケーションがPROFILEに書かれたデータを書き換えるには,SET PROFILE DATA を使います。 SET PROFILE DATAは,メモリ中に読み込まれたPROFILEのデータを変更しますので, その後の GET PROFILE DATAは変更の影響を受けます。WRITE PROFILE によって変更されたメモリ中のデータが,ファイルに書き込まれます。
SET PROFILE DATAによって変更されたメモリ中の内容をファイルに反映させるには, WRITE PROFILEを使います。WRITE PROFILEを行わなければ,メモリ中の変更は CLOSE PROFILEによって失われます。
アプリケーションは,SET KEYBINDによってバイナリ形式のKEYBINDファイルの 内容をメモリ中に読み込みます。キーに対応するACTIONを得るためには, SET KEYBINDを実行しておかなければなりません。KEYBIND情報は1つの UNIT IDにつき1つだけ設定できます。すでに,指定したUNIT IDによって KEYBIND情報が読み込まれていた場合には, 古い情報は消えて新しいものと置き換わります。
GET KEY ACTIONによってキーに定義されたACTIONの情報を得ます。 GET KEY ACTIONは1度に複数のACTIONを返しますので, アプリケーションは得られたACTIONを1つずつ実行します。
KEYBINDの内部状態を初期化するには,INIT KEY STATEを使います。 INIT KEY STATEによって,STATEは強制的に"initial"に移ります。 GET KEY ACTIONによって,KEYBIND情報の中にそのキーが定義されていないというステータスが返されると, アプリケーションが「初期状態」にない場合には, INIT KEY STATEを呼んでKEYBINDの内部状態を初期化します。
最近のキーまたは最近の複数キーによるACTIONが不正な場合,またはその ACTIONの結果が不正の場合に,RECOVER KEY STATEによって, そのキーまたは複数キーが押される直前のSTATEに戻すことができます。 アプリケーションがその時点の状態を保存していれば, その状態から実行を再開できます。
GET KEYCODEは,キーの名前を示す文字列を,IMLIBが定義するKEYCODEに変換します。 個々のキーのキー名については,『ユーザ・キー定義 利用者の手引き』 を参照してください。
キーの中には,画面に表示される文字に対応するキーがあります。GET CHARACTERは, KEYCODEに対応する文字を得るのに使われます。 指定されたKEYCODEが,表示される文字に対応しない場合には, GET CHARACTERはそのことを示すステータスを返します。
半角カナは文字コードセットによって若干コードが変わりますので, GET CHARACTERにコードセット指定のパラメータを加えた MC GET CHARACTERを使って文字を得ます。MC GET CHARACTERは半角カナの KEY CODE以外の入力に対してはGET CHARACTERと同じ動作を行います。
キーが発生するコードは,ENCODE KEYによってそのキーに対応する KEYCODEに変換されます。ENCODE KEYには数字キーパッド,編集キーパッド, ファンクション・キーが発生するエスケープ・シーケンスも正しく処理します。
DECwindowsのキー入力ルーチンXLookupString (3X11)が返すKEYSYMの値を KEYSYM TO KEYCODEに渡すと,KEYSYMはIMLIBのKEYCODEに変換されます。
半角カナは文字コードセットによって若干コードが変わりますので, ENCODE KEYにコードセット指定のためのパラメータを加えた MC ENCODE KEYを使って KEYCODEに変換します。MC ENCODE KEYは半角カナ以外の入力に対しては ENCODE KEYと同じ動作を行います。
IMLIBルーチンのインターフェイスと機能についてに個々に示します。
PROFILEを読み込み,そのcontextを示すunit IDを返します。
status=ImOpenProfile(file, unit_id)
ファイル名としてスラッシュを含まない名前が指定された場合、その名前の先頭に
を付け、さらに必要に応じて名前の末尾に拡張子.datをつけて探します。
省略時のPROFILEファイルのデフォルトは以下のファイルを順に探し、最初に見つかったものになります。
これらのどれもが見つからなかった場合は、動作は保証されません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__FILNOTFND | Error | File not found. |
IM__CANNOTOPN | Error | Cannot open. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__SYNTAXERR | Error | Syntax error. |
IM__READERR | Error | File read error. |
PROFILEのデータ構造を指定したファイルに書き込みます。
status=ImWriteProfile(unit_id, file)
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__CANNOTOPN | Error | Cannot open. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__WRITEERR | Error | File write error. |
IM__INSPRV | Error | Insufficient priviledge or file protection violation |
status=ImCloseProfile(unit_id)
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__ILLUNIT | Error | Illegal unit ID. |
status=ImSetProfileData(unit_id, index-string, value-string)
SET PROFILE DATAは,PROFILEのメモリ上のデータを変更します。 変更されたデータをファイルに書き込むにはWRITE PROFILEを使ってください。 なお,INDEX文字列は大文字・小文字を区別しません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__ILLUNIT | Error | Illegal unit ID. |
status=ImGetProfileData(unit_id, index-string, value-string, buflen)
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__NOINDEX | Error | No index. |
IM__TRUNCATED | Warning | String truncated. |
IM__FATERRLIB | Fatal | Fatal library internal error. |
status=ImSetKeybind(unit_id, file, level)
ファイル名としてスラッシュを含まない名前が指定された場合、その名前の先頭に
をつけ、さらに必要に応じて末尾に拡張子.im_datをつけて探します。
省略時のKEYBINDファイルのデフォルトは以下のファイルを順に探し、最初に見つかったものになります。
これらのどれもが見つからなかった場合は、動作は保証されません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__FILNOTFND | Error | File not found. |
IM__CANNOTOPN | Error | Cannot open. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__ILLFORMAT | Error | Illegal data format. |
IM__ILLLEVEL | Error | Illegal level number or file level mismatch. |
IM__NOINDEX | Error | No index. |
IM__READERR | Error | File read error. |
status=ImGetKeyAction(unit_id, key_code, action_list)
"Key not defined"という条件値は,そのキーがその状態で, ユーザによって定義されていないことを示します。 この場合は,アプリケーションが定義する機能を実行します。
"Wait for next key"という条件値は, <GOLD>キーのようなそのキーだけでは完結しないキーが入力されたことを示します。 この場合,アプリケーションは GET KEY ACTIONをもう一度呼んで,複数キーに定義された ACTIONを得なければなりません。アプリケーションは,GET KEY ACTIONを "Wait for next key"が出なくなるまで続けることになります。 複数キーは最大16個まで許されています。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__INSVIRMEM | Error | Insufficient virtual memory. |
IM__NOKEYBIND | Error | Keybind data is not set yet. Execute SET KEYBIND first. |
IM__KEYNOTDEFINED | Information | The specified key is not defined. Execute application defined action. |
IM__PARTIALKEY | Information | The key is middle of a multiple keydefinition. Wait for the next key to complete the key definition. |
IM__NOACTION | Information | The key has no action. |
status=ImRecoverKeyState(unit_id)
注意: 直前のSTATEに戻すのは,アプリケーションの責任です。 最近のACTIONにDONEが入っていた場合,DONEの前の状態に戻すことはできません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__NORECOVER | Warning | No previous state to recover. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__NOKEYBIND | Error | Keybind data is not set up yet. |
keycode=ImGetKeycode(key_name)
status=ImGetCharacter(keycode, ch)
表示文字は最大1バイトなので,アプリケーションは"ch"のために, 終端のヌル文字を含めて最低 2バイト用意しなければなりません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__NOPRINTABLE | Information | The keycode is not for a key of printable character. |
IM__INVKEYCODE | Error | Invalid keycode |
IM__FATERRLIB | Fatal | Fatal library internal error. |
status=ImMCGetCharacter(keycode, ch, codeset)
MC GET CHARACTERは,コードセットにより異なる半角カナのコードに対応しています。 コードセットして指定できるシンボルは次のとおりです。
シンボル | コードセット | 半角カナコード |
---|---|---|
IM$C_DECKANJI | DEC漢字 | 0xA1〜0xDF |
IM$C_SDECKANJI | SuperDEC漢字 | SS2(0x8E) + 0xA1〜0xDF |
IM$C_EUCJP | 日本語EUC | SS2(0x8E) + 0xA1〜0xDF |
IM$C_SJIS | シフトJIS | 0xA1〜0xDF |
表示文字は最大2バイトなので,アプリケーションは"ch"のために, 終端のヌル文字を含めて最低 3バイト用意しなければなりません。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__NOPRINTABLE | Information | The keycode is not for a key of printable character. |
IM__INVKEYCODE | Error | Invalid keycode |
IM__FATERRLIB | Fatal | Fatal library internal error. |
IM__INVCODESET | Error | Invalid Codeset Specified. |
status=ImInitKeyState(unit_id)
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__ILLUNIT | Error | Illegal unit ID. |
IM__NOKEYBIND | Error | Keybind data is not set yet. Execute SET KEYBIND first. |
keycode=ImEncodeKey(string, length)
キーは1つずつ渡さなければなりません。2つ以上のキーを同時に渡すとエラーとなります。 サポートされている表示文字コードは,ASCIIコードと半角カナコードです。 ファンクション・キーなどのようにエスケープ・シーケンスを発生するキーは, エスケープ・シーケンス全体を一度にENCODE KEYに渡す必要があります。
keycode=ImMCEncodeKey(string, length, codeset)
MC ENCODE KEYは,コードセットによって異なる半角カナのコードに対応しています。 コードセットとして指定できるシンボルは次のとおりです。
シンボル | コードセット | 半角カナコード |
---|---|---|
IM$C_DECKANJI | DEC漢字 | 0xA1〜0xDF |
IM$C_SDECKANJI | SuperDEC漢字 | SS2(0x8E) + 0xA1〜0xDF |
IM$C_EUCJP | 日本語EUC | SS2(0x8E) + 0xA1〜0xDF |
IM$C_SJIS | シフトJIS | 0xA1〜0xDF |
半角カナコード以外の入力に対する出力は ENCODE_KEYと同じです。
keycode=ImKeysymToKeycode(keysym, modifier)
すべてのモディファイアがサポートされているわけではありませんが, サポートされていないキーが押されたということを示すために, モディファイアは必ず指定してください。
モディファイアを指定するためには以下に示す定数値を使います。
モディファイアのビット列は,XLookupStringによって返されるビット列と同じなので, DECwindowsのアプリケーションはXLookupStringが返す値をそのまま KEYSYM TO KEYCODEに渡すことができます。
KEYSYM TO KEYCODEがサポートするKEYSYMの値は, 付録 Aを参照してください。
シンボル | 重大度 | メッセージ |
---|---|---|
IM__SUCCESS | Success | Normal successful completion. |
IM__UNSUPKEYSYM | Error | Unsupported keysym. |