diff options
Diffstat (limited to 'doc/html/man/curs_getch.3x.html')
| -rw-r--r-- | doc/html/man/curs_getch.3x.html | 640 |
1 files changed, 341 insertions, 299 deletions
diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index b4e6c5cd5211..fd8a8909f3e7 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,7 +1,7 @@ -<!-- +<!-- * t **************************************************************************** - * Copyright 2018-2019,2020 Thomas E. Dickey * + * 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 * @@ -28,362 +28,403 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getch.3x,v 1.57 2020/12/19 21:38:20 tom Exp @ + * @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</TITLE> +<TITLE>curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> -<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + </HEAD> <BODY> -<H1 class="no-header">curs_getch 3x</H1> +<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> <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> +<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 <STRONG>curses</STRONG> terminal keyboard + 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>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>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG> - /* extension */ - <STRONG>int</STRONG> <STRONG>has_key(int</STRONG> <EM>ch</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> - The <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG> and <STRONG>mvwgetch</STRONG>, routines read a character from - the window. In no-delay mode, if no input is waiting, the value <STRONG>ERR</STRONG> is - returned. In delay mode, the program waits until the system passes - text through to the program. Depending on the setting of <STRONG>cbreak</STRONG>, this - is after one character (cbreak mode), or after the first newline - (nocbreak mode). In half-delay mode, the program waits until a charac- - ter is typed or the specified timeout has been reached. - - If <STRONG>echo</STRONG> is enabled, and the window is not a pad, then the character - will also be echoed into the designated window according to the follow- - ing rules: - - <STRONG>o</STRONG> 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 <STRONG>delch</STRONG> had been called. - - <STRONG>o</STRONG> If the character value is any other <STRONG>KEY_</STRONG> define, the user is alert- - ed with a <STRONG>beep</STRONG> call. - - <STRONG>o</STRONG> If the character is a carriage-return, and if <STRONG>nl</STRONG> is enabled, it is - translated to a line-feed after echoing. - - <STRONG>o</STRONG> Otherwise the character is simply output to the screen. - - If the window is not a pad, and it has been moved or modified since the - last call to <STRONG>wrefresh</STRONG>, <STRONG>wrefresh</STRONG> will be called before another character - is read. - - -</PRE><H3><a name="h3-Keypad-mode">Keypad mode</a></H3><PRE> - If <STRONG>keypad</STRONG> is <STRONG>TRUE</STRONG>, and a function key is pressed, the token for that - function key is returned instead of the raw characters: - - <STRONG>o</STRONG> The predefined function keys are listed in <STRONG><curses.h></STRONG> as macros - with values outside the range of 8-bit characters. Their names be- - gin with <STRONG>KEY_</STRONG>. - - <STRONG>o</STRONG> Other (user-defined) function keys which may be defined using <STRONG>de-</STRONG> - <STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG> have no names, but also are expected to have values - outside the range of 8-bit characters. - - 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 re- - ceived (which, on modern terminals, means an escape character), <STRONG>curses</STRONG> - 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 expe- - rience a delay between the time a user presses the escape key and the - escape is returned to the program. - - In <STRONG>ncurses</STRONG>, the timer normally expires after the value in <STRONG>ESCDELAY</STRONG> (see - <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). If <STRONG>notimeout</STRONG> is <STRONG>TRUE</STRONG>, 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 no- - timeout mode after pressing the escape key until another key is - pressed. - - -</PRE><H3><a name="h3-Ungetting-characters">Ungetting characters</a></H3><PRE> - The <STRONG>ungetch</STRONG> routine places <EM>ch</EM> back onto the input queue to be returned - by the next call to <STRONG>wgetch</STRONG>. There is just one input queue for all win- - dows. - - -</PRE><H3><a name="h3-Predefined-key-codes">Predefined key-codes</a></H3><PRE> - The following special keys are defined in <STRONG><curses.h></STRONG>. - - <STRONG>o</STRONG> Except for the special case <STRONG>KEY_RESIZE</STRONG>, it is necessary to enable - <STRONG>keypad</STRONG> for <STRONG>getch</STRONG> to return these codes. - - <STRONG>o</STRONG> Not all of these are necessarily supported on any particular termi- - nal. - - <STRONG>o</STRONG> The naming convention may seem obscure, with some apparent mis- - spellings (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. - - <EM>Name</EM> <EM>Key</EM> <EM>name</EM> - ------------------------------------------------- - 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(<EM>n</EM>) For 0 <= <EM>n</EM> <= 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) - 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 - - Keypad is arranged like this: - - +-----+------+-------+ - | <STRONG>A1</STRONG> | <STRONG>up</STRONG> | <STRONG>A3</STRONG> | - +-----+------+-------+ - |<STRONG>left</STRONG> | <STRONG>B2</STRONG> | <STRONG>right</STRONG> | - +-----+------+-------+ - | <STRONG>C1</STRONG> | <STRONG>down</STRONG> | <STRONG>C3</STRONG> | - +-----+------+-------+ - A few of these predefined values do <EM>not</EM> correspond to a real key: - - <STRONG>o</STRONG> <STRONG>KEY_RESIZE</STRONG> is returned when the <STRONG>SIGWINCH</STRONG> signal has been detected - (see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>). This code is returned - whether or not <STRONG>keypad</STRONG> has been enabled. - - <STRONG>o</STRONG> <STRONG>KEY_MOUSE</STRONG> is returned for mouse-events (see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>). This - code relies upon whether or not <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> has been enabled, be- - cause (e.g., with <EM>xterm</EM> mouse prototocol) ncurses must read escape - sequences, just like a function key. - - -</PRE><H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE> - The <STRONG>has_key</STRONG> routine takes a key-code value from the above list, and re- - turns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the current terminal type rec- - ognizes a key with that value. - - The library also supports these extensions: - - <STRONG>define_key</STRONG> - defines a key-code for a given string (see <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>). - - <STRONG>key_defined</STRONG> - checks if there is a key-code defined for a given string (see - <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>). +</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> - All routines return the integer <STRONG>ERR</STRONG> upon failure and an integer value - other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of <STRONG>ungetch</STRONG>) upon successful completion. + 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>ungetch</STRONG> - returns <STRONG>ERR</STRONG> if there is no more room in the FIFO. + <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set + to <STRONG>EINTR</STRONG>. - <STRONG>wgetch</STRONG> - returns <STRONG>ERR</STRONG> if the window pointer is null, or if its timeout - expires without having any data, or if the execution was inter- - rupted by a signal (<STRONG>errno</STRONG> will be set to <STRONG>EINTR</STRONG>). + <STRONG>ungetch</STRONG> fails if there is no more room in the input queue. - Functions with a "mv" prefix first perform a cursor movement using - <STRONG>wmove</STRONG>, and return an error if the position is outside the window, or if - the window pointer is null. + <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - 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. + <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 keys may be the same as commonly used control keys, e.g., <STRONG>KEY_EN-</STRONG> - <STRONG>TER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> versus control/H. Some curses im- - plementations may differ according to whether they treat these control - keys specially (and ignore the terminfo), or use the terminfo defini- - tions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says that <STRONG>KEY_EN-</STRONG> - <STRONG>TER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG> when you press control/M. + 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. - Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the <EM>Enter</EM> key on - the numeric keypad: + <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 terminal description lists the most useful keys, + <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> the <EM>Enter</EM> key on the regular keyboard is already handled by the - standard ASCII characters for carriage-return and line-feed, + <STRONG>o</STRONG> "Enter or send" is X/Open Curses's description of this key. - <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing "Enter" on the - regular keyboard may return either a carriage-return or line-feed, - and finally + <EM>curses</EM> treats the Enter or Return key in the <EM>alphabetic</EM> section of the + keyboard differently. - <STRONG>o</STRONG> "Enter or send" is the standard description for this key. + <STRONG>o</STRONG> It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line + feed (<STRONG>^J</STRONG>). - When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak mode - (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) 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. + <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. - Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros. + 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 set of keypad macros was largely defined by the ex- - tremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Sa- - fari 4. Modern personal computers usually have only a small subset of - these. IBM PC-style consoles typically support little more than - <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_NPAGE</STRONG>, - <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The Ins key is usually - mapped to <STRONG>KEY_IC</STRONG>. + 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> - The *get* functions are described in the XSI Curses standard, Issue 4. - They read single-byte characters only. The standard specifies that - they return <STRONG>ERR</STRONG> on failure, but specifies no error conditions. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or backspace - characters was not specified in the SVr4 documentation. This descrip- - tion is adopted from the XSI Curses standard. + 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. - The behavior of <STRONG>getch</STRONG> 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 <STRONG>read(2)</STRONG> - call in progress or not, and also (in some implementations) depending - on whether an input timeout or non-blocking mode has been set. + <STRONG>wgetch</STRONG> reads only single-byte characters. - <STRONG>KEY_MOUSE</STRONG> is mentioned in XSI Curses, along with a few related terminfo - capabilities, but no higher-level functions use the feature. The im- - plementation in ncurses is an extension. + 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. - <STRONG>KEY_RESIZE</STRONG> is an extension first implemented for ncurses. NetBSD curs- - es later added this extension. + 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>. - Programmers concerned about portability should be prepared for either - of two cases: (a) signal receipt does not interrupt <STRONG>getch</STRONG>; (b) signal - receipt interrupts <STRONG>getch</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. - The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend that any code - using it be conditionalized on the <STRONG>NCURSES_VERSION</STRONG> feature macro. + <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="ncurses.3x.html">curses(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>curs_out-</STRONG> - <STRONG><A HREF="curs_outopts.3x.html">opts(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><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/> - Comparable functions in the wide-character (ncursesw) library are de- - scribed in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>. + ECMA-48 "Control Functions for Coded Character Sets" <https:// + ecma-international.org/publications-and-standards/standards/ecma-48/> - <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> +ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -391,15 +432,16 @@ <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> +<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> |