使用 Python 进行 Curses 编程

作者:

A.M. Kuchling, Eric S. Raymond

发布:

2.04

什么是 curses？

curses 库为基于文本的终端提供了独立于终端的屏幕绘制和键盘处理功能；这类终端包括 VT100、Linux 控制台以及各种程序提供的模拟终端。显示终端支持各种控制代码来执行常见操作，例如移动光标、滚动屏幕和擦除区域。不同的终端使用差异很大的代码，并且通常有自己的小怪癖。

在一个图形显示的世界里，人们可能会问“为什么还要费心呢”？确实，字符单元格显示终端是一种过时的技术，但在某些领域中，能够用它们做一些花哨的事情仍然很有价值。一个领域是那些不运行 X 服务器的小型或嵌入式 Unix 系统。另一个是像操作系统安装程序和内核配置器这样的工具，它们可能需要在任何图形支持可用之前运行。

curses 库提供了相当基本的功能，为程序员提供了一个包含多个不重叠文本窗口的显示抽象。窗口的内容可以通过各种方式改变——添加文本、擦除文本、改变其外观——curses 库会计算出需要发送到终端的控制代码以产生正确的输出。curses 不提供许多用户界面概念，例如按钮、复选框或对话框；如果您需要这些功能，请考虑使用像 Urwid 这样的用户界面库。

curses 库最初是为 BSD Unix 编写的；后来 AT&T 的 System V 版本的 Unix 添加了许多增强功能和新函数。BSD curses 不再维护，已被 ncurses 取代，ncurses 是 AT&T 接口的开源实现。如果您使用的是 Linux 或 FreeBSD 等开源 Unix，您的系统几乎肯定使用 ncurses。由于大多数当前商业 Unix 版本都基于 System V 代码，因此这里描述的所有函数可能都可用。然而，某些专有 Unix 系统中较旧的 curses 版本可能不支持所有功能。

Python 的 Windows 版本不包含 curses 模块。一个名为 UniCurses 的移植版本可用。

Python curses 模块

Python 模块是对 curses 提供的 C 函数的相当简单的包装；如果您已经熟悉 C 语言中的 curses 编程，那么将这些知识转移到 Python 真的很容易。最大的区别是 Python 接口通过将不同的 C 函数（例如 addstr()、mvaddstr() 和 mvwaddstr()）合并到单个 addstr() 方法中，从而使事情变得更简单。您稍后会看到更详细的介绍。

本 HOWTO 是使用 curses 和 Python 编写文本模式程序的入门。它不试图成为 curses API 的完整指南；为此，请参阅 Python 库指南中关于 ncurses 的部分，以及 ncurses 的 C 手册页。但是，它会给您提供基本概念。

启动和结束 curses 应用程序

在做任何事情之前，必须初始化 curses。这是通过调用 initscr() 函数来完成的，该函数将确定终端类型，向终端发送任何所需的设置代码，并创建各种内部数据结构。如果成功，initscr() 返回一个表示整个屏幕的窗口对象；这通常被称为 stdscr，因为它对应于 C 变量的名称。

import curses
stdscr = curses.initscr()

通常，curses 应用程序会关闭按键到屏幕的自动回显，以便能够读取按键并仅在某些情况下显示它们。这需要调用 noecho() 函数。

curses.noecho()

应用程序通常还需要即时响应按键，而无需按下 Enter 键；这被称为 cbreak 模式，与通常的缓冲输入模式相对。

curses.cbreak()

终端通常将特殊按键（例如光标键或 Page Up 和 Home 等导航键）作为多字节转义序列返回。虽然您可以编写应用程序来预期此类序列并相应地处理它们，但 curses 可以为您完成此操作，返回一个特殊值，例如 curses.KEY_LEFT。要让 curses 完成这项工作，您需要启用键盘模式。

stdscr.keypad(True)

终止 curses 应用程序比启动它容易得多。您需要调用

curses.nocbreak()
stdscr.keypad(False)
curses.echo()

以恢复 curses 友好的终端设置。然后调用 endwin() 函数以将终端恢复到其原始操作模式。

curses.endwin()

调试 curses 应用程序时的一个常见问题是，当应用程序在未将终端恢复到其先前状态的情况下退出时，您的终端会变得混乱。在 Python 中，这通常发生在您的代码有错误并引发未捕获的异常时。例如，当您输入时，按键不再回显到屏幕上，这使得使用 shell 变得困难。

在 Python 中，您可以通过导入 curses.wrapper() 函数并像这样使用它来避免这些复杂情况并使调试变得更容易

from curses import wrapper

