usr/src/man/man3xcurses/getch.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GETCH 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 getch, wgetch, mvgetch, mvwgetch \- get a single-byte character from the
   9 terminal
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  14 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  15
  16 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  17
  18 #include <curses.h>
  19
  20 \fBint\fR \fBgetch\fR(\fBvoid\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBwgetch\fR(\fBWINDOW *\fR\fIwin\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBmvgetch\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBmvwgetch\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR);
  36 .fi
  37
  38 .SH PARAMETERS
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIwin\fR\fR
  43 .ad
  44 .RS 7n
  45 Is a pointer to the window associated with the terminal from which the
  46 character is to be read.
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIy\fR\fR
  53 .ad
  54 .RS 7n
  55 Is the y (row) coordinate for the position of the character to be read.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIx\fR\fR
  62 .ad
  63 .RS 7n
  64 Is the x (column) coordinate for the position of the character to be read.
  65 .RE
  66
  67 .SH DESCRIPTION
  68 .sp
  69 .LP
  70 These functions read a single-byte character from the terminal associated with
  71 the current or specified window. The results are unspecified if the input is
  72 not a single-byte character. If \fBkeypad\fR(3XCURSES) is enabled, these
  73 functions respond to the pressing of a function key by returning the
  74 corresponding \fBKEY_\fR value defined in <\fBcurses.h\fR>
  75 .sp
  76 .LP
  77 Processing of terminal input is subject to the general rules described on the
  78 \fBkeypad\fR(3XCURSES) manual page.
  79 .sp
  80 .LP
  81 If echoing is enabled, then the character is echoed as though it were provided
  82 as an input argument to \fBaddch\fR(3XCURSES), except for the following
  83 characters:
  84 .sp
  85 .ne 2
  86 .na
  87 \fB<backspace>\fR
  88 .ad
  89 .RS 17n
  90 The input is interpreted as follows: unless the cursor already was in column 0,
  91 <backspace> moves the cursor one column toward the start of the current line
  92 and any characters after the <backspace> are added or inserted starting there.
  93 The character at the resulting cursor position it then deleted as though
  94 \fBdelch\fR(3XCURSES) were called, except that if the cursor was originally in
  95 the first column of the line, the user is alerted as though
  96 \fBbeep\fR(3XCURSES) were called.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fBFunction keys\fR
 103 .ad
 104 .RS 17n
 105 The user is alerted  as though \fBbeep()\fR were called. Information concerning
 106 the function keys is not returned to the caller.
 107 .RE
 108
 109 .sp
 110 .LP
 111 If the current or specified window is not a pad, and it has been moved modified
 112 since the last refresh operation, then it will be refreshed before another
 113 character is read.
 114 .SS "Constant Values for Function Keys"
 115 .sp
 116 .LP
 117 The following is a list of tokens for function keys that are returned by  the
 118 \fBgetch()\fR set of functions if keypad handling is enabled (some  terminals
 119 may not support all tokens).
 120 .sp
 121
 122 .sp
 123 .TS
 124 box;
 125 c c
 126 l l .
 127 \fBConstant\fR  \fBDescription\fR
 128 _
 129 KEY_BREAK       Break key
 130 KEY_DOWN        The down arrow key
 131 KEY_UP  The up arrow key
 132 KEY_LEFT        The left arrow key
 133 KEY_RIGHT       The right arrow key
 134 KEY_HOME        Home key
 135 KEY_BACKSPACE   Backspace
 136 KEY_F0  T{
 137 Function keys.  Space for 64 keys is reserved.
 138 T}
 139 KEY_F(\fIn\fR)  For  0 <= \fIn\fR <= 63
 140 KEY_DL  Delete line
 141 KEY_IL  Insert line
 142 KEY_DC  Delete character
 143 KEY_IC  Insert char or enter insert mode
 144 KEY_EIC Exit insert char mode
 145 KEY_CLEAR       Clear screen
 146 KEY_EOS Clear to end of screen
 147 KEY_EOL Clear to end of line
 148 KEY_SF  Scroll 1 line forward
 149  KEY_SR Scroll 1 line backwards
 150 KEY_NPAGE       Next page
 151 KEY_PPAGE       Previous page
 152 KEY_STAB        Set tab
 153 KEY_CTAB        Clear tab
 154 KEY_CATAB       Clear all tabs
 155 KEY_ENTER       Enter or send
 156 KEY_SRESET      Soft (partial) reset
 157 KEY_RESET       Reset or hard reset
 158 KEY_PRINT       Print or copy
 159 KEY_LL  Home down or bottom (lower left)
 160 KEY_A1  Upper left of keypad
 161 KEY_A3  Upper right of keypad
 162 KEY_B2  Center of keypad
 163 KEY_C1  Lower left of keypad
 164 KEY_C3  Lower right of keypad
 165 KEY_BTAB        Back tab
 166 KEY_BEG Beginning key
 167 KEY_CANCEL      Cancel key
 168 KEY_CLOSE       Close key
 169 KEY_COMMAND     Cmd (command) key
 170 KEY_COPY        Copy key
 171 KEY_CREATE      Create key
 172 KEY_END End key
 173 KEY_EXIT        Exit key
 174 KEY_FIND        Find key
 175 KEY_HELP        Help key
 176 KEY_MARK        Mark key
 177 KEY_MESSAGE     Message key
 178 KEY_MOVE        Move key
 179 KEY_NEXT        Next object key
 180 KEY_OPEN        Open key
 181 KEY_OPTIONS     Options key
 182 KEY_PREVIOUS    Previous object key
 183 KEY_REDO        Redo key
 184 KEY_REFERENCE   Reference key
 185 KEY_REFRESH     Refresh key
 186 KEY_REPLACE     Replace key
 187 KEY_RESTART     Restart key
 188 KEY_RESUME      Resume key
 189 KEY_SAVE        Save key
 190 KEY_SBEG        Shifted beginning key
 191 KEY_SCANCEL     Shifted cancel key
 192 KEY_SCOMMAND    Shifted command key
 193 KEY_SCOPY       Shifted copy key
 194 KEY_SCREATE     Shifted create key
 195 KEY_SDC Shifted delete char key
 196 KEY_SDL Shifted delete line key
 197 KEY_SELECT      Select key
 198 KEY_SEND        Shifted end key
 199 KEY_SEOL        Shifted clear line key
 200 KEY_SEXIT       Shifted exit key
 201 KEY_SFIND       Shifted find key
 202 KEY_SHELP       Shifted help key
 203 KEY_SHOME       Shifted home key
 204 KEY_SIC Shifted input key
 205 KEY_SLEFT       Shifted left arrow key
 206 KEY_SMESSAGES   Shifted messages key
 207 KEY_SMOVE       Shifted move key
 208 KEY_SNEXT       Shifted next key
 209 KEY_SOPTIONS    Shifted options key
 210 KEY_SPREVIOUS   Shifted previous key
 211 KEY_SPRINT      Shifted print key
 212 KEY_SREDO       Shifted redo key
 213 KEY_SREPLACE    Shifted replace key
 214 KEY_SRIGHT      Shifted right arrow key
 215 KEY_SRSUME      Shifted resume key
 216 KEY_SSAVE       Shifted save key
 217 KEY_SSUSPEND    Shifted suspend key
 218 KEY_SUNDO       Shifted undo key
 219 KEY_SUSPEND     Suspend key
 220 KEY_UNDO        Undo key
 221 .TE
 222
 223 .SH RETURN VALUES
 224 .sp
 225 .LP
 226 Upon successful completion, these functions return the single-byte character,
 227 \fBKEY_\fR value, or \fBERR\fR. When in the nodelay mode and no data is
 228 available, \fBERR\fR is returned.
 229 .SH ERRORS
 230 .sp
 231 .LP
 232 No errors are defined.
 233 .SH  USAGE
 234 .sp
 235 .LP
 236 Applications should not define the escape key by itself as a single-character
 237 function.
 238 .sp
 239 .LP
 240 When using these functions, nocbreak mode (\fBcbreak\fR(3XCURSES)) and echo
 241 mode (\fBecho\fR(3XCURSES)) should not be used at the same time. Depending on
 242 the state of the terminal when each character is typed, the application may
 243 produce undesirable results.
 244 .SH ATTRIBUTES
 245 .sp
 246 .LP
 247 See \fBattributes\fR(5) for descriptions of the following attributes:
 248 .sp
 249
 250 .sp
 251 .TS
 252 box;
 253 c | c
 254 l | l .
 255 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 256 _
 257 Interface Stability     Standard
 258 _
 259 MT-Level        Unsafe
 260 .TE
 261
 262 .SH SEE ALSO
 263 .sp
 264 .LP
 265 \fBcbreak\fR(3XCURSES), \fBecho\fR(3XCURSES), \fBhalfdelay\fR(3XCURSES),
 266 \fBkeypad\fR(3XCURSES), \fBlibcurses\fR(3XCURSES), \fBnodelay\fR(3XCURSES),
 267 \fBnotimeout\fR(3XCURSES), \fBraw\fR(3XCURSES), \fBtimeout\fR(3XCURSES),
 268 \fBattributes\fR(5), \fBstandards\fR(5)