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

FreeBSD Manual Pages


home | help
notcurses_init(3)					     notcurses_init(3)

       notcurses_init -	initialize a notcurses instance

       #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

	      typedef enum {
		NCLOGLEVEL_SILENT,  // default.	print nothing once fullscreen service begins
		NCLOGLEVEL_PANIC,   // print diagnostics immediately related to	crashing
		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;
		FILE* renderfp;
		ncloglevel_e loglevel;
		int 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*

       void notcurses_version_components(int* major, int* minor,  int*	patch,
       int* tweak);

       int notcurses_lex_margins(const char* op, notcurses_options* opts);

       int notcurses_cursor_enable(struct notcurses* nc, int y,	int x);

       int notcurses_cursor_yx(struct notcurses* nc, int* y, int* x);

       int notcurses_cursor_disable(struct notcurses* nc);

       notcurses_init prepares the terminal for	cursor-addressable (multiline)
       mode.  The FILE provided	as fp must be writable and attached to a  ter-
       minal,  or  NULL.   If it is NULL, /dev/tty will	be opened.  The	struct
       notcurses_option	passed as opts controls	behavior.  A process can  have
       only one	Notcurses context active at a time.

       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.  An invalid terminfo specification	can lead  to  reduced  perfor-
       mance,  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	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).

       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 see	rendering to a subregion, with the screen outside this	region
       not  cleared.   Margins are best-effort.	 Supplying any negative	margin
       is an error.  notcurses_lex_margins provides lexing a  margin  argument
       expression in one of two	forms:

       o a single number, which	will be	applied	to all sides, or

       o four  comma-delimited	numbers,  applied  to  top, right, bottom, and

       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:

       o 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.

       o 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

       o 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

       o NCOPTION_NO_QUIT_SIGHANDLERS:	A  signal  handler will	usually	be in-
	 SIGTERM,  cleaning  up	 the  terminal	on such	exceptions.  With this
	 flag, the handler will	not be installed.

       o NCOPTION_SUPPRESS_BANNERS: Disables the diagnostics and  version  in-
	 formation printed on startup, and the performance summary on exit.

       o NCOPTION_NO_ALTERNATE_SCREEN:	Do  not	 use the alternate screen (see
	 terminfo(5)), even if it is available.

       o NCOPTION_NO_FONT_CHANGES: Do not touch	 the  font.   Notcurses	 might
	 otherwise  attempt  to	 extend	the font, especially in	the Linux con-

   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

       o interruption of some thread to	process	the signal

       o a TIOCGWINSZ ioctl to retrieve	the new	screen size

       o queuing of a NCKEY_RESIZE input event	(if  there  is	space  in  the

       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-

       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_cursor_disable	returns	-1 if the cursor is already invisible.

       Several	command-line  options  and  keybindings	 are  recommended  for
       Notcurses rendered-mode programs:

       o -l[0-8]  ought	 be mapped to the various NCLOGLEVEL values.  Alterna-
	 tively, map -v	to NCLOGLEVEL_WARNING, and map -vv to NCLOGLEVEL_INFO.

       o -k ought be mapped to NCOPTION_NO_ALTERNATE_SCREEN.

       o Ctrl+L	ought be mapped	to notcurses_refresh(3).

       getenv(3), setlocale(3),	termios(3), notcurses(3),  notcurses_input(3),
       notcurses_plane(3), notcurses_refresh(3), notcurses_render(3), notcurs-
       es_stop(3), terminfo(5),	signal(7)

       nick black <>.

				    v2.3.11		     notcurses_init(3)


Want to link to this manual page? Use this URL:

home | help