# 16.10. `curses` - 字符单元显示的终端处理

`curses`模块为curses库提供了一个接口，这是便携式高级终端处理的事实标准。

而curses最广泛应用在 Unix 环境中，版本以供 Windows、 DOS以及其他系统。此扩展模块用于匹配的 ncurses API，开源 curses 库托管在 Linux 和 BSD Unix 变种。

注意

从版本5.4开始，ncurses库决定如何使用`nl_langinfo`函数解释非ASCII数据。这意味着您必须在应用程序中调用`locale.setlocale()`，并使用系统的可用编码之一编码Unicode字符串。本例使用系统的默认编码：

    import locale
    locale.setlocale(locale.LC_ALL, '')
    code = locale.getpreferredencoding()

然后使用code作为`str.encode()`调用的编码。

也可以看看

模块`curses.ascii`
  与ASCII字符一起工作的实用程序，无论您的区域设置如何。
模块`curses.panel`
  面板堆栈扩展，为curses窗口添加深度。
模块`curses.textpad`
  支持Emacs式绑定的curses的可编辑文本小部件。
Curses Programming with Python
  由Andrew Kuchling和Eric Raymond撰写的关于使用curses与Python的教程材料。

Python源代码发行版中的Tools / demo /目录包含一些使用此模块提供的curses绑定的示例程序。

## 16.10.1. 函数

这个模块 `curses` 定义了一下异常。

exception `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 线缓冲关闭和字符都是可供读取一个接一个。然而，不同于raw模式，特殊字符 （中断、 退出、 暂停和流控制） 保留他们对 tty 驱动程序和调用程序的影响。调用`raw()` 然后 `cbreak()`离开终端进入cbreak模式。

`curses.``color_content`(color_number)

  返回一组红绿蓝RGB的颜色强度分量color_number,其值要介于 `0` 和 `COLORS`.返回一个 3 元组，则包含 R、 G、 B 值的给定的颜色, 其值在 `0` (no component) 和 `1000` (maximum amount of component).

`curses.``color_pair`(color_number)

  返回在指定的颜色显示文本的属性值。此属性可以跟 `A_STANDOUT`, `A_REVERSE`, 和其他`A_*` 组合.`pair_number()` 是此函数的对应。

`curses.``curs_set`(visibility)

  设置光标的状态。visibility（可见性） 可以设置为 0, 1, or 2, 对应为不可见,普通的, 或者非常明显.如果终端支持的可见性要求，则返回以前的游标状态;否则，则引发异常。许多终端，"可见"模式是下划线光标和"非常明显"模式是一个块游标。

`curses.``def_prog_mode`()

  作为"程序"模式，模式正在运行的程序使用curss时保存当前的终端模式。(对应的是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()`对window做了相关操作后，使用 `noutrefresh()` 调用后有所更新。正常的`refresh()`调用仅仅是`noutrefresh()`，后面跟着`doupdate()`；如果必须更新多个窗口，则可以通过在所有窗口上发出`noutrefresh()`调用来加速性能，并可能减少屏幕闪烁，然后再单个`doupdate()`。

`curses.``echo`()

  进入echo模型。在echo 模式，每个字符的输入都会显示在屏幕上。

`curses.``endwin`()

  取消初始化库，和终端回到正常状态。

`curses.``erasechar`()

  返回用户当前的擦除字符。在Unix操作系统下，这是curses程序的控制tty的一个属性，并不是由curses库本身设置的。

`curses.``filter`()

  必须在调用`initscr()`之前调用`filter()`例程（如果使用）。结果是，在这些调用中， `LINES`设置为1；能力明确，杯，荤，cud1，cuu1，cuu，vpa被禁用；并且主字符串被设置为cr的值。其效果是光标限制在当前行，屏幕更新也是如此。这可以用于在不触摸屏幕的其余部分的情况下启用一次一个字符的行编辑。

`curses.``flash`()

  闪烁屏幕。也就是说，将其改为反向视频，然后在短时间内将其改回。有些人比较喜欢诸如“可见铃”，以响应由`beep()`产生的听觉注意信号。

`curses.``flushinp`()

  刷新所有输入缓冲区。这抛弃了用户键入并且尚未被程序处理的任何类型的头文件。