def main(stdscr):
    # Clear screen
    stdscr.clear()

    # This raises ZeroDivisionError when i == 10.
    for i in range(0, 11):
        v = i-10
        stdscr.addstr(i, 0, '10 divided by {} is {}'.format(v, 10/v))

        stdscr.refresh()
        stdscr.getkey()

wrapper(main)

wrapper() 函数接受一个可调用对象，并执行上述初始化，如果支持颜色，还会初始化颜色。wrapper() 然后运行您提供的可调用对象。一旦可调用对象返回，wrapper() 将恢复终端的原始状态。可调用对象在捕获异常、恢复终端状态，然后重新引发异常的 try...except 内部被调用。因此，您的终端在发生异常时不会处于奇怪的状态，您将能够读取异常消息和回溯。

窗口和 Pad

窗口是 curses 中的基本抽象。窗口对象表示屏幕上的矩形区域，并支持显示文本、擦除文本、允许用户输入字符串等方法。

initscr() 函数返回的 stdscr 对象是一个覆盖整个屏幕的窗口对象。许多程序可能只需要这一个窗口，但您可能希望将屏幕分成更小的窗口，以便单独重绘或清除它们。newwin() 函数创建一个给定大小的新窗口，并返回新的窗口对象。

begin_x = 20; begin_y = 7
height = 5; width = 40
win = curses.newwin(height, width, begin_y, begin_x)

请注意，curses 中使用的坐标系很特别。坐标总是按 y,x 的顺序传递，窗口的左上角坐标是 (0,0)。这打破了处理坐标时 x 坐标在前的正常惯例。这是与大多数其他计算机应用程序不幸的区别，但它自 curses 最初编写以来就一直是其中的一部分，现在更改为时已晚。

您的应用程序可以通过使用 curses.LINES 和 curses.COLS 变量来获取屏幕的 y 和 x 大小。合法的坐标将从 (0,0) 延伸到 (curses.LINES - 1, curses.COLS - 1)。

当您调用方法来显示或擦除文本时，效果不会立即显示在屏幕上。相反，您必须调用窗口对象的 refresh() 方法来更新屏幕。

这是因为 curses 最初是为慢速 300 波特终端连接而编写的；对于这些终端，最大限度地减少重绘屏幕所需的时间非常重要。相反，curses 会累积对屏幕的更改，并在您调用 refresh() 时以最有效的方式显示它们。例如，如果您的程序在一个窗口中显示一些文本，然后清除该窗口，则无需发送原始文本，因为它们永远不可见。

实际上，明确告诉 curses 重绘窗口并不会使 curses 编程复杂多少。大多数程序都会进行一系列操作，然后暂停，等待按键或用户执行其他操作。您所要做的就是确保在暂停等待用户输入之前已经重绘了屏幕，方法是首先调用 stdscr.refresh() 或其他相关窗口的 refresh() 方法。

pad 是窗口的一种特殊情况；它可以比实际的显示屏幕大，并且每次只显示 pad 的一部分。创建 pad 需要 pad 的高度和宽度，而刷新 pad 需要提供屏幕上将显示 pad 子区域的坐标。

pad = curses.newpad(100, 100)
# These loops fill the pad with letters; addch() is
# explained in the next section
for y in range(0, 99):
    for x in range(0, 99):
        pad.addch(y,x, ord('a') + (x*x+y*y) % 26)

# Displays a section of the pad in the middle of the screen.
# (0,0) : coordinate of upper-left corner of pad area to display.
# (5,5) : coordinate of upper-left corner of window area to be filled
#         with pad content.
# (20, 75) : coordinate of lower-right corner of window area to be
#          : filled with pad content.
pad.refresh( 0,0, 5,5, 20,75)

refresh() 调用在屏幕上坐标 (5,5) 到 (20,75) 的矩形区域中显示 pad 的一部分；显示区域的左上角是 pad 上的坐标 (0,0)。除了这个区别，pad 与普通窗口完全相同，并支持相同的方法。

如果屏幕上有多个窗口和 pad，有一种更有效的方法来更新屏幕并防止由于屏幕的每个部分更新而导致的恼人屏幕闪烁。refresh() 实际上做了两件事

  1. 调用每个窗口的 noutrefresh() 方法来更新表示屏幕所需状态的底层数据结构。

  2. 调用函数 doupdate() 函数以更改物理屏幕以匹配数据结构中记录的所需状态。

相反，您可以对多个窗口调用 noutrefresh() 以更新数据结构，然后调用 doupdate() 以更新屏幕。

显示文本

从 C 程序员的角度来看，curses 有时可能看起来像一个曲折的函数迷宫，所有函数都略有不同。例如，addstr() 在 stdscr 窗口的当前光标位置显示一个字符串，而 mvaddstr() 在显示字符串之前先移动到给定的 y,x 坐标。waddstr() 就像 addstr()，但允许指定要使用的窗口而不是默认使用 stdscr。mvwaddstr() 允许同时指定窗口和坐标。

