1notcurses_input(3)                                          notcurses_input(3)
2
3
4

NAME

6       notcurses_input - input via notcurses
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct timespec;
12              struct notcurses;
13
14              typedef struct ncinput {
15                char32_t id;     // Unicode codepoint
16                int y;           // Y cell coordinate of event, -1 for undefined
17                int x;           // X cell coordinate of event, -1 for undefined
18                bool alt;        // Was Alt held during the event?
19                bool shift;      // Was Shift held during the event?
20                bool ctrl;       // Was Ctrl held during the event?
21                uint64_t seqnum; // Monotonically increasing input event counter
22              } ncinput;
23
24       bool nckey_mouse_p(char32_t r);
25
26       char32_t notcurses_getc(struct notcurses* n, const struct timespec* ts,
27       const sigset_t* sigmask, ncinput* ni);
28
29       char32_t notcurses_getc_nblock(struct notcurses* n, ncinput* ni);
30
31       char32_t notcurses_getc_blocking(struct notcurses* n, ncinput* ni);
32
33       int notcurses_mouse_enable(struct notcurses* n);
34
35       int notcurses_mouse_disable(struct notcurses* n);
36
37       int notcurses_inputready_fd(struct notcurses* n);
38
39       static inline bool ncinput_equal_p(const ncinput*  n1,  const  ncinput*
40       n2);
41
42       int notcurses_linesigs_disable(struct notcurses* n);
43
44       int notcurses_linesigs_enable(struct notcurses* n);
45

DESCRIPTION

