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

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