curses - 用于字符单元显示的终端处理

源代码： Lib/curses

---

curses 模块提供了一个 curses 库的接口，curses 库是用于可移植高级终端处理的事实标准。

虽然 curses 在 Unix 环境中使用最广泛，但 Windows、DOS 以及其他系统也提供了相应的版本。此扩展模块旨在匹配 ncurses 的 API，ncurses 是一个托管在 Linux 和 BSD 变体 Unix 上的开源 curses 库。

注意

每当文档提到*字符*时，它可以指定为整数、单字符 Unicode 字符串或单字节字节字符串。

每当文档提到*字符串*时，它可以指定为 Unicode 字符串或字节字符串。

另请参阅

模块 curses.ascii

用于处理 ASCII 字符的实用程序，与您的区域设置无关。

模块 curses.panel

一个面板堆栈扩展，为 curses 窗口增加了深度。

模块 curses.textpad

curses 的可编辑文本小部件，支持类似 Emacs 的绑定。

使用 Python 进行 Curses 编程

Andrew Kuchling 和 Eric Raymond 编写的关于将 curses 与 Python 结合使用的教程材料。

函数

模块 curses 定义了以下异常

异常 curses.error

当 curses 库函数返回错误时引发的异常。

注意

每当函数或方法的 x 或 y 参数可选时，它们默认为当前光标位置。每当 attr 可选时，它默认为 A_NORMAL。

模块 curses 定义了以下函数

curses.baudrate()

以每秒位数返回终端的输出速度。在软件终端模拟器上，它将具有固定的高值。出于历史原因而包含；在以前，它被用于为时间延迟编写输出循环，偶尔也用于根据线路速度更改接口。

curses.beep()

发出短暂的提示音。

curses.can_change_color()

返回 True 或 False，具体取决于程序员是否可以更改终端显示的颜色。

curses.cbreak()

进入 cbreak 模式。在 cbreak 模式（有时称为“rare”模式）下，正常的 tty 行缓冲被关闭，并且可以逐个读取字符。但是，与原始模式不同，特殊字符（中断、退出、挂起和流控制）在 tty 驱动程序和调用程序上保留其效果。先调用 raw() 然后调用 cbreak() 会使终端处于 cbreak 模式。

curses.color_content(color_number)

返回颜色 color_number 中红色、绿色和蓝色 (RGB) 分量的强度，该颜色必须介于 0 和 COLORS - 1 之间。返回一个 3 元组，包含给定颜色的 R、G、B 值，这些值将在 0（无分量）和 1000（最大分量）之间。

curses.color_pair(pair_number)

返回以指定颜色对显示文本的属性值。仅支持前 256 种颜色对。此属性值可以与 A_STANDOUT、A_REVERSE 和其他 A_* 属性组合使用。pair_number() 是此函数的对应函数。

curses.curs_set(visibility)

设置光标状态。 visibility 可以设置为 0、1 或 2，分别表示不可见、正常或非常可见。如果终端支持请求的可见性，则返回先前的光标状态；否则引发异常。在许多终端上，“可见”模式是下划线光标，“非常可见”模式是块状光标。

curses.def_prog_mode()

将当前终端模式保存为“程序”模式，即运行程序使用 curses 时所处的模式。（与其对应的是“shell”模式，用于程序不在 curses 中时。）随后调用 reset_prog_mode() 将恢复此模式。

curses.def_shell_mode()

将当前终端模式保存为“shell”模式，即运行程序不使用 curses 时所处的模式。（与其对应的是“程序”模式，用于程序使用 curses 功能时。）随后调用 reset_shell_mode() 将恢复此模式。

curses.delay_output(ms)

在输出中插入 ms 毫秒的暂停。

curses.doupdate()

更新物理屏幕。curses 库保留了两个数据结构，一个表示当前物理屏幕内容，另一个虚拟屏幕表示所需的下一个状态。doupdate() 函数将更新物理屏幕以匹配虚拟屏幕。

在对窗口执行 addstr() 等写入操作后，可以通过调用 noutrefresh() 来更新虚拟屏幕。普通的 refresh() 调用只是 noutrefresh() 后跟 doupdate()；如果必须更新多个窗口，则可以通过在所有窗口上发出 noutrefresh() 调用，然后执行单个 doupdate() 来提高性能并可能减少屏幕闪烁。

curses.echo()

进入回显模式。在回显模式下，每个字符输入在输入时都会回显到屏幕上。

curses.endwin()

取消初始化库，并将终端恢复到正常状态。

curses.erasechar()

以单字节字节对象的形式返回用户当前的擦除字符。在 Unix 操作系统下，这是 curses 程序的控制终端的属性，而不是由 curses 库本身设置的。

curses.filter()

如果使用 filter() 例程，则必须在调用 initscr() 之前调用。其效果是，在这些调用期间，LINES 设置为 1；禁用功能 clear、cup、cud、cud1、cuu1、cuu、vpa；并将 home 字符串设置为 cr 的值。其效果是光标被限制在当前行，屏幕更新也是如此。这可以用于启用一次一个字符的行编辑，而无需触及屏幕的其余部分。

curses.flash()

闪烁屏幕。也就是说，将其更改为反向视频，然后在短时间内将其更改回。有些人更喜欢这种“可见铃声”，而不是 beep() 产生的声音提示信号。

curses.flushinp()

刷新所有输入缓冲区。这将丢弃用户已键入但程序尚未处理的所有预输入内容。

curses.getmouse()

在 getch() 返回 KEY_MOUSE 以指示鼠标事件后，应调用此方法来检索排队的鼠标事件，表示为 5 元组 (id, x, y, z, bstate)。id 是用于区分多个设备的 ID 值，x、y、z 是事件的坐标。（z 当前未使用。）bstate 是一个整数值，其位将被设置以指示事件的类型，并且将是一个或多个以下常量的按位或，其中 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.getsyx()

