mirror of
https://github.com/python/cpython.git
synced 2025-12-08 06:10:17 +00:00
138 lines
3.8 KiB
ReStructuredText
138 lines
3.8 KiB
ReStructuredText
.. highlight:: c
|
|
|
|
Curses C API
|
|
------------
|
|
|
|
:mod:`curses` exposes a small C interface for extension modules.
|
|
Consumers must include the header file :file:`py_curses.h` (which is not
|
|
included by default by :file:`Python.h`) and :c:func:`import_curses` must
|
|
be invoked, usually as part of the module initialisation function, to populate
|
|
:c:var:`PyCurses_API`.
|
|
|
|
.. warning::
|
|
|
|
Neither the C API nor the pure Python :mod:`curses` module are compatible
|
|
with subinterpreters.
|
|
|
|
.. c:macro:: import_curses()
|
|
|
|
Import the curses C API. The macro does not need a semi-colon to be called.
|
|
|
|
On success, populate the :c:var:`PyCurses_API` pointer.
|
|
|
|
On failure, set :c:var:`PyCurses_API` to NULL and set an exception.
|
|
The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
|
|
|
|
.. code-block::
|
|
|
|
import_curses(); // semi-colon is optional but recommended
|
|
if (PyErr_Occurred()) { /* cleanup */ }
|
|
|
|
|
|
.. c:var:: void **PyCurses_API
|
|
|
|
Dynamically allocated object containing the curses C API.
|
|
This variable is only available once :c:macro:`import_curses` succeeds.
|
|
|
|
``PyCurses_API[0]`` corresponds to :c:data:`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 :func:`curses.setupterm`,
|
|
:func:`curses.initscr`, and :func:`curses.start_color` have been called
|
|
respectively.
|
|
|
|
See also the convenience macros :c:macro:`PyCursesSetupTermCalled`,
|
|
:c:macro:`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`.
|
|
|
|
.. note::
|
|
|
|
The number of entries in this structure is subject to changes.
|
|
Consider using :c:macro:`PyCurses_API_pointers` to check if
|
|
new fields are available or not.
|
|
|
|
|
|
.. c:macro:: PyCurses_API_pointers
|
|
|
|
The number of accessible fields (``4``) in :c:var:`PyCurses_API`.
|
|
This number is incremented whenever new fields are added.
|
|
|
|
|
|
.. c:var:: PyTypeObject PyCursesWindow_Type
|
|
|
|
The :ref:`heap type <heap-types>` corresponding to :class:`curses.window`.
|
|
|
|
|
|
.. c:function:: int PyCursesWindow_Check(PyObject *op)
|
|
|
|
Return true if *op* is a :class:`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();``.
|
|
|
|
.. c:macro:: PyCursesSetupTermCalled
|
|
|
|
Macro checking if :func:`curses.setupterm` has been called.
|
|
|
|
The macro expansion is roughly equivalent to:
|
|
|
|
.. code-block::
|
|
|
|
{
|
|
typedef int (*predicate_t)(void);
|
|
predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
|
|
if (!was_setupterm_called()) {
|
|
return NULL;
|
|
}
|
|
}
|
|
|
|
|
|
.. c:macro:: PyCursesInitialised
|
|
|
|
Macro checking if :func:`curses.initscr` has been called.
|
|
|
|
The macro expansion is roughly equivalent to:
|
|
|
|
.. code-block::
|
|
|
|
{
|
|
typedef int (*predicate_t)(void);
|
|
predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
|
|
if (!was_initscr_called()) {
|
|
return NULL;
|
|
}
|
|
}
|
|
|
|
|
|
.. c:macro:: PyCursesInitialisedColor
|
|
|
|
Macro checking if :func:`curses.start_color` has been called.
|
|
|
|
The macro expansion is roughly equivalent to:
|
|
|
|
.. code-block::
|
|
|
|
{
|
|
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.
|
|
|
|
.. c:macro:: PyCurses_CAPSULE_NAME
|
|
|
|
Name of the curses capsule to pass to :c:func:`PyCapsule_Import`.
|
|
|
|
Internal usage only. Use :c:macro:`import_curses` instead.
|
|
|