Annotation of src/lib/libcurses/curses_input.3, Revision 1.1
1.1 ! blymn 1: .\" $NetBSD$
! 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 August 12, 2002
! 34: .Dt CURSES_INPUT 3
! 35: .Os
! 36: .Sh NAME
! 37: .Nm curses_input ,
! 38: .Nm getch ,
! 39: .Nm wgetch ,
! 40: .Nm getnstr ,
! 41: .Nm wgetnstr ,
! 42: .Nm mvgetnstr ,
! 43: .Nm mvwgetnstr ,
! 44: .Nm getstr ,
! 45: .Nm wgetstr ,
! 46: .Nm mvgetstr ,
! 47: .Nm mvwgetstr ,
! 48: .Nm keypad ,
! 49: .Nm notimeout ,
! 50: .Nm timeout ,
! 51: .Nm wtimeout ,
! 52: .Nm nodelay ,
! 53: .Nm ungetch
! 54: .Nd curses input stream routines
! 55: .Sh LIBRARY
! 56: .Lb libcurses
! 57: .Sh SYNOPSIS
! 58: .Fd #include \*[Lt]curses.h\*[Gt]
! 59: .Ft int
! 60: .Fn getch "void"
! 61: .Ft int
! 62: .Fn wgetch "WINDOW *win"
! 63: .Ft int
! 64: .Fn getnstr "char *str" "int limit"
! 65: .Ft int
! 66: .Fn wgetnstr "WINDOW *win" "char *str" "int limit"
! 67: .Ft int
! 68: .Fn mvgetnstr "int y" "int x" "char *str" "int limit"
! 69: .Ft int
! 70: .Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit"
! 71: .Ft int
! 72: .Fn getstr "char *str"
! 73: .Ft int
! 74: .Fn wgetstr "WINDOW *win" "char *str"
! 75: .Ft int
! 76: .Fn mvgetstr "int y" "int x" "char *str" "int limit"
! 77: .Ft int
! 78: .Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str" "int limit"
! 79: .Ft int
! 80: .Fn keypad "WINDOW *win" "boolf flag"
! 81: .Ft int
! 82: .Fn notimeout "WINDOW *win" "boolf flag"
! 83: .Ft int
! 84: .Fn timeout "int delay"
! 85: .Ft int
! 86: .Fn wtimeout "WINDOW *win" "int delay"
! 87: .Ft int
! 88: .Fn nodelay "WINDOW *win" "boolf flag"
! 89: .Ft int
! 90: .Fn ungetch "int c"
! 91: .Sh DESCRIPTION
! 92: These functions read characters and strings from the window input file
! 93: descriptor.
! 94: .Pp
! 95: The
! 96: .Fn getch
! 97: function reads a character from the
! 98: .Dv stdscr
! 99: input file descriptor and returns it.
! 100: If the
! 101: .Fn keypad
! 102: flag has been set to
! 103: .Dv TRUE ,
! 104: then
! 105: .Fn getch
! 106: will assemble multi-character key sequences into key symbols,
! 107: Calling
! 108: .Fn getch
! 109: will cause an implicit
! 110: .Fn refresh
! 111: on
! 112: .Dv stdscr .
! 113: .Pp
! 114: The
! 115: .Fn wgetch
! 116: function is the same as the
! 117: .Fn getch
! 118: function, exceptng that it reads from the input file descriptor associated
! 119: with the window specified by
! 120: .Fa win .
! 121: .Pp
! 122: The
! 123: .Fn mvgetch
! 124: and
! 125: .Fn mvwgetch
! 126: functions are the same as the
! 127: .Fn getch
! 128: and
! 129: .Fn wgetch
! 130: functions, respectively, excepting that
! 131: .Fn wmove
! 132: is called to move the cursor to the position specified by
! 133: .Fa y ,
! 134: .Fa x
! 135: before the character is read.
! 136: .Pp
! 137: Calling
! 138: .Fn getnstr ,
! 139: .Fn wgetnstr ,
! 140: .Fn mvgetnstr
! 141: or
! 142: .Fn mvwgetnstr
! 143: is effectively the same as calling
! 144: .Fn getch
! 145: repeatedly until a newline is received or the character limit
! 146: .Fa limit
! 147: is reached.
! 148: Once this happens the string is
! 149: .Dv NULL
! 150: terminated and returned in
! 151: .Fa str .
! 152: During input, the normal curses input key processing is performed and
! 153: affects the input buffer.
! 154: The
! 155: .Fn mvgetnstr
! 156: function calls
! 157: .Fn wmove
! 158: to move the cursor to the position given by
! 159: .Fa y ,
! 160: .Fa x
! 161: before getting the string,
! 162: .Fn wgetnstr
! 163: reads the input from the designated window,
! 164: .Fn mvwgetnstr
! 165: moves the cursor to the position given by
! 166: .Fa y ,
! 167: .Fa x
! 168: before getting the input from the designated window.
! 169: .Pp
! 170: The functions
! 171: .Fn getstr ,
! 172: .Fn wgetstr ,
! 173: .Fn mvgetstr
! 174: and
! 175: .Fn mvwgetstr
! 176: are similar to
! 177: .Fn getnstr ,
! 178: .Fn wgetnstr ,
! 179: .Fn mvgetnstr
! 180: and
! 181: .Fn mvwgetnstr ,
! 182: respectively, excepting that there is no limit on the number of characters
! 183: that may be inserted into
! 184: .Fa str .
! 185: This may cause the buffer to be overflowed, so their use is not recommended.
! 186: .Pp
! 187: The
! 188: .Fn keypad
! 189: function is used to affect how
! 190: .Fn getch
! 191: processes input characters.
! 192: If
! 193: .Fa flag
! 194: is set to
! 195: .Dv TRUE ,
! 196: then
! 197: .Fn getch
! 198: will scan the input stream looking for multi-character key sequences
! 199: that are emitted by some terminal function keys.
! 200: If a recognised sequence of characters is found, then
! 201: .Fn getch
! 202: will collapse that sequence into an integer key symbol, as shown below.
! 203: The default setting for the flag is
! 204: .Dv FALSE .
! 205: .Pp
! 206: The
! 207: .Fn notimeout
! 208: function controls whether or not
! 209: .Fn getch
! 210: will wait indefinitely between characters in a multi-character key
! 211: sequence or not.
! 212: If
! 213: .Fa flag
! 214: is
! 215: .Dv TRUE ,
! 216: then there is no timeout applied between characters comprising a
! 217: multi-character key sequence.
! 218: If
! 219: .Fa flag
! 220: is
! 221: .Dv FALSE ,
! 222: then the component characters of a multi-character sequence must not
! 223: have an inter-character gap of more than 200ms.
! 224: If this timing is exceeded, then the multi-character key assembly is
! 225: deemed to have failed and the characters read thus far are returned
! 226: one at a time when
! 227: .Fn getch
! 228: is called.
! 229: The default setting for the flag is
! 230: .Dv FALSE .
! 231: .Pp
! 232: The
! 233: .Fn timeout
! 234: function affects the behaviour of
! 235: .Fn getch
! 236: when reading a character from
! 237: .Dv stdscr .
! 238: If
! 239: .Fa delay
! 240: is negative, then
! 241: .Fn getch
! 242: will block indefinitely on a read.
! 243: If
! 244: .Fa delay
! 245: is 0, then
! 246: .Fn getch
! 247: will return immediately with
! 248: .Dv ERR
! 249: if there are no characters immediately available.
! 250: If
! 251: .Fa delay
! 252: is a positive number, then
! 253: .Fn getch
! 254: will wait for that many milliseconds before returning and, if no character
! 255: was available, then
! 256: .Dv ERR
! 257: will be returned.
! 258: Note that for a positive number, the timeout is only accurate to the nearest
! 259: tenth of a second.
! 260: The
! 261: .Fn wtimeout
! 262: function does the same as
! 263: .Fn timeout
! 264: but applies to the specified window
! 265: .Fa win .
! 266: .Pp
! 267: The
! 268: .Fn nodelay
! 269: function turns on and off blocking reads for
! 270: .Fn getch .
! 271: If
! 272: .Fa flag
! 273: is
! 274: .Dv TRUE ,
! 275: then
! 276: .Fn getch
! 277: will not block on reads, if
! 278: .Fa flag
! 279: is
! 280: .Dv FALSE ,
! 281: then reads will block.
! 282: The default setting for the flag is
! 283: .Dv FALSE .
! 284: .Fn nodelay win TRUE
! 285: is equivalent to
! 286: .Fn wtimeout win 0
! 287: and
! 288: .Fn nodelay win FALSE
! 289: is equivalent to
! 290: .Fn wtimeout win -1 \.
! 291: .Pp
! 292: .Fn ungetch
! 293: will convert
! 294: .Fa c
! 295: into an unsigned char and push that character back onto the input stream.
! 296: Only one character of push-back is guaranteed to work, more may be possible
! 297: depending on system resources.
! 298: .Sh RETURN VALUES
! 299: If
! 300: .Fn keypad TRUE
! 301: has been called on a window, then
! 302: .Fn getch
! 303: may return one of the following values:
! 304: .Pp
! 305: .Bl -column "Termcap entry" "getch Return Value" "Key Function" -offset indent
! 306: .It Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function"
! 307: .It \&!1 Ta KEY_SSAVE Ta Shift Save
! 308: .It \&!2 Ta KEY_SSUSPEND Ta Shift Suspend
! 309: .It \&!3 Ta KEY_SUNDO Ta Shift Undo
! 310: .It \ Ta KEY_SHELP Ta Shift Help
! 311: .It \ Ta KEY_SHOME Ta Shift Home
! 312: .It \ Ta KEY_SIC Ta Shift Insert Character
! 313: .It \ Ta KEY_SLEFT Ta Shift Left Arrow
! 314: .It \&%0 Ta KEY_REDO Ta Redo
! 315: .It \&%1 Ta KEY_HELP Ta Help
! 316: .It \&%2 Ta KEY_MARK Ta Mark
! 317: .It \&%3 Ta KEY_MESSAGE Ta Message
! 318: .It \&%4 Ta KEY_MOVE Ta Move
! 319: .It \&%5 Ta KEY_NEXT Ta Next Object
! 320: .It \&%6 Ta KEY_OPEN Ta Open
! 321: .It \&%7 Ta KEY_OPTIONS Ta Options
! 322: .It \&%8 Ta KEY_PREVIOUS Ta Previous Object
! 323: .It \&%9 Ta KEY_PRINT Ta Print
! 324: .It \&%a Ta KEY_SMESSAGE Ta Shift Message
! 325: .It \&%b Ta KEY_SMOVE Ta Shift Move
! 326: .It \&%c Ta KEY_SNEXT Ta Shift Next Object
! 327: .It \&%d Ta KEY_SOPTIONS Ta Shift Options
! 328: .It \&%e Ta KEY_SPREVIOUS Ta Shift Previous Object
! 329: .It \&%f Ta KEY_SPRINT Ta Shift Print
! 330: .It \&%g Ta KEY_SREDO Ta Shift Redo
! 331: .It \&%h Ta KEY_SREPLACE Ta Shift Replace
! 332: .It \&%i Ta KEY_SRIGHT Ta Shift Right Arrow
! 333: .It \&%j Ta KEY_SRSUME Ta Shift Resume
! 334: .It \&&0 Ta KEY_SCANCEL Ta Shift Cancel
! 335: .It \&&1 Ta KEY_REFERENCE Ta Reference
! 336: .It \&&2 Ta KEY_REFRESH Ta Refresh
! 337: .It \&&3 Ta KEY_REPLACE Ta Replace
! 338: .It \&&4 Ta KEY_RESTART Ta Restart
! 339: .It \&&5 Ta KEY_RESUME Ta Resume
! 340: .It \&&6 Ta KEY_SAVE Ta Save
! 341: .It \&&7 Ta KEY_SUSPEND Ta Suspend
! 342: .It \&&8 Ta KEY_UNDO Ta Undo
! 343: .It \&&9 Ta KEY_SBEG Ta Shift Begin
! 344: .It \&*0 Ta KEY_SFIND Ta Shift Find
! 345: .It \&*1 Ta KEY_SCOMMAND Ta Shift Command
! 346: .It \&*2 Ta KEY_SCOPY Ta Shift Copy
! 347: .It \&*3 Ta KEY_SCREATE Ta Shift Create
! 348: .It \&*4 Ta KEY_SDC Ta Shift Delete Character
! 349: .It \&*5 Ta KEY_SDL Ta Shift Delete Line
! 350: .It \&*6 Ta KEY_SELECT Ta Select
! 351: .It \&*7 Ta KEY_SEND Ta Shift End
! 352: .It \&*8 Ta KEY_SEOL Ta Shift Clear to EOL
! 353: .It \&*9 Ta KEY_SEXIT Ta Shift Exit
! 354: .It \&@0 Ta KEY_FIND Ta Find
! 355: .It \&@1 Ta KEY_BEG Ta Begin
! 356: .It \&@2 Ta KEY_CANCEL Ta Cancel
! 357: .It \&@3 Ta KEY_CLOSE Ta Close
! 358: .It \&@4 Ta KEY_COMMAND Ta Command
! 359: .It \&@5 Ta KEY_COPY Ta Copy
! 360: .It \&@6 Ta KEY_CREATE Ta Create
! 361: .It \&@7 Ta KEY_END Ta End
! 362: .It \&@8 Ta KEY_ENTER Ta Enter
! 363: .It \&@9 Ta KEY_EXIT Ta Exit
! 364: .It \&F1 Ta KEY_F(11) Ta Function Key 11
! 365: .It \&F2 Ta KEY_F(12) Ta Function Key 12
! 366: .It \&F3 Ta KEY_F(13) Ta Function Key 13
! 367: .It \&F4 Ta KEY_F(14) Ta Function Key 14
! 368: .It \&F5 Ta KEY_F(15) Ta Function Key 15
! 369: .It \&F6 Ta KEY_F(16) Ta Function Key 16
! 370: .It \&F7 Ta KEY_F(17) Ta Function Key 17
! 371: .It \&F8 Ta KEY_F(18) Ta Function Key 18
! 372: .It \&F9 Ta KEY_F(19) Ta Function Key 19
! 373: .It \&FA Ta KEY_F(20) Ta Function Key 20
! 374: .It \&FB Ta KEY_F(21) Ta Function Key 21
! 375: .It \&FC Ta KEY_F(22) Ta Function Key 22
! 376: .It \&FD Ta KEY_F(23) Ta Function Key 23
! 377: .It \&FE Ta KEY_F(24) Ta Function Key 24
! 378: .It \&FF Ta KEY_F(25) Ta Function Key 25
! 379: .It \&FG Ta KEY_F(26) Ta Function Key 26
! 380: .It \&FH Ta KEY_F(27) Ta Function Key 27
! 381: .It \&FI Ta KEY_F(28) Ta Function Key 28
! 382: .It \&FJ Ta KEY_F(29) Ta Function Key 29
! 383: .It \&FK Ta KEY_F(30) Ta Function Key 30
! 384: .It \&FL Ta KEY_F(31) Ta Function Key 31
! 385: .It \&FM Ta KEY_F(32) Ta Function Key 32
! 386: .It \&FN Ta KEY_F(33) Ta Function Key 33
! 387: .It \&FO Ta KEY_F(34) Ta Function Key 34
! 388: .It \&FP Ta KEY_F(35) Ta Function Key 35
! 389: .It \&FQ Ta KEY_F(36) Ta Function Key 36
! 390: .It \&FR Ta KEY_F(37) Ta Function Key 37
! 391: .It \&FS Ta KEY_F(38) Ta Function Key 38
! 392: .It \&FT Ta KEY_F(39) Ta Function Key 39
! 393: .It \&FU Ta KEY_F(40) Ta Function Key 40
! 394: .It \&FV Ta KEY_F(41) Ta Function Key 41
! 395: .It \&FW Ta KEY_F(42) Ta Function Key 42
! 396: .It \&FX Ta KEY_F(43) Ta Function Key 43
! 397: .It \&FY Ta KEY_F(44) Ta Function Key 44
! 398: .It \&FZ Ta KEY_F(45) Ta Function Key 45
! 399: .It \&Fa Ta KEY_F(46) Ta Function Key 46
! 400: .It \&Fb Ta KEY_F(47) Ta Function Key 47
! 401: .It \&Fc Ta KEY_F(48) Ta Function Key 48
! 402: .It \&Fd Ta KEY_F(49) Ta Function Key 49
! 403: .It \&Fe Ta KEY_F(50) Ta Function Key 50
! 404: .It \&Ff Ta KEY_F(51) Ta Function Key 51
! 405: .It \&Fg Ta KEY_F(52) Ta Function Key 52
! 406: .It \&Fh Ta KEY_F(53) Ta Function Key 53
! 407: .It \&Fi Ta KEY_F(54) Ta Function Key 54
! 408: .It \&Fj Ta KEY_F(55) Ta Function Key 55
! 409: .It \&Fk Ta KEY_F(56) Ta Function Key 56
! 410: .It \&Fl Ta KEY_F(57) Ta Function Key 57
! 411: .It \&Fm Ta KEY_F(58) Ta Function Key 58
! 412: .It \&Fn Ta KEY_F(59) Ta Function Key 59
! 413: .It \&Fo Ta KEY_F(60) Ta Function Key 60
! 414: .It \&Fp Ta KEY_F(61) Ta Function Key 61
! 415: .It \&Fq Ta KEY_F(62) Ta Function Key 62
! 416: .It \&Fr Ta KEY_F(63) Ta Function Key 63
! 417: .It \&K1 Ta KEY_A1 Ta Upper left key in keypad
! 418: .It \&K2 Ta KEY_B2 Ta Centre key in keypad
! 419: .It \&K3 Ta KEY_A3 Ta Upper right key in keypad
! 420: .It \&K4 Ta KEY_C1 Ta Lower left key in keypad
! 421: .It \&K5 Ta KEY_C3 Ta Lower right key in keypad
! 422: .It \&Km Ta KEY_MOUSE Ta Mouse Event
! 423: .It \&k0 Ta KEY_F0 Ta Function Key 0
! 424: .It \&k1 Ta KEY_F(1) Ta Function Key 1
! 425: .It \&k2 Ta KEY_F(2) Ta Function Key 2
! 426: .It \&k3 Ta KEY_F(3) Ta Function Key 3
! 427: .It \&k4 Ta KEY_F(4) Ta Function Key 4
! 428: .It \&k5 Ta KEY_F(5) Ta Function Key 5
! 429: .It \&k6 Ta KEY_F(6) Ta Function Key 6
! 430: .It \&k7 Ta KEY_F(7) Ta Function Key 7
! 431: .It \&k8 Ta KEY_F(8) Ta Function Key 8
! 432: .It \&k9 Ta KEY_F(9) Ta Function Key 9
! 433: .It \&k; Ta KEY_F(10) Ta Function Key 10
! 434: .It \&kA Ta KEY_IL Ta Insert Line
! 435: .It \&ka Ta KEY_CATAB Ta Clear All Tabs
! 436: .It \&kB Ta KEY_BTAB Ta Back Tab
! 437: .It \&kb Ta KEY_BACKSPACE Ta Backspace
! 438: .It \&kC Ta KEY_CLEAR Ta Clear
! 439: .It \&kD Ta KEY_DC Ta Delete Character
! 440: .It \&kd Ta KEY_DOWN Ta Down Arrow
! 441: .It \&kE Ta KEY_EOL Ta Clear to End Of Line
! 442: .It \&kF Ta KEY_SF Ta Scroll Forward one line
! 443: .It \&kH Ta KEY_LL Ta Home Down
! 444: .It \&kh Ta KEY_HOME Ta Home
! 445: .It \&kI Ta KEY_IC Ta Insert Character
! 446: .It \&kL Ta KEY_DL Ta Delete Line
! 447: .It \&kl Ta KEY_LEFT Ta Left Arrow
! 448: .It \&kM Ta KEY_EIC Ta Exit Insert Character Mode
! 449: .It \&kN Ta KEY_NPAGE Ta Next Page
! 450: .It \&kP Ta KEY_PPAGE Ta Previous Page
! 451: .It \&kR Ta KEY_SR Ta Scroll One Line Back
! 452: .It \&kr Ta KEY_RIGHT Ta Right Arrow
! 453: .It \&kS Ta KEY_EOS Ta Clear to End Of Screen
! 454: .It \&kT Ta KEY_STAB Ta Set Tab
! 455: .It \&kt Ta KEY_CTAB Ta Clear Tab
! 456: .It \&ku Ta KEY_UP Ta Up Arrow
! 457: .El
! 458: .Pp
! 459: Note that not all terminals are capable of generating all the keycodes
! 460: listed above nor are termcap entries normally configured with all the
! 461: above capabilities defined.
! 462: .Pp
! 463: Functions returning pointers will return
! 464: .Dv NULL
! 465: if an error is detected.
! 466: The functions that return an int will return one of the following
! 467: values:
! 468: .Pp
! 469: .Bl -tag -width ERR -compact
! 470: .It Er OK
! 471: The function completed successfully.
! 472: .It Er ERR
! 473: An error occurred in the function.
! 474: .El
! 475: .Sh SEE ALSO
! 476: .Xr curses_cursor 3
! 477: .Xr curses_refresh 3 ,
! 478: .Xr curses_tty 3 ,
! 479: .Xr termcap 5
! 480: .Sh STANDARDS
! 481: The
! 482: .Nx
! 483: Curses library complies with the X/Open Curses specification, part of the
! 484: Single Unix Specification.
! 485: .Sh HISTORY
! 486: The Curses package appeared in
! 487: .Bx 4.0 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to curses_input.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libcurses