1notcurses(3)                                                      notcurses(3)
2
3
4

NAME

6       notcurses - TUI library for modern terminal emulators
7

SYNOPSIS

9       #include   <notcurses/notcurses.h>  or  #include  <notcurses/notcurses-
10       core.h>
11
12       -lnotcurses-core -lnotcurses or -lnotcurses-core
13

DESCRIPTION

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
20       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
28       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
31   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
40       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
45       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
50   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
56   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
65   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
77   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
89   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
98       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
104   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
115   Widgets
116       A few high-level widgets are included, all built atop ncplanes:
117
118notcurses_fds(3) for dumping file descriptors/subprocesses to a plane
119
120notcurses_menu(3) for menu bars at the top or bottom of the screen
121
122notcurses_multiselector(3) for selecting one or more items from a set
123
124notcurses_plot(3) for drawing histograms and lineplots
125
126notcurses_progbar(3) for drawing progress bars
127
128notcurses_reader(3) for free-form input data
129
130notcurses_reel(3) for hierarchal display of block-based data
131
132notcurses_tabbed(3) for tabbed interfaces
133
134notcurses_selector(3) for selecting one item from a set
135
136notcurses_tree(3) for hierarchal display of line-based data
137
138   Threads
139       Notcurses explicitly supports use in multithreaded environments, but it
140       does not itself perform any locking.
141
142       • 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
146       • It is otherwise always  safe  to  operate  concurrently  on  distinct
147         piles.
148
149       • It  is  not  safe  to render a pile while concurrently modifying that
150         pile.
151
152       • It is safe to output to multiple distinct ncplanes at the same  time,
153         even within the same pile.
154
155       • It  is safe to output to ncplanes while adding or deleting some other
156         ncplane.
157
158       • It is not safe for multiple threads to output to the same ncplane.
159
160       • It is not safe to add, delete, or reorder ncplanes  within  a  single
161         pile from multiple threads.
162
163       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
167       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
171   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

NOTES

180       When using the C++ wrappers, NCPP_EXCEPTIONS_PLEASE can be  defined  in
181       order to turn most error returns into exceptions.
182

SEE ALSO

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

AUTHORS

196       nick black <nickblack@linux.com>.
197
198
199
200                                    v2.3.1                        notcurses(3)
Impressum