# curs_get_wch 3x 2023-12-23 ncurses 6.4 Library calls

    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 wch);

## DESCRIPTION

### wget_wch

           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.

           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 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
               begin with KEY_.

           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.

### unget_wch

           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.

           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.

## RETURN VALUE

           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
           function returns ERR.

           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.

## NOTES

           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
           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.

           All of these functions except wget_wch and unget_wch may be implemented
           as macros.

## PORTABILITY

           These functions are described in the XSI Curses standard, Issue 4.

## SEE ALSO

           curses(3x),    curs_getch(3x),    curs_inopts(3x),    curs_ins_wch(3x),
           curs_move(3x), curs_refresh(3x)

    ncurses 6.4                       2023-12-23                  curs_get_wch(3x)