- wget_wch gathers a key stroke wch from the terminal keyboard associated
- with a curses window win, returning OK if a wide character is read,
+ wget_wch gathers a key event from the terminal keyboard associated with
+ a curses window win, returning OK if a wide character is read,
KEY_CODE_YES if a function key is read, and ERR if no key event is
available. ncurses(3x) describes the variants of this function.
When input is pending, wget_wch stores an integer identifying the key
- stroke in wch; for alphanumeric and punctuation keys, this value
+ event in wch; 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 win is in keypad mode; see
- subsections "Keypad Mode" and "Predefined Key Codes" in getch(3x).
-
- 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 a character is typed or the specified delay
+ 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 subsections
+ "Keypad Mode" and "Predefined Key Codes" in getch(3x).
+
+ 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
wch to the window (at the cursor position) per the following rules.
- o If wch 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
+ o If wch 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 wch to the window, as with wecho_wchar(3x).
- o If the window has been moved or modified since the last call to
- wrefresh(3x), curses calls wrefresh.
+ o If the window win has been moved or modified since the last call to
+ wrefresh(3x), curses calls wrefresh on it.
- If wch is a carriage return and nl(3x) has been called, wgetch stores
- the the character code for newline (line feed) in wch instead.
+ If wch is a carriage return and nl(3x) has been called, wgetch stores
+ the the character code for line feed in wch instead.
- unget_wch places wch into the input queue to be returned by the next
- call to wget_wch. A single input queue serves all windows.
+ unget_wch places wch into the input queue to be returned by the next
+ call to wget_wch. A single input queue serves all windows associated
+ with the terminal.
@@ -119,9 +121,8 @@
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.
+ Functions prefixed with "mv" first perform cursor movement and fail if
+ the position (y, x) is outside the window boundaries.
unget_wch returns OK on success and ERR if there is no more room in the
input queue.
@@ -133,15 +134,14 @@
All of these functions except wget_wch and unget_wch may be implemented
as macros.
- Unlike wgetch(3x), wget_wch and its variants store the value of the
- input character in an additional wch parameter instead of the return
+ Unlike wgetch(3x), wget_wch and its variants store the value of the
+ input character in an additional wch parameter instead of the return
value.
- Unlike ungetch, unget_wch cannot distinguish function key codes
- wget_wch from conventional character codes. An application can
- overcome this limitation by pushing function key codes with ungetch and
- subsequently checking the return value of wget_wch for a match with
- KEY_CODE_YES.
+ Unlike ungetch, unget_wch cannot distinguish function key codes from
+ conventional character codes. An application can overcome this
+ limitation by pushing function key codes with ungetch and subsequently
+ checking the return value of wget_wch for a match with KEY_CODE_YES.
@@ -152,7 +152,7 @@
Applications employing ncurses extensions should condition their use on
the visibility of the NCURSES_VERSION preprocessor macro.
- X/Open Curses, Issue 4, describes these functions. It specifies no
+ X/Open Curses, Issue 4 describes these functions. It specifies no
error conditions for them.
See the "PORTABILITY" section of wgetch(3x) regarding the interaction
@@ -168,7 +168,7 @@
-ncurses 6.4 2024-04-13 curs_get_wch(3x)
+ncurses 6.5 2024-05-11 curs_get_wch(3x)