Curses C API
************

"curses" exposes a small C interface for extension modules. Consumers
must include the header file "py_curses.h" (which is not included by
default by "Python.h") and "import_curses()" must be invoked, usually
as part of the module initialisation function, to populate
"PyCurses_API".

Avertissement:

  Neither the C API nor the pure Python "curses" module are compatible
  with subinterpreters.

import_curses()

   Import the curses C API. The macro does not need a semi-colon to be
   called.

   On success, populate the "PyCurses_API" pointer.

   On failure, set "PyCurses_API" to NULL and set an exception. The
   caller must check if an error occurred via "PyErr_Occurred()":

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

void **PyCurses_API

   Dynamically allocated object containing the curses C API. This
   variable is only available once "import_curses" succeeds.

   "PyCurses_API[0]" corresponds to "PyCursesWindow_Type".

   "PyCurses_API[1]", "PyCurses_API[2]", and "PyCurses_API[3]" are
   pointers to predicate functions of type "int (*)(void)".

   When called, these predicates return whether "curses.setupterm()",
   "curses.initscr()", and "curses.start_color()" have been called
   respectively.

   See also the convenience macros "PyCursesSetupTermCalled",
   "PyCursesInitialised", and "PyCursesInitialisedColor".

   Note:

     The number of entries in this structure is subject to changes.
     Consider using "PyCurses_API_pointers" to check if new fields are
     available or not.

PyCurses_API_pointers

   The number of accessible fields ("4") in "PyCurses_API". This
   number is incremented whenever new fields are added.

PyTypeObject PyCursesWindow_Type

   The heap type corresponding to "curses.window".

int PyCursesWindow_Check(PyObject *op)

   Return true if *op* is a "curses.window" instance, false otherwise.

The following macros are convenience macros expanding into C
statements. In particular, they can only be used as "macro;" or
"macro", but not "macro()" or "macro();".

PyCursesSetupTermCalled

   Macro checking if "curses.setupterm()" has been called.

   The macro expansion is roughly equivalent to:

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

PyCursesInitialised

   Macro checking if "curses.initscr()" has been called.

   The macro expansion is roughly equivalent to:

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

PyCursesInitialisedColor

   Macro checking if "curses.start_color()" has been called.

   The macro expansion is roughly equivalent to:

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


Internal data
*************

The following objects are exposed by the C API but should be
considered internal-only.

PyCurses_CAPSULE_NAME

   Name of the curses capsule to pass to "PyCapsule_Import()".

   Internal usage only. Use "import_curses" instead.
