##
6.14.1 関数

`curses` モジュールでは以下の例外を定義しています:

exception `error`
  curses ライブラリ関数がエラーを返した際に送出される例外です。

注意: 関数やメソッドにおけるオプションの引数 x および y がある場合、標準の値は常に現在のカーソルになります。 オプションの attr がある場合、標準の値は `A_NORMAL` です。

`curses` では以下の関数を定義しています:

`baudrate`( | )

  端末の出力速度をビット／秒で返します。ソフトウェア端末エミュレータ の場合、これは固定の高い値を持つことになります。この関数は 歴史的な理由で入れられています; かつては、この関数は時間遅延を 生成するための出力ループを書くために用いられたり、行速度 に応じてインタフェースを切り替えたりするために用いられたり していました。

`beep`( | )

  注意を促す短い音を鳴らします。

`can_change_color`( | )

  端末に表示される色をプログラマが変更できるか否かによって、 真または偽を返します。

`cbreak`( | )

  cbreak モードに入ります。cbreak モード (``rare'' モードと呼ばれる こともあります) では、通常の tty 行バッファリングはオフにされ、 文字を一文字一文字読むことができます。ただし、raw モードとは異なり、 特殊文字 (割り込み:interrupt、終了:quit、一時停止:suspend、および フロー制御) については、tty ドライバおよび呼び出し側のプログラムに 対する通常の効果をもっています。まず `raw()` を呼び出し、 次いで `cbreak()` を呼び出すと、端末を cbreak モード にします。

`color_content`( | color_number)

  色 color_number の赤、緑、および青 (RGB) 要素の強度を返します。 color_number は `0` から `COLORS` の間でなければ なりません。与えられた色の R、G、B、の値からなる三要素のタプルが 返されます。この値は `0` (その成分はない) から `1000` (その成分の最大強度) の範囲をとります。

`color_pair`( | color_number)

  指定された色の表示テキストにおける属性値を返します。 属性値は `A_STANDOUT`、 `A_REVERSE`、 およびその他の `A_*` 属性と組み合わせられています。 `pair_number()` はこの関数の逆です。

`curs_set`( | visibility)

  カーソルの状態を設定します。visibility は 0、1、または 2 に 設定され、それぞれ不可視、通常、または非常に可視、を意味します。 要求された可視属性を端末がサポートしている場合、以前のカーソル 状態が返されます; そうでなければ例外が送出されます。多くの端末では、 ``可視 (通常)'' モードは下線カーソルで、``非常に可視'' モードは ブロックカーソルです。

`def_prog_mode`( | )

  現在の端末属性を、稼動中のプログラムが curses を使う際のモードである ``プログラム'' モードとして保存します。(このモードの反対は、プログラム が curses を使わない ``シェル'' モードです。) その後 `reset_prog_mode()` を呼ぶとこのモードを復旧します。

`def_shell_mode`( | )

  現在の端末属性を、稼動中のプログラムが curses を使っていないときのモード である ``シェル'' モードとして保存します。(このモードの反対は、 プログラムが curses 機能を利用している ``プログラム'' モードです。) その後 `reset_shell_mode()` を呼ぶとこのモードを復旧します。

`delay_output`( | ms)

  出力に ms ミリ秒の一時停止を入れます。

`doupdate`( | )

  物理スクリーン (physical screen) を更新します。curses ライブラリは、 現在の物理スクリーンの内容と、次の状態として要求されている仮想スクリーン をそれぞれ表す、2 つのデータ構造を保持しています。`doupdate()` は更新を適用し、物理スクリーンを仮想スクリーンに一致させます。

  仮想スクリーンは `addstr()` のような書き込み操作をウィンドウに 行った後に `noutrefresh()` を呼び出して更新することができます。 通常の `refresh()` 呼び出しは、単に `noutrefresh()` を呼んだ後に `doupdate()` を呼ぶだけです; 複数のウィンドウを 更新しなければならない場合、全てのウィンドウに対して `noutrefresh()` を呼び出した後、一度だけ `doupdate()` を呼ぶことで、パフォーマンスを向上させることができ、おそらくスクリーン のちらつきも押さえることができます。

