Provided by: libnotcurses-core-dev_3.0.7+dfsg.1-1ubuntu8_amd64 
NAME
notcurses_init - initialize a Notcurses instance
SYNOPSIS
#include <notcurses/notcurses.h>
#define NCOPTION_INHIBIT_SETLOCALE 0x0001ull
#define NCOPTION_NO_CLEAR_BITMAPS 0x0002ull
#define NCOPTION_NO_WINCH_SIGHANDLER 0x0004ull
#define NCOPTION_NO_QUIT_SIGHANDLERS 0x0008ull
#define NCOPTION_PRESERVE_CURSOR 0x0010ull
#define NCOPTION_SUPPRESS_BANNERS 0x0020ull
#define NCOPTION_NO_ALTERNATE_SCREEN 0x0040ull
#define NCOPTION_NO_FONT_CHANGES 0x0080ull
#define NCOPTION_DRAIN_INPUT 0x0100ull
#define NCOPTION_SCROLLING 0x0200ull
#define NCOPTION_CLI_MODE (NCOPTION_NO_ALTERNATE_SCREEN \
|NCOPTION_NO_CLEAR_BITMAPS \
|NCOPTION_PRESERVE_CURSOR \
|NCOPTION_SCROLLING)
typedef enum {
NCLOGLEVEL_SILENT, // print nothing once fullscreen service begins
NCLOGLEVEL_PANIC, // default. print diagnostics before we crash/exit
NCLOGLEVEL_FATAL, // we're hanging around, but we've had a horrible fault
NCLOGLEVEL_ERROR, // we can't keep doing this, but we can do other things
NCLOGLEVEL_WARNING, // you probably don't want what's happening to happen
NCLOGLEVEL_INFO, // "standard information"
NCLOGLEVEL_VERBOSE, // "detailed information"
NCLOGLEVEL_DEBUG, // this is honestly a bit much
NCLOGLEVEL_TRACE, // there's probably a better way to do what you want
} ncloglevel_e;
typedef struct notcurses_options {
const char* termtype;
ncloglevel_e loglevel;
unsigned margin_t, margin_r, margin_b, margin_l;
uint64_t flags; // from NCOPTION_* bits
} notcurses_options;
struct notcurses* notcurses_init(const notcurses_options* opts, FILE* fp);
void notcurses_version_components(int* major, int* minor, int* patch, int* tweak);
int notcurses_cursor_enable(struct notcurses* nc, int y, int x);
int notcurses_cursor_disable(struct notcurses* nc);
int notcurses_cursor_yx(const struct notcurses* nc, int* y, int* x);
int notcurses_lex_margins(const char* op, notcurses_options* opts);
int notcurses_default_foreground(const struct notcurses* nc, uint32_t* fg);
int notcurses_default_background(const struct notcurses* nc, uint32_t* bg);
DESCRIPTION
notcurses_init prepares the terminal for cursor-addressable (multiline) mode, writing to
some FILE. If the FILE provided as fp is NULL, stdout will be used. Whatever FILE is
used must be writable, is ideally fully buffered, and must be byte-oriented (see
fwide(3)). If the FILE is not connected to a terminal (for example when redirected to a
file), /dev/tty will be opened (if possible) for communication with the controlling
terminal. Most output (including all styling and coloring) is written to the FILE; only
queries need be sent to a true terminal. If no terminal is available (for example when
running as a daemon), defaults regarding such things as screen size and the palette are
assumed.
The struct notcurses_option passed as opts controls behavior. Passing a NULL opts is
equivalent to passing an all-zero (default) opts. A process can have only one Notcurses
context active at a time; calling notcurses_init again before calling notcurses_stop will
return NULL (this is reliable even if called concurrently from two threads).
On success, a pointer to a valid struct notcurses is returned. NULL is returned on
failure. Before the process exits, notcurses_stop(3) should be called to reset the
terminal and free up resources.
An appropriate terminfo(5) entry must exist for the terminal. This entry is usually
selected using the value of the TERM environment variable (see getenv(3)), but a non-NULL
value for termtype will override this (terminfo is not used on Microsoft Windows, where it
is neither meaningful nor necessary to define TERM). An invalid terminfo specification
can lead to reduced performance, reduced display capabilities, and/or display errors.
Notcurses natively targets 24bpp/8bpc RGB color, and it is thus desirable to use a
terminal with the rgb capability (e.g. xterm's xterm-direct). Colors will otherwise be
quantized down to whatever the terminal supports.
If the terminal advertises support for an "alternate screen" via the smcup terminfo
capability, Notcurses will employ it by default. This can be prevented by setting
NCOPTION_NO_ALTERNATE_SCREEN in flags. Users tend to have strong opinions regarding the
alternate screen, so it's often useful to expose this via a command-line option. When the
alternate screen is not used, the contents of the terminal at startup remain visible until
obliterated, on a cell-by-cell basis (see notcurses_plane(3) for details on clearing the
screen at startup without using the alternate screen). If the alternate screen is not
available, the display will still be cleared without NCOPTION_NO_ALTERNATE_SCREEN.
Notcurses hides the cursor by default. It can be dynamically enabled, moved, or disabled
during execution via notcurses_cursor_enable and notcurses_cursor_disable. It will be
hidden while updating the screen. The current location of the terminal cursor can be
acquired with notcurses_cursor_yx, whether visible or not.
notcurses_init typically emits some diagnostics at startup, including version information
and some details of the configured terminal. This can be inhibited with
NCOPTION_SUPPRESS_BANNERS. This will also inhibit the performance summary normally
printed by notcurses_stop(3).
Notcurses can render to a subregion of the terminal by specifying desired margins on all
four sides. By default, all margins are zero, and thus rendering will be performed on the
entirety of the viewing area. This is orthogonal to use of the alternate screen; using
the alternate screen plus margins will see the full screen cleared, followed by rendering
to a subregion. Inhibiting the alternate screen plus margins will render to a subregion,
with the screen outside this region not cleared. Margins are best-effort.
notcurses_lex_margins provides lexing a margin argument expression in one of two forms:
• a single number, which will be applied to all sides, or
• four comma-delimited numbers, applied to top, right, bottom, and left.
To allow future options without requiring redefinition of the structure, the flags field
is only a partially-defined bitfield. Undefined bits should be zero. The following flags
are defined:
• NCOPTION_INHIBIT_SETLOCALE: Unless this flag is set, notcurses_init will call
setlocale(LC_ALL, NULL). If the result is either "C" or "POSIX", it will print a
diagnostic to stderr, and then call setlocale(LC_ALL, ""). This will attempt to set the
locale based off the LANG environment variable. Your program should call setlocale(3)
itself, usually as one of the first lines.
• NCOPTION_NO_CLEAR_BITMAPS: On entry, make no special attempt to clear any preexisting
bitmaps. Note that they might still get cleared even if this is set, and they might not
get cleared even if this is not set.
• NCOPTION_NO_WINCH_SIGHANDLER: A signal handler will usually be installed for SIGWINCH
and SIGCONT, resulting in NCKEY_RESIZE events being generated on input. With this flag,
the handler will not be installed.
• NCOPTION_NO_QUIT_SIGHANDLERS: A signal handler will usually be installed for SIGABRT,
SIGBUS, SIGFPE, SIGILL, SIGINT, SIGQUIT, SIGSEGV, and SIGTERM, cleaning up the terminal
on such exceptions. With this flag, the handler will not be installed.
• NCOPTION_PRESERVE_CURSOR: The virtual cursor is typically placed at the screen's origin
at startup. With this flag, it is instead placed wherever the cursor was at program
launch.
• NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and version information printed on
startup, and the performance summary on exit.
• NCOPTION_NO_ALTERNATE_SCREEN: Do not use the alternate screen (see terminfo(5)), even if
it is available.
• NCOPTION_NO_FONT_CHANGES: Do not touch the font. Notcurses might otherwise attempt to
extend the font, especially in the Linux console.
• NCOPTION_DRAIN_INPUT: Standard input may be freely discarded. If you do not intend to
process input, pass this flag. Otherwise, input can buffer up, and eventually prevent
Notcurses from processing messages from the terminal. It will furthermore avoid wasting
time processing useless input.
• NCOPTION_SCROLLING: Enable scrolling on the standard plane. This is equivalent to
calling ncplane_set_scrolling(stdn, true) on some standard plane stdn.
NCOPTION_CLI_MODE is provided as an alias for the bitwise OR of NCOPTION_SCROLLING,
NCOPTION_NO_ALTERNATE_SCREEN, NCOPTION_PRESERVE_CURSOR, and NCOPTION_NO_CLEAR_BITMAPS. If
writing a CLI, it is recommended to use NCOPTION_CLI_MODE rather than explicitly listing
these options.
notcurses_default_foreground returns the default foreground color, if it could be
detected. notcurses_default_background returns the default background color, if it could
be detected.
Fatal signals
It is important to reset the terminal before exiting, whether terminating due to intended
operation or a received signal. This is usually accomplished by explicitly calling
notcurses_stop(3) during shutdown. For convenience, Notcurses by default installs signal
handlers for various signals which would typically result in process termination (see
signal(7)). These signal handlers call notcurses_stop(3) for each struct notcurses in the
process, and then propagate the signal to any previously-configured handler. These
handlers are disabled upon entry to notcurses_stop(3).
To prevent signal handler registration, provide NCOPTION_NO_QUIT_SIGHANDLERS. No means is
provided to selectively register fatal signal handlers. If this is done, the caller ought
be sure to effect similar functionality themselves.
Resize events
SIGWINCH (SIGnal WINdow CHange) is delivered to the process when the terminal is resized.
The default action is to ignore it (SIG_IGN). Notcurses installs a handler for this
signal. The handler causes Notcurses to update its idea of the terminal's size using
TIOCGWINSZ (see ioctl_tty(2)), and generates an NCKEY_RESIZE input event (see
notcurses_input(3). This signal handler can be inhibited by setting
NCOPTION_NO_WINCH_SIGHANDLER in flags. If this is done, the caller should probably watch
for the signal, and invoke notcurses_refresh(3) or notcurses_render(3) upon its receipt.
A resize event does not invalidate any references returned earlier by Notcurses. The
content of any new screen area is undefined until the next call to notcurses_render(3).
This is true even if an existing struct ncplane (see notcurses_plane(3)) overlaps the new
area, since the signal could arrive while the ncplanes are being modified. Signal
handlers are quite restricted as to what actions they can perform, so minimal work is
performed in the handler proper.
Thus, in the absence of NCOPTION_NO_WINCH_SIGHANDLER, SIGWINCH results in:
• interruption of some thread to process the signal
• a TIOCGWINSZ ioctl to retrieve the new screen size
• queuing of a NCKEY_RESIZE input event (if there is space in the queue)
Upon the next call to notcurses_render(3) or notcurses_refresh(3), the standard plane (see
notcurses_stdplane(3)) will be resized to the new screen size. The next
notcurses_render(3) call will function as expected across the new screen geometry.
The hardware cursor
Most terminals provide a cursor, a visual indicator of where output will next be placed.
There is usually (but not always) some degree of control over what glyph forms this
cursor, and whether it e.g. blinks.
By default, Notcurses disables this cursor in rendered mode. It can be turned back on
with notcurses_enable_cursor, which has immediate effect (there is no need to call
notcurses_render(3)). If already visible, this function updates the location. Each time
the physical screen is updated, Notcurses will disable the cursor, write the update, move
the cursor back to this location, and finally make the cursor visible.
notcurses_cursor_yx retrieves the location of the cursor, whether visible or not.
notcurses_disable_cursor hides the cursor.
You generally shouldn't need to touch the terminal cursor. It's only really relevant with
echoed user input, and you don't want echoed user input in rendered mode (instead, read
the input, and write it to a plane yourself). A subprocess can be streamed to a plane
with an ncsubproc, etc.
If the NCOPTION_PRESERVE_CURSOR flag is provided, the cursor's location will be determined
at startup, and the standard plane's virtual cursor will be placed to match it (instead of
in the upper-left corner). Combined with NCOPTION_NO_ALTERNATE_SCREEN and a scrolling
standard plane, this allows rendered mode to be used as a normal scrolling shell
application.
RETURN VALUES
NULL is returned on failure. Otherwise, the return value points at a valid struct
notcurses, which can be used until it is provided to notcurses_stop(3).
notcurses_cursor_disable returns -1 if the cursor is already invisible.
notcurses_default_foreground returns -1 if the default foreground color could not be
detected.
notcurses_default_background returns -1 if the default background color could not be
detected.
ENVIRONMENT VARIABLES
The NOTCURSES_LOGLEVEL environment variable, if defined, ought be an integer between -1
and 7. These values correspond to NCLOGLEVEL_SILENT through NCLOGLEVEL_TRACE, and
override the loglevel field of notcurses_options.
The TERM environment variable will be used by setupterm(3ncurses) to select an appropriate
terminfo database.
NOTES
Several command-line options and keybindings are recommended for Notcurses rendered-mode
programs:
• -l[0-8] ought be mapped to the various NCLOGLEVEL values. Alternatively, map -v to
NCLOGLEVEL_WARNING, and map -vv to NCLOGLEVEL_INFO.
• -k ought be mapped to NCOPTION_NO_ALTERNATE_SCREEN.
• Ctrl+L ought be mapped to notcurses_refresh(3).
BUGS
The introductory diagnostics are not currently emitted when the alternate screen is used.
They ought be printed to the regular screen before entering the alternate screen. They
are displayed normally when NCOPTION_NO_ALTERNATE_SCREEN is used.
SEE ALSO
fwide(3), getenv(3), setlocale(3), termios(3), notcurses(3), notcurses_input(3),
notcurses_plane(3), notcurses_refresh(3), notcurses_render(3), notcurses_stop(3),
setupterm(3ncurses), terminfo(5), signal(7)
AUTHORS
nick black <nickblack@linux.com>.
v3.0.7 notcurses_init(3)