幸运的是，Python 接口隐藏了所有这些细节。stdscr 是一个与其他窗口对象一样的窗口对象，像 addstr() 这样的方法接受多种参数形式。通常有四种不同的形式。

形式

描述

str 或 ch

在当前位置显示字符串 str 或字符 ch

str 或 ch, attr

在当前位置使用属性 attr 显示字符串 str 或字符 ch

y, x, str 或 ch

移动到窗口内的位置 y,x，并显示 str 或 ch

y, x, str 或 ch, attr

移动到窗口内的位置 y,x，并使用属性 attr 显示 str 或 ch

属性允许以突出显示的形式显示文本，例如粗体、下划线、反色或彩色。它们将在下一小节中更详细地解释。

addstr() 方法接受 Python 字符串或字节串作为要显示的值。字节串的内容按原样发送到终端。字符串使用窗口的 encoding 属性的值进行编码；这默认为 locale.getencoding() 返回的默认系统编码。

addch() 方法接受一个字符，可以是长度为 1 的字符串、长度为 1 的字节串或整数。

提供了扩展字符的常量；这些常量是大于 255 的整数。例如，ACS_PLMINUS 是一个 +/- 符号，ACS_ULCORNER 是一个框的左上角（用于绘制边框）。您也可以使用相应的 Unicode 字符。

窗口会记住上次操作后光标的位置，因此如果您省略了 y,x 坐标，字符串或字符将显示在上次操作离开的位置。您还可以使用 move(y,x) 方法移动光标。由于某些终端总是显示闪烁的光标，您可能希望确保光标位于某个不会分散注意力的位置；让光标在某个看似随机的位置闪烁可能会让人困惑。

如果您的应用程序完全不需要闪烁光标，您可以调用 curs_set(False) 使其不可见。为了与旧版 curses 兼容，有一个 leaveok(bool) 函数是 curs_set() 的同义词。当 bool 为真时，curses 库将尝试抑制闪烁光标，您无需担心将其留在奇怪的位置。

属性和颜色

字符可以以不同的方式显示。基于文本的应用程序中的状态行通常以反色显示，或者文本查看器可能需要突出显示某些单词。curses 通过允许您为屏幕上的每个单元格指定属性来支持这一点。

属性是一个整数，每个位代表不同的属性。您可以尝试设置多个属性位来显示文本，但 curses 不保证所有可能的组合都可用，或者它们都具有视觉上的区别。这取决于所使用终端的能力，因此最好坚持使用最常用的属性，如下所示。

属性

描述

A_BLINK

闪烁文本

A_BOLD

超亮或粗体文本

A_DIM

半亮文本

A_REVERSE

反色文本

A_STANDOUT

可用的最佳高亮模式

A_UNDERLINE

带下划线的文本

因此，要在屏幕顶行显示反色状态行，您可以编写

stdscr.addstr(0, 0, "Current mode: Typing mode",
              curses.A_REVERSE)
stdscr.refresh()

curses 库还支持提供颜色的终端。最常见的此类终端可能是 Linux 控制台，其次是彩色 xterm。

要使用颜色，您必须在调用 initscr() 之后尽快调用 start_color() 函数，以初始化默认颜色集（curses.wrapper() 函数会自动执行此操作）。完成此操作后，如果正在使用的终端实际上可以显示颜色，则 has_colors() 函数将返回 TRUE。（注意：curses 使用美式拼写“color”，而不是加拿大/英式拼写“colour”。如果您习惯了英式拼写，您将不得不为了这些函数而将它拼错。）

curses 库维护有限数量的颜色对，其中包含前景色（或文本）和背景色。您可以使用 color_pair() 函数获取与颜色对对应的属性值；这可以与 A_REVERSE 等其他属性进行按位或运算，但同样，这种组合不保证在所有终端上都有效。

一个示例，使用颜色对 1 显示一行文本

stdscr.addstr("Pretty text", curses.color_pair(1))
stdscr.refresh()

正如我之前所说，颜色对由前景色和背景色组成。init_pair(n, f, b) 函数将颜色对 n 的定义更改为前景色 f 和背景色 b。颜色对 0 被硬编码为白底黑字，并且无法更改。

颜色是编号的，start_color() 在激活颜色模式时初始化 8 种基本颜色。它们是：0:黑色，1:红色，2:绿色，3:黄色，4:蓝色，5:品红色，6:青色，和 7:白色。curses 模块为每种颜色定义了命名常量：curses.COLOR_BLACK、curses.COLOR_RED 等等。

