### Build, Test, and Install Notcurses

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Compile Notcurses, run unit tests, and install the library. 'make test' runs notcurses-tester, but hides important output. 'make demo' runs the demo application.

```bash
make
```

```bash
make test
```

```bash
make install
```

```bash
sudo ldconfig
```

```bash
make demo
```

--------------------------------

### Build and Install Python Wrappers

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Build and install the Python wrappers for Notcurses after the core library has been installed. The wrappers are also available via PyPi.

```bash
cd cffi
python setup.py build
python setup.py install
```

--------------------------------

### Install APT Python Wrapper Dependencies

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Install additional packages required for building the Python wrappers for Notcurses on Debian-based systems using APT.

```bash
apt-get install python3-cffi python3-dev python3-pypandoc python3-setuptools
```

--------------------------------

### Install APT Build Dependencies

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Install necessary packages for building Notcurses on Debian-based systems using APT. Core Notcurses can be built without multimedia support by omitting libavdevice-dev. libdeflate-dev can be substituted with zlib1g-dev by using the -DUSE_DEFLATE=off CMake flag. Omit libqrcodegen-dev if QR code generation is not needed.

```bash
apt-get install build-essential cmake doctest-dev libavdevice-dev libdeflate-dev libgpm-dev libncurses-dev libqrcodegen-dev libswscale-dev libunistring-dev pandoc pkg-config
```

--------------------------------

### Install RPM Build Dependencies

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Install necessary packages for building Notcurses on RPM-based systems using DNF. Core Notcurses can be built without multimedia support by omitting OpenImageIO-devel. libdeflate-devel can be substituted with zlib-devel by using the -DUSE_DEFLATE=off CMake flag. Omit libqrcodegen-devel if QR code generation is not needed.

```bash
dnf install cmake doctest-devel libdeflate-devel ncurses-devel gpm-devel libqrcodegen-devel libunistring-devel OpenImageIO-devel pandoc
```

--------------------------------

### Setup fade context

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_fade.3.md

Initializes a fade context structure for more granular control over fading operations.

```APIDOC
## ncfadectx_setup

### Description
Sets up a fade context (`struct ncfadectx`) associated with a given ncplane. This context can be used for more advanced, iterative control over fade operations.

### Function Signature
```c
struct ncfadectx* ncfadectx_setup(struct ncplane* n);
```

### Parameters
*   **n** (struct ncplane*) - The ncplane for which to set up the fade context.
```

--------------------------------

### Install Windows MSYS2 Build Dependencies

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Install necessary packages for building Notcurses on Windows using MSYS2 (UCRT 64-bit). Core Notcurses can be built without multimedia support by omitting mingw-w64-ucrt-x86_64-openimageio. libdeflate can be omitted if not needed for Kitty graphics, by using the -DUSE_DEFLATE=off CMake flag.

```bash
pacman -S mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-libdeflate mingw-w64-ucrt-x86_64-libunistring mingw-w64-ucrt-x86_64-ncurses mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-openimageio mingw-w64-ucrt-x86_64-toolchain
```

--------------------------------

### Install FreeBSD/DragonFly BSD Build Dependencies

Source: https://github.com/dankamongmen/notcurses/blob/master/INSTALL.md

Install necessary packages for building Notcurses on FreeBSD or DragonFly BSD. Core Notcurses can be built without multimedia support by omitting ffmpeg. libdeflate can be omitted if not needed for Kitty graphics, by using the -DUSE_DEFLATE=off CMake flag. Omit qr-code-generator if QR code generation is not needed.

```bash
pkg install archivers/libdeflate devel/ncurses multimedia/ffmpeg graphics/qr-code-generator devel/libunistring
```

--------------------------------

### Get Plane Contents as String

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Creates a flat string from the EGCs of a selected region of the ncplane 'n'. Starts at 'begy'x'begx' and continues for 'leny'x'lenx' cells. Either or both of 'leny' and 'lenx' can be specified as 0 to go through the boundary of the plane. -1 can be specified for 'begx'/'begy' to use the current cursor location.

```c
char* ncplane_contents(const struct ncplane* nc, int begy, int begx,
                       unsigned leny, unsigned lenx);
```

--------------------------------

### Hello World in Direct Mode

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/examples/src/directmode.md

A basic example demonstrating how to initialize direct mode, print a message, and clean up resources. Ensure the TERM environment variable is set correctly.

```c
#include <ncdirect.h>
#include <stdio.h>

int main() {
  struct ncdirect* nc = ncdirect_init(NULL, NULL, 0);
  if (nc == NULL) {
    fprintf(stderr, "Failed to initialize ncdirect mode\n");
    return 1;
  }

  // Print "Hello, world!\n" to stdout
  printf("Hello, world!\n");

  // Stop ncdirect mode and release resources
  ncdirect_stop(nc);
  return 0;
}
```

--------------------------------

### notcurses_init

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_init.3.md

Initializes a Notcurses instance with the specified options and output file pointer. This is the primary function to start using the Notcurses library.

