ncurses 4.1
[ncurses.git] / 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>