doc/html/man/curs_getch.3x.html

   1 <HTML>
   2 <BODY>
   3 <PRE>
   4 <!-- Manpage converted by man2html 3.0.1 -->
   5
   6 </PRE>
   7 <H2>NAME</H2><PRE>
   8        <B>getch</B>,  <B>wgetch</B>,  <B>mvgetch</B>, <B>mvwgetch</B>, <B>ungetch</B>, <B>has_key</B> - get
   9        (or push back) characters from <B>curses</B> terminal keyboard
  10
  11
  12 </PRE>
  13 <H2>SYNOPSIS</H2><PRE>
  14        <B>#include</B> <B>&lt;curses.h&gt;</B>
  15
  16        <B>int</B> <B>getch(void);</B>
  17        <B>int</B> <B>wgetch(WINDOW</B> <B>*win);</B>
  18        <B>int</B> <B>mvgetch(int</B> <B>y,</B> <B>int</B> <B>x);</B>
  19        <B>int</B> <B>mvwgetch(WINDOW</B> <B>*win,</B> <B>int</B> <B>y,</B> <B>int</B> <B>x);</B>
  20        <B>int</B> <B>ungetch(int</B> <B>ch);</B>
  21        <B>int</B> <B>has_key(int</B> <B>ch);</B>
  22
  23
  24 </PRE>
  25 <H2>DESCRIPTION</H2><PRE>
  26        The <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B> and <B>mvwgetch</B>, routines  read  a
  27        character  from the window.  In no-delay mode, if no input
  28        is waiting, the value <B>ERR</B> is returned.  In delay mode, the
  29        program  waits until the system passes text through to the
  30        program.  Depending on the  setting  of  <B>cbreak</B>,  this  is
  31        after one character (cbreak mode), or after the first new-
  32        line (nocbreak mode).  In  half-delay  mode,  the  program
  33        waits  until a character is typed or the specified timeout
  34        has been reached.
  35
  36        Unless <B>noecho</B> has been set, then the character  will  also
  37        be echoed into the designated window according to the fol-
  38        lowing rules: If the character is the current erase  char-
  39        acter,  left  arrow, or backspace, the cursor is moved one
  40        space to the left and that screen position is erased as if
  41        <B>delch</B>  had  been  called.   If  the character value is any
  42        other <B>KEY_</B> define, the user is alerted with a  <B>beep</B>  call.
  43        Otherwise the character is simply output to the screen.
  44
  45        If the window is not a pad, and it has been moved or modi-
  46        fied since the last call to  <B>wrefresh</B>,  <B>wrefresh</B>  will  be
  47        called before another character is read.
  48
  49        If  <B>keypad</B>  is  <B>TRUE</B>,  and  a function key is pressed, the
  50        token for that function key is returned instead of the raw
  51        characters.    Possible   function  keys  are  defined  in
  52        <B>&lt;curses.h&gt;</B> as macros with  values  outside  the  range  of
  53        8-bit  characters  whose  names  begin  with <B>KEY_.</B> Thus, a
  54        variable intended to hold the return value of  a  function
  55        key must be of short size or larger.
  56
  57        When a character that could be the beginning of a function
  58        key is received (which,  on  modern  terminals,  means  an
  59        escape  character), <B>curses</B> sets a timer.  If the remainder
  60        of the sequence does not come  in  within  the  designated
  61        time,  the  character  is  passed  through; otherwise, the
  62        function key value is returned.   For  this  reason,  many
  63        terminals  experience  a  delay  between  the  time a user
  64        presses the escape key and the escape is returned  to  the
  65        program.
  66
  67        The <B>ungetch</B> routine places <I>ch</I> back onto the input queue to
  68        be returned by the next call to <B>wgetch</B>.  Note  that  there
  69        is, in effect, just one input queue for all windows.
  70
  71
  72    <B>Function</B> <B>Keys</B>
  73        The  following function keys, defined in <B>&lt;curses.h&gt;</B>, might
  74        be returned by <B>getch</B> if <B>keypad</B>  has  been  enabled.   Note
  75        that  not  all  of  these are necessarily supported on any
  76        particular terminal.
  77
  78            <I>Name</I>            <I>Key</I> <I>name</I>
  79
  80            KEY_BREAK       Break key
  81            KEY_DOWN        The four arrow keys ...
  82            KEY_UP
  83            KEY_LEFT
  84            KEY_RIGHT
  85            KEY_HOME        Home key (upward+left arrow)
  86            KEY_BACKSPACE   Backspace
  87            KEY_F0          Function keys; space for 64  keys
  88                            is reserved.
  89            KEY_F(<I>n</I>)        For 0 &lt;= <I>n</I> &lt;= 63
  90            KEY_DL          Delete line
  91            KEY_IL          Insert line
  92            KEY_DC          Delete character
  93            KEY_IC          Insert char or enter insert mode
  94            KEY_EIC         Exit insert char mode
  95            KEY_CLEAR       Clear screen
  96            KEY_EOS         Clear to end of screen
  97            KEY_EOL         Clear to end of line
  98            KEY_SF          Scroll 1 line forward
  99            KEY_SR          Scroll 1 line backward (reverse)
 100            KEY_NPAGE       Next page
 101            KEY_PPAGE       Previous page
 102            KEY_STAB        Set tab
 103            KEY_CTAB        Clear tab
 104            KEY_CATAB       Clear all tabs
 105            KEY_ENTER       Enter or send
 106            KEY_SRESET      Soft (partial) reset
 107            KEY_RESET       Reset or hard reset
 108            KEY_PRINT       Print or copy
 109            KEY_LL          Home down or bottom (lower left).
 110            KEY_A1          Upper left of keypad
 111            KEY_A3          Upper right of keypad
 112            KEY_B2          Center of keypad
 113            KEY_C1          Lower left of keypad
 114            KEY_C3          Lower right of keypad
 115            KEY_BTAB        Back tab key
 116            KEY_BEG         Beg(inning) key
 117            KEY_CANCEL      Cancel key
 118
 119            KEY_CLOSE       Close key
 120            KEY_COMMAND     Cmd (command) key
 121            KEY_COPY        Copy key
 122            KEY_CREATE      Create key
 123            KEY_END         End key
 124            KEY_EXIT        Exit key
 125            KEY_FIND        Find key
 126            KEY_HELP        Help key
 127            KEY_MARK        Mark key
 128            KEY_MESSAGE     Message key
 129            KEY_MOUSE       Mouse event read
 130            KEY_MOVE        Move key
 131            KEY_NEXT        Next object key
 132            KEY_OPEN        Open key
 133            KEY_OPTIONS     Options key
 134            KEY_PREVIOUS    Previous object key
 135            KEY_REDO        Redo key
 136            KEY_REFERENCE   Ref(erence) key
 137            KEY_REFRESH     Refresh key
 138            KEY_REPLACE     Replace key
 139            KEY_RESIZE      Screen resized
 140            KEY_RESTART     Restart key
 141            KEY_RESUME      Resume key
 142            KEY_SAVE        Save key
 143            KEY_SBEG        Shifted beginning key
 144            KEY_SCANCEL     Shifted cancel key
 145            KEY_SCOMMAND    Shifted command key
 146            KEY_SCOPY       Shifted copy key
 147            KEY_SCREATE     Shifted create key
 148            KEY_SDC         Shifted delete char key
 149            KEY_SDL         Shifted delete line key
 150            KEY_SELECT      Select key
 151            KEY_SEND        Shifted end key
 152            KEY_SEOL        Shifted clear line key
 153            KEY_SEXIT       Shifted exit key
 154            KEY_SFIND       Shifted find key
 155            KEY_SHELP       Shifted help key
 156            KEY_SHOME       Shifted home key
 157            KEY_SIC         Shifted input key
 158            KEY_SLEFT       Shifted left arrow key
 159            KEY_SMESSAGE    Shifted message key
 160            KEY_SMOVE       Shifted move key
 161            KEY_SNEXT       Shifted next key
 162            KEY_SOPTIONS    Shifted options key
 163            KEY_SPREVIOUS   Shifted prev key
 164            KEY_SPRINT      Shifted print key
 165            KEY_SREDO       Shifted redo key
 166            KEY_SREPLACE    Shifted replace key
 167            KEY_SRIGHT      Shifted right arrow
 168            KEY_SRSUME      Shifted resume key
 169            KEY_SSAVE       Shifted save key
 170            KEY_SSUSPEND    Shifted suspend key
 171            KEY_SUNDO       Shifted undo key
 172
 173            KEY_SUSPEND     Suspend key
 174            KEY_UNDO        Undo key
 175
 176        Keypad is arranged like this:
 177
 178                          +-----+------+-------+
 179                          | <B>A1</B>  |  <B>up</B>  |  <B>A3</B>   |
 180                          +-----+------+-------+
 181                          |<B>left</B> |  <B>B2</B>  | <B>right</B> |
 182                          +-----+------+-------+
 183                          | <B>C1</B>  | <B>down</B> |  <B>C3</B>   |
 184                          +-----+------+-------+
 185        The <B>has_key</B> routine takes a key value from the above list,
 186        and returns TRUE or FALSE according as the current  termi-
 187        nal type recognizes a key with that value.
 188
 189
 190
 191 </PRE>
 192 <H2>RETURN VALUE</H2><PRE>
 193        All  routines  return  the integer <B>ERR</B> upon failure and an
 194        integer value other than <B>ERR</B> (<B>OK</B> in the case of ungetch())
 195        upon successful completion.
 196
 197
 198 </PRE>
 199 <H2>NOTES</H2><PRE>
 200        Use of the escape key by a programmer for a single charac-
 201        ter function is discouraged, as it will cause a  delay  of
 202        up to one second while the keypad code looks for a follow-
 203        ing function-key sequence.
 204
 205        When using <B>getch</B>, <B>wgetch</B>, <B>mvgetch</B>, or  <B>mvwgetch</B>,  nocbreak
 206        mode (<B>nocbreak</B>) and echo mode (<B>echo</B>) should not be used at
 207        the same time.  Depending on the state of the  tty  driver
 208        when  each  character  is  typed,  the program may produce
 209        undesirable results.
 210
 211        Note that <B>getch</B>, <B>mvgetch</B>, and <B>mvwgetch</B> may be macros.
 212
 213        Historically, the set of keypad macros was largely defined
 214        by  the  extremely  function-key-rich keyboard of the AT&amp;T
 215        7300, aka 3B1, aka Safari 4.   Modern  personal  computers
 216        usually  have  only a small subset of these.  IBM PC-style
 217        consoles  typically  support  little  more  than   <B>KEY_UP</B>,
 218        <B>KEY_DOWN</B>,    <B>KEY_LEFT</B>,   <B>KEY_RIGHT</B>,   <B>KEY_HOME</B>,   <B>KEY_END</B>,
 219        <B>KEY_NPAGE</B>, <B>KEY_PPAGE</B>, and function keys 1 through 12.  The
 220        Ins key is usually mapped to <B>KEY_IC</B>.
 221
 222
 223 </PRE>
 224 <H2>PORTABILITY</H2><PRE>
 225        The  *get* functions are described in the XSI Curses stan-
 226        dard, Issue 4.  They  read  single-byte  characters  only.
 227        The  standard  specifies  that they return <B>ERR</B> on failure,
 228        but specifies no error conditions.
 229
 230        The echo behavior of these functions on input of  <B>KEY_</B>  or
 231        backspace  characters  was not specified in the SVr4 docu-
 232        mentation.  This  description  is  adopted  from  the  XSI
 233        Curses standard.
 234
 235        The  behavior of <B>getch</B> and friends in the presence of han-
 236        dled signals is unspecified in the  SVr4  and  XSI  Curses
 237        documentation.   Under  historical curses implementations,
 238        it varied depending  on  whether  the  operating  system's
 239        implementation  of  handled  signal  receipt  interrupts a
 240        <B><A HREF="read.2.html">read(2)</A></B> call in progress or not, and also (in some  imple-
 241        mentations)  depending on whether an input timeout or non-
 242        blocking mode hsd been set.
 243
 244        Programmers concerned about portability should be prepared
 245        for  either  of  two  cases:  (a)  signal receipt does not
 246        interrupt <B>getch</B>; (b) signal receipt interrupts  <B>getch</B>  and
 247        causes  it  to  return ERR with <B>errno</B> set to <B>EINTR</B>.  Under
 248        the <B>ncurses</B> implementation, handled signals  never  inter-
 249        rupt <B>getch</B>.
 250
 251        The  <B>has_key</B>  function is unique to <B>ncurses</B>.  We recommend
 252        that  any  code  using  it  be  conditionalized   on   the
 253        <B>NCURSES_VERSION</B> feature macro.
 254
 255
 256 </PRE>
 257 <H2>SEE ALSO</H2><PRE>
 258        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>,        <B><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></B>,        <B><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></B>,
 259        <B><A HREF="curs_move.3x.html">curs_move(3x)</A></B>, <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>.  <B><A HREF="resizeterm.3x.html">resizeterm(3x)</A></B>.
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289 </PRE>
 290 <HR>
 291 <ADDRESS>
 292 Man(1) output converted with
 293 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 294 </ADDRESS>
 295 </BODY>
 296 </HTML>