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.
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
termcap(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
termcap(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
termcap(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.