1notcurses_reader(3)                                        notcurses_reader(3)
2
3
4

NAME

6       notcurses_reader - high level widget for collecting input
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct ncplane;
12              struct ncreader;
13              struct notcurses;
14
15              #define NCREADER_OPTION_HORSCROLL 0x0001
16              #define NCREADER_OPTION_VERSCROLL 0x0002
17              #define NCREADER_OPTION_NOCMDKEYS 0x0004
18              #define NCREADER_OPTION_CURSOR    0x0008
19
20              typedef struct ncreader_options {
21                uint64_t tchannels; // channels used for input
22                uint32_t tattrword; // attributes used for input
23                uint64_t flags;     // bitfield over NCREADER_OPTION_*
24              } ncreader_options;
25
26       struct  ncreader*  ncreader_create(struct  notcurses* nc, const ncread‐
27       er_options* opts);
28
29       int ncreader_clear(struct ncreader* n);
30
31       struct ncplane* ncreader_plane(struct ncreader* n);
32
33       int ncreader_move_left(struct ncreader* n);
34
35       int ncreader_move_right(struct ncreader* n);
36
37       int ncreader_move_up(struct ncreader* n);
38
39       int ncreader_move_down(struct ncreader* n);
40
41       int ncreader_write_egc(struct ncreader* n, const char* egc);
42
43       bool ncreader_offer_input(struct ncreader* n, const ncinput* ni);
44
45       char* ncreader_contents(const struct ncreader* n);
46
47       void ncreader_destroy(struct ncreader* n, char contents);**
48

DESCRIPTION

50       The ncreader widget supports free-form, multi-line input.  It  supports
51       navigation  with  the arrow keys and scrolling.  While the visible por‐
52       tion of the ncreader is always the same size (defined by  the  provided
53       ncplane),  the  actual  text backing this visible region can grow arbi‐
54       trarily large if scrolling is enabled.
55
56       The following option flags are supported:
57
58NCREADER_OPTION_HORSCROLL: The visual area will be backed by a  plane
59         that can grow arbitrarily wide.
60
61NCREADER_OPTION_VERSCROLL:  The visual area will be backed by a plane
62         that can grow arbitrarily high.
63
64NCREADER_OPTION_NOCMDKEYS: The typical keyboard shortcuts (see below)
65         will not be honored.
66
67NCREADER_OPTION_CURSOR:  The  terminal's  cursor will be made visible
68         across the life of the ncreader, and its location will be managed.
69
70       The contents of the ncreader can be retrieved with ncreader_contents.
71
72       The ncreader consists of at least  one  ncplane  (the  visible  editing
73       area).   If the ncreader supports scrolling, it will consist of two nc‐
74       planes, one of which will be kept outside the rendering area (and  will
75       thus be invisible).  ncreader_plane always returns the visible plane.
76
77       ncreader_clear  drops  all input from the ncreader, restoring it to the
78       same pristine condition in which it was returned by ncreader_create.
79
80       Unlike most widgets' input handlers, ncreader_offer_input will  consume
81       most  inputs.   The arrow keys navigate.  Backspace consumes the EGC to
82       the left of the cursor, if one exists.  Enter moves to the first column
83       of  the  next  line  (if  the cursor is already on the bottom line, the
84       plane must have scrolling enabled, or  the  cursor  will  not  advance,
85       though  the Enter will still be consumed).  Otherwise, most inputs will
86       be reproduced onto the ncreader (though see NOTES below).
87
88       All the ncreader's content is returned from ncreader_contents, preserv‐
89       ing whitespace.
90
91       "Emacs-style"  keyboard  shortcuts  similar to those supported by read‐
92       line(3) and most shells are supported unless  NCREADER_OPTION_NOCMDKEYS
93       is provided to ncreader_create.
94

NOTES

96       Support for NCREADER_OPTION_VERSCROLL is not yet implemented.
97
98       ncreader  does  not  buffer inputs in order to assemble EGCs from them.
99       If inputs are to be processed as EGCs  (as  they  should),  the  caller
100       would need assemble the grapheme clusters.  Of course, there is not yet
101       any API through which multi-codepoint EGCs could be supplied to ncread‐
102       er.
103
104       There  is not yet any support for word-wrapping.  This will likely come
105       in the future.
106

RETURN VALUES

SEE ALSO

109       notcurses(3), notcurses_input(3), notcurses_plane(3), readline(3)
110

AUTHORS

112       nick black <nickblack@linux.com>.
113
114
115
116                                    v2.3.1                 notcurses_reader(3)
Impressum