1notcurses_input(3) notcurses_input(3)
2
6 notcurses_input - input via notcurses
7
9 #include <notcurses/notcurses.h>
10 struct timespec;
12 struct notcurses;
13 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 bool nckey_mouse_p(char32_t r);
25 char32_t notcurses_getc(struct notcurses* n, const struct timespec* ts,
27 const sigset_t* sigmask, ncinput* ni);
28 char32_t notcurses_getc_nblock(struct notcurses* n, ncinput* ni);
30 char32_t notcurses_getc_blocking(struct notcurses* n, ncinput* ni);
32 int notcurses_mouse_enable(struct notcurses* n);
34 int notcurses_mouse_disable(struct notcurses* n);
36 int notcurses_inputready_fd(struct notcurses* n);
38 static inline bool ncinput_equal_p(const ncinput* n1, const ncinput*
40 n2);
41 int notcurses_linesigs_disable(struct notcurses* n);
43 int notcurses_linesigs_enable(struct notcurses* n);
45
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 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 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 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 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 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 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 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 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 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
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 notcurses_mouse_enable returns 0 on success, and non-zero on failure,
128 as does notcurses_mouse_disable.
129 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
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 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 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
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 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 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 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
168 poll(2), notcurses(3), notcurses_refresh(3), notcurses_render(3),
169 termios(3), terminfo(5), ascii(7), signal(7), unicode(7)
170
172 nick black <nickblack@linux.com>.
173 v2.3.1 notcurses_input(3)