以元组 (y, x) 的形式返回虚拟屏幕光标的当前坐标。如果 leaveok 当前为 True，则返回 (-1, -1)。

curses.getwin(file)

读取先前 window.putwin() 调用存储在文件中的窗口相关数据。然后，该例程使用该数据创建并初始化一个新窗口，并返回新的窗口对象。

curses.has_colors()

如果终端可以显示颜色，则返回 True；否则，返回 False。

curses.has_extended_color_support()

如果模块支持扩展颜色，则返回 True；否则，返回 False。扩展颜色支持允许支持超过 16 种颜色的终端（例如 xterm-256color）使用超过 256 种颜色对。

扩展颜色支持需要 ncurses 6.1 或更高版本。

版本 3.10 中的新功能。

curses.has_ic()

如果终端具有插入和删除字符功能，则返回 True。包含此函数仅出于历史原因，因为所有现代软件终端仿真器都具有此类功能。

curses.has_il()

如果终端具有插入和删除行功能，或者可以使用滚动区域模拟它们，则返回 True。包含此函数仅出于历史原因，因为所有现代软件终端仿真器都具有此类功能。

curses.has_key(ch)

获取键值 ch，如果当前终端类型识别具有该值的键，则返回 True。

curses.halfdelay(tenths)

用于半延迟模式，该模式类似于 cbreak 模式，因为用户键入的字符可立即被程序使用。但是，在阻塞 tenths 十分之一秒后，如果没有键入任何内容，则引发异常。 tenths 的值必须介于 1 和 255 之间。使用 nocbreak() 退出半延迟模式。

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

更改颜色的定义，采用要更改的颜色编号，后跟三个 RGB 值（分别表示红色、绿色和蓝色分量的数量）。 color_number 的值必须介于 0 和 COLORS - 1 之间。 r、g、b 中的每一个都必须是介于 0 和 1000 之间的值。使用 init_color() 时，屏幕上该颜色的所有实例都会立即更改为新定义。此函数在大多数终端上是无操作的；仅当 can_change_color() 返回 True 时，它才处于活动状态。

curses.init_pair(pair_number, fg, bg)

更改颜色对的定义。它采用三个参数：要更改的颜色对的编号、前景色编号和背景色编号。 pair_number 的值必须介于 1 和 COLOR_PAIRS - 1 之间（0 颜色对连接到黑色上的白色，无法更改）。 fg 和 bg 参数的值必须介于 0 和 COLORS - 1 之间，或者在调用 use_default_colors() 后为 -1。如果之前已初始化颜色对，则会刷新屏幕，并且该颜色对的所有实例都将更改为新定义。

curses.initscr()

初始化库。返回一个表示整个屏幕的 窗口 对象。

注意

如果在打开终端时出错，则底层的 curses 库可能会导致解释器退出。

curses.is_term_resized(nlines, ncols)

如果 resize_term() 将修改窗口结构，则返回 True，否则返回 False。

curses.isendwin()

如果已调用 endwin()（即 curses 库已取消初始化），则返回 True。

curses.keyname(k)

以字节对象形式返回编号为 k 的键的名称。生成可打印 ASCII 字符的键的名称是该键的字符。控制键组合的名称是一个两字节的字节对象，由一个插入符号 (b'^') 和相应的可打印 ASCII 字符组成。 Alt 键组合 (128–255) 的名称是一个字节对象，由前缀 b'M-' 和相应的 ASCII 字符的名称组成。

curses.killchar()

以一个字节的字节对象形式返回用户当前的行删除字符。在 Unix 操作系统下，这是 curses 程序的控制 tty 的属性，而不是由 curses 库本身设置的。

curses.longname()

返回一个字节对象，其中包含描述当前终端的 terminfo 长名称字段。详细描述的最大长度为 128 个字符。它仅在调用 initscr() 后定义。

curses.meta(flag)

如果 flag 为 True，则允许输入 8 位字符。 如果 flag 为 False，则仅允许 7 位字符。

curses.mouseinterval(interval)

设置按下和释放事件之间可以经过的最大时间（以毫秒为单位），以便将它们识别为单击，并返回之前的间隔值。 默认值为 200 毫秒，即五分之一秒。

curses.mousemask(mousemask)

设置要报告的鼠标事件，并返回一个元组 (availmask, oldmask)。 availmask 指示可以报告指定的鼠标事件中的哪些；如果完全失败，则返回 0。 oldmask 是给定窗口的鼠标事件掩码的先前值。 如果从未调用此函数，则永远不会报告鼠标事件。

curses.napms(ms)

休眠 ms 毫秒。

curses.newpad(nlines, ncols)

创建一个新填充数据结构的指针，并返回该指针，该数据结构具有给定的行数和列数。 返回一个作为窗口对象的填充。

填充类似于窗口，不同之处在于它不受屏幕大小的限制，并且不一定与屏幕的特定部分相关联。 当需要一个大窗口，并且一次只显示窗口的一部分时，可以使用填充。 不会自动刷新填充（例如，滚动或输入回显）。 填充的 refresh() 和 noutrefresh() 方法需要 6 个参数来指定要显示的填充部分和要在屏幕上用于显示的位置。 参数为 pminrow、pmincol、sminrow、smincol、smaxrow、smaxcol；p 参数指的是要显示的填充区域的左上角，s 参数定义了要在其中显示填充区域的屏幕上的剪切框。

curses.newwin(nlines, ncols)

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

返回一个新 窗口，其左上角位于 (begin_y, begin_x)，高度/宽度为 nlines/ncols。

默认情况下，窗口将从指定位置扩展到屏幕的右下角。

curses.nl()

进入换行模式。 此模式在输入时将回车键转换为换行符，并在输出时将换行符转换为回车符和换行符。 换行模式最初处于启用状态。

curses.nocbreak()

