- get_wch, wget_wch, mvget_wch, mvwget_wch, unget_wch - get (or push
- back) a wide character from curses terminal keyboard
+ get_wch, wget_wch, mvget_wch, mvwget_wch, unget_wch - get (or push
+ back) a wide character from curses terminal keyboard
- The get_wch, wget_wch, mvget_wch, and mvwget_wch functions read a char-
- acter from the terminal associated with the current or specified win-
- dow. In no-delay mode, if no input is waiting, the value ERR is re-
- turned. In delay mode, the program waits until the system passes text
- through to the program. Depending on the setting of cbreak, this is
- after one character (cbreak mode), or after the first newline (nocbreak
- mode). In half-delay mode, the program waits until the user types a
- character or the specified timeout interval has elapsed.
+
+
+ The get_wch, wget_wch, mvget_wch, and mvwget_wch functions read a
+ character from the terminal associated with the current or specified
+ 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 after one character (cbreak mode), or after the first newline
+ (nocbreak mode). In half-delay mode, the program waits until the user
+ types a character or the specified timeout interval has elapsed.
Unless noecho has been set, these routines echo the character into the
designated window.
@@ -78,58 +82,67 @@
is read.
If keypad is enabled, these functions respond to the pressing of a
- function key by setting the object pointed to by wch to the keycode as-
- signed to the function key, and returning KEY_CODE_YES. If a character
- (such as escape) that could be the beginning of a function key is re-
- ceived, curses sets a timer. If the remainder of the sequence does ar-
- rive within the designated time, curses passes through the character;
- otherwise, curses returns the function key value. For this reason,
- many terminals experience a delay between the time a user presses the
- escape key and the time the escape is returned to the program.
+ function key by setting the object pointed to by wch to the keycode
+ assigned to the function key, and returning KEY_CODE_YES. If a
+ character (such as escape) that could be the beginning of a function
+ key is received, curses sets a timer. If the remainder of the sequence
+ does arrive within the designated time, curses passes through the
+ character; otherwise, curses returns the function key value. For this
+ reason, many terminals experience a delay between the time a user
+ presses the escape key and the time the escape is returned to the
+ program.
The keycodes returned by these functions are the same as those returned
by wgetch:
- o The predefined function keys are listed in <curses.h> as macros
- with values outside the range of 8-bit characters. Their names be-
- gin with KEY_.
+ o The predefined function keys are listed in <curses.h> as macros
+ with values outside the range of 8-bit characters. Their names
+ begin with KEY_.
- o Other (user-defined) function keys which may be defined using de-
- fine_key(3x) have no names, but also are expected to have values
+ o Other (user-defined) function keys which may be defined using
+ define_key(3x) have no names, but also are expected to have values
outside the range of 8-bit characters.
+
+
The unget_wch function pushes the wide character wch back onto the head
- of the input queue, so the wide character is returned by the next call
- to get_wch. The pushback of one character is guaranteed. If the pro-
- gram calls unget_wch too many times without an intervening call to
+ of the input queue, so the wide character is returned by the next call
+ to get_wch. The pushback of one character is guaranteed. If the
+ program calls unget_wch too many times without an intervening call to
get_wch, the operation may fail.
+ Unlike ungetch and wgetch, unget_wch cannot distinguish special
+ characters returned by wget_wch from ordinary characters. An
+ application can push special keys which it may read via wget_wch by
+ checking for the KEY_CODE_YES result, and using ungetch for those
+ special keys.
+
- The header file <curses.h> automatically includes the header file
+ The header file <curses.h> automatically includes the header file
<stdio.h>.
- Applications should not define the escape key by itself as a single-
+ Applications should not define the escape key by itself as a single-
character function.
- When using get_wch, wget_wch, mvget_wch, or mvwget_wch, applications
+ When using get_wch, wget_wch, mvget_wch, or mvwget_wch, applications
should not use nocbreak mode and echo mode at the same time. Depending
- on the state of the tty driver when each character is typed, the pro-
- gram may produce undesirable results.
+ on the state of the tty driver when each character is typed, the
+ program may produce undesirable results.
All functions except wget_wch and unget_wch may be macros.
- When get_wch, wget_wch, mvget_wch, and mvwget_wch functions successful-
- ly report the pressing of a function key, they return KEY_CODE_YES.
- When they successfully report a wide character, they return OK. Other-
- wise, they return ERR.
+ When get_wch, wget_wch, mvget_wch, and mvwget_wch functions
+ successfully report the pressing of a function key, they return
+ KEY_CODE_YES. When they successfully report a wide character, they
+ return OK. Otherwise, they return ERR.
- Upon successful completion, unget_wch returns OK. Otherwise, the func-
- tion returns ERR.
+ Upon successful completion, unget_wch returns OK. Otherwise, the
+ function returns ERR.
- Functions with a "mv" prefix first perform a cursor movement using
+ Functions with a "mv" prefix first perform a cursor movement using
wmove, and return an error if the position is outside the window, or if
the window pointer is null.
@@ -140,13 +153,18 @@
- curs_get_wch(3x)
+ncurses 6.4 2023-09-16 curs_get_wch(3x)