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

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