Reading Characters

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.

• 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.
• curses writes any other c to the window, as with wechochar(3X).
• 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.

Keypad Mode

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.

• The curses.h header file declares many predefined function keys whose names begin with KEY_; these object-like macros have values outside the range of eight-bit character codes.
• In ncurses, user-defined function keys 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.

Ungetting Characters

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.

Predefined Key Codes

The header file curses.h defines the following function key codes.

• Except for the special case of KEY_RESIZE, a window's keypad mode must be enabled for wgetch to read these codes from it.
• Not all of these are necessarily supported on any particular terminal.
• 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.

Many keyboards feature a nine-key directional pad.

Two of the symbols in the list above do not correspond to a physical key.

• wgetch returns KEY_RESIZE, even if the window's keypad mode is disabled, when ncurses handles a SIGWINCH signal; see initscr(3X) and resizeterm(3X).
• wgetch 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 prototocol), ncurses must read an escape sequence, as with a function key.

Testing Key Codes

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).