\"      $NetBSD: curses_input.3,v 1.33 2025/04/11 23:57:20 uwe Exp $
\"
\" Copyright (c) 2002
\"      Brett Lymn ([email protected], [email protected])
\"
\" 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 \&#1 Ta KEY_SHELP Ta Shift Help
It \&#2 Ta KEY_SHOME Ta Shift Home
It \&#3 Ta KEY_SIC Ta Shift Insert Character
It \&#4 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 .

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.