退出 cbreak 模式。 返回到具有行缓冲的正常“熟”模式。

curses.noecho()

退出回显模式。 关闭输入字符的回显。

curses.nonl()

退出换行模式。 禁用在输入时将回车符转换为换行符，并禁用在输出时将换行符转换为换行符/回车符的低级转换（但这不会更改 addch('\n') 的行为，该行为始终在虚拟屏幕上执行等效的回车和换行）。 禁用转换后，curses 有时可以稍微加快垂直移动速度； 此外，它将能够检测输入时的回车键。

curses.noqiflush()

使用 noqiflush() 例程时，将不会执行与 INTR、QUIT 和 SUSP 字符关联的输入和输出队列的正常刷新。 如果希望在处理程序退出后输出像未发生中断一样继续，则可能希望在信号处理程序中调用 noqiflush()。

curses.noraw()

退出原始模式。 返回到具有行缓冲的正常“熟”模式。

curses.pair_content(pair_number)

返回一个元组 (fg, bg)，其中包含请求的颜色对的颜色。 pair_number 的值必须介于 0 和 COLOR_PAIRS - 1 之间。

curses.pair_number(attr)

返回由属性值 attr 设置的颜色对的编号。 color_pair() 是此函数的对应函数。

curses.putp(str)

等效于 tputs(str, 1, putchar)；为当前终端输出指定 terminfo 功能的值。请注意，putp() 的输出始终发送到标准输出。

curses.qiflush([flag])

如果 flag 为 False，则效果与调用 noqiflush() 相同。如果 flag 为 True，或未提供参数，则在读取这些控制字符时将刷新队列。

curses.raw()

进入原始模式。在原始模式下，将关闭正常的行缓冲和中断、退出、挂起和流控制键的处理；字符将逐个呈现给 curses 输入函数。

curses.reset_prog_mode()

将终端恢复到 def_prog_mode() 先前保存的“程序”模式。

curses.reset_shell_mode()

将终端恢复到 def_shell_mode() 先前保存的“shell”模式。

curses.resetty()

将终端模式的状态恢复为上次调用 savetty() 时的状态。

curses.resize_term(nlines, ncols)

resizeterm() 使用的后端函数，执行大部分工作；调整窗口大小时，resize_term() 会用空格填充扩展的区域。调用应用程序应使用适当的数据填充这些区域。resize_term() 函数尝试调整所有窗口的大小。但是，由于 pad 的调用约定，如果没有与应用程序的额外交互，则无法调整它们的大小。

curses.resizeterm(nlines, ncols)

将标准窗口和当前窗口的大小调整为指定的尺寸，并调整 curses 库使用的其他记录窗口尺寸的簿记数据（特别是 SIGWINCH 处理程序）。

curses.savetty()

将终端模式的当前状态保存在缓冲区中，可由 resetty() 使用。

curses.get_escdelay()

检索 set_escdelay() 设置的值。

3.9 版新增。

curses.set_escdelay(ms)

设置读取转义字符后要等待的毫秒数，以区分在键盘上输入的单个转义字符与光标和功能键发送的转义序列。

3.9 版新增。

curses.get_tabsize()

检索 set_tabsize() 设置的值。

3.9 版新增。

curses.set_tabsize(size)

设置 curses 库在将制表符转换为空格时使用的列数，因为它将制表符添加到窗口中。

3.9 版新增。

curses.setsyx(y, x)

将虚拟屏幕光标设置为 y、x。如果 y 和 x 均为 -1，则 leaveok 设置为 True。

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

初始化终端。term 是一个字符串，给出终端名称，或者为 None；如果省略或为 None，则将使用 TERM 环境变量的值。fd 是将向其发送任何初始化序列的文件描述符；如果未提供或为 -1，则将使用 sys.stdout 的文件描述符。

curses.start_color()

如果程序员想要使用颜色，则必须先调用此例程，然后再调用任何其他颜色操作例程。最佳做法是在 initscr() 之后立即调用此例程。

start_color() 初始化八种基本颜色（黑、红、绿、黄、蓝、洋红、青和白），并在 curses 模块中初始化两个全局变量，COLORS 和 COLOR_PAIRS，分别包含终端可支持的最大颜色数和颜色对数。它还会将终端上的颜色恢复为刚打开终端时的值。

curses.termattrs()

返回终端支持的所有视频属性的逻辑或。当 curses 程序需要完全控制屏幕外观时，此信息非常有用。

curses.termname()

返回环境变量 TERM 的值，作为字节对象，截断为 14 个字符。

curses.tigetflag(capname)

以整数形式返回与 terminfo 功能名称 *capname* 对应的布尔功能的值。如果 *capname* 不是布尔功能，则返回值 -1；如果它在终端描述中被取消或不存在，则返回值 0。

curses.tigetnum(capname)

以整数形式返回与 terminfo 功能名称 *capname* 对应的数字功能的值。如果 *capname* 不是数字功能，则返回值 -2；如果它在终端描述中被取消或不存在，则返回值 -1。

curses.tigetstr(capname)

以字节对象形式返回与 terminfo 功能名称 *capname* 对应的字符串功能的值。如果 *capname* 不是 terminfo“字符串功能”，或者在终端描述中被取消或不存在，则返回 None。

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

使用提供的参数实例化字节对象 *str*，其中 *str* 应该是从 terminfo 数据库获取的参数化字符串。例如，tparm(tigetstr("cup"), 5, 3) 可能会产生 b'\033[6;4H'，确切结果取决于终端类型。

curses.typeahead(fd)

指定文件描述符 *fd* 用于预输入检查。如果 *fd* 为 -1，则不进行预输入检查。

curses 库通过在更新屏幕时定期查找预输入来进行“换行优化”。如果找到输入，并且它来自 tty，则当前更新将被推迟，直到再次调用 refresh 或 doupdate，从而可以更快地响应预先键入的命令。此函数允许为预输入检查指定不同的文件描述符。