`echo`( | )

  echo モードに入ります。 echo モードでは、各文字入力はスクリーン上に 入力された通りにエコーバックされます。

`endwin`( | )

  ライブラリの非初期化を行い、端末を通常の状態に戻します。

`erasechar`( | )

  ユーザの現在の消去文字 (erase character) 設定を返します。 Unix オペレーティングシステムでは、この値は curses プログラムが 制御している端末の属性であり、curses ライブラリ自体では設定 されません。

`filter`( | )

  `filter()` ルーチンを使う場合、`initscr()` を 呼ぶ前に呼び出さなくてはなりません。この手順のもたらす効果は以下の 通りです: まず二つの関数の呼び出しの間は、LINES は 1 に設定されます; clear、cup、cud、cud1、cuu1、cuu、vpa は無効化されます; home 文字列 は cr の値に設定されます。これにより、カーソルは現在の行に制限される ので、スクリーンの更新も同様に制限されます。 この関数は、スクリーンの他の部分に影響を及ぼさずに文字単位の行編集を 行う場合に利用できます。

`flash`( | )

  スクリーンをフラッシュ(flash) します。すなわち、画面を色反転 (reverse-video) にして、短時間でもとにもどします。人によっては、 `beep()` で生成される可聴な注意音よりも、このような ``可視ベル(visible bell)'' を好みます。

`flushinp`( | )

  全ての入力バッファをフラッシュします。この関数は、ユーザによって すでに入力されているが、まだプログラムによって処理されていない 全ての先行入力文字 (typeahead) を捨て去ります。

`getmouse`( | )

  `getch()` が `KEY_MOUSE` を返してマウスイベントを 通知した後、この関数を呼んで待ち行列 (queue) 上に置かれている マウスイベントを取得しなければなりません。イベントは `(id, x, y, z, bstate)` の 5 要素のタプルで表現されています。 id は複数のデバイスを区別するための ID 値で、 x、 y、z はイベントの座標値です (現在 z は使われていません)。 bstate は整数値で、 その各ビットはイベントのタイプを示す値に設定されています。 この値は以下に示す定数のうち一つまたはそれ以上のビット単位 OR になっています。以下の定数のn は 1 から 4 のボタン番号を 示します: `BUTTONn_PRESSED`, `BUTTONn_RELEASED`, `BUTTONn_CLICKED`, `BUTTONn_DOUBLE_CLICKED`, `BUTTONn_TRIPLE_CLICKED`, `BUTTON_SHIFT`, `BUTTON_CTRL`, `BUTTON_ALT`.

`getsyx`( | )

  仮想スクリーンにおける現在のカーソル位置を y および x の順で返します。 leaveok が真に設定されていれば、 -1、-1 が返されます。

`getwin`( | file)

  以前の `putwin()` 呼び出しでファイルに保存されている、 ウィンドウ関連データを読み出します。次に、このルーチンは そのデータを使って新たなウィンドウを生成し初期化して、 その新規ウィンドウオブジェクトを返します。

`has_colors`( | )

  端末が色表示を行える場合には真を返します。そうでない場合には偽を 返します。

`has_ic`( | )

  端末が文字の挿入／削除機能を持つ場合に真を返します。 この関数は、最近の端末エミュレータがどれもこの機能を持っているのと同じく、 歴史的な理由だけのために含められています。

`has_il`( | )

  端末が行の挿入／削除機能を持つか、領域単位のスクロールによって 機能をシミュレートできる場合に真を返します。 この関数は、最近の端末エミュレータがどれもこの機能を持っているのと同じく、 歴史的な理由だけのために含められています。

`has_key`( | ch)

  キー値 ch をとり、現在の端末タイプがその値のキーを認識できる 場合に真を返します。

