使用 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 取代，后者是 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() 将返回一个表示整个屏幕的窗口对象；这通常在对应的 C 变量名之后称为 stdscr。

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 的一部分，现在更改它为时已晚。

您的应用程序可以通过使用 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

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

y, x, str 或 ch

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

y, x, str 或 ch, attr

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

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

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 为 true 时，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 模块提供 ASCII 类成员函数，该函数接受整数或 1 个字符的字符串参数；这些函数对于为此类循环编写更具可读性的测试可能很有用。它还提供转换函数，该函数接受整数或 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 实例捕获鼠标事件，但是现在 curses 模块的 Python 库页面已相当完整。接下来您应该浏览它。

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

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