NAME

getwch, wgetwch, mvgetwch, mvwgetwch, ungetwch − Read (or push back) a wchar_t character from curses terminal keyboard

LIBRARY

The curses library (libcurses.so, libcurses.a)

SYNOPSIS

#include <curses.h>

int getwch();

int wgetwch( WINDOW ∗win );

int mvgetwch(
        int y,
        int x );

int mvwgetwch(
        WINDOW ∗win,
        int y,
        int x );

int ungetwch( int wch );

PARAMETERS

wchSpecifies the wide character to be pushed back to the input queue. 

winSpecifies a curses window. If not specified, the window is the default window stdscr. 

y, xSpecifies the line (y) and column (x) coordinates of the target position on the window.  If coordinates are not specified, the target position is the current position of the logical cursor. 

DESCRIPTION

The getwch routine reads a wchar_t character from the terminal associated with the default window. 

The wgetwch routine reads a wchar_t character from the terminal associated with the specified window win. 

The mvgetwch routine reads a wchar_t character from the terminal associated with the default window at the specified position (y, x). 

The mvwgetwch routine reads a wchar_t character from the terminal associated with the specified window win at the specified position (y, x). 

The ungetwch routine pushes a wchar_t character wch back to the input queue to be returned by the next call to wgetwch. 

The following information applies to all the routines.  In nodelay mode, if there is no input waiting, the integer ERR is returned.  In delay mode, the program waits until the system passes text through to the program.  Usually the program restarts after being passed one character or the first newline, depending on how the program has set cbreak.  The system echos the character on the designated window unless the program has set noecho. 

If the program sets keypad to TRUE and the user presses a function key, curses returns the token for that function key instead of the raw characters to the program.  Possible function keys are defined using integers beginning with 0401 in the curses.h header file.  The function key names begin with KEY_. 

If the system receives a character that could be the beginning of a function key (such as escape), curses sets a timer.  If the remainder of the sequence does not arrive within the designated time, curses passes the character through to the program; otherwise, curses returns the function key value.  Consequently, there may be a delay after a user presses the escape key before the escape is returned to the program.  Because there is delay after the user presses the escape key, do not use escape for a single character function in your program. 

The getwch, mvgetwch, and mvwgetwch routines are macros. 

RETURN VALUES

Upon successful completion, the getwch, mvgetwch, mvwgetwch, and wgetwch routines return the character that has been read to the program. 

If delay mode is in effect and no data is available, ERR is returned. 

The ungetwch routine returns ERR on error and an integer value other than ERR on success. 

RELATED INFORMATION

Functions: cbreak(3), keypad(3), nodelay(3), noecho(3).