curses --- 文字セル表示のターミナル処理

ソースコード: Lib/curses

---

curses モジュールは、移植可能な高度な端末処理の事実上の標準である curses ライブラリへのインターフェースを提供します。

curses が最も広く用いられているのは Unix 環境ですが、Windows、DOS で利用できるバージョンもあり、おそらく他のシステムで利用できるバージョンもあります。この拡張モジュールは Linux および BSD 系の Unixで動作するオープンソースの curses ライブラリである ncurses の API に合致するように設計されています。

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォーム をサポートしません。

これは optional module です。 お使いの CPython に含まれていない場合は、配布元 (Python を提供した組織など) のドキュメントを確認してください。 配布元の方は オプションのモジュールの要件 を参照してください。

利用可能な環境: Unix.

注釈

Whenever the documentation mentions a character it can be specified as an integer, a one-character Unicode string or a one-byte byte string. An integer is the code of a single encoded byte, optionally combined with attributes and a color pair, as returned by window.inch(). Methods that write to a window accept also a character cell: a Unicode string of a spacing character followed by combining characters, or a complexchar.

Whenever the documentation mentions a character string it can be specified as a Unicode string or a byte string. Methods that write to a window accept also a complexstr.

注釈

Whether curses may be used from several threads depends on the underlying library and how it was built. In many implementations, including the default build of ncurses, the screen state is shared and not thread-safe; since the blocking and refresh methods (such as getch() and refresh()) release the GIL, unsynchronized use from several threads can then crash the interpreter. Serialize the calls, or wrap them in window.use() and screen.use().

参考

curses.ascii モジュール

ロケール設定に関わらず ASCII 文字を扱うためのユーティリティ。

curses.panel モジュール

curses ウィンドウにデプス機能を追加するパネルスタック拡張。

curses.textpad モジュール

Emacs ライクなキーバインディングをサポートする編集可能な curses 用テキストウィジェット。

Python で Curses プログラミング

Andrew Kuchling および Eric Raymond によって書かれた、curses を Python で使うためのチュートリアルです。

関数

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

exception curses.error

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

注釈

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

curses モジュールは以下の関数を定義します:

Initialization and termination

curses.initscr()

ライブラリを初期化します。スクリーン全体をあらわす ウィンドウ オブジェクトを返します。

この関数より先に setupterm() を呼び出す際の注意事項は、その関数の説明を参照してください。

注釈

端末のオープン時にエラーが発生した場合、curses ライブラリによってインタープリタが終了される場合があります。

curses.endwin()

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

curses.isendwin()

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

curses.newterm(type=None, fd=None, infd=None, /)

Initialize a new terminal in addition to the one initialized by initscr(), and return a screen for it. This allows a program to drive more than one terminal.

type is the terminal name, as in setupterm(); if None, the value of the TERM environment variable is used. fd and infd are the output and input files for the terminal: either a file object or a file descriptor. They default to sys.stdout and sys.stdin.

The new screen becomes the current one. Use set_term() to switch between screens.

この関数より先に setupterm() を呼び出す際の注意事項は、その関数の説明を参照してください。

Added in version 3.16.

curses.new_prescr()

Return a new screen that can be used to call functions that affect global state before initscr() or newterm() is called.

Availability: if the underlying curses library provides new_prescr().

Added in version 3.16.

curses.set_term(screen, /)

Make screen, a screen returned by newterm(), the current terminal, and return the previously current screen. Returns None if the previous screen was the one created by initscr(). Raises error if screen has no terminal, as is the case for a screen returned by new_prescr().

Added in version 3.16.

curses.wrapper(func, /, *args, **kwargs)

curses を初期化し、呼び出し可能なオブジェクト func (その他の curses を使用するアプリケーション) を呼び出します。アプリケーションが例外を送出した場合、この関数は端末を例外を再送出する前に正常な状態に戻し、トレースバックを作成します。その後、呼び出し可能オブジェクト func には、第一引数としてメインウィンドウ 'stdscr' が、続いて wrapper() に渡されたその他の引数が渡されます。func を呼び出す前、wrapper() は cbreak モードをオンに、エコーをオフに、端末キーパッドを有効にし、端末が色表示をサポートしている場合は色を初期化します。終了時 (通常終了、例外による終了のどちらでも)、cooked モードに戻し、エコーをオンにし、端末キーパッドを無効にします。

Terminal mode control

curses.def_prog_mode()

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

curses.def_shell_mode()

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

curses.reset_prog_mode()

端末を "program" モードに復旧し、あらかじめ def_prog_mode() で保存した内容に戻します。

curses.reset_shell_mode()

端末を "shell" モードに復旧し、あらかじめ def_shell_mode() で保存した内容に戻します。

curses.savetty()

resetty() で使用される、バッファ内の端末モードの現在の状態を保存します。

curses.resetty()

端末モードの状態を最後に savetty() を呼び出した時の状態に戻します。

curses.curs_set(visibility)

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

curses.getsyx()

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

curses.setsyx(y, x)

仮想スクリーンのカーソルを y, x に設定します。y および x がどちらも -1 の場合、 leaveok() が に True に設定されます。

curses.doupdate()

物理スクリーンを更新します。 curses ライブラリは、現在の物理スクリーンの内容を表すものと、次に表示したい状態を表す仮想スクリーンという 2 つのデータ構造を保持しています。 doupdate() 関数は、仮想スクリーンに一致するように物理スクリーンを更新します。

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

Input options

curses.cbreak()

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

curses.nocbreak()

cbreak モードを終了します。行バッファリングを行う通常の "cooked" モードに戻ります。

curses.echo()

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

curses.noecho()

echo モードを終了します。入力のエコーバックはオフにされます。

curses.raw()

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

curses.noraw()

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

curses.halfdelay(tenths)

半遅延モードに使用します。 このモードは、ユーザが入力した文字をプログラムがすぐに利用できる点では cbreak モードと同様です。 ただし、tenths × 0.1 秒間ブロックした後、何も入力されていなければ、getch() は -1 を返し、getkey() と get_wch() は curses.error を送出します。 tenths の値は 1 から 255 の範囲でなければなりません。 半遅延モードから抜けるには nocbreak() を使用してください。

curses.meta(flag)

flag が True の場合、8 ビット文字の入力を許可します。flag が False の場合、7 ビット文字だけを許可します。

curses.nl(flag=True)

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

flag が False の場合、nonl() の呼び出しと同じ効果があります。

curses.nonl()

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

curses.intrflush(flag)

flag が True の場合、割り込みキー (interrupt、break、quit) を押すと端末ドライバのキュー内の出力がすべてフラッシュされます。 flag が False の場合、フラッシュは行われません。

curses.qiflush([flag])

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

curses.noqiflush()

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

curses.typeahead(fd)

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

The curses library does "line-breakout optimization" by looking for typeahead periodically while updating the screen. If input is found, and it is coming from a tty, the current update is postponed until refresh() or doupdate() is called again, allowing faster response to commands typed in advance. This function allows specifying a different file descriptor for typeahead checking.

curses.is_cbreak()