```APIDOC
## notcurses_init

### Description
Initializes a Notcurses instance. This function sets up the terminal for use with the Notcurses library, applying the provided options.

### Signature
```c
struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);
```

### Parameters
- **opts** (*const notcurses_options***): A pointer to a `notcurses_options` struct containing configuration settings.
- **fp** (*FILE***): A file pointer for output, typically `stdout`.
```

--------------------------------

### Fill Area with Cell Content

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Fills a region of a plane starting from a given coordinate with the content of a cell. It replaces cells with the same initial glyph as the starting cell.

```c
int ncplane_polyfill_yx(struct ncplane* n, unsigned y, unsigned x, const nccell* c);
```

--------------------------------

### notcurses_core_init

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Initializes a Notcurses context without multimedia functionality, resulting in a smaller binary. Link with notcurses-core if this is used.

```APIDOC
## notcurses_core_init

### Description
The same as notcurses_init(), but without any multimedia functionality, allowing for a svelter binary. Link with notcurses-core if this is used.

### Method
`struct notcurses* notcurses_core_init(const notcurses_options* opts, FILE* fp);`
```

--------------------------------

### Upload HTML Documentation

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Copy generated HTML documentation to the web server.

```bash
scp *.html ../doc/man/index.html qemfd.net:/var/www/notcurses/

```

```bash
scp -r html qemfd.net:/var/www/notcurses/

```

--------------------------------

### Plane Below

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Get the plane directly below the specified plane in the z-order.

```APIDOC
## ncplane_below

### Description
Returns the plane below the specified ncplane.

### Return Value
Returns a pointer to the plane below, or NULL if the provided plane is the bottommost. This function cannot fail.
```

--------------------------------

### Execute Release Script

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Run the main release script to automate version bumping, tagging, and publishing.

```bash
tools/release.sh $OLDVERSION $VERSION "quip"

```

--------------------------------

### Parent Plane Access

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Functions to get the parent of a plane.

```APIDOC
## ncplane_parent

### Description
Returns the parent plane of plane `n`.

### Signature
```c
struct ncplane* ncplane_parent(struct ncplane* n);
```

## ncplane_parent_const

### Description
Returns the parent plane of plane `n` as a const pointer.

### Signature
```c
const struct ncplane* ncplane_parent_const(const struct ncplane* n);
```
```

--------------------------------

### Get Base Cell

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the default cell of a plane.

```c
int ncplane_base(struct ncplane* ***ncp***, nccell* ***c***);
```

--------------------------------

### Initialize Notcurses Instance

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_init.3.md

Initializes a Notcurses instance using the provided options and file pointer. This is the primary function to start using the Notcurses library.

```c
struct notcurses* notcurses_init(const notcurses_options* ***opts***, FILE* ***fp***);
```

--------------------------------

### Channel Initializers

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_channels.3.md

Macros to initialize NCCHANNEL and NCCHANNELS structures with RGB values.

```APIDOC
## NCCHANNEL_INITIALIZER

### Description
Initializes a single channel (foreground or background) with Red, Green, and Blue components. It also sets the default background mask.

### Parameters
- **r** (uint32_t) - Red component (0-255)
- **g** (uint32_t) - Green component (0-255)
- **b** (uint32_t) - Blue component (0-255)

## NCCHANNELS_INITIALIZER

### Description
Initializes a pair of channels (foreground and background) with their respective RGB components.

### Parameters
- **fr** (uint32_t) - Foreground Red component (0-255)
- **fg** (uint32_t) - Foreground Green component (0-255)
- **fb** (uint32_t) - Foreground Blue component (0-255)
- **br** (uint32_t) - Background Red component (0-255)
- **bg** (uint32_t) - Background Green component (0-255)
- **bb** (uint32_t) - Background Blue component (0-255)
```

--------------------------------

### Get ncplane Styles

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves the current styling for a given ncplane.

```APIDOC
## ncplane_styles

### Description
Get the current styling for the ncplane 'n'.

### Signature
```c
uint16_t ncplane_styles(const struct ncplane* n);
```
```

--------------------------------

### Get ncplane Styles

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves the current styling attributes for an ncplane.

```c
// Get the current styling for the ncplane 'n'.
uint16_t ncplane_styles(const struct ncplane* n);
```

--------------------------------

### Build Proof-of-Concept C Executables

Source: https://github.com/dankamongmen/notcurses/blob/master/CMakeLists.txt

Globally finds C source files in src/poc and adds them as executables. Configures include directories and links necessary libraries.

```cmake
if(USE_POC)
file(GLOB POCSRCS CONFIGURE_DEPENDS src/poc/*.c)
foreach(f ${POCSRCS})
  get_filename_component(fe "${f}" NAME_WE)
  add_executable(${fe} ${f})
  target_include_directories(${fe}
    BEFORE
    PRIVATE include src "${TERMINFO_INCLUDE_DIRS}"
    "${PROJECT_BINARY_DIR}/include"
  )
  target_link_libraries(${fe}
    PRIVATE notcurses "${TERMINFO_LIBRARIES}" "${LIBM}" "${LIBRT}"
  )
  target_link_directories(${fe}
    PRIVATE "${TERMINFO_LIBRARY_DIRS}"
  )
endforeach()
endif()
```

