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 uint32_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 enum {
22 EVTYPE_UNKNOWN,
23 EVTYPE_PRESS,
24 EVTYPE_REPEAT,
25 EVTYPE_RELEASE,
26 } evtype;
27 int ypx, xpx; // pixel offsets within cell, -1 for undefined
28 } ncinput;
29 #define NCMICE_NO_EVENTS 0
31 #define NCMICE_MOVE_EVENT 0x1
32 #define NCMICE_BUTTON_EVENT 0x2
33 #define NCMICE_DRAG_EVENT 0x4
34 #define NCMICE_ALL_EVENTS 0x7
35 bool nckey_mouse_p(uint32_t r);
37 bool ncinput_nomod_p(const ncinput* ni);
39 uint32_t notcurses_get(struct notcurses* n, const struct timespec* ts,
41 ncinput* ni);
42 int notcurses_getvec(struct notcurses* n, const struct timespec* ts,
44 ncinput* ni, int vcount);
45 uint32_t notcurses_getc_nblock(struct notcurses* n, ncinput* ni);
47 uint32_t notcurses_getc_blocking(struct notcurses* n, ncinput* ni);
49 int notcurses_mice_enable(struct notcurses* n, unsigned eventmask);
51 int notcurses_mice_disable(struct notcurses* n);
53 int notcurses_inputready_fd(struct notcurses* n);
55 static inline bool ncinput_equal_p(const ncinput* n1, const ncinput*
57 n2);
58 int notcurses_linesigs_disable(struct notcurses* n);
60 int notcurses_linesigs_enable(struct notcurses* n);
62
64 notcurses supports input from keyboards and mice, and any device that
65 looks like them. Mouse support requires a broker such as GPM, Wayland,
66 or Xorg, and must be explicitly enabled via notcurses_mouse_enable.
67 The full 32-bit range of Unicode is supported (see unicode(7)), with
68 synthesized events mapped into the Supplementary Private Use Area-B
69 (https://unicode.org/charts/PDF/U1.0.10.pdf). Unicode characters are
70 returned directly as UCS-32, one codepoint at a time.
71 notcurses takes its keyboard input from stdin, which will be placed in‐
73 to non-blocking mode for the duration of operation. The terminal is
74 put into non-canonical mode (see termios(3)), and thus keys are re‐
75 ceived without line-buffering. notcurses maintains its own buffer of
76 input characters, which it will attempt to fill whenever it reads.
77 notcurses_get allows a struct timespec to be specified as a timeout.
79 If ts is NULL, notcurses_get will block until it reads input, or is in‐
80 terrupted by a signal. If its values are zeroes, there will be no
81 blocking. Otherwise, ts specifies an absolute deadline (taken against
82 CLOCK_MONOTONIC; see clock_gettime(2)). On timeout, 0 is returned.
83 Event details will be reported in ni, unless ni is NULL.
84 notcurses_inputready_fd provides a file descriptor suitable for use
86 with I/O multiplexors such as poll(2). This file descriptor might or
87 might not be the actual input file descriptor. If it readable,
88 notcurses_get can be called without the possibility of blocking.
89 ncinput_equal_p compares two ncinput structs for data equality (i.e.
91 not considering padding), returning true if they represent the same in‐
92 put (though not necessarily the same input event).
93 notcurses_linesigs_disable disables conversion of inputs INTR, QUIT,
95 SUSP, and DSUSP into SIGINT, SIGQUIT, and SIGTSTP. These conversions
96 are enabled by default. notcurses_linesigs_enable undoes this action,
97 but signals in the interim are permanently lost.
98 Mice
100 For mouse events, the additional fields y, x, ypx, and xpx are set.
101 These fields are not meaningful for keypress events. Mouse events can
102 be distinguished using the nckey_mouse_p predicate. NCMICE_MOVE_EVENT
103 requests events whenever the mouse moves when no buttons are held down.
104 NCMICE_DRAG_EVENT requests events when the mouse is moving with buttons
105 held down. NCMICE_BUTTON_EVENT requests events then the button state
106 changes. NCMICE_ALL_EVENTS is provided for convenience and future-
107 proofing against API (though not ABI) changes.
108 Synthesized keypresses
110 Many keys do not have a Unicode representation, let alone ASCII. Exam‐
111 ples include the modifier keys (Alt, Meta, etc.), the "function" keys,
112 and the arrow keys on the numeric keypad. The special keys available
113 to the terminal are defined in the terminfo(5) entry, which notcurses
114 loads on startup. Upon receiving an escape code matching a terminfo
115 input capability, notcurses synthesizes a special value. An escape se‐
116 quence must arrive in its entirety to notcurses; running out of input
117 in the middle of an escape sequence will see it rejected. Likewise,
118 any error while handling an escape sequence will see the lex aborted,
119 and the sequence thus far played back as independent literal key‐
120 strokes.
121 The full list of synthesized keys (there are well over one hundred) can
123 be found in <notcurses/notcurses.h>. For more details, consult termin‐
124 fo(5).
125 NCKEY_RESIZE
127 Unless the SIGWINCH handler has been inhibited (see notcurses_init),
128 notcurses will automatically catch screen resizes, and synthesize an
129 NCKEY_RESIZE event. Upon receiving this event, the user may call
130 notcurses_refresh to force an immediate reflow, or just wait until the
131 next call to notcurses_render, when notcurses will pick up the resize
132 itself. If the SIGWINCH handler is inhibited, NCKEY_RESIZE is never
133 generated.
134 NCKEY_EOF
136 Upon reaching the end of input, NCKEY_EOF will be returned. At this
137 point, any further calls will immediately return NCKEY_EOF. Note that
138 this does not necessarily result from pressing e.g. Ctrl+D.
139
141 On error, the get family of functions return (uint32_t)-1. The cause
142 of the error may be determined using errno(3). Unless the error was a
143 temporary one (especially e.g. EINTR), notcurses_get probably cannot
144 be usefully called forthwith. On a timeout, 0 is returned. Otherwise,
145 the UCS-32 value of a Unicode codepoint, or a synthesized event, is re‐
146 turned.
147 If an error is encountered before notcurses_getvec has read any input,
149 it will return -1. If it times out before reading any input, it will
150 return 0. Otherwise, it returns the number of ncinput objects written
151 back.
152 notcurses_mice_enable returns 0 on success, and non-zero on failure, as
154 does notcurses_mice_disable. Success does not necessarily mean that a
155 mouse is available nor that all requested events will be generated.
156 ncinput_equal_p returns true if the two ncinput structs represent the
158 same input (though not necessarily the same input event), and false
159 otherwise.
160
162 Like any other notcurses function, it is an error to call notcurses_get
163 during or after a call to notcurses_stop. If a thread is always sit‐
164 ting on blocking input, it can be tricky to guarantee that this doesn't
165 happen.
166 Only one thread may call into the input stack at once, but unlike al‐
168 most every other function in notcurses, notcurses_get and friends can
169 be called concurrently with notcurses_render.
170 Do not simply poll the file descriptor associated with stdin to test
172 for input readiness. Instead, use the file descriptor returned by
173 notcurses_inputready_fd to ensure compatibility with future versions of
174 Notcurses (it is possible that future versions will process input in
175 their own contexts).
176 When support is detected, the Kitty keyboard disambiguation protocol
178 will be requested. This eliminates most of the BUGS mentioned below.
179
181 The Shift key is not indicated in conjunction with typical Unicode
182 text. If e.g. Shift is used to generate a capital letter 'A', id will
183 equal 'A', and shift will be false. Similarly, when Ctrl is pressed
184 along with a letter, the letter will currently always be reported in
185 its uppercase form. E.g., if Shift, Ctrl, and 'a' are all pressed,
186 this is indistinguishable from Ctrl and 'A'.
187 Ctrl pressed along with 'J' or 'M', whether Shift is pressed or not,
189 currently registers as NCKEY_ENTER. This will likely change in the fu‐
190 ture.
191 When the Kitty keyboard disambiguation protocol is used, most of these
193 issues are resolved. You can determine whether the protocol is in use
194 by examining the output of notcurses-info(1). If the kbd property is
195 indicated, you're using the Kitty protocol.
196 Mouse events in the top and left margins will never be delivered to the
198 application (as is intended), but mouse events in the bottom and right
199 margins sometimes can be if the event occurs prior to a window resize.
200 The ypx and xpx fields are never currently valid (i.e. they are always
202 -1). This ought be fixed in the future using the SGR PixelMode mouse
203 protocol.
204 On some operating systems, CLOCK_REALTIME is used as the basis for
206 timeouts instead of CLOCK_MONOTONIC. This ought be fixed.
207
209 notcurses-info(1), clock_gettime(2), poll(2), notcurses(3), notcurs‐
210 es_refresh(3), notcurses_render(3), termios(3), terminfo(5), ascii(7),
211 signal(7), unicode(7)
212
214 nick black <nickblack@linux.com>.
215 v2.4.9 notcurses_input(3)