curses.unctrl(ch)

返回一个字节对象，它是字符 *ch* 的可打印表示形式。控制字符表示为一个插入符号后跟该字符，例如 b'^C'。打印字符保持原样。

curses.ungetch(ch)

推送 *ch*，以便下一个 getch() 将返回它。

注意

在调用 getch() 之前，只能推送一个 *ch*。

curses.update_lines_cols()

更新 LINES 和 COLS 模块变量。用于检测手动屏幕大小调整。

3.5 版新增。

curses.unget_wch(ch)

推送 *ch*，以便下一个 get_wch() 将返回它。

注意

在调用 get_wch() 之前，只能推送一个 *ch*。

3.3 版新增。

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

将 KEY_MOUSE 事件推送到输入队列，并将给定的状态数据与其关联。

curses.use_env(flag)

如果使用此函数，则应在调用 initscr() 或 newterm 之前调用。当 *flag* 为 False 时，将使用 terminfo 数据库中指定的行数和列数，即使设置了环境变量 LINES 和 COLUMNS（默认使用），或者 curses 在窗口中运行（在这种情况下，如果未设置 LINES 和 COLUMNS，则默认行为是使用窗口大小）。

curses.use_default_colors()

允许在支持此功能的终端上使用默认颜色值。使用此功能可以在应用程序中支持透明度。默认颜色分配给颜色编号 -1。调用此函数后，例如，init_pair(x, curses.COLOR_RED, -1) 将颜色对 *x* 初始化为默认背景上的红色前景颜色。

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

初始化 curses 并调用另一个可调用对象 *func*，该对象应该是使用 curses 的应用程序的其余部分。如果应用程序引发异常，此函数将在重新引发异常并生成回溯之前将终端恢复到正常状态。然后，可调用对象 *func* 将主窗口“stdscr”作为其第一个参数传递，然后是传递给 wrapper() 的任何其他参数。在调用 *func* 之前，wrapper() 会打开 cbreak 模式，关闭回显，启用终端键盘，并在终端支持颜色的情况下初始化颜色。退出时（无论是正常退出还是因异常退出），它都会恢复 cooked 模式，打开回显并禁用终端键盘。

窗口对象

窗口对象（由上面的 initscr() 和 newwin() 返回）具有以下方法和属性

window.addch(ch[, attr])

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

在 (y, x) 处绘制字符 *ch*，并带有属性 *attr*，覆盖之前在该位置绘制的任何字符。默认情况下，字符位置和属性是窗口对象的当前设置。

注意

在窗口、子窗口或填充区之外写入会引发 curses.error。尝试写入窗口、子窗口或填充区的右下角将在打印字符后引发异常。

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

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

在 (y, x) 处绘制字符串 *str* 的最多 *n* 个字符，并带有属性 *attr*，覆盖之前显示的任何内容。

window.addstr(str[, attr])

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

在 (y, x) 处绘制字符串 *str*，并带有属性 *attr*，覆盖之前显示的任何内容。

注意

• 在窗口、子窗口或填充区之外写入会引发 curses.error。尝试写入窗口、子窗口或填充区的右下角将在打印字符串后引发异常。

• 此 Python 模块的后端 ncurses 中的一个错误在调整窗口大小时可能会导致段错误。这已在 ncurses-6.1-20190511 中修复。如果您使用的是较早版本的 ncurses，则可以通过不在调用 addstr() 时使用嵌入了换行符的 *str* 来避免触发此错误。而是为每一行分别调用 addstr()。

window.attroff(attr)

从应用于当前窗口的所有写入的“背景”集中删除属性 *attr*。

window.attron(attr)

将属性 *attr* 从应用于当前窗口的所有写入的“背景”集中添加。

window.attrset(attr)

将“背景”属性集设置为 *attr*。此集最初为 0（无属性）。

window.bkgd(ch[, attr])

将窗口的背景属性设置为字符 *ch*，并带有属性 *attr*。然后将更改应用于该窗口中的每个字符位置

• 窗口中每个字符的属性都将更改为新的背景属性。

• 无论先前背景字符出现在哪里，都将更改为新的背景字符。

window.bkgdset(ch[, attr])

设置窗口的背景。窗口的背景由一个字符和任何属性组合组成。背景的属性部分与写入窗口的所有非空白字符组合（或运算）。背景的字符部分和属性部分都与空白字符组合。背景成为字符的属性，并通过任何滚动和插入/删除行/字符操作随字符移动。

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

在窗口边缘绘制边框。每个参数指定用于边框特定部分的字符；有关更多详细信息，请参见下表。

注意

任何参数值为 0 将导致对该参数使用默认字符。不能使用关键字参数。默认值列在此表中

参数	描述	默认值
ls	左侧	ACS_VLINE
rs	右侧	ACS_VLINE
ts	顶部	ACS_HLINE
bs	底部	ACS_HLINE
tl	左上角	ACS_ULCORNER
tr	右上角	ACS_URCORNER
bl	左下角	ACS_LLCORNER
br	右下角	ACS_LRCORNER

window.box([vertch, horch])

与 border() 类似，但 ls 和 rs 都是 vertch，ts 和 bs 都是 horch。此函数始终使用默认的角字符。

window.chgat(attr)

window.chgat(num, attr)

window.chgat(y, x, attr)

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

设置当前光标位置处 num 个字符的属性，如果提供，则设置位置 (y, x) 处的属性。如果未给出 num 或为 -1，则该属性将设置在从当前位置到行尾的所有字符上。如果提供，此函数会将光标移动到位置 (y, x)。更改后的行将使用 touchline() 方法进行标记，以便在下一次窗口刷新时重新显示内容。

window.clear()

与 erase() 类似，但也会导致在下次调用 refresh() 时重绘整个窗口。

