Debian Codegraph @

Doc/c-api/curses.rst

raw
1 .. highlight:: c
2
3 Curses C API
4 ------------
5
6 :mod:`curses` exposes a small C interface for extension modules.
7 Consumers must include the header file :file:`py_curses.h` (which is not
8 included by default by :file:`Python.h`) and :c:func:`import_curses` must
9 be invoked, usually as part of the module initialisation function, to populate
10 :c:var:`PyCurses_API`.
11
12 .. warning::
13
14 Neither the C API nor the pure Python :mod:`curses` module are compatible
15 with subinterpreters.
16
17 .. c:macro:: import_curses()
18
19 Import the curses C API. The macro does not need a semi-colon to be called.
20
21 On success, populate the :c:var:`PyCurses_API` pointer.
22
23 On failure, set :c:var:`PyCurses_API` to NULL and set an exception.
24 The caller must check if an error occurred via :c:func:`PyErr_Occurred`:
25
26 .. code-block::
27
28 import_curses(); // semi-colon is optional but recommended
29 if (PyErr_Occurred()) { /* cleanup */ }
30
31
32 .. c:var:: void **PyCurses_API
33
34 Dynamically allocated object containing the curses C API.
35 This variable is only available once :c:macro:`import_curses` succeeds.
36
37 ``PyCurses_API[0]`` corresponds to :c:data:`PyCursesWindow_Type`.
38
39 ``PyCurses_API[1]``, ``PyCurses_API[2]``, and ``PyCurses_API[3]``
40 are pointers to predicate functions of type ``int (*)(void)``.
41
42 When called, these predicates return whether :func:`curses.setupterm`,
43 :func:`curses.initscr`, and :func:`curses.start_color` have been called
44 respectively.
45
46 See also the convenience macros :c:macro:`PyCursesSetupTermCalled`,
47 :c:macro:`PyCursesInitialised`, and :c:macro:`PyCursesInitialisedColor`.
48
49 .. note::
50
51 The number of entries in this structure is subject to changes.
52 Consider using :c:macro:`PyCurses_API_pointers` to check if
53 new fields are available or not.
54
55
56 .. c:macro:: PyCurses_API_pointers
57
58 The number of accessible fields (``4``) in :c:var:`PyCurses_API`.
59 This number is incremented whenever new fields are added.
60
61
62 .. c:var:: PyTypeObject PyCursesWindow_Type
63
64 The :ref:`heap type <heap-types>` corresponding to :class:`curses.window`.
65
66
67 .. c:function:: int PyCursesWindow_Check(PyObject *op)
68
69 Return true if *op* is a :class:`curses.window` instance, false otherwise.
70
71
72 The following macros are convenience macros expanding into C statements.
73 In particular, they can only be used as ``macro;`` or ``macro``, but not
74 ``macro()`` or ``macro();``.
75
76 .. c:macro:: PyCursesSetupTermCalled
77
78 Macro checking if :func:`curses.setupterm` has been called.
79
80 The macro expansion is roughly equivalent to:
81
82 .. code-block::
83
84 {
85 typedef int (*predicate_t)(void);
86 predicate_t was_setupterm_called = (predicate_t)PyCurses_API[1];
87 if (!was_setupterm_called()) {
88 return NULL;
89 }
90 }
91
92
93 .. c:macro:: PyCursesInitialised
94
95 Macro checking if :func:`curses.initscr` has been called.
96
97 The macro expansion is roughly equivalent to:
98
99 .. code-block::
100
101 {
102 typedef int (*predicate_t)(void);
103 predicate_t was_initscr_called = (predicate_t)PyCurses_API[2];
104 if (!was_initscr_called()) {
105 return NULL;
106 }
107 }
108
109
110 .. c:macro:: PyCursesInitialisedColor
111
112 Macro checking if :func:`curses.start_color` has been called.
113
114 The macro expansion is roughly equivalent to:
115
116 .. code-block::
117
118 {
119 typedef int (*predicate_t)(void);
120 predicate_t was_start_color_called = (predicate_t)PyCurses_API[3];
121 if (!was_start_color_called()) {
122 return NULL;
123 }
124 }
125
126
127 Internal data
128 -------------
129
130 The following objects are exposed by the C API but should be considered
131 internal-only.
132
133 .. c:macro:: PyCurses_CAPSULE_NAME
134
135 Name of the curses capsule to pass to :c:func:`PyCapsule_Import`.
136
137 Internal usage only. Use :c:macro:`import_curses` instead.
138