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

FreeBSD Manual Pages

  
 
  

home | help
notcurses(3)							  notcurses(3)

NAME
       notcurses - TUI library for modern terminal emulators

SYNOPSIS
       #include	<notcurses/notcurses.h>

       -lnotcurses

DESCRIPTION
       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 it implements).  notcurses is	capable	 of  subregion
       fades, 24bpp TrueColor, transparency, multimedia, and safe multithread-
       ed use.

       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), after calling setlocale(3) to pre-
       pare a UTF-8 locale (see	Construction).

   Construction
       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)

   Output
       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).

   Input
       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  (https://unicode.org/charts/PDF/U100000.pdf).  Information
       on  input  is  available	 at  notcurses_input(3).   The	included  tool
       notcurses-input(1) can be used to test input decoding.

   Ncplanes
       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.  Further
       ncplanes	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 cells	(see Cells be-
       low).  Information on ncplanes is available at notcurses_plane(3).

   Cells
       Cells make up the framebuffers backing each ncplane, one	cell per coor-
       dinate, one extended grapheme cluster (see  unicode(7))	per  cell.   A
       cell  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	cells.
       They are	typically encountered when retrieving data  from  ncplanes  or
       the rendered scene (see e.g. ncplane_at_yx(3)), or to achieve peak per-
       formance	when a particular EGC is heavily reused	within a plane.

   Widgets
       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_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

   Threads
       Notcurses explicitly supports use in multithreaded environments,	but it
       does  not itself	perform	any locking.  It is safe to output to multiple
       distinct	ncplanes at the	same time.  It is safe to output  to  ncplanes
       while adding or deleting	some other ncplane.  It	is not safe for	multi-
       ple threads to output to	the same ncplane.  It  is  not	safe  to  add,
       delete, or reorder ncplanes from	multiple threads, and it is never safe
       to invoke notcurses_render while	any  other  thread  is	touching  that
       notcurses object	(aside from input functions; read on).

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

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

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

SEE ALSO
       ncurses(3NCURSES),  notcurses-demo(1),	notcurses-input(1),   notcurs-
       es_cell(3),  notcurses_channels(3),  notcurses_directmode(3),  notcurs-
       es_error(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_reader(3),  notcurs-
       es_reel(3), notcurses_refresh(3), notcurses_render(3), notcurses_selec-
       tor(3),	notcurses_stats(3),  notcurses_stdplane(3), notcurses_stop(3),
       notcurses_visual(3), terminfo(5), ascii(7), utf-8(7), unicode(7)

AUTHORS
       nick black <nickblack@linux.com>.

				    v1.6.11			  notcurses(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=notcurses&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help