summaryrefslogtreecommitdiffstats
path: root/contrib/ncurses/man/curs_getch.3x
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/ncurses/man/curs_getch.3x')
-rw-r--r--contrib/ncurses/man/curs_getch.3x328
1 files changed, 0 insertions, 328 deletions
diff --git a/contrib/ncurses/man/curs_getch.3x b/contrib/ncurses/man/curs_getch.3x
deleted file mode 100644
index 71fed5f..0000000
--- a/contrib/ncurses/man/curs_getch.3x
+++ /dev/null
@@ -1,328 +0,0 @@
-'\" t
-.\"***************************************************************************
-.\" Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. *
-.\" *
-.\" Permission is hereby granted, free of charge, to any person obtaining a *
-.\" copy of this software and associated documentation files (the *
-.\" "Software"), to deal in the Software without restriction, including *
-.\" without limitation the rights to use, copy, modify, merge, publish, *
-.\" distribute, distribute with modifications, sublicense, and/or sell *
-.\" copies of the Software, and to permit persons to whom the Software is *
-.\" furnished to do so, subject to the following conditions: *
-.\" *
-.\" The above copyright notice and this permission notice shall be included *
-.\" in all copies or substantial portions of the Software. *
-.\" *
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
-.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
-.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
-.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
-.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
-.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
-.\" *
-.\" Except as contained in this notice, the name(s) of the above copyright *
-.\" holders shall not be used in advertising or otherwise to promote the *
-.\" sale, use or other dealings in this Software without prior written *
-.\" authorization. *
-.\"***************************************************************************
-.\"
-.\" $Id: curs_getch.3x,v 1.30 2006/12/02 17:02:53 tom Exp $
-.TH curs_getch 3X ""
-.na
-.hy 0
-.SH NAME
-\fBgetch\fR,
-\fBwgetch\fR,
-\fBmvgetch\fR,
-\fBmvwgetch\fR,
-\fBungetch\fR,
-\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard
-.ad
-.hy
-.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.PP
-\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
-\fBint has_key(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.
-.PP
-Unless \fBnoecho\fR has been set,
-then the character will also be echoed into the
-designated window according to the following rules:
-If the character is the current erase character, left arrow, or backspace,
-the cursor is moved one space to the left and that screen position is erased
-as if \fBdelch\fR had been called.
-If the character value is any other \fBKEY_\fR define, the user is alerted
-with a \fBbeep\fR call.
-Otherwise the character is simply output to the screen.
-.PP
-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.
-.PP
-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<curses.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.
-.PP
-When a character that could be the beginning of a function key is received
-(which, on modern terminals, means an escape character),
-\fBcurses\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.
-.PP
-The \fBungetch\fR routine places \fIch\fR back onto the input queue to be
-returned by the next call to \fBwgetch\fR.
-There is just one input queue for all windows.
-.PP
-.SS Function Keys
-The following function keys, defined in \fB<curses.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.
-.sp
-.TS
-center tab(/) ;
-l l
-l l .
-\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/T{
-Function keys; space for 64 keys is reserved.
-T}
-KEY_F(\fIn\fR)/T{
-For 0 \(<= \fIn\fR \(<= 63
-T}
-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)
-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_MOUSE/Mouse event read
-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_RESIZE/Screen resized
-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
-.TE
-.PP
-Keypad is arranged like this:
-.sp
-.TS
-center allbox tab(/) ;
-c c c .
-\fBA1\fR/\fBup\fR/\fBA3\fR
-\fBleft\fR/\fBB2\fR/\fBright\fR
-\fBC1\fR/\fBdown\fR/\fBC3\fR
-.TE
-.sp
-The \fBhas_key\fR 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., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP.
-See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and
-\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP.
-.PP
-.SH RETURN VALUE
-All routines return the integer \fBERR\fR upon failure and an integer value
-other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful
-completion.
-.RS
-.TP 5
-\fBungetch\fP
-returns an error
-if there is no more room in the FIFO.
-.TP 5
-\fBwgetch\fP
-returns an error
-if the window pointer is null, or
-if its timeout expires without having any data.
-.RE
-.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.
-.PP
-Note that some keys may be the same as commonly used control
-keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP 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.
-\fBNcurses\fR uses the terminfo definition.
-If it says that \fBKEY_ENTER\fP is control/M,
-\fBgetch\fR will return \fBKEY_ENTER\fP
-when you press control/M.
-.PP
-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.
-.PP
-Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros.
-.PP
-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 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
-\fBERR\fR on failure, but specifies no error conditions.
-.PP
-The echo behavior of these functions on input of \fBKEY_\fR or backspace
-characters was not specified in the SVr4 documentation.
-This description is
-adopted from the XSI Curses standard.
-.PP
-The behavior of \fBgetch\fR 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 \fBread\fR(2) call in
-progress or not, and also (in some implementations) depending on whether an
-input timeout or non-blocking mode has been set.
-.PP
-Programmers concerned about portability should be prepared for either of two
-cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
-interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to
-\fBEINTR\fR.
-Under the \fBncurses\fR implementation, handled signals never
-interrupt \fBgetch\fR.
-.PP
-The \fBhas_key\fR function is unique to \fBncurses\fR.
-We recommend that
-any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro.
-.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_inopts\fR(3X),
-\fBcurs_mouse\fR(3X),
-\fBcurs_move\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBresizeterm\fR(3X).
-.PP
-Comparable functions in the wide-character (ncursesw) library are
-described in
-\fBcurs_get_wch\fR(3X).
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
OpenPOWER on IntegriCloud