.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "notcurses" "3" "v3.0.7" "" ""
.hy
.SH NAME
.PP
notcurses - TUI library for modern terminal emulators
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R] or \f[B]#include
<notcurses/notcurses-core.h>\f[R]
.PP
\f[B]-lnotcurses-core -lnotcurses\f[R] or \f[B]-lnotcurses-core\f[R]
.SH DESCRIPTION
.PP
Notcurses builds atop the \f[B]terminfo(5)\f[R] abstraction layer to
provide reasonably portable vivid character displays.
It is an intellectual descendant of \f[B]ncurses(3NCURSES)\f[R], but
goes beyond that library (and the X/Open Curses API it implements).
.PP
A program wishing to use Notcurses will need to link it, ideally using
the output of \f[B]pkg-config --libs notcurses\f[R] (see
\f[B]pkg-config(1)\f[R]).
It is advised to compile with the output of \f[B]pkg-config --cflags
notcurses\f[R].
If using CMake, a support file is provided, and can be accessed as
\f[B]Notcurses\f[R] (see \f[B]cmake(1)\f[R]).
If multimedia capabilities are not needed, it is possible to link
against a minimal Notcurses using \f[B]pkg-config --libs
notcurses-core\f[R].
.PP
\f[B]notcurses_init(3)\f[R] can then be used to initialize a Notcurses
instance for a given \f[B]FILE\f[R]* (usually \f[B]stdout\f[R], usually
attached to a terminal).
.SS The alternate screen
.PP
Many terminals provide an \[dq]alternate screen\[dq] with its own
contents, no scrollback buffer, and no scrolling.
Entering the alternate screen replaces the current visible contents
wholesale, as does returning to the regular screen.
Notcurses refers to the alternate screen\[aq]s semantics as \[dq]TUI
mode\[dq], and the regular screen\[aq]s semantics as \[dq]CLI mode\[dq].
It is possible to swap between the two modes at runtime using
\f[B]notcurses_leave_alternate_screen(3)\f[R] and
\f[B]notcurses_enter_alternate_screen(3)\f[R].
Notcurses will enter TUI mode by default on startup; to prevent this,
use \f[B]NCOPTION_NO_ALTERNATE_SCREEN\f[R] as described in
\f[B]notcurses_init(3)\f[R].
On program exit, Notcurses will always return to the regular screen,
independent of the screen being used on program start.
.SS Construction
.PP
Before calling into Notcurses\[em]and usually as one of the first calls
of the program\[em]be sure to call \f[B]setlocale\f[R] with an
appropriate UTF-8 \f[B]LC_ALL\f[R] locale.
It is usually appropriate to use \f[B]setlocale(LC_ALL,
\[dq]\[dq])\f[R], relying on the user to properly set the \f[B]LANG\f[R]
environment variable.
Notcurses will refuse to start if \f[B]nl_langinfo(3)\f[R] doesn\[aq]t
indicate UTF-8 or ANSI_X3.4-1968 (aka US-ASCII).
Be aware that capabilities are substantially reduced in ASCII.
.PP
\f[B]notcurses_init(3)\f[R] accepts a \f[B]struct notcurses_options\f[R]
allowing fine-grained control of Notcurses behavior, including signal
handlers, alternative screens, and overriding the TERM environment
variable.
A \f[B]terminfo\f[R] entry appropriate for the actual terminal must be
available.
.PP
\f[B]ncdirect_init(3)\f[R] makes available a restricted subset of
Notcurses functionality.
This subset is intended to be interleaved with user-generated output,
and is limited to coloring and styling.
Direct mode is documented in \f[B]notcurses_direct(3)\f[R].
.PP
Only one context can be active in a process at a time, whether direct
mode (\f[B]struct ncdirect\f[R]) or rendered mode (\f[B]struct
notcurses\f[R]).
.SS Output
.PP
All output is performed on \f[B]struct ncplane\f[R]s (see Ncplanes
below).
Output is not visible until explicitly rendered via
\f[B]notcurses_render(3)\f[R].
Information on drawing functions is available at
\f[B]notcurses_output(3)\f[R].
.SS Input
.PP
Notcurses supports input from keyboards (via \f[B]stdin\f[R]) and
pointing devices (via a broker such as GPM, X, or Wayland).
Input is delivered as 32-bit Unicode code points.
Synthesized events such as mouse button presses and arrow keys are
mapped into Unicode\[aq]s Supplementary Private Use
Area-B (https://unicode.org/charts/PDF/U100000.pdf).
Information on input is available at \f[B]notcurses_input(3)\f[R].
The included tool \f[B]notcurses-input(1)\f[R] can be used to test input
decoding.
.SS Ncpiles
.PP
A given \f[B]notcurses\f[R] context is made up of one or more piles.
Piles provide distinct rendering contexts: a thread can be rendering or
mutating one pile, while another thread concurrently renders or mutates
another pile.
A pile is made up of planes, totally ordered on a z-axis.
In addition to the z-ordering, the planes of a pile are bound in a
forest (a set of directed, acyclic graphs).
Those planes which are not bound to some other plane constitute the root
planes of a pile.
A pile is destroyed when all its planes are destroyed, or moved to other
piles.
Since the standard plane (see below) always exists, and cannot be moved
to another pile, one pile always exists, known as the standard pile.
.PP
Note that rasterizing a pile will replace all content within its
margins.
.PP
For more information, see \f[B]notcurses_pile(3)\f[R].
.SS Ncplanes
.PP
Following initialization, a single ncplane exists, the \[dq]standard
plane\[dq] (see \f[B]notcurses_stdplane(3)\f[R]).
This plane cannot be destroyed nor manually resized, and is always
exactly as large as the screen (if run without a TTY, the
\[dq]screen\[dq] is assumed to be 80x24 cells).
Further ncplanes can be created with \f[B]ncplane_create(3)\f[R].
A total z-ordering always exists on the set of ncplanes, and new
ncplanes are placed at the top of the z-buffer.
Ncplanes can be larger, smaller, or the same size as the physical
screen, and can be placed anywhere relative to it (including entirely
off-screen).
Ncplanes are made up of \f[B]nccell\f[R]s (see NcCells below).
Information on ncplanes is available at \f[B]notcurses_plane(3)\f[R].
.SS NcCells
.PP
\f[B]nccell\f[R]s make up the framebuffers backing each ncplane, one
cell per coordinate, one extended grapheme cluster (see
\f[B]unicode(7)\f[R]) per cell.
An \f[B]nccell\f[R] consists of a gcluster (either a directly-encoded
7-bit ASCII character (see \f[B]ascii(7)\f[R]), or a 25-bit index into
the ncplane\[aq]s egcpool), a set of attributes, and two channels (one
for the foreground, and one for the background\[em]see
\f[B]notcurses_channels(3)\f[R]).
Information on cells is available at \f[B]notcurses_cell(3)\f[R].
.PP
It is not usually necessary for users to interact directly with
\f[B]nccell\f[R]s.
They are typically encountered when retrieving data from ncplanes or the
rendered scene (see e.g.
\f[B]ncplane_at_yx(3)\f[R]), or to achieve peak performance when a
particular EGC is heavily reused within a plane.
.SS Visuals
.PP
Bitmaps can be loaded from disk or memory, or even synthesized from the
content of existing planes.
These are stored in \f[B]ncvisual\f[R] objects, described in
\f[B]notcurses_visual(3)\f[R].
Visuals can be rendered to arbitrarily many planes using a variety of
blitters, varying in their aspect ratios and resolution.
If the terminal supports a pixel protocol such as Sixel or Kitty, it is
possible to render bitmaps at the pixel level (as opposed to the cell
level, using geometric glyphs).
Otherwise, various Unicode-based blitters are available to render
bitmaps in the text paradigm.
.SS Widgets
.PP
A few high-level widgets are included, all built atop ncplanes:
.IP \[bu] 2
\f[B]notcurses_fds(3)\f[R] for dumping file descriptors/subprocesses to
a plane
.IP \[bu] 2
\f[B]notcurses_menu(3)\f[R] for menu bars at the top or bottom of the
screen
.IP \[bu] 2
\f[B]notcurses_multiselector(3)\f[R] for selecting one or more items
from a set
.IP \[bu] 2
\f[B]notcurses_plot(3)\f[R] for drawing histograms and lineplots
.IP \[bu] 2
\f[B]notcurses_progbar(3)\f[R] for drawing progress bars
.IP \[bu] 2
\f[B]notcurses_reader(3)\f[R] for free-form input data
.IP \[bu] 2
\f[B]notcurses_reel(3)\f[R] for hierarchal display of block-based data
.IP \[bu] 2
\f[B]notcurses_tabbed(3)\f[R] for tabbed interfaces
.IP \[bu] 2
\f[B]notcurses_selector(3)\f[R] for selecting one item from a set
.IP \[bu] 2
\f[B]notcurses_tree(3)\f[R] for hierarchal display of line-based data
.SS Threads
.PP
Notcurses explicitly supports use in multithreaded environments, but it
does not itself perform any locking.
.IP \[bu] 2
Only one pile\[aq]s rendered frame can be rasterized at a time, and it
is \f[B]not\f[R] safe to concurrently render that pile.
It is safe to rasterize a frame while rendering some other pile.
.IP \[bu] 2
It is otherwise always safe to operate concurrently on distinct piles.
.IP \[bu] 2
It is not safe to render a pile while concurrently modifying that pile.
.IP \[bu] 2
It is safe to output to multiple distinct ncplanes at the same time,
even within the same pile.
.IP \[bu] 2
It is safe to output to ncplanes while adding or deleting some other
ncplane.
.IP \[bu] 2
It is \f[B]not\f[R] safe for multiple threads to output to the same
ncplane.
.IP \[bu] 2
It is \f[B]not\f[R] safe to add, delete, or reorder ncplanes within a
single pile from multiple threads.
.PP
Only one thread may call \f[B]notcurses_get(3)\f[R] or any other
input-related thread at a time, but it \f[B]is\f[R] safe to call for
input while another thread renders.
.PP
Since multiple threads can concurrently manipulate distinct ncplanes,
peak performance might require dividing the screen into several planes,
and manipulating them from multiple threads.
.SS Destruction
.PP
Before exiting, \f[B]notcurses_stop(3)\f[R] should be called.
In addition to freeing up resources, this is necessary to restore the
terminal to a state useful for the shell.
By default, \f[B]notcurses_init(3)\f[R] installs signal handlers to
catch all signals which would normally terminate the process.
The new handlers will try to call \f[B]notcurses_stop(3)\f[R], and then
propagate the received signal to the previous action.
.SH ENVIRONMENT VARIABLES
.PP
The \f[B]TERM\f[R] environment variable ought be correctly defined.
It will be used to index into the \f[B]terminfo(5)\f[R] database by way
of \f[B]setupterm(3NCURSES)\f[R].
Notcurses will additionally use \f[B]TERM_PROGRAM\f[R] to distinguish
certain terminals.
.PP
If the \f[B]COLORTERM\f[R] environment variable is defined as
\[dq]\f[B]24bit\f[R]\[dq] or \[dq]\f[B]truecolor\f[R]\[dq], Notcurses
will assume the terminal capable of 24-bit RGB color, even in the
absence of \[dq]\f[B]RGB\f[R]\[dq] or \[dq]\f[B]Tc\f[R]\[dq]
capabilities in terminfo.
.PP
If the \f[B]NOTCURSES_LOGLEVEL\f[R] environment variable is defined as a
number between -1 and 8, inclusive, that will override any logging level
specified in the \f[B]struct notcurses_options\f[R] provided to
\f[B]notcurses_init(3)\f[R].
.PP
The \f[B]LOGNAME\f[R] environment variable, if defined, will be used for
\f[B]notcurses_accountname(3)\f[R].
.SH NOTES
.PP
When using the C++ wrappers, \f[B]NCPP_EXCEPTIONS_PLEASE\f[R] can be
defined in order to turn most error returns into exceptions.
.SH SEE ALSO
.PP
\f[B]ncurses(3NCURSES)\f[R], \f[B]notcurses-demo(1)\f[R],
\f[B]notcurses-input(1)\f[R], \f[B]notcurses_capabilities(3)\f[R],
\f[B]notcurses_cell(3)\f[R], \f[B]notcurses_channels(3)\f[R],
\f[B]notcurses_direct(3)\f[R], \f[B]notcurses_fade(3)\f[R],
\f[B]notcurses_fds(3)\f[R], \f[B]notcurses_init(3)\f[R],
\f[B]notcurses_input(3)\f[R], \f[B]notcurses_lines(3)\f[R],
\f[B]notcurses_menu(3)\f[R], \f[B]notcurses_multiselector(3)\f[R],
\f[B]notcurses_output(3)\f[R], \f[B]notcurses_palette(3)\f[R],
\f[B]notcurses_pile(3)\f[R], \f[B]notcurses_plane(3)\f[R],
\f[B]notcurses_plot(3)\f[R], \f[B]notcurses_progbar(3)\f[R],
\f[B]notcurses_reader(3)\f[R], \f[B]notcurses_reel(3)\f[R],
\f[B]notcurses_refresh(3)\f[R], \f[B]notcurses_render(3)\f[R],
\f[B]notcurses_selector(3)\f[R], \f[B]notcurses_stats(3)\f[R],
\f[B]notcurses_stdplane(3)\f[R], \f[B]notcurses_stop(3)\f[R],
\f[B]notcurses_tabbed(3)\f[R], \f[B]notcurses_tree(3)\f[R],
\f[B]notcurses_visual(3)\f[R], \f[B]terminfo(5)\f[R],
\f[B]ascii(7)\f[R], \f[B]utf-8(7)\f[R], \f[B]unicode(7)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.