- 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 char-
- acter into the designated window.
-
- If the window is not a pad and has been moved or modified
- since the last call to wrefresh, wrefresh will be called
- before another character 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 corresponding KEY_ value defined in
- <curses.h> 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 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 program calls unget_wch
- too many times without an intervening call to get_wch, the
- operation may fail.
+
+ 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,
+ 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.
- Applications should not define the escape key by itself as
- a single-character function.
+ When input is pending, wget_wch stores an integer identifying the key
+ stroke 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).
- 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 program may produce
- undesirable results.
+ 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
+ elapses.
- All functions except wget_wch and unget_wch may be macros.
+ 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
+ handled the same way.
-
-
RETURN VALUES
- When get_wch, wget_wch, mvget_wch, and mvwget_wch func-
- tions 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.
+ ocurses writes any other wch to the window, as with wecho_wchar(3x).
- Upon successful completion, unget_wch returns OK. Other-
- wise, the function returns ERR.
+ o If the window has been moved or modified since the last call to
+ wrefresh(3x), curses calls wrefresh.
- Functions with a "mv" prefix first perform a cursor move-
- ment using wmove, and return an error if the position is
- outside the window, or if the window pointer is null.
+ 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.
-
+ wget_wch returns OK when it reads a wide character and KEY_CODE_YES
+ when it reads a function key code. It returns ERR if
+
+ o the WINDOW pointer is NULL, or
+
+ o its timeout expires without any data arriving, or
+
+ o execution was interrupted by a signal, in which case errno is set
+ to EINTR.
+
+ 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.
+
+
+
+ See the "NOTES" section of wgetch(3x).
+
+ 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
+ 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.
+
+
+
+ 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
+ error conditions for them.
+
+ See the "PORTABILITY" section of wgetch(3x) regarding the interaction
+ of wget_wch with signal handlers.
+
+
+