# Curses C API

`curses` 针对扩展模块对外公开了一个小型 C 接口。使用方必须包含头文件 `py_curses.h` (该文件默认不被 `Python.h` 包含) 并且 `import_curses()` 必须被调用，通常是作为模块初始化函数的一部分，以便填充 `PyCurses_API` 指针。

警告

该 C API 和纯 Python `curses` 模块均不兼容子解释器。

import_curses()

  导入 curses C API。调用该宏不需要带分号。

  成功时，填充 `PyCurses_API` 指针。

  失败时，将 `PyCurses_API` 设为 NULL 并设置一个异常。调用方必须通过 `PyErr_Occurred()` 检查是否发生了错误：

      import_curses();  // semi-colon is optional but recommended
      if (PyErr_Occurred()) { /* cleanup */ }

void **PyCurses_API

  包含 curses C API 的动态分配对象。该变量仅在 `import_curses` 执行成功后可用。

  `PyCurses_API[0]` 对应于 `PyCursesWindow_Type`。

  `PyCurses_API[1]`, `PyCurses_API[2]` 和 `PyCurses_API[3]` 是指向 `int (*)(void)` 类型的谓词函数的指针。

  当被调用时，这些谓词函数将分别返回 `curses.setupterm()`, `curses.initscr()` 和 `curses.start_color()` 是否已被调用。

  另请参阅 `PyCursesSetupTermCalled`, `PyCursesInitialised` 和 `PyCursesInitialisedColor` 便捷宏。

  备注

  此结构体中的条目数可能发生变化。请考虑使用 `PyCurses_API_pointers` 来检查是否有新字段可用。

PyCurses_API_pointers

  在 `PyCurses_API` 中的可访问字段数 (`4`)。此数值会在新字段被添加时递增。

PyTypeObject PyCursesWindow_Type

  对应于 `curses.window` 的 堆类型。

int PyCursesWindow_Check(PyObject *op)

  如果 op 是一个 `curses.window` 实例则返回真值，否则返回假值。

下列宏属于扩展为 C 语句的便捷宏。具体而言，它们只能以 `macro;` 或 `macro` 的形式，而不能以 `macro()` 或 `macro();` 的形式被使用。

PyCursesSetupTermCalled

  检查 `curses.setupterm()` 是否已被调用的宏。

  这个宏扩展大致等价于：

      {
          typedef int (*predicate_t)(void);
          predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
          if (!was_setupterm_called()) {
              return NULL;
          }
      }

PyCursesInitialised

  检查 `curses.initscr()` 是否已被调用的宏。

  这个宏扩展大致等价于：

      {
          typedef int (*predicate_t)(void);
          predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
          if (!was_initscr_called()) {
              return NULL;
          }
      }

PyCursesInitialisedColor

  检查 `curses.start_color()` 是否已被调用的宏。

  这个宏扩展大致等价于：

      {
          typedef int (*predicate_t)(void);
          predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
          if (!was_start_color_called()) {
              return NULL;
          }
      }

# 内部数据

下列对象由 C API 对外暴露但是应当被视为仅限内部使用。

PyCurses_CAPSULE_NAME

  传给 `PyCapsule_Import()` 的 curses capsule 的名称。

  仅限内部使用。请改用 `import_curses`。