| blob | 8eb76a1f3c18b33be76cc849ad9377caa1ae33a7 |
1 .\" $NetBSD: curses_input.3,v 1.21 2010/08/06 04:03:26 dholland Exp $
2 .\"
3 .\" Copyright (c) 2002
4 .\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au)
5 .\"
6 .\" This code is donated to the NetBSD Foundation by the Author.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. The name of the Author may not be used to endorse or promote
17 .\" products derived from this software without specific prior written
18 .\" permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\"
33 .Dd July 25, 2006
34 .Dt CURSES_INPUT 3
35 .Os
36 .Sh NAME
37 .Nm curses_input ,
38 .Nm getch ,
39 .Nm wgetch ,
40 .Nm mvgetch ,
41 .Nm mvwgetch ,
42 .Nm define_key ,
43 .Nm keyok ,
44 .Nm getnstr ,
45 .Nm wgetnstr ,
46 .Nm mvgetnstr ,
47 .Nm mvwgetnstr ,
48 .Nm getstr ,
49 .Nm wgetstr ,
50 .Nm mvgetstr ,
51 .Nm mvwgetstr ,
52 .Nm keypad ,
53 .Nm notimeout ,
54 .Nm timeout ,
55 .Nm wtimeout ,
56 .Nm nodelay ,
57 .Nm ungetch
58 .Nd curses input stream routines
59 .Sh LIBRARY
60 .Lb libcurses
61 .Sh SYNOPSIS
62 .In curses.h
63 .Ft int
64 .Fn getch "void"
65 .Ft int
66 .Fn wgetch "WINDOW *win"
67 .Ft int
68 .Fn mvgetch "int y" "int x"
69 .Ft int
70 .Fn mvwgetch "WINDOW *win" "int y" "int x"
71 .Ft int
72 .Fn keyok "int key_symbol" "bool flag"
73 .Ft int
74 .Fn define_key "char *sequence" "int key_symbol"
75 .Ft int
76 .Fn getnstr "char *str" "int limit"
77 .Ft int
78 .Fn wgetnstr "WINDOW *win" "char *str" "int limit"
79 .Ft int
80 .Fn mvgetnstr "int y" "int x" "char *str" "int limit"
81 .Ft int
82 .Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit"
83 .Ft int
84 .Fn getstr "char *str"
85 .Ft int
86 .Fn wgetstr "WINDOW *win" "char *str"
87 .Ft int
88 .Fn mvgetstr "int y" "int x" "char *str"
89 .Ft int
90 .Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str"
91 .Ft int
92 .Fn keypad "WINDOW *win" "boolf flag"
93 .Ft int
94 .Fn notimeout "WINDOW *win" "boolf flag"
95 .Ft int
96 .Fn timeout "int delay"
97 .Ft int
98 .Fn wtimeout "WINDOW *win" "int delay"
99 .Ft int
100 .Fn nodelay "WINDOW *win" "boolf flag"
101 .Ft int
102 .Fn ungetch "int c"
103 .Pp
104 .Va extern int ESCDELAY ;
105 .Sh DESCRIPTION
106 These functions read characters and strings from the window input file
107 descriptor.
108 .Pp
109 The
110 .Fn getch
111 function reads a character from the
112 .Dv stdscr
113 input file descriptor and returns it.
114 If the
115 .Fn keypad
116 flag has been set to
117 .Dv TRUE ,
118 then
119 .Fn getch
120 will assemble multi-character key sequences into key symbols,
121 If the terminal is resized,
122 .Fn getch
123 will return
124 .Dv KEY_RESIZE ,
125 regardless of the setting of
126 .Fn keypad .
127 Calling
128 .Fn getch
129 will cause an implicit
130 .Fn refresh
131 on
132 .Dv stdscr .
133 .Pp
134 The
135 .Fn wgetch
136 function is the same as the
137 .Fn getch
138 function, excepting that it reads from the input file descriptor associated
139 with the window specified by
140 .Fa win .
141 .Pp
142 If the
143 .Fn keypad
144 flag is
145 .Dv TRUE
146 then the assembly of specific key symbols can be disabled by using the
147 .Fn keyok
148 function.
149 If the
150 .Fa flag
151 is set to
152 .Dv FALSE
153 on a key symbol then
154 .Fn getch
155 will behave as if the character sequence associated with that key symbol
156 was not recognised and will return the component characters one at a time to
157 the caller.
158 .Pp
159 Custom associations between sequences of characters and a key symbol can
160 be made by using the
161 .Fn define_key
162 function.
163 Normally, these associations are made by the information in the
164 .Xr termcap 5
165 database but the
166 .Fn define_key
167 function gives the capability to remove or add more associations.
168 If
169 .Fn define_key
170 is passed a non-NULL string in
171 .Fa sequence
172 it will associate that sequence with the key symbol passed in
173 .Fa key_symbol .
174 The key symbol may be one of the ones listed below or a custom value that
175 is application defined.
176 It is valid to have multiple character sequences map to the same key
177 symbol and there are no constraints on the length of the sequence allowed.
178 The assembly of custom sequences follow the same rules for inter-character
179 timing and so forth as the
180 .Xr termcap 5
181 derived ones.
182 If
183 .Fn define_key
184 is passed a NULL in
185 .Fa sequence
186 then all associations for the key symbol in
187 .Fa key_symbol
188 will be deleted, this includes any associations that were derived from
189 .Xr termcap 5 .
190 .Pp
191 The
192 .Fn mvgetch
193 and
194 .Fn mvwgetch
195 functions are the same as the
196 .Fn getch
197 and
198 .Fn wgetch
199 functions, respectively, excepting that
200 .Fn wmove
201 is called to move the cursor to the position specified by
202 .Fa y ,
203 .Fa x
204 before the character is read.
205 .Pp
206 Calling
207 .Fn getnstr ,
208 .Fn wgetnstr ,
209 .Fn mvgetnstr
210 or
211 .Fn mvwgetnstr
212 is effectively the same as calling
213 .Fn getch
214 repeatedly until a newline is received or the character limit
215 .Fa limit
216 is reached.
217 Once this happens the string is
218 .Dv NULL
219 terminated and returned in
220 .Fa str .
221 During input, the normal curses input key processing is performed and
222 affects the input buffer.
223 The
224 .Fn mvgetnstr
225 function calls
226 .Fn wmove
227 to move the cursor to the position given by
228 .Fa y ,
229 .Fa x
230 before getting the string,
231 .Fn wgetnstr
232 reads the input from the designated window,
233 .Fn mvwgetnstr
234 moves the cursor to the position given by
235 .Fa y ,
236 .Fa x
237 before getting the input from the designated window.
238 .Pp
239 The functions
240 .Fn getstr ,
241 .Fn wgetstr ,
242 .Fn mvgetstr ,
243 and
244 .Fn mvwgetstr
245 are similar to
246 .Fn getnstr ,
247 .Fn wgetnstr ,
248 .Fn mvgetnstr ,
249 and
250 .Fn mvwgetnstr ,
251 respectively, excepting that there is no limit on the number of characters
252 that may be inserted into
253 .Fa str .
254 This may cause the buffer to be overflowed, so their use is not recommended.
255 .Pp
256 The
257 .Fn keypad
258 function is used to affect how
259 .Fn getch
260 processes input characters.
261 If
262 .Fa flag
263 is set to
264 .Dv TRUE ,
265 then
266 .Fn getch
267 will scan the input stream looking for multi-character key sequences
268 that are emitted by some terminal function keys.
269 If a recognised sequence of characters is found, then
270 .Fn getch
271 will collapse that sequence into an integer key symbol, as shown below.
272 The default setting for the flag is
273 .Dv FALSE .
274 .Pp
275 The
276 .Fn notimeout
277 function controls whether or not
278 .Fn getch
279 will wait indefinitely between characters in a multi-character key
280 sequence or not.
281 If
282 .Fa flag
283 is
284 .Dv TRUE ,
285 then there is no timeout applied between characters comprising a
286 multi-character key sequence.
287 If
288 .Fa flag
289 is
290 .Dv FALSE ,
291 then the component characters of a multi-character sequence must not
292 have an inter-character gap of more than
293 .Va ESCDELAY .
294 If this timing is exceeded, then the multi-character key assembly is
295 deemed to have failed and the characters read thus far are returned
296 one at a time when
297 .Fn getch
298 is called.
299 The default setting for the flag is
300 .Dv FALSE .
301 The default value of
302 .Va ESCDELAY
303 is 300ms.
304 If
305 .Va ESCDELAY
306 is negative, no timeout is applied between characters comprising a
307 multi-character key sequence.
308 .Pp
309 The
310 .Fn timeout
311 function affects the behaviour of
312 .Fn getch
313 when reading a character from
314 .Dv stdscr .
315 If
316 .Fa delay
317 is negative, then
318 .Fn getch
319 will block indefinitely on a read.
320 If
321 .Fa delay
322 is 0, then
323 .Fn getch
324 will return immediately with
325 .Dv ERR
326 if there are no characters immediately available.
327 If
328 .Fa delay
329 is a positive number, then
330 .Fn getch
331 will wait for that many milliseconds before returning and, if no character
332 was available, then
333 .Dv ERR
334 will be returned.
335 Note that for a positive number, the timeout is only accurate to the nearest
336 tenth of a second.
337 Also, the maximum value of
338 .Fa delay
339 is 25500 milliseconds.
340 The
341 .Fn wtimeout
342 function does the same as
343 .Fn timeout
344 but applies to the specified window
345 .Fa win .
346 .Pp
347 The
348 .Fn nodelay
349 function turns on and off blocking reads for
350 .Fn getch .
351 If
352 .Fa flag
353 is
354 .Dv TRUE ,
355 then
356 .Fn getch
357 will not block on reads, if
358 .Fa flag
359 is
360 .Dv FALSE ,
361 then reads will block.
362 The default setting for the flag is
363 .Dv FALSE .
364 .Fn nodelay win TRUE
365 is equivalent to
366 .Fn wtimeout win 0
367 and
368 .Fn nodelay win FALSE
369 is equivalent to
370 .Fn wtimeout win \-1 .
371 .Pp
372 .Fn ungetch
373 will convert
374 .Fa c
375 into an unsigned char and push that character back onto the input stream.
376 Only one character of push-back is guaranteed to work, more may be possible
377 depending on system resources.
378 .Sh RETURN VALUES
379 The functions
380 .Fn getch ,
381 .Fn wgetch ,
382 .Fn mvgetch ,
383 and
384 .Fn mvwgetch
385 will return the value of the key pressed or
386 .Dv ERR
387 in the case of an error or a timeout.
388 Additionally, if
389 .Fn keypad TRUE
390 has been called on a window, then it may return one of the following values:
391 .Pp
392 .Bl -column "Termcap entry" "getch Return Value" "Key Function" -offset indent
393 .It Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function"
394 .It \&!1 Ta KEY_SSAVE Ta Shift Save
395 .It \&!2 Ta KEY_SSUSPEND Ta Shift Suspend
396 .It \&!3 Ta KEY_SUNDO Ta Shift Undo
397 .It \ Ta KEY_SHELP Ta Shift Help
398 .It \ Ta KEY_SHOME Ta Shift Home
399 .It \ Ta KEY_SIC Ta Shift Insert Character
400 .It \ Ta KEY_SLEFT Ta Shift Left Arrow
401 .It \&%0 Ta KEY_REDO Ta Redo
402 .It \&%1 Ta KEY_HELP Ta Help
403 .It \&%2 Ta KEY_MARK Ta Mark
404 .It \&%3 Ta KEY_MESSAGE Ta Message
405 .It \&%4 Ta KEY_MOVE Ta Move
406 .It \&%5 Ta KEY_NEXT Ta Next Object
407 .It \&%6 Ta KEY_OPEN Ta Open
408 .It \&%7 Ta KEY_OPTIONS Ta Options
409 .It \&%8 Ta KEY_PREVIOUS Ta Previous Object
410 .It \&%9 Ta KEY_PRINT Ta Print
411 .It \&%a Ta KEY_SMESSAGE Ta Shift Message
412 .It \&%b Ta KEY_SMOVE Ta Shift Move
413 .It \&%c Ta KEY_SNEXT Ta Shift Next Object
414 .It \&%d Ta KEY_SOPTIONS Ta Shift Options
415 .It \&%e Ta KEY_SPREVIOUS Ta Shift Previous Object
416 .It \&%f Ta KEY_SPRINT Ta Shift Print
417 .It \&%g Ta KEY_SREDO Ta Shift Redo
418 .It \&%h Ta KEY_SREPLACE Ta Shift Replace
419 .It \&%i Ta KEY_SRIGHT Ta Shift Right Arrow
420 .It \&%j Ta KEY_SRSUME Ta Shift Resume
421 .It \&\*[Am]0 Ta KEY_SCANCEL Ta Shift Cancel
422 .It \&\*[Am]1 Ta KEY_REFERENCE Ta Reference
423 .It \&\*[Am]2 Ta KEY_REFRESH Ta Refresh
424 .It \&\*[Am]3 Ta KEY_REPLACE Ta Replace
425 .It \&\*[Am]4 Ta KEY_RESTART Ta Restart
426 .It \&\*[Am]5 Ta KEY_RESUME Ta Resume
427 .It \&\*[Am]6 Ta KEY_SAVE Ta Save
428 .It \&\*[Am]7 Ta KEY_SUSPEND Ta Suspend
429 .It \&\*[Am]8 Ta KEY_UNDO Ta Undo
430 .It \&\*[Am]9 Ta KEY_SBEG Ta Shift Begin
431 .It \&*0 Ta KEY_SFIND Ta Shift Find
432 .It \&*1 Ta KEY_SCOMMAND Ta Shift Command
433 .It \&*2 Ta KEY_SCOPY Ta Shift Copy
434 .It \&*3 Ta KEY_SCREATE Ta Shift Create
435 .It \&*4 Ta KEY_SDC Ta Shift Delete Character
436 .It \&*5 Ta KEY_SDL Ta Shift Delete Line
437 .It \&*6 Ta KEY_SELECT Ta Select
438 .It \&*7 Ta KEY_SEND Ta Shift End
439 .It \&*8 Ta KEY_SEOL Ta Shift Clear to EOL
440 .It \&*9 Ta KEY_SEXIT Ta Shift Exit
441 .It \&@0 Ta KEY_FIND Ta Find
442 .It \&@1 Ta KEY_BEG Ta Begin
443 .It \&@2 Ta KEY_CANCEL Ta Cancel
444 .It \&@3 Ta KEY_CLOSE Ta Close
445 .It \&@4 Ta KEY_COMMAND Ta Command
446 .It \&@5 Ta KEY_COPY Ta Copy
447 .It \&@6 Ta KEY_CREATE Ta Create
448 .It \&@7 Ta KEY_END Ta End
449 .It \&@8 Ta KEY_ENTER Ta Enter
450 .It \&@9 Ta KEY_EXIT Ta Exit
451 .It \&F1 Ta KEY_F(11) Ta Function Key 11
452 .It \&F2 Ta KEY_F(12) Ta Function Key 12
453 .It \&F3 Ta KEY_F(13) Ta Function Key 13
454 .It \&F4 Ta KEY_F(14) Ta Function Key 14
455 .It \&F5 Ta KEY_F(15) Ta Function Key 15
456 .It \&F6 Ta KEY_F(16) Ta Function Key 16
457 .It \&F7 Ta KEY_F(17) Ta Function Key 17
458 .It \&F8 Ta KEY_F(18) Ta Function Key 18
459 .It \&F9 Ta KEY_F(19) Ta Function Key 19
460 .It \&FA Ta KEY_F(20) Ta Function Key 20
461 .It \&FB Ta KEY_F(21) Ta Function Key 21
462 .It \&FC Ta KEY_F(22) Ta Function Key 22
463 .It \&FD Ta KEY_F(23) Ta Function Key 23
464 .It \&FE Ta KEY_F(24) Ta Function Key 24
465 .It \&FF Ta KEY_F(25) Ta Function Key 25
466 .It \&FG Ta KEY_F(26) Ta Function Key 26
467 .It \&FH Ta KEY_F(27) Ta Function Key 27
468 .It \&FI Ta KEY_F(28) Ta Function Key 28
469 .It \&FJ Ta KEY_F(29) Ta Function Key 29
470 .It \&FK Ta KEY_F(30) Ta Function Key 30
471 .It \&FL Ta KEY_F(31) Ta Function Key 31
472 .It \&FM Ta KEY_F(32) Ta Function Key 32
473 .It \&FN Ta KEY_F(33) Ta Function Key 33
474 .It \&FO Ta KEY_F(34) Ta Function Key 34
475 .It \&FP Ta KEY_F(35) Ta Function Key 35
476 .It \&FQ Ta KEY_F(36) Ta Function Key 36
477 .It \&FR Ta KEY_F(37) Ta Function Key 37
478 .It \&FS Ta KEY_F(38) Ta Function Key 38
479 .It \&FT Ta KEY_F(39) Ta Function Key 39
480 .It \&FU Ta KEY_F(40) Ta Function Key 40
481 .It \&FV Ta KEY_F(41) Ta Function Key 41
482 .It \&FW Ta KEY_F(42) Ta Function Key 42
483 .It \&FX Ta KEY_F(43) Ta Function Key 43
484 .It \&FY Ta KEY_F(44) Ta Function Key 44
485 .It \&FZ Ta KEY_F(45) Ta Function Key 45
486 .It \&Fa Ta KEY_F(46) Ta Function Key 46
487 .It \&Fb Ta KEY_F(47) Ta Function Key 47
488 .It \&Fc Ta KEY_F(48) Ta Function Key 48
489 .It \&Fd Ta KEY_F(49) Ta Function Key 49
490 .It \&Fe Ta KEY_F(50) Ta Function Key 50
491 .It \&Ff Ta KEY_F(51) Ta Function Key 51
492 .It \&Fg Ta KEY_F(52) Ta Function Key 52
493 .It \&Fh Ta KEY_F(53) Ta Function Key 53
494 .It \&Fi Ta KEY_F(54) Ta Function Key 54
495 .It \&Fj Ta KEY_F(55) Ta Function Key 55
496 .It \&Fk Ta KEY_F(56) Ta Function Key 56
497 .It \&Fl Ta KEY_F(57) Ta Function Key 57
498 .It \&Fm Ta KEY_F(58) Ta Function Key 58
499 .It \&Fn Ta KEY_F(59) Ta Function Key 59
500 .It \&Fo Ta KEY_F(60) Ta Function Key 60
501 .It \&Fp Ta KEY_F(61) Ta Function Key 61
502 .It \&Fq Ta KEY_F(62) Ta Function Key 62
503 .It \&Fr Ta KEY_F(63) Ta Function Key 63
504 .It \&K1 Ta KEY_A1 Ta Upper left key in keypad
505 .It \&K2 Ta KEY_B2 Ta Centre key in keypad
506 .It \&K3 Ta KEY_A3 Ta Upper right key in keypad
507 .It \&K4 Ta KEY_C1 Ta Lower left key in keypad
508 .It \&K5 Ta KEY_C3 Ta Lower right key in keypad
509 .It \&Km Ta KEY_MOUSE Ta Mouse Event
510 .It \&k0 Ta KEY_F0 Ta Function Key 0
511 .It \&k1 Ta KEY_F(1) Ta Function Key 1
512 .It \&k2 Ta KEY_F(2) Ta Function Key 2
513 .It \&k3 Ta KEY_F(3) Ta Function Key 3
514 .It \&k4 Ta KEY_F(4) Ta Function Key 4
515 .It \&k5 Ta KEY_F(5) Ta Function Key 5
516 .It \&k6 Ta KEY_F(6) Ta Function Key 6
517 .It \&k7 Ta KEY_F(7) Ta Function Key 7
518 .It \&k8 Ta KEY_F(8) Ta Function Key 8
519 .It \&k9 Ta KEY_F(9) Ta Function Key 9
520 .It \&k; Ta KEY_F(10) Ta Function Key 10
521 .It \&kA Ta KEY_IL Ta Insert Line
522 .It \&ka Ta KEY_CATAB Ta Clear All Tabs
523 .It \&kB Ta KEY_BTAB Ta Back Tab
524 .It \&kb Ta KEY_BACKSPACE Ta Backspace
525 .It \&kC Ta KEY_CLEAR Ta Clear
526 .It \&kD Ta KEY_DC Ta Delete Character
527 .It \&kd Ta KEY_DOWN Ta Down Arrow
528 .It \&kE Ta KEY_EOL Ta Clear to End Of Line
529 .It \&kF Ta KEY_SF Ta Scroll Forward one line
530 .It \&kH Ta KEY_LL Ta Home Down
531 .It \&kh Ta KEY_HOME Ta Home
532 .It \&kI Ta KEY_IC Ta Insert Character
533 .It \&kL Ta KEY_DL Ta Delete Line
534 .It \&kl Ta KEY_LEFT Ta Left Arrow
535 .It \&kM Ta KEY_EIC Ta Exit Insert Character Mode
536 .It \&kN Ta KEY_NPAGE Ta Next Page
537 .It \&kP Ta KEY_PPAGE Ta Previous Page
538 .It \&kR Ta KEY_SR Ta Scroll One Line Back
539 .It \&kr Ta KEY_RIGHT Ta Right Arrow
540 .It \&kS Ta KEY_EOS Ta Clear to End Of Screen
541 .It \&kT Ta KEY_STAB Ta Set Tab
542 .It \&kt Ta KEY_CTAB Ta Clear Tab
543 .It \&ku Ta KEY_UP Ta Up Arrow
544 .El
545 .Pp
546 Note that not all terminals are capable of generating all the keycodes
547 listed above nor are termcap entries normally configured with all the
548 above capabilities defined.
549 .Pp
550 Other functions that return an int will return one of the following
551 values:
552 .Pp
553 .Bl -tag -width ERR -compact
554 .It Er OK
555 The function completed successfully.
556 .It Er ERR
557 An error occurred in the function.
558 .El
559 .Pp
560 Functions returning pointers will return
561 .Dv NULL
562 if an error is detected.
563 .Sh SEE ALSO
564 .Xr curses_cursor 3 ,
565 .Xr curses_keyname 3 ,
566 .Xr curses_refresh 3 ,
567 .Xr curses_tty 3 ,
568 .Xr termcap 5
569 .Sh STANDARDS
570 The
571 .Nx
572 Curses library complies with the X/Open Curses specification, part of the
573 Single Unix Specification.
574 .Sh NOTES
575 The
576 .Fn keyok
577 and
578 .Fn define_key
579 functions are implementations of extensions made by the NCurses library
580 to the Curses standard.
581 Portable implementations should avoid the use of these functions.
582 .Sh HISTORY
583 The Curses package appeared in
584 .Bx 4.0 .