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

FreeBSD Manual Pages


home | help
notcurses(3)							  notcurses(3)

       notcurses - TUI library for modern terminal emulators

       #include	<notcurses/notcurses.h>


       Notcurses builds	atop the terminfo(5) abstraction layer to provide rea-
       sonably portable	vivid character	displays.  It is an  intellectual  de-
       scendant	 of  ncurses(3NCURSES),	 but goes beyond that library (and the
       X/Open Curses API thus implemented).

       A program wishing to use	Notcurses will need to link it,	ideally	 using
       the  output  of pkg-config --libs notcurses (see	pkg-config(1)).	 It is
       advised to compile with the output of  pkg-config  --cflags  notcurses.
       If  using  CMake,  a  support  file is provided,	and can	be accessed as
       Notcurses (see cmake(1)).

       notcurses_init(3) can then be used to initialize	a  Notcurses  instance
       for a given FILE	(usually stdout, usually attached to a terminal).

       Before calling into Notcurses--and usually as one of the	first calls of
       the program--be sure to call setlocale with an appropriate UTF-8	LC_ALL
       locale.	 It is usually appropriate to use setlocale(LC_ALL, ""), rely-
       ing on  the  user  to  properly	set  the  LANG	environment  variable.
       Notcurses will refuse to	start if nl_langinfo(3)	doesn't	indicate UTF-8
       or ANSI_X3.4-1968 (aka US-ASCII).  Be aware that	capabilities are  sub-
       stantially reduced in ASCII.

       notcurses_init(3)  accepts  a  struct  notcurses_options	allowing fine-
       grained control of Notcurses behavior, including	signal	handlers,  al-
       ternative  screens,  and	 overriding  the TERM environment variable.  A
       terminfo	entry appropriate for the actual terminal must be available.

       ncdirect_init(3)	makes available	a very restricted subset of  Notcurses
       functionality.	This  subset  is intended to be	interleaved with user-
       generated output, and is	limited	to coloring and	styling.  Direct  mode
       is documented in	notcurses_directmode(3)

       All  output is performed	on struct ncplanes (see	Ncplanes below).  Out-
       put is not visible until	explicitly rendered  via  notcurses_render(3).
       It  is  safe  to	 output	from multiple threads.	Information on drawing
       functions is available at notcurses_output(3).

       Notcurses supports input	from keyboards (via stdin)  and	 pointing  de-
       vices (via a broker such	as GPM,	X, or Wayland).	 Input is delivered as
       32-bit Unicode code points.  Synthesized	events such  as	 mouse	button
       presses	and arrow keys are mapped into Unicode's Supplementary Private
       Use Area-B  (   Information
       on  input  is  available	 at  notcurses_input(3).   The	included  tool
       notcurses-input(1) can be used to test input decoding.

       A given notcurses context is made up of one or more piles.  Piles  pro-
       vide distinct rendering contexts: a thread can be rendering or mutating
       one pile, while another thread concurrently renders or mutates  another
       pile.   A  pile	is made	up of planes, totally ordered on a z-axis.  In
       addition	to the z-ordering, the planes of a pile	are bound in a	forest
       (a  set of directed, acyclic graphs).  Those planes which are not bound
       to some other plane constitute the root planes of a pile.   A  pile  is
       destroyed  when	all its	planes are destroyed, or moved to other	piles.
       Since the standard plane	(see below) always exists, and cannot be moved
       to another pile,	one pile always	exists,	known as the standard pile.

       Following initialization, a single ncplane exists, the "standard	plane"
       (see notcurses_stdplane(3)).  This plane	cannot be destroyed nor	 manu-
       ally  resized,  and  is	always	exactly	as large as the	screen (if run
       without a TTY, the "screen" is assumed to be 80x24 cells).  Further nc-
       planes  can  be created with ncplane_new(3).  A total z-ordering	always
       exists on the set of ncplanes, and new ncplanes are placed at  the  top
       of  the z-buffer.  Ncplanes can be larger, smaller, or the same size as
       the physical screen, and	can be placed anywhere relative	to it (includ-
       ing entirely off-screen).  Ncplanes are made up of nccells (see NcCells
       below).	Information on ncplanes	is available at	notcurses_plane(3).

       nccells make up the framebuffers	backing	each ncplane, one cell per co-
       ordinate,  one extended grapheme	cluster	(see unicode(7)) per cell.  An
       nccell consists of a gcluster (either a	directly-encoded  7-bit	 ASCII
       character  (see	ascii(7)),  or	a  25-bit  index  into	the  ncplane's
       egcpool), a set of attributes, and two  channels	 (one  for  the	 fore-
       ground, and one for the background--see notcurses_channels(3)).	Infor-
       mation on cells is available at notcurses_cell(3).

       It is not usually necessary for users to	 interact  directly  with  nc-
       cells.	They  are  typically encountered when retrieving data from nc-
       planes or the  rendered	scene  (see  e.g.   ncplane_at_yx(3)),	or  to
       achieve peak performance	when a particular EGC is heavily reused	within
       a plane.

       A few high-level	widgets	are included, all built	atop ncplanes:

       o notcurses_fds(3) for dumping file descriptors/subprocesses to a plane

       o notcurses_menu(3) for menu bars at the	top or bottom of the screen

       o notcurses_multiselector(3) for	selecting one or more items from a set

       o notcurses_plot(3) for drawing histograms and lineplots

       o notcurses_progbar(3) for drawing progress bars

       o notcurses_reader(3) for free-form input data

       o notcurses_reel(3) for hierarchal display of data

       o notcurses_selector(3) for selecting one item from a set

       Notcurses explicitly supports use in multithreaded environments,	but it
       does not	itself perform any locking.

       o Only one pile's rendered frame	can be rasterized at a time, and it is
	 not safe to concurrently render that pile.  It	is safe	to rasterize a
	 frame while rendering some other pile.

       o It  is	 otherwise  always  safe  to  operate concurrently on distinct

       o It is not safe	to render a pile  while	 concurrently  modifying  that

       o It  is	safe to	output to multiple distinct ncplanes at	the same time,
	 even within the same pile.

       o It is safe to output to ncplanes while	adding or deleting some	 other

       o It is not safe	for multiple threads to	output to the same ncplane.

       o It  is	 not  safe to add, delete, or reorder ncplanes within a	single
	 pile from multiple threads.

       Only one	thread may call	 notcurses_getc	 or  any  other	 input-related
       thread at a time, but it	is safe	to call	for input while	another	thread

       Since multiple threads can concurrently manipulate  distinct  ncplanes,
       peak performance	might require dividing the screen into several planes,
       and manipulating	them from multiple threads.

       Before exiting, notcurses_stop(3) should	be  called.   In  addition  to
       freeing	up  resources,	this is	necessary to restore the terminal to a
       state useful for	the shell.   By	 default,  notcurses_init(3)  installs
       signal handlers to catch	all signals which would	normally terminate the
       process.	 The new handlers will try to call notcurses_stop(3), and then
       propagate the received signal to	the previous action.

       When  using  the	C++ wrappers, NCPP_EXCEPTIONS_PLEASE can be defined in
       order to	turn most error	returns	into exceptions.

       ncurses(3NCURSES), notcurses-demo(1), notcurses-input(1), notcurses_ca-
       pabilities(3),  notcurses_cell(3), notcurses_channels(3), notcurses_di-
       rectmode(3),  notcurses_fade(3),	 notcurses_fds(3),  notcurses_init(3),
       notcurses_input(3),   notcurses_lines(3),  notcurses_menu(3),  notcurs-
       es_multiselector(3),	notcurses_output(3),	 notcurses_palette(3),
       notcurses_plane(3),  notcurses_plot(3),	notcurses_progbar(3), notcurs-
       es_reader(3), notcurses_reel(3),	 notcurses_refresh(3),	notcurses_ren-
       der(3),	 notcurses_selector(3),	  notcurses_stats(3),	notcurses_std-
       plane(3),    notcurses_stop(3),	  notcurses_visual(3),	  terminfo(5),
       ascii(7), utf-8(7), unicode(7)

       nick black <>.

				    v2.1.4			  notcurses(3)


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

home | help