Ada95/html/man/curs_getch.3x.html

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