curses — 字符单元格显示的终端处理

源代码: Lib/curses

---

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

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

可用性: 非 Android、非 iOS、非 WASI。

该模块在移动平台或WebAssembly 平台上不受支持。

备注

文档中提及 字符 时，它可以指定为一个整数、一个单字符的 Unicode 字符串或一个单字节的字节字符串。

文档中提及 字符字符串 时，它可以指定为一个 Unicode 字符串或一个字节字符串。

参见

模块 curses.ascii

用于处理 ASCII 字符的实用程序，无论您的区域设置如何。

模块 curses.panel

增加了 curses 窗口深度的面板堆栈扩展。

模块 curses.textpad

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

使用 Python 进行 Curses 编程

Andrew Kuchling 和 Eric Raymond 编写的关于使用 Python 和 curses 的教程资料。

函数

模块 curses 定义了以下异常

exception curses.error

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

备注

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

模块 curses 定义了以下函数

curses.assume_default_colors(fg, bg, /)

允许在支持此功能的终端上使用颜色的默认值。使用此功能以支持应用程序的透明度。

• 将终端默认的前景/背景颜色分配给颜色号 -1。因此 init_pair(x, COLOR_RED, -1) 会将颜色对 x 初始化为红色前景，默认背景；init_pair(x, -1, COLOR_BLUE) 会将颜色对 x 初始化为默认前景，蓝色背景。

• 将颜色对 0 的定义更改为 (fg, bg)。

在 3.14 版本加入。

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 之间。返回一个包含给定颜色的 R、G、B 值的 3 元组，其值将在 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 程序控制 tty 的一个属性，而不是 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 颜色对只能通过 use_default_colors() 和 assume_default_colors() 更改）。fg 和 bg 参数的值必须在 0 到 COLORS - 1 之间，或者在调用 use_default_colors() 或 assume_default_colors() 之后为 -1。如果颜色对先前已初始化，则屏幕会刷新，并且该颜色对的所有出现都会更改为新定义。

curses.initscr()

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

备注

如果打开终端时出错，底层 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)

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

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

curses.newwin(nlines, ncols)

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

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

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

curses.nl()

进入换行模式。此模式将回车键在输入时转换为换行符，并将换行符在输出时转换为回车和换行符。换行模式最初是开启的。

curses.nocbreak()

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

curses.noecho()

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

curses.nonl()

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

curses.noqiflush()

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

curses.noraw()

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

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()

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

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()

等同于 assume_default_colors(-1, -1)。

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

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

窗口对象

class curses.window

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

window.addch(ch[, attr])

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

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

备注

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

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，覆盖显示上先前存在的任何内容。

备注

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

• 一个 ncurses 中的 bug（此 Python 模块的后端）可能在调整窗口大小时导致段错误。此问题已在 ncurses-6.1-20190511 中修复。如果您使用的是较早的 ncurses 版本，可以通过不使用包含嵌入式换行符的 str 调用 addstr() 来避免触发此问题。相反，请为每一行单独调用 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 或 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() 时，编码属性会从父窗口继承。默认情况下，使用当前区域设置编码（参见 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)

从用户读取一个字节对象，具有基本的行编辑能力。n 的最大值为 2047。

3.14 版中已变更: n 的最大值从 1023 增加到 2047。

window.getyx()

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

window.hline(ch, n)

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

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

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，则在移动到 y、x 之后）。

window.insstr(str[, attr])

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

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

window.instr([n])

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

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

3.14 版中已变更: n 的最大值从 1023 增加到 2047。

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])

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

这 6 个可选参数只能在窗口是使用 newpad() 创建的板时指定。需要额外的参数来指示板和屏幕的哪些部分涉及。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) 处显示一条由字符 ch 和属性 attr 组成的长度为 n 的垂直线。

常量

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	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 + Beg（开始）
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 + Home
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
Home	KEY_HOME
结束	KEY_END
Page Up	KEY_PPAGE
Page Down	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	上部 T 形的别名
curses.ACS_BTEE	下部 T 形
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	左 T 形
curses.ACS_NEQUAL	不等于号
curses.ACS_PI	字母 pi
curses.ACS_PLMINUS	加减号
curses.ACS_PLUS	大加号
curses.ACS_RARROW	右箭头
curses.ACS_RTEE	右 T 形
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	右 T 形的别名
curses.ACS_SSBB	左下角的别名
curses.ACS_SSBS	下部 T 形的别名
curses.ACS_SSSB	左 T 形的别名
curses.ACS_SSSS	交叉点或大加号的别名
curses.ACS_STERLING	英镑符号
curses.ACS_TTEE	上部 T 形
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	在按钮状态改变时 Control 键按下
curses.BUTTON_ALT	在按钮状态改变时 Control 键按下

在 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 坐标。在可能的情况下（包括 xterm 和大多数其他软件终端仿真器），矩形将使用 VT100/IBM PC 形式字符绘制。否则，它将使用 ASCII 破折号、竖线和加号绘制。

文本框对象

你可以按如下方式实例化一个 Textbox 对象

class curses.textpad.Textbox(win)

返回一个文本框小部件对象。_win_ 参数应该是一个 curses window 对象，文本框将包含在该对象中。文本框的编辑光标最初位于包含窗口的左上角，坐标为 (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	如果窗口只有一行则终止，否则插入换行符。
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

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