Spaces:
Running on Zero
Running on Zero
File size: 4,015 Bytes
9273228 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | # Curses C API
`curses`{.interpreted-text role="mod"} exposes a small C interface for extension modules. Consumers must include the header file `py_curses.h`{.interpreted-text role="file"} (which is not included by default by `Python.h`{.interpreted-text role="file"}) and `import_curses`{.interpreted-text role="c:func"} must be invoked, usually as part of the module initialisation function, to populate `PyCurses_API`{.interpreted-text role="c:var"}.
:::: warning
::: title
Warning
:::
Neither the C API nor the pure Python `curses`{.interpreted-text role="mod"} module are compatible with subinterpreters.
::::
> Import the curses C API. The macro does not need a semi-colon to be called.
>
> On success, populate the `PyCurses_API`{.interpreted-text role="c:var"} pointer.
>
> On failure, set `PyCurses_API`{.interpreted-text role="c:var"} to NULL and set an exception. The caller must check if an error occurred via `PyErr_Occurred`{.interpreted-text role="c:func"}:
>
> ```
> import_curses(); // semi-colon is optional but recommended
> if (PyErr_Occurred()) { /* cleanup */ }
> ```
> Dynamically allocated object containing the curses C API. This variable is only available once `import_curses`{.interpreted-text role="c:macro"} succeeds.
>
> `PyCurses_API[0]` corresponds to `PyCursesWindow_Type`{.interpreted-text role="c:data"}.
>
> `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`{.interpreted-text role="func"}, `curses.initscr`{.interpreted-text role="func"}, and `curses.start_color`{.interpreted-text role="func"} have been called respectively.
>
> See also the convenience macros `PyCursesSetupTermCalled`{.interpreted-text role="c:macro"}, `PyCursesInitialised`{.interpreted-text role="c:macro"}, and `PyCursesInitialisedColor`{.interpreted-text role="c:macro"}.
>
> :::: note
> ::: title
> Note
> :::
>
> The number of entries in this structure is subject to changes. Consider using `PyCurses_API_pointers`{.interpreted-text role="c:macro"} to check if new fields are available or not.
> ::::
> The number of accessible fields (`4`) in `PyCurses_API`{.interpreted-text role="c:var"}. This number is incremented whenever new fields are added.
> The `heap type <heap-types>`{.interpreted-text role="ref"} corresponding to `curses.window`{.interpreted-text role="class"}.
> Return true if *op* is a `curses.window`{.interpreted-text role="class"} 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();`.
> Macro checking if `curses.setupterm`{.interpreted-text role="func"} 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;
> }
> }
> ```
> Macro checking if `curses.initscr`{.interpreted-text role="func"} 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;
> }
> }
> ```
> Macro checking if `curses.start_color`{.interpreted-text role="func"} 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.
> Name of the curses capsule to pass to `PyCapsule_Import`{.interpreted-text role="c:func"}.
>
> Internal usage only. Use `import_curses`{.interpreted-text role="c:macro"} instead.
|