`curses.``getmouse`()

  After `getch()` returns `KEY_MOUSE` to signal a mouse event, this method should be call to retrieve the queued mouse event, represented as a 5-tuple `(id, x, y, z, bstate)`. id是用于区分多个设备的ID值，x，y，z是事件的坐标。（z目前尚未使用。）bstate is an integer value whose bits will be set to indicate the type of event, and will be the bitwise OR of one or more of the following constants, where n is the button number from 1 to 4: `BUTTONn_PRESSED`, `BUTTONn_RELEASED`, `BUTTONn_CLICKED`, `BUTTONn_DOUBLE_CLICKED`, `BUTTONn_TRIPLE_CLICKED`, `BUTTON_SHIFT`, `BUTTON_CTRL`, `BUTTON_ALT`.

`curses.``getsyx`()

  返回y和x中虚拟屏幕光标的当前坐标。如果leaveok当前为真，则返回-1，-1。

`curses.``getwin`(file)

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

`curses.``has_colors`()

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

`curses.``has_ic`()

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

`curses.``has_il`()

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

`curses.``has_key`(ch)

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

`curses.``halfdelay`(tenths)

  用于半延时模式，类似于Cbreak模式，因为用户键入的字符可立即用于程序。然而，在阻塞十分之一秒之后，如果没有输入任何内容，则会引发异常。十分之一的值必须是`1`和`255`之间的数字。使用`nocbreak()`离开半延迟模式。

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

  改变颜色的定义，取出要改变的颜色的数字，后面跟着三个RGB值（红色，绿色和蓝色成分的数量）。color_number的值必须介于`0`和`COLORS`之间。r，g，b中的每一个必须是`0`和`1000` 当使用`init_color()`时，屏幕上该颜色的所有出现立即变为新的定义。此功能在大多数终端上不可用；它仅在`can_change_color()`返回`1`时才有效。

`curses.``init_pair`(pair_number, fg, bg)

  更改颜色对的定义。它有三个参数：要更改的颜色对的编号，前景颜色编号和背景颜色编号。pair_number的值必须介于`1`和`COLOR_PAIRS - 1` （`0`颜色对以黑色连线为白色，无法更改）。fg和bg参数的值必须介于`0`和`COLORS`之间。如果颜色对先前已初始化，则刷新屏幕并将该颜色对的所有出现更改为新定义。

`curses.``initscr`()

  初始化库。返回代表整个屏幕的`WindowObject`。

  注意

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

`curses.``is_term_resized`(nlines, ncols)

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

`curses.``isendwin`()

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

`curses.``keyname`(k)

  返回编号为k的密钥的名称。生成可打印ASCII字符的键的名称是键的字符。控制键组合的名称是一个由字符组成的双字符字符串，后跟相应的可打印ASCII字符。alt-key组合的名称（128-255）是由前缀'M-'组成的字符串，后跟相应的ASCII字符的名称。

`curses.``killchar`()

  返回用户的当前行杀死字符。在Unix操作系统下，这是curses程序的控制tty的一个属性，并不是由curses库本身设置的。

`curses.``longname`()

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

`curses.``meta`(yes)

  如果是是1，则允许输入8位字符。如果yes为0，则只允许7位字符。

`curses.``mouseinterval`(interval)

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

`curses.``mousemask`(mousemask)

  设置要报告的鼠标事件，并返回一个元组`（availmask， oldmask）`。availmask indicates which of the specified mouse events can be reported; on complete failure it returns 0. oldmask is the previous value of the given window’s mouse event mask. 如果从未调用此函数，则不会报告任何鼠标事件。

`curses.``napms`(ms)

  Sleep for ms milliseconds.

`curses.``newpad`(nlines, ncols)

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

  衬垫就像一个窗口，除了它不受屏幕大小的限制，并且不一定与屏幕的特定部分相关联。当需要大窗口时，可以使用焊盘，并且一次只能在屏幕上显示一部分窗口。自动刷新垫（例如从滚动或回显输入）不会发生。pad的`refresh()`和`noutrefresh()`方法需要6个参数来指定要显示的pad的部分以及要用于显示。参数是pminrow，pmincol，sminrow，smincol，smaxrow， smaxcol T5>； p自变量指的是要显示的填充区域的左上角，并且s自变量在屏幕上定义了一个剪切框， 。

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

  返回一个新的窗口，其左上角位于`（begin_y， begin_x）`，其高度/宽度为nlines < / T3> / NCOLS T4>。

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

