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 Construction
32 Before calling into Notcurses—and usually as one of the first calls of
33 the program—be sure to call setlocale with an appropriate UTF-8 LC_ALL
34 locale. It is usually appropriate to use setlocale(LC_ALL, ""), rely‐
35 ing on the user to properly set the LANG environment variable.
36 Notcurses will refuse to start if nl_langinfo(3) doesn't indicate UTF-8
37 or ANSI_X3.4-1968 (aka US-ASCII). Be aware that capabilities are sub‐
38 stantially reduced in ASCII.
39 notcurses_init(3) accepts a struct notcurses_options allowing fine-
41 grained control of Notcurses behavior, including signal handlers, al‐
42 ternative screens, and overriding the TERM environment variable. A
43 terminfo entry appropriate for the actual terminal must be available.
44 ncdirect_init(3) makes available a restricted subset of Notcurses func‐
46 tionality. This subset is intended to be interleaved with user-gener‐
47 ated output, and is limited to coloring and styling. Direct mode is
48 documented in notcurses_direct(3).
49 Output
51 All output is performed on struct ncplanes (see Ncplanes below). Out‐
52 put is not visible until explicitly rendered via notcurses_render(3).
53 It is safe to output from multiple threads. Information on drawing
54 functions is available at notcurses_output(3).
55 Input
57 Notcurses supports input from keyboards (via stdin) and pointing de‐
58 vices (via a broker such as GPM, X, or Wayland). Input is delivered as
59 32-bit Unicode code points. Synthesized events such as mouse button
60 presses and arrow keys are mapped into Unicode's Supplementary Private
61 Use Area-B (https://unicode.org/charts/PDF/U100000.pdf). Information
62 on input is available at notcurses_input(3). The included tool
63 notcurses-input(1) can be used to test input decoding.
64 Ncpiles
66 A given notcurses context is made up of one or more piles. Piles pro‐
67 vide distinct rendering contexts: a thread can be rendering or mutating
68 one pile, while another thread concurrently renders or mutates another
69 pile. A pile is made up of planes, totally ordered on a z-axis. In
70 addition to the z-ordering, the planes of a pile are bound in a forest
71 (a set of directed, acyclic graphs). Those planes which are not bound
72 to some other plane constitute the root planes of a pile. A pile is
73 destroyed when all its planes are destroyed, or moved to other piles.
74 Since the standard plane (see below) always exists, and cannot be moved
75 to another pile, one pile always exists, known as the standard pile.
76 Ncplanes
78 Following initialization, a single ncplane exists, the "standard plane"
79 (see notcurses_stdplane(3)). This plane cannot be destroyed nor manu‐
80 ally resized, and is always exactly as large as the screen (if run
81 without a TTY, the "screen" is assumed to be 80x24 cells). Further nc‐
82 planes can be created with ncplane_new(3). A total z-ordering always
83 exists on the set of ncplanes, and new ncplanes are placed at the top
84 of the z-buffer. Ncplanes can be larger, smaller, or the same size as
85 the physical screen, and can be placed anywhere relative to it (includ‐
86 ing entirely off-screen). Ncplanes are made up of nccells (see NcCells
87 below). Information on ncplanes is available at notcurses_plane(3).
88 NcCells
90 nccells make up the framebuffers backing each ncplane, one cell per co‐
91 ordinate, one extended grapheme cluster (see unicode(7)) per cell. An
92 nccell consists of a gcluster (either a directly-encoded 7-bit ASCII
93 character (see ascii(7)), or a 25-bit index into the ncplane's
94 egcpool), a set of attributes, and two channels (one for the fore‐
95 ground, and one for the background—see notcurses_channels(3)). Infor‐
96 mation on cells is available at notcurses_cell(3).
97 It is not usually necessary for users to interact directly with nc‐
99 cells. They are typically encountered when retrieving data from nc‐
100 planes or the rendered scene (see e.g. ncplane_at_yx(3)), or to
101 achieve peak performance when a particular EGC is heavily reused within
102 a plane.
103 Visuals
105 Bitmaps can be loaded from disk or memory, or even synthesized from the
106 content of existing planes. These are stored in ncvisual objects, de‐
107 scribed in notcurses_visual(3). Visuals can be rendered to arbitrarily
108 many planes using a variety of blitters, varying in their aspect ratios
109 and resolution. If the terminal supports a pixel protocol such as Six‐
110 el or Kitty, it is possible to render bitmaps at the pixel level (as
111 opposed to the cell level, using geometric glyphs). Otherwise, various
112 Unicode-based blitters are available to render bitmaps in the text par‐
113 adigm.
114 Widgets
116 A few high-level widgets are included, all built atop ncplanes:
117 • notcurses_fds(3) for dumping file descriptors/subprocesses to a plane
119 • notcurses_menu(3) for menu bars at the top or bottom of the screen
121 • notcurses_multiselector(3) for selecting one or more items from a set
123 • notcurses_plot(3) for drawing histograms and lineplots
125 • notcurses_progbar(3) for drawing progress bars
127 • notcurses_reader(3) for free-form input data
129 • notcurses_reel(3) for hierarchal display of block-based data
131 • notcurses_tabbed(3) for tabbed interfaces
133 • notcurses_selector(3) for selecting one item from a set
135 • notcurses_tree(3) for hierarchal display of line-based data
137 Threads
139 Notcurses explicitly supports use in multithreaded environments, but it
140 does not itself perform any locking.
141 • Only one pile's rendered frame can be rasterized at a time, and it is
143 not safe to concurrently render that pile. It is safe to rasterize a
144 frame while rendering some other pile.
145 • It is otherwise always safe to operate concurrently on distinct
147 piles.
148 • It is not safe to render a pile while concurrently modifying that
150 pile.
151 • It is safe to output to multiple distinct ncplanes at the same time,
153 even within the same pile.
154 • It is safe to output to ncplanes while adding or deleting some other
156 ncplane.
157 • It is not safe for multiple threads to output to the same ncplane.
159 • It is not safe to add, delete, or reorder ncplanes within a single
161 pile from multiple threads.
162 Only one thread may call notcurses_getc or any other input-related
164 thread at a time, but it is safe to call for input while another thread
165 renders.
166 Since multiple threads can concurrently manipulate distinct ncplanes,
168 peak performance might require dividing the screen into several planes,
169 and manipulating them from multiple threads.
170 Destruction
172 Before exiting, notcurses_stop(3) should be called. In addition to
173 freeing up resources, this is necessary to restore the terminal to a
174 state useful for the shell. By default, notcurses_init(3) installs
175 signal handlers to catch all signals which would normally terminate the
176 process. The new handlers will try to call notcurses_stop(3), and then
177 propagate the received signal to the previous action.
178
180 When using the C++ wrappers, NCPP_EXCEPTIONS_PLEASE can be defined in
181 order to turn most error returns into exceptions.
182
184 ncurses(3NCURSES), notcurses-demo(1), notcurses-input(1), notcurses_ca‐
185 pabilities(3), notcurses_cell(3), notcurses_channels(3), notcurses_di‐
186 rect(3), notcurses_fade(3), notcurses_fds(3), notcurses_init(3),
187 notcurses_input(3), notcurses_lines(3), notcurses_menu(3), notcurs‐
188 es_multiselector(3), notcurses_output(3), notcurses_palette(3),
189 notcurses_plane(3), notcurses_plot(3), notcurses_progbar(3), notcurs‐
190 es_reader(3), notcurses_reel(3), notcurses_refresh(3), notcurses_ren‐
191 der(3), notcurses_selector(3), notcurses_stats(3), notcurses_std‐
192 plane(3), notcurses_stop(3), notcurses_tabbed(3), notcurses_tree(3),
193 notcurses_visual(3), terminfo(5), ascii(7), utf-8(7), unicode(7)
194
196 nick black <nickblack@linux.com>.
197 v2.3.1 notcurses(3)