


curs_getch(3X)                                     curs_getch(3X)


NNAAMMEE
       ccuurrss__ggeettcchh:  ggeettcchh,  wwggeettcchh,  mmvvggeettcchh, mmvvwwggeettcchh, uunnggeettcchh -
       get (or push back) characters from  ccuurrsseess  terminal  key-
       board

SSYYNNOOPPSSIISS
       ##iinncclluuddee <<ccuurrsseess..hh>>

       iinntt ggeettcchh((vvooiidd));;
       iinntt wwggeettcchh((WWIINNDDOOWW **wwiinn));;
       iinntt mmvvggeettcchh((iinntt yy,, iinntt xx));;
       iinntt mmvvwwggeettcchh((WWIINNDDOOWW **wwiinn,, iinntt yy,, iinntt xx));;
       iinntt uunnggeettcchh((iinntt cchh));;

DDEESSCCRRIIPPTTIIOONN
       The  ggeettcchh,  wwggeettcchh, mmvvggeettcchh and mmvvwwggeettcchh, routines read a
       character from the window.  In no-delay mode, if no  input
       is waiting, the value EERRRR is returned.  In delay mode, the
       program waits until the system passes text through to  the
       program.   Depending  on  the  setting  of ccbbrreeaakk, this is
       after one character (cbreak mode), or after the first new-
       line  (nocbreak  mode).   In  half-delay mode, the program
       waits until a character is typed or the specified  timeout
       has been reached.

       If  nnooeecchhoo  has  been set, then the character will also be
       echoed into the designated window according to the follow-
       ing  rules:  If the character is the current erase charac-
       ter, left arrow, or backspace, the  cursor  is  moved  one
       space to the left and that screen position is erased as if
       ddeellcchh had been called.  If  the  character  value  is  any
       other  KKEEYY__  define, the user is alerted with a bbeeeepp call.
       Otherwise the character is simply output to the screen.

       If the window is not a pad, and it has been moved or modi-
       fied  since  the  last  call to wwrreeffrreesshh, wwrreeffrreesshh will be
       called before another character is read.

       If kkeeyyppaadd is TTRRUUEE, and a  function  key  is  pressed,  the
       token for that function key is returned instead of the raw
       characters.   Possible  function  keys  are   defined   in
       <<ccuurrsseess..hh>>  as  macros  with  values  outside the range of
       8-bit characters whose names  begin  with  KKEEYY__..  Thus,  a
       variable  intended  to hold the return value of a function
       key must be of short size or larger.

       When a character that could be the beginning of a function
       key  is  received  (which,  on  modern terminals, means an
       escape character), ccuurrsseess sets a timer.  If the  remainder
       of  the  sequence  does  not come in within the designated
       time, the character  is  passed  through;  otherwise,  the
       function  key  value  is  returned.  For this reason, many
       terminals experience a  delay  between  the  time  a  user
       presses  the  escape key and the escape is returned to the



                                                                1





curs_getch(3X)                                     curs_getch(3X)


       program.

       The uunnggeettcchh routine places _c_h back onto the input queue to
       be  returned  by the next call to wwggeettcchh.  Note that there
       is, in effect, just one input queue for all windows.


   FFuunnccttiioonn KKeeyyss
       The following function keys, defined in <<ccuurrsseess..hh>>,  might
       be  returned  by  ggeettcchh  if kkeeyyppaadd has been enabled.  Note
       that not all of these are  necessarily  supported  on  any
       particular terminal.
       __________________________________________________________________
       _N_a_m_e                 _K_e_y _n_a_m_e
       __________________________________________________________________
       KEY_BREAK            Break key
       KEY_DOWN             The four arrow keys ...
       KEY_UP
       KEY_LEFT
       KEY_RIGHT
       KEY_HOME             Home key (upward+left arrow)
       KEY_BACKSPACE        Backspace
       KEY_F0               Function keys; space for 64 keys is reserved.
       KEY_F(_n)             For 0 _< _n _< 63
       KEY_DL               Delete line
       KEY_IL               Insert line
       KEY_DC               Delete character
       KEY_IC               Insert char or enter insert mode
       KEY_EIC              Exit insert char mode
       KEY_CLEAR            Clear screen
       KEY_EOS              Clear to end of screen
       KEY_EOL              Clear to end of line
       KEY_SF               Scroll 1 line forward
       KEY_SR               Scroll 1 line backward (reverse)
       KEY_NPAGE            Next page
       KEY_PPAGE            Previous page
       KEY_STAB             Set tab
       KEY_CTAB             Clear tab
       KEY_CATAB            Clear all tabs
       KEY_ENTER            Enter or send
       KEY_SRESET           Soft (partial) reset
       KEY_RESET            Reset or hard reset
       KEY_PRINT            Print or copy
       KEY_LL               Home down or bottom (lower left).  Keypad is
                            arranged like this:
                                 AA11    uupp    AA33
                                lleefftt   BB22   rriigghhtt
                                 CC11   ddoowwnn   CC33
       KEY_A1               Upper left of keypad
       KEY_A3               Upper right of keypad
       KEY_B2               Center of keypad
       KEY_C1               Lower left of keypad
       KEY_C3               Lower right of keypad
       KEY_BTAB             Back tab key



                                                                2





