mirror of
https://github.com/dankamongmen/notcurses.git
synced 2024-11-02 09:40:15 +00:00
120 lines
5.3 KiB
Markdown
120 lines
5.3 KiB
Markdown
notcurses_init(3) -- initialize a notcurses instance
|
|
====================================================
|
|
|
|
## SYNOPSIS
|
|
|
|
`#include <notcurses.h>`
|
|
|
|
<pre>typedef struct notcurses_options {
|
|
const char* termtype;
|
|
bool inhibit_alternate_screen;
|
|
bool retain_cursor;
|
|
bool clear_screen_start;
|
|
bool suppress_banner;
|
|
bool no_quit_sighandlers;
|
|
bool no_winch_sighandler;
|
|
FILE* renderfp;
|
|
} notcurses_options;</pre>
|
|
|
|
`struct notcurses*
|
|
notcurses_init(const struct notcurses_options* opts, FILE* fp);`
|
|
|
|
## DESCRIPTION
|
|
|
|
`notcurses_init` prepares the `FILE*` provided as `fp` (which must be attached
|
|
to a terminal) for cursor-addressable (multiline) mode. The `struct
|
|
notcurses_option` passed as `opts` controls behavior. Only one instance should
|
|
be associated with a given terminal at a time, though it is no problem to have
|
|
multiple instances in a given process. 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. 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`).
|
|
|
|
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 `inhibit_alternate_screen` to `true`. Users tend to have strong
|
|
opinions regarding the alternate screen, so it's often useful to expose this
|
|
via a command-line option.
|
|
|
|
notcurses furthermore hides the cursor by default, but `retain_cursor` can
|
|
prevent this (the cursor can be dynamically enabled or disabled during
|
|
execution via notcurses_cursor_enable(3) and notcurses_cursor_disable(3)).
|
|
|
|
If `clear_screen_start` is set to `true`, the screen will be cleared as part of
|
|
`notcurses_init`. Otherwise, whatever's on the screen at entry will remain
|
|
there until changed.
|
|
|
|
`notcurses_init` typically emits some diagnostics at startup, including version
|
|
information and some details of the configured terminal. This can be inhibited
|
|
with `suppress_banner`. This will also inhibit the performance summary normally
|
|
printed by notcurses_stop(3).
|
|
|
|
### 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 typically resulting 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, set `no_quit_sighandlers` to `true`.
|
|
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 `no_winch_sighandler` to `true`. If this is done, the
|
|
caller should probably watch for the signal, and invoke `notcurses_resize()`
|
|
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), unless `clear_screen_start` is set `true`, in which
|
|
case new area is cleared. This is true even if an existing `struct ncplane`
|
|
(see notcurses_ncplane(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 perfomed in
|
|
the handler proper.
|
|
|
|
Thus, in the absence of `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)
|
|
* blanking of the new screen area (if `clear_screen_start` is set)
|
|
|
|
Upon the next call to notcurses_render(3) or notcurses_resize(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.
|
|
|
|
## 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).
|
|
|
|
## AUTHOR
|
|
|
|
Nick Black <nickblack@linux.com>
|
|
|
|
## SEE ALSO
|
|
|
|
getenv(3), termios(3), notcurses(3), notcurses_input(3), notcurses_ncplane(3),
|
|
notcurses_render(3), notcurses_stop(3), terminfo(5), signal(7)
|