cursgetch(3X) cursgetch(3X)
NAME
getch, wgetch, mvgetch, mvwgetch, ungetch, haskey - get (or push back)
characters from curses terminal keyboard
SYNOPSIS
##include <>
int getch(void);;
int wgetch(WINDOW **win);;
int mvgetch(int y,, int x);;
int mvwgetch(WINDOW **win,, int y,, int x);;
int ungetch(int ch);;
int haskey(int ch);;
DESCRIPTION
The getch, wgetch, mvgetch and mvwgetch, routines read a character from
the window. In no-delay mode, if no input is waiting, the value ER is
returned. In delay mode, the program waits until the system passes
text through to the program. Depending on the setting of cbreak, this
is after one character (cbreak mode), or after the first newline
(nocbreak mode). In half-delay mode, the program waits until a charac-
ter is typed or the specified timeout has been reached.
Unless noecho has been set, then the character will also be echoed into
the designated window according to the following rules: If the charac-
ter is the current erase character, left arrow, or backspace, the cur-
sor is moved one space to the left and that screen position is erased
as if delch had been called. If the character value is any other KEY
define, the user is alerted with a beep call. Otherwise the character
is simply output to the screen.
If the window is not a pad, and it has been moved or modified since the
last call to wrefresh, wrefresh will be called before another character
is read.
If keypad is TRUE, and a function key is pressed, the token for that
function key is returned instead of the raw characters. Possible func-
tion keys are defined in <> as macros with values outside the
range of 8-bit characters whose names begin with KEY. Thus, a variable
intended to hold the return value of a function key must be of short
size or larger.
When a character that could be the beginning of a function key is
received (which, on modern terminals, means an escape character),
curses sets a timer. If the remainder of the sequence does not come in
within the designated time, the character is passed through; otherwise,
the function key value is returned. For this reason, many terminals
experience a delay between the time a user presses the escape key and
the escape is returned to the program.
The ungetch routine places ch back onto the input queue to be returned
by the next call to wgetch. There is just one input queue for all win-
dows.
Function Keys
The following function keys, defined in <>, might be returned
by getch if keypad has been enabled. Note that not all of these are
necessarily supported on any particular terminal.
Name Key name
KEYBREAK Break key
KEYDOWN The four arrow keys ...
KEYUP
KEYLEFT
KEYRIGHT
KEYHOME Home key (upward]left arrow)
KEYBACKSPACE Backspace
KEYF0 Function keys; space for 64 keys
is reserved.
KEYF(n) For 0 <= n <= 63
KEYDL Delete line
KEYIL Insert line
KEYDC Delete character
KEYIC Insert char or enter insert mode
KEYEIC Exit insert char mode
KEYCLEAR Clear screen
KEYEOS Clear to end of screen
KEYEOL Clear to end of line
KEYSF Scroll 1 line forward
KEYSR Scroll 1 line backward (reverse)
KEYNPAGE Next page
KEYPAGE Previous page
KEYSTAB Set tab
KEYCTAB Clear tab
KEYCATAB Clear all tabs
KEYENTER Enter or send
KEYSRESET Soft (partial) reset
KEYRESET Reset or hard reset
KEYPRINT Print or copy
KEYL Home down or bottom (lower left)
KEYA1 Upper left of keypad
KEYA3 Upper right of keypad
KEYB2 Center of keypad
KEYC1 Lower left of keypad
KEYC3 Lower right of keypad
KEYBTAB Back tab key
KEYBEG Beg(inning) key
KEYCANCEL Cancel key
KEYCLOSE Close key
KEYCOMAND Cmd (command) key
KEYCOPY Copy key
KEYCREATE Create key
KEYEND End key
KEYEXIT Exit key
KEYFIND Find key
KEYHELP Help key
KEYMARK Mark key
KEYMESAGE Message key
KEYMOUSE Mouse event read
KEYMOVE Move key
KEYNEXT Next object key
KEYOPEN Open key
KEYOPTIONS Options key
KEYPREVIOUS Previous object key
KEYREDO Redo key
KEYREFERENCE Ref(erence) key
KEYREFRESH Refresh key
KEYREPLACE Replace key
KEYRESIZE Screen resized
KEYRESTART Restart key
KEYRESUME Resume key
KEYSAVE Save key
KEYSBEG Shifted beginning key
KEYSCANCEL Shifted cancel key
KEYSCOMAND Shifted command key
KEYSCOPY Shifted copy key
KEYSCREATE Shifted create key
KEYSDC Shifted delete char key
KEYSDL Shifted delete line key
KEYSELECT Select key
KEYSEND Shifted end key
KEYSEOL Shifted clear line key
KEYSEXIT Shifted exit key
KEYSFIND Shifted find key
KEYSHELP Shifted help key
KEYSHOME Shifted home key
KEYSIC Shifted input key
KEYSLEFT Shifted left arrow key
KEYSMESAGE Shifted message key
KEYSMOVE Shifted move key
KEYSNEXT Shifted next key
KEYSOPTIONS Shifted options key
KEYSPREVIOUS Shifted prev key
KEYSPRINT Shifted print key
KEYSREDO Shifted redo key
KEYSREPLACE Shifted replace key
KEYSRIGHT Shifted right arrow
KEYSRSUME Shifted resume key
KEYSAVE Shifted save key
KEYSUSPEND Shifted suspend key
KEYSUNDO Shifted undo key
KEYSUSPEND Suspend key
KEYUNDO Undo key
Keypad is arranged like this:
]-----]------]-------]
A1 up A3
]-----]------]-------]
left B2 right
]-----]------]-------]
C1 down C3
]-----]------]-------]
The haskey routine takes a key value from the above list, and returns
TRUE or FALSE according to whether the current terminal type recognizes
a key with that value. Note that a few values do not correspond to a
real key, e.g., KEYRESIZE and KEYMOUSE.
RETURN VALUE
All routines return the integer ER upon failure and an integer value
other than ER (OK in the case of ungetch()) upon successful comple-
tion.
NOTES
Use of the escape key by a programmer for a single character function
is discouraged, as it will cause a delay of up to one second while the
keypad code looks for a following function-key sequence.
Note that some keys may be the same as commonly used control keys,
e.g., KEYENTER versus control/M, KEYBACKSPACE versus control/H. Some
curses implementations may differ according to whether they treat these
control keys specially (and ignore the terminfo), or use the terminfo
definitions. Ncurses uses the terminfo definition. If it says that
KEYENTER is control/M, getch will return KEYENTER when you press con-
trol/M.
When using getch, wgetch, mvgetch, or mvwgetch, nocbreak mode
(nocbreak) and echo mode (echo) should not be used at the same time.
Depending on the state of the tty driver when each character is typed,
the program may produce undesirable results.
Note that getch, mvgetch, and mvwgetch may be macros.
Historically, the set of keypad macros was largely defined by the
extremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka
Safari 4. Modern personal computers usually have only a small subset
of these. IBM PC-style consoles typically support little more than
KEYUP, KEYDOWN, KEYLEFT, KEYRIGHT, KEYHOME, KEYEND, KEYNPAGE,
KEYPAGE, and function keys 1 through 12. The Ins key is usually
mapped to KEYIC.
PORTABILITY
The *get* functions are described in the XSI Curses standard, Issue 4.
They read single-byte characters only. The standard specifies that
they return ER on failure, but specifies no error conditions.
The echo behavior of these functions on input of KEY or backspace
characters was not specified in the SVr4 documentation. This descrip-
tion is adopted from the XSI Curses standard.
The behavior of getch and friends in the presence of handled signals is
unspecified in the SVr4 and XSI Curses documentation. Under historical
curses implementations, it varied depending on whether the operating
system's implementation of handled signal receipt interrupts a read(2)
call in progress or not, and also (in some implementations) depending
on whether an input timeout or non-blocking mode has been set.
Programmers concerned about portability should be prepared for either
of two cases: (a) signal receipt does not interrupt getch; (b) signal
receipt interrupts getch and causes it to return ER with errno set to
EINTR. Under the ncurses implementation, handled signals never inter-
rupt getch.
The haskey function is unique to ncurses. We recommend that any code
using it be conditionalized on the NCURSESVERSION feature macro.
SEE ALSO
curses(3X), cursinopts(3X), cursmouse(3X), cursmove(3X),
cursrefresh(3X). resizeterm(3X).
cursgetch(3X)
|
