@@ -89,22 +89,22 @@
elapses.
If echo(3x) has been called, and the window is not a pad, curses writes
- the returned character ch to the window (at the cursor position) per
- the following rules.
+ the returned character c to the window (at the cursor position) per the
+ following rules.
- o If ch matches the terminal's erase character, the cursor moves
+ 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 ch to the window, as with wechochar(3x).
+ ocurses writes any other c to the window, as with wechochar(3x).
o If the window has been moved or modified since the last call to
wrefresh(3x), curses calls wrefresh.
- If ch is a carriage return and nl(3x) has been called, wgetch returns
- the character code for newline (line feed) instead.
+ If c is a carriage return and nl(3x) has been called, wgetch returns
+ the character code for line feed instead.
- ungetch places ch into the input queue to be returned by the next call
+ ungetch places c into the input queue to be returned by the next call
to wgetch. A single input queue serves all windows.
@@ -164,7 +164,7 @@
terminal.
o The naming convention may seem obscure, with some apparent
- misspellings (such as "RSUME" for "resume"); The names correspond
+ 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.
@@ -267,7 +267,7 @@
KEY_SSUSPEND Shifted suspend key
KEY_SUNDO Shifted undo key
- The keypad is arranged as follows.
+ Many keyboards feature a nine-key directional pad.
+-----+------+-------+
| A1 | up | A3 |
@@ -276,41 +276,43 @@
+-----+------+-------+
| C1 | down | C3 |
+-----+------+-------+
- Two of these symbols do not correspond to a real key.
+ 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 detects the SIGWINCH signal; see initscr(3x)
+ 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
+ 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 prototocol), ncurses must read
an escape sequence, as with a function key.
- In ncurses, has_key takes a key code value from the above list, and
- returns a Boolean value indicating the terminal's recognition of it.
- See also define_key(3x) and key_defined(3x).
+ 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).
- wgetch returns ERR if
+ Except for has_key, these functions return OK on success and ERR on
+ failure.
- o the WINDOW pointer is NULL, or
+ 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
+ o execution was interrupted by a signal, in which case errno is set
to EINTR.
- Functions with a "mv" prefix first perform cursor movement using
- wmove(3x) and fail if the position is outside the window, or (for "mvw"
- functions) if the win parameter is a null pointer.
-
- ungetch returns OK on success and ERR if there is no more room in the
- input queue.
+ ungetch fails if there is no more room in the input queue.
has_key returns TRUE or FALSE.
@@ -329,12 +331,12 @@
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.
+ 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.
- o The terminfokey_enter (kent) capability describes the character
- (sequence) sent by the terminal's keypad Enter key.
+ 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.
@@ -355,7 +357,7 @@
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 on the IBM PC/AT keyboard and tend to have
+ 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
@@ -378,7 +380,7 @@
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
- X/Open Curses, Issue 4, describes getch, wgetch, mvgetch, mvwgetch, and
+ 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.
@@ -390,8 +392,8 @@
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 interrupts a read(2) call in
- progress or not, and also (in some implementations) whether an input
+ system's dispatch of a signal to a handler interrupting a read(2) 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 wgetch; or (b) signal receipt interrupts
@@ -422,7 +424,7 @@
-ncurses 6.4 2024-04-13 curs_getch(3x)
+ncurses 6.4 2024-04-20 curs_getch(3x)