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