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

FreeBSD Manual Pages

  
 
  

home | help
notcurses_reader(3)					   notcurses_reader(3)

NAME
       notcurses_reader	- high level widget for	collecting input

SYNOPSIS
       #include	<notcurses/notcurses.h>

	      struct ncplane;
	      struct ncreader;
	      struct notcurses;

	      #define NCREADER_OPTION_HORSCROLL	0x0001
	      #define NCREADER_OPTION_VERSCROLL	0x0002
	      #define NCREADER_OPTION_NOCMDKEYS	0x0004
	      #define NCREADER_OPTION_CURSOR	0x0008

	      typedef struct ncreader_options {
		uint64_t tchannels; // channels	used for input
		uint32_t tattrword; // attributes used for input
		uint64_t flags;	    // bitfield	over NCREADER_OPTION_*
	      }	ncreader_options;

       struct  ncreader*  ncreader_create(struct  notcurses* nc, const ncread-
       er_options* opts);

       int ncreader_clear(struct ncreader* n);

       struct ncplane* ncreader_plane(struct ncreader* n);

       int ncreader_move_left(struct ncreader* n);

       int ncreader_move_right(struct ncreader*	n);

       int ncreader_move_up(struct ncreader* n);

       int ncreader_move_down(struct ncreader* n);

       int ncreader_write_egc(struct ncreader* n, const	char* egc);

       bool ncreader_offer_input(struct	ncreader* n, const ncinput* ni);

       char* ncreader_contents(const struct ncreader* n);

       void ncreader_destroy(struct ncreader* n, char contents);**

DESCRIPTION
       The ncreader widget supports free-form, multi-line input.  It  supports
       navigation  with	 the arrow keys	and scrolling.	While the visible por-
       tion of the ncreader is always the same size (defined by	 the  provided
       ncplane),  the  actual  text backing this visible region	can grow arbi-
       trarily large if	scrolling is enabled.

       The following option flags are supported:

        NCREADER_OPTION_HORSCROLL: The	visual area will be backed by a	 plane
	 that can grow arbitrarily wide.

        NCREADER_OPTION_VERSCROLL:  The visual	area will be backed by a plane
	 that can grow arbitrarily high.

        NCREADER_OPTION_NOCMDKEYS: The	typical	keyboard shortcuts (see	below)
	 will not be honored.

        NCREADER_OPTION_CURSOR: The terminal's	cursor will  be	 made  visible
	 across	the life of the	ncreader, and its location will	be managed.

       The contents of the ncreader can	be retrieved with ncreader_contents.

       The  ncreader  consists	of  at	least one ncplane (the visible editing
       area).  If the ncreader supports	scrolling, it will consist of two  nc-
       planes,	one of which will be kept outside the rendering	area (and will
       thus be invisible).  ncreader_plane always returns the visible plane.

       ncreader_clear drops all	input from the ncreader, restoring it  to  the
       same pristine condition in which	it was returned	by ncreader_create.

       Unlike  most widgets' input handlers, ncreader_offer_input will consume
       most inputs.  The arrow keys navigate.  Backspace consumes the  EGC  to
       the left	of the cursor, if one exists.  Enter moves to the first	column
       of  the	next  line  (if	 the cursor is already on the bottom line, the
       plane must have scrolling enabled, or  the  cursor  will	 not  advance,
       though  the Enter will still be consumed).  Otherwise, most inputs will
       be reproduced onto the ncreader (though see NOTES below).

       All the ncreader's content is returned from ncreader_contents, preserv-
       ing whitespace.

       "Emacs-style" keyboard shortcuts	similar	to those  supported  by	 read-
       line(3)	and most shells	are supported unless NCREADER_OPTION_NOCMDKEYS
       is provided to ncreader_create.

NOTES
       Support for NCREADER_OPTION_VERSCROLL is	not yet	implemented.

       ncreader	does not buffer	inputs in order	to assemble  EGCs  from	 them.
       If  inputs  are	to  be	processed as EGCs (as they should), the	caller
       would need assemble the grapheme	clusters.  Of course, there is not yet
       any API through which multi-codepoint EGCs could	be supplied to ncread-
       er.

       There is	not yet	any support for	word-wrapping.	This will likely  come
       in the future.

RETURN VALUES
SEE ALSO
       notcurses(3), notcurses_input(3), notcurses_plane(3), readline(3)

AUTHORS
       nick black <nickblack@linux.com>.

				    v3.0.8		   notcurses_reader(3)

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

home | help