--------------------------------

### Get Plane Contents

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the character contents of a portion of a plane.

```c
char* ncplane_contents(const struct ncplane* ***nc***, int ***begy***, int ***begx***, unsigned ***leny***, unsigned ***lenx***);
```

--------------------------------

### notcurses_init

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_init.3.md

Initializes the Notcurses library and prepares the terminal for cursor-addressable mode. It takes a file pointer for output, an optional options structure, and an optional termtype string. It returns a pointer to a struct notcurses on success, or NULL on failure. The terminal is reset and resources are freed by calling notcurses_stop.

```APIDOC
## notcurses_init

### Description
Prepares the terminal for cursor-addressable (multiline) mode, writing to some FILE. If the FILE provided as *fp* is NULL, stdout will be used. Whatever FILE is used must be writable, is ideally fully buffered, and must be byte-oriented (see fwide(3)). If the FILE is not connected to a terminal (for example when redirected to a file), /dev/tty will be opened (if possible) for communication with the controlling terminal. Most output (including all styling and coloring) is written to the FILE; only queries need be sent to a true terminal. If no terminal is available (for example when running as a daemon), defaults regarding such things as screen size and the palette are assumed.

The struct notcurses_option passed as *opts* controls behavior. Passing a NULL *opts* is equivalent to passing an all-zero (default) *opts*. A process can have only one Notcurses context active at a time; calling notcurses_init again before calling notcurses_stop will return NULL (this is reliable even if called concurrently from two threads).

On success, a pointer to a valid struct notcurses is returned. NULL is returned on failure. Before the process exits, notcurses_stop(3) should be called to reset the terminal and free up resources.

An appropriate terminfo(5) entry must exist for the terminal. This entry is usually selected using the value of the TERM environment variable (see getenv(3)), but a non-NULL value for *termtype* will override this (terminfo is not used on Microsoft Windows, where it is neither meaningful nor necessary to define TERM). An invalid terminfo specification can lead to reduced performance, reduced display capabilities, and/or display errors. Notcurses natively targets 24bpp/8bpc RGB color, and it is thus desirable to use a terminal with the rgb capability (e.g. xterm's xterm-direct). Colors will otherwise be quantized down to whatever the terminal supports.

If the terminal advertises support for an "alternate screen" via the smcup terminfo capability, Notcurses will employ it by default. This can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in *flags*. Users tend to have strong opinions regarding the alternate screen, so it's often useful to expose this via a command-line option. When the alternate screen is not used, the contents of the terminal at startup remain visible until obliterated, on a cell-by-cell basis (see notcurses_plane(3) for details on clearing the screen at startup without using the alternate screen). If the alternate screen is not available, the display will still be cleared without NCOPTION_NO_ALTERNATE_SCREEN.

Notcurses hides the cursor by default. It can be dynamically enabled, moved, or disabled during execution via notcurses_cursor_enable and notcurses_cursor_disable. It will be hidden while updating the screen. The current location of the terminal cursor can be acquired with notcurses_cursor_yx, whether visible or not.

notcurses_init typically emits some diagnostics at startup, including version information and some details of the configured terminal. This can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also inhibit the performance summary normally printed by notcurses_stop(3).

Notcurses can render to a subregion of the terminal by specifying desired margins on all four sides. By default, all margins are zero, and thus rendering will be performed on the entirety of the viewing area. This is orthogonal to use of the alternate screen; using the alternate screen plus margins will see the full screen cleared, followed by rendering to a subregion. Inhibiting the alternate screen plus margins will render to a subregion, with the screen outside this region not cleared. Margins are best-effort.
notcurses_lex_margins provides lexing a margin argument expression in one of two forms:

* a single number, which will be applied to all sides, or
* four comma-delimited numbers, applied to top, right, bottom, and left.

To allow future options without requiring redefinition of the structure, the *flags* field is only a partially-defined bitfield. Undefined bits should be zero. The following flags are defined:

* NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init will call setlocale(LC_ALL, NULL). If the result is either "C" or "POSIX", it will print a diagnostic to stderr, and then call setlocale(LC_ALL, ""). This will attempt to set the locale based off the LANG environment variable. Your program should call setlocale(3) itself, usually as one of the first lines.

* NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear any preexisting bitmaps. Note that they might still get cleared even if this is set, and they might not get cleared even if this is not set.

### Parameters
#### Path Parameters
- **fp** (*FILE*) - Optional - The file pointer to write output to. If NULL, stdout is used.
- **opts** (*const struct notcurses_option **) - Optional - A pointer to a struct notcurses_option controlling behavior. If NULL, default options are used.
- **termtype** (*const char **) - Optional - A string specifying the terminal type. If NULL, the TERM environment variable is used.

### Returns
- **struct notcurses *** - A pointer to a valid struct notcurses on success.
- **NULL** - On failure.
```

--------------------------------

