diff options
author | ache <ache@FreeBSD.org> | 1994-10-07 08:58:58 +0000 |
---|---|---|
committer | ache <ache@FreeBSD.org> | 1994-10-07 08:58:58 +0000 |
commit | a80c0624fbd8bd1c784b0b5b7a0fd20b09d317b9 (patch) | |
tree | 4a94ca97fb2fc2fdc1fcdd522a66e39c6e763138 /lib/libncurses/curs_getch.3 | |
download | FreeBSD-src-a80c0624fbd8bd1c784b0b5b7a0fd20b09d317b9.zip FreeBSD-src-a80c0624fbd8bd1c784b0b5b7a0fd20b09d317b9.tar.gz |
Moved from ports with several enhancements
Diffstat (limited to 'lib/libncurses/curs_getch.3')
-rw-r--r-- | lib/libncurses/curs_getch.3 | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/lib/libncurses/curs_getch.3 b/lib/libncurses/curs_getch.3 new file mode 100644 index 0000000..1b16502 --- /dev/null +++ b/lib/libncurses/curs_getch.3 @@ -0,0 +1,188 @@ +.TH curs_getch 3X "" +.SH NAME +\fBcurs_getch\fR: \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(3X), \fBcurs_inopts\fR(3X), \fBcurs_move\fR(3X), +\fBcurs_refresh\fR(3X). +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: |