notcurses_init(3) man page #213

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;</pre>
 
@@ -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 <nickblack@linux.com>
 
 ## 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)

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;