### Get Plane Parent

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the parent plane of a given plane.

```c
struct ncplane* ncplane_parent(struct ncplane* ***n***);
```

```c
const struct ncplane* ncplane_parent_const(const struct ncplane* ***n***);
```

--------------------------------

### Get the ncplane of an nctablet

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_reel.3.md

Retrieves the ncplane that the nctablet is drawn upon.

```c
struct ncplane* nctablet_plane(struct nctablet* t);
```

--------------------------------

### notcurses_init

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Initializes a Notcurses context on the connected terminal. It can take custom options and a file pointer for the terminal. Returns NULL on error.

```APIDOC
## notcurses_init

### Description
Initializes a Notcurses context on the connected terminal at 'fp'. 'fp' must be a tty. You'll usually want stdout. NULL can be supplied for 'fp', in which case /dev/tty will be opened. Returns NULL on error, including any failure initializing terminfo.

### Method
`struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);`
```

--------------------------------

### ncprogbar_progress

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_progbar.3.md

Gets the current progress value of the progress bar widget.

```APIDOC
## ncprogbar_progress

### Description
Gets the current progress value of the progress bar widget.

### Parameters
#### Path Parameters
- **n** (*const struct ncprogbar***) - The progress bar widget.

### Return Value
Returns the current progress, a value between zero and one, inclusive. This function cannot fail.
```

--------------------------------

### Alternate Screen Usage Example

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Demonstrates entering and exiting the alternate screen. This is useful for applications that need to temporarily take over the full terminal display.

```c
// Shift to the alternate screen, if available. If already using the alternate
// screen, this returns 0 immediately. If the alternate screen is not
```

--------------------------------

### Initialize Notcurses Core Context

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Initializes a Notcurses context without multimedia functionality for a smaller binary size. Link with notcurses-core if using this function.

```c
// The same as notcurses_init(), but without any multimedia functionality,
// allowing for a svelter binary. Link with notcurses-core if this is used.
struct notcurses* notcurses_core_init(const notcurses_options* opts, FILE* fp);
```

--------------------------------

### Get the ncplane of an ncreel

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_reel.3.md

Retrieves the ncplane associated with an ncreel widget.

```c
struct ncplane* ncreel_plane(struct ncreel* nr);
```

--------------------------------

### Get ncplane from ncsubproc

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_fds.3.md

Retrieves the associated ncplane from an ncsubproc object.

```c
struct ncplane* ncsubproc_plane(struct ncsubproc* ***n***);
```

--------------------------------

### Initialize Notcurses Context

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Initializes a Notcurses context on the specified file pointer. If NULL is provided for 'fp', /dev/tty will be used. Returns NULL on error, including terminfo initialization failures.

```c
// Initialize a Notcurses context on the connected terminal at 'fp'. 'fp' must
// be a tty. You'll usually want stdout. NULL can be supplied for 'fp',
// in which case /dev/tty will be opened. Returns NULL on error, including any
// failure initializing terminfo.
struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);
```

--------------------------------

### Get ncplane from ncfdplane

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_fds.3.md

Retrieves the associated ncplane from an ncfdplane object.

```c
struct ncplane* ncfdplane_plane(struct ncfdplane* ***n***);
```

--------------------------------

### Direct Mode Options

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Bitmask options for ncdirect_init() and ncdirect_core_init().

```APIDOC
## NCDIRECT_OPTION_INHIBIT_SETLOCALE

### Description
Prevents ncdirect_init() from calling setlocale() to inspect or set the locale. Use this if you are managing locale settings yourself before calling Notcurses initialization.

## NCDIRECT_OPTION_INHIBIT_CBREAK

### Description
Do not place the terminal into cbreak mode. By default, echo and line buffering are turned off. Using this flag may interfere with ncdirect_readline().

## NCDIRECT_OPTION_DRAIN_INPUT

### Description
Allows input to be freely dropped. Provide this when the program does not intend to handle input to prevent internal buffers from accumulating and potentially blocking Notcurses.

## NCDIRECT_OPTION_NO_QUIT_SIGHANDLERS

### Description
Inhibits the registration of signal handlers for SIG{INT, SEGV, ABRT, QUIT} that restore the screen and call the old signal handler.

## NCDIRECT_OPTION_VERBOSE

### Description
Enables logging to stderr at the NCLOGLEVEL_WARNING level.

## NCDIRECT_OPTION_VERY_VERBOSE

### Description
Enables logging to stderr at the NCLOGLEVEL_TRACE level, which includes all diagnostics and implies NCDIRECT_OPTION_VERBOSE.
```

--------------------------------

### Get Extended Gcluster

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves a pointer to the NUL-terminated EGC referenced by a cell.

```APIDOC
## nccell_extended_gcluster

### Description
Returns a pointer to the NUL-terminated EGC referenced by 'c'. This pointer is invalidated by any further operation on the plane 'n'.

### Signature
const char* nccell_extended_gcluster(const struct ncplane* n, const nccell* c);

### Returns
A pointer to the EGC string.
```

--------------------------------

