+ wgetch gathers a key event from the terminal keyboard associated with a
+ curses window win. ncurses(3x) describes the variants of this
+ function.
+
+ When input is pending, wgetch returns an integer identifying the key
+ event; for alphanumeric and punctuation keys, this value corresponds to
+ the character encoding used by the terminal. Use of the control key as
+ a modifier, by holding it down while pressing and releasing another
+ key, often results in a distinct code. The behavior of other keys
+ depends on whether win 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 nodelay(3x)), the function returns ERR; otherwise, curses waits
+ until the terminal has input. If cbreak(3x) has been called, this
+ happens after one character is read. If nocbreak(3x) has been called,
+ it occurs when the next newline is read. If halfdelay(3x) has been
+ called, curses waits until input is available or the specified delay
+ elapses.
+
+ If echo(3x) has been called, and the window is not a pad, curses writes
+ the returned character c to the window (at the cursor position) per the
+ following rules.
+
+ o If c matches the terminal's erase character, the cursor moves
+ leftward one position and the new position is erased as if
+ wmove(3x) and then wdelch(3x) were called. When the window's
+ keypad mode is enabled (see below), KEY_LEFT and KEY_BACKSPACE are
+ handled the same way.
+
+ ocurses writes any other c to the window, as with wechochar(3x).
+
+ o If the window win has been moved or modified since the last call to
+ wrefresh(3x), curses calls wrefresh on it.
+
+ If c is a carriage return and nl(3x) has been called, wgetch returns
+ the character code for line feed instead.
+
+
+
+ To curses, key strokes not from the alphabetic section of the keyboard
+ (those corresponding to the ECMA-6 character set--see
+ ascii(7)--optionally modified by either the control or shift keys) are
+ treated as function keys. (In curses, 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 KEY_ 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 wgetch calls.
+
+ o The curses.h header file declares many predefinedfunctionkeys
+ whose names begin with KEY_; these object-like macros have values
+ outside the range of eight-bit character codes.
+
+ o In ncurses, user-definedfunctionkeys are configured with
+ define_key(3x); 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
+ short 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 curses cannot distinguish
+ a user's press of the escape key (assuming it sends ESC) from the
+ beginning of a function key's character sequence without waiting to see
+ if, and how soon, further input arrives. When curses reads such an
+ ambiguous character, it sets a timer. If the remainder of the sequence
+ does not arrive within the designated time, wgetch 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
+ curses application may experience a delay after they escape key is
+ pressed while curses 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 notimeout(3x).
+ Because function key sequences usually begin with ESC, the terminal may
+ appear to hang in no time-out mode after the user presses the escape
+ key. Generally, further typing "awakens" curses.
+
+
+
+ ungetch places c into the input queue to be returned by the next call
+ to wgetch. A single input queue serves all windows associated with the
+ terminal.
+
+
+
+ The header file curses.h defines the following function key codes.
+
+ o Except for the special case of KEY_RESIZE, a window's keypad mode
+ must be enabled for wgetch to read these codes from it.
+
+ o Not all of these are necessarily supported on any particular
+ terminal.
+
+ o The naming convention may seem obscure, with some apparent
+ misspellings (such as "RSUME" for "resume"); the names correspond
+ to the terminfo capability names for the keys, and were
+ standardized before the IBM PC/AT keyboard layout achieved a
+ dominant position in industry.
+
+ SymbolKeyname
+ -----------------------------------------------------------------
+ KEY_BREAK Break key
+ KEY_DOWN
+ KEY_UP Arrow keys
+ 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(n) Function key n where 0 <= n <= 63
+ KEY_DL Delete line
+ KEY_IL Insert line
+ KEY_DC Delete character
+ KEY_IC Insert character/Enter insert mode
+ KEY_EIC Exit insert character mode
+ KEY_CLEAR Clear screen
+ KEY_EOS Clear to end of screen
+ KEY_EOL Clear to end of line
+ KEY_SF Scroll one line forward
+ KEY_SR Scroll one line backward (reverse)
+ KEY_NPAGE Next page/Page up
+ KEY_PPAGE Previous page/Page down
+ KEY_STAB Set tab
+ KEY_CTAB Clear tab
+ KEY_CATAB Clear all tabs
+ KEY_ENTER Enter/Send
+ KEY_SRESET Soft (partial) reset
+ KEY_RESET (Hard) reset
+ KEY_PRINT Print/Copy
+ KEY_LL Home down/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_SELECT Select key
+ KEY_SUSPEND Suspend key
+ KEY_UNDO Undo 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 character key
+ KEY_SDL Shifted delete line 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 object key
+ KEY_SOPTIONS Shifted options key
+ KEY_SPREVIOUS Shifted previous object 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
+
+ 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 not correspond to a physical
+ key.
+
+ owgetch returns KEY_RESIZE, even if the window's keypad mode is
+ disabled, when ncurses handles a SIGWINCH signal; see initscr(3x)
+ and resizeterm(3x).
+
+ owgetch returns KEY_MOUSE to indicate that a mouse event is pending
+ collection; see curs_mouse(3x). Receipt of this code requires a
+ window's keypad mode to be enabled, because to interpret mouse
+ input (as with with xterm(1)'s mouse protocol), ncurses must read
+ an escape sequence, as with a function key.
+
+
+
+ In ncurses, has_key returns a Boolean value indicating whether the
+ terminal type recognizes its parameter as a key code value. See also
+ define_key(3x) and key_defined(3x).
+
+
+
+ Except for has_key, these functions return OK on success and ERR on
+ failure.
+
+ Functions taking a WINDOW pointer argument fail if the pointer is NULL.
+
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
+
+ wgetch also fails if
+
+ o its timeout expires without any data arriving, or
+
+ o execution was interrupted by a signal, in which case errno is set
+ to EINTR.
+
+ ungetch fails if there is no more room in the input queue.
+
+ has_key returns TRUE or FALSE.
+
+
+
+ curses 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, KEY_ENTER may be the same as ^M, and KEY_BACKSPACE may be the
+ same as ^H or ^?. Consult the terminfo entry for the terminal type to
+ determine whether this is the case; see infocmp(1). Some curses
+ implementations, including ncurses, honor the terminfo key definitions;
+ others treat such control characters specially.
+
+ curses distinguishes the Enter keys in the alphabetic and numeric
+ keypad sections of a keyboard because (most) terminals do. KEY_ENTER
+ refers to the key on the numeric keypad and, like other function keys,
+ is reliably recognized only if the window's keypad mode is enabled.
+
+ o The terminfokey_enter (kent) capability describes the character
+ (sequence) sent by the Enter key of a terminal's numeric (or
+ similar) keypad.
+ o "Enter or send" is X/Open Curses's description of this key.
-
-
DESCRIPTION
- The getch, wgetch, mvgetch and mvwgetch, routines read a
- character from the window. In no-delay mode, if no input
- is waiting, the value ERR is returned. In delay mode, the
- program waits until the system passes text through to the
- program. Depending on the setting of cbreak, this is af-
- ter one character (cbreak mode), or after the first new-
- line (nocbreak mode). In half-delay mode, the program
- waits until a character is typed or the specified timeout
- has been reached.
-
- Unless noecho has been set, then the character will also
- be echoed into the designated window according to the fol-
- lowing rules: If the character is the current erase char-
- acter, left arrow, or backspace, the cursor is moved one
- space to the left and that screen position is erased as if
- delch had been called. If the character value is any oth-
- er KEY_ define, the user is alerted with a beep call.
- Otherwise the character is simply output to the screen.
-
- If the window is not a pad, and it has been moved or modi-
- fied since the last call to wrefresh, wrefresh will be
- called before another character is read.
-
- If keypad is TRUE, and a function key is pressed, the to-
- ken for that function key is returned instead of the raw
- characters. Possible function keys are defined in <curs-
- es.h> as macros with values outside the range of 8-bit
- characters whose names begin with KEY_. 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 es-
- cape character), curses 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 es-
- cape key and the escape is returned to the program.
-
- The ungetch routine places ch back onto the input queue to
- be returned by the next call to wgetch. There is just one
- input queue for all windows.
-
-
- FunctionKeys
- The following function keys, defined in <curses.h>, might
- be returned by getch if keypad has been enabled. Note
- that not all of these are necessarily supported on any
- particular terminal.
-
-
- NameKeyname
- 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(n) For 0 <= n <= 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:
-
-
- +-----+------+-------+
- | A1 | up | A3 |
- +-----+------+-------+
- |left | B2 | right |
- +-----+------+-------+
- | C1 | down | C3 |
- +-----+------+-------+
- The has_key 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.,
- KEY_RESIZE and KEY_MOUSE. See resizeterm(3x) for more de-
- tails about KEY_RESIZE, and curs_mouse(3x) for a discus-
- sion of KEY_MOUSE.
+ curses treats the Enter or Return key in the alphabetic section of the
+ keyboard differently.
+ o It usually produces a control code for carriage return (^M) or line
+ feed (^J).
+ o Depending on the terminal mode (raw, cbreak, or "cooked"), and
+ whether nl(3x) or nonl(3x) has been called, wgetch may return
+ either a carriage return or line feed upon an Enter or Return key
+ stroke.
-
-
RETURN VALUE
- All routines return the integer ERR upon failure and an
- integer value other than ERR (OK in the case of ungetch())
- upon successful completion.
+ Use of wgetch with echo(3x) and neither cbreak(3x) nor raw(3x) is not
+ well-defined.
- ungetch
- returns an error if there is no more room in
- the FIFO.
+ 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 curses application can expect such a keyboard to transmit key
+ codes KEY_UP, KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END,
+ KEY_PPAGE (Page Up), KEY_NPAGE (Page Down), KEY_IC (Insert), KEY_DC
+ (Delete), and KEY_F(n) for 1 <= n <= 12.
- wgetch
- returns an error if the window pointer is
- null, or if its timeout expires without having
- any data.
+ getch, mvgetch, and mvwgetch may be implemented as macros.
-
-
NOTES
- Use of the escape key by a programmer for a single charac-
- ter function is discouraged, as it will cause a delay of
- up to one second while the keypad code looks for a follow-
- ing function-key sequence.
-
- Note that some keys may be the same as commonly used con-
- trol keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE
- versus control/H. Some curses implementations may differ
- according to whether they treat these control keys spe-
- cially (and ignore the terminfo), or use the terminfo def-
- initions. Ncurses uses the terminfo definition. If it
- says that KEY_ENTER is control/M, getch will return
- KEY_ENTER when you press control/M.
-
- When using getch, wgetch, mvgetch, or mvwgetch, nocbreak
- mode (nocbreak) and echo mode (echo) 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 un-
- desirable results.
-
- Note that getch, mvgetch, and mvwgetch 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 KEY_UP,
- KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END,
- KEY_NPAGE, KEY_PPAGE, and function keys 1 through 12. The
- Ins key is usually mapped to KEY_IC.
+
+ In ncurses, when a window's "no time-out" mode is not set, the ESCDELAY
+ 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 curs_variables(3x).
+ has_key was designed for ncurses, and is not found in SVr4 curses,
+ 4.4BSD curses, or any other previous curses implementation.
-
-
PORTABILITY
- The *get* functions are described in the XSI Curses stan-
- dard, Issue 4. They read single-byte characters only.
- The standard specifies that they return ERR on failure,
- but specifies no error conditions.
-
- The echo behavior of these functions on input of KEY_ or
- backspace characters was not specified in the SVr4 docu-
- mentation. This description is adopted from the XSI Curs-
- es standard.
-
- The behavior of getch and friends in the presence of han-
- dled signals is unspecified in the SVr4 and XSI Curses
- documentation. Under historical curses implementations,
- it varied depending on whether the operating system's im-
- plementation of handled signal receipt interrupts a
- read(2) call in progress or not, and also (in some imple-
- mentations) depending on 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 in-
- terrupt getch; (b) signal receipt interrupts getch and
- causes it to return ERR with errno set to EINTR. Under
- the ncurses implementation, handled signals never inter-
- rupt getch.
-
- The has_key function is unique to ncurses. We recommend
- that any code using it be conditionalized on the NCURS-
- ES_VERSION feature macro.
+
+ Applications employing ncurses extensions should condition their use on
+ the visibility of the NCURSES_VERSION preprocessor macro.
-
-
SEE ALSO
- curses(3x), curs_inopts(3x), curs_mouse(3x),
- curs_move(3x), curs_refresh(3x), resizeterm(3x).
+ X/Open Curses, Issue 4 describes getch, wgetch, mvgetch, mvwgetch, and
+ ungetch. It specifies no error conditions for them.
+
+ wgetch reads only single-byte characters.
+
+ The echo behavior of these functions on input of KEY_ or backspace
+ characters was not specified in the SVr4 documentation. This
+ description is adapted from X/Open Curses.
+
+ The behavior of wgetch in the presence of signal handlers is
+ unspecified in the SVr4 documentation and X/Open Curses. In historical
+ curses implementations, it varied depending on whether the operating
+ system's dispatch of a signal to a handler interrupted a read(2) call
+ in progress, and also (in some implementations) whether an input
+ timeout or non-blocking mode had been set. Programmers concerned about
+ portability should be prepared for either of two cases: (a) signal
+ receipt does not interrupt wgetch; or (b) signal receipt interrupts
+ wgetch and causes it to return ERR with errno set to EINTR.
+
+ KEY_MOUSE is mentioned in X/Open Curses, along with a few related term-
+ info capabilities, but no higher-level functions use the feature. The
+ implementation in ncurses is an extension.
+
+ KEY_RESIZE and has_key are extensions first implemented for ncurses.
+ By 2022, PDCurses and NetBSD curses had added them along with
+ KEY_MOUSE.
+
+
+