`halfdelay`( | tenths)

  半遅延モード、すなわち cbreak モードに似た、ユーザが打鍵した文字 がすぐにプログラムで利用できるようになるモードで使われます。 しかしながら、何も入力されなかった場合、 tenths 十秒後に 例外が送出されます。tenths の値は 1 から 255 の間でなければ なりません。半遅延モードから抜けるには `nocbreak()` を使います。

`init_color`( | color_number, r, g, b)

  色の定義を変更します。変更したい色番号と、その後に 3 つ組みの RGB 値 (赤、緑、青の成分の大きさ) をとります。color_number の値は `0` から `COLORS` の間でなければなりません。 r、g、b の値は `0` から `1000` の 間でなければなりません。 `init_color()` を使うと、 スクリーン上でカラーが使用されている部分は全て新しい設定に 即時変更されます。この関数はほとんどの端末で何も行いません; `can_change_color()` が `1` を返す場合にのみ 動作します。

`init_pair`( | pair_number, fg, bg)

  色ペアの定義を変更します。3 つの引数: 変更したい色ペア、前景色の 色番号、背景色の色番号、をとります。pair_number は `1` から `COLOR_PAIRS -1` の間でなければなりません (`0` 色ペアは黒色背景に白色前景となるように設定されており、 変更することができません) 。fg および bg 引数は `0` と `COLORS` の間でなければなりません。 色ペアが以前に初期化されていれば、スクリーンを更新して、指定 された色ペアの部分を新たな設定に変更します。

`initscr`( | )

  ライブラリを初期化します。スクリーン全体をあらわす `WindowObject` を返します。注意: 端末のオープン時にエラーが発生した場合、curses ライブラリ によってインタープリタが終了される場合があります。

`isendwin`( | )

  `endwin()` がすでに呼び出されている (すなわち、curses ライブラリ が非初期化されてしまっている) 場合に真を返します。

