curs_util(3x) curs_util(3x)
delay_output, filter, flushinp, getwin, key_name, keyname,
nofilter, putwin, unctrl, use_env, use_tioctl, wunctrl
- 種々の curses ユーティリティ・ルーチン
#include <curses.h>
char *unctrl(chtype c);
wchar_t *wunctrl(cchar_t *c);
char *keyname(int c);
char *key_name(wchar_t w);
void filter(void);
void nofilter(void);
void use_env(bool f);
void use_tioctl(bool f);
int putwin(WINDOW *win, FILE *filep);
WINDOW *getwin(FILE *filep);
int delay_output(int ms);
int flushinp(void);
unctrl ルーチンは文字 c の印字可能な表現を文字列として
返します。属性は無視されます。
制御文字は ^X の形式で表示されます。
印字可能文字はそのまま表示されます。
対応する wunctrl はワイド文字の印字可能な表現を返します。
keyname ルーチンはキー c に対応する文字列を返します。
o 印字可能文字はそれ自身を表示します。
たとえば、そのキーを含む 1 文字の文字列です。
o 制御文字は ^X の形式で表示されます。
o DEL (コード 127) は ^? と表示されます。
o 128 以上の値は、M-X の形式で表示される
メタ文字 (画面が初期化されていないか、meta を
引数 TRUE とともに呼び出したとき) か、またはそのまま
表示されます。
後者の場合、値は印字可能でないことがあります。これは
X/Open の仕様に従っています。
(訳注: meta 関数は curs_inopts(3x) を参照)
o 256 以上の値はファンクションキーの名前の
名前であることがあります。(訳注: 原文どおり)
さもなければ (対応する名前がない場合) エラーを知らせるため
関数はヌルを返します。
X/Open はいくつかの実装がヌルの代わりに返す
"UNKNOWN KEY" という戻り値を載せています。
対応する key_name はワイド文字値 w に対応する文字列を
返します。
これら 2 つの関数は同じ文字列の組を返しません。前者が
メタ文字を表示するところで、後者はヌルを返します。
filter ルーチンを使うときは、initscr または newterm を
呼び出す前に呼び出さなければなりません。
filter の効果は、これらの呼び出しの間、LINES を 1 に設定し、
clear, cup, cud, cud1, cuu1, cuu, vpa の機能項目を無効にし、
home 文字列を cr の値に設定します。
nofilter ルーチンは先行する filter 呼び出しの効果を
取り消します。
これにより、異なるデバイス上の画面を異なった $TERM の値で
初期化することができるようになります。
filter ルーチンはメモリ上にある端末情報のコピーを修正するため、
制約が生じます。
use_env ルーチンを使うときは、initscr または newterm を
呼び出す前に呼び出さなければなりません。(それらは画面の
サイズを計算するためです。)
このルーチンは ncurses が画面のサイズを決定する時に
環境変数を扱う方法を変更します。
o 通常 ncurses は最初に端末データベースで画面のサイズを
調べます。
use_env が引数 FALSE とともに呼び出された場合、
use_tioctl が引数 TRUE とともに呼び出されないかぎり、
ここで止めます。
o 次にオペレーティング・システム呼び出しにより画面のサイズを
問い合わせます。成功した場合、端末データベースからの値は
上書きされます。
o 最後に (use_env が引数 FALSE とともに呼び出されていない
かぎり) ncurses は環境変数 LINES または COLUMNS を調べ、
それらの値を使ってオペレーティング・システムからの
または端末データベースからの結果を上書きします。
ncurses はまた、環境変数 LINES または COLUMNS で上書き
されない限り SIGWINCH への応答として画面サイズを
変更します。
(訳注: resizeterm(3x), curs_initscr(3x) 参照)
use_tioctl ルーチンを使うときは、initscr または newterm を
呼び出す前に呼び出さなければなりません。(それらは画面の
サイズを計算するためです。)
use_tioctl が引数 TRUE とともに呼び出された後、ncurses は
画面サイズを計算する最後の段階を次のように変更します。
o 環境変数 LINES と COLUMNS が 0 より大きい値に
設定されていることを確かめます。
o それぞれについて、ncurses は対応する環境変数の値を
オペレーティング・システム呼び出し経由で得た値または
端末データベースからの値で更新します。
o 画面のサイズを設定したこれらの環境変数をそのまま保持する
ために、ncurses はこれらの環境変数の値を再度読み出します。
use_env と use_tioctl ルーチンの組み合わせは次のように
まとめられます。
use_env use_tioctl まとめ
----------------------------------------------------------------
TRUE FALSE これはデフォルトの動作です。
ncurses は環境変数 $LINES または $COLUMNS
で上書きされない限りオペレーティング・
システム呼び出しを使います。
TRUE TRUE ncurses はオペレーティング・システム
呼び出しに基づいて $LINES と $COLUMNS を
更新します。
FALSE TRUE ncurses は $LINES と $COLUMNS を無視し、
サイズを得るためにオペレーティング・
システム呼び出しを使います。
FALSE FALSE ncurses は端末データベースに依って
サイズを決定します。
putwin ルーチンはウインドウ (またはパッド) win に関連する
すべてのデータを filep が指すファイルへ書き出します。
この情報は後で getwin 関数を使って復元することができます。
getwin ルーチンは putwin でファイルに書き込まれた
ウインドウに関連するデータを読み出します。
次に、このルーチンはそのデータを使って新しいウインドウを
作成して初期化します。
このルーチンは新しいウインドウへのポインタを返します。
いくつかの注意点を下に示します。
o 書き込まれたデータは WINDOW 構造体と、これに伴う文字の
マスのコピーです。
フォーマットはワイド文字用ライブラリ (ncursesw) と
1 バイト用ライブラリ (ncurses) で異なります。
しかし、両者の間でデータを移すこともできます。
o 復元されたウインドウは子ウインドウではなく、常に最上位
レベルのウインドウ (またはパッド) として作成されます。
o ウインドウ内の文字のマスは色のペアの値を含みますが、実際の
色の番号を含みません。
アプリケーションで init_pair, を使って作成されていない
色のペアを復元されたウインドウ中のマスが使っている場合、
ウインドウを更新 (refresh) しても保存した時の色で
表示されません。
delay_output ルーチンは ms ミリ秒の休止を出力に挿入します。
CPU を休止せず、パディング文字を使うので、このルーチンを
広範に使ってはいけません。
パディング文字が指定されていない場合は、遅延を実行するために
napms が使われます。
flushinp ルーチンはすでにタイプされてまだプログラムが
読んでいない先読み入力をすべて破棄します。
flushinp を除き、整数を返すルーチンは、失敗のとき ERR を、
正常終了のとき OK (SVr4 は「ERR 以外の整数値」としか
指定していません) を返します。
ポインタを返すルーチンはエラーのとき NULL を返します。
X/Open はエラーの条件を何も定義していません。この実装では
flushinp
端末が初期化されていなかった場合にエラーを返します。
meta
端末が初期化されていなかった場合にエラーを返します。
(訳注: meta 関数は curs_inopts(3x) を参照)
putwin
これに伴う fwrite 呼び出しがエラーを返した場合に
エラーを返します。
SVr4 の説明書は filter の動作をとてもあいまいな表現でしか
記載していません。
ここの記述は (cuu を無効化することについて誤って
記述している) XSI Curses standard から修正したものです。
keyname 関数は、tic の -x オプション経由で terminfo の
収録項目に定義されているユーザ定義文字列機能の名前を返すことが
あります。
この実装は、実行時に "k" で始まるユーザ定義文字列に
キーコードを自動的に割り当てます。
キーコードは KEY_MAX で始まりますが、実行ごとに同じ値である
ことは保証されません。これはユーザ定義のコードがすべての
ロードされた端末記述からマージされるためです。
use_extended_names 関数は、ライブラリが端末記述を読むときに
このデータをロードするかどうかを制御します。
nofilter と use_tioctl ルーチンは ncurses 固有です。
これらは Version 7, BSD, System V の実装では
サポートされていません。
ncurses 拡張機能に依存するすべてのコードは、
NCURSES_VERSION を使って条件付きとすることを推奨します。
putwin と getwin 関数は移植性に関して数個の問題があります。
o これらの関数が読み書きするファイルは実装依存の
フォーマットを使います。
ファイル・フォーマットは明らかに標準化の目標ですが、
見過ごされてきました。
とても興味深いことに、Solaris ソースの著作権登録年によると
これらの関数は (scr_init などと共に) カリフォルニア大学
バークレー校 (1982年) に端を発し、後に SVr4 に
組み込まれました (1988年)。
奇妙なことに、4.3BSD curses のソースにはこのような関数は
ありません。
o 多くの実装では単純に WINDOW 構造体のバイナリをファイルに
ダンプ出力します。
これには ncurses の古いバージョンとともに、SVr4 curses,
NetBSD, PDCurses が含まれます。
この実装は (X/Open の変種である 1995年の Solaris curses
と同様に) テキスト形式のダンプを用いています。
バイナリ・ダンプを使う実装は、ブロック入出力を使います
(fwrite と fread 関数)。
テキスト形式のダンプを使う実装は、バッファ付き入出力を
使います。
少数のアプリケーションはこれらの関数を使ってファイルに
追加のデータを書き込むことがあります。
それはブロック入出力とバッファ付き入出力を混用することで
問題を引き起こす可能性があります。
この実装では出力を一掃することで書き込み時の問題を減らして
います。
しかし、混合した方式を用いて書き込んだファイルからの
読み込みは、成功しないかもしれません。
これらの関数は XSI Curses standard, Issue 4 に記載されて
います。
これは unctrl と wunctrl は失敗のときヌルポインタを返すと
明示していますが、エラーの条件を何も定義していません。
この実装は、次の 3 つの場合を調べます。
o 引数が 7 ビット US-ASCII コードの場合。
これは X/Open Curses に書かれている場合です。
o 引数が 128-159 の範囲、つまり C1 制御文字の場合。
use_legacy_coding が引数 2 と共に呼び出された場合、
unctrl は引数を返します。つまり引数を最初の文字とする
1 文字の文字列です。
さもなければ、("^@", "^A",… など C0 制御文字に類似した)
"~@", "~A",… などを返します。
X/Open Curses は curses を初期化する前に unctrl を
呼び出せるかどうかを記述していません。
この実装ではそれを許しており、その場合には "~@",… などの
値を返します。
o 引数が 0 から 255 の範囲外の場合。
unctrl はヌルポインタを返します。
この実装では 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 までのコードの扱いについて
記述していません。
これらを "メタ" キーとして扱うとき (または curses を初期化
する前に keyname が呼ばれたとき)、この実装は "M-^@", "M-^A",
などの文字列を返します。
legacy_coding(3x), curses(3x), curs_initscr(3x),
curs_kernel(3x), curs_scr_dump(3x), curs_variables(3x),
legacy_coding(3x). ←重複(訳注)
curs_util(3x)