### Get Plane as RGBA

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Converts a portion of a plane to an RGBA pixel buffer.

```c
uint32_t* ncplane_as_rgba(const struct ncplane* ***nc***, ncblitter_e ***blit***, unsigned ***begy***, unsigned ***begx***, unsigned ***leny***, unsigned ***lenx***, unsigned* ***pxdimy***, unsigned* ***pxdimx***);
```

--------------------------------

### Get Cell at YX

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the nccell structure at a specific (y, x) position.

```c
int ncplane_at_yx_cell(struct ncplane* ***n***, int ***y***, int ***x***, nccell* ***c***);
```

--------------------------------

### Initializer Macros for Notcurses Channels

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_channels.3.md

Macros to initialize single channels (foreground/background RGB) and channel pairs. Use these to create channel structures with specific color values.

```c
#define NCCHANNEL_INITIALIZER(r, g, b) \
  (((uint32_t)r << 16u) + ((uint32_t)g << 8u) + (b) + NC_BGDEFAULT_MASK)

#define NCCHANNELS_INITIALIZER(fr, fg, fb, br, bg, bb) \
  ((NCCHANNEL_INITIALIZER(fr, fg, fb) << 32ull) +
   (NCCHANNEL_INITIALIZER(br, bg, bb)))
```

--------------------------------

### Get Cell at Cursor

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the nccell structure at the current cursor position.

```c
int ncplane_at_cursor_cell(struct ncplane* ***n***, nccell* ***c***);
```

--------------------------------

### Build Debian Source Package

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Build the source package for Debian.

```bash
dpkg-buildpackage --build=source

```

--------------------------------

### Import Original Tarball

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Import the repackaged original tarball into the build system.

```bash
gbp import-orig ../notcurses_$VERSION+dfsg.orig.tar.xz

```

--------------------------------

### Get Plane Above

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the plane directly above the given plane in the stacking order.

```c
struct ncplane* ncplane_above(struct ncplane* ***n***);
```

--------------------------------

### Get Plane Below

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the plane directly below the given plane in the stacking order.

```c
struct ncplane* ncplane_below(struct ncplane* ***n***);
```

--------------------------------

### Initialize Notcurses and Refresh Screen

Source: https://github.com/dankamongmen/notcurses/blob/master/README.md

Call notcurses_refresh() immediately after notcurses_init() to clear the screen on startup when not using the alternate screen. This ensures a clean display before any other rendering.

```c
notcurses_refresh();
```

--------------------------------

### Get Plane Y Coordinate

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the current y-coordinate of the cursor within a plane.

```c
int ncplane_y(const struct ncplane* ***n***);
```

--------------------------------

### Test Alpine Linux APKBUILD

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Test the APKBUILD file for Alpine Linux packaging.

```bash
abuild -r

```

--------------------------------

### Get Terminal Height

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_direct.3.md

Returns the height of the terminal in rows for direct mode.

```c
unsigned ncdirect_dim_y(const struct ncdirect* ***nc***);
```

--------------------------------

### Build Debian Binaries with Pbuilder

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Build the binary packages using pbuilder in an xterm environment.

```bash
cd .. && export TERM=xterm-256color && sudo pbuilder build *dsc

```

--------------------------------

### Get Terminal Width

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_direct.3.md

Returns the width of the terminal in columns for direct mode.

```c
unsigned ncdirect_dim_x(const struct ncdirect* ***nc***);
```

--------------------------------

### Initialization and Cleanup

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_direct.3.md

Functions for initializing and stopping the direct mode Notcurses interface.

```APIDOC
## ncdirect_init

### Description
Initializes the direct mode Notcurses interface.

### Parameters
- **termtype** (const char*) - The terminal type string.
- **fp** (FILE*) - The file pointer to use for output.
- **flags** (uint64_t) - Options to control initialization behavior.

### Returns
A pointer to a `struct ncdirect` on success, NULL on failure.
```

```APIDOC
## ncdirect_stop

### Description
Stops and cleans up the direct mode Notcurses interface.

### Parameters
- **nc** (struct ncdirect*) - The `ncdirect` structure to stop.

### Returns
0 on success, -1 on failure.
```

--------------------------------

### ncsubproc Creation (vp)

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_fds.3.md

Creates a new ncsubproc object to execute a command and write its output to a given ncplane. Uses a vector of arguments, similar to createv.

```c
struct ncsubproc* ncsubproc_createvp(struct ncplane* ***n***, const ncsubproc_options* ***opts***, const char* ***bin***,  char* const ***arg***[], ncfdplane_callback ***cbfxn***, ncfdplane_done_cb ***donecbfxn***);
```

--------------------------------

### Configure version and build definition headers

Source: https://github.com/dankamongmen/notcurses/blob/master/CMakeLists.txt

Generates the version.h and builddef.h header files from their respective input templates. These files are typically used to provide build-time information to the library.

```cmake
configure_file(tools/version.h.in include/version.h)
configure_file(tools/builddef.h.in include/builddef.h)
```

--------------------------------

### Fill Plane

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_lines.3.md

