Moved from ports with several enhancements

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: