diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3/curs_getch.3x')
| -rw-r--r-- | upstream/mageia-cauldron/man3/curs_getch.3x | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3/curs_getch.3x b/upstream/mageia-cauldron/man3/curs_getch.3x new file mode 100644 index 00000000..fed7fa70 --- /dev/null +++ b/upstream/mageia-cauldron/man3/curs_getch.3x @@ -0,0 +1,454 @@ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 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.78 2024/02/17 19:27:03 tom Exp $ +.TH curs_getch 3X 2024-02-17 "ncurses 6.4" "Library calls" +.ie \n(.g \{\ +.ds `` \(lq +.ds '' \(rq +.\} +.el \{\ +.ie t .ds `` `` +.el .ds `` "" +.ie t .ds '' '' +.el .ds '' "" +.\} +. +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +\fB\%ungetch\fP, +\fB\%has_key\fP \- +get (or push back) characters from \fIcurses\fR terminal keyboard +.SH SYNOPSIS +.nf +.B #include <curses.h> +.PP +.B int getch(void); +.B int wgetch(WINDOW *\fIwin\fP); +.B int mvgetch(int \fIy\fP, int \fIx\fP); +.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP); +.PP +.B int ungetch(int \fIch\fP); +.PP +\fI/* extension */\fP +.B int has_key(int \fIch\fP); +.fi +.SH DESCRIPTION +.SS "Reading Characters" +The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read +a character from the window. +In no-delay mode, if no input is waiting, the value \fBERR\fP is returned. +In delay mode, the program waits until the system +passes text through to the program. +Depending on the setting of \fBcbreak\fP, +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 +If \fBecho\fP is enabled, and the window is not a pad, +then the character will also be echoed into the +designated window according to the following rules: +.bP +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\fP had been called. +.bP +If the character value is any other \fBKEY_\fP define, the user is alerted +with a \fBbeep\fP call. +.bP +If the character is a carriage-return, +and if \fBnl\fP is enabled, +it is translated to a line-feed after echoing. +.bP +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\fP, \fBwrefresh\fP will be called before another character +is read. +.SS "Keypad Mode" +If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for +that function key is returned instead of the raw characters: +.bP +The predefined function +keys are listed in \fB<curses.h>\fP as macros with values outside the range +of 8-bit characters. +Their names begin with \fBKEY_\fP. +.bP +Other (user-defined) function keys which may be defined +using \fBdefine_key\fP(3X) +have no names, but also are expected to have values outside the range of +8-bit characters. +.PP +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\fP 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 +In \fI\%ncurses\fP, the timer normally expires after +the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)). +If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire; +it is an infinite (or very large) value. +Because function keys usually begin with an escape character, +the terminal may appear to hang in notimeout mode after pressing the escape key +until another key is pressed. +.SS "Ungetting Characters" +The \fBungetch\fP routine places \fIch\fP back onto the input queue to be +returned by the next call to \fBwgetch\fP. +There is just one input queue for all windows. +.SS "Predefined Key Codes" +The following special keys are defined in \fB<curses.h>\fP. +.bP +Except for the special case \fBKEY_RESIZE\fP, +it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes. +.bP +Not all of these are necessarily supported on any particular terminal. +.bP +The naming convention may seem obscure, with some apparent +misspellings (such as \*(``RSUME\*('' for \*(``resume\*(''). +The names correspond to the long terminfo capability names for the keys, +and were defined long ago, in the 1980s. +.PP +.RS +.TS +tab(/) ; +l l . +\fBName\fP/\fBKey\fP \fBname\fP +_ +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\fP)/T{ +For 0 \(<= \fIn\fP \(<= 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 occurred +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 insert 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 +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 +.RE +.PP +Keypad is arranged like this: +.PP +.RS +.TS +allbox tab(/) ; +c c c . +\fBA1\fP/\fBup\fP/\fBA3\fP +\fBleft\fP/\fBB2\fP/\fBright\fP +\fBC1\fP/\fBdown\fP/\fBC3\fP +.TE +.RE +.sp +A few of these predefined values do \fInot\fP correspond to a real key: +.bP +.B KEY_RESIZE +is returned when the \fBSIGWINCH\fP signal has been detected +(see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X)). +This code is returned whether or not \fBkeypad\fP has been enabled. +.bP +.B KEY_MOUSE +is returned for mouse-events (see \fBcurs_mouse\fP(3X)). +This code relies upon whether or not \fBkeypad\fP(3X) has been enabled, +because +(e.g., +with \fBxterm\fP(1) mouse prototocol) +\fI\%ncurses\fP must read escape sequences, +just like a function key. +.SS "Testing Key Codes" +The \fBhas_key\fP routine takes a key-code value from the above list, and +returns \fBTRUE\fP or \fBFALSE\fP according to whether +the current terminal type recognizes a key with that value. +.PP +The library also supports these extensions: +.RS 3 +.TP 5 +.B define_key +defines a key-code for a given string (see \fBdefine_key\fP(3X)). +.TP 5 +.B key_defined +checks if there is a key-code defined for a given +string (see \fBkey_defined\fP(3X)). +.RE +.SH RETURN VALUE +All routines return the integer \fBERR\fP upon failure and an integer value +other than \fBERR\fP (\fBOK\fP in the case of \fBungetch\fP) upon successful +completion. +.RS 3 +.TP 5 +\fBungetch\fP +returns \fBERR\fP +if there is no more room in the FIFO. +.TP +\fBwgetch\fP +returns \fBERR\fP +.RS +.bP +if the window pointer is null, or +.bP +if its timeout expires without having any data, or +.bP +if the execution was interrupted by a signal (\fBerrno\fP will be set to +\fBEINTR\fP). +.RE +.RE +.PP +Functions with a \*(``mv\*('' prefix first perform a cursor movement using +\fBwmove\fP, and return an error if the position is outside the window, +or if the window pointer is null. +.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 +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. +\fI\%ncurses\fP uses the terminfo definition. +If it says that \fBKEY_ENTER\fP is control/M, +\fBgetch\fP will return \fBKEY_ENTER\fP +when you press control/M. +.PP +Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP +key on the numeric keypad: +.bP +the terminal description lists the most useful keys, +.bP +the \fIEnter\fP key on the regular keyboard is already handled by +the standard ASCII characters for carriage-return and line-feed, +.bP +depending on whether \fBnl\fP or \fBnonl\fP was called, +pressing \*(``Enter\*('' on the regular keyboard +may return either a carriage-return or line-feed, and finally +.bP +\*(``Enter or send\*('' is the standard description for this key. +.PP +When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or +\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode +(\fBecho\fP) 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\fP, \fBmvgetch\fP, and \fBmvwgetch\fP 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\fP, \fBKEY_DOWN\fP, +\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP, +\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12. +The Ins key +is usually mapped to \fBKEY_IC\fP. +.SH EXTENSIONS +\fB\%has_key\fP was designed for \fB\%ncurses\fP(3X), +and is not found in SVr4 +.IR curses , +4.4BSD +.IR curses , +or any other previous curses implementation. +.SH PORTABILITY +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +X/Open Curses, Issue 4, Version 2, describes +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +and +\fB\%ungetch\fP. +They read single-byte characters only. +The standard specifies that they return \fBERR\fP on failure, +but describes no failure conditions. +.PP +The echo behavior of these functions on input of +.B KEY_ +or backspace characters was not specified in the SVr4 documentation. +This description is adapted from X/Open Curses. +.PP +The behavior of \fBgetch\fP and friends in the presence of signal +handlers is unspecified in the SVr4 documentation and X/Open Curses. +Under historical curses implementations, +it varied depending on whether the operating system's dispatch of a +signal to a handler interrupts a \fBread\fP(2) call in progress or not, +and also +(in some implementations) +whether an input timeout or non-blocking mode has been set. +.PP +.B KEY_MOUSE +is mentioned in X/Open Curses, +along with a few related +.I \%term\%info +capabilities, +but no higher-level functions use the feature. +The implementation in +.I \%ncurses +is an extension. +.PP +.B KEY_RESIZE +is an extension first implemented for +.I \%ncurses. +NetBSD +.I curses +later added this extension. +.PP +Programmers concerned about portability should be prepared for either of two +cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt +interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to +\fBEINTR\fP. +.PP +The \fBhas_key\fP function is unique to \fI\%ncurses\fP. +We recommend that +any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro. +.SH SEE ALSO +\fB\%curses\fP(3X), +\fB\%curs_inopts\fP(3X), +\fB\%curs_mouse\fP(3X), +\fB\%curs_move\fP(3X), +\fB\%curs_outopts\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_variables\fP(3X), +\fB\%resizeterm\fP(3X) +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fB\%curs_get_wch\fP(3X). |