Fills a region of the plane starting from the given coordinates with the specified cell.

```APIDOC
## ncplane_polyfill_yx

### Description
Fills a region of the plane starting from the given coordinates with the specified cell.

### Signature
```c
int ncplane_polyfill_yx(struct ncplane* n, unsigned y, unsigned x, const nccell* c);
```

### Parameters
- **n** (*struct ncplane*): The target plane.
- **y** (*unsigned*): The starting y-coordinate.
- **x** (*unsigned*): The starting x-coordinate.
- **c** (*const nccell*): The cell to use for filling.
```

--------------------------------

### notcurses_core_init

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_core.3.md

Initializes a Notcurses screen using the core library, suitable for applications that do not require multimedia capabilities. This function replaces notcurses_init when linking against libnotcurses-core.

```APIDOC
## notcurses_core_init

### Description
Initializes a Notcurses screen using the core library, suitable for applications that do not require multimedia capabilities. This function replaces notcurses_init when linking against libnotcurses-core.

### Signature
```c
struct notcurses* notcurses_core_init(const notcurses_options* opts, FILE* fp);
```

### Parameters
*   **opts** (*const notcurses_options***): A pointer to a structure containing options for initializing Notcurses.
*   **fp** (*FILE***): A file pointer, typically stdout, for the terminal output.
```

--------------------------------

### Get Pixel from ncvisual

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves the RGBA value of a pixel at the specified coordinates from the `ncvisual`.

```c
int ncvisual_at_yx(const struct ncvisual* n, unsigned y, unsigned x,
                   uint32_t* pixel);
```

--------------------------------

### Generate Arch Linux .SRCINFO

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Generate the .SRCINFO file for Arch Linux packaging.

```bash
makepkg --printsrcinfo > .SRCINFO

```

--------------------------------

### Upload Python Package

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/release-checklist.md

Build and upload the Python package to PyPI using twine.

```bash
python3 setup.py sdist

```

```bash
twine upload dist/*

```

--------------------------------

### Get Progress Bar Progress

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves the current completion percentage of the progress bar.

```APIDOC
## ncprogbar_progress

### Description
Gets the current completion percentage of the progress bar.

### Signature
```c
double ncprogbar_progress(const struct ncprogbar* n);
```

### Parameters
- **n** (const struct ncprogbar*) - A pointer to the progress bar.

### Returns
- (double) - The current progress value, between 0.0 and 1.0.
```

--------------------------------

### Get Progress Bar Plane

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Returns a reference to the ncplane associated with the progress bar.

```c
struct ncplane* ncprogbar_plane(struct ncprogbar* n);
```

--------------------------------

### Create a new palette

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_palette.3.md

Allocates and initializes a new notcurses palette. Ensure to free it with ncpalette_free when done.

```c
ncpalette* ncpalette_new(struct notcurses* ***nc***);
```

--------------------------------

### Get ncplane Channels

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Retrieves the current colors and alpha values for a given ncplane.

```APIDOC
## ncplane_channels

### Description
Get the current colors and alpha values for ncplane 'n'.

### Signature
```c
uint64_t ncplane_channels(const struct ncplane* n);
```
```

--------------------------------

### Create ncvisual from BGRA memory

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Prepare an ncvisual from BGRA content in memory. Requires a notcurses context.

```c
// ncvisual_from_rgba(), but for BGRA.
struct ncvisual* ncvisual_from_bgra(struct notcurses* nc, const void* bgra,
                                    int rows, int rowstride, int cols);
```

--------------------------------

### Tablet Growth Example 2

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Illustrates a non-focused tablet (A) growing upwards. This behavior is observed to avoid moving the currently focused tablet (B).

```text
 -------------
 | ---------
 | |   A   |
 | |       |
 | ---------
 | ---------
 | |XX B XX|
 | ---------
 | ---------
 | |   C   |
 | ---------
 -------------

 -------------
 | |       |
 | |   A   |
 | |       |
 | ---------
 | ---------
 | |XX B XX|
 | ---------
 | ---------
 | |   C   |
 | ---------
 -------------
```

--------------------------------

### User Pointer Management

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Functions to get and set a user-defined pointer associated with an ncplane.

```APIDOC
## ncplane_set_userptr

### Description
Sets a user-defined pointer for the given ncplane and returns the previous pointer.

### Method
`void* ncplane_set_userptr(struct ncplane* n, void* opaque);`

### Parameters
- **n** (`struct ncplane*`) - The target ncplane.
- **opaque** (`void*`) - The new user pointer to set.

### Returns
- `void*` - The previous user pointer associated with the ncplane.
```

```APIDOC
## ncplane_userptr

### Description
Retrieves the user-defined pointer associated with the given ncplane.

### Method
`void* ncplane_userptr(struct ncplane* n);`

### Parameters
- **n** (`struct ncplane*`) - The target ncplane.

### Returns
- `void*` - The current user pointer associated with the ncplane.
```

--------------------------------

### Plane Alpha Channels

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Functions for getting and setting foreground and background alpha values.