window.clearok(flag)

如果 flag 为 True，则下次调用 refresh() 将完全清除窗口。

window.clrtobot()

从光标擦除到窗口末尾：删除光标下方的所有行，然后执行与 clrtoeol() 等效的操作。

window.clrtoeol()

从光标擦除到行尾。

window.cursyncup()

更新窗口所有祖先的当前光标位置，以反映窗口的当前光标位置。

window.delch([y, x])

删除 (y, x) 处的任何字符。

window.deleteln()

删除光标所在的行。以下所有行都向上移动一行。

window.derwin(begin_y, begin_x)

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

“派生窗口”的缩写，derwin() 与调用 subwin() 相同，只是 begin_y 和 begin_x 是相对于窗口原点的，而不是相对于整个屏幕的。返回派生窗口的窗口对象。

window.echochar(ch[, attr])

添加具有属性 attr 的字符 ch，并立即在窗口上调用 refresh()。

window.enclose(y, x)

测试给定的屏幕相对字符单元坐标对是否被给定窗口包围，返回 True 或 False。这对于确定哪些屏幕窗口子集包含鼠标事件的位置非常有用。

在 3.10 版更改: 之前返回 1 或 0 而不是 True 或 False。

window.encoding

用于对方法参数（Unicode 字符串和字符）进行编码的编码。例如，使用 window.subwin() 创建子窗口时，encoding 属性将从父窗口继承。默认情况下，使用当前的区域设置编码（请参阅 locale.getencoding()）。

3.3 版新增。

window.erase()

清除窗口。

window.getbegyx()

返回一个表示左上角坐标的元组 (y, x)。

window.getbkgd()

返回给定窗口当前的背景字符/属性对。

window.getch([y, x])

获取一个字符。请注意，返回的整数不一定在 ASCII 范围内：功能键、键盘键等由大于 255 的数字表示。在非延迟模式下，如果没有输入，则返回 -1，否则等待按键按下。

window.get_wch([y, x])

获取一个宽字符。对于大多数键，返回一个字符；对于功能键、键盘键和其他特殊键，返回一个整数。在非延迟模式下，如果没有输入，则引发异常。

3.3 版新增。

window.getkey([y, x])

获取一个字符，返回一个字符串而不是像 getch() 那样返回一个整数。功能键、键盘键和其他特殊键返回一个包含键名的多字节字符串。在非延迟模式下，如果没有输入，则引发异常。

window.getmaxyx()

返回一个表示窗口高度和宽度的元组 (y, x)。

window.getparyx()

返回此窗口相对于其父窗口的起始坐标，以元组 (y, x) 的形式。如果此窗口没有父窗口，则返回 (-1, -1)。

window.getstr()

window.getstr(n)

window.getstr(y, x)

window.getstr(y, x, n)

从用户读取一个字节对象，具有基本的行编辑功能。

window.getyx()

返回一个表示当前光标位置（相对于窗口左上角）的元组 (y, x)。

window.hline(ch, n)

window.hline(y, x, ch, n)

显示一条从 (y, x) 开始、长度为 n、由字符 ch 组成的水平线。

window.idcok(flag)

如果 flag 为 False，则 curses 不再考虑使用终端的硬件插入/删除字符功能；如果 flag 为 True，则启用字符插入和删除功能。首次初始化 curses 时，默认启用字符插入/删除功能。

window.idlok(flag)

如果 flag 为 True，则 curses 将尝试使用硬件行编辑功能。否则，将禁用行插入/删除功能。

window.immedok(flag)

如果 flag 为 True，则窗口图像中的任何更改都会自动导致窗口刷新；您不再需要自己调用 refresh()。但是，由于重复调用 wrefresh，它可能会大大降低性能。默认情况下禁用此选项。

window.inch([y, x])

返回窗口中给定位置的字符。低 8 位是字符本身，高位是属性。

window.insch(ch[, attr])

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

在 (y, x) 处绘制字符 ch，并使用属性 attr，将从位置 x 开始的行向右移动一个字符。

window.insdelln(nlines)

在当前行上方指定的窗口中插入 nlines 行。底部 nlines 行将丢失。对于负的 nlines，从光标下方的一行开始删除 nlines 行，并将剩余的行向上移动。底部 nlines 行将被清除。当前光标位置保持不变。

window.insertln()

在光标下方插入一个空行。所有后续行都向下移动一行。

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

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

在光标下的字符之前插入一个字符串（尽可能多的字符以适合该行），最多插入 n 个字符。如果 n 为零或负数，则插入整个字符串。光标右侧的所有字符都将向右移动，该行最右侧的字符将丢失。光标位置不会改变（如果指定，则在移动到 y、x 后）。

window.insstr(str[, attr])

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

在光标下的字符之前插入一个字符串（尽可能多的字符以适合该行）。光标右侧的所有字符都将向右移动，该行最右侧的字符将丢失。光标位置不会改变（如果指定，则在移动到 y、x 后）。

window.instr([n])

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

返回一个字节对象，其中包含从当前光标位置或指定的 y、x 开始从窗口中提取的字符。字符的属性将被剥离。如果指定了 n，则 instr() 将返回一个长度不超过 n 个字符的字符串（不包括尾随的 NUL）。

window.is_linetouched(line)

如果自上次调用 refresh() 后修改了指定的行，则返回 True；否则返回 False。如果 line 对于给定的窗口无效，则引发 curses.error 异常。

window.is_wintouched()

如果自上次调用 refresh() 后修改了指定的窗口，则返回 True；否则返回 False。

window.keypad(flag)

如果 flag 为 True，则某些键（键盘、功能键）生成的转义序列将由 curses 解释。如果 flag 为 False，则转义序列将按原样保留在输入流中。

window.leaveok(flag)

如果 flag 为 True，则光标在更新时保持原位，而不是位于“光标位置”。这将尽可能减少光标移动。如果可能，光标将变为不可见。