让我们把这一切整合起来。要将颜色 1 更改为白底红字，您将调用

curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)

当您更改颜色对时，任何已经使用该颜色对显示的文本都会更改为新颜色。您也可以使用以下代码以这种颜色显示新文本

stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1))

非常高级的终端可以将实际颜色的定义更改为给定的 RGB 值。这允许您将颜色 1（通常是红色）更改为紫色、蓝色或任何您喜欢的其他颜色。不幸的是，Linux 控制台不支持此功能，因此我无法尝试，也无法提供任何示例。您可以通过调用 can_change_color() 来检查您的终端是否可以执行此操作，如果支持此功能，该函数将返回 True。如果您很幸运拥有这样功能强大的终端，请查阅您系统的手册页以获取更多信息。

用户输入

C curses 库只提供非常简单的输入机制。Python 的 curses 模块添加了一个基本的文本输入小部件。（其他库，例如 Urwid，拥有更广泛的小部件集合。）

有两种从窗口获取输入的方法

  • getch() 刷新屏幕，然后等待用户按下按键，如果之前调用过 echo()，则显示按键。您可以选择指定一个坐标，在暂停之前将光标移动到该坐标。

  • getkey() 具有相同的功能，但将整数转换为字符串。单个字符作为 1 个字符的字符串返回，功能键等特殊键返回较长的字符串，其中包含键名，例如 KEY_UP 或 ^G。

可以使用 nodelay() 窗口方法不等待用户。在 nodelay(True) 之后，窗口的 getch() 和 getkey() 变为非阻塞。为了表示没有输入准备就绪，getch() 返回 curses.ERR（值为 -1），getkey() 引发异常。还有一个 halfdelay() 函数，可以用来（实际上）为每个 getch() 设置一个计时器；如果在指定延迟（以十分之一秒为单位）内没有输入可用，curses 会引发异常。

getch() 方法返回一个整数；如果它介于 0 到 255 之间，则表示按下键的 ASCII 码。大于 255 的值是特殊键，例如 Page Up、Home 或光标键。您可以将返回值与 curses.KEY_PPAGE、curses.KEY_HOME 或 curses.KEY_LEFT 等常量进行比较。您的程序主循环可能看起来像这样

while True:
    c = stdscr.getch()
    if c == ord('p'):
        PrintDocument()
    elif c == ord('q'):
        break  # Exit the while loop
    elif c == curses.KEY_HOME:
        x = y = 0

curses.ascii 模块提供了接受整数或 1 字符字符串参数的 ASCII 类成员函数；这些函数可能有助于编写此类循环中更易读的测试。它还提供接受整数或 1 字符字符串参数并返回相同类型的转换函数。例如，curses.ascii.ctrl() 返回与其参数对应的控制字符。

还有一个检索整个字符串的方法，getstr()。它不经常使用，因为其功能非常有限；唯一可用的编辑键是退格键和回车键，后者终止字符串。它可以选择限制为固定数量的字符。

curses.echo()            # Enable echoing of characters

# Get a 15-character string, with the cursor on the top line
s = stdscr.getstr(0,0, 15)

curses.textpad 模块提供了一个支持 Emacs 式键绑定的文本框。Textbox 类的各种方法支持带输入验证的编辑，并收集带或不带尾随空格的编辑结果。这是一个示例

import curses
from curses.textpad import Textbox, rectangle

def main(stdscr):
    stdscr.addstr(0, 0, "Enter IM message: (hit Ctrl-G to send)")

    editwin = curses.newwin(5,30, 2,1)
    rectangle(stdscr, 1,0, 1+5+1, 1+30+1)
    stdscr.refresh()

    box = Textbox(editwin)

    # Let the user edit until Ctrl-G is struck.
    box.edit()

    # Get resulting contents
    message = box.gather()

有关更多详细信息，请参阅 curses.textpad 的库文档。

获取更多信息

本 HOWTO 不涵盖一些高级主题，例如读取屏幕内容或从 xterm 实例捕获鼠标事件，但 Python 库页面的 curses 模块现在相当完整。您应该接下来浏览它。

如果您对 curses 函数的详细行为有疑问，请查阅您的 curses 实现的手册页，无论是 ncurses 还是专有 Unix 供应商的。手册页将记录任何怪癖，并提供所有函数、属性和 ACS_* 可用字符的完整列表。

由于 curses API 非常庞大，因此 Python 接口中不支持某些函数。通常这并不是因为它们难以实现，而是因为还没有人需要它们。此外，Python 尚未支持与 ncurses 关联的菜单库。欢迎提供补丁以添加对这些功能的支持；请参阅 Python 开发者指南 以了解有关向 Python 提交补丁的更多信息。