```APIDOC
## Plane Alpha Channels

### Description
Functions to retrieve and set the alpha (transparency) values for the foreground and background of an ncplane.

### Functions
- **`ncplane_fg_alpha`**: Retrieves the foreground alpha value.
- **`ncplane_bg_alpha`**: Retrieves the background alpha value.
- **`ncplane_set_fg_alpha`**: Sets the foreground alpha value.
- **`ncplane_set_bg_alpha`**: Sets the background alpha value.

### Signatures
```c
static inline unsigned ncplane_fg_alpha(struct ncplane* nc);
static inline unsigned ncplane_bg_alpha(struct ncplane* nc);
int ncplane_set_fg_alpha(struct ncplane* n, unsigned alpha);
int ncplane_set_bg_alpha(struct ncplane* n, unsigned alpha);
```
```

--------------------------------

### Build notcurses-demo Executable

Source: https://github.com/dankamongmen/notcurses/blob/master/CMakeLists.txt

Adds the 'notcurses-demo' executable, compiling C source files from src/demo and linking against notcurses and other libraries. Defines _GNU_SOURCE compilation macro.

```cmake
if(BUILD_EXECUTABLES)
############################################################################
# notcurses-demo
file(GLOB DEMOSRCS CONFIGURE_DEPENDS src/demo/*.c)
add_executable(notcurses-demo ${DEMOSRCS} ${COMPATSRC})
target_compile_definitions(notcurses-demo
  PRIVATE
    _GNU_SOURCE
)
target_include_directories(notcurses-demo
  BEFORE
  PRIVATE
    include
    src
    "${TERMINFO_INCLUDE_DIRS}"
    "${CMAKE_REQUIRED_INCLUDES}"
    "${PROJECT_BINARY_DIR}/include"
)
target_link_libraries(notcurses-demo
  PRIVATE
    notcurses
    ${LIBM}
    ${LIBRT}
    Threads::Threads
)

############################################################################

```

--------------------------------

### Plane Channels (Colors)

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Functions for getting and setting foreground and background color channels.

```APIDOC
## Plane Color Channels

### Description
Functions to manage the foreground and background color channels of an ncplane, including RGB and palette index settings.

### Functions
- **`ncplane_channels`**: Retrieves the combined foreground and background channels.
- **`ncplane_set_channels`**: Sets both foreground and background channels.
- **`ncplane_bchannel`**: Retrieves the background channel.
- **`ncplane_fchannel`**: Retrieves the foreground channel.
- **`ncplane_set_bchannel`**: Sets the background channel.
- **`ncplane_set_fchannel`**: Sets the foreground channel.
- **`ncplane_fg_rgb`**: Retrieves the foreground RGB color.
- **`ncplane_bg_rgb`**: Retrieves the background RGB color.
- **`ncplane_set_fg_rgb`**: Sets the foreground RGB color.
- **`ncplane_set_bg_rgb`**: Sets the background RGB color.
- **`ncplane_fg_rgb8`**: Retrieves the 8-bit RGB components of the foreground color.
- **`ncplane_bg_rgb8`**: Retrieves the 8-bit RGB components of the background color.
- **`ncplane_set_fg_rgb8`**: Sets the foreground color using 8-bit RGB components.
- **`ncplane_set_bg_rgb8`**: Sets the background color using 8-bit RGB components.
- **`ncplane_set_fg_rgb8_clipped`**: Sets the foreground color using 8-bit RGB components, clipping values if necessary.
- **`ncplane_set_bg_rgb8_clipped`**: Sets the background color using 8-bit RGB components, clipping values if necessary.
- **`ncplane_set_fg_default`**: Resets the foreground color to the default.
- **`ncplane_set_bg_default`**: Resets the background color to the default.
- **`ncplane_set_fg_palindex`**: Sets the foreground color using a palette index.
- **`ncplane_set_bg_palindex`**: Sets the background color using a palette index.

### Signatures
```c
uint64_t ncplane_channels(const struct ncplane* n);
void ncplane_set_channels(struct ncplane* nc, uint64_t channels);
static inline unsigned ncplane_bchannel(struct ncplane* nc);
static inline unsigned ncplane_fchannel(struct ncplane* nc);
uint64_t ncplane_set_bchannel(struct ncplane* nc, uint32_t channel);
uint64_t ncplane_set_fchannel(struct ncplane* nc, uint32_t channel);
static inline unsigned ncplane_fg_rgb(struct ncplane* nc);
static inline unsigned ncplane_bg_rgb(struct ncplane* nc);
int ncplane_set_fg_rgb(struct ncplane* n, uint32_t channel);
int ncplane_set_bg_rgb(struct ncplane* n, uint32_t channel);
static inline unsigned ncplane_fg_rgb8(struct ncplane* n, unsigned* r, unsigned* g, unsigned* b);
static inline unsigned ncplane_bg_rgb8(struct ncplane* n, unsigned* r, unsigned* g, unsigned* b);
int ncplane_set_fg_rgb8(struct ncplane* n, unsigned r, unsigned g, unsigned b);
int ncplane_set_bg_rgb8(struct ncplane* n, unsigned r, unsigned g, unsigned b);
void ncplane_set_fg_rgb8_clipped(struct ncplane* n, int r, int g, int b);
void ncplane_set_bg_rgb8_clipped(struct ncplane* n, int r, int g, int b);
void ncplane_set_fg_default(struct ncplane* n);
void ncplane_set_bg_default(struct ncplane* n);
int ncplane_set_fg_palindex(struct ncplane* n, unsigned idx);
int ncplane_set_bg_palindex(struct ncplane* n, unsigned idx);
```
```