`keyname`( | k)

  k に番号付けされているキーの名前を返します。印字可能な ASCII 文字を生成するキーの名前はそのキーの文字自体になります。 コントロールキーと組み合わせたキーの名前は、キャレットの後に対応する ASCII 文字が続く 2 文字の文字列になります。Alt キーと組み合わせた キー (128-255) の名前は、先頭に `M-' が付き、その後に対応する ASCII 文字が続く文字列になります。

`killchar`( | )

  ユーザの現在の行削除文字を返します。 Unix オペレーティングシステムでは、この値は curses プログラムが 制御している端末の属性であり、curses ライブラリ自体では設定 されません。

`longname`( | )

  現在の端末について記述している terminfo の長形式 name フィールドが 入った文字列を返します。verbose 形式記述の最大長は 128 文字です。 この値は `initscr()` 呼び出しの後でのみ定義されています。

`meta`( | yes)

  yes が 1 の場合、8 ビット文字を入力として許します。yes が 0 の場合、 7 ビット文字だけを許します。

`mouseinterval`( | interval)

  ボタンが押されてから離されるまでの時間をマウスクリック一回として認識 する最大の時間間隔を設定します。以前の内部設定値を返します。 標準の値は 200 ミリ秒、または 5 分の 1 秒です。

`mousemask`( | mousemask)

  報告すべきマウスイベントを設定し、`(availmask, oldmask)` の組からなるタプルを返します。 availmask はどの指定されたマウスイベントのどれが報告されるかを 示します; どのイベント指定も完全に失敗した場合には 0 が返ります。 oldmask は与えられたウィンドウの以前のマウスイベントマスク です。この関数が呼ばれない限り、マウスイベントは何も報告されません。

`napms`( | ms)

  ms ミリ秒スリープします。

`newpad`( | nlines, ncols)

  与えられた行とカラム数を持つパッド (pad) データ構造を生成し、その ポインタを返します。パッドはウィンドウオブジェクトとして返されます。

  パッドはウィンドウと同じようなものですが、スクリーンのサイズによる 制限をうけず、スクリーンの特定の部分に関連付けられていなくても かまいません。大きなウィンドウが必要であり、スクリーンにはその ウィンドウの一部しか一度に表示しない場合に使えます。 (スクロールや入力エコーなどによる) パッドに対する再描画は起こりません。 パッドに対する `refresh()` および `noutrefresh()` メソッド は、パッド中の表示する部分と表示するために利用するスクリーン上の位置を 指定する 6 つの引数が必要です。これらの引数は pminrow、 pmincol、 sminrow、 smincol、 smaxrow、smaxcol です; p で始まる引数はパッド中の表示領域の左上位置で、s で始まる引数は パッド領域を表示するスクリーン上のクリップ矩形を指定します。

`newwin`( | [nlines, ncols,] begin_y, begin_x)

  左上の角が `(begin_y, begin_x)` で、高さ／幅が nlines/ncols の新規ウィンドウを返します。

  標準では、ウィンドウは指定された位置からスクリーンの右下まで 広がります。

`nl`( | )

  newlime モードに入ります。このモードはリターンキーを入力中の改行 として変換し、出力時に改行文字を復帰 (return) と改行 (line-feed) に変換 します。newline モードは初期化時にはオンになっています。

`nocbreak`( | )

  cbreak モードから離れます。行バッファリングを行う通常の ``cooked'' モードに戻ります。

`noecho`( | )

  echo モードから離れます。入力のエコーバックはオフにされます。

`nonl`( | )

  newline モードから離れます。入力時のリターンキーから改行への変換、 および出力時の改行から復帰／改行への低レベル変換を無効化します (ただし、`addch('\n')` の振る舞いは変更せず、仮想スクリーン 上では常に復帰と改行に等しくなります)。変換をオフにすることで、 curses は水平方向の動きを少しだけ高速化できることがあります; また、入力中のリターンキーの検出ができるようになります。

`noqiflush`( | )

  noquiflush ルーチンを使うと、通常行われている INTR、QUIT、および SUSP 文字による入力および出力キューのフラッシュが行われなく なります。シグナルハンドラが終了した際、割り込みが発生しなかった かのように出力を続たい場合、ハンドラ中で `noqiflush()` を呼び出すことができます。

`noraw`( | )

  raw モードから離れます。行バッファリングを行う通常の ``cooked'' モードに戻ります。

`pair_content`( | pair_number)

  要求された色ペア中の色を含む `(fg, bg)` からなる タプルを返します。pair_number は `0` から ``COLOR_PAIRS` - 1` の間でなければなりません。

`pair_number`( | attr)

  attr に対する色ペアセットの番号を返します。`color_pair()` はこの関数の逆に相当します。

`putp`( | string)

  `tputs(str, 1, putchar)` と等価です; 現在の端末における、 指定された terminfo 機能の値を出力します。putp の出力は常に標準 出力に送られるので注意して下さい。

`qiflush`( | [flag])

  flag が偽なら、`noqiflush()` を呼ぶのとと同じ効果です。 flag が真か、引数が与えられていない場合、制御文字が読み出された 最にキューはフラッシュされます。

`raw`( | )

  raw モードに入ります。raw モードでは、通常の行バッファリングと 割り込み (interrupt)、終了 (quit)、一時停止 (suspend)、および フロー制御キーはオフになります; 文字は curses 入力関数に一文字 づつ渡されます。

`reset_prog_mode`( | )

  端末を ``program'' モードに復旧し、予め `def_prog_mode()` で保存した内容に戻します。

`reset_shell_mode`( | )

  端末を ``shell'' モードに復旧し、予め `def_shell_mode()` で保存した内容に戻します。

`setsyx`( | y, x)

  仮想スクリーンカーソルを y、x に設定します。 y および x が共に -1 の場合、leaveok が設定されます。

`setupterm`( | [termstr, fd])

  端末を初期化します。termstr は文字列で、端末の名前を与えます; 省略された場合、TERM 環境変数の値が使われます。fd は 初期化シーケンスが送られる先のファイル記述子です; fd を与えない場合、`sys.stdout` のファイル記述子が使われます。

`start_color`( | )

  プログラマがカラーを利用したい場合で、かつ他の何らかのカラー操作 ルーチンを呼び出す前に呼び出さなくてはなりません。 この関数は `initscr()` を呼んだ直後に呼ぶようにしておくと よいでしょう。

  `start_color()` は 8 つの基本色 (黒、赤、緑、黄、青、マゼンタ、 シアン、および白) と、色数の最大値と端末がサポートする色ペアの最大数 が入っている、`curses` モジュールにおける二つのグローバル変数、 `COLORS` および `COLOR_PAIRS` を初期化します。 この関数はまた、色設定を端末のスイッチが入れられたときの状態に 戻します。

`termattrs`( | )

  端末がサポートする全てのビデオ属性を論理和した値を返します。 この情報は、curses プログラムがスクリーンの見え方を 完全に制御する必要がある場合に便利です。

`termname`( | )

  14 文字以下になるように切り詰められた環境変数 TERM の値を返します。

`tigetflag`( | capname)

  terminfo 機能名 capname に対応する機能値をブール値で返します。 capname がブール値で表される機能値でない場合 `-1` が返され、機能がキャンセルされているか、端末記述上に見つからない 場合には `0` を返します。

`tigetnum`( | capname)

  terminfo 機能名 capname に対応する機能値を数値で返します。 capname が数値で表される機能値でない場合 `-2` が返され、機能がキャンセルされているか、端末記述上に見つからない 場合には `-1` を返します。

`tigetstr`( | capname)

  terminfo 機能名 capname に対応する機能値を文字列値で返します。 capname が文字列値で表される機能値でない場合や、 機能がキャンセルされているか、端末記述上に見つからない 場合には `None` を返します。

`tparm`( | str[,...])

  str を与えられたパラメタを使って文字列にインスタンス化します。 str は terminfo データベースから得られたパラメタを持つ文字列 でなければなりません。例えば、`tparm(tigetstr("cup"), 5, 3)` は `'\033[6;4H'` のようになります。厳密には端末の形式に よって異なる結果となります。

`typeahead`( | fd)

  先読みチェックに使うためのファイル記述子 fd を指定します。 fd が `-1` の場合、先読みチェックは行われません。

  curses ライブラリはスクリーンを更新する間、先読み文字列を定期的に 検索することで ``行はみ出し最適化 (line-breakout optimization)'' を行います。入力が得られ、かつ入力は端末からのものである場合、現在 行おうとしている更新は refresh や doupdate を再度呼び出すまで 先送りにします。この関数は異なるファイル記述子で先読みチェックを 行うように指定することができます。

`unctrl`( | ch)

  ch の印字可能な表現を文字列で返します。制御文字は例えば `^C` のようにキャレットに続く文字として表示 されます。印字可能文字はそのままです。

`ungetch`( | ch)

  ch をプッシュして、 `getch()` を次に呼び出したときに 返されるようにします。注意: `getch()` を呼び出すまでは ch は一つしかプッシュできません。

`ungetmouse`( | id, x, y, z, bstate)

  与えられた状態データが関連付けられた `KEY_MOUSE` イベントを 入力キューにプッシュします。

`use_env`( | flag)

  この関数を使う場合、`initscr()` または newterm を呼ぶ前に 呼び出さなくてはなりません。flag が偽の場合、環境変数 LINES および COLUMNS の値 (これらは標準の設定で 使われます) の値が設定されていたり、curses がウィンドウ内で 動作して (この場合 LINES や COLUMNS が設定 されていないとウィンドウのサイズを使います) いても、terminfo データベースに指定された lines および columns の値を使います。