如果 flag 为 False，则光标在更新后将始终位于“光标位置”。

window.move(new_y, new_x)

将光标移动到 (new_y, new_x)。

window.mvderwin(y, x)

在父窗口内移动窗口。窗口的屏幕相对参数不会改变。此例程用于在屏幕上的相同物理位置显示父窗口的不同部分。

window.mvwin(new_y, new_x)

移动窗口，使其左上角位于 (new_y, new_x)。

window.nodelay(flag)

如果 *flag* 为 True，则 getch() 将是非阻塞的。

window.notimeout(flag)

如果 *flag* 为 True，则转义序列不会超时。

如果 *flag* 为 False，则几毫秒后，转义序列将不会被解释，并将按原样保留在输入流中。

window.noutrefresh()

标记为刷新但等待。此函数更新表示窗口所需状态的数据结构，但不强制更新物理屏幕。要完成此操作，请调用 doupdate()。

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

将窗口叠加在 *destwin* 之上。窗口不必大小相同，仅复制重叠区域。此复制是非破坏性的，这意味着当前背景字符不会覆盖 *destwin* 的旧内容。

要对复制区域进行细粒度控制，可以使用 overlay() 的第二种形式。*sminrow* 和 *smincol* 是源窗口的左上角坐标，其他变量标记目标窗口中的一个矩形。

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

将窗口覆盖在 *destwin* 之上。窗口不必大小相同，在这种情况下，仅复制重叠区域。此复制是破坏性的，这意味着当前背景字符会覆盖 *destwin* 的旧内容。

要对复制区域进行细粒度控制，可以使用 overwrite() 的第二种形式。*sminrow* 和 *smincol* 是源窗口的左上角坐标，其他变量标记目标窗口中的一个矩形。

window.putwin(file)

将与窗口关联的所有数据写入提供的文件对象。可以使用 getwin() 函数检索此信息。

window.redrawln(beg, num)

指示从第 *beg* 行开始的 *num* 个屏幕行已损坏，应在下一次 refresh() 调用时完全重绘。

window.redrawwin()

触摸整个窗口，使其在下一次 refresh() 调用时完全重绘。

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

立即更新显示（将实际屏幕与之前的绘图/删除方法同步）。

仅当窗口是使用 newpad() 创建的填充区时，才能指定 6 个可选参数。需要附加参数来指示填充区和屏幕的哪些部分参与其中。*pminrow* 和 *pmincol* 指定要显示在填充区中的矩形的左上角。*sminrow*、*smincol*、*smaxrow* 和 *smaxcol* 指定要显示在屏幕上的矩形的边缘。要显示在填充区中的矩形的右下角是根据屏幕坐标计算的，因为矩形的大小必须相同。两个矩形必须完全包含在它们各自的结构中。*pminrow*、*pmincol*、*sminrow* 或 *smincol* 的负值将被视为零。

window.resize(nlines, ncols)

重新分配 curses 窗口的存储空间，以将其维度调整为指定的值。如果任一维度大于当前值，则窗口的数据将填充具有当前背景渲染（由 bkgdset() 设置）的空格。

window.scroll([lines=1])

将屏幕或滚动区域向上滚动 *lines* 行。

window.scrollok(flag)

控制当窗口的光标移动到窗口或滚动区域边缘时会发生什么，这可能是由于在最后一行执行换行操作或键入最后一行的最后一个字符造成的。如果 *flag* 为 False，则光标停留在最后一行。如果 *flag* 为 True，则窗口向上滚动一行。请注意，为了在终端上获得物理滚动效果，还需要调用 idlok()。

window.setscrreg(top, bottom)

设置从 *top* 行到 *bottom* 行的滚动区域。所有滚动操作都将在该区域内进行。

window.standend()

关闭突出显示属性。在某些终端上，这会产生关闭所有属性的副作用。

window.standout()

打开属性 *A_STANDOUT*。

window.subpad(begin_y, begin_x)

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

返回一个子窗口，其左上角位于 (begin_y, begin_x)，宽度/高度为 *ncols*/*nlines*。

window.subwin(begin_y, begin_x)

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

返回一个子窗口，其左上角位于 (begin_y, begin_x)，宽度/高度为 *ncols*/*nlines*。

默认情况下，子窗口将从指定位置扩展到窗口的右下角。

window.syncdown()

触摸窗口中所有在其任何祖先窗口中被触摸过的位置。此例程由 refresh() 调用，因此几乎不需要手动调用它。

window.syncok(flag)

如果 *flag* 为 True，则每当窗口发生更改时，都会自动调用 syncup()。

window.syncup()

触摸窗口祖先中所有在窗口中已更改的位置。

window.timeout(delay)

设置窗口的阻塞或非阻塞读取行为。如果 *delay* 为负数，则使用阻塞读取（将无限期地等待输入）。如果 *delay* 为零，则使用非阻塞读取，并且如果无输入等待，则 getch() 将返回 -1。如果 *delay* 为正数，则 getch() 将阻塞 *delay* 毫秒，并在该时间结束时仍无输入，则返回 -1。

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

假定从 *start* 行开始的 *count* 行已更改。如果提供了 *changed*，则它指定受影响的行是否标记为已更改（*changed* =True）或未更改（*changed* =False）。

window.touchwin()

为了绘图优化的目的，假定整个窗口已更改。

window.untouchwin()

将窗口中的所有行标记为自上次调用 refresh() 以来未更改。

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

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

显示一条从 (y, x) 开始、长度为 *n* 的垂直线，该线由字符 *ch* 组成，属性为 *attr*。

常量

curses 模块定义以下数据成员

curses.ERR

一些返回整数的 curses 例程，例如 getch()，在失败时返回 ERR。

curses.OK

一些返回整数的 curses 例程，例如 napms()，在成功时返回 OK。

