3e6427f35f
old 1M, 3X and 3S section numbers) and make some minor formatting changes to silence manck.
189 lines
7.5 KiB
Groff
189 lines
7.5 KiB
Groff
.TH curs_getch 3 ""
|
|
.SH NAME
|
|
\fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR,
|
|
\fBmvwgetch\fR,
|
|
\fBungetch\fR - get (or push back) characters from \fBncurses\fR terminal keyboard
|
|
.SH SYNOPSIS
|
|
\fB#include <ncurses.h>\fR
|
|
|
|
\fBint getch(void);\fR
|
|
.br
|
|
\fBint wgetch(WINDOW *win);\fR
|
|
.br
|
|
\fBint mvgetch(int y, int x);\fR
|
|
.br
|
|
\fBint mvwgetch(WINDOW *win, int y, int x);\fR
|
|
.br
|
|
\fBint ungetch(int ch);\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read
|
|
a character from the window. In no-delay mode, if no input is waiting, the
|
|
value \fBERR\fR is returned. In delay mode, the program waits until the system
|
|
passes text through to the program. Depending on the setting of \fBcbreak\fR,
|
|
this is after one character (cbreak mode), or after the first newline (nocbreak
|
|
mode). In half-delay mode, the program waits until a character is typed or the
|
|
specified timeout has been reached. Unless \fBnoecho\fR has been set, the
|
|
character will also be echoed into the designated window.
|
|
|
|
If the window is not a pad, and it has been moved or modified since the last
|
|
call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character
|
|
is read.
|
|
|
|
If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for
|
|
that function key is returned instead of the raw characters. Possible function
|
|
keys are defined in \fB<ncurses.h>\fR as macros with values outside the range
|
|
of 8-bit characters whose names begin with \fBKEY_.\fR 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), \fBncurses\fR 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 \fBungetch\fR routine places \fIch\fR back onto the input queue to be
|
|
returned by the next call to \fBwgetch\fR. Note that there is, in effect,
|
|
just one input queue for all windows.
|
|
|
|
.SS Function Keys
|
|
The following function keys, defined in \fB<ncurses.h>\fR, might be returned by
|
|
\fBgetch\fR if \fBkeypad\fR has been enabled. Note that not all of these are
|
|
necessarily supported on any particular terminal.
|
|
.nf
|
|
__________________________________________________________________
|
|
\fIName\fR \fIKey\fR \fIname\fR
|
|
__________________________________________________________________
|
|
KEY_BREAK Break key
|
|
KEY_DOWN The four arrow keys ...
|
|
KEY_UP
|
|
KEY_LEFT
|
|
KEY_RIGHT
|
|
KEY_HOME Home key (upward+left arrow)
|
|
KEY_BACKSPACE Backspace
|
|
KEY_F0 Function keys; space for 64 keys is reserved.
|
|
KEY_F(\fIn\fR) For 0 \fI<\fR \fIn\fR \fI<\fR 63
|
|
KEY_DL Delete line
|
|
KEY_IL Insert line
|
|
KEY_DC Delete character
|
|
KEY_IC Insert char or enter insert mode
|
|
KEY_EIC Exit insert char mode
|
|
KEY_CLEAR Clear screen
|
|
KEY_EOS Clear to end of screen
|
|
KEY_EOL Clear to end of line
|
|
KEY_SF Scroll 1 line forward
|
|
KEY_SR Scroll 1 line backward (reverse)
|
|
KEY_NPAGE Next page
|
|
KEY_PPAGE Previous page
|
|
KEY_STAB Set tab
|
|
KEY_CTAB Clear tab
|
|
KEY_CATAB Clear all tabs
|
|
KEY_ENTER Enter or send
|
|
KEY_SRESET Soft (partial) reset
|
|
KEY_RESET Reset or hard reset
|
|
KEY_PRINT Print or copy
|
|
KEY_LL Home down or bottom (lower left). Keypad is
|
|
arranged like this:
|
|
\fBA1\fR \fBup\fR \fBA3\fR
|
|
\fBleft\fR \fBB2\fR \fBright\fR
|
|
\fBC1\fR \fBdown\fR \fBC3\fR
|
|
KEY_A1 Upper left of keypad
|
|
KEY_A3 Upper right of keypad
|
|
KEY_B2 Center of keypad
|
|
KEY_C1 Lower left of keypad
|
|
KEY_C3 Lower right of keypad
|
|
KEY_BTAB Back tab key
|
|
KEY_BEG Beg(inning) key
|
|
KEY_CANCEL Cancel key
|
|
KEY_CLOSE Close key
|
|
KEY_COMMAND Cmd (command) key
|
|
KEY_COPY Copy key
|
|
KEY_CREATE Create key
|
|
KEY_END End key
|
|
KEY_EXIT Exit key
|
|
KEY_FIND Find key
|
|
KEY_HELP Help key
|
|
KEY_MARK Mark key
|
|
KEY_MESSAGE Message key
|
|
KEY_MOVE Move key
|
|
KEY_NEXT Next object key
|
|
KEY_OPEN Open key
|
|
KEY_OPTIONS Options key
|
|
KEY_PREVIOUS Previous object key
|
|
KEY_REDO Redo key
|
|
KEY_REFERENCE Ref(erence) key
|
|
KEY_REFRESH Refresh key
|
|
KEY_REPLACE Replace key
|
|
KEY_RESTART Restart key
|
|
KEY_RESUME Resume key
|
|
KEY_SAVE Save key
|
|
KEY_SBEG Shifted beginning key
|
|
KEY_SCANCEL Shifted cancel key
|
|
KEY_SCOMMAND Shifted command key
|
|
KEY_SCOPY Shifted copy key
|
|
KEY_SCREATE Shifted create key
|
|
KEY_SDC Shifted delete char key
|
|
KEY_SDL Shifted delete line key
|
|
KEY_SELECT Select key
|
|
KEY_SEND Shifted end key
|
|
KEY_SEOL Shifted clear line key
|
|
KEY_SEXIT Shifted exit key
|
|
KEY_SFIND Shifted find key
|
|
KEY_SHELP Shifted help key
|
|
KEY_SHOME Shifted home key
|
|
KEY_SIC Shifted input key
|
|
KEY_SLEFT Shifted left arrow key
|
|
KEY_SMESSAGE Shifted message key
|
|
KEY_SMOVE Shifted move key
|
|
KEY_SNEXT Shifted next key
|
|
KEY_SOPTIONS Shifted options key
|
|
KEY_SPREVIOUS Shifted prev key
|
|
KEY_SPRINT Shifted print key
|
|
KEY_SREDO Shifted redo key
|
|
KEY_SREPLACE Shifted replace key
|
|
KEY_SRIGHT Shifted right arrow
|
|
KEY_SRSUME Shifted resume key
|
|
KEY_SSAVE Shifted save key
|
|
KEY_SSUSPEND Shifted suspend key
|
|
KEY_SUNDO Shifted undo key
|
|
KEY_SUSPEND Suspend key
|
|
KEY_UNDO Undo key
|
|
.fi
|
|
|
|
.SH RETURN VALUE
|
|
All routines return the integer \fBERR\fR upon failure and an integer
|
|
value other than \fBERR\fR upon successful completion.
|
|
.SH 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.
|
|
|
|
When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or
|
|
\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode
|
|
(\fBecho\fR) 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 \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR 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 \fBKEY_UP\fR, \fBKEY_DOWN\fR,
|
|
\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR,
|
|
\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. The Ins key
|
|
is usually mapped to \fBKEY_IC\fR.
|
|
.SH CAPABILITIES
|
|
All of the key_* capabilities; also \fBkeypad_local\fR and \fBkeypad_xmit\fR.
|
|
.SH SEE ALSO
|
|
\fBncurses\fR(3), \fBcurs_inopts\fR(3), \fBcurs_move\fR(3),
|
|
\fBcurs_refresh\fR(3).
|
|
.\"#
|
|
.\"# The following sets edit modes for GNU EMACS
|
|
.\"# Local Variables:
|
|
.\"# mode:nroff
|
|
.\"# fill-column:79
|
|
.\"# End:
|