`curses.``nl`()

  进入换行模式。此模式将返回键转换为输入的换行符，并将换行符转换为输出的回车符和换行符。换行模式最初处于打开状态。

`curses.``nocbreak`()

  离开cbreak模式。使用线路缓冲恢复到正常的“烹饪”模式。

`curses.``noecho`()

  留下回声模式。输入字符的回显被关闭。

`curses.``nonl`()

  离开换行模式。禁止在输入时将return换成换行符，并禁止将newline的低级转换转换为换行符/输出返回（但这不会改变`addch('\n')`的行为，相当于虚拟屏幕上的返回和换行）。通过翻译，诅咒有时可以加快垂直运动的速度；此外，它将能够检测输入上的返回键。

`curses.``noqiflush`()

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

`curses.``noraw`()

  保持原始模式。使用线路缓冲恢复到正常的“烹饪”模式。

`curses.``pair_content`(pair_number)

  返回包含请求颜色对的颜色的元组`（fg， bg）`。pair_number的值必须介于`1`和`COLOR_PAIRS - 1 T3>。`

`curses.``pair_number`(attr)

  返回由属性值attr设置的颜色对的编号。`color_pair()` is the counterpart to this function.

`curses.``putp`(string)

  Equivalent to `tputs(str, 1, putchar)`; emit the value of a specified terminfo capability for the current terminal. 请注意，`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)

  Backend function used by `resizeterm()`, performing most of the work; when resizing the windows, `resize_term()` blank-fills the areas that are extended. 调用应用程序应该用适当的数据填写这些区域。`resize_term()`函数尝试调整所有窗口的大小。但是，由于打击垫的调用惯例，不可能在没有与应用程序进行额外交互的情况下调整这些大小。

`curses.``resizeterm`(nlines, ncols)

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

`curses.``savetty`()

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

`curses.``setsyx`(y, x)

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

`curses.``setupterm`([termstr, fd])

  初始化终端。termstr是一个给出终端名称的字符串；如果省略，将使用 `TERM`环境变量的值。fd is the file descriptor to which any initialization sequences will be sent; if not supplied, the file descriptor for `sys.stdout` will be used.

`curses.``start_color`()

  如果程序员想要使用颜色，并且在任何其他颜色操作例程被调用之前必须被调用。在`initscr()`之后立即调用这个例程是一个好习惯。

  `start_color()` initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global variables in the `curses` module, `COLORS` and `COLOR_PAIRS`, containing the maximum number of colors and color-pairs the terminal can support. 它还将终端上的颜色恢复到刚刚打开终端时的值。

`curses.``termattrs`()

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

`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对应的字符串能力的值。`None` is returned if capname is not a string capability, or is canceled or absent from the terminal description.

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

  使用提供的参数实例化字符串str，其中str应该是从terminfo数据库获得的参数化字符串。例如 `tparm(tigetstr("cup"), 5, 3)` could result in `b'\033[6;4H'`, the exact result depending on terminal type.

`curses.``typeahead`(fd)

  指定文件描述符fd用于键入检查。如果fd是`-1`，则不会执行前端检查。

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

`curses.``unctrl`(ch)

  返回一个字符串，它是字符ch的可打印表示。控制字符显示为字符后面的插入符号，例如`^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之前调用此函数。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.``use_default_colors`()

  允许在支持此功能的终端上使用颜色的默认值。使用它来支持应用程序的透明度。默认颜色分配给颜色编号-1。After calling this function, `init_pair(x, curses.COLOR_RED, -1)` initializes, for instance, color pair x to a red foreground color on the default background.

`curses.``wrapper`(func, ...)

  初始化curses并调用另一个可调用的对象，func，它应该是您的curses使用应用程序的其余部分。如果应用程序引发异常，则此函数将在重新引发异常并生成回溯之前将终端恢复到正常状态。可调用对象func然后传递主窗口'stdscr'作为其第一个参数，然后传递给`wrapper()`的任何其他参数。Before calling func, `wrapper()` turns on cbreak mode, turns off echo, enables the terminal keypad, and initializes colors if the terminal has color support. 在退出时（无论是正常还是例外），它将恢复已烹饪模式，打开回音并禁用终端键盘。