curses.version

curses.__version__

表示模块当前版本的字节对象。

curses.ncurses_version

一个命名元组，包含 ncurses 库版本号的三个组成部分：*major*、*minor* 和 *patch*。所有值均为整数。也可以通过名称访问这些组成部分，因此 curses.ncurses_version[0] 等效于 curses.ncurses_version.major，依此类推。

可用性：如果使用了 ncurses 库。

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() 更新。

一些常量可用于指定字符单元格属性。可用的确切常量取决于系统。

属性	含义
curses.A_ALTCHARSET	备用字符集模式
curses.A_BLINK	闪烁模式
curses.A_BOLD	粗体模式
curses.A_DIM	暗淡模式
curses.A_INVIS	不可见或空白模式
curses.A_ITALIC	斜体模式
curses.A_NORMAL	普通属性
curses.A_PROTECT	保护模式
curses.A_REVERSE	反转背景和前景颜色
curses.A_STANDOUT	突出显示模式
curses.A_UNDERLINE	下划线模式
curses.A_HORIZONTAL	水平高亮
curses.A_LEFT	左侧高亮
curses.A_LOW	低亮度
curses.A_RIGHT	右侧高亮
curses.A_TOP	顶部高亮
curses.A_VERTICAL	垂直高亮

3.7 版新增： 添加了 A_ITALIC。

可以使用多个常量来提取某些方法返回的相应属性。

位掩码	含义
curses.A_ATTRIBUTES	用于提取属性的位掩码
curses.A_CHARTEXT	用于提取字符的位掩码
curses.A_COLOR	用于提取颜色对字段信息的位掩码

键通过以 KEY_ 开头的名称的整型常量来引用。可用的确切键帽取决于系统。

键常量	键
curses.KEY_MIN	最小键值
curses.KEY_BREAK	中断键（不可靠）
curses.KEY_DOWN	向下箭头
curses.KEY_UP	向上箭头
curses.KEY_LEFT	向左箭头
curses.KEY_RIGHT	向右箭头
curses.KEY_HOME	Home 键（向上+向左箭头）
curses.KEY_BACKSPACE	退格键（不可靠）
curses.KEY_F0	功能键。最多支持 64 个功能键。
curses.KEY_Fn	功能键 n 的值
curses.KEY_DL	删除行
curses.KEY_IL	插入行
curses.KEY_DC	删除字符
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	下一页
curses.KEY_PPAGE	上一页
curses.KEY_STAB	设置制表符
curses.KEY_CTAB	清除制表符
curses.KEY_CATAB	清除所有制表符
curses.KEY_ENTER	回车或发送（不可靠）
curses.KEY_SRESET	软（部分）重置（不可靠）
curses.KEY_RESET	重置或硬重置（不可靠）
curses.KEY_PRINT	打印
curses.KEY_LL	向下翻页或底部（左下）
curses.KEY_A1	小键盘左上角
curses.KEY_A3	小键盘右上角
curses.KEY_B2	小键盘中心
curses.KEY_C1	小键盘左下角
curses.KEY_C3	小键盘右下角
curses.KEY_BTAB	后退一个制表符
curses.KEY_BEG	开头
curses.KEY_CANCEL	取消
curses.KEY_CLOSE	关闭
curses.KEY_COMMAND	命令
curses.KEY_COPY	复制
curses.KEY_CREATE	创建
curses.KEY_END	结束
curses.KEY_EXIT	退出
curses.KEY_FIND	查找
curses.KEY_HELP	帮助
curses.KEY_MARK	标记
curses.KEY_MESSAGE	消息
curses.KEY_MOVE	移动
curses.KEY_NEXT	下一个
curses.KEY_OPEN	打开
curses.KEY_OPTIONS	选项
curses.KEY_PREVIOUS	上一步（前一个）
curses.KEY_REDO	重做
curses.KEY_REFERENCE	引用（参考）
curses.KEY_REFRESH	刷新
curses.KEY_REPLACE	替换
curses.KEY_RESTART	重启
curses.KEY_RESUME	恢复
curses.KEY_SAVE	保存
curses.KEY_SBEG	Shift + 开始
curses.KEY_SCANCEL	Shift + 取消
curses.KEY_SCOMMAND	Shift + 命令
curses.KEY_SCOPY	Shift + 复制
curses.KEY_SCREATE	Shift + 创建
curses.KEY_SDC	Shift + 删除字符
curses.KEY_SDL	Shift + 删除行
curses.KEY_SELECT	选择
curses.KEY_SEND	Shift + 结束
curses.KEY_SEOL	Shift + 清除行
curses.KEY_SEXIT	Shift + 退出
curses.KEY_SFIND	Shift + 查找
curses.KEY_SHELP	Shift + 帮助
curses.KEY_SHOME	Shift + 主页
curses.KEY_SIC	Shift + 输入
curses.KEY_SLEFT	Shift + 左箭头
curses.KEY_SMESSAGE	Shift + 消息
curses.KEY_SMOVE	Shift + 移动
curses.KEY_SNEXT	Shift + 下一步
curses.KEY_SOPTIONS	Shift + 选项
curses.KEY_SPREVIOUS	Shift + 上一步
curses.KEY_SPRINT	Shift + 打印
curses.KEY_SREDO	Shift + 重做
curses.KEY_SREPLACE	Shift + 替换
curses.KEY_SRIGHT	Shift + 右箭头
curses.KEY_SRSUME	Shift + 恢复
curses.KEY_SSAVE	Shift + 保存
curses.KEY_SSUSPEND	Shift + 挂起
curses.KEY_SUNDO	Shift + 撤销
curses.KEY_SUSPEND	挂起
curses.KEY_UNDO	撤销
curses.KEY_MOUSE	鼠标事件已发生
curses.KEY_RESIZE	终端大小调整事件
curses.KEY_MAX	最大键值

