1notcurses(3) notcurses(3)
2
6 notcurses - TUI library for modern terminal emulators
7
9 #include <notcurses/notcurses.h> or #include <notcurses/notcurses-
10 core.h>
11 -lnotcurses-core -lnotcurses or -lnotcurses-core
13
15 Notcurses builds atop the terminfo(5) abstraction layer to provide rea‐
16 sonably portable vivid character displays. It is an intellectual de‐
17 scendant of ncurses(3NCURSES), but goes beyond that library (and the
18 X/Open Curses API it implements).
19 A program wishing to use Notcurses will need to link it, ideally using
21 the output of pkg-config --libs notcurses (see pkg-config(1)). It is
22 advised to compile with the output of pkg-config --cflags notcurses.
23 If using CMake, a support file is provided, and can be accessed as
24 Notcurses (see cmake(1)). If multimedia capabilities are not needed,
25 it is possible to link against a minimal Notcurses using pkg-config
26 --libs notcurses-core.
27 notcurses_init(3) can then be used to initialize a Notcurses instance
29 for a given FILE* (usually stdout, usually attached to a terminal).
30 The alternate screen
32 Many terminals provide an "alternate screen" with its own contents, no
33 scrollback buffer, and no scrolling. Entering the alternate screen re‐
34 places the current visible contents wholesale, as does returning to the
35 regular screen. Notcurses refers to the alternate screen's semantics
36 as "TUI mode", and the regular screen's semantics as "CLI mode". It is
37 possible to swap between the two modes at runtime using notcurs‐
38 es_leave_alternate_screen(3) and notcurses_enter_alternate_screen(3).
39 Notcurses will enter TUI mode by default on startup; to prevent this,
40 use NCOPTION_NO_ALTERNATE_SCREEN as described in notcurses_init(3). On
41 program exit, Notcurses will always return to the regular screen, inde‐
42 pendent of the screen being used on program start.
43 Construction
45 Before calling into Notcurses—and usually as one of the first calls of
46 the program—be sure to call setlocale with an appropriate UTF-8 LC_ALL
47 locale. It is usually appropriate to use setlocale(LC_ALL, ""), rely‐
48 ing on the user to properly set the LANG environment variable.
49 Notcurses will refuse to start if nl_langinfo(3) doesn't indicate UTF-8
50 or ANSI_X3.4-1968 (aka US-ASCII). Be aware that capabilities are sub‐
51 stantially reduced in ASCII.
52 notcurses_init(3) accepts a struct notcurses_options allowing fine-
54 grained control of Notcurses behavior, including signal handlers, al‐
55 ternative screens, and overriding the TERM environment variable. A
56 terminfo entry appropriate for the actual terminal must be available.
57 ncdirect_init(3) makes available a restricted subset of Notcurses func‐
59 tionality. This subset is intended to be interleaved with user-gener‐
60 ated output, and is limited to coloring and styling. Direct mode is
61 documented in notcurses_direct(3).
62 Only one context can be active in a process at a time, whether direct
64 mode (struct ncdirect) or rendered mode (struct notcurses).
65 Output
67 All output is performed on struct ncplanes (see Ncplanes below). Out‐
68 put is not visible until explicitly rendered via notcurses_render(3).
69 Information on drawing functions is available at notcurses_output(3).
70 Input
72 Notcurses supports input from keyboards (via stdin) and pointing de‐
73 vices (via a broker such as GPM, X, or Wayland). Input is delivered as
74 32-bit Unicode code points. Synthesized events such as mouse button
75 presses and arrow keys are mapped into Unicode's Supplementary Private
76 Use Area-B (https://unicode.org/charts/PDF/U100000.pdf). Information
77 on input is available at notcurses_input(3). The included tool
78 notcurses-input(1) can be used to test input decoding.
79 Ncpiles
81 A given notcurses context is made up of one or more piles. Piles pro‐
82 vide distinct rendering contexts: a thread can be rendering or mutating
83 one pile, while another thread concurrently renders or mutates another
84 pile. A pile is made up of planes, totally ordered on a z-axis. In
85 addition to the z-ordering, the planes of a pile are bound in a forest
86 (a set of directed, acyclic graphs). Those planes which are not bound
87 to some other plane constitute the root planes of a pile. A pile is
88 destroyed when all its planes are destroyed, or moved to other piles.
89 Since the standard plane (see below) always exists, and cannot be moved
90 to another pile, one pile always exists, known as the standard pile.
91 Note that rasterizing a pile will replace all content within its mar‐
93 gins.
94 For more information, see notcurses_pile(3).
96 Ncplanes
98 Following initialization, a single ncplane exists, the "standard plane"
99 (see notcurses_stdplane(3)). This plane cannot be destroyed nor manu‐
100 ally resized, and is always exactly as large as the screen (if run
101 without a TTY, the "screen" is assumed to be 80x24 cells). Further nc‐
102 planes can be created with ncplane_create(3). A total z-ordering al‐
103 ways exists on the set of ncplanes, and new ncplanes are placed at the
104 top of the z-buffer. Ncplanes can be larger, smaller, or the same size
105 as the physical screen, and can be placed anywhere relative to it (in‐
106 cluding entirely off-screen). Ncplanes are made up of nccells (see Nc‐
107 Cells below). Information on ncplanes is available at notcurs‐
108 es_plane(3).
109 NcCells
111 nccells make up the framebuffers backing each ncplane, one cell per co‐
112 ordinate, one extended grapheme cluster (see unicode(7)) per cell. An
113 nccell consists of a gcluster (either a directly-encoded 7-bit ASCII
114 character (see ascii(7)), or a 25-bit index into the ncplane's
115 egcpool), a set of attributes, and two channels (one for the fore‐
116 ground, and one for the background—see notcurses_channels(3)). Infor‐
117 mation on cells is available at notcurses_cell(3).
118 It is not usually necessary for users to interact directly with nc‐
120 cells. They are typically encountered when retrieving data from nc‐
121 planes or the rendered scene (see e.g. ncplane_at_yx(3)), or to
122 achieve peak performance when a particular EGC is heavily reused within
123 a plane.
124 Visuals
126 Bitmaps can be loaded from disk or memory, or even synthesized from the
127 content of existing planes. These are stored in ncvisual objects, de‐
128 scribed in notcurses_visual(3). Visuals can be rendered to arbitrarily
129 many planes using a variety of blitters, varying in their aspect ratios
130 and resolution. If the terminal supports a pixel protocol such as Six‐
131 el or Kitty, it is possible to render bitmaps at the pixel level (as
132 opposed to the cell level, using geometric glyphs). Otherwise, various
133 Unicode-based blitters are available to render bitmaps in the text par‐
134 adigm.
135 Widgets
137 A few high-level widgets are included, all built atop ncplanes:
138 • notcurses_fds(3) for dumping file descriptors/subprocesses to a plane
140 • notcurses_menu(3) for menu bars at the top or bottom of the screen
142 • notcurses_multiselector(3) for selecting one or more items from a set
144 • notcurses_plot(3) for drawing histograms and lineplots
146 • notcurses_progbar(3) for drawing progress bars
148 • notcurses_reader(3) for free-form input data
150 • notcurses_reel(3) for hierarchal display of block-based data
152 • notcurses_tabbed(3) for tabbed interfaces
154 • notcurses_selector(3) for selecting one item from a set
156 • notcurses_tree(3) for hierarchal display of line-based data
158 Threads
160 Notcurses explicitly supports use in multithreaded environments, but it
161 does not itself perform any locking.
162 • Only one pile's rendered frame can be rasterized at a time, and it is
164 not safe to concurrently render that pile. It is safe to rasterize a
165 frame while rendering some other pile.
166 • It is otherwise always safe to operate concurrently on distinct
168 piles.
169 • It is not safe to render a pile while concurrently modifying that
171 pile.
172 • It is safe to output to multiple distinct ncplanes at the same time,
174 even within the same pile.
175 • It is safe to output to ncplanes while adding or deleting some other
177 ncplane.
178 • It is not safe for multiple threads to output to the same ncplane.
180 • It is not safe to add, delete, or reorder ncplanes within a single
182 pile from multiple threads.
183 Only one thread may call notcurses_get(3) or any other input-related
185 thread at a time, but it is safe to call for input while another thread
186 renders.
187 Since multiple threads can concurrently manipulate distinct ncplanes,
189 peak performance might require dividing the screen into several planes,
190 and manipulating them from multiple threads.
191 Destruction
193 Before exiting, notcurses_stop(3) should be called. In addition to
194 freeing up resources, this is necessary to restore the terminal to a
195 state useful for the shell. By default, notcurses_init(3) installs
196 signal handlers to catch all signals which would normally terminate the
197 process. The new handlers will try to call notcurses_stop(3), and then
198 propagate the received signal to the previous action.
199
201 The TERM environment variable ought be correctly defined. It will be
202 used to index into the terminfo(5) database by way of setupterm(3NCURS‐
203 ES). Notcurses will additionally use TERM_PROGRAM to distinguish cer‐
204 tain terminals.
205 If the COLORTERM environment variable is defined as "24bit" or "true‐
207 color", Notcurses will assume the terminal capable of 24-bit RGB color,
208 even in the absence of "RGB" or "Tc" capabilities in terminfo.
209 If the NOTCURSES_LOGLEVEL environment variable is defined as a number
211 between -1 and 8, inclusive, that will override any logging level spec‐
212 ified in the struct notcurses_options provided to notcurses_init(3).
213 The LOGNAME environment variable, if defined, will be used for notcurs‐
215 es_accountname(3).
216
218 When using the C++ wrappers, NCPP_EXCEPTIONS_PLEASE can be defined in
219 order to turn most error returns into exceptions.
220
222 ncurses(3NCURSES), notcurses-demo(1), notcurses-input(1), notcurses_ca‐
223 pabilities(3), notcurses_cell(3), notcurses_channels(3), notcurses_di‐
224 rect(3), notcurses_fade(3), notcurses_fds(3), notcurses_init(3),
225 notcurses_input(3), notcurses_lines(3), notcurses_menu(3), notcurs‐
226 es_multiselector(3), notcurses_output(3), notcurses_palette(3),
227 notcurses_pile(3), notcurses_plane(3), notcurses_plot(3), notcurs‐
228 es_progbar(3), notcurses_reader(3), notcurses_reel(3), notcurses_re‐
229 fresh(3), notcurses_render(3), notcurses_selector(3), notcurs‐
230 es_stats(3), notcurses_stdplane(3), notcurses_stop(3), notcurs‐
231 es_tabbed(3), notcurses_tree(3), notcurses_visual(3), terminfo(5),
232 ascii(7), utf-8(7), unicode(7)
233
235 nick black <nickblack@linux.com>.
236 v3.0.8 notcurses(3)