--------------------------------

### ncsubproc Creation (vpe)

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_fds.3.md

Creates a new ncsubproc object to execute a command with specified environment variables and write its output to a given ncplane. Uses a vector of arguments and environment variables.

```c
struct ncsubproc* ncsubproc_createvpe(struct ncplane* ***n***, const ncsubproc_options* ***opts***, const char* ***bin***,  char* const ***arg***[], char* const ***env***[], ncfdplane_callback ***cbfxn***, ncfdplane_done_cb ***donecbfxn***);
```

--------------------------------

### Plane Dimensions

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Functions to get the dimensions (rows and columns) and cursor position of an ncplane.

```APIDOC
## Plane Dimensions and Cursor

### Description
These functions provide information about the dimensions (rows and columns) and the current cursor position within an ncplane.

### Functions
- **`ncplane_dim_yx`**: Sets the provided `rows` and `cols` pointers to the dimensions of the plane.
- **`ncplane_dim_y`**: Returns the number of rows in the plane.
- **`ncplane_dim_x`**: Returns the number of columns in the plane.
- **`ncplane_cursor_yx`**: Sets the provided `y` and `x` pointers to the current cursor coordinates.
- **`ncplane_cursor_y`**: Returns the current row of the cursor.
- **`ncplane_cursor_x`**: Returns the current column of the cursor.

### Signatures
```c
void ncplane_dim_yx(const struct ncplane* n, unsigned* restrict rows, unsigned* restrict cols);
static inline unsigned ncplane_dim_y(const struct ncplane* n);
static inline unsigned ncplane_dim_x(const struct ncplane* n);
void ncplane_cursor_yx(const struct ncplane* n, unsigned* restrict y, unsigned* restrict x);
unsigned ncplane_cursor_y(const struct ncplane* n);
unsigned ncplane_cursor_x(const struct ncplane* n);
```
```

--------------------------------

### Cursor Movement

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Functions to move the cursor horizontally and vertically, and to get its current position.

```APIDOC
## Cursor Movement

### `ncdirect_cursor_right(struct ncdirect* nc, int num)`

Moves the cursor `num` columns to the right.

### `ncdirect_cursor_down(struct ncdirect* nc, int num)`

Moves the cursor `num` rows down.

### `ncdirect_cursor_yx(struct ncdirect* n, unsigned* y, unsigned* x)`

Gets the cursor's current row (`y`) and column (`x`) position. This operation might be terminal-dependent and could have side effects.
```

--------------------------------

### Build Proof-of-Concept C++ Executables

Source: https://github.com/dankamongmen/notcurses/blob/master/CMakeLists.txt

Globally finds C++ source files in src/pocpp and adds them as executables if USE_CXX is enabled. Configures include directories and links necessary libraries.

```cmake
if(${USE_CXX})
  file(GLOB POCPPSRCS CONFIGURE_DEPENDS src/pocpp/*.cpp)
  foreach(f ${POCPPSRCS})
    get_filename_component(fe "${f}" NAME_WE)
    add_executable(${fe} ${f})
    target_include_directories(${fe}
      BEFORE
      PRIVATE include src "${TERMINFO_INCLUDE_DIRS}"
      "${PROJECT_BINARY_DIR}/include"
    )
    target_link_libraries(${fe}
      PRIVATE notcurses++ "${TERMINFO_LIBRARIES}" "${LIBM}" "${LIBRT}"
    )
    target_link_directories(${fe}
      PRIVATE "${TERMINFO_LIBRARY_DIRS}"
    )
  endforeach()
endif()
```

--------------------------------

### Get Character at YX

Source: https://github.com/dankamongmen/notcurses/blob/master/doc/man/man3/notcurses_plane.3.md

Retrieves the character, style, and channels at a specific (y, x) position.

```c
char* ncplane_at_yx(const struct ncplane* ***n***, int ***y***, int ***x***, uint16_t* ***stylemask***, uint64_t* ***channels***);
```

--------------------------------

### Create and Blit ncvisual to Plane

Source: https://github.com/dankamongmen/notcurses/blob/master/USAGE.md

Creates a new plane based on `opts` and blits the `ncvisual` to it according to `vopts`. Requires `NCVISUAL_OPTION_CHILDPLANE` if `vopts->n` is non-NULL.

```c
static inline struct ncplane*
ncvisualplane_create(struct notcurses* nc, const struct ncplane_options* opts,
                     struct ncvisual* ncv, struct ncvisual_options* vopts);
```