*** UNIX MANUAL PAGE BROWSER ***

curs_get_wch(3X) Library calls curs_get_wch(3X) NAME get_wch, wget_wch, mvget_wch, mvwget_wch, unget_wch - get (or push back) a wide character from curses terminal keyboard SYNOPSIS #include <curses.h> int get_wch(wint_t *wch); int wget_wch(WINDOW *win, wint_t *wch); int mvget_wch(int y, int x, wint_t *wch); int mvwget_wch(WINDOW *win, int y, int x, wint_t *wch); int unget_wch(const wchar_t wc); DESCRIPTION Reading Characters 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. When input is pending, wget_wch stores an integer identifying the key stroke in wch; for alphanumeric and punctuation keys, this value corre- sponds to the character encoding used by the terminal. Use of the con- trol 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 hap- pens 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. 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 key- pad mode is enabled (see below), KEY_LEFT and KEY_BACKSPACE are handled the same way. o curses 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. 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. Ungetting Characters 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. RETURN VALUE 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. NOTES 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 in- put 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 over- come 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. EXTENSIONS See the "EXTENSIONS" section of wgetch(3X). PORTABILITY 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 er- ror conditions for them. See the "PORTABILITY" section of wgetch(3X) regarding the interaction of wget_wch with signal handlers. SEE ALSO curs_getch(3X) describes comparable functions of the ncurses library in its non-wide-character configuration. curses(3X), curs_add_wch(3X), curs_inopts(3X), curs_move(3X), curs_refresh(3X) ncurses 6.5 2024-04-20 curs_get_wch(3X)