1notcurses_init(3)                                            notcurses_init(3)
2
3
4

NAME

6       notcurses_init - initialize a Notcurses instance
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              #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
22              #define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
23                                         |NCOPTION_NO_CLEAR_BITMAPS \
24                                         |NCOPTION_PRESERVE_CURSOR \
25                                         |NCOPTION_SCROLLING)
26
27              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
39              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
46       struct  notcurses*  notcurses_init(const notcurses_options* opts, FILE*
47       fp);
48
49       void notcurses_version_components(int* major, int* minor,  int*  patch,
50       int* tweak);
51
52       int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
53
54       int notcurses_cursor_disable(struct notcurses* nc);
55
56       int notcurses_cursor_yx(const struct notcurses* nc, int* y, int* x);
57
58       int notcurses_lex_margins(const char* op, notcurses_options* opts);
59
60       int  notcurses_default_foreground(const struct notcurses* nc, uint32_t*
61       fg);
62
63       int notcurses_default_background(const struct notcurses* nc,  uint32_t*
64       bg);
65

DESCRIPTION

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
79       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
85       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
89       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
100       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
111       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
117       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
122       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
132       • a single number, which will be applied to all sides, or
133
134       • four comma-delimited numbers, applied  to  top,  right,  bottom,  and
135         left.
136
137       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
141NCOPTION_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
148NCOPTION_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
153NCOPTION_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
158NCOPTION_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
163NCOPTION_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
167NCOPTION_SUPPRESS_BANNERS:  Disables  the diagnostics and version in‐
168         formation printed on startup, and the performance summary on exit.
169
170NCOPTION_NO_ALTERNATE_SCREEN: Do not use the  alternate  screen  (see
171         terminfo(5)), even if it is available.
172
173NCOPTION_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
177NCOPTION_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
183NCOPTION_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
187       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
192       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
196   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
207       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
212   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
223       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
231       Thus,  in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results
232       in:
233
234       • interruption of some thread to process the signal
235
236       • a TIOCGWINSZ ioctl to retrieve the new screen size
237
238       • queuing of a NCKEY_RESIZE input event  (if  there  is  space  in  the
239         queue)
240
241       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
246   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
251       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
260       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
266       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

RETURN VALUES

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
278       notcurses_cursor_disable returns -1 if the cursor is already invisible.
279
280       notcurses_default_foreground returns -1 if the default foreground color
281       could not be detected.
282
283       notcurses_default_background returns -1 if the default background color
284       could not be detected.
285

ENVIRONMENT VARIABLES

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
292       The  TERM  environment  variable will be used by setupterm(3ncurses) to
293       select an appropriate terminfo database.
294

NOTES

296       Several  command-line  options  and  keybindings  are  recommended  for
297       Notcurses rendered-mode programs:
298
299-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
302-k ought be mapped to NCOPTION_NO_ALTERNATE_SCREEN.
303
304       • Ctrl+L ought be mapped to notcurses_refresh(3).
305

BUGS

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

SEE ALSO

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

AUTHORS

318       nick black <nickblack@linux.com>.
319
320
321
322                                    v3.0.8                   notcurses_init(3)
Impressum