| <!-- |
| * 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.87 2024/04/20 19:18:18 tom Exp @ |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
| <HTML> |
| <HEAD> |
| <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> |
| <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> |
| <TITLE>curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> |
| <link rel="author" href="mailto:bug-ncurses@gnu.org"> |
| |
| </HEAD> |
| <BODY> |
| <H1 class="no-header">curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</H1> |
| <PRE> |
| <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> |
| |
| |
| |
| |
| </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> |
| <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get (or push back) |
| characters from <EM>curses</EM> terminal keyboard |
| |
| |
| </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> |
| <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>getch(void);</STRONG> |
| <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> |
| <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> |
| |
| <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG> |
| |
| <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> |
| <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>c</EM><STRONG>);</STRONG> |
| |
| |
| </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> |
| |
| </PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE> |
| <STRONG>wgetch</STRONG> gathers a key stroke from the terminal keyboard associated with |
| a <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this |
| function. |
| |
| When input is pending, <STRONG>wgetch</STRONG> returns an integer identifying the key |
| stroke; for alphanumeric and punctuation keys, this value corresponds |
| to the character encoding used by the terminal. Use of the control key |
| as a modifier often results in a distinct code. The behavior of other |
| keys depends on whether <EM>win</EM> is in keypad mode; see subsection "Keypad |
| Mode" below. |
| |
| If no input is pending, then if the no-delay flag is set in the window |
| (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits |
| until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this |
| happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called, |
| it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been |
| called, <EM>curses</EM> waits until a character is typed or the specified delay |
| elapses. |
| |
| If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes |
| the returned character <EM>c</EM> to the window (at the cursor position) per the |
| following rules. |
| |
| <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves |
| leftward one position and the new position is erased as if |
| <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's |
| keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are |
| handled the same way. |
| |
| <STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>c</EM> to the window, as with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>. |
| |
| <STRONG>o</STRONG> If the window has been moved or modified since the last call to |
| <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>. |
| |
| If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns |
| the character code for line feed instead. |
| |
| |
| </PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE> |
| To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard |
| (those corresponding to the ECMA-6 character set--see |
| <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are |
| treated as <EM>function</EM> keys. (In <EM>curses</EM>, the term "function key" includes |
| but is not limited to keycaps engraved with "F1", "PF1", and so on.) |
| If the window is in keypad mode, these produce a numeric code |
| corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined Key |
| Codes" below; otherwise, they transmit a sequence of codes typically |
| starting with the escape character, and which must be collected with |
| multiple <STRONG>wgetch</STRONG> calls. |
| |
| <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM> |
| whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values |
| outside the range of eight-bit character codes. |
| |
| <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with |
| <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected to have |
| values outside the range of eight-bit codes. |
| |
| A variable intended to hold a function key code must thus be of type |
| <EM>short</EM> or larger. |
| |
| Most terminals one encounters follow the ECMA-48 standard insofar as |
| their function keys produce character sequences prefixed with the |
| escape character ESC. This fact implies that <EM>curses</EM> cannot know |
| whether the terminal has sent an ESC key stroke or the beginning of a |
| function key's character sequence without waiting to see if, and how |
| soon, further input arrives. When <EM>curses</EM> reads such an ambiguous |
| character, it sets a timer. If the remainder of the sequence does not |
| arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix character; |
| otherwise, it returns the function key code corresponding to the unique |
| sequence defined by the terminal. Consequently, a user of a <EM>curses</EM> |
| application may experience a delay after pressing ESC while <EM>curses</EM> |
| disambiguates the input; see section "EXTENSIONS" below. If the window |
| is in "no time-out" mode, the timer does not expire; it is an infinite |
| (or very large) value. See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. Because function key |
| sequences usually begin with an escape character, the terminal may |
| appear to hang in no time-out mode after the user has pressed ESC. |
| Generally, further typing "awakens" <EM>curses</EM>. |
| |
| |
| </PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE> |
| <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call |
| to <STRONG>wgetch</STRONG>. A single input queue serves all windows. |
| |
| |
| </PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE> |
| The header file <EM>curses.h</EM> defines the following function key codes. |
| |
| <STRONG>o</STRONG> Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's keypad mode |
| must be enabled for <STRONG>wgetch</STRONG> to read these codes from it. |
| |
| <STRONG>o</STRONG> Not all of these are necessarily supported on any particular |
| terminal. |
| |
| <STRONG>o</STRONG> The naming convention may seem obscure, with some apparent |
| misspellings (such as "RSUME" for "resume"); the names correspond |
| to the <EM>terminfo</EM> capability names for the keys, and were |
| standardized before the IBM PC/AT keyboard layout achieved a |
| dominant position in industry. |
| |
| <STRONG>Symbol</STRONG> <STRONG>Key</STRONG> <STRONG>name</STRONG> |
| ----------------------------------------------------------------- |
| <STRONG>KEY_BREAK</STRONG> Break key |
| <STRONG>KEY_DOWN</STRONG> |
| <STRONG>KEY_UP</STRONG> Arrow keys |
| <STRONG>KEY_LEFT</STRONG> |
| <STRONG>KEY_RIGHT</STRONG> |
| <STRONG>KEY_HOME</STRONG> Home key (upward+left arrow) |
| <STRONG>KEY_BACKSPACE</STRONG> Backspace |
| <STRONG>KEY_F0</STRONG> Function keys; space for 64 keys is reserved |
| <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> Function key <EM>n</EM> where 0 <= <EM>n</EM> <= 63 |
| |
| <STRONG>KEY_DL</STRONG> Delete line |
| <STRONG>KEY_IL</STRONG> Insert line |
| <STRONG>KEY_DC</STRONG> Delete character |
| <STRONG>KEY_IC</STRONG> Insert character/Enter insert mode |
| <STRONG>KEY_EIC</STRONG> Exit insert character mode |
| <STRONG>KEY_CLEAR</STRONG> Clear screen |
| <STRONG>KEY_EOS</STRONG> Clear to end of screen |
| <STRONG>KEY_EOL</STRONG> Clear to end of line |
| <STRONG>KEY_SF</STRONG> Scroll one line forward |
| <STRONG>KEY_SR</STRONG> Scroll one line backward (reverse) |
| <STRONG>KEY_NPAGE</STRONG> Next page/Page up |
| <STRONG>KEY_PPAGE</STRONG> Previous page/Page down |
| <STRONG>KEY_STAB</STRONG> Set tab |
| <STRONG>KEY_CTAB</STRONG> Clear tab |
| <STRONG>KEY_CATAB</STRONG> Clear all tabs |
| <STRONG>KEY_ENTER</STRONG> Enter/Send |
| <STRONG>KEY_SRESET</STRONG> Soft (partial) reset |
| <STRONG>KEY_RESET</STRONG> (Hard) reset |
| <STRONG>KEY_PRINT</STRONG> Print/Copy |
| <STRONG>KEY_LL</STRONG> Home down/Bottom (lower left) |
| <STRONG>KEY_A1</STRONG> Upper left of keypad |
| <STRONG>KEY_A3</STRONG> Upper right of keypad |
| <STRONG>KEY_B2</STRONG> Center of keypad |
| <STRONG>KEY_C1</STRONG> Lower left of keypad |
| <STRONG>KEY_C3</STRONG> Lower right of keypad |
| <STRONG>KEY_BTAB</STRONG> Back tab key |
| <STRONG>KEY_BEG</STRONG> Beg(inning) key |
| <STRONG>KEY_CANCEL</STRONG> Cancel key |
| <STRONG>KEY_CLOSE</STRONG> Close key |
| <STRONG>KEY_COMMAND</STRONG> Cmd (command) key |
| <STRONG>KEY_COPY</STRONG> Copy key |
| <STRONG>KEY_CREATE</STRONG> Create key |
| <STRONG>KEY_END</STRONG> End key |
| <STRONG>KEY_EXIT</STRONG> Exit key |
| <STRONG>KEY_FIND</STRONG> Find key |
| <STRONG>KEY_HELP</STRONG> Help key |
| <STRONG>KEY_MARK</STRONG> Mark key |
| <STRONG>KEY_MESSAGE</STRONG> Message key |
| <STRONG>KEY_MOUSE</STRONG> Mouse event occurred |
| <STRONG>KEY_MOVE</STRONG> Move key |
| <STRONG>KEY_NEXT</STRONG> Next object key |
| <STRONG>KEY_OPEN</STRONG> Open key |
| <STRONG>KEY_OPTIONS</STRONG> Options key |
| <STRONG>KEY_PREVIOUS</STRONG> Previous object key |
| <STRONG>KEY_REDO</STRONG> Redo key |
| <STRONG>KEY_REFERENCE</STRONG> Ref(erence) key |
| <STRONG>KEY_REFRESH</STRONG> Refresh key |
| <STRONG>KEY_REPLACE</STRONG> Replace key |
| <STRONG>KEY_RESIZE</STRONG> Screen resized |
| <STRONG>KEY_RESTART</STRONG> Restart key |
| <STRONG>KEY_RESUME</STRONG> Resume key |
| <STRONG>KEY_SAVE</STRONG> Save key |
| <STRONG>KEY_SELECT</STRONG> Select key |
| <STRONG>KEY_SUSPEND</STRONG> Suspend key |
| <STRONG>KEY_UNDO</STRONG> Undo key |
| ----------------------------------------------------------------- |
| <STRONG>KEY_SBEG</STRONG> Shifted beginning key |
| <STRONG>KEY_SCANCEL</STRONG> Shifted cancel key |
| <STRONG>KEY_SCOMMAND</STRONG> Shifted command key |
| <STRONG>KEY_SCOPY</STRONG> Shifted copy key |
| <STRONG>KEY_SCREATE</STRONG> Shifted create key |
| <STRONG>KEY_SDC</STRONG> Shifted delete character key |
| <STRONG>KEY_SDL</STRONG> Shifted delete line key |
| <STRONG>KEY_SEND</STRONG> Shifted end key |
| <STRONG>KEY_SEOL</STRONG> Shifted clear line key |
| |
| <STRONG>KEY_SEXIT</STRONG> Shifted exit key |
| <STRONG>KEY_SFIND</STRONG> Shifted find key |
| <STRONG>KEY_SHELP</STRONG> Shifted help key |
| <STRONG>KEY_SHOME</STRONG> Shifted home key |
| <STRONG>KEY_SIC</STRONG> Shifted insert key |
| <STRONG>KEY_SLEFT</STRONG> Shifted left arrow key |
| <STRONG>KEY_SMESSAGE</STRONG> Shifted message key |
| <STRONG>KEY_SMOVE</STRONG> Shifted move key |
| <STRONG>KEY_SNEXT</STRONG> Shifted next object key |
| <STRONG>KEY_SOPTIONS</STRONG> Shifted options key |
| <STRONG>KEY_SPREVIOUS</STRONG> Shifted previous object key |
| <STRONG>KEY_SPRINT</STRONG> Shifted print key |
| <STRONG>KEY_SREDO</STRONG> Shifted redo key |
| <STRONG>KEY_SREPLACE</STRONG> Shifted replace key |
| <STRONG>KEY_SRIGHT</STRONG> Shifted right arrow key |
| <STRONG>KEY_SRSUME</STRONG> Shifted resume key |
| <STRONG>KEY_SSAVE</STRONG> Shifted save key |
| <STRONG>KEY_SSUSPEND</STRONG> Shifted suspend key |
| <STRONG>KEY_SUNDO</STRONG> Shifted undo key |
| |
| Many keyboards feature a nine-key directional pad. |
| |
| +-----+------+-------+ |
| | A1 | up | A3 | |
| +-----+------+-------+ |
| |left | B2 | right | |
| +-----+------+-------+ |
| | C1 | down | C3 | |
| +-----+------+-------+ |
| Two of the symbols in the list above do <EM>not</EM> correspond to a physical |
| key. |
| |
| <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_RESIZE</STRONG>, even if the window's keypad mode is |
| disabled, when <EM>ncurses</EM> handles a <STRONG>SIGWINCH</STRONG> signal; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> |
| and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>. |
| |
| <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending |
| collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. Receipt of this code requires a |
| window's keypad mode to be enabled, because to interpret mouse |
| input (as with with <STRONG>xterm(1)</STRONG>'s mouse prototocol), <EM>ncurses</EM> must read |
| an escape sequence, as with a function key. |
| |
| |
| </PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE> |
| In <EM>ncurses</EM>, <STRONG>has_key</STRONG> returns a Boolean value indicating whether the |
| terminal type recognizes its parameter as a key code value. See also |
| <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> and <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>. |
| |
| |
| </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> |
| Except for <STRONG>has_key</STRONG>, these functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on |
| failure. |
| |
| Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. |
| |
| Functions prefixed with "mv" first perform cursor movement and fail if |
| the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. |
| |
| <STRONG>wgetch</STRONG> also fails if |
| |
| <STRONG>o</STRONG> its timeout expires without any data arriving, or |
| |
| <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set |
| to <STRONG>EINTR</STRONG>. |
| |
| <STRONG>ungetch</STRONG> fails if there is no more room in the input queue. |
| |
| <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. |
| |
| |
| </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> |
| <EM>curses</EM> discourages assignment of the ESC key to a discrete function by |
| the programmer because the library requires a delay while it awaits the |
| potential remainder of a terminal escape sequence. |
| |
| Some key strokes are indistinguishable from control characters; for |
| example, <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the |
| same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>. Consult the terminal's <EM>terminfo</EM> entry to determine |
| whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>. Some <EM>curses</EM> implementations, |
| including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions; others treat |
| such control characters specially. |
| |
| <EM>curses</EM> distinguishes the Enter keys in the alphabetic and numeric |
| keypad sections of a keyboard because (most) terminals do. <STRONG>KEY_ENTER</STRONG> |
| refers to the key on the numeric keypad and, like other function keys, |
| and is reliably recognized only if the window's keypad mode is enabled. |
| |
| <STRONG>o</STRONG> The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability describes the character |
| (sequence) sent by the Enter key of a terminal's numeric (or |
| similar) keypad. |
| |
| <STRONG>o</STRONG> "Enter or send" is X/Open Curses's description of this key. |
| |
| <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of the |
| keyboard differently. |
| |
| <STRONG>o</STRONG> It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line |
| feed (<STRONG>^J</STRONG>). |
| |
| <STRONG>o</STRONG> Depending on the terminal mode (raw, cbreak, or "cooked"), and |
| whether <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> may return |
| either a carriage return or line feed upon an Enter or Return key |
| stroke. |
| |
| Use of <STRONG>wgetch</STRONG> with <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> and neither <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> nor <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> is not |
| well-defined. |
| |
| Historically, the list of key code macros above was influenced by the |
| function-key-rich keyboard of the AT&T 7300 (also known variously as |
| the "3B1", "Safari 4", and "UNIX PC"), a 1985 machine. Today's |
| computer keyboards are based that of the IBM PC/AT and tend to have |
| fewer. A <EM>curses</EM> application can expect such a keyboard to transmit key |
| codes <STRONG>KEY_UP</STRONG>, <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>, |
| <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page Down), <STRONG>KEY_IC</STRONG> (Insert), <STRONG>KEY_DC</STRONG> |
| (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 <= <EM>n</EM> <= 12. |
| |
| <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros. |
| |
| |
| </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> |
| In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG> |
| variable configures the duration of the timer used to disambiguate a |
| function key character sequence from a series of key strokes beginning |
| with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. |
| |
| <STRONG>has_key</STRONG> was designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and is not found in SVr4 <EM>curses</EM>, |
| 4.4BSD <EM>curses</EM>, or any other previous curses implementation. |
| |
| |
| </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> |
| Applications employing <EM>ncurses</EM> extensions should condition their use on |
| the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. |
| |
| X/Open Curses, Issue 4 describes <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, and |
| <STRONG>ungetch</STRONG>. It specifies no error conditions for them. |
| |
| <STRONG>wgetch</STRONG> reads only single-byte characters. |
| |
| The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or backspace |
| characters was not specified in the SVr4 documentation. This |
| description is adapted from X/Open Curses. |
| |
| The behavior of <STRONG>wgetch</STRONG> in the presence of signal handlers is |
| unspecified in the SVr4 documentation and X/Open Curses. In historical |
| <EM>curses</EM> implementations, it varied depending on whether the operating |
| system's dispatch of a signal to a handler interrupting a <STRONG>read(2)</STRONG> call |
| in progress, and also (in some implementations) whether an input |
| timeout or non-blocking mode has been set. Programmers concerned about |
| portability should be prepared for either of two cases: (a) signal |
| receipt does not interrupt <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts |
| <STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. |
| |
| <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM> |
| <EM>info</EM> capabilities, but no higher-level functions use the feature. The |
| implementation in <EM>ncurses</EM> is an extension. |
| |
| <STRONG>KEY_RESIZE</STRONG> and <STRONG>has_key</STRONG> are extensions first implemented for <EM>ncurses</EM>. |
| By 2022, <EM>PDCurses</EM> and NetBSD <EM>curses</EM> had added them along with |
| <STRONG>KEY_MOUSE</STRONG>. |
| |
| |
| </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> |
| <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library |
| in its wide-character configuration (<EM>ncursesw</EM>). |
| |
| <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, |
| <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, |
| <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG> |
| |
| ECMA-6 "7-bit coded Character Set" <https://ecma-international.org/ |
| publications-and-standards/standards/ecma-6/> |
| |
| ECMA-48 "Control Functions for Coded Character Sets" <https:// |
| ecma-international.org/publications-and-standards/standards/ecma-48/> |
| |
| |
| |
| ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> |
| </PRE> |
| <div class="nav"> |
| <ul> |
| <li><a href="#h2-NAME">NAME</a></li> |
| <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> |
| <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> |
| <ul> |
| <li><a href="#h3-Reading-Characters">Reading Characters</a></li> |
| <li><a href="#h3-Keypad-Mode">Keypad Mode</a></li> |
| <li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li> |
| <li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li> |
| <li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li> |
| </ul> |
| </li> |
| <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> |
| <li><a href="#h2-NOTES">NOTES</a></li> |
| <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> |
| <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> |
| <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> |
| </ul> |
| </div> |
| </BODY> |
| </HTML> |