diff options
Diffstat (limited to 'static/netbsd/man3/curses_input.3')
| -rw-r--r-- | static/netbsd/man3/curses_input.3 | 624 |
1 files changed, 624 insertions, 0 deletions
diff --git a/static/netbsd/man3/curses_input.3 b/static/netbsd/man3/curses_input.3 new file mode 100644 index 00000000..c42ee804 --- /dev/null +++ b/static/netbsd/man3/curses_input.3 @@ -0,0 +1,624 @@ +.\" $NetBSD: curses_input.3,v 1.33 2025/04/11 23:57:20 uwe Exp $ +.\" +.\" Copyright (c) 2002 +.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) +.\" +.\" This code is donated to the NetBSD Foundation by the Author. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the Author may not be used to endorse or promote +.\" products derived from this software without specific prior written +.\" permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" +.Dd May 14, 2024 +.Dt CURSES_INPUT 3 +.Os +.Sh NAME +.Nm curses_input , +.Nm getch , +.Nm wgetch , +.Nm mvgetch , +.Nm mvwgetch , +.Nm define_key , +.Nm keyok , +.Nm has_key , +.Nm getnstr , +.Nm wgetnstr , +.Nm mvgetnstr , +.Nm mvwgetnstr , +.Nm getstr , +.Nm wgetstr , +.Nm mvgetstr , +.Nm mvwgetstr , +.Nm keypad , +.Nm is_keypad , +.Nm notimeout , +.Nm timeout , +.Nm wtimeout , +.Nm nodelay , +.Nm ungetch , +.Nm set_escdelay +.Nd curses input stream routines +.Sh LIBRARY +.Lb libcurses +.Sh SYNOPSIS +.In curses.h +.Ft int +.Fn getch "void" +.Ft int +.Fn wgetch "WINDOW *win" +.Ft int +.Fn mvgetch "int y" "int x" +.Ft int +.Fn mvwgetch "WINDOW *win" "int y" "int x" +.Ft int +.Fn keyok "int key_symbol" "bool flag" +.Ft int +.Fn has_key "int key_symbol" +.Ft int +.Fn define_key "const char *sequence" "int key_symbol" +.Ft int +.Fn getnstr "char *str" "int limit" +.Ft int +.Fn wgetnstr "WINDOW *win" "char *str" "int limit" +.Ft int +.Fn mvgetnstr "int y" "int x" "char *str" "int limit" +.Ft int +.Fn mvwgetnstr "WINDOW *win" "int y" "int x" "char *str" "int limit" +.Ft int +.Fn getstr "char *str" +.Ft int +.Fn wgetstr "WINDOW *win" "char *str" +.Ft int +.Fn mvgetstr "int y" "int x" "char *str" +.Ft int +.Fn mvwgetstr "WINDOW *win" "int y" "int x" "char *str" +.Ft int +.Fn keypad "WINDOW *win" "bool flag" +.Ft bool +.Fn is_keypad "const WINDOW *win" +.Ft int +.Fn notimeout "WINDOW *win" "bool flag" +.Ft void +.Fn timeout "int delay" +.Ft void +.Fn wtimeout "WINDOW *win" "int delay" +.Ft int +.Fn nodelay "WINDOW *win" "bool flag" +.Ft int +.Fn ungetch "int c" +.Ft int +.Fn set_escdelay "int escdelay" +.Pp +.Va extern int ESCDELAY ; +.Sh DESCRIPTION +These functions read characters and strings from the window input file +descriptor. +.Pp +The +.Fn getch +function reads a character from the +.Va stdscr +input file descriptor and returns it. +If the +.Fn keypad +flag has been set to +.Dv TRUE , +then +.Fn getch +will assemble multi-character key sequences into key symbols, +If the terminal is resized, +.Fn getch +will return +.Dv KEY_RESIZE , +regardless of the setting of +.Fn keypad . +Calling +.Fn getch +will cause an implicit +.Fn refresh +on +.Va stdscr . +.Pp +The +.Fn wgetch +function is the same as the +.Fn getch +function, excepting that it reads from the input file descriptor associated +with the window specified by +.Fa win . +.Pp +If the +.Fn keypad +flag is +.Dv TRUE +then the assembly of specific key symbols can be disabled by using the +.Fn keyok +function. +If the +.Fa flag +is set to +.Dv FALSE +on a key symbol then +.Fn getch +will behave as if the character sequence associated with that key symbol +was not recognised and will return the component characters one at a time to +the caller. +The +.Fn is_keypad +function returns +.Dv TRUE +if the +.Fn +keypad +flag is set for the window specified by +.Fa win . +.Pp +The +.Fn has_key +function takes a key value and returns +.Dv TRUE +if the current terminal recognises a key with that value, otherwise +.Dv FALSE . +.Pp +Custom associations between sequences of characters and a key symbol can +be made by using the +.Fn define_key +function. +Normally, these associations are made by the information in the +.Xr terminfo 5 +database but the +.Fn define_key +function gives the capability to remove or add more associations. +If +.Fn define_key +is passed a non-NULL string in +.Fa sequence +it will associate that sequence with the key symbol passed in +.Fa key_symbol . +The key symbol may be one of the ones listed below or a custom value that +is application defined. +It is valid to have multiple character sequences map to the same key +symbol and there are no constraints on the length of the sequence allowed. +The assembly of custom sequences follow the same rules for inter-character +timing and so forth as the +.Xr terminfo 5 +derived ones. +If +.Fn define_key +is passed a NULL in +.Fa sequence +then all associations for the key symbol in +.Fa key_symbol +will be deleted, this includes any associations that were derived from +.Xr terminfo 5 . +.Pp +The +.Fn mvgetch +and +.Fn mvwgetch +functions are the same as the +.Fn getch +and +.Fn wgetch +functions, respectively, excepting that +.Fn wmove +is called to move the cursor to the position specified by +.Fa y , +.Fa x +before the character is read. +.Pp +Calling +.Fn getnstr , +.Fn wgetnstr , +.Fn mvgetnstr +or +.Fn mvwgetnstr +is effectively the same as calling +.Fn getch +repeatedly until a newline is received or the character limit +.Fa limit +is reached. +Once this happens the string is +.Dv NULL +terminated and returned in +.Fa str . +During input, the normal curses input key processing is performed and +affects the input buffer. +The +.Fn mvgetnstr +function calls +.Fn wmove +to move the cursor to the position given by +.Fa y , +.Fa x +before getting the string, +.Fn wgetnstr +reads the input from the designated window, +.Fn mvwgetnstr +moves the cursor to the position given by +.Fa y , +.Fa x +before getting the input from the designated window. +.Pp +The functions +.Fn getstr , +.Fn wgetstr , +.Fn mvgetstr , +and +.Fn mvwgetstr +are similar to +.Fn getnstr , +.Fn wgetnstr , +.Fn mvgetnstr , +and +.Fn mvwgetnstr , +respectively, excepting that there is no limit on the number of characters +that may be inserted into +.Fa str . +This may cause the buffer to be overflowed, so their use is not recommended. +.Pp +The +.Fn keypad +function is used to affect how +.Fn getch +processes input characters. +If +.Fa flag +is set to +.Dv TRUE , +then +.Fn getch +will scan the input stream looking for multi-character key sequences +that are emitted by some terminal function keys. +If a recognised sequence of characters is found, then +.Fn getch +will collapse that sequence into an integer key symbol, as shown below. +The default setting for the flag is +.Dv FALSE . +.Pp +The +.Fn notimeout +function controls whether or not +.Fn getch +will wait indefinitely between characters in a multi-character key +sequence or not. +If +.Fa flag +is +.Dv TRUE , +then there is no timeout applied between characters comprising a +multi-character key sequence. +If +.Fa flag +is +.Dv FALSE , +then the component characters of a multi-character sequence must not +have an inter-character gap of more than +.Va ESCDELAY . +If this timing is exceeded, then the multi-character key assembly is +deemed to have failed and the characters read thus far are returned +one at a time when +.Fn getch +is called. +The default setting for the flag is +.Dv FALSE . +The default value of +.Va ESCDELAY +is 300ms. +If +.Va ESCDELAY +is negative, no timeout is applied between characters comprising a +multi-character key sequence. +.Pp +The +.Fn timeout +function affects the behaviour of +.Fn getch +when reading a character from +.Va stdscr . +If +.Fa delay +is negative, then +.Fn getch +will block indefinitely on a read. +If +.Fa delay +is 0, then +.Fn getch +will return immediately with +.Dv ERR +if there are no characters immediately available. +If +.Fa delay +is a positive number, then +.Fn getch +will wait for that many milliseconds before returning and, if no character +was available, then +.Dv ERR +will be returned. +Note that for a positive number, the timeout is only accurate to the nearest +tenth of a second. +Also, the maximum value of +.Fa delay +is 25500 milliseconds. +The +.Fn wtimeout +function does the same as +.Fn timeout +but applies to the specified window +.Fa win . +.Pp +The +.Fn nodelay +function turns on and off blocking reads for +.Fn getch . +If +.Fa flag +is +.Dv TRUE , +then +.Fn getch +will not block on reads, if +.Fa flag +is +.Dv FALSE , +then reads will block. +The default setting for the flag is +.Dv FALSE . +.Fn nodelay win TRUE +is equivalent to +.Fn wtimeout win 0 +and +.Fn nodelay win FALSE +is equivalent to +.Fn wtimeout win \-1 . +.Pp +.Fn ungetch +will convert +.Fa c +into an unsigned char and push that character back onto the input stream. +Only one character of push-back is guaranteed to work, more may be possible +depending on system resources. +.Pp +The +.Fn set_escdelay +function sets the +.Va ESCDELAY +value of the current screen to +.Fa escdelay . +.Sh RETURN VALUES +The functions +.Fn getch , +.Fn wgetch , +.Fn mvgetch , +and +.Fn mvwgetch +will return the value of the key pressed or +.Dv ERR +in the case of an error or a timeout. +Additionally, if +.Fn keypad TRUE +has been called on a window, then it may return one of the following values: +.Pp +.Bl -column "Termcap entry" "getch Return Value" "Key Function" -offset indent +.It Sy "Termcap entry" Ta Sy "getch Return Value" Ta Sy "Key Function" +.It \&!1 Ta KEY_SSAVE Ta Shift Save +.It \&!2 Ta KEY_SSUSPEND Ta Shift Suspend +.It \&!3 Ta KEY_SUNDO Ta Shift Undo +.It \ Ta KEY_SHELP Ta Shift Help +.It \ Ta KEY_SHOME Ta Shift Home +.It \ Ta KEY_SIC Ta Shift Insert Character +.It \ Ta KEY_SLEFT Ta Shift Left Arrow +.It \&%0 Ta KEY_REDO Ta Redo +.It \&%1 Ta KEY_HELP Ta Help +.It \&%2 Ta KEY_MARK Ta Mark +.It \&%3 Ta KEY_MESSAGE Ta Message +.It \&%4 Ta KEY_MOVE Ta Move +.It \&%5 Ta KEY_NEXT Ta Next Object +.It \&%6 Ta KEY_OPEN Ta Open +.It \&%7 Ta KEY_OPTIONS Ta Options +.It \&%8 Ta KEY_PREVIOUS Ta Previous Object +.It \&%9 Ta KEY_PRINT Ta Print +.It \&%a Ta KEY_SMESSAGE Ta Shift Message +.It \&%b Ta KEY_SMOVE Ta Shift Move +.It \&%c Ta KEY_SNEXT Ta Shift Next Object +.It \&%d Ta KEY_SOPTIONS Ta Shift Options +.It \&%e Ta KEY_SPREVIOUS Ta Shift Previous Object +.It \&%f Ta KEY_SPRINT Ta Shift Print +.It \&%g Ta KEY_SREDO Ta Shift Redo +.It \&%h Ta KEY_SREPLACE Ta Shift Replace +.It \&%i Ta KEY_SRIGHT Ta Shift Right Arrow +.It \&%j Ta KEY_SRSUME Ta Shift Resume +.It \&&0 Ta KEY_SCANCEL Ta Shift Cancel +.It \&&1 Ta KEY_REFERENCE Ta Reference +.It \&&2 Ta KEY_REFRESH Ta Refresh +.It \&&3 Ta KEY_REPLACE Ta Replace +.It \&&4 Ta KEY_RESTART Ta Restart +.It \&&5 Ta KEY_RESUME Ta Resume +.It \&&6 Ta KEY_SAVE Ta Save +.It \&&7 Ta KEY_SUSPEND Ta Suspend +.It \&&8 Ta KEY_UNDO Ta Undo +.It \&&9 Ta KEY_SBEG Ta Shift Begin +.It \&*0 Ta KEY_SFIND Ta Shift Find +.It \&*1 Ta KEY_SCOMMAND Ta Shift Command +.It \&*2 Ta KEY_SCOPY Ta Shift Copy +.It \&*3 Ta KEY_SCREATE Ta Shift Create +.It \&*4 Ta KEY_SDC Ta Shift Delete Character +.It \&*5 Ta KEY_SDL Ta Shift Delete Line +.It \&*6 Ta KEY_SELECT Ta Select +.It \&*7 Ta KEY_SEND Ta Shift End +.It \&*8 Ta KEY_SEOL Ta Shift Clear to EOL +.It \&*9 Ta KEY_SEXIT Ta Shift Exit +.It \&@0 Ta KEY_FIND Ta Find +.It \&@1 Ta KEY_BEG Ta Begin +.It \&@2 Ta KEY_CANCEL Ta Cancel +.It \&@3 Ta KEY_CLOSE Ta Close +.It \&@4 Ta KEY_COMMAND Ta Command +.It \&@5 Ta KEY_COPY Ta Copy +.It \&@6 Ta KEY_CREATE Ta Create +.It \&@7 Ta KEY_END Ta End +.It \&@8 Ta KEY_ENTER Ta Enter +.It \&@9 Ta KEY_EXIT Ta Exit +.It \&F1 Ta KEY_F(11) Ta Function Key 11 +.It \&F2 Ta KEY_F(12) Ta Function Key 12 +.It \&F3 Ta KEY_F(13) Ta Function Key 13 +.It \&F4 Ta KEY_F(14) Ta Function Key 14 +.It \&F5 Ta KEY_F(15) Ta Function Key 15 +.It \&F6 Ta KEY_F(16) Ta Function Key 16 +.It \&F7 Ta KEY_F(17) Ta Function Key 17 +.It \&F8 Ta KEY_F(18) Ta Function Key 18 +.It \&F9 Ta KEY_F(19) Ta Function Key 19 +.It \&FA Ta KEY_F(20) Ta Function Key 20 +.It \&FB Ta KEY_F(21) Ta Function Key 21 +.It \&FC Ta KEY_F(22) Ta Function Key 22 +.It \&FD Ta KEY_F(23) Ta Function Key 23 +.It \&FE Ta KEY_F(24) Ta Function Key 24 +.It \&FF Ta KEY_F(25) Ta Function Key 25 +.It \&FG Ta KEY_F(26) Ta Function Key 26 +.It \&FH Ta KEY_F(27) Ta Function Key 27 +.It \&FI Ta KEY_F(28) Ta Function Key 28 +.It \&FJ Ta KEY_F(29) Ta Function Key 29 +.It \&FK Ta KEY_F(30) Ta Function Key 30 +.It \&FL Ta KEY_F(31) Ta Function Key 31 +.It \&FM Ta KEY_F(32) Ta Function Key 32 +.It \&FN Ta KEY_F(33) Ta Function Key 33 +.It \&FO Ta KEY_F(34) Ta Function Key 34 +.It \&FP Ta KEY_F(35) Ta Function Key 35 +.It \&FQ Ta KEY_F(36) Ta Function Key 36 +.It \&FR Ta KEY_F(37) Ta Function Key 37 +.It \&FS Ta KEY_F(38) Ta Function Key 38 +.It \&FT Ta KEY_F(39) Ta Function Key 39 +.It \&FU Ta KEY_F(40) Ta Function Key 40 +.It \&FV Ta KEY_F(41) Ta Function Key 41 +.It \&FW Ta KEY_F(42) Ta Function Key 42 +.It \&FX Ta KEY_F(43) Ta Function Key 43 +.It \&FY Ta KEY_F(44) Ta Function Key 44 +.It \&FZ Ta KEY_F(45) Ta Function Key 45 +.It \&Fa Ta KEY_F(46) Ta Function Key 46 +.It \&Fb Ta KEY_F(47) Ta Function Key 47 +.It \&Fc Ta KEY_F(48) Ta Function Key 48 +.It \&Fd Ta KEY_F(49) Ta Function Key 49 +.It \&Fe Ta KEY_F(50) Ta Function Key 50 +.It \&Ff Ta KEY_F(51) Ta Function Key 51 +.It \&Fg Ta KEY_F(52) Ta Function Key 52 +.It \&Fh Ta KEY_F(53) Ta Function Key 53 +.It \&Fi Ta KEY_F(54) Ta Function Key 54 +.It \&Fj Ta KEY_F(55) Ta Function Key 55 +.It \&Fk Ta KEY_F(56) Ta Function Key 56 +.It \&Fl Ta KEY_F(57) Ta Function Key 57 +.It \&Fm Ta KEY_F(58) Ta Function Key 58 +.It \&Fn Ta KEY_F(59) Ta Function Key 59 +.It \&Fo Ta KEY_F(60) Ta Function Key 60 +.It \&Fp Ta KEY_F(61) Ta Function Key 61 +.It \&Fq Ta KEY_F(62) Ta Function Key 62 +.It \&Fr Ta KEY_F(63) Ta Function Key 63 +.It \&K1 Ta KEY_A1 Ta Upper left key in keypad +.It \&K2 Ta KEY_B2 Ta Centre key in keypad +.It \&K3 Ta KEY_A3 Ta Upper right key in keypad +.It \&K4 Ta KEY_C1 Ta Lower left key in keypad +.It \&K5 Ta KEY_C3 Ta Lower right key in keypad +.It \&Km Ta KEY_MOUSE Ta Mouse Event +.It \&k0 Ta KEY_F0 Ta Function Key 0 +.It \&k1 Ta KEY_F(1) Ta Function Key 1 +.It \&k2 Ta KEY_F(2) Ta Function Key 2 +.It \&k3 Ta KEY_F(3) Ta Function Key 3 +.It \&k4 Ta KEY_F(4) Ta Function Key 4 +.It \&k5 Ta KEY_F(5) Ta Function Key 5 +.It \&k6 Ta KEY_F(6) Ta Function Key 6 +.It \&k7 Ta KEY_F(7) Ta Function Key 7 +.It \&k8 Ta KEY_F(8) Ta Function Key 8 +.It \&k9 Ta KEY_F(9) Ta Function Key 9 +.It \&k; Ta KEY_F(10) Ta Function Key 10 +.It \&kA Ta KEY_IL Ta Insert Line +.It \&ka Ta KEY_CATAB Ta Clear All Tabs +.It \&kB Ta KEY_BTAB Ta Back Tab +.It \&kb Ta KEY_BACKSPACE Ta Backspace +.It \&kC Ta KEY_CLEAR Ta Clear +.It \&kD Ta KEY_DC Ta Delete Character +.It \&kd Ta KEY_DOWN Ta Down Arrow +.It \&kE Ta KEY_EOL Ta Clear to End Of Line +.It \&kF Ta KEY_SF Ta Scroll Forward one line +.It \&kH Ta KEY_LL Ta Home Down +.It \&kh Ta KEY_HOME Ta Home +.It \&kI Ta KEY_IC Ta Insert Character +.It \&kL Ta KEY_DL Ta Delete Line +.It \&kl Ta KEY_LEFT Ta Left Arrow +.It \&kM Ta KEY_EIC Ta Exit Insert Character Mode +.It \&kN Ta KEY_NPAGE Ta Next Page +.It \&kP Ta KEY_PPAGE Ta Previous Page +.It \&kR Ta KEY_SR Ta Scroll One Line Back +.It \&kr Ta KEY_RIGHT Ta Right Arrow +.It \&kS Ta KEY_EOS Ta Clear to End Of Screen +.It \&kT Ta KEY_STAB Ta Set Tab +.It \&kt Ta KEY_CTAB Ta Clear Tab +.It \&ku Ta KEY_UP Ta Up Arrow +.El +.Pp +Note that not all terminals are capable of generating all the keycodes +listed above nor are terminfo entries normally configured with all the +above capabilities defined. +.Pp +Other functions that return an int will return one of the following +values: +.Pp +.Bl -tag -width ERR -compact +.It Er OK +The function completed successfully. +.It Er ERR +An error occurred in the function. +.El +.Pp +Functions returning pointers will return +.Dv NULL +if an error is detected. +.Sh SEE ALSO +.Xr curses_cursor 3 , +.Xr curses_keyname 3 , +.Xr curses_refresh 3 , +.Xr curses_tty 3 , +.Xr terminfo 5 +.Sh STANDARDS +The +.Nx +Curses library complies with the X/Open Curses specification, part of the +Single Unix Specification. +.Sh NOTES +The +.Fn keyok +and +.Fn define_key +functions are implementations of extensions made by the NCurses library +to the Curses standard. +Portable implementations should avoid the use of these functions. +.Sh HISTORY +The Curses package appeared in +.Bx 4.0 . +The +.Fn is_keypad +and +.Fn set_tabsize +functions are +.Em ncurses +extension to the Curses library and was added in +.Nx 8.0 . |