## 16.10.2. 窗口对象

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

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

  注意

  字符表示C字符（ASCII码），而不是Python字符（长度为1的字符串）。（只要文档提到一个字符，这个注释就是真的。）内置的`ord()`方便地将字符串传递给代码。

  在`（y， x）`处使用属性attr对字符ch性格以前画家在那个位置。默认情况下，字符位置和属性是窗口对象的当前设置。

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

  在属性attr上覆盖`（y， x）`字符串str以前在显示器上的任何东西

`window.``attroff`(attr)

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

`window.``attron`(attr)

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

`window.``attrset`(attr)

  将“背景”属性设置为attr。这个集合最初是0（没有属性）。

`window.``bkgd`(ch[, attr])

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

  - 窗口中每个字符的属性都会更改为新的背景属性。
  - 无论何处出现前一个背景字符，都会更改为新的背景字符。

`window.``bkgdset`(ch[, attr])

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

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

  在窗口的边缘周围绘制边框。每个参数指定用于边框特定部分的字符；有关更多详细信息，请参阅下表。这些字符可以指定为整数或单字符字符串。

  注意

  任何参数的`0`值都会导致默认字符用于该参数。关键字参数可以不能使用。该表中列出了默认值：

  参数 | 描述 | 默认值
  --- | --- | ---
  LS T0> | 左边 | `ACS_VLINE`
  RS T0> | 右边 | `ACS_VLINE`
  TS T0> | 最佳 | `ACS_HLINE`
  BS T0> | 底部 | `ACS_HLINE`
  TL T0> | 左上角 | `ACS_ULCORNER`
  TR T0> | 右上角 | `ACS_URCORNER`
  BL T0> | 左下角 | `ACS_LLCORNER`
  BR T0> | 右下角 | `ACS_LRCORNER`

`window.``box`([vertch, horch])

  Similar to `border()`, but both ls and rs are vertch and both ts and bs are horch. 此功能始终使用默认的角落角色。

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

  在当前光标位置或`（y， x）`位置设置num 。如果未给出num的值或num = -1，则将在行的所有字符上设置该属性。该功能不移动光标。使用`touchline()`方法可以触及已更改的行，以便下一次窗口刷新将重新显示内容。

`window.``clear`()

  像`erase()`一样，但是也会导致在下次调用`refresh()`时重新整个窗口。