47       notcurses  supports  input from keyboards and mice, and any device that
48       looks like them.  Mouse support requires a broker such as GPM, Wayland,
49       or  Xorg,  and  must  be explicitly enabled via notcurses_mouse_enable.
50       The full 32-bit range of Unicode is supported  (see  unicode(7)),  with
51       synthesized  events  mapped  into  the Supplementary Private Use Area-B
52       (https://unicode.org/charts/PDF/U1.0.10.pdf).  Unicode  characters  are
53       returned directly as UCS-32, one codepoint at a time.
54
55       notcurses takes its keyboard input from stdin, which will be placed in‐
56       to non-blocking mode for the duration of operation.   The  terminal  is
57       put  into  non-canonical  mode  (see termios(3)), and thus keys are re‐
58       ceived without line-buffering.  notcurses maintains its own  buffer  of
59       input characters, which it will attempt to fill whenever it reads.
60
61       notcurses_getc  allows  a struct timespec to be specified as a timeout.
62       If ts is NULL, notcurses_getc will block until it reads  input,  or  is
63       interrupted  by  a  signal.  If its values are zeroes, there will be no
64       blocking.  Otherwise, ts specifies a minimum time to wait for input be‐
65       fore giving up.  On timeout, 0 is returned.  Signals in sigmask will be
66       masked and blocked in the same manner as a call to  ppoll(2).   sigmask
67       may be NULL.  Event details will be reported in ni, unless ni is NULL.
68
69       notcurses_inputready_fd  provides  a  file  descriptor suitable for use
70       with I/O multiplexors such as poll(2).  This file descriptor  might  or
71       might  not  be  the  actual  input  file  descriptor.   If it readable,
72       notcurses_getc can be called without the possibility of blocking.
73
74       ncinput_equal_p compares two ncinput structs for  data  equality  (i.e.
75       not  considering  padding  or the seqnum field), returning true if they
76       represent the same input (though not necessarily the same input event).
77
78       notcurses_linesigs_disable disables conversion of  inputs  INTR,  QUIT,
79       SUSP,  and  DSUSP into SIGINT, SIGQUIT, and SIGTSTP.  These conversions
80       are enabled by default.  notcurses_linesigs_enable undoes this  action,
81       but signals in the interim are permanently lost.
82
83   Mice
84       For  mouse events, the additional fields y and x are set.  These fields
85       are not meaningful for keypress events.  Mouse events  can  be  distin‐
86       guished  using the nckey_mouse_p predicate.  Once enabled, mouse button
87       presses are detected, as are mouse motions made while a button is  held
88       down.   If  no  button  is depressed, mouse movement does not result in
89       events.  This is known as "button-event tracking" mode in the nomencla‐
90       ture of Xterm Control Sequences (https://www.xfree86.org/current/ctlse
91       qs.html).
92
93   Synthesized keypresses
94       Many keys do not have a Unicode representation, let alone ASCII.  Exam‐
95       ples  include the modifier keys (Alt, Meta, etc.), the "function" keys,
96       and the arrow keys on the numeric keypad.  The special  keys  available
97       to  the  terminal are defined in the terminfo(5) entry, which notcurses
98       loads on startup.  Upon receiving an escape code  matching  a  terminfo
99       input capability, notcurses synthesizes a special value.  An escape se‐
100       quence must arrive in its entirety to notcurses; running out  of  input
101       in  the  middle  of an escape sequence will see it rejected.  Likewise,
102       any error while handling an escape sequence will see the  lex  aborted,
103       and  the  sequence  thus  far  played  back as independent literal key‐
104       strokes.
105
106       The full list of synthesized keys (there are well over one hundred) can
107       be found in <notcurses/notcurses.h>.  For more details, consult termin‐
108       fo(5).
109
110   NCKEY_RESIZE
111       Unless the SIGWINCH handler has been  inhibited  (see  notcurses_init),
112       notcurses  will  automatically  catch screen resizes, and synthesize an
113       NCKEY_RESIZE event.  Upon receiving  this  event,  the  user  may  call
114       notcurses_refresh  to force an immediate reflow, or just wait until the
115       next call to notcurses_render, when notcurses will pick up  the  resize
116       itself.   If  the  SIGWINCH handler is inhibited, NCKEY_RESIZE is never
117       generated.
118

RETURN VALUES

120       On error, the getc family of functions return (char32_t)-1.  The  cause
121       of  the error may be determined using errno(3).  Unless the error was a
122       temporary one (especially e.g.  EINTR), notcurses_getc probably  cannot
123       be usefully called forthwith.  On a timeout, 0 is returned.  Otherwise,
124       the UCS-32 value of a Unicode codepoint, or a synthesized event, is re‐
125       turned.
126
127       notcurses_mouse_enable  returns  0 on success, and non-zero on failure,
128       as does notcurses_mouse_disable.
129
130       ncinput_equal_p returns true if the two ncinput structs  represent  the
131       same  input  (though  not  necessarily the same input event), and false
132       otherwise.
133

NOTES

135       Like any other notcurses function, it is  an  error  to  call  notcurs‐
136       es_getc  during  or after a call to notcurses_stop.  If a thread is al‐
137       ways sitting on blocking input, it can be tricky to guarantee that this
138       doesn't happen.
139
140       Only  one  thread may call into the input stack at once, but unlike al‐
141       most every other function in notcurses, notcurses_getc and friends  can
142       be called concurrently with notcurses_render.
143
144       Do  not  simply  poll the input file descriptor.  Instead, use the file
145       descriptor returned by notcurses_inputready_fd to ensure  compatibility
146       with  future versions of Notcurses (it is possible that future versions
147       will process input in their own contexts).
148

BUGS

150       Failed escape sequences are not yet played back in their entirety; only
151       an ESC (ASCII 0x1b) will be seen by the application.
152
153       The Shift key is only indicated in conjunction with mouse button press‐
154       es.  If e.g.  Shift is used to generate a capital letter 'A',  id  will
155       equal  'A',  and  shift will be false.  This should be fixed in the fu‐
156       ture.
157
158       When Ctrl is pressed along with a letter, the letter will currently al‐
159       ways  be reported in its uppercase form.  E.g., if Shift, Ctrl, and 'a'
160       are all pressed, this is indistinguishable from Ctrl  and  'a'  without
161       Shift.  This should be fixed in the future.
162
163       Ctrl  pressed  along  with 'J' or 'M', whether Shift is pressed or not,
164       currently registers as NCKEY_ENTER.  This will likely change in the fu‐
165       ture.
166

SEE ALSO

168       poll(2),   notcurses(3),   notcurses_refresh(3),   notcurses_render(3),
169       termios(3), terminfo(5), ascii(7), signal(7), unicode(7)
170

AUTHORS

172       nick black <nickblack@linux.com>.
173
174
175
176                                    v2.3.1                  notcurses_input(3)
Impressum