Return True if cbreak mode (see cbreak()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

Added in version 3.16.

curses.is_echo()

Return True if echo mode (see echo()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

Added in version 3.16.

curses.is_nl()

Return True if nl mode (see nl()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

Added in version 3.16.

curses.is_raw()

Return True if raw mode (see raw()) is enabled, False otherwise. Availability: ncurses 6.5 or later.

Added in version 3.16.

Keyboard input

curses.ungetch(ch)

Push ch so the next getch() or get_wch() will return it.

ch may be an integer (a key code or the code of an encoded byte), a byte, or a string of length 1. A one-character string is pushed like unget_wch(); on a narrow build it must encode to a single byte.

注釈

getch() を呼び出すまでは ch は一つしかプッシュできません。

バージョン 3.16 で変更: A one-character string argument is no longer required to encode to a single byte, except on a narrow build.

curses.unget_wch(ch)

ch をプッシュし、次に get_wch() を呼び出した時にその値が返るようにします。

ch には、整数 (キーコードではなく文字コード) または長さ 1 の文字列を指定できます。

注釈

get_wch() を呼び出すまでは ch は一つしかプッシュできません。

Added in version 3.3.

バージョン 3.16 で変更: Also available on a narrow build, where ch must encode to a single byte (an 8-bit locale).

curses.flushinp()

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

curses.has_key(ch)

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

curses.keyname(k)

番号 k のキーの名前を bytes オブジェクトで返します。 印字可能な ASCII 文字を生成するキーの名前はそのキーの文字自体になります。 コントロールキーと組み合わせたキーの名前は、キャレット(b'^')の後に対応する ASCII 文字が続く 2 バイトの bytes オブジェクトになります。 Alt キーと組み合わせたキー (128--255) の名前は、先頭に b'M-' が付き、その後に対応する ASCII 文字の名前が続く bytes オブジェクトになります。

k が負の場合は ValueError を送出します。

curses.define_key(definition, keycode)

Define an escape sequence definition, a string, as a key that generates the key code keycode, so that curses interprets it like one of the keys predefined in the terminal database.

If definition is None, any existing binding for keycode is removed. If keycode is zero or negative, any existing binding for definition is removed.

Added in version 3.16.

curses.key_defined(definition)

Return the key code bound to the escape sequence definition, a string, 0 if no key code is bound to it, or -1 if definition is a prefix of a longer bound sequence (and so is ambiguous).

Added in version 3.16.

curses.keyok(keycode, enable)

Enable (if enable is true) or disable (otherwise) interpretation of the key code keycode. Unlike window.keypad(), this affects a single key code rather than all of them.

Added in version 3.16.

Mouse

curses.getmouse()

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

バージョン 3.10 で変更: 基盤となる curses ライブラリが BUTTON5_* 定数を提供する場合に、それらが公開されるようになりました。

curses.ungetmouse(id, x, y, z, bstate)

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

curses.mousemask(mousemask)

通知するマウスイベントを設定し、タプル (availmask, oldmask) を返します。 availmask は、指定したマウスイベントのうち通知可能なものを示し、完全に失敗した場合は 0 になります。 oldmask は以前のマウスイベントマスクの値です。 この関数を一度も呼び出さない場合、マウスイベントは一切通知されません。

curses.mouseinterval(interval)

ボタンを押してから離すまでのイベントをクリックと認識する最大時間をミリ秒で設定し、以前の時間間隔を返します。 デフォルト値は 166 ミリ秒、すなわち 6 分の 1 秒です。 時間間隔を変更せずに取得するには、負の interval を使用してください。

curses.has_mouse()

Return True if the mouse driver has been successfully initialized.

Availability: if the underlying curses library provides has_mouse().

Added in version 3.16.

色

curses.start_color()

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

start_color() は 8 つの基本色 (黒、赤、緑、黄、青、マゼンタ、シアン、白) と、curses モジュールの 2 つのグローバル変数 COLORS および COLOR_PAIRS を初期化します。 これらの変数には、端末がサポートできる色と色ペアの最大数が格納されます。 また、端末の色を端末の電源投入直後の値に戻します。

curses.has_colors()

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

curses.has_extended_color_support()

モジュールが拡張カラーをサポートしている場合は True を、そうでない場合は False を返します。 拡張カラーのサポートにより、16 色を超える色をサポートする端末 (例えば xterm-256color) で 256 個を超える色ペアを使用できます。

拡張カラーのサポートには ncurses バージョン 6.1 以降が必要です。

Added in version 3.10.

curses.can_change_color()

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

curses.init_color(color_number, r, g, b)

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

curses.color_content(color_number)

色 color_number の赤、緑、青 (RGB) 成分の強度を返します。 color_number は 0 から COLORS - 1 の範囲でなければなりません。 指定した色の R、G、B の値を含む 3 要素のタプルを返します。 各値は 0 (成分なし) から 1000 (成分の最大量) の範囲です。 その色がサポートされていない場合は例外を送出します。

curses.init_pair(pair_number, fg, bg)

色ペアの定義を変更します。 変更する色ペアの番号、前景色の番号、背景色の番号という 3 つの引数を取ります。 pair_number の値は 1 から COLOR_PAIRS - 1 の範囲でなければなりません (色ペア 0 は use_default_colors() と assume_default_colors() でのみ変更できます)。 引数 fg と bg の値は 0 から COLORS - 1 の範囲か、use_default_colors() または assume_default_colors() を呼び出した後であれば -1 でなければなりません。 色ペアが以前に初期化されていた場合、スクリーンが更新され、その色ペアを使用しているすべての箇所が新しい定義に変わります。

curses.pair_content(pair_number)

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

curses.color_pair(pair_number)

Return the attribute value for displaying text in the specified color pair. Only color pairs that fit in the color-pair field of the returned value can be represented (usually the first 256); a larger pair_number raises OverflowError rather than being silently masked to a different pair. Use color_set() or attr_set() to display higher pairs. This attribute value can be combined with A_STANDOUT, A_REVERSE, and the other A_* attributes. pair_number() is the counterpart to this function.

curses.pair_number(attr)

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

curses.use_default_colors()

assume_default_colors(-1, -1) と等価です。

curses.assume_default_colors(fg, bg, /)

この機能をサポートする端末で、色のデフォルト値を使用できるようにします。 アプリケーションで透過表示をサポートするには、この関数を使用してください。

• 端末のデフォルトの前景色と背景色を色番号 -1 に割り当てます。 したがって、init_pair(x, COLOR_RED, -1) はペア x をデフォルトの背景色に赤の前景色として初期化し、init_pair(x, -1, COLOR_BLUE) はペア x を青の背景色にデフォルトの前景色として初期化します。

• 色ペア 0 の定義を (fg, bg) に変更します。

これは ncurses の拡張機能です。

Added in version 3.14.

curses.alloc_pair(fg, bg)

Allocate a color pair for foreground color fg and background color bg, and return its number. If a color pair for the same combination of colors already exists, return its number. Otherwise allocate a new color pair and return its number.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

Added in version 3.16.

curses.free_pair(pair_number)

Free the color pair pair_number, which must have been allocated by alloc_pair(). The pair must not be in use.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

Added in version 3.16.

curses.find_pair(fg, bg)

Return the number of a color pair for foreground color fg and background color bg, or -1 if no color pair for this combination of colors has been allocated.

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

Added in version 3.16.

curses.reset_color_pairs()

Discard all color-pair definitions, releasing the color pairs allocated by init_pair() and alloc_pair().

This function is only available if Python was built against a wide-character version of the underlying curses library with extended-color support (see has_extended_color_support()).

Added in version 3.16.

Windows and pads

curses.newwin(nlines, ncols)

curses.newwin(nlines, ncols, begin_y, begin_x)

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

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

curses.newpad(nlines, ncols)

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

パッドはウィンドウに似ていますが、スクリーンの大きさによる制限がなく、スクリーンの特定の部分に関連付けられるとは限りません。 大きなウィンドウが必要で、一度にスクリーンに表示するのはその一部だけという場合にパッドを使用できます。 パッドでは、スクロールや入力のエコーバックなどによる自動更新は行われません。 パッドの refresh() と noutrefresh() メソッドには、表示するパッドの部分とスクリーン上の表示位置を指定する 6 つの引数が必要です。 これらの引数は pminrow、pmincol、sminrow、smincol、smaxrow、smaxcol です。 p で始まる引数は表示するパッド領域の左上隅を示し、s で始まる引数はパッド領域を表示するスクリーン上の切り取り矩形を定義します。

Soft labels

The following functions manage soft-label keys, a row of labels displayed along the bottom line of the screen, typically used to label a row of function keys. slk_init() must be called before initscr() or newterm(); it takes one screen line away from the standard window for the labels.

curses.slk_init(fmt=0)

Reserve a screen line for the soft labels and choose their layout. fmt selects the arrangement: 0 for 3-2-3 (eight labels), 1 for 4-4 (eight labels). Where the underlying curses library supports them, 2 gives 4-4-4 (twelve labels) and 3 gives 4-4-4 with an index line.

Must be called before initscr() or newterm(), and affects only the screen created next.

Added in version 3.16.

curses.slk_set(labnum, label, justify)

Set the text of soft label number labnum, in the range 1 through 8 (or 12 in a twelve-label layout). justify controls how label is placed within the label: 0 for left, 1 for centered, 2 for right.

Added in version 3.16.

curses.slk_label(labnum)

Return the current text of soft label number labnum, justified as it was set, or an empty string if it has no label.

Added in version 3.16.

curses.slk_refresh()

Update the soft labels on the physical screen, like refresh() for a window.

Added in version 3.16.

curses.slk_noutrefresh()

Update the soft labels on the virtual screen, like window.noutrefresh(). Use it together with doupdate() to batch screen updates.

Added in version 3.16.

curses.slk_clear()

Remove the soft labels from the screen.

Added in version 3.16.

curses.slk_restore()

Restore the soft labels to the screen after a slk_clear().

Added in version 3.16.

curses.slk_touch()

Force all the soft labels to be redrawn by the next slk_refresh() or slk_noutrefresh().

Added in version 3.16.

curses.slk_attron(attr)

curses.slk_attroff(attr)

curses.slk_attrset(attr)

Add, remove, or set the attributes used to display the soft labels, given as packed A_* attributes.

Added in version 3.16.

curses.slk_attr()

Return the current attributes of the soft labels as packed A_* attributes. Availability depends on the underlying curses library.

Added in version 3.16.

curses.slk_attr_on(attr)

curses.slk_attr_off(attr)

Turn the given attributes on or off without affecting any others. Like the attr_* window methods, these work with the WA_* attributes rather than packed A_* attributes.

Added in version 3.16.

curses.slk_attr_set(attr, pair=0)

Set the attributes and color pair of the soft labels. attr is given as WA_* attributes and pair as a color pair number.

Added in version 3.16.

curses.slk_color(pair)

Set the color pair of the soft labels to color pair number pair.

Added in version 3.16.

Saving and restoring

curses.getwin(file)

以前の window.putwin() 呼び出しでファイルに保存したウィンドウ関連のデータを読み込みます。 続いて、そのデータを使用して新しいウィンドウを作成して初期化し、新しいウィンドウオブジェクトを返します。 file 引数は、バイナリモードで読み込み用に開いたファイルオブジェクトでなければなりません。

curses.scr_dump(filename)

Write the current contents of the virtual screen to filename, which may be a string or a path-like object. The file can later be read by scr_restore(), scr_init() or scr_set(). This is the whole-screen counterpart of window.putwin().

Added in version 3.16.

curses.scr_restore(filename)

Set the virtual screen to the contents of filename, which must have been written by scr_dump(). The next call to doupdate() or window.refresh() restores the screen to those contents.

Added in version 3.16.

curses.scr_init(filename)

Initialize the assumed contents of the terminal from filename, which must have been written by scr_dump(). Use it when the terminal already displays those contents, for example after another program has drawn the screen, so that curses does not redraw what is already there.

Added in version 3.16.

curses.scr_set(filename)

Use filename, which must have been written by scr_dump(), as both the virtual screen and the assumed terminal contents. This combines the effects of scr_restore() and scr_init().

Added in version 3.16.

Querying the terminal

curses.baudrate()

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

curses.erasechar()

Return the user's current erase character as a raw byte, a bytes object of length 1. See also erasewchar().

curses.erasewchar()

Return the user's current erase character as a one-character str. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

Added in version 3.16.

curses.killchar()

Return the user's current line kill character as a raw byte, a bytes object of length 1. See also killwchar().

curses.killwchar()

Return the user's current line kill character as a one-character str. Under Unix operating systems this is a property of the controlling tty of the curses program, and is not set by the curses library itself.

Added in version 3.16.

curses.termname()

Return the name of the terminal in use, as a bytes object. This is the name passed to newterm() or setupterm(), or the value of the TERM environment variable if none was given. Some curses libraries truncate it to 14 characters.

curses.longname()

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

curses.termattrs()

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

curses.term_attrs()

Like termattrs(), but return the attributes as WA_* values rather than A_* values.

Added in version 3.16.

curses.has_ic()

端末が文字の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っており、この関数は歴史的な理由のためだけに存在しています。

curses.has_il()

端末が行の挿入/削除機能を持つ場合に True を返します。最近の端末エミュレータはどれもこの機能を持っていて、この関数は歴史的な理由のためだけに存在しています。

Bell and screen flash

curses.beep()

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

curses.flash()

スクリーンを点滅します。すなわち、画面を色反転して、短時間でもとにもどします。人によっては、beep() で生成される注意音よりも、このような "目に見えるベル" を好みます。

Terminal resizing

curses.resizeterm(nlines, ncols)

現在の標準ウィンドウのサイズを指定された寸法に変更し、curses ライブラリが使用する、その他のウィンドウサイズを記憶しているデータ (特に SIGWINCH ハンドラ) を調整します。

curses.resize_term(nlines, ncols)

resizeterm() で使用されるバックエンド関数で、ウィンドウサイズを変更する時、resize_term() は拡張された領域を埋めます。呼び出したアプリケーションはそれらの領域を適切なデータで埋めなくてはなりません。resize_term() 関数はすべてのウィンドウのサイズ変更を試みます。ただし、パッド呼び出しの慣例により、アプリケーションとの追加のやり取りを行わないサイズ変更は行えません。

curses.is_term_resized(nlines, ncols)

resize_term() を呼び出した場合にウィンドウ構造が変更されるなら True を、そうでなければ False を返します。

curses.update_lines_cols()

モジュール変数 LINES と COLS を更新します。 手動によるスクリーンのサイズ変更を検出する際に役立ちます。

Added in version 3.5.

Terminfo database

curses.setupterm(term=None, fd=-1)

端末を初期化します。term は端末名となる文字列または None です。省略または None の場合、環境変数 TERM の値が使用されます。fd は送信される初期化シーケンスへのファイル記述子です。指定されないまたは -1 の場合、sys.stdout のファイル記述子が使用されます。

端末が見つからないか、その terminfo データベースのエントリーを読み込めない場合、curses.error を送出します。 端末がすでに初期化されている場合、この関数は何もしません。

注釈

Calling initscr() or newterm() after setupterm() leaks the terminal that setupterm() allocated: the curses library keeps only a single current terminal and does not free the previously allocated one.

curses.tigetflag(capname)

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

先に setupterm() (または initscr()) を呼び出す必要があります。

curses.tigetnum(capname)

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

先に setupterm() (または initscr()) を呼び出す必要があります。

curses.tigetstr(capname)

terminfo の機能名 capname に対応する文字列機能の値を bytes オブジェクトとして返します。 capname が terminfo の「文字列機能」でない場合や、端末の記述で取り消されているか存在しない場合は、None を返します。

先に setupterm() (または initscr()) を呼び出す必要があります。

curses.tparm(str[, ...])

bytes オブジェクト str に指定したパラメータを適用します。 str は terminfo データベースから取得した、パラメータを含むバイト文字列でなければなりません。 例えば、tparm(tigetstr("cup"), 5, 3) は b'\033[6;4H' を返すことがありますが、正確な結果は端末の種類によって異なります。 整数のパラメータを最大 9 個指定できます。

先に setupterm() (または initscr()) を呼び出す必要があります。

curses.putp(str)

tputs(str, 1, putchar) と等価です。 現在の端末に対し、指定した terminfo 機能の値である bytes オブジェクトを出力します。 putp() の出力先は常に標準出力であることに注意してください。

先に setupterm() (または initscr()) を呼び出す必要があります。

Utilities

curses.unctrl(ch)

Return a bytes object which is a printable representation of the character ch; any attributes and color pair are ignored. Control characters are represented as a caret followed by a character, for example as b'^C'. Printing characters are left as they are. The representation of other characters is defined by the underlying curses library.

ch must fit in a single byte; use wunctrl() for other characters.

curses.wunctrl(ch)

Return a string which is a printable representation of the character ch; any attributes and color pair are ignored. ASCII control characters are represented as a caret followed by a character, for example as '^C'. Printing characters, including non-ASCII characters printable in the locale, are left as they are. The representation of other characters is defined by the underlying curses library.

Added in version 3.16.

curses.filter()

The filter() routine, if used, must be called before initscr() or newterm() is called, and affects every screen created afterwards. The effect is that, during the initialization, LINES is set to 1; the capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home string is set to the value of cr. The effect is that the cursor is confined to the current line, and so are screen updates. This may be used for enabling character-at-a-time line editing without touching the rest of the screen.

curses.nofilter()

Undo the effect of a previous filter() call. Like filter(), it must be called before initscr() (or newterm()) so that the next initialization uses the full screen again.

Availability: if the underlying curses library provides nofilter().

Added in version 3.16.

curses.use_env(flag)

If used, this function should be called before initscr() or newterm() are called, and affects every screen created afterwards. When flag is False, the values of lines and columns specified in the terminfo database will be used, even if environment variables LINES and COLUMNS (used by default) are set, or if curses is running in a window (in which case default behavior would be to use the window size if LINES and COLUMNS are not set).

curses.get_escdelay()

set_escdelay() で設定した値を取得します。

Added in version 3.9.

curses.set_escdelay(ms)

キーボードで入力した単独のエスケープ文字と、カーソルキーやファンクションキーが送信するエスケープシーケンスを区別するため、エスケープ文字を読み込んだ後に待機する時間をミリ秒で設定します。

Depending on the curses library, the setting may apply to all screens, not only to the current one.

Added in version 3.9.

curses.get_tabsize()

set_tabsize() で設定した値を取得します。

Added in version 3.9.

curses.set_tabsize(size)

curses ライブラリがウィンドウにタブ文字を追加する際、タブ文字を空白に変換するために使用する桁数を設定します。

Depending on the curses library, the setting may apply to all screens, not only to the current one, and creating a screen may reset it.

Added in version 3.9.

curses.napms(ms)

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

curses.delay_output(ms)

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

ウィンドウオブジェクト

class curses.window

上記の initscr() や newwin() が返すウィンドウは、以下のメソッドと属性を持ちます:

Adding and inserting text

window.addch(ch[, attr])

window.addch(y, x, ch[, attr])

(y, x) にある文字 ch を属性 attr で描画します。このときその場所に以前描画された文字は上書きされます。デフォルトでは、文字の位置および属性はウィンドウオブジェクトにおける現在の設定になります。

ch may be a single character, optionally followed by combining characters, that together occupy one character cell.

注釈

ウィンドウ、サブウィンドウ、パッドの外側に書き込むと curses.error が送出されます。 ウィンドウ、サブウィンドウ、パッドの右下隅に書き込もうとすると、文字を表示した後に例外が送出されます。

バージョン 3.16 で変更: A character may now be given as a string of a base character followed by combining characters, instead of only a single character, or as a complexchar cell.

window.addstr(str[, attr])

window.addstr(y, x, str[, attr])

(y, x) に文字列 str を属性 attr で描画します。以前ディスプレイにあった内容はすべて上書きされます。

str may also be a complexstr, in which case each cell carries its own attributes and color pair, so attr must not be given. A complexstr obtained from in_wchstr() is written back unchanged.

注釈

• ウィンドウ、サブウィンドウ、パッドの外側に書き込むと curses.error が送出されます。 ウィンドウ、サブウィンドウ、パッドの右下隅に書き込もうとすると、文字列を表示した後に例外が送出されます。

• この Python モジュールのバックエンドである ncurses のバグにより、ウィンドウのサイズ変更時にセグメンテーション違反が発生することがありました。 このバグは ncurses-6.1-20190511 で修正されました。 それ以前の ncurses を使用せざるを得ない場合は、改行を含む str で addstr() を呼び出さず、代わりに各行に対して個別に addstr() を呼び出すことで回避できます。

バージョン 3.16 で変更: str may now also be a complexstr, as described above.

window.addnstr(str, n[, attr])

window.addnstr(y, x, str, n[, attr])

文字列 str から最大で n 文字を (y, x) に属性 attr で描画します。以前ディスプレイにあった内容はすべて上書きされます。

バージョン 3.16 で変更: str may now also be a complexstr; see addstr().

window.echochar(ch[, attr])

属性 attr を持つ文字 ch を追加し、すぐにウィンドウの refresh() を呼び出します。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

window.insch(ch[, attr])

window.insch(y, x, ch[, attr])

カーソルの下、または指定した (y, x) の位置の文字の前に、属性 attr の文字 ch を挿入します。 カーソルの右側の文字はすべて 1 文字分右に移動し、行の右端の文字は失われます。 カーソル位置は変わりません (y、x が指定されていれば、その位置に移動した後での位置です)。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

window.insstr(str[, attr])

window.insstr(y, x, str[, attr])

キャラクタ文字列を (行に収まるだけ) カーソルより前に挿入します。カーソルの右側にある文字はすべて右にシフトし、行の右端の文字は失われます。カーソル位置は (y, x が指定されていた場合はそこに移動しますが、その後は) 変化しません。

str may also be a complexstr, in which case each cell carries its own attributes and color pair, so attr must not be given.

バージョン 3.16 で変更: str may now also be a complexstr, as described above.

window.insnstr(str, n[, attr])

window.insnstr(y, x, str, n[, attr])

カーソルの下の文字の前に、最大 n 文字の文字列を (行に収まるだけ) 挿入します。 n が負の場合、文字列全体を挿入します。 カーソルの右側の文字はすべて右に移動し、行の右端の文字は失われます。 カーソル位置は変わりません (y、x が指定されていれば、その位置に移動した後での位置です)。

バージョン 3.16 で変更: str may now also be a complexstr; see insstr().

Deleting and inserting lines

window.delch([y, x])

カーソルの下、または指定した (y, x) の位置の文字を削除します。 同じ行の右側にある文字はすべて 1 文字分左に移動します。

window.deleteln()

カーソルの下にある行を削除します。後続の行はすべて 1 行上に移動します。

window.insertln()

カーソルの下に空行を 1 行入れます。それ以降の行は 1 行づつ下に移動します。

window.insdelln(nlines)

指定されたウィンドウの現在の行の上に nlines 行を挿入します。 最下部の nlines 行は失われます。 nlines が負の場合は、カーソルのある行からその絶対値に相当する行数を削除し、残りの行を上に移動します。 最下部の同じ行数分は消去されます。 現在のカーソル位置は変わりません。

Reading input

window.getch([y, x])

y、x が指定されていればカーソルをそこに移動してからキー入力を読み取り、整数として返します。 ウィンドウがパッドではなく、前回の更新以降に変更されていれば、まず更新します。 キーが押されるまで待機しますが、読み取りが非ブロッキングの場合やタイムアウトした場合は -1 を返します (nodelay() と timeout() を参照)。

通常のキーは、現在のロケールのエンコーディングで表した 1 バイトのコードとして返されるため、複数バイトでエンコードされる文字を読み取るには複数回の呼び出しが必要です。 例えば UTF-8 ロケールでは、'é' は 195、続いて 169 として読み取られます。 1 文字として読み取るには get_wch() を使用してください。

キーパッドモード (keypad() を参照) では、ファンクションキーやその他の特殊キーは、通常のキーと区別できる KEY_* 定数 のいずれかとして返されます。 それ以外の場合、またはエスケープシーケンスが時間内に到着しなかった場合 (notimeout() と set_escdelay() を参照)、バイトが 1 つずつ返されます。

echo モード (echo() を参照) では、addch() と同様にキーがウィンドウに追加されます。 特殊キーはエコーバックされません。

window.get_wch([y, x])

y、x が指定されていればカーソルをそこに移動してからキー入力を読み取り、1 文字の str として返します。 ウィンドウがパッドではなく、前回の更新以降に変更されていれば、まず更新します。 キーが押されるまで待機しますが、読み取りが非ブロッキングの場合やタイムアウトした場合は error を送出します (nodelay() と timeout() を参照)。

キーパッドモード (keypad() を参照) では、ファンクションキーやその他の特殊キーは、整数である KEY_* 定数 のいずれかとして返されます。 それ以外の場合、またはエスケープシーケンスが時間内に到着しなかった場合 (notimeout() と set_escdelay() を参照)、文字が 1 つずつ返されます。

echo モード (echo() を参照) では、addch() と同様にキーがウィンドウに追加されます。 特殊キーはエコーバックされません。

Added in version 3.3.

バージョン 3.16 で変更: Also available on a narrow build, where only a character representable as a single byte (an 8-bit locale) can be returned.

window.getkey([y, x])

getch() と同様にキー入力を読み取りますが、str として返します。 通常のキーはバイトを Latin-1 でデコードした 1 文字の文字列として、特殊キーは 'KEY_UP' のような名前として返します (keyname() を参照)。 入力がない場合、-1 を返す代わりに error を送出します。

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

y、x が指定されていればカーソルをそこに移動してから、基本的な行編集機能を使ってユーザの入力を 1 行読み取ります。 末尾の改行を除き、現在のロケールのエンコーディングの bytes オブジェクトとして返します。 最大 n バイトを読み取ります。 n のデフォルト値は 2047 で、この値を超えることはできません。

Use get_wstr() to read the input as a str.

バージョン 3.14 で変更: n の最大値が 1023 から 2047 に増えました。

window.get_wstr()

window.get_wstr(n)

window.get_wstr(y, x)

window.get_wstr(y, x, n)

Read a line of input from the user, with primitive line editing capacity, after moving the cursor to y, x if specified. Return it as a str, without the terminating newline. At most n characters are read; n defaults to and cannot exceed 2047.

This is the wide-character variant of getstr().

Added in version 3.16.

window.getdelay()

Return the window's read timeout in milliseconds, as set by nodelay() or timeout(): -1 for blocking, 0 for non-blocking, or a positive number of milliseconds.

Added in version 3.16.

Reading window contents

window.inch([y, x])

Return the character at the given position in the window. The bottom 8 bits are the character proper and the upper bits are the attributes; extract them with the A_CHARTEXT and A_ATTRIBUTES bit-masks, and the color pair with pair_number(). The character byte is the locale-encoded byte of the cell's character, consistent with instr(). It cannot represent a cell holding combining characters, a character that does not fit in a single byte, or a color pair outside the color_pair() range; use in_wch() for those, which returns it as a complexchar.

window.in_wch([y, x])

Return the complex character at the given position in the window as a complexchar. Unlike inch(), the returned object carries the cell's text (a spacing character optionally followed by combining characters) together with its attributes and color pair.

Added in version 3.16.

window.instr([n])

window.instr(y, x[, n])

Read the text of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n bytes if n is specified, and return it as a bytes object, in the encoding of the current locale. Attributes and color pairs are stripped; use in_wchstr() to read them too. A character not representable in the encoding cannot be returned; use in_wstr() for those.

バージョン 3.14 で変更: n の最大値が 1023 から 2047 に増えました。

バージョン 3.16 で変更: n is no longer limited to 2047.

window.in_wstr([n])

window.in_wstr(y, x[, n])

Read the text of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n characters if n is specified, and return it as a str. Attributes and color pairs are stripped; use in_wchstr() to read them too.

This is the wide-character variant of instr().

Added in version 3.16.

window.in_wchstr([n])

window.in_wchstr(y, x[, n])

Read the styled cells of the window from the current cursor position, or from y, x if specified, to the end of the line or at most n cells if n is specified, and return them as a complexstr. Unlike instr() and in_wstr(), each cell keeps its attributes and color pair, so the result can be written back unchanged with addstr().

Added in version 3.16.

Attributes

window.attroff(attr)

現在のウィンドウへのすべての書き込みに適用される "バックグラウンド" の属性セットから attr を取り除きます。

window.attron(attr)

現在のウィンドウへのすべての書き込みに適用される「背景」の属性の集合に、属性 attr を追加します。

window.attrset(attr)

"バックグラウンド" の属性セットを attr に設定します。初期値は 0 (属性なし) です。

window.attr_get()

Return the window's current rendition as a (attrs, pair) tuple, where attrs is the set of attributes and pair is the color pair number.

Unlike attron() and friends, which take packed A_* attributes, this method and the other attr_* methods work with the WA_* attributes and keep the color pair as a separate number, which lets them use color pairs that do not fit alongside the attributes in a single value.

Added in version 3.16.

window.attr_set(attr, pair=0)

Set the window's rendition to the attributes attr and the color pair pair.

Added in version 3.16.

window.attr_on(attr)

Turn on the attributes attr without affecting any others.

Added in version 3.16.

window.attr_off(attr)

Turn off the attributes attr without affecting any others.

Added in version 3.16.

window.color_set(pair)

Set the window's color pair to pair, leaving the other attributes unchanged.

Added in version 3.16.

window.getattrs()

Return the window's current attributes.

Added in version 3.16.

window.standout()

A_STANDOUT 属性をオンにします。

window.standend()

A_STANDOUT 属性をオフにします。端末によっては、この操作ですべての属性をオフにする副作用が発生します。

window.chgat(attr)

window.chgat(num, attr)

window.chgat(y, x, attr)

window.chgat(y, x, num, attr)

現在のカーソル位置、または指定した位置 (y, x) にある num 文字の属性を設定します。 num を指定しないか -1 にした場合は、行末までのすべての文字に属性が設定されます。 (y, x) を指定した場合、この関数はカーソルをその位置に移動します。 変更した行は touchline() メソッドで変更済みと記録され、次回のウィンドウ更新時に内容が再表示されます。

Background

window.bkgd(ch[, attr])

ウィンドウ上の背景プロパティを、attr を属性とする文字 ch に設定します。変更はそのウィンドウ中のすべての文字に以下のようにして適用されます:

• ウィンドウ中のすべての文字の属性が新たな背景属性に変更されます。

• 以前の背景文字が出現すると、常に新たな背景文字に変更されます。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

window.bkgdset(ch[, attr])

ウィンドウの背景を設定します。ウィンドウの背景は、文字と何らかの属性の組み合わせから成り立ちます。背景情報の属性の部分は、ウィンドウ上に描画されている空白でないすべての文字と組み合わされ (OR され) ます。空白文字には文字部分と属性部分の両方が組み合わされます。背景は文字のプロパティとなり、スクロールや行/文字の挿入/削除操作の際には文字と一緒に移動します。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

window.getbkgd()

Return the given window's current background character/attribute pair. Its components can be extracted like those of inch(). It cannot represent a background set with a wide character or with a color pair outside the color_pair() range; use getbkgrnd() for those.

window.getbkgrnd()

Return the given window's current background as a complexchar. Unlike getbkgd(), the returned object carries the background character together with its attributes and color pair, and the color pair is not limited to the value that fits in a color_pair().

Added in version 3.16.

Clearing and erasing

window.erase()

ウィンドウをクリアします。

window.clear()

erase() に似ていますが、次に refresh() が呼び出された際にウィンドウ全体を再描画するようにします。

window.clrtobot()

カーソル位置からウィンドウの末尾までを消去します。 まずカーソルのある行より下のすべての行を消去し、次に clrtoeol() と同等の処理を行います。

window.clrtoeol()

カーソル位置から行末までを消去します。

Borders and lines

window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

ウィンドウの縁に境界線を描画します。各引数には境界の特定部分を表現するために使われる文字を指定します; 詳細は以下のテーブルを参照してください。

注釈

どの引数も、0 を指定した場合デフォルトの文字が使われるようになります。キーワード引数は使うことが できません。デフォルトはテーブル内で示しています:

引数	説明	デフォルト値	Wide default value
ls	左側	ACS_VLINE	WACS_VLINE
rs	右側	ACS_VLINE	WACS_VLINE
ts	上側	ACS_HLINE	WACS_HLINE
bs	下側	ACS_HLINE	WACS_HLINE
tl	左上の角	ACS_ULCORNER	WACS_ULCORNER
tr	右上の角	ACS_URCORNER	WACS_URCORNER
bl	左下の角	ACS_LLCORNER	WACS_LLCORNER
br	右下の角	ACS_LRCORNER	WACS_LRCORNER

The wide default value is used when the border is drawn from string characters or complexchar cells.

If any parameter is a byte character or an integer other than 0, the border is drawn from byte characters, and every string character must be encodable as a single byte.

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted. A single call cannot mix complexchar cells with integer or byte characters.

window.box([vertch, horch])

border() と同様ですが、ls および rs は共に vertch で、ts および bs は共に horch です。この関数では、角に使われるデフォルト文字が常に使用されます。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted. A single call cannot mix complexchar cells with integer or byte characters.

window.hline(ch, n[, attr])

window.hline(y, x, ch, n[, attr])

(y, x) を始点として、属性 attr の文字 ch からなる長さ n の水平線を表示します。 使用できるセルが n 個に満たない場合、線はウィンドウの右端で止まります。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

window.vline(ch, n[, attr])

window.vline(y, x, ch, n[, attr])

(y, x) を始点として、属性 attr の文字 ch からなる長さ n の垂直線を表示します。

バージョン 3.16 で変更: Wide and combining characters, and complexchar cells, are now accepted.

Cursor position and window geometry

window.move(new_y, new_x)

カーソルを (new_y, new_x) に移動します。

window.getyx()

ウィンドウの左上角からの相対で表した現在のカーソル位置をタプル (y, x) で返します。

window.getbegyx()

左上隅の座標をタプル (y, x) として返します。

window.getmaxyx()

ウィンドウの高さおよび幅を表すタプル (y, x) を返します。

window.getparyx()

親ウィンドウ中におけるウィンドウの開始位置をタプル (y, x) で返します。ウィンドウに親ウィンドウがない場合 (-1, -1) を返します。

window.getparent()

Return the parent window of this subwindow, or None if this window is not a subwindow.

Added in version 3.16.

Creating and resizing windows

window.subwin(begin_y, begin_x)

window.subwin(nlines, ncols, begin_y, begin_x)

左上隅がスクリーンからの相対座標 (begin_y, begin_x) にあり、幅が ncols、高さが nlines のサブウィンドウを返します。

デフォルトでは、サブウィンドウは指定された場所からウィンドウの右下角まで広がります。

window.derwin(begin_y, begin_x)

window.derwin(nlines, ncols, begin_y, begin_x)

"derive window (ウィンドウを派生する)" の短縮形です。derwin() は subwin() と同じですが、begin_y および begin_x はスクリーン全体の原点ではなく、ウィンドウの原点からの相対位置です。派生したウィンドウオブジェクトが返されます。

window.subpad(begin_y, begin_x)

window.subpad(nlines, ncols, begin_y, begin_x)

左上隅が (begin_y, begin_x) にあり、幅が ncols、高さが nlines のサブパッドを返します。 座標は親パッドからの相対座標です (スクリーン座標を使う subwin() とは異なります)。 このメソッドは newpad() で作成したパッドでのみ利用できます。

window.dupwin()

Return a new window that is an exact duplicate of the window: it has the same size, position, contents and attributes. Unlike a window created by subwin() or derwin(), the duplicate is independent of the original -- it has its own cell buffer, so later changes to one do not affect the other.

Added in version 3.16.

window.mvwin(new_y, new_x)

ウィンドウの左上角が (new_y, new_x) になるように移動します。

ウィンドウの一部でもスクリーンの外に出る位置への移動はエラーです。 ウィンドウは移動せず、curses.error が送出されます。

window.mvderwin(y, x)

ウィンドウを親ウィンドウの中で移動します。ウィンドウのスクリーン相対となるパラメタ群は変化しません。このルーチンは親ウィンドウの一部をスクリーン上の同じ物理位置に表示する際に用いられます。

window.resize(nlines, ncols)

curses ウィンドウの記憶域を、指定値のサイズに調整するため再割当てします。サイズが現在の値より大きい場合、ウィンドウのデータは現在の背景設定 (bkgdset() で設定) で埋められマージされます。

Refreshing and redrawing

window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

ディスプレイを即時更新し (実際のウィンドウとこれまでの描画/削除メソッドの内容とを同期し) ます。

6 つの引数を指定できるのは、ウィンドウが newpad() で作成されたパッドである場合だけで、その場合はすべて必須です。 これらの追加のパラメータは、パッドとスクリーンのどの部分を使用するかを示すために必要です。 pminrow と pmincol はパッド内の表示する矩形の左上隅を指定します。 sminrow、smincol、smaxrow、smaxcol はスクリーン上に表示する矩形の端を指定します。 両方の矩形は同じ大きさでなければならないため、パッド内の表示する矩形の右下隅はスクリーン座標から計算されます。 両方の矩形は、それぞれの構造の内部に完全に収まっていなければなりません。 pminrow、pmincol、sminrow、smincol の負の値はゼロとして扱われます。

window.noutrefresh()

window.noutrefresh(pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)

更新をマークはしますが待機します。この関数はウィンドウのデータ構造を表現したい内容を反映するように更新しますが、物理スクリーン上に反映させるための強制更新を行いません。更新を行うためには doupdate() を呼び出します。

6 つの引数を指定できるのは、ウィンドウが newpad() で作成されたパッドである場合だけで、その場合はすべて必須です。 意味は refresh() のものと同じです。

window.redrawln(beg, num)

beg 行から始まる num スクリーン行の表示内容が壊れており、次の refresh() 呼び出しで完全に再描画されなければならないことを通知します。

window.redrawwin()

ウィンドウ全体を更新 (touch) し、次の refresh() 呼び出しで完全に再描画されるようにします。

Output options

window.clearok(flag)

flag が True ならば、次の refresh() はウィンドウを完全に消去します。

window.idlok(flag)

flag が True の場合、curses はハードウェアの行編集機能を使用しようとします。 それ以外の場合、curses はその機能を使用しません。

window.idcok(flag)

flag が False の場合、curses は端末のハードウェアによる文字挿入/削除機能を使おうとしなくなります; flag が True ならば、文字挿入/削除は有効にされます。curses が最初に初期化された際には文字挿入/削除はデフォルトで有効になっています。

window.immedok(flag)

flag が True ならば、ウィンドウイメージ内における何らかの変更があるとウィンドウを更新するようになります; すなわち、refresh() を自分で呼ばなくても良くなります。とはいえ、wrefresh を繰り返し呼び出すことになるため、この操作はかなりパフォーマンスを低下させます。デフォルトでは無効になっています。

window.leaveok(flag)

flag が True の場合、更新時にカーソルを「カーソル位置」に移動せず、そのままの位置に残します。 これにより、可能な限りカーソルの移動を減らします。

flag が False の場合、カーソルは更新の際に常に "カーソル位置" に移動します。

window.scrollok(flag)

ウィンドウのカーソルが、最下行で改行を行ったり最後の文字を入力したりした結果、ウィンドウやスクロール領域の縁からはみ出して移動した際の動作を制御します。flag が False の場合、カーソルは最下行にそのままにしておかれます。flag が True の場合、ウィンドウは 1 行上にスクロールします。端末の物理スクロール効果を得るためには idlok() も呼び出す必要があるので注意してください。

window.scroll([lines=1])

スクリーンまたはスクロール領域をスクロールします。 lines が正の場合は lines 行上に、負の場合は下にスクロールします。 scrollok() でウィンドウのスクロールを有効にしていなければ、curses.error を送出します。

window.setscrreg(top, bottom)

スクロール領域を top から bottom に設定します。スクロール動作はすべてこの領域で行われます。

window.getscrreg()

Return a tuple (top, bottom) of the window's current scrolling region, as set by setscrreg().

Added in version 3.16.

window.syncok(flag)

flag が True の場合、ウィンドウが変更された際は常に syncup() を自動的に呼ぶようになります。

Input options

window.keypad(flag)

flag が True の場合、一部のキー (キーパッド、ファンクションキー) が生成するエスケープシーケンスを curses が解釈します。 flag が False の場合、エスケープシーケンスは入力ストリーム内にそのまま残されます。 キーパッドモードはデフォルトでは無効ですが、wrapper() はメインウィンドウに対して有効にします。

window.nodelay(flag)

flag が True の場合、getch() は非ブロックで動作します。

window.notimeout(flag)

flag が True の場合、エスケープシーケンスはタイムアウトしなくなります。

flag が False の場合、数ミリ秒間の間エスケープシーケンスは解釈されず、入力ストリーム中にそのままの状態で残されます。

window.timeout(delay)

ウィンドウのブロックまたは非ブロック読み込み動作を設定します。delay が負の場合、ブロック読み出しが使われ、入力を無期限で待ち受けます。delay がゼロの場合、非ブロック読み出しが使われ、入力待ちの文字がない場合 getch() は -1 を返します。delay が正の値であれば、getch() は delay ミリ秒間ブロックし、ブロック後の時点で入力がない場合には -1 を返します。

Overlapping and touch

window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

ウィンドウを destwin の上に重ね書き (overlay) します。ウィンドウは同じサイズである必要はなく、重なっている領域だけが複写されます。この複写は非破壊的です。これは現在の背景文字が destwin の内容を上書きしないことを意味します。

複写領域をきめ細かく制御するために、overlay() の第二形式を使うことができます。sminrow および smincol は元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を表します。

window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

destwin の上にウィンドウの内容を上書き (overwrite) します。ウィンドウは同じサイズである必要はなく、重なっている領域だけが複写されます。この複写は破壊的です。これは現在の背景文字が destwin の内容を上書きすることを意味します。

複写領域をきめ細かく制御するために、overwrite() の第二形式を使うことができます。sminrow および smincol は元のウィンドウの左上の座標で、他の変数は destwin 内の矩形を表します。

window.touchline(start, count[, changed])

start 行から count 行が変更されたものとして扱います。 changed を指定した場合は、対象の行を変更済み (changed=True) とするか、未変更 (changed=False) とするかを指定します。

window.touchwin()

描画を最適化するために、ウィンドウ全体が変更されたかのように振舞わせます。

window.untouchwin()

ウィンドウ内のすべての行を、最後に refresh() を呼んだ際から変更されていないものとしてマークします。

window.syncup()

ウィンドウ内で更新 (touch) した場所を、上位のすべてのウィンドウ内でも更新します。

window.syncdown()

このウィンドウの上位のウィンドウのいずれかで更新(touch)された各場所をこのウィンドウ内でも更新します。このルーチンは refresh() から呼び出されるので、手動で呼び出す必要はほとんどないはずです。

window.cursyncup()

ウィンドウのすべての親ウィンドウについて、現在のカーソル位置を反映するよう更新します。

Coordinate conversion

window.enclose(y, x)

与えられた文字セル座標をスクリーン原点から相対的なものとし、ウィンドウの中に含まれるかを調べて、True または False を返します。スクリーン上のウィンドウの一部がマウスイベントの発生場所を含むかどうかを調べる上で便利です。

バージョン 3.10 で変更: 以前は True または False ではなく、1 または 0 を返していました。

window.mouse_trafo(y, x, to_screen)

Convert between window-relative and screen-relative (stdscr-relative) character-cell coordinates. If to_screen is true, convert the window-relative coordinates y, x to screen-relative coordinates; otherwise convert in the opposite direction. The two coordinate systems differ when lines are reserved on the screen, for example for soft labels.

Return the converted coordinates as a (y, x) tuple, or None if they lie outside the window.

Added in version 3.16.

Other

window.encoding

メソッドの文字列の引数をエンコードする際、およびワイド文字をサポートしないビルドで結果をデコードする際に使用するエンコーディングです。 例えば window.subwin() でサブウィンドウを作成すると、encoding 属性は親ウィンドウから継承されます。 デフォルトでは現在のロケールのエンコーディングが使用されます (locale.getencoding() を参照)。

Added in version 3.3.

window.putwin(file)

ウィンドウに関連付けられているすべてのデータを与えられたファイルオブジェクトに書き込みます。この情報は後に getwin() 関数を使って取得することができます。

window.use(func, /, *args, **kwargs)

Call func(window, *args, **kwargs) with the lock of the window held, and return its result. This provides automatic protection for the window against concurrent access from another thread.

Availability: if the underlying curses library provides use_window().

Added in version 3.16.

State queries

window.is_cleared()

Return the current value set by clearok().

Added in version 3.16.

window.is_idcok()

Return the current value set by idcok().

Added in version 3.16.

window.is_idlok()

Return the current value set by idlok().

Added in version 3.16.

window.is_immedok()

Return the current value set by immedok().

Added in version 3.16.

window.is_keypad()

Return the current value set by keypad().

Added in version 3.16.

window.is_leaveok()

Return the current value set by leaveok().

Added in version 3.16.

window.is_linetouched(line)

指定した行が、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。line が現在のウィンドウ上の有効な行でない場合、curses.error 例外を送出します。

window.is_nodelay()

Return the current value set by nodelay().

Added in version 3.16.

window.is_notimeout()

Return the current value set by notimeout().

Added in version 3.16.

window.is_pad()

Return True if the window is a pad created by newpad().

Added in version 3.16.

window.is_scrollok()

Return the current value set by scrollok().

Added in version 3.16.

window.is_subwin()

Return True if the window is a subwindow created by subwin() or derwin().

Added in version 3.16.

window.is_syncok()

Return the current value set by syncok().

Added in version 3.16.

window.is_wintouched()

指定したウィンドウが、最後に refresh() を呼んだ時から変更されている場合に True を返します; そうでない場合には False を返します。

Screen objects

class curses.screen

A screen object represents a terminal initialized by newterm() (or new_prescr()), in addition to the default screen created by initscr(). Screen objects are returned by those functions; they cannot be instantiated directly.

A screen is freed automatically once it is no longer referenced, either directly or through one of its windows. Each window keeps its screen alive, so a screen remains valid as long as any of its windows does.

Added in version 3.16.

screen.close()

Detach the screen's standard window, breaking the reference cycle between them so the screen can be reclaimed promptly instead of waiting for a garbage collection. Afterwards stdscr is None and the window it returned earlier can no longer be used. The screen's resources are released once it and all its windows are no longer referenced.

Added in version 3.16.

screen.stdscr

The standard window of the screen, covering the whole terminal, or None for a screen created by new_prescr().

screen.use(func, /, *args, **kwargs)

Call func(screen, *args, **kwargs) with the lock of the screen held, and return its result. This provides automatic protection for the screen against concurrent access from another thread.

Availability: if the underlying curses library provides use_screen().

Added in version 3.16.

Complex character objects

class curses.complexchar(text, /, attr=0, pair=0)

A complex character (or complexchar) is an immutable styled character cell: a spacing character optionally followed by combining characters, together with a set of attributes and a color pair.

text is the cell's text, attr a combination of the WA_* attributes (equivalent to the matching A_* constants), and pair a color pair number. Unlike the packed chtype used by inch() and the A_* methods, the color pair is stored separately and is not limited to the value that fits in a color_pair().

Complex characters are returned by window.in_wch() and window.getbkgrnd(), and are accepted (along with an integer, a byte or a string) by the character-cell methods such as window.addch(), window.insch(), window.bkgd(), window.border(), window.hline() and window.vline(). A complex character already carries its own rendition, so it cannot be combined with an explicit attr argument.

str() returns the cell's text; two complex characters are equal when their text, attributes and color pair all match.

The same code works on both wide- and narrow-character builds. On a narrow build a cell holds a single character (no combining marks) that must encode to one byte in the window's encoding (8-bit locales only), and pair is limited to the value that fits in a color_pair().

attr

The attributes of the character cell (read-only).

pair

The color pair number of the character cell (read-only).

Added in version 3.16.

class curses.complexstr(cells[, attr[, pair]])

A complex character string (or complexstr) is an immutable sequence of styled character cells -- the string counterpart of complexchar (as str is to a single character).

If cells is a string, it is split into character cells (each a spacing character optionally followed by combining characters), and attr (a combination of the WA_* attributes) and pair (a color pair number), if given, are applied to every cell.

Otherwise cells is an iterable whose items are themselves cells, each a complexchar or a string; each item then carries its own rendition, and attr and pair must be omitted.

It is returned by window.in_wchstr(), and accepted by window.addstr(), addnstr(), insstr() and insnstr(), so a run read from a window can be written back unchanged.

It behaves like an immutable sequence: len(s) is the number of cells, s[i] is the i-th cell as a complexchar, slicing and concatenation produce new complexstr instances, and iterating yields the cells. str() returns the cells' text joined together, and two complex character strings are equal when their cells all match. It is hashable.

To build or edit a run of cells, use an ordinary list of complexchar (or strings); a complexstr is the immutable form returned by a read.

Like complexchar, this type works on both wide- and narrow-character builds, with the same per-cell limitations on a narrow build.

Added in version 3.16.

定数

General

curses モジュールは以下のデータメンバを定義します:

curses.ERR

getch() のような整数を返す curses ルーチンのいくつかは、失敗した際に ERR を返します。

curses.OK

napms() のような整数を返す curses ルーチンのいくつかは、成功した際に OK を返します。

curses.version

モジュールの現在のバージョンを表す bytes オブジェクトです。

curses.ncurses_version

ncurses ライブラリのバージョンの 3 つの成分 major、minor、patch を含む名前付きタプルです。 値はすべて整数です。 各成分には名前でもアクセスできるため、例えば curses.ncurses_version[0] は curses.ncurses_version.major と等価です。

利用可能な環境: ncurses ライブラリが使用されている場合。

Added in version 3.8.

curses.COLORS

端末がサポートできる色の最大数です。 start_color() の呼び出し後にのみ定義されます。

curses.COLOR_PAIRS

端末がサポートできる色ペアの最大数です。 start_color() の呼び出し後にのみ定義されます。

curses.COLS

スクリーンの幅、すなわち列数です。 initscr() の呼び出し後にのみ定義されます。 update_lines_cols()、resizeterm()、resize_term() により更新されます。

curses.LINES

スクリーンの高さ、すなわち行数です。 initscr() の呼び出し後にのみ定義されます。 update_lines_cols()、resizeterm()、resize_term() により更新されます。

Attributes

文字セルの属性を指定するための定数が用意されています。 実際に利用できる定数はシステムによって異なります。

属性	Wide attribute	意味
curses.A_ALTCHARSET	curses.WA_ALTCHARSET	代替文字セットモード
curses.A_BLINK	curses.WA_BLINK	点滅モード
curses.A_BOLD	curses.WA_BOLD	太字モード
curses.A_DIM	curses.WA_DIM	低輝度モード
curses.A_INVIS	curses.WA_INVIS	非表示または空白モード
curses.A_ITALIC	curses.WA_ITALIC	イタリックモード
curses.A_NORMAL	curses.WA_NORMAL	通常の属性
curses.A_PROTECT	curses.WA_PROTECT	保護モード
curses.A_REVERSE	curses.WA_REVERSE	背景色と前景色を反転
curses.A_STANDOUT	curses.WA_STANDOUT	強調モード
curses.A_UNDERLINE	curses.WA_UNDERLINE	下線モード
curses.A_HORIZONTAL	curses.WA_HORIZONTAL	水平強調
curses.A_LEFT	curses.WA_LEFT	左強調
curses.A_LOW	curses.WA_LOW	下強調
curses.A_RIGHT	curses.WA_RIGHT	右強調
curses.A_TOP	curses.WA_TOP	上強調
curses.A_VERTICAL	curses.WA_VERTICAL	垂直強調

Added in version 3.7: A_ITALIC が追加されました。

The attr_get(), attr_set(), attr_on() and attr_off() methods use the parallel set of WA_* constants listed above. Each has the same meaning as the corresponding A_* attribute (WA_BOLD like A_BOLD, and so on), but belongs to the attr_t type rather than being packed into a character. In ncurses the two sets share the same values, but other curses implementations may give them different ones, so use the WA_* constants with the attr_* methods.

Added in version 3.16: The WA_* constants were added.

一部のメソッドが返す値から対応する属性を取り出すための定数が用意されています。

ビットマスク	Wide bit-mask	意味
curses.A_ATTRIBUTES	curses.WA_ATTRIBUTES	属性を取り出すビットマスク
curses.A_CHARTEXT		文字を取り出すビットマスク
curses.A_COLOR		色ペアフィールドの情報を取り出すビットマスク

Keys

キーは KEY_ で始まる名前をもつ整数定数です。利用可能なキーキャップはシステムに依存します。

キー定数	キー
curses.KEY_MIN	最小のキー値
curses.KEY_BREAK	ブレークキー (Break, 信頼できません)
curses.KEY_DOWN	下矢印
curses.KEY_UP	上矢印
curses.KEY_LEFT	左矢印
curses.KEY_RIGHT	右矢印
curses.KEY_HOME	ホームキー (Home, または上左矢印)
curses.KEY_BACKSPACE	バックスペース (Backspace, 信頼できません)
curses.KEY_F0	ファンクションキー。64 個までサポートされています。
curses.KEY_Fn	ファンクションキー n の値
curses.KEY_DL	行削除 (Delete line)
curses.KEY_IL	行挿入 (Insert line)
curses.KEY_DC	文字削除 (Delete char)
curses.KEY_IC	文字挿入、または文字挿入モードへ入る
curses.KEY_EIC	文字挿入モードから抜ける
curses.KEY_CLEAR	画面消去
curses.KEY_EOS	画面の末端まで消去
curses.KEY_EOL	行末端まで消去
curses.KEY_SF	前に 1 行スクロール
curses.KEY_SR	後ろ (逆方向) に 1 行スクロール
curses.KEY_NPAGE	次のページ (Page Next)
curses.KEY_PPAGE	前のページ (Page Prev)
curses.KEY_STAB	タブ設定
curses.KEY_CTAB	タブリセット
curses.KEY_CATAB	すべてのタブをリセット
curses.KEY_ENTER	入力または送信 (信頼できません)
curses.KEY_SRESET	ソフトウェア (部分的) リセット (信頼できません)
curses.KEY_RESET	リセットまたはハードリセット (信頼できません)
curses.KEY_PRINT	印刷 (Print)
curses.KEY_LL	下ホーム (Home down) または最下行 (左下)
curses.KEY_A1	キーパッドの左上キー
curses.KEY_A3	キーパッドの右上キー
curses.KEY_B2	キーパッドの中央キー
curses.KEY_C1	キーパッドの左下キー
curses.KEY_C3	キーパッドの右下キー
curses.KEY_BTAB	Back tab
curses.KEY_BEG	開始 (Beg)
curses.KEY_CANCEL	キャンセル (Cancel)
curses.KEY_CLOSE	Close [閉じる]
curses.KEY_COMMAND	コマンド (Cmd)
curses.KEY_COPY	Copy [コピー]
curses.KEY_CREATE	生成 (Create)
curses.KEY_END	終了 (End)
curses.KEY_EXIT	Exit [終了]
curses.KEY_FIND	検索 (Find)
curses.KEY_HELP	ヘルプ (Help)
curses.KEY_MARK	マーク (Mark)
curses.KEY_MESSAGE	メッセージ (Message)
curses.KEY_MOVE	移動 (Move)
curses.KEY_NEXT	次へ (Next)
curses.KEY_OPEN	開く (Open)
curses.KEY_OPTIONS	オプション
curses.KEY_PREVIOUS	前へ (Prev)
curses.KEY_REDO	Redo [やり直し]
curses.KEY_REFERENCE	参照 (Ref)
curses.KEY_REFRESH	更新 (Refresh)
curses.KEY_REPLACE	置換 (Replace)
curses.KEY_RESTART	再起動 (Restart)
curses.KEY_RESUME	再開 (Resume)
curses.KEY_SAVE	Save [保存]
curses.KEY_SBEG	シフト付き Beg
curses.KEY_SCANCEL	シフト付き Cancel
curses.KEY_SCOMMAND	シフト付き Command
curses.KEY_SCOPY	シフト付き Copy
curses.KEY_SCREATE	シフト付き Create
curses.KEY_SDC	シフト付き Delete char
curses.KEY_SDL	シフト付き Delete line
curses.KEY_SELECT	選択 (Select)
curses.KEY_SEND	シフト付き End
curses.KEY_SEOL	シフト付き Clear line
curses.KEY_SEXIT	シフト付き Exit
curses.KEY_SFIND	シフト付き Find
curses.KEY_SHELP	シフト付き Help
curses.KEY_SHOME	シフト付き Home
curses.KEY_SIC	シフト付き Input
curses.KEY_SLEFT	シフト付き Left arrow
curses.KEY_SMESSAGE	シフト付き Message
curses.KEY_SMOVE	シフト付き Move
curses.KEY_SNEXT	シフト付き Next
curses.KEY_SOPTIONS	シフト付き Options
curses.KEY_SPREVIOUS	シフト付き Prev
curses.KEY_SPRINT	シフト付き Print
curses.KEY_SREDO	シフト付き Redo
curses.KEY_SREPLACE	シフト付き Replace
curses.KEY_SRIGHT	シフト付き Right arrow
curses.KEY_SRSUME	シフト付き Resume
curses.KEY_SSAVE	シフト付き Save
curses.KEY_SSUSPEND	シフト付き Suspend
curses.KEY_SUNDO	シフト付き Undo
curses.KEY_SUSPEND	一時停止 (Suspend)
curses.KEY_UNDO	Undo [元に戻す]
curses.KEY_MOUSE	マウスイベント通知
curses.KEY_RESIZE	端末リサイズイベント
curses.KEY_MAX	最大キー値

VT100 とそのソフトウェアエミュレーション (X 端末エミュレータなど) では、通常は少なくとも 4 つのファンクションキー (KEY_F1、KEY_F2、KEY_F3、KEY_F4) が利用でき、矢印キーはそれぞれ KEY_UP、KEY_DOWN、KEY_LEFT、KEY_RIGHT に対応付けられています。 PC キーボードのあるマシンでは、矢印キーと 12 個のファンクションキーがあると考えてよいでしょう (古い PC キーボードにはファンクションキーが 10 個しかない場合もあります)。 また、以下のキーパッドの対応付けが標準です:

キーキャップ	定数
Insert	KEY_IC
Delete	KEY_DC
Home	KEY_HOME
End	KEY_END
Page Up	KEY_PPAGE
Page Down	KEY_NPAGE

Alternate character set

代替文字セットを以下の表に列挙します。これらは VT100 端末から継承したものであり、X 端末のようなソフトウェアエミュレーション上で一般に利用可能なものです。グラフィックが利用できない場合、curses は印字可能 ASCII文字による粗雑な近似出力を行います。

Every character has two names. The ACS_* code is an integer character, restricted to the 8-bit alternate character set of the terminal. The WACS_* code is the same character as a complexchar cell, which is not restricted to the alternate character set.

注釈

These are available only after initscr() has been called. The WACS_* codes are only available if Python is built with wide character support.

Added in version 3.16: The WACS_* codes.

ACS コード	WACS code	意味
curses.ACS_BBSS	curses.WACS_BBSS	右上隅の別名
curses.ACS_BLOCK	curses.WACS_BLOCK	黒四角ブロック
curses.ACS_BOARD	curses.WACS_BOARD	白四角ブロック
curses.ACS_BSBS	curses.WACS_BSBS	水平線の別名
curses.ACS_BSSB	curses.WACS_BSSB	左上隅の別名
curses.ACS_BSSS	curses.WACS_BSSS	上向き T 字罫線の別名
curses.ACS_BTEE	curses.WACS_BTEE	下向き T 字罫線
curses.ACS_BULLET	curses.WACS_BULLET	黒丸(bullet)
curses.ACS_CKBOARD	curses.WACS_CKBOARD	チェッカーボードパタン (点描)
curses.ACS_DARROW	curses.WACS_DARROW	下向き矢印
curses.ACS_DEGREE	curses.WACS_DEGREE	度記号
curses.ACS_DIAMOND	curses.WACS_DIAMOND	ダイアモンド
curses.ACS_GEQUAL	curses.WACS_GEQUAL	大なりイコール
curses.ACS_HLINE	curses.WACS_HLINE	水平線
curses.ACS_LANTERN	curses.WACS_LANTERN	ランタン(lantern) シンボル
curses.ACS_LARROW	curses.WACS_LARROW	左向き矢印
curses.ACS_LEQUAL	curses.WACS_LEQUAL	小なりイコール
curses.ACS_LLCORNER	curses.WACS_LLCORNER	左下隅
curses.ACS_LRCORNER	curses.WACS_LRCORNER	右下隅
curses.ACS_LTEE	curses.WACS_LTEE	左向き T 字罫線
curses.ACS_NEQUAL	curses.WACS_NEQUAL	不等号
curses.ACS_PI	curses.WACS_PI	パイ記号
curses.ACS_PLMINUS	curses.WACS_PLMINUS	プラスマイナス記号
curses.ACS_PLUS	curses.WACS_PLUS	大プラス記号
curses.ACS_RARROW	curses.WACS_RARROW	右向き矢印
curses.ACS_RTEE	curses.WACS_RTEE	右向き T 字罫線
curses.ACS_S1	curses.WACS_S1	スキャンライン 1
curses.ACS_S3	curses.WACS_S3	スキャンライン 3
curses.ACS_S7	curses.WACS_S7	スキャンライン 7
curses.ACS_S9	curses.WACS_S9	スキャンライン 9
curses.ACS_SBBS	curses.WACS_SBBS	右下隅の別名
curses.ACS_SBSB	curses.WACS_SBSB	垂直線の別名
curses.ACS_SBSS	curses.WACS_SBSS	右向き T 字罫線の別名
curses.ACS_SSBB	curses.WACS_SSBB	左下隅の別名
curses.ACS_SSBS	curses.WACS_SSBS	下向き T 字罫線の別名
curses.ACS_SSSB	curses.WACS_SSSB	左向き T 字罫線の別名
curses.ACS_SSSS	curses.WACS_SSSS	交差罫線または大プラス記号の別名
curses.ACS_STERLING	curses.WACS_STERLING	ポンドスターリング記号
curses.ACS_TTEE	curses.WACS_TTEE	上向き T 字罫線
curses.ACS_UARROW	curses.WACS_UARROW	上向き矢印
curses.ACS_ULCORNER	curses.WACS_ULCORNER	左上隅
curses.ACS_URCORNER	curses.WACS_URCORNER	右上隅
curses.ACS_VLINE	curses.WACS_VLINE	垂直線

The following table lists the double-line and thick-line characters. They have no ACS_* counterpart, and are not provided by every implementation. As in the table above, the alternate name spells out the four sides of the character, clockwise from the top: B for a blank side, S for a single line, D for a double line and T for a thick line.

WACS code	Alternate name	意味
curses.WACS_D_BTEE	curses.WACS_DDBD	double-line bottom tee
curses.WACS_D_HLINE	curses.WACS_BDBD	double-line horizontal line
curses.WACS_D_LLCORNER	curses.WACS_DDBB	double-line lower-left corner
curses.WACS_D_LRCORNER	curses.WACS_DBBD	double-line lower-right corner
curses.WACS_D_LTEE	curses.WACS_DDDB	double-line left tee
curses.WACS_D_PLUS	curses.WACS_DDDD	double-line big plus sign
curses.WACS_D_RTEE	curses.WACS_DBDD	double-line right tee
curses.WACS_D_TTEE	curses.WACS_BDDD	double-line top tee
curses.WACS_D_ULCORNER	curses.WACS_BDDB	double-line upper-left corner
curses.WACS_D_URCORNER	curses.WACS_BBDD	double-line upper-right corner
curses.WACS_D_VLINE	curses.WACS_DBDB	double-line vertical line
curses.WACS_T_BTEE	curses.WACS_TTBT	thick-line bottom tee
curses.WACS_T_HLINE	curses.WACS_BTBT	thick-line horizontal line
curses.WACS_T_LLCORNER	curses.WACS_TTBB	thick-line lower-left corner
curses.WACS_T_LRCORNER	curses.WACS_TBBT	thick-line lower-right corner
curses.WACS_T_LTEE	curses.WACS_TTTB	thick-line left tee
curses.WACS_T_PLUS	curses.WACS_TTTT	thick-line big plus sign
curses.WACS_T_RTEE	curses.WACS_TBTT	thick-line right tee
curses.WACS_T_TTEE	curses.WACS_BTTT	thick-line top tee
curses.WACS_T_ULCORNER	curses.WACS_BTTB	thick-line upper-left corner
curses.WACS_T_URCORNER	curses.WACS_BBTT	thick-line upper-right corner
curses.WACS_T_VLINE	curses.WACS_TBTB	thick-line vertical line

Mouse buttons

getmouse() で使用するマウスボタン定数を以下の表に示します:

マウスボタン定数	意味
curses.BUTTONn_PRESSED	マウスボタン n が押された
curses.BUTTONn_RELEASED	マウスボタン n が離された
curses.BUTTONn_CLICKED	マウスボタン n がクリックされた
curses.BUTTONn_DOUBLE_CLICKED	マウスボタン n がダブルクリックされた
curses.BUTTONn_TRIPLE_CLICKED	マウスボタン n がトリプルクリックされた
curses.BUTTON_SHIFT	ボタンの状態変更時に Shift が押されていた
curses.BUTTON_CTRL	ボタンの状態変更時に Control が押されていた
curses.BUTTON_ALT	ボタンの状態変更時に Alt が押されていた

バージョン 3.10 で変更: 基盤となる curses ライブラリが BUTTON5_* 定数を提供する場合に、それらが公開されるようになりました。

Colors

以下のテーブルは定義済みの色を列挙したものです:

定数	色
curses.COLOR_BLACK	黒
curses.COLOR_BLUE	青
curses.COLOR_CYAN	シアン (薄く緑がかった青)
curses.COLOR_GREEN	緑
curses.COLOR_MAGENTA	マゼンタ (紫がかった赤)
curses.COLOR_RED	赤
curses.COLOR_WHITE	白
curses.COLOR_YELLOW	黄色

curses.textpad --- curses プログラム用のテキスト入力ウィジェット

curses.textpad モジュールは、curses ウィンドウで基本的なテキスト編集を行う Textbox クラスを提供します。 このクラスは Emacs (したがって Netscape Navigator、BBedit 6.x、FrameMaker、その他多くのプログラム) に似たキーバインディングをサポートします。 このモジュールは、テキストボックスの枠を描く場合などに役立つ、矩形を描画する関数も提供します。

curses.textpad モジュールは以下の関数を定義します:

curses.textpad.rectangle(win, uly, ulx, lry, lrx)

矩形を描画します。 最初の引数はウィンドウオブジェクトでなければならず、残りの引数はそのウィンドウからの相対座標です。 2 番目と 3 番目の引数は描画する矩形の左上隅の y 座標と x 座標、4 番目と 5 番目は右下隅の y 座標と x 座標です。 対応する端末 (xterm やその他の大半のソフトウェア端末エミュレータを含む) では、VT100/IBM PC の罫線文字を使用して矩形を描画します。 それ以外の場合は、ASCII のダッシュ、縦棒、プラス記号で描画します。

Textbox オブジェクト

以下のような Textbox オブジェクトをインスタンス生成することができます:

class curses.textpad.Textbox(win, insert_mode=False)

テキストボックスウィジェットオブジェクトを返します。 win 引数には、テキストボックスを配置する curses の ウィンドウ オブジェクトを指定する必要があります。 insert_mode が真の場合、テキストボックスは入力した文字で既存のテキストを上書きせず、右にずらして挿入します。 テキストボックスの編集カーソルは、初期状態では配置先のウィンドウの左上隅、座標 (0, 0) にあります。 インスタンスの stripspaces フラグは、初期状態ではオンです。

バージョン 3.16 で変更: Entering and reading back the full Unicode range, including combining characters, is now supported when curses is built with wide-character support.

Textbox オブジェクトは以下のメソッドを持ちます:

edit(validate=None)

これは通常使用するエントリーポイントです。 終了用のキー操作が入力されるまで、編集のキー操作を受け付けます。 validate を指定する場合は関数でなければなりません。 入力されたキー操作ごとに、そのキー操作をパラメータとしてこの関数を呼び出し、結果に基づいて実行するコマンドを決めます。 関数が偽の値を返した場合、そのキー操作は無視されます。 このメソッドはウィンドウの内容を文字列として返します。 ウィンドウ内の空白を含むかどうかは stripspaces 属性に左右されます。

バージョン 3.16 で変更: validate is now called with a non-ASCII character as a string; other keystrokes are still passed as an integer.

do_command(ch)

コマンドのキー操作を 1 つ処理します。 編集を継続する場合は 1 を、終了用のキー操作を処理した場合は 0 を返します。 サポートする特殊なキー操作は以下のとおりです:

キーストローク	動作
Control-A	ウィンドウの左端に移動します。
Control-B	カーソルを左へ移動し、必要なら前の行に折り返します。
Control-D	カーソル下の文字を削除します。
Control-E	右端 (stripspaces がオフのとき) または行末 (stripspaces がオンのとき) に移動します。
Control-F	カーソルを右に移動し、必要なら次の行に折り返します。
Control-G	ウィンドウを終了し、その内容を返します。
Control-H	逆方向に文字を削除します。
Control-J	ウィンドウが 1 行の場合は終了し、それ以外の場合は次の行の先頭に移動します。
Control-K	行が空白行ならその行全体を削除し、そうでなければカーソル以降行末までを消去します。
Control-L	スクリーンを更新します。
Control-N	カーソルを下に移動します; 1 行下に移動します。
Control-O	カーソルの場所に空行を 1 行挿入します。
Control-P	カーソルを上に移動します; 1 行上に移動します。

移動操作は、カーソルがウィンドウの縁にあって移動ができない場合には何も行いません。場合によっては、以下のような同義のキーストロークがサポートされています:

定数	キーストローク
KEY_LEFT	Control-B
KEY_RIGHT	Control-F
KEY_UP	Control-P
KEY_DOWN	Control-N
KEY_BACKSPACE	Control-h

他のキーストロークは、与えられた文字を挿入し、(行折り返し付きで) 右に移動するコマンドとして扱われます。

gather()

ウィンドウの内容を文字列として返します; ウィンドウ内の空白が含められるかどうかは stripspaces メンバ変数で決められます。

stripspaces

この属性はウィンドウ内の空白領域の解釈方法を制御するためのフラグです。フラグがオンに設定されている場合、各行の末端にある空白領域は無視されます; すなわち、末端空白領域にカーソルが入ると、その場所の代わりに行の末尾にカーソルが移動します。また、末端の空白領域はウィンドウの内容を取得する際に剥ぎ取られます。