`window.``clearok`(yes)

  如果yes为1，则下一次调用`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)

  An abbreviation for “derive window”, `derwin()` is the same as calling `subwin()`, except that begin_y and begin_x are relative to the origin of the window, rather than relative to the entire screen. 为派生窗口返回一个窗口对象。

`window.``echochar`(ch[, attr])

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

`window.``enclose`(y, x)

  测试给定的窗口是否包含给定的屏幕相对字符单元坐标对，返回`True`或`False`。确定屏幕窗口的哪个子集包含鼠标事件的位置很有用。

`window.``encoding`

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

  版本3.3中的新功能。

`window.``erase`()

  清除窗口。

`window.``getbegyx`()

  返回左上角坐标的元组`（y， x）`。

`window.``getbkgd`()

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

`window.``getch`([y, x])

  获得一个角色。请注意，返回的整数不是必须在ASCII范围内：功能键，小键盘键等返回数字大于256。在无延迟模式下，如果没有输入，则返回-1，否则`getch()`将一直等待，直到按下一个键。

`window.``get_wch`([y, x])

  获得广泛的性格。返回大多数键的字符，或功能键，小键盘键和其他特殊键的整数。

  版本3.3中的新功能。

`window.``getkey`([y, x])

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

`window.``getmaxyx`()

  返回窗口高度和宽度的元组`（y， x）`。

`window.``getparyx`()

  将此窗口的起始坐标相对于其父窗口返回为两个整数变量y和x。如果此窗口没有父项，则返回`-1， -1`。

`window.``getstr`([y, x])

  从用户读取一个字符串，具有原始的行编辑能力。

`window.``getyx`()

  返回当前光标位置相对于窗口左上角的元组`（y， x）`。

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

  Display a horizontal line starting at `(y, x)` with length n consisting of the character ch.

`window.``idcok`(flag)

  如果flag为`False`，则curses不再考虑使用终端的硬件插入/删除字符功能；如果标志为`True`，则启用字符插入和删除功能。当首次初始化curses时，缺省情况下使用字符插入/删除。

`window.``idlok`(yes)

  If called with yes equal to 1, `curses` will try and use hardware line editing facilities. 否则，行插入/删除被禁用。

`window.``immedok`(flag)

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

`window.``inch`([y, x])

  返回窗口中给定位置的字符。底部的8位是字符，高位是属性。

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

  在属性attr中在`（y， x）`上绘制字符ch从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。属性从角色中剥离。If n is specified, `instr()` returns a string at most n characters long (exclusive of the trailing NUL).

`window.``is_linetouched`(line)

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

`window.``is_wintouched`()

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

`window.``keypad`(yes)

  如果yes是1，则由`curses`解释某些键（键盘，功能键）生成的转义序列。如果yes为0，则转义序列将保留原样在输入流中。

`window.``leaveok`(yes)

  如果yes是1，则光标保留在更新位置，而不是位于“光标位置”。这样可以尽可能减少光标移动。如果可能的话，光标将变得不可见。

  如果yes为0，则更新后光标始终位于“光标位置”。

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

  如果是是`1`，则`getch()`将是非阻塞的。

`window.``notimeout`(yes)

  如果是是`1`，转义序列不会超时。

  如果是是`0`，几毫秒后，转义序列将不会被解释，并且会保留在输入流中。

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

  通过行行向上滚动屏幕或滚动区域。

`window.``scrollok`(flag)

  控制当窗口的光标离开窗口边界或滚动区域时发生的情况，或者是作为底线上的换行动作的结果，或者是输入最后一行的最后一个字符。如果flag为false，则光标留在最后一行。如果flag为true，则窗口向上滚动一行。请注意，为了获得终端上的物理滚动效果，还需要调用`idlok()`。

`window.``setscrreg`(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 T3> / nlines T4>。

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

  返回一个子窗口，其左上角在`（begin_y， begin_x）`上，其宽度/高度为ncols T3> / nlines T4>。

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

`window.``syncdown`()

  触摸在任何祖先窗口中被触摸的窗口中的每个位置。这个例程由`refresh()`调用，所以几乎不需要手动调用它。

`window.``syncok`(flag)

  如果flag设置为`True`，那么只要窗口发生变化，就会自动调用`syncup()`。

`window.``syncup`()

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

`window.``timeout`(delay)

  为窗口设置阻止或非阻止读取行为。如果delay为负数，则使用阻塞读取（将无限期等待输入）。如果delay为零，则使用非阻塞读取，如果没有输入正在等待，则返回-1将由`getch()`返回。如果延迟为正数，那么`getch()`将在延迟毫秒内阻塞，如果在末尾没有输入，则返回-1那时。

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

  假设count行已更改，从行​​开始开始。如果提供了变更，它将指定受影响的行是否被标记为已更改（更改 = 1）或未更改（更改 = 0） 。

`window.``touchwin`()

  为了绘制优化目的，假设整个窗口已经被更改。

`window.``untouchwin`()

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

`window.``vline`(ch, n)
`window.``vline`(y, x, ch, n)

  Display a vertical line starting at `(y, x)` with length n consisting of the character ch.

## 16.10.3. 常量

`curses`模块定义了以下数据成员：

`curses.``ERR`

  某些返回整数的curses例程（如`getch()`）会在失败时返回`ERR`。

`curses.``OK`

  某些返回整数的curses例程（如`napms()`）会在成功时返回`OK`。

`curses.``version`

  代表模块当前版本的字符串。也可用作`__version__`。

有几个常量可用于指定字符单元属性：

属性 | 含义
--- | ---
`A_ALTCHARSET` | 备用字符集模式。
`A_BLINK` | 闪烁模式。
`A_BOLD` | 粗体模式。
`A_DIM` | 暗淡模式。
`A_NORMAL` | 普通属性。
`A_REVERSE` | 反向背景和前景色。
`A_STANDOUT` | 突出模式。
`A_UNDERLINE` | 下划线模式。

键由整数常量引用，名称以`KEY_`开头。可用的确切键帽取决于系统。

关键常数 | 键
--- | ---
`KEY_MIN` | 最小键值
`KEY_BREAK` | 断开键（不可靠）
`KEY_DOWN` | 向下箭头
`KEY_UP` | 向上箭头
`KEY_LEFT` | 左箭头
`KEY_RIGHT` | 右箭头
`KEY_HOME` | 主页键（向上+左箭头）
`KEY_BACKSPACE` | 退格（不可靠）
`KEY_F0` | 功能键。最多支持64个功能键。
`KEY_Fn` | 功能键的值n
`KEY_DL` | 删除线
`KEY_IL` | 插入行
`KEY_DC` | 删除字符
`KEY_IC` | 插入字符或进入插入模式
`KEY_EIC` | 退出插入字符模式
`KEY_CLEAR` | 清除屏幕
`KEY_EOS` | 清除屏幕结束
`KEY_EOL` | 清除到行尾
`KEY_SF` | 向前滚动1行
`KEY_SR` | 向后滚动1行（反向）
`KEY_NPAGE` | 下一页
`KEY_PPAGE` | 上一页
`KEY_STAB` | 设置选项卡
`KEY_CTAB` | 清除选项卡
`KEY_CATAB` | 清除所有标签
`KEY_ENTER` | 输入或发送（不可靠）
`KEY_SRESET` | 软（部分）重置（不可靠）
`KEY_RESET` | 重置或硬重置（不可靠）
`KEY_PRINT` | 打印
`KEY_LL` | 首页向下或向下（左下）
`KEY_A1` | 键盘左上角
`KEY_A3` | 键盘右上方
`KEY_B2` | 键盘中心
`KEY_C1` | 键盘左下方
`KEY_C3` | 键盘右下方
`KEY_BTAB` | 后退标签
`KEY_BEG` | Beg（开始）
`KEY_CANCEL` | 取消
`KEY_CLOSE` | 关
`KEY_COMMAND` | 命令（命令）
`KEY_COPY` | 复制
`KEY_CREATE` | 创建
`KEY_END` | 结束
`KEY_EXIT` | 出口
`KEY_FIND` | 找
`KEY_HELP` | HELP
`KEY_MARK` | 标记
`KEY_MESSAGE` | 信息
`KEY_MOVE` | 移动
`KEY_NEXT` | 下一个
`KEY_OPEN` | 打开
`KEY_OPTIONS` | 选项
`KEY_PREVIOUS` | 上一个（上一个）
`KEY_REDO` | 重做
`KEY_REFERENCE` | 参考（参考）
`KEY_REFRESH` | 刷新
`KEY_REPLACE` | 更换
`KEY_RESTART` | 重新开始
`KEY_RESUME` | 恢复
`KEY_SAVE` | 保存
`KEY_SBEG` | Shifted Beg（开始）
`KEY_SCANCEL` | 移动取消
`KEY_SCOMMAND` | 转移命令
`KEY_SCOPY` | 转移拷贝
`KEY_SCREATE` | 转移创建
`KEY_SDC` | 转移删除字符
`KEY_SDL` | 移动删除线
`KEY_SELECT` | 选择
`KEY_SEND` | 转移结束
`KEY_SEOL` | 转移清除线
`KEY_SEXIT` | 转移Dxit
`KEY_SFIND` | 转移查找
`KEY_SHELP` | 转移帮助
`KEY_SHOME` | 转移的家
`KEY_SIC` | 转移输入
`KEY_SLEFT` | 移动左箭头
`KEY_SMESSAGE` | 转移消息
`KEY_SMOVE` | 移动移动
`KEY_SNEXT` | 向下移动
`KEY_SOPTIONS` | 转移选项
`KEY_SPREVIOUS` | 上移
`KEY_SPRINT` | 转移打印
`KEY_SREDO` | 转移重做
`KEY_SREPLACE` | 移位替换
`KEY_SRIGHT` | 移动右箭头
`KEY_SRSUME` | 转移的简历
`KEY_SSAVE` | 转移保存
`KEY_SSUSPEND` | 转移暂停
`KEY_SUNDO` | 移动撤消
`KEY_SUSPEND` | 暂停
`KEY_UNDO` | 撤消
`KEY_MOUSE` | 鼠标事件已发生
`KEY_RESIZE` | 终端调整大小事件
`KEY_MAX` | 最大键值

On VT100s and their software emulations, such as X terminal emulators, there are normally at least four function keys (`KEY_F1`, `KEY_F2`, `KEY_F3`, `KEY_F4`) available, and the arrow keys mapped to `KEY_UP`, `KEY_DOWN`, `KEY_LEFT` and `KEY_RIGHT` in the obvious way. 如果您的机器具有PC键盘，则可以安全地使用箭头键和十二个功能键（较旧的PC键盘可能只有十个功能键）；此外，以下键盘映射也是标准配置：

键帽 | 不变
--- | ---
`Insert` | KEY_IC
`Delete` | KEY_DC
`Home` | KEY_HOME
`End` | KEY_END
`页 向上` | KEY_PPAGE
`页 向下` | KEY_NPAGE

下表列出了备用字符集中的字符。这些是从VT100终端继承的，并且通常可用于诸如X终端的软件仿真。当没有图形可用时，curses会回到粗糙的可打印ASCII近似值。

注意

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

ACS代码 | 含义
--- | ---
`ACS_BBSS` | 右上角的替代名称
`ACS_BLOCK` | 实心方块
`ACS_BOARD` | 董事会的正方形
`ACS_BSBS` | 水平线的替代名称
`ACS_BSSB` | 左上角的替代名称
`ACS_BSSS` | 顶部T恤的替代名称
`ACS_BTEE` | 底部三通
`ACS_BULLET` | 子弹
`ACS_CKBOARD` | 棋盘（点画）
`ACS_DARROW` | 指向下的箭头
`ACS_DEGREE` | 学位标志
`ACS_DIAMOND` | 钻石
`ACS_GEQUAL` | 大于或 - 等于对
`ACS_HLINE` | 水平线
`ACS_LANTERN` | 灯笼符号
`ACS_LARROW` | 左箭头
`ACS_LEQUAL` | 低于或相等到
`ACS_LLCORNER` | 左下角
`ACS_LRCORNER` | 右下角
`ACS_LTEE` | 左发球
`ACS_NEQUAL` | 不等号
`ACS_PI` | 字母pi
`ACS_PLMINUS` | 加号或减号
`ACS_PLUS` | 大加号
`ACS_RARROW` | 右箭头
`ACS_RTEE` | 正确的发球台
`ACS_S1` | 扫描线1
`ACS_S3` | 扫描线3
`ACS_S7` | 扫描线7
`ACS_S9` | 扫描线9
`ACS_SBBS` | 右下角的替代名称
`ACS_SBSB` | 垂直线的替代名称
`ACS_SBSS` | 右T恤的替代名称
`ACS_SSBB` | 左下角的替代名称
`ACS_SSBS` | 底部三通的替代名称
`ACS_SSSB` | 左T恤的替代名称
`ACS_SSSS` | 交叉名称或大加号
`ACS_STERLING` | 英镑
`ACS_TTEE` | 顶级球座
`ACS_UARROW` | 向上箭头
`ACS_ULCORNER` | 左上角
`ACS_URCORNER` | 右上角
`ACS_VLINE` | 垂线

下表列出了预定义的颜色：

不变 | color（颜色）
--- | ---
`COLOR_BLACK` | 黑色
`COLOR_BLUE` | 蓝色
`COLOR_CYAN` | 青色（浅绿蓝色）
`COLOR_GREEN` | 绿色
`COLOR_MAGENTA` | 洋红色（紫红色）
`COLOR_RED` | 红
`COLOR_WHITE` | 白色
`COLOR_YELLOW` | 黄色

# 16.11. `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破折号，垂直条和加号绘制。

## 16.11.1. 文本框对象

您可以按如下方式实例化一个`Textbox`对象：

class `curses.textpad.``Textbox`(win)

  返回一个文本框小部件对象。win参数应该是一个包含文本框的curses `WindowObject`。文本框的编辑光标最初位于包含窗口的左上角，坐标为`（0， 0）`。实例的`stripspaces`标志最初处于打开状态。

  `Textbox`对象具有以下方法：

  `edit`([validator])

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

  `do_command`(ch)

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

    按键 | 行动
    --- | ---
    `Control-A` | 去窗口的左边缘。
    `Control-B` | 光标离开，如果合适的话，包装到上一行。
    `Control-D` | 删除光标下的字符。
    `Control-E` | 转到右边缘（strippaces off）或行尾（strippaces on）。
    `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`

    该属性是一个控制窗口中空白解释的标志。打开时，每行上的尾随空白将被忽略；任何将光标放在尾部空白上的光标移动都会转到该行的末尾，而在收集窗口内容时尾随空白会被剥离。