在 VT100 及其软件仿真（例如 X 终端仿真器）上，通常至少有四个功能键（KEY_F1、KEY_F2、KEY_F3、KEY_F4）可用，并且箭头键以显而易见的方式映射到 KEY_UP、KEY_DOWN、KEY_LEFT 和 KEY_RIGHT。如果您的机器有 PC 键盘，则可以安全地预期箭头键和十二个功能键（较旧的 PC 键盘可能只有十个功能键）；此外，以下键盘映射是标准的

键帽	常量
插入	KEY_IC
删除	KEY_DC
主页	KEY_HOME
结束	KEY_END
向上翻页	KEY_PPAGE
向下翻页	KEY_NPAGE

下表列出了备用字符集中的字符。 这些字符继承自 VT100 终端，通常在 X 终端等软件仿真中可用。 当没有可用的图形时，curses 会使用粗略的可打印 ASCII 字符进行近似。

注意

这些字符仅在调用 initscr() 后才可用。

ACS 代码	含义
curses.ACS_BBSS	右上角的别名
curses.ACS_BLOCK	实心方形块
curses.ACS_BOARD	方形板
curses.ACS_BSBS	水平线的别名
curses.ACS_BSSB	左上角的别名
curses.ACS_BSSS	上三通的别名
curses.ACS_BTEE	下三通
curses.ACS_BULLET	项目符号
curses.ACS_CKBOARD	棋盘（阴影线）
curses.ACS_DARROW	向下箭头
curses.ACS_DEGREE	度数符号
curses.ACS_DIAMOND	菱形
curses.ACS_GEQUAL	大于等于
curses.ACS_HLINE	水平线
curses.ACS_LANTERN	灯笼符号
curses.ACS_LARROW	左箭头
curses.ACS_LEQUAL	小于等于
curses.ACS_LLCORNER	左下角
curses.ACS_LRCORNER	右下角
curses.ACS_LTEE	左三通
curses.ACS_NEQUAL	不等于号
curses.ACS_PI	字母 π
curses.ACS_PLMINUS	正负号
curses.ACS_PLUS	大加号
curses.ACS_RARROW	右箭头
curses.ACS_RTEE	右三通
curses.ACS_S1	扫描线 1
curses.ACS_S3	扫描线 3
curses.ACS_S7	扫描线 7
curses.ACS_S9	扫描线 9
curses.ACS_SBBS	右下角的别名
curses.ACS_SBSB	垂直线的别名
curses.ACS_SBSS	右三通的别名
curses.ACS_SSBB	左下角的别名
curses.ACS_SSBS	下三通的别名
curses.ACS_SSSB	左三通的别名
curses.ACS_SSSS	交叉或大加号的别名
curses.ACS_STERLING	英镑符号
curses.ACS_TTEE	上三通
curses.ACS_UARROW	向上箭头
curses.ACS_ULCORNER	左上角
curses.ACS_URCORNER	右上角
curses.ACS_VLINE	垂直线

下表列出了 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	按钮状态改变时按下了 Ctrl 键
curses.BUTTON_ALT	按钮状态改变时按下了 Ctrl 键

在 3.10 版更改: 如果底层 curses 库提供，则现在会公开 BUTTON5_* 常量。

下表列出了预定义的颜色

常量	颜色
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 模块提供了一个 Textbox 类，用于处理 curses 窗口中的基本文本编辑，支持一组类似于 Emacs（因此也类似于 Netscape Navigator、BBedit 6.x、FrameMaker 和许多其他程序）的键绑定。该模块还提供了一个矩形绘制函数，可用于构建文本框或用于其他目的。

模块 curses.textpad 定义了以下函数

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

绘制一个矩形。第一个参数必须是一个窗口对象；其余参数是相对于该窗口的坐标。第二个和第三个参数是要绘制的矩形左上角的 y 和 x 坐标；第四个和第五个参数是右下角的 y 和 x 坐标。矩形将使用 VT100/IBM PC 表格字符在支持此功能的终端上绘制（包括 xterm 和大多数其他软件终端模拟器）。否则，它将使用 ASCII 破折号、竖线和加号绘制。

Textbox 对象

您可以按如下方式实例化 Textbox 对象

class curses.textpad.Textbox(win)

返回一个文本框小部件对象。win 参数应该是一个 curses 窗口 对象，文本框将包含在该窗口中。文本框的编辑光标最初位于包含窗口的左上角，坐标为 (0, 0)。实例的 stripspaces 标志最初处于启用状态。

Textbox 对象具有以下方法

edit([validator])

这是您通常使用的入口点。它接受编辑击键，直到输入其中一个终止击键。如果提供了 validator，则它必须是一个函数。它将在输入每个击键时调用，并将击键作为参数；命令调度是根据结果完成的。此方法以字符串形式返回窗口内容；窗口中是否包含空格受 stripspaces 属性的影响。

do_command(ch)

处理单个命令击键。以下是支持的特殊击键

击键	操作
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	光标向下移动；向下移动一行。
Control-O	在光标位置插入一个空行。
Control-P	光标向上移动；向上移动一行。

如果光标位于无法移动的边缘，则移动操作无效。在可能的情况下，支持以下同义词

常量	击键
KEY_LEFT	Control-B
KEY_RIGHT	Control-F
KEY_UP	Control-P
KEY_DOWN	Control-N
KEY_BACKSPACE	Control-h

所有其他按键都被视为插入给定字符并向右移动（自动换行）的命令。

gather()

以字符串形式返回窗口内容；窗口中是否包含空格受 stripspaces 成员的影响。

stripspaces

此属性是一个标志，用于控制窗口中空格的解释。当它开启时，每行尾部的空格将被忽略；任何将光标移动到尾部空格的光标移动都会转到该行的末尾，并且在收集窗口内容时会删除尾部空格。