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 typedef enum {
22 NCLOGLEVEL_SILENT, // print nothing once fullscreen service begins
23 NCLOGLEVEL_PANIC, // default. print diagnostics before we crash/exit
24 NCLOGLEVEL_FATAL, // we're hanging around, but we've had a horrible fault
25 NCLOGLEVEL_ERROR, // we can't keep doing this, but we can do other things
26 NCLOGLEVEL_WARNING, // you probably don't want what's happening to happen
27 NCLOGLEVEL_INFO, // "standard information"
28 NCLOGLEVEL_VERBOSE, // "detailed information"
29 NCLOGLEVEL_DEBUG, // this is honestly a bit much
30 NCLOGLEVEL_TRACE, // there's probably a better way to do what you want
31 } ncloglevel_e;
32 typedef struct notcurses_options {
34 const char* termtype;
35 ncloglevel_e loglevel;
36 int margin_t, margin_r, margin_b, margin_l;
37 uint64_t flags; // from NCOPTION_* bits
38 } notcurses_options;
39 struct notcurses* notcurses_init(const notcurses_options* opts, FILE*
41 fp);
42 void notcurses_version_components(int* major, int* minor, int* patch,
44 int* tweak);
45 int notcurses_lex_margins(const char* op, notcurses_options* opts);
47 int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
49 int notcurses_cursor_yx(struct notcurses* nc, int* y, int* x);
51 int notcurses_cursor_disable(struct notcurses* nc);
53
55 notcurses_init prepares the terminal for cursor-addressable (multiline)
56 mode. The FILE provided as fp must be writable and attached to a ter‐
57 minal, or NULL. If it is NULL, /dev/tty will be opened. The struct
58 notcurses_option passed as opts controls behavior. A process can have
59 only one Notcurses context active at a time.
60 On success, a pointer to a valid struct notcurses is returned. NULL is
62 returned on failure. Before the process exits, notcurses_stop(3)
63 should be called to reset the terminal and free up resources.
64 An appropriate terminfo(5) entry must exist for the terminal. This en‐
66 try is usually selected using the value of the TERM environment vari‐
67 able (see getenv(3)), but a non-NULL value for termtype will override
68 this. An invalid terminfo specification can lead to reduced perfor‐
69 mance, reduced display capabilities, and/or display errors. notcurses
70 natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
71 a terminal with the rgb capability (e.g. xterm's xterm-direct).
72 If the terminal advertises support for an "alternate screen" via the
74 smcup terminfo capability, notcurses will employ it by default. This
75 can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in flags.
76 Users tend to have strong opinions regarding the alternate screen, so
77 it's often useful to expose this via a command-line option. When the
78 alternate screen is not used, the contents of the terminal at startup
79 remain visible until obliterated, on a cell-by-cell basis (see notcurs‐
80 es_plane(3) for details on clearing the screen at startup without using
81 the alternate screen).
82 notcurses hides the cursor by default. It can be dynamically enabled,
84 moved, or disabled during execution via notcurses_cursor_enable and
85 notcurses_cursor_disable. It will be hidden while updating the screen.
86 The current location of the terminal cursor can be acquired with
87 notcurses_cursor_yx, whether visible or not.
88 notcurses_init typically emits some diagnostics at startup, including
90 version information and some details of the configured terminal. This
91 can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also inhib‐
92 it the performance summary normally printed by notcurses_stop(3).
93 Notcurses can render to a subregion of the terminal by specifying de‐
95 sired margins on all four sides. By default, all margins are zero, and
96 thus rendering will be performed on the entirety of the viewing area.
97 This is orthogonal to use of the alternate screen; using the alternate
98 screen plus margins will see the full screen cleared, followed by ren‐
99 dering to a subregion. Inhibiting the alternate screen plus margins
100 will see rendering to a subregion, with the screen outside this region
101 not cleared. Margins are best-effort. Supplying any negative margin
102 is an error. notcurses_lex_margins provides lexing a margin argument
103 expression in one of two forms:
104 • a single number, which will be applied to all sides, or
106 • four comma-delimited numbers, applied to top, right, bottom, and
108 left.
109 To allow future options without requiring redefinition of the struc‐
111 ture, the flags field is only a partially-defined bitfield. Undefined
112 bits should be zero. The following flags are defined:
113 • NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init
115 will call setlocale(LC_ALL, NULL). If the result is either "C" or
116 "POSIX", it will print a diagnostic to stderr, and then call setlo‐
117 cale(LC_ALL, ""). This will attempt to set the locale based off the
118 LANG environment variable. Your program should call setlocale(3) it‐
119 self, usually as one of the first lines.
120 • NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear
122 any preexisting bitmaps. Note that they might still get cleared even
123 if this is set, and they might not get cleared even if this is not
124 set.
125 • NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be in‐
127 stalled for SIGWINCH and SIGCONT, resulting in NCKEY_RESIZE events
128 being generated on input. With this flag, the handler will not be
129 installed.
130 • NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be in‐
132 stalled for SIGABRT, SIGBUS, SIGFPE, SIGILL, SIGINT, SIGQUIT,
133 SIGSEGV, and SIGTERM, cleaning up the terminal on such exceptions.
134 With this flag, the handler will not be installed.
135 • NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version in‐
137 formation printed on startup, and the performance summary on exit.
138 • NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see
140 terminfo(5)), even if it is available.
141 • NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might
143 otherwise attempt to extend the font, especially in the Linux con‐
144 sole.
145 • NCOPTION_DRAIN_INPUT: Standard input may be freely discarded. If you
147 do not intend to process input, pass this flag. Otherwise, input can
148 buffer up, and eventually prevent Notcurses from processing messages
149 from the terminal. It will furthermore avoid wasting time processing
150 useless input.
151 Fatal signals
153 It is important to reset the terminal before exiting, whether terminat‐
154 ing due to intended operation or a received signal. This is usually
155 accomplished by explicitly calling notcurses_stop(3) during shutdown.
156 For convenience, notcurses by default installs signal handlers for var‐
157 ious signals which would typically result in process termination (see
158 signal(7)). These signal handlers call notcurses_stop(3) for each
159 struct notcurses in the process, and then propagate the signal to any
160 previously-configured handler. These handlers are disabled upon entry
161 to notcurses_stop(3).
162 To prevent signal handler registration, provide NCOP‐
164 TION_NO_QUIT_SIGHANDLERS. No means is provided to selectively register
165 fatal signal handlers. If this is done, the caller ought be sure to
166 effect similar functionality themselves.
167 Resize events
169 SIGWINCH (SIGnal WINdow CHange) is delivered to the process when the
170 terminal is resized. The default action is to ignore it (SIG_IGN).
171 notcurses installs a handler for this signal. The handler causes
172 notcurses to update its idea of the terminal's size using TIOCGWINSZ
173 (see ioctl_tty(2)), and generates an NCKEY_RESIZE input event (see
174 notcurses_input(3). This signal handler can be inhibited by setting
175 NCOPTION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller
176 should probably watch for the signal, and invoke notcurses_refresh(3)
177 or notcurses_render(3) upon its receipt.
178 A resize event does not invalidate any references returned earlier by
180 notcurses. The content of any new screen area is undefined until the
181 next call to notcurses_render(3). This is true even if an existing
182 struct ncplane (see notcurses_plane(3)) overlaps the new area, since
183 the signal could arrive while the ncplanes are being modified. Signal
184 handlers are quite restricted as to what actions they can perform, so
185 minimal work is performed in the handler proper.
186 Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results
188 in:
189 • interruption of some thread to process the signal
191 • a TIOCGWINSZ ioctl to retrieve the new screen size
193 • queuing of a NCKEY_RESIZE input event (if there is space in the
195 queue)
196 Upon the next call to notcurses_render(3) or notcurses_refresh(3), the
198 standard plane (see notcurses_stdplane(3)) will be resized to the new
199 screen size. The next notcurses_render(3) call will function as ex‐
200 pected across the new screen geometry.
201 The hardware cursor
203 Most terminals provide a cursor, a visual indicator of where output
204 will next be placed. There is usually (but not always) some degree of
205 control over what glyph forms this cursor, and whether it e.g. blinks.
206 By default, Notcurses disables this cursor in rendered mode. It can be
208 turned back on with notcurses_enable_cursor, which has immediate effect
209 (there is no need to call notcurses_render(3)). If already visible,
210 this function updates the location. Each time the physical screen is
211 updated, Notcurses will disable the cursor, write the update, move the
212 cursor back to this location, and finally make the cursor visible.
213 notcurses_cursor_yx retrieves the location of the cursor, whether visi‐
214 ble or not. notcurses_disable_cursor hides the cursor.
215 You generally shouldn't need to touch the terminal cursor. It's only
217 really relevant with echoed user input, and you don't want echoed user
218 input in rendered mode (instead, read the input, and write it to a
219 plane yourself). A subprocess can be streamed to a plane with an nc‐
220 subproc, etc.
221 If the NCOPTION_PRESERVE_CURSOR flag is provided, the cursor's location
223 will be determined at startup, and the standard plane's virtual cursor
224 will be placed to match it (instead of in the upper-left corner). Com‐
225 bined with NCOPTION_NO_ALTERNATE_SCREEN and a scrolling standard plane,
226 this allows rendered mode to be used as a normal scrolling shell appli‐
227 cation.
228
230 NULL is returned on failure. Otherwise, the return value points at a
231 valid struct notcurses, which can be used until it is provided to
232 notcurses_stop(3).
233 notcurses_cursor_disable returns -1 if the cursor is already invisible.
235
237 The NOTCURSES_LOGLEVEL environment variable, if defined, ought be an
238 integer between -1 and 7. These values correspond to NCLOGLEVEL_SILENT
239 through NCLOGLEVEL_TRACE, and override the loglevel field of notcurs‐
240 es_options.
241 The TERM environment variable will be used by setupterm(3ncurses) to
243 select an appropriate terminfo database.
244
246 Several command-line options and keybindings are recommended for
247 Notcurses rendered-mode programs:
248 • -l[0-8] ought be mapped to the various NCLOGLEVEL values. Alterna‐
250 tively, map -v to NCLOGLEVEL_WARNING, and map -vv to NCLOGLEVEL_INFO.
251 • -k ought be mapped to NCOPTION_NO_ALTERNATE_SCREEN.
253 • Ctrl+L ought be mapped to notcurses_refresh(3).
255
257 getenv(3), setlocale(3), termios(3), notcurses(3), notcurses_input(3),
258 notcurses_plane(3), notcurses_refresh(3), notcurses_render(3), notcurs‐
259 es_stop(3), setupterm(3ncurses), terminfo(5), signal(7)
260
262 nick black <nickblack@linux.com>.
263 v2.4.9 notcurses_init(3)