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_SUPPRESS_BANNERS 0x0020ull
16 #define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
17 #define NCOPTION_NO_FONT_CHANGES 0x0080ull
18 typedef enum {
20 NCLOGLEVEL_SILENT, // default. print nothing once fullscreen service begins
21 NCLOGLEVEL_PANIC, // print diagnostics immediately related to crashing
22 NCLOGLEVEL_FATAL, // we're hanging around, but we've had a horrible fault
23 NCLOGLEVEL_ERROR, // we can't keep doing this, but we can do other things
24 NCLOGLEVEL_WARNING, // you probably don't want what's happening to happen
25 NCLOGLEVEL_INFO, // "standard information"
26 NCLOGLEVEL_VERBOSE, // "detailed information"
27 NCLOGLEVEL_DEBUG, // this is honestly a bit much
28 NCLOGLEVEL_TRACE, // there's probably a better way to do what you want
29 } ncloglevel_e;
30 typedef struct notcurses_options {
32 const char* termtype;
33 FILE* renderfp;
34 ncloglevel_e loglevel;
35 int margin_t, margin_r, margin_b, margin_l;
36 uint64_t flags; // from NCOPTION_* bits
37 } notcurses_options;
38 struct notcurses* notcurses_init(const notcurses_options* opts, FILE*
40 fp);
41 void notcurses_version_components(int* major, int* minor, int* patch,
43 int* tweak);
44 int notcurses_lex_margins(const char* op, notcurses_options* opts);
46 int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
48 int notcurses_cursor_disable(struct notcurses* nc);
50
52 notcurses_init prepares the terminal for cursor-addressable (multiline)
53 mode. The FILE provided as fp must be writable and attached to a ter‐
54 minal, or NULL. If it is NULL, /dev/tty will be opened. The struct
55 notcurses_option passed as opts controls behavior. Only one instance
56 should be associated with a given terminal at a time, though it is no
57 problem to have multiple instances in a given process.
58 On success, a pointer to a valid struct notcurses is returned. NULL is
60 returned on failure. Before the process exits, notcurses_stop(3)
61 should be called to reset the terminal and free up resources.
62 An appropriate terminfo(5) entry must exist for the terminal. This en‐
64 try is usually selected using the value of the TERM environment vari‐
65 able (see getenv(3)), but a non-NULL value for termtype will override
66 this. An invalid terminfo specification can lead to reduced perfor‐
67 mance, reduced display capabilities, and/or display errors. notcurses
68 natively targets 24bpp/8bpc RGB color, and it is thus desirable to use
69 a terminal with the rgb capability (e.g. xterm's xterm-direct).
70 If the terminal advertises support for an "alternate screen" via the
72 smcup terminfo capability, notcurses will employ it by default. This
73 can be prevented by setting NCOPTION_NO_ALTERNATE_SCREEN in flags.
74 Users tend to have strong opinions regarding the alternate screen, so
75 it's often useful to expose this via a command-line option.
76 notcurses hides the cursor by default. It can be dynamically enabled,
78 moved, or disabled during execution via notcurses_cursor_enable(3) and
79 notcurses_cursor_disable(3).
80 notcurses_init typically emits some diagnostics at startup, including
82 version information and some details of the configured terminal. This
83 can be inhibited with NCOPTION_SUPPRESS_BANNERS. This will also inhib‐
84 it the performance summary normally printed by notcurses_stop(3).
85 Notcurses can render to a subregion of the terminal by specifying de‐
87 sired margins on all four sides. By default, all margins are zero, and
88 thus rendering will be performed on the entirety of the viewing area.
89 This is orthogonal to use of the alternate screen; using the alternate
90 screen plus margins will see the full screen cleared, followed by ren‐
91 dering to a subregion. Inhibiting the alternate screen plus margins
92 will see rendering to a subregion, with the screen outside this region
93 not cleared. This is the only means by which existing output can be
94 undisturbed by notcurses. Margins are best-effort. Supplying any neg‐
95 ative margin is an error. notcurses_lex_margins provides lexing a mar‐
96 gin argument expression in one of two forms:
97 • a single number, which will be applied to all sides, or
99 • four comma-delimited numbers, applied to top, right, bottom, and
101 left.
102 To allow future options without requiring redefinition of the struc‐
104 ture, the flags field is only a partially-defined bitfield. Undefined
105 bits should be zero. The following flags are defined:
106 • NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init
108 will call setlocale(LC_ALL, NULL). If the result is either "C" or
109 "POSIX", it will print a diagnostic to stderr, and then call setlo‐
110 cale(LC_ALL, ""). This will attempt to set the locale based off the
111 LANG environment variable. Your program should call setlocale(3) it‐
112 self, usually as one of the first lines.
113 • NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear
115 any preexisting bitmaps. Note that they might still get cleared even
116 if this is set, and they might not get cleared even if this is not
117 set.
118 • NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be in‐
120 stalled for SIGWINCH and SIGCONT, resulting in NCKEY_RESIZE events
121 being generated on input. With this flag, the handler will not be
122 installed.
123 • NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be in‐
125 stalled for SIGINT, SIGILL, SIGQUIT, SIGSEGV, SIGTERM, and SIGABRT,
126 cleaning up the terminal on such exceptions. With this flag, the
127 handler will not be installed.
128 • NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version in‐
130 formation printed on startup, and the performance summary on exit.
131 • NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see
133 terminfo(5)), even if it is available.
134 • NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might
136 otherwise attempt to extend the font, especially in the Linux con‐
137 sole.
138 Fatal signals
140 It is important to reset the terminal before exiting, whether terminat‐
141 ing due to intended operation or a received signal. This is usually
142 accomplished by explicitly calling notcurses_stop(3) during shutdown.
143 For convenience, notcurses by default installs signal handlers for var‐
144 ious signals which would typically result in process termination (see
145 signal(7)). These signal handlers call notcurses_stop(3) for each
146 struct notcurses in the process, and then propagate the signal to any
147 previously-configured handler. These handlers are disabled upon entry
148 to notcurses_stop(3).
149 To prevent signal handler registration, provide NCOP‐
151 TION_NO_QUIT_SIGHANDLERS. No means is provided to selectively register
152 fatal signal handlers. If this is done, the caller ought be sure to
153 effect similar functionality themselves.
154 Resize events
156 SIGWINCH (SIGnal WINdow CHange) is delivered to the process when the
157 terminal is resized. The default action is to ignore it (SIG_IGN).
158 notcurses installs a handler for this signal. The handler causes
159 notcurses to update its idea of the terminal's size using TIOCGWINSZ
160 (see ioctl_tty(2)), and generates an NCKEY_RESIZE input event (see
161 notcurses_input(3). This signal handler can be inhibited by setting
162 NCOPTION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller
163 should probably watch for the signal, and invoke notcurses_refresh(3)
164 or notcurses_render(3) upon its receipt.
165 A resize event does not invalidate any references returned earlier by
167 notcurses. The content of any new screen area is undefined until the
168 next call to notcurses_render(3). This is true even if an existing
169 struct ncplane (see notcurses_plane(3)) overlaps the new area, since
170 the signal could arrive while the ncplanes are being modified. Signal
171 handlers are quite restricted as to what actions they can perform, so
172 minimal work is performed in the handler proper.
173 Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results
175 in:
176 • interruption of some thread to process the signal
178 • a TIOCGWINSZ ioctl to retrieve the new screen size
180 • queuing of a NCKEY_RESIZE input event (if there is space in the
182 queue)
183 Upon the next call to notcurses_render(3) or notcurses_refresh(3), the
185 standard plane (see notcurses_stdplane(3)) will be resized to the new
186 screen size. The next notcurses_render(3) call will function as ex‐
187 pected across the new screen geometry.
188
190 NULL is returned on failure. Otherwise, the return value points at a
191 valid struct notcurses, which can be used until it is provided to
192 notcurses_stop(3).
193
195 getenv(3), setlocale(3), termios(3), notcurses(3), notcurses_input(3),
196 notcurses_plane(3), notcurses_refresh(3), notcurses_render(3), notcurs‐
197 es_stop(3), terminfo(5), signal(7)
198
200 nick black <nickblack@linux.com>.
201 v2.3.1 notcurses_init(3)