curs_util(3X) | curs_util(3X) |
名称
delay_output, filter, flushinp, getwin, key_name, keyname, nofilter, putwin, unctrl, use_env, wunctrl - 雑多な curses ユーティリティルーチン書式
#include <curses.h>解説
unctrl ルーチンは、属性を無視して、文字 c の印刷可能な表現である文字列を返します。制御文字は、 ^ X 表記で表示されます。印刷文字は、そのまま表示されます。対応する wunctrl は、ワイド文字の印刷可能な表現を返します。keyname ルーチンは、キー c に対応する文字列を返します:
- -
- 印刷可能な文字は、例えば、キーを含む 1 文字の文字列として、そのまま表示されます。
- -
- 制御文字は、 ^ X 表記で表示されます。
- -
- DEL (文字 127) は、 ^? として表示されます。
- -
- 128 を超える値は、(画面が初期化されていないか、または meta が TRUE パラメータを付けて呼び出されたなら)、 M- X 記法で表示されるいずれかのメタ文字か、またはそのまま表示されます。後者の場合に、値は、印刷可能でないかもしれません。これは、X/Open 規格に従っています。
- -
- 256 を超える値は、ファンクションキーの名前となります。
- -
- そうでなければ (対応する名前がないなら)、関数は、エラーを示すために NULL を返します。また、X/Open は、(いくつかの実装は、NULL 以外を返し) "UNKNOWN KEY"返り値をリストします。
対応する key_name は、ワイド文字の値 w に対応する文字列を返します。 2 つの関数は、同じ組の文字列を返しません。後者は、前者がメタ文字を表示するところで NULL 返します。
filter ルーチンが使用されるなら、 initscr または newterm が呼び出される前に呼び出されなければなりません。結果は、それらが呼び出される間、 LINES は、1 に設定されます。ケーパビリティ clear, cup, cud, cud1, cuu1, cuu, vpa は、無効にされます。そして、 home 文字列は、 cr の値に設定されます。
nofilter ルーチンは、前の filter 呼び出しの効果を取り消します。それによって、呼び出し側は、 $TERM の値の違いを使用して、異なったデバイスで画面を初期化できます。 filter ルーチンが、端末の情報のメモリ内のコピーを変更するので、制限が生じます。
use_env ルーチンが使用されるなら、 initscr または newterm が呼び出される前に呼び出されます。引数として FALSE を付けて呼び出されるなら、たとえ環境変数 LINES と COLUMNS (デフォルトで使用されます) が設定されても、または curses がウィンドウで実行されても (この場合、 LINES と COLUMNS が設定されていないなら、デフォルトの動作は、ウィンドウサイズを使用します)、 terminfo データベースで指定された line と column の値が使用されます。 LINES または COLUMNS を設定することは、オペレーティングシステムから得られる対応するサイズを上書きすることに注意してください。
putwin ルーチンは、ウィンドウ win に関連したすべてのデータを filep が指すファイルに書き込みます。 getwin 関数を使用して後で、この情報を検索して取り出すことができます。
getwin ルーチンは、 putwin によってファイルに格納されたウィンドウに関連するデータを読み込みます。次に、ルーチンは、そのデータを使用して新しいウィンドウを作成して初期化します。新しいウィンドウを指すポインタを返します。
delay_output ルーチンは、出力で ms ミリ秒の一時停止を挿入します。このルーチンは、詰め物文字が CPU の一時停止ではなく使用されるので、広範囲に使用されるべきではありません。詰め物文字が指定されないなら、これは、遅延を実行するために napms を使用します。
flushinp ルーチンは、ユーザによってタイプされ、プログラムによってまだ読み込まれていないすべての先行入力を廃棄します。
戻り値
flushinp を除いて、整数を返すルーチンは、失敗すると ERR を返し、成功して終了すれば、 OK (SVr4 は、" ERR 以外の整数値"とだけ明記されています) を返します。ポインタを返すルーチンは、エラーの場合 NULL を返します。
X/Open は、エラー条件を何も定義していません。この実装では、
- flushinp
- は、端末が初期化されていなかったなら、エラーを返します。
- meta
- は、端末が初期化されていなかったなら、エラーを返します。
- putwin
- は、関連する fwrite 呼び出しが、エラーを返すなら、エラーを返します。
移植性
XSI Curses standard, Issue 4 は、これらの関数を記述しています。それは、 unctrl と wunctrl が成功しなければ、NULL ポインタを返すと記述していますが、どんなエラー条件も定義していません。この実装は、次の 3 つの場合をチェックします:- -
- パラメータは、7 ビットの US-ASCII コードです。これは、文書化された X/Open Curses の場合です。
- -
- パラメータは、範囲 128-159 です、すなわち、C1 制御コード。 use_legacy_coding が 2 パラメータを付けて呼び出されたなら、 unctrl は、パラメータ (すなわち、最初の文字としてのパラメータがある 1 文字の文字列) を返します。そうでなければ、``^@''、``^A''、C0 制御に似た、``~@''、``~A''、その他、を返します。
- X/Open Curses は、curses を初期化する前に unctrl を呼び出すことができるかどうかを文書化していません。この実装は、それを可能にして、その場合 ``~@''、などの値を返します。
- -
- パラメータ値は、0 から 255 の範囲の外側です。 unctrl は、NULL ポインタを返します。
SVr4 文書は、漠然とした用語で filter の動作のみを記述しています。ここで、その記述は、(誤って cuu を無効にすることについての記述が間違っている) XSI Curses 標準から編集されています。
この実装の unctrl によって返される文字列は、`^' でなく `~' 接頭辞がある上位 128 コードから C1 制御を表示して、コンパイル時に決定されます。他の実装には、異なった仕様があります。例えば、それらは、`^' をつけた制御文字の設定とパラメータを 7 ビットにすることの両方を表示します。または、それらは、C1 制御を無視して、印刷可能な上位 128 コードのすべてを取り扱います。この実装は、8 ビットを使用していますが、ロケールを反映するように文字列を変更していません。 use_legacy_coding 関数によって、呼び出し側は、 unctrl の出力を変更することができます。
同様に、 meta 関数によって、呼び出し側は、 keyname の出力を変更することができます、すなわち、それは、``メタ'' キー (範囲 128 から 255 のコード) のために `M-' 接頭辞を使用するかどうか決定します。 use_legacy_coding と meta の両方は、curses が初期化された後にだけ成功します。 X/Open Curses は、コード 128 から 159 の処理を文書化していていません。 ``メタ'' キーとしてそれらを取り扱うとき、 (または、 keyname が curses を初期化する前に呼び出されるなら) これは、返り文字列 ``M-^@''、``M-^A''、その他、を実装しています。
keyname 関数は、 tic の -x オプションを通して、 terminfo エントリで定義されたユーザ定義文字列のケーパビリティの名前を返します。この実装は、"k"で始まるユーザ定義文字列に、実行時に、キーコードを自動的に割り当てます。キーコードは、KEY_MAX で始まりますが、ユーザ定義のコードがロードされたすべての端末の記述とマージされので、異なった実行で同じ値となることは、保証されていません。 use_extended_names 関数は、端末の記述がライブラリによって読み込まれるとき、このデータがロードされるかどうかを制御します。
nofilter ルーチンは、ncurses に特有です。それは、Version 7、BSD または System V 実装でサポートされませんでした。 ncurses 拡張に依存するあらゆるコードは、NCURSES_VERSION を使用して条件付けられることが推奨されます。