Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
notcurses_init(3)					     notcurses_init(3)

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  con-
       trolling	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),  de-
       faults  regarding  such	things	as screen size and the palette are as-
       sumed.

       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 en-
       try  is	usually	selected using the value of the	TERM environment vari-
       able (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 specifi-
       cation can lead to reduced performance, reduced	display	 capabilities,
       and/or  display errors.	Notcurses natively targets 24bpp/8bpc RGB col-
       or, 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 notcurs-
       es_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	inhib-
       it the performance summary normally printed by notcurses_stop(3).

       Notcurses can render to a subregion of the terminal by  specifying  de-
       sired 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 ren-
       dering 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 lex-
       ing 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	struc-
       ture, 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	setlo-
	 cale(LC_ALL, "").  This will attempt to set the locale	based off  the
	 LANG environment variable.  Your program should call setlocale(3) it-
	 self, 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  in-
	 stalled  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 in-
	 stalled  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 in-
	 formation 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  con-
	 sole.

        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 stan-
	 dard plane stdn.

       NCOPTION_CLI_MODE  is  provided as an alias for the bitwise OR of NCOP-
       TION_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 terminat-
       ing 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 var-
       ious 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	 NCOP-
       TION_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  ex-
       pected 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 visi-
       ble 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  nc-
       subproc,	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).  Com-
       bined with NCOPTION_NO_ALTERNATE_SCREEN and a scrolling standard	plane,
       this allows rendered mode to be used as a normal	scrolling shell	appli-
       cation.

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 notcurs-
       es_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.   Alterna-
	 tively, 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	alter-
       nate screen is used.  They ought	be printed to the regular  screen  be-
       fore  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),  notcurs-
       es_input(3),  notcurses_plane(3),  notcurses_refresh(3),	notcurses_ren-
       der(3), notcurses_stop(3), setupterm(3ncurses), terminfo(5), signal(7)

AUTHORS
       nick black <nickblack@linux.com>.

				    v3.0.8		     notcurses_init(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=notcurses_init&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help