Ada95/html/curs_getch.3x.html

   1 <HTML>
   2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
   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>&lt;curses.h&gt;</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>&lt;curses.h&gt;</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>&lt;curses.h&gt;</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 &lt;= <EM>n</EM>
  78        &lt;=   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_MOVE/Move
  96        key   KEY_NEXT/Next   object   key    KEY_OPEN/Open    key
  97        KEY_OPTIONS/Options  key  KEY_PREVIOUS/Previous object key
  98        KEY_REDO/Redo    key     KEY_REFERENCE/Ref(erence)     key
  99        KEY_REFRESH/Refresh     key     KEY_REPLACE/Replace    key
 100        KEY_RESTART/Restart     key     KEY_RESUME/Resume      key
 101        KEY_SAVE/Save key KEY_SBEG/Shifted beginning key KEY_SCAN-
 102        CEL/Shifted cancel key  KEY_SCOMMAND/Shifted  command  key
 103        KEY_SCOPY/Shifted  copy key KEY_SCREATE/Shifted create key
 104        KEY_SDC/Shifted delete  char  key  KEY_SDL/Shifted  delete
 105        line  key  KEY_SELECT/Select  key KEY_SEND/Shifted end key
 106        KEY_SEOL/Shifted clear line key KEY_SEXIT/Shifted exit key
 107        KEY_SFIND/Shifted  find  key  KEY_SHELP/Shifted  help  key
 108        KEY_SHOME/Shifted  home  key  KEY_SIC/Shifted  input   key
 109        KEY_SLEFT/Shifted left arrow key KEY_SMESSAGE/Shifted mes-
 110        sage key KEY_SMOVE/Shifted move key KEY_SNEXT/Shifted next
 111        key KEY_SOPTIONS/Shifted options key KEY_SPREVIOUS/Shifted
 112        KEY_SRIGHT/Shifted right arrow  KEY_SRSUME/Shifted  resume
 113        key  KEY_SSAVE/Shifted  save key KEY_SSUSPEND/Shifted sus-
 114        pend key KEY_SUNDO/Shifted  undo  key  KEY_SUSPEND/Suspend
 115        key KEY_UNDO/Undo key
 116
 117        Keypad is arranged like this:
 118
 119        center  allbox  tab(/)  ;  c c c .  <STRONG>A1</STRONG>/<STRONG>up</STRONG>/<STRONG>A3</STRONG> <STRONG>left</STRONG>/<STRONG>B2</STRONG>/<STRONG>right</STRONG>
 120        <STRONG>C1</STRONG>/<STRONG>down</STRONG>/<STRONG>C3</STRONG>
 121
 122        The <STRONG>has_key</STRONG> routine takes a key value from the above list,
 123        and  returns TRUE or FALSE according as the current termi-
 124        nal type recognizes a key with that value.
 125
 126
 127
 128 </PRE>
 129 <H2>RETURN VALUE</H2><PRE>
 130        All routines return the integer <STRONG>ERR</STRONG> upon  failure  and  an
 131        integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
 132        upon successful completion.
 133
 134
 135 </PRE>
 136 <H2>NOTES</H2><PRE>
 137        Use of the escape key by a programmer for a single charac-
 138        ter  function  is discouraged, as it will cause a delay of
 139        up to one second while the keypad code looks for a follow-
 140        ing function-key sequence.
 141
 142        When  using  <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
 143        mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) should not be used at
 144        the  same  time.  Depending on the state of the tty driver
 145        when each character is  typed,  the  program  may  produce
 146        undesirable results.
 147
 148        Note that <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be macros.
 149
 150        Historically, the set of keypad macros was largely defined
 151        by the extremely function-key-rich keyboard  of  the  AT&amp;T
 152        7300,  aka  3B1,  aka Safari 4.  Modern personal computers
 153        usually have only a small subset of these.   IBM  PC-style
 154        consoles   typically  support  little  more  than  <STRONG>KEY_UP</STRONG>,
 155        <STRONG>KEY_DOWN</STRONG>,   <STRONG>KEY_LEFT</STRONG>,   <STRONG>KEY_RIGHT</STRONG>,   <STRONG>KEY_HOME</STRONG>,    <STRONG>KEY_END</STRONG>,
 156        <STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12.  The
 157        Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
 158
 159
 160 </PRE>
 161 <H2>PORTABILITY</H2><PRE>
 162        The *get* functions are described in the XSI Curses  stan-
 163        dard,  Issue  4.   They  read single-byte characters only.
 164        The standard specifies that they return  <STRONG>ERR</STRONG>  on  failure,
 165        but specifies no error conditions.
 166
 167        The  echo  behavior of these functions on input of <STRONG>KEY_</STRONG> or
 168        backspace characters was not specified in the  SVr4  docu-
 169        mentation.   This  description  is  adopted  from  the XSI
 170        dled  signals  is  unspecified  in the SVr4 and XSI Curses
 171        documentation.  Under historical  curses  implementations,
 172        it  varied  depending  on  whether  the operating system's
 173        implementation of  handled  signal  receipt  interrupts  a
 174        <STRONG><A HREF="read.2.html">read(2)</A></STRONG>  call in progress or not, and also (in some imple-
 175        mentations) depending on whether an input timeout or  non-
 176        blocking mode hsd been set.
 177
 178        Programmers concerned about portability should be prepared
 179        for either of two  cases:  (a)  signal  receipt  does  not
 180        interrupt  <STRONG>getch</STRONG>;  (b) signal receipt interrupts <STRONG>getch</STRONG> and
 181        causes it to return ERR with <STRONG>errno</STRONG> set  to  <STRONG>EINTR</STRONG>.   Under
 182        the  <STRONG>ncurses</STRONG>  implementation, handled signals never inter-
 183        rupt <STRONG>getch</STRONG>.
 184
 185        The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>.   We  recommend
 186        that  any  code using it be conditionalized on the NCURSES
 187        feature macro.
 188
 189
 190 </PRE>
 191 <H2>SEE ALSO</H2><PRE>
 192        <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_move.3x.html">curs_move(3X)</A></STRONG>,
 193        <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3X)</A></STRONG>.
 194
 195
 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>