1notcurses_init(3) notcurses_init(3)
2
6 notcurses_init - initialize a Notcurses instance
7
9 #include <notcurses/notcurses.h>
10 #define NCOPTION_INHIBIT_SETLOCALE 0x0001ull
12 #define NCOPTION_NO_CLEAR_BITMAPS 0x0002ull
13 #define NCOPTION_NO_WINCH_SIGHANDLER 0x0004ull
14 #define NCOPTION_NO_QUIT_SIGHANDLERS 0x0008ull
15 #define NCOPTION_PRESERVE_CURSOR 0x0010ull
16 #define NCOPTION_SUPPRESS_BANNERS 0x0020ull
17 #define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
18 #define NCOPTION_NO_FONT_CHANGES 0x0080ull
19 #define NCOPTION_DRAIN_INPUT 0x0100ull
20 #define NCOPTION_SCROLLING 0x0200ull
21 #define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
23 |NCOPTION_NO_CLEAR_BITMAPS \
24 |NCOPTION_PRESERVE_CURSOR \
25 |NCOPTION_SCROLLING)
26 typedef enum {
28 NCLOGLEVEL_SILENT, // print nothing once fullscreen service begins
29 NCLOGLEVEL_PANIC, // default. print diagnostics before we crash/exit
30 NCLOGLEVEL_FATAL, // we're hanging around, but we've had a horrible fault
31 NCLOGLEVEL_ERROR, // we can't keep doing this, but we can do other things
32 NCLOGLEVEL_WARNING, // you probably don't want what's happening to happen
33 NCLOGLEVEL_INFO, // "standard information"
34 NCLOGLEVEL_VERBOSE, // "detailed information"
35 NCLOGLEVEL_DEBUG, // this is honestly a bit much
36 NCLOGLEVEL_TRACE, // there's probably a better way to do what you want
37 } ncloglevel_e;
38 typedef struct notcurses_options {
40 const char* termtype;
41 ncloglevel_e loglevel;
42 unsigned margin_t, margin_r, margin_b, margin_l;
43 uint64_t flags; // from NCOPTION_* bits
44 } notcurses_options;
45 struct notcurses* notcurses_init(const notcurses_options* opts, FILE*
47 fp);
48 void notcurses_version_components(int* major, int* minor, int* patch,
50 int* tweak);
51 int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
53 int notcurses_cursor_disable(struct notcurses* nc);
55 int notcurses_cursor_yx(const struct notcurses* nc, int* y, int* x);
57 int notcurses_lex_margins(const char* op, notcurses_options* opts);
59 int notcurses_default_foreground(const struct notcurses* nc, uint32_t*
61 fg);
62 int notcurses_default_background(const struct notcurses* nc, uint32_t*
64 bg);
65
67 notcurses_init prepares the terminal for cursor-addressable (multiline)
68 mode, writing to some FILE. If the FILE provided as fp is NULL, stdout
69 will be used. Whatever FILE is used must be writable, is ideally fully
70 buffered, and must be byte-oriented (see fwide(3)). If the FILE is not
71 connected to a terminal (for example when redirected to a file),
72 /dev/tty will be opened (if possible) for communication with the con‐
73 trolling terminal. Most output (including all styling and coloring) is
74 written to the FILE; only queries need be sent to a true terminal. If
75 no terminal is available (for example when running as a daemon), de‐
76 faults regarding such things as screen size and the palette are as‐
77 sumed.
78 The struct notcurses_option passed as opts controls behavior. Passing
80 a NULL opts is equivalent to passing an all-zero (default) opts. A
81 process can have only one Notcurses context active at a time; calling
82 notcurses_init again before calling notcurses_stop will return NULL
83 (this is reliable even if called concurrently from two threads).
84 On success, a pointer to a valid struct notcurses is returned. NULL is
86 returned on failure. Before the process exits, notcurses_stop(3)
87 should be called to reset the terminal and free up resources.
88 An appropriate terminfo(5) entry must exist for the terminal. This en‐
90 try is usually selected using the value of the TERM environment vari‐
91 able (see getenv(3)), but a non-NULL value for termtype will override
92 this (terminfo is not used on Microsoft Windows, where it is neither
93 meaningful nor necessary to define TERM). An invalid terminfo specifi‐
94 cation can lead to reduced performance, reduced display capabilities,
95 and/or display errors. Notcurses natively targets 24bpp/8bpc RGB col‐
96 or, and it is thus desirable to use a terminal with the rgb capability
97 (e.g. xterm's xterm-direct). Colors will otherwise be quantized down
98 to whatever the terminal supports.
99 If the terminal advertises support for an "alternate screen" via the
101 smcup terminfo capability, Notcurses will employ it by default. This
102 can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in flags.
103 Users tend to have strong opinions regarding the alternate screen, so
104 it's often useful to expose this via a command-line option. When the
105 alternate screen is not used, the contents of the terminal at startup
106 remain visible until obliterated, on a cell-by-cell basis (see notcurs‐
107 es_plane(3) for details on clearing the screen at startup without using
108 the alternate screen). If the alternate screen is not available, the
109 display will still be cleared without NCOPTION_NO_ALTERNATE_SCREEN.
110 Notcurses hides the cursor by default. It can be dynamically enabled,
112 moved, or disabled during execution via notcurses_cursor_enable and
113 notcurses_cursor_disable. It will be hidden while updating the screen.
114 The current location of the terminal cursor can be acquired with
115 notcurses_cursor_yx, whether visible or not.
116 notcurses_init typically emits some diagnostics at startup, including
118 version information and some details of the configured terminal. This
119 can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also inhib‐
120 it the performance summary normally printed by notcurses_stop(3).
121 Notcurses can render to a subregion of the terminal by specifying de‐
123 sired margins on all four sides. By default, all margins are zero, and
124 thus rendering will be performed on the entirety of the viewing area.
125 This is orthogonal to use of the alternate screen; using the alternate
126 screen plus margins will see the full screen cleared, followed by ren‐
127 dering to a subregion. Inhibiting the alternate screen plus margins
128 will render to a subregion, with the screen outside this region not
129 cleared. Margins are best-effort. notcurses_lex_margins provides lex‐
130 ing a margin argument expression in one of two forms:
131 • a single number, which will be applied to all sides, or
133 • four comma-delimited numbers, applied to top, right, bottom, and
135 left.
136 To allow future options without requiring redefinition of the struc‐
138 ture, the flags field is only a partially-defined bitfield. Undefined
139 bits should be zero. The following flags are defined:
140 • NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init
142 will call setlocale(LC_ALL, NULL). If the result is either "C" or
143 "POSIX", it will print a diagnostic to stderr, and then call setlo‐
144 cale(LC_ALL, ""). This will attempt to set the locale based off the
145 LANG environment variable. Your program should call setlocale(3) it‐
146 self, usually as one of the first lines.
147 • NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear
149 any preexisting bitmaps. Note that they might still get cleared even
150 if this is set, and they might not get cleared even if this is not
151 set.
152 • NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be in‐
154 stalled for SIGWINCH and SIGCONT, resulting in NCKEY_RESIZE events
155 being generated on input. With this flag, the handler will not be
156 installed.
157 • NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be in‐
159 stalled for SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGINT, SIGQUIT,
160 SIGSEGV, and SIGTERM, cleaning up the terminal on such exceptions.
161 With this flag, the handler will not be installed.
162 • NCOPTION_PRESERVE_CURSOR: The virtual cursor is typically placed at
164 the screen's origin at startup. With this flag, it is instead placed
165 wherever the cursor was at program launch.
166 • NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version in‐
168 formation printed on startup, and the performance summary on exit.
169 • NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see
171 terminfo(5)), even if it is available.
172 • NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might
174 otherwise attempt to extend the font, especially in the Linux con‐
175 sole.
176 • NCOPTION_DRAIN_INPUT: Standard input may be freely discarded. If you
178 do not intend to process input, pass this flag. Otherwise, input can
179 buffer up, and eventually prevent Notcurses from processing messages
180 from the terminal. It will furthermore avoid wasting time processing
181 useless input.
182 • NCOPTION_SCROLLING: Enable scrolling on the standard plane. This is
184 equivalent to calling ncplane_set_scrolling(stdn, true) on some stan‐
185 dard plane stdn.
186 NCOPTION_CLI_MODE is provided as an alias for the bitwise OR of NCOP‐
188 TION_SCROLLING, NCOPTION_NO_ALTERNATE_SCREEN, NCOPTION_PRESERVE_CURSOR,
189 and NCOPTION_NO_CLEAR_BITMAPS. If writing a CLI, it is recommended to
190 use NCOPTION_CLI_MODE rather than explicitly listing these options.
191 notcurses_default_foreground returns the default foreground color, if
193 it could be detected. notcurses_default_background returns the default
194 background color, if it could be detected.
195 Fatal signals
197 It is important to reset the terminal before exiting, whether terminat‐
198 ing due to intended operation or a received signal. This is usually
199 accomplished by explicitly calling notcurses_stop(3) during shutdown.
200 For convenience, Notcurses by default installs signal handlers for var‐
201 ious signals which would typically result in process termination (see
202 signal(7)). These signal handlers call notcurses_stop(3) for each
203 struct notcurses in the process, and then propagate the signal to any
204 previously-configured handler. These handlers are disabled upon entry
205 to notcurses_stop(3).
206 To prevent signal handler registration, provide NCOP‐
208 TION_NO_QUIT_SIGHANDLERS. No means is provided to selectively register
209 fatal signal handlers. If this is done, the caller ought be sure to
210 effect similar functionality themselves.
211 Resize events
213 SIGWINCH (SIGnal WINdow CHange) is delivered to the process when the
214 terminal is resized. The default action is to ignore it (SIG_IGN).
215 Notcurses installs a handler for this signal. The handler causes
216 Notcurses to update its idea of the terminal's size using TIOCGWINSZ
217 (see ioctl_tty(2)), and generates an NCKEY_RESIZE input event (see
218 notcurses_input(3). This signal handler can be inhibited by setting
219 NCOPTION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller
220 should probably watch for the signal, and invoke notcurses_refresh(3)
221 or notcurses_render(3) upon its receipt.
222 A resize event does not invalidate any references returned earlier by
224 Notcurses. The content of any new screen area is undefined until the
225 next call to notcurses_render(3). This is true even if an existing
226 struct ncplane (see notcurses_plane(3)) overlaps the new area, since
227 the signal could arrive while the ncplanes are being modified. Signal
228 handlers are quite restricted as to what actions they can perform, so
229 minimal work is performed in the handler proper.
230 Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results
232 in:
233 • interruption of some thread to process the signal
235 • a TIOCGWINSZ ioctl to retrieve the new screen size
237 • queuing of a NCKEY_RESIZE input event (if there is space in the
239 queue)
240 Upon the next call to notcurses_render(3) or notcurses_refresh(3), the
242 standard plane (see notcurses_stdplane(3)) will be resized to the new
243 screen size. The next notcurses_render(3) call will function as ex‐
244 pected across the new screen geometry.
245 The hardware cursor
247 Most terminals provide a cursor, a visual indicator of where output
248 will next be placed. There is usually (but not always) some degree of
249 control over what glyph forms this cursor, and whether it e.g. blinks.
250 By default, Notcurses disables this cursor in rendered mode. It can be
252 turned back on with notcurses_enable_cursor, which has immediate effect
253 (there is no need to call notcurses_render(3)). If already visible,
254 this function updates the location. Each time the physical screen is
255 updated, Notcurses will disable the cursor, write the update, move the
256 cursor back to this location, and finally make the cursor visible.
257 notcurses_cursor_yx retrieves the location of the cursor, whether visi‐
258 ble or not. notcurses_disable_cursor hides the cursor.
259 You generally shouldn't need to touch the terminal cursor. It's only
261 really relevant with echoed user input, and you don't want echoed user
262 input in rendered mode (instead, read the input, and write it to a
263 plane yourself). A subprocess can be streamed to a plane with an nc‐
264 subproc, etc.
265 If the NCOPTION_PRESERVE_CURSOR flag is provided, the cursor's location
267 will be determined at startup, and the standard plane's virtual cursor
268 will be placed to match it (instead of in the upper-left corner). Com‐
269 bined with NCOPTION_NO_ALTERNATE_SCREEN and a scrolling standard plane,
270 this allows rendered mode to be used as a normal scrolling shell appli‐
271 cation.
272
274 NULL is returned on failure. Otherwise, the return value points at a
275 valid struct notcurses, which can be used until it is provided to
276 notcurses_stop(3).
277 notcurses_cursor_disable returns -1 if the cursor is already invisible.
279 notcurses_default_foreground returns -1 if the default foreground color
281 could not be detected.
282 notcurses_default_background returns -1 if the default background color
284 could not be detected.
285
287 The NOTCURSES_LOGLEVEL environment variable, if defined, ought be an
288 integer between -1 and 7. These values correspond to NCLOGLEVEL_SILENT
289 through NCLOGLEVEL_TRACE, and override the loglevel field of notcurs‐
290 es_options.
291 The TERM environment variable will be used by setupterm(3ncurses) to
293 select an appropriate terminfo database.
294
296 Several command-line options and keybindings are recommended for
297 Notcurses rendered-mode programs:
298 • -l[0-8] ought be mapped to the various NCLOGLEVEL values. Alterna‐
300 tively, map -v to NCLOGLEVEL_WARNING, and map -vv to NCLOGLEVEL_INFO.
301 • -k ought be mapped to NCOPTION_NO_ALTERNATE_SCREEN.
303 • Ctrl+L ought be mapped to notcurses_refresh(3).
305
307 The introductory diagnostics are not currently emitted when the alter‐
308 nate screen is used. They ought be printed to the regular screen be‐
309 fore entering the alternate screen. They are displayed normally when
310 NCOPTION_NO_ALTERNATE_SCREEN is used.
311
313 fwide(3), getenv(3), setlocale(3), termios(3), notcurses(3), notcurs‐
314 es_input(3), notcurses_plane(3), notcurses_refresh(3), notcurses_ren‐
315 der(3), notcurses_stop(3), setupterm(3ncurses), terminfo(5), signal(7)
316
318 nick black <nickblack@linux.com>.
319 v3.0.8 notcurses_init(3)