From 7c5a13e7ac51b030085d005407b2094b3512ba45 Mon Sep 17 00:00:00 2001 From: nick black Date: Sat, 28 Dec 2019 19:58:05 -0500 Subject: [PATCH] notcurses_init(3) man page #213 --- doc/man/man3/notcurses_init.3.ronn | 86 ++++++++++++++++++++++++++---- include/notcurses.h | 10 ++-- 2 files changed, 81 insertions(+), 15 deletions(-) diff --git a/doc/man/man3/notcurses_init.3.ronn b/doc/man/man3/notcurses_init.3.ronn index 301f5fe80..72e27fd07 100644 --- a/doc/man/man3/notcurses_init.3.ronn +++ b/doc/man/man3/notcurses_init.3.ronn @@ -1,5 +1,5 @@ -notcurses_init(3notcurses) -- initialize a notcurses instance -============================================================= +notcurses_init(3) -- initialize a notcurses instance +==================================================== ## SYNOPSIS @@ -9,10 +9,10 @@ notcurses_init(3notcurses) -- initialize a notcurses instance 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; - bool suppress_banner; - bool clear_screen_start; FILE* renderfp; } notcurses_options; @@ -27,14 +27,80 @@ 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(3notcurses)` should be called to reset the terminal and free -up resources. +`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 will lead to reduced performance, reduced -display capabilities, or display errors. +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`. + +### 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` 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` 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`. + +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` or `notcurses_resize`, the standard +plane (see `notcurses_stdplane(3)`) will be resized to the new screen size. The +next `notcurses_render` call will function as expected across the new screen +geometry. ## RETURN VALUES @@ -47,5 +113,5 @@ Nick Black ## SEE ALSO -getenv(3), termios(3), notcurses(3notcurses), notcurses_stop(3notcurses), -terminfo(5) +getenv(3), termios(3), notcurses(3), notcurses_input(3), notcurses_ncplane(3), +notcurses_render(3), notcurses_stop(3), terminfo(5), signal(7) diff --git a/include/notcurses.h b/include/notcurses.h index 1d7abf2e0..695e55bcc 100644 --- a/include/notcurses.h +++ b/include/notcurses.h @@ -109,6 +109,11 @@ typedef struct notcurses_options { // By default, we hide the cursor if possible. This flag inhibits use of // the civis capability, retaining the cursor. bool retain_cursor; + // Notcurses does not clear the screen on startup unless thus requested to. + bool clear_screen_start; + // Notcurses typically prints version info in notcurses_init() and performance + // info in notcurses_stop(). This inhibits that output. + bool suppress_banner; // We typically install a signal handler for SIG{INT, SEGV, ABRT, QUIT} that // restores the screen, and then calls the old signal handler. Set to inhibit // registration of these signal handlers. @@ -116,11 +121,6 @@ typedef struct notcurses_options { // We typically install a signal handler for SIGWINCH that generates a resize // event in the notcurses_getc() queue. Set to inhibit this handler. bool no_winch_sighandler; - // Notcurses typically prints version info in notcurses_init() and performance - // info in notcurses_stop(). This inhibits that output. - bool suppress_banner; - // Notcurses does not clear the screen on startup unless thus requested to. - bool clear_screen_start; // If non-NULL, notcurses_render() will write each rendered frame to this // FILE* in addition to outfp. This is used primarily for debugging. FILE* renderfp;