curs_getch(3X)                                     curs_getch(3X)


       KEY_BEG              Beg(inning) key
       KEY_CANCEL           Cancel key
       KEY_CLOSE            Close key
       KEY_COMMAND          Cmd (command) key
       KEY_COPY             Copy key
       KEY_CREATE           Create key
       KEY_END              End key
       KEY_EXIT             Exit key
       KEY_FIND             Find key
       KEY_HELP             Help key
       KEY_MARK             Mark key
       KEY_MESSAGE          Message key
       KEY_MOVE             Move key
       KEY_NEXT             Next object key
       KEY_OPEN             Open key
       KEY_OPTIONS          Options key
       KEY_PREVIOUS         Previous object key
       KEY_REDO             Redo key
       KEY_REFERENCE        Ref(erence) key
       KEY_REFRESH          Refresh key
       KEY_REPLACE          Replace key
       KEY_RESTART          Restart key
       KEY_RESUME           Resume key
       KEY_SAVE             Save key
       KEY_SBEG             Shifted beginning key
       KEY_SCANCEL          Shifted cancel key
       KEY_SCOMMAND         Shifted command key
       KEY_SCOPY            Shifted copy key
       KEY_SCREATE          Shifted create key
       KEY_SDC              Shifted delete char key
       KEY_SDL              Shifted delete line key
       KEY_SELECT           Select key
       KEY_SEND             Shifted end key
       KEY_SEOL             Shifted clear line key
       KEY_SEXIT            Shifted exit key
       KEY_SFIND            Shifted find key
       KEY_SHELP            Shifted help key
       KEY_SHOME            Shifted home key
       KEY_SIC              Shifted input key
       KEY_SLEFT            Shifted left arrow key
       KEY_SMESSAGE         Shifted message key
       KEY_SMOVE            Shifted move key
       KEY_SNEXT            Shifted next key
       KEY_SOPTIONS         Shifted options key
       KEY_SPREVIOUS        Shifted prev key
       KEY_SPRINT           Shifted print key
       KEY_SREDO            Shifted redo key
       KEY_SREPLACE         Shifted replace key
       KEY_SRIGHT           Shifted right arrow
       KEY_SRSUME           Shifted resume key
       KEY_SSAVE            Shifted save key
       KEY_SSUSPEND         Shifted suspend key
       KEY_SUNDO            Shifted undo key
       KEY_SUSPEND          Suspend key



                                                                3





curs_getch(3X)                                     curs_getch(3X)


       KEY_UNDO             Undo key


RREETTUURRNN VVAALLUUEE
       All  routines  return  the integer EERRRR upon failure and an
       integer  value  other  than  EERRRR"  (OOKK  in  the  case   of
       ungetch()) upon successful completion.

NNOOTTEESS
       Use of the escape key by a programmer for a single charac-
       ter function is discouraged, as it will cause a  delay  of
       up to one second while the keypad code looks for a follow-
       ing function-key sequence.

       When using ggeettcchh, wwggeettcchh, mmvvggeettcchh, or  mmvvwwggeettcchh,  nocbreak
       mode (nnooccbbrreeaakk) and echo mode (eecchhoo) should not be used at
       the same time.  Depending on the state of the  tty  driver
       when  each  character  is  typed,  the program may produce
       undesirable results.

       Note that ggeettcchh, mmvvggeettcchh, and mmvvwwggeettcchh may be macros.

       Historically, the set of keypad macros was largely defined
       by  the  extremely  function-key-rich keyboard of the AT&T
       7300, aka 3B1, aka Safari 4.   Modern  personal  computers
       usually  have  only a small subset of these.  IBM PC-style
       consoles  typically  support  little  more  than   KKEEYY__UUPP,
       KKEEYY__DDOOWWNN,    KKEEYY__LLEEFFTT,   KKEEYY__RRIIGGHHTT,   KKEEYY__HHOOMMEE,   KKEEYY__EENNDD,
       KKEEYY__NNPPAAGGEE, KKEEYY__PPPPAAGGEE, and function keys 1 through 12.  The
       Ins key is usually mapped to KKEEYY__IICC.

PPOORRTTAABBIILLIITTYY
       These  functions are described in the XSI Curses standard,
       Issue 4.  They  read  single-byte  characters  only.   The
       standard  specifies  that  they return EERRRR on failure, but
       specifies no error conditions.

       The echo behavior of these functions on input of  KKEEYY__  or
       backspace  characters was not specified.  This description
       is adopted from the XSI Curses standard.

SSEEEE AALLSSOO
       ccuurrsseess(3X),        ccuurrss__iinnooppttss(3X),         ccuurrss__mmoovvee(3X),
       ccuurrss__rreeffrreesshh(3X).













                                                                4


