NAME
curses_input,
getch,
wgetch,
mvgetch,
mvwgetch,
define_key,
keyok,
has_key,
getnstr,
wgetnstr,
mvgetnstr,
mvwgetnstr,
getstr,
wgetstr,
mvgetstr,
mvwgetstr,
keypad,
is_keypad,
notimeout,
timeout,
wtimeout,
nodelay,
ungetch,
set_escdelay —
curses input stream
routines
LIBRARY
Curses Library (libcurses, -lcurses)
SYNOPSIS
#include <curses.h>
int
getch(
void);
int
wgetch(
WINDOW
*win);
int
mvgetch(
int
y,
int x);
int
mvwgetch(
WINDOW
*win,
int y,
int x);
int
keyok(
int
key_symbol,
bool
flag);
int
has_key(
int
key_symbol);
int
define_key(
char
*sequence,
int
key_symbol);
int
getnstr(
char
*str,
int limit);
int
wgetnstr(
WINDOW
*win,
char *str,
int limit);
int
mvgetnstr(
int
y,
int x,
char *str,
int limit);
int
mvwgetnstr(
WINDOW
*win,
int y,
int x,
char *str,
int limit);
int
getstr(
char
*str);
int
wgetstr(
WINDOW
*win,
char *str);
int
mvgetstr(
int
y,
int x,
char *str);
int
mvwgetstr(
WINDOW
*win,
int y,
int x,
char *str);
int
keypad(
WINDOW
*win,
boolf flag);
bool
is_keypad(
const
WINDOW *win);
int
notimeout(
WINDOW
*win,
boolf flag);
int
timeout(
int
delay);
int
wtimeout(
WINDOW
*win,
int delay);
int
nodelay(
WINDOW
*win,
boolf flag);
int
ungetch(
int
c);
int
set_escdelay(
int
escdelay);
extern int ESCDELAY;
DESCRIPTION
These functions read characters and strings from the window input file
descriptor.
The
getch() function reads a character from the
stdscr
input file descriptor and returns it. If the
keypad() flag has been set to
TRUE
,
then
getch() will assemble multi-character key sequences
into key symbols, If the terminal is resized,
getch() will
return
KEY_RESIZE
, regardless of the setting of
keypad(). Calling
getch() will cause an
implicit
refresh() on
stdscr
.
The
wgetch() function is the same as the
getch() function, excepting that it reads from the input
file descriptor associated with the window specified by
win.
If the
keypad() flag is
TRUE
then the
assembly of specific key symbols can be disabled by using the
keyok() function. If the
flag is set
to
FALSE
on a key symbol then
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
is_keypad()
function returns
TRUE
if the keypad flag is set for
the window specified by
win.
The
has_key() function takes a key value and returns
TRUE
if the current terminal recognises a key with
that value, otherwise
FALSE
.
Custom associations between sequences of characters and a key symbol can be made
by using the
define_key() function. Normally, these
associations are made by the information in the
terminfo(5) database but the
define_key() function gives the capability to remove or add
more associations. If
define_key() is passed a non-NULL
string in
sequence it will associate that sequence with
the key symbol passed in
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
terminfo(5) derived ones. If
define_key() is passed a NULL in
sequence then all associations for the key symbol in
key_symbol will be deleted, this includes any
associations that were derived from
terminfo(5).
The
mvgetch() and
mvwgetch() functions are
the same as the
getch() and
wgetch()
functions, respectively, excepting that
wmove() is called to
move the cursor to the position specified by
y,
x before the character is read.
Calling
getnstr(),
wgetnstr(),
mvgetnstr() or
mvwgetnstr() is effectively
the same as calling
getch() repeatedly until a newline is
received or the character limit
limit is reached. Once
this happens the string is
NULL
terminated and
returned in
str. During input, the normal curses input
key processing is performed and affects the input buffer. The
mvgetnstr() function calls
wmove() to move
the cursor to the position given by
y,
x before getting the string,
wgetnstr() reads the input from the designated window,
mvwgetnstr() moves the cursor to the position given by
y,
x before getting the input from
the designated window.
The functions
getstr(),
wgetstr(),
mvgetstr(), and
mvwgetstr() are similar to
getnstr(),
wgetnstr(),
mvgetnstr(), and
mvwgetnstr(),
respectively, excepting that there is no limit on the number of characters
that may be inserted into
str. This may cause the buffer
to be overflowed, so their use is not recommended.
The
keypad() function is used to affect how
getch() processes input characters. If
flag is set to
TRUE
, then
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
getch() will collapse that sequence into an integer key
symbol, as shown below. The default setting for the flag is
FALSE
.
The
notimeout() function controls whether or not
getch() will wait indefinitely between characters in a
multi-character key sequence or not. If
flag is
TRUE
, then there is no timeout applied between
characters comprising a multi-character key sequence. If
flag is
FALSE
, then the
component characters of a multi-character sequence must not have an
inter-character gap of more than
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
getch() is called. The default setting for the flag is
FALSE
. The default value of
ESCDELAY is 300ms. If
ESCDELAY is
negative, no timeout is applied between characters comprising a
multi-character key sequence.
The
timeout() function affects the behaviour of
getch() when reading a character from
stdscr
. If
delay is negative,
then
getch() will block indefinitely on a read. If
delay is 0, then
getch() will return
immediately with
ERR
if there are no characters
immediately available. If
delay is a positive number,
then
getch() will wait for that many milliseconds before
returning and, if no character was available, then
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
delay is 25500 milliseconds. The
wtimeout() function does the same as
timeout() but applies to the specified window
win.
The
nodelay() function turns on and off blocking reads for
getch(). If
flag is
TRUE
, then
getch() will not block on
reads, if
flag is
FALSE
, then
reads will block. The default setting for the flag is
FALSE
.
nodelay(
win,
TRUE) is equivalent to
wtimeout(
win,
0)
and
nodelay(
win,
FALSE) is equivalent to
wtimeout(
win,
-1).
ungetch() will convert
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.
The
set_escdelay() function sets the
ESCDELAY value of the current screen to
escdelay.
RETURN VALUES
The functions
getch(),
wgetch(),
mvgetch(), and
mvwgetch() will return the
value of the key pressed or
ERR
in the case of an
error or a timeout. Additionally, if
keypad(
TRUE) has been called on a
window, then it may return one of the following values:
Termcap entry |
getch Return Value |
Key Function |
!1 |
KEY_SSAVE |
Shift Save |
!2 |
KEY_SSUSPEND |
Shift Suspend |
!3 |
KEY_SUNDO |
Shift Undo |
#1 |
KEY_SHELP |
Shift Help |
#2 |
KEY_SHOME |
Shift Home |
#3 |
KEY_SIC |
Shift Insert Character |
#4 |
KEY_SLEFT |
Shift Left Arrow |
%0 |
KEY_REDO |
Redo |
%1 |
KEY_HELP |
Help |
%2 |
KEY_MARK |
Mark |
%3 |
KEY_MESSAGE |
Message |
%4 |
KEY_MOVE |
Move |
%5 |
KEY_NEXT |
Next Object |
%6 |
KEY_OPEN |
Open |
%7 |
KEY_OPTIONS |
Options |
%8 |
KEY_PREVIOUS |
Previous Object |
%9 |
KEY_PRINT |
Print |
%a |
KEY_SMESSAGE |
Shift Message |
%b |
KEY_SMOVE |
Shift Move |
%c |
KEY_SNEXT |
Shift Next Object |
%d |
KEY_SOPTIONS |
Shift Options |
%e |
KEY_SPREVIOUS |
Shift Previous Object |
%f |
KEY_SPRINT |
Shift Print |
%g |
KEY_SREDO |
Shift Redo |
%h |
KEY_SREPLACE |
Shift Replace |
%i |
KEY_SRIGHT |
Shift Right Arrow |
%j |
KEY_SRSUME |
Shift Resume |
&0 |
KEY_SCANCEL |
Shift Cancel |
&1 |
KEY_REFERENCE |
Reference |
&2 |
KEY_REFRESH |
Refresh |
&3 |
KEY_REPLACE |
Replace |
&4 |
KEY_RESTART |
Restart |
&5 |
KEY_RESUME |
Resume |
&6 |
KEY_SAVE |
Save |
&7 |
KEY_SUSPEND |
Suspend |
&8 |
KEY_UNDO |
Undo |
&9 |
KEY_SBEG |
Shift Begin |
*0 |
KEY_SFIND |
Shift Find |
*1 |
KEY_SCOMMAND |
Shift Command |
*2 |
KEY_SCOPY |
Shift Copy |
*3 |
KEY_SCREATE |
Shift Create |
*4 |
KEY_SDC |
Shift Delete Character |
*5 |
KEY_SDL |
Shift Delete Line |
*6 |
KEY_SELECT |
Select |
*7 |
KEY_SEND |
Shift End |
*8 |
KEY_SEOL |
Shift Clear to EOL |
*9 |
KEY_SEXIT |
Shift Exit |
@0 |
KEY_FIND |
Find |
@1 |
KEY_BEG |
Begin |
@2 |
KEY_CANCEL |
Cancel |
@3 |
KEY_CLOSE |
Close |
@4 |
KEY_COMMAND |
Command |
@5 |
KEY_COPY |
Copy |
@6 |
KEY_CREATE |
Create |
@7 |
KEY_END |
End |
@8 |
KEY_ENTER |
Enter |
@9 |
KEY_EXIT |
Exit |
F1 |
KEY_F(11) |
Function Key 11 |
F2 |
KEY_F(12) |
Function Key 12 |
F3 |
KEY_F(13) |
Function Key 13 |
F4 |
KEY_F(14) |
Function Key 14 |
F5 |
KEY_F(15) |
Function Key 15 |
F6 |
KEY_F(16) |
Function Key 16 |
F7 |
KEY_F(17) |
Function Key 17 |
F8 |
KEY_F(18) |
Function Key 18 |
F9 |
KEY_F(19) |
Function Key 19 |
FA |
KEY_F(20) |
Function Key 20 |
FB |
KEY_F(21) |
Function Key 21 |
FC |
KEY_F(22) |
Function Key 22 |
FD |
KEY_F(23) |
Function Key 23 |
FE |
KEY_F(24) |
Function Key 24 |
FF |
KEY_F(25) |
Function Key 25 |
FG |
KEY_F(26) |
Function Key 26 |
FH |
KEY_F(27) |
Function Key 27 |
FI |
KEY_F(28) |
Function Key 28 |
FJ |
KEY_F(29) |
Function Key 29 |
FK |
KEY_F(30) |
Function Key 30 |
FL |
KEY_F(31) |
Function Key 31 |
FM |
KEY_F(32) |
Function Key 32 |
FN |
KEY_F(33) |
Function Key 33 |
FO |
KEY_F(34) |
Function Key 34 |
FP |
KEY_F(35) |
Function Key 35 |
FQ |
KEY_F(36) |
Function Key 36 |
FR |
KEY_F(37) |
Function Key 37 |
FS |
KEY_F(38) |
Function Key 38 |
FT |
KEY_F(39) |
Function Key 39 |
FU |
KEY_F(40) |
Function Key 40 |
FV |
KEY_F(41) |
Function Key 41 |
FW |
KEY_F(42) |
Function Key 42 |
FX |
KEY_F(43) |
Function Key 43 |
FY |
KEY_F(44) |
Function Key 44 |
FZ |
KEY_F(45) |
Function Key 45 |
Fa |
KEY_F(46) |
Function Key 46 |
Fb |
KEY_F(47) |
Function Key 47 |
Fc |
KEY_F(48) |
Function Key 48 |
Fd |
KEY_F(49) |
Function Key 49 |
Fe |
KEY_F(50) |
Function Key 50 |
Ff |
KEY_F(51) |
Function Key 51 |
Fg |
KEY_F(52) |
Function Key 52 |
Fh |
KEY_F(53) |
Function Key 53 |
Fi |
KEY_F(54) |
Function Key 54 |
Fj |
KEY_F(55) |
Function Key 55 |
Fk |
KEY_F(56) |
Function Key 56 |
Fl |
KEY_F(57) |
Function Key 57 |
Fm |
KEY_F(58) |
Function Key 58 |
Fn |
KEY_F(59) |
Function Key 59 |
Fo |
KEY_F(60) |
Function Key 60 |
Fp |
KEY_F(61) |
Function Key 61 |
Fq |
KEY_F(62) |
Function Key 62 |
Fr |
KEY_F(63) |
Function Key 63 |
K1 |
KEY_A1 |
Upper left key in keypad |
K2 |
KEY_B2 |
Centre key in keypad |
K3 |
KEY_A3 |
Upper right key in keypad |
K4 |
KEY_C1 |
Lower left key in keypad |
K5 |
KEY_C3 |
Lower right key in keypad |
Km |
KEY_MOUSE |
Mouse Event |
k0 |
KEY_F0 |
Function Key 0 |
k1 |
KEY_F(1) |
Function Key 1 |
k2 |
KEY_F(2) |
Function Key 2 |
k3 |
KEY_F(3) |
Function Key 3 |
k4 |
KEY_F(4) |
Function Key 4 |
k5 |
KEY_F(5) |
Function Key 5 |
k6 |
KEY_F(6) |
Function Key 6 |
k7 |
KEY_F(7) |
Function Key 7 |
k8 |
KEY_F(8) |
Function Key 8 |
k9 |
KEY_F(9) |
Function Key 9 |
k; |
KEY_F(10) |
Function Key 10 |
kA |
KEY_IL |
Insert Line |
ka |
KEY_CATAB |
Clear All Tabs |
kB |
KEY_BTAB |
Back Tab |
kb |
KEY_BACKSPACE |
Backspace |
kC |
KEY_CLEAR |
Clear |
kD |
KEY_DC |
Delete Character |
kd |
KEY_DOWN |
Down Arrow |
kE |
KEY_EOL |
Clear to End Of Line |
kF |
KEY_SF |
Scroll Forward one line |
kH |
KEY_LL |
Home Down |
kh |
KEY_HOME |
Home |
kI |
KEY_IC |
Insert Character |
kL |
KEY_DL |
Delete Line |
kl |
KEY_LEFT |
Left Arrow |
kM |
KEY_EIC |
Exit Insert Character Mode |
kN |
KEY_NPAGE |
Next Page |
kP |
KEY_PPAGE |
Previous Page |
kR |
KEY_SR |
Scroll One Line Back |
kr |
KEY_RIGHT |
Right Arrow |
kS |
KEY_EOS |
Clear to End Of Screen |
kT |
KEY_STAB |
Set Tab |
kt |
KEY_CTAB |
Clear Tab |
ku |
KEY_UP |
Up Arrow |
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.
Other functions that return an int will return one of the following values:
OK
- The function completed successfully.
ERR
- An error occurred in the function.
Functions returning pointers will return
NULL
if an
error is detected.
SEE ALSO
curses_cursor(3),
curses_keyname(3),
curses_refresh(3),
curses_tty(3),
terminfo(5)
STANDARDS
The
NetBSD Curses library complies with the X/Open
Curses specification, part of the Single Unix Specification.
NOTES
The
keyok() and
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.
HISTORY
The Curses package appeared in
4.0BSD. The
is_keypad() and
set_tabsize() functions
are
ncurses extension to the Curses library and was added in
NetBSD 8.0.