.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_reader" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_reader - high level widget for collecting input
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
struct ncinput;
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;
\f[R]
.fi
.PP
\f[B]struct ncreader* ncreader_create(struct notcurses*
\f[R]\f[I]nc\f[R]\f[B], const ncreader_options*
\f[R]\f[I]opts\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_clear(struct ncreader* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncreader_plane(struct ncreader*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_move_left(struct ncreader*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_move_right(struct ncreader*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_move_up(struct ncreader* \f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_move_down(struct ncreader*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncreader_write_egc(struct ncreader* \f[R]\f[I]n\f[R]\f[B],
const char* \f[R]\f[I]egc\f[R]\f[B]);\f[R]
.PP
\f[B]bool ncreader_offer_input(struct ncreader* \f[R]\f[I]n\f[R]\f[B],
const struct ncinput* \f[R]\f[I]ni\f[R]\f[B]);\f[R]
.PP
\f[B]char* ncreader_contents(const struct ncreader*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]void ncreader_destroy(struct ncreader* \f[R]\f[I]n\f[R]\f[B],
char\f[R] \f[B]\f[BI]contents\f[B]\f[R]);**
.SH DESCRIPTION
.PP
The \f[B]ncreader\f[R] widget supports free-form, multi-line input.
It supports navigation with the arrow keys and scrolling.
While the visible portion of the \f[B]ncreader\f[R] is always the same
size (defined by the provided \f[B]ncplane\f[R]), the actual text
backing this visible region can grow arbitrarily large if scrolling is
enabled.
.PP
The following option flags are supported:
.IP \[bu] 2
\f[B]NCREADER_OPTION_HORSCROLL\f[R]: The visual area will be backed by a
plane that can grow arbitrarily wide.
.IP \[bu] 2
\f[B]NCREADER_OPTION_VERSCROLL\f[R]: The visual area will be backed by a
plane that can grow arbitrarily high.
.IP \[bu] 2
\f[B]NCREADER_OPTION_NOCMDKEYS\f[R]: The typical keyboard shortcuts (see
below) will not be honored.
.IP \[bu] 2
\f[B]NCREADER_OPTION_CURSOR\f[R]: The terminal\[cq]s cursor will be made
visible across the life of the \f[B]ncreader\f[R], and its location will
be managed.
.PP
The contents of the \f[B]ncreader\f[R] can be retrieved with
\f[B]ncreader_contents\f[R].
.PP
The \f[B]ncreader\f[R] consists of at least one \f[B]ncplane\f[R] (the
visible editing area).
If the \f[B]ncreader\f[R] supports scrolling, it will consist of two
\f[B]ncplanes\f[R], one of which will be kept outside the rendering area
(and will thus be invisible).
\f[B]ncreader_plane\f[R] always returns the visible plane.
.PP
\f[B]ncreader_clear\f[R] drops all input from the \f[B]ncreader\f[R],
restoring it to the same pristine condition in which it was returned by
\f[B]ncreader_create\f[R].
.PP
Unlike most widgets\[cq] input handlers, \f[B]ncreader_offer_input\f[R]
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 \f[B]ncreader\f[R]
(though see NOTES below).
.PP
All the \f[B]ncreader\f[R]\[cq]s content is returned from
\f[B]ncreader_contents\f[R], preserving whitespace.
.PP
\[lq]Emacs-style\[rq] keyboard shortcuts similar to those supported by
\f[B]readline(3)\f[R] and most shells are supported unless
\f[B]NCREADER_OPTION_NOCMDKEYS\f[R] is provided to
\f[B]ncreader_create\f[R].
.SH NOTES
.PP
Support for \f[B]NCREADER_OPTION_VERSCROLL\f[R] is not yet implemented.
.PP
\f[B]ncreader\f[R] 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 \f[B]ncreader\f[R].
.PP
There is not yet any support for word-wrapping.
This will likely come in the future.
.SH RETURN VALUES
.SH SEE ALSO
.PP
\f[B]notcurses(3)\f[R], \f[B]notcurses_input(3)\f[R],
\f[B]notcurses_plane(3)\f[R], \f[B]readline(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.