Blame - doc/html/man/curs_getch.3x.html - android_external_libncurses

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

2

<!--

3

* t

4

****************************************************************************

5

6

* *

7

* Permission is hereby granted, free of charge, to any person obtaining a *

8

* copy of this software and associated documentation files (the *

9

* "Software"), to deal in the Software without restriction, including *

10

* without limitation the rights to use, copy, modify, merge, publish, *

11

* distribute, distribute with modifications, sublicense, and/or sell *

12

* copies of the Software, and to permit persons to whom the Software is *

13

* furnished to do so, subject to the following conditions: *

14

* *

15

* The above copyright notice and this permission notice shall be included *

16

* in all copies or substantial portions of the Software. *

17

* *

18

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

19

* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

20

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

21

* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

22

* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

23

* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

24

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

25

* *

26

* Except as contained in this notice, the name(s) of the above copyright *

27

* holders shall not be used in advertising or otherwise to promote the *

28

* sale, use or other dealings in this Software without prior written *

29

* authorization. *

30

****************************************************************************

31

* @Id: curs_getch.3x,v 1.30 2006/12/02 17:02:53 tom Exp @

-->

<HTML>

<HEAD>

<TITLE>curs_getch 3x</TITLE>

</HEAD>

<BODY>

<H1>curs_getch 3x</H1>

41

<HR>

42

<PRE>

43

44

<A HREF="curs_getch.3x.html">curs_getch(3x)</A> <A HREF="curs_getch.3x.html">curs_getch(3x)</A>

</PRE>

getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get

52

(or push back) characters from curses terminal keyboard

</PRE>

<H2>SYNOPSIS</H2><PRE>

#include <curses.h>

int getch(void);

int wgetch(WINDOW *win);

61

int mvgetch(int y, int x);

62

int mvwgetch(WINDOW *win, int y, int x);

int ungetch(int ch);

int has_key(int ch);

</PRE>

<H2>DESCRIPTION</H2><PRE>

69

The getch, wgetch, mvgetch and mvwgetch, routines read a

70

character from the window. In no-delay mode, if no input

71

is waiting, the value ERR is returned. In delay mode, the

72

program waits until the system passes text through to the

73

program. Depending on the setting of cbreak, this is af-

74

ter one character (cbreak mode), or after the first new-

75

line (nocbreak mode). In half-delay mode, the program

76

waits until a character is typed or the specified timeout

77

has been reached.

78

79

Unless noecho has been set, then the character will also

80

be echoed into the designated window according to the fol-

81

lowing rules: If the character is the current erase char-

82

acter, left arrow, or backspace, the cursor is moved one

83

space to the left and that screen position is erased as if

84

delch had been called. If the character value is any oth-

85

er KEY_ define, the user is alerted with a beep call.

86

Otherwise the character is simply output to the screen.

87

88

If the window is not a pad, and it has been moved or modi-

89

fied since the last call to wrefresh, wrefresh will be

90

called before another character is read.

91

92

If keypad is TRUE, and a function key is pressed, the to-

93

ken for that function key is returned instead of the raw

94

characters. Possible function keys are defined in <curs-

95

es.h> as macros with values outside the range of 8-bit

96

characters whose names begin with KEY_. Thus, a variable

97

intended to hold the return value of a function key must

98

be of short size or larger.

99

100

When a character that could be the beginning of a function

101

key is received (which, on modern terminals, means an es-

102

cape character), curses sets a timer. If the remainder of

103

the sequence does not come in within the designated time,

104

the character is passed through; otherwise, the function

105

key value is returned. For this reason, many terminals

106

experience a delay between the time a user presses the es-

107

cape key and the escape is returned to the program.

108

109

The ungetch routine places ch back onto the input queue to

110

be returned by the next call to wgetch. There is just one

111

input queue for all windows.

Function Keys

The following function keys, defined in <curses.h>, might

116

be returned by getch if keypad has been enabled. Note

117

that not all of these are necessarily supported on any

particular terminal.

Name Key name

KEY_BREAK Break key

KEY_DOWN The four arrow keys ...

KEY_UP

KEY_LEFT

KEY_RIGHT

KEY_HOME Home key (upward+left arrow)

128

KEY_BACKSPACE Backspace

129

KEY_F0 Function keys; space for 64 keys

130

is reserved.

131

KEY_F(n) For 0 <= n <= 63

132

KEY_DL Delete line

133

KEY_IL Insert line

134

KEY_DC Delete character

135

KEY_IC Insert char or enter insert mode

136

KEY_EIC Exit insert char mode

137

KEY_CLEAR Clear screen

138

KEY_EOS Clear to end of screen

139

KEY_EOL Clear to end of line

140

KEY_SF Scroll 1 line forward

141

KEY_SR Scroll 1 line backward (reverse)

142

KEY_NPAGE Next page

143

KEY_PPAGE Previous page

144

KEY_STAB Set tab

145

KEY_CTAB Clear tab

146

KEY_CATAB Clear all tabs

147

KEY_ENTER Enter or send

148

KEY_SRESET Soft (partial) reset

149

KEY_RESET Reset or hard reset

150

KEY_PRINT Print or copy

151

KEY_LL Home down or bottom (lower left)

152

KEY_A1 Upper left of keypad

153

KEY_A3 Upper right of keypad

154

KEY_B2 Center of keypad

155

KEY_C1 Lower left of keypad

156

KEY_C3 Lower right of keypad

157

KEY_BTAB Back tab key

158

KEY_BEG Beg(inning) key

159

KEY_CANCEL Cancel key

160

KEY_CLOSE Close key

161

KEY_COMMAND Cmd (command) key

162

KEY_COPY Copy key

163

KEY_CREATE Create key

KEY_END End key

KEY_EXIT Exit key

KEY_FIND Find key

KEY_HELP Help key

KEY_MARK Mark key

KEY_MESSAGE Message key

170

KEY_MOUSE Mouse event read

171

KEY_MOVE Move key

172

KEY_NEXT Next object key

173

KEY_OPEN Open key

174

KEY_OPTIONS Options key

175

KEY_PREVIOUS Previous object key

176

KEY_REDO Redo key

177

KEY_REFERENCE Ref(erence) key

178

KEY_REFRESH Refresh key

179

KEY_REPLACE Replace key

180

KEY_RESIZE Screen resized

181

KEY_RESTART Restart key

182

KEY_RESUME Resume key

183

184

KEY_SAVE Save key

185

KEY_SBEG Shifted beginning key

186

KEY_SCANCEL Shifted cancel key

187

KEY_SCOMMAND Shifted command key

188

KEY_SCOPY Shifted copy key

189

KEY_SCREATE Shifted create key

190

KEY_SDC Shifted delete char key

191

KEY_SDL Shifted delete line key

192

KEY_SELECT Select key

193

KEY_SEND Shifted end key

194

KEY_SEOL Shifted clear line key

195

KEY_SEXIT Shifted exit key

196

KEY_SFIND Shifted find key

197

KEY_SHELP Shifted help key

198

KEY_SHOME Shifted home key

199

KEY_SIC Shifted input key

200

KEY_SLEFT Shifted left arrow key

201

KEY_SMESSAGE Shifted message key

202

KEY_SMOVE Shifted move key

203

KEY_SNEXT Shifted next key

204

KEY_SOPTIONS Shifted options key

205

KEY_SPREVIOUS Shifted prev key

206

KEY_SPRINT Shifted print key

207

KEY_SREDO Shifted redo key

208

KEY_SREPLACE Shifted replace key

209

KEY_SRIGHT Shifted right arrow

210

KEY_SRSUME Shifted resume key

211

KEY_SSAVE Shifted save key

212

KEY_SSUSPEND Shifted suspend key

213

KEY_SUNDO Shifted undo key

214

KEY_SUSPEND Suspend key

215

KEY_UNDO Undo key

216

217

Keypad is arranged like this:

218

219

220

+-----+------+-------+

221

| A1 | up | A3 |

222

+-----+------+-------+

223

|left | B2 | right |

224

+-----+------+-------+

225

| C1 | down | C3 |

226

+-----+------+-------+

227

The has_key routine takes a key value from the above list,

228

and returns TRUE or FALSE according to whether the current

229

terminal type recognizes a key with that value. Note that

230

a few values do not correspond to a real key, e.g.,

231

KEY_RESIZE and KEY_MOUSE. See <A HREF="resizeterm.3x.html">resizeterm(3x)</A> for more de-

232

tails about KEY_RESIZE, and <A HREF="curs_mouse.3x.html">curs_mouse(3x)</A> for a discus-

sion of KEY_MOUSE.

</PRE>

<H2>RETURN VALUE</H2><PRE>

239

All routines return the integer ERR upon failure and an

240

integer value other than ERR (OK in the case of ungetch())

241

upon successful completion.

242

243

ungetch

244

returns an error if there is no more room in

the FIFO.

wgetch

returns an error if the window pointer is

249

null, or if its timeout expires without having

any data.

</PRE>

<H2>NOTES</H2><PRE>

Use of the escape key by a programmer for a single charac-

256

ter function is discouraged, as it will cause a delay of

257

up to one second while the keypad code looks for a follow-

258

ing function-key sequence.

259

260

Note that some keys may be the same as commonly used con-

261

trol keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE

262

versus control/H. Some curses implementations may differ

263

according to whether they treat these control keys spe-

264

cially (and ignore the terminfo), or use the terminfo def-

265

initions. Ncurses uses the terminfo definition. If it

266

says that KEY_ENTER is control/M, getch will return

267

KEY_ENTER when you press control/M.

268

269

When using getch, wgetch, mvgetch, or mvwgetch, nocbreak

270

mode (nocbreak) and echo mode (echo) should not be used at

271

the same time. Depending on the state of the tty driver

272

when each character is typed, the program may produce un-

273

desirable results.

274

275

Note that getch, mvgetch, and mvwgetch may be macros.

276

277

Historically, the set of keypad macros was largely defined

278

by the extremely function-key-rich keyboard of the AT&T

279

7300, aka 3B1, aka Safari 4. Modern personal computers

280

usually have only a small subset of these. IBM PC-style

281

consoles typically support little more than KEY_UP,

282

KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END,

283

KEY_NPAGE, KEY_PPAGE, and function keys 1 through 12. The

284

Ins key is usually mapped to KEY_IC.

</PRE>

<H2>PORTABILITY</H2><PRE>

289

The *get* functions are described in the XSI Curses stan-

290

dard, Issue 4. They read single-byte characters only.

291

The standard specifies that they return ERR on failure,

292

but specifies no error conditions.

293

294

The echo behavior of these functions on input of KEY_ or

295

backspace characters was not specified in the SVr4 docu-

296

mentation. This description is adopted from the XSI Curs-

297

es standard.

298

299

The behavior of getch and friends in the presence of han-

300

dled signals is unspecified in the SVr4 and XSI Curses

301

documentation. Under historical curses implementations,

302

it varied depending on whether the operating system's im-

303

plementation of handled signal receipt interrupts a

304

<A HREF="read.2.html">read(2)</A> call in progress or not, and also (in some imple-

305

mentations) depending on whether an input timeout or non-

306

blocking mode has been set.

307

308

Programmers concerned about portability should be prepared

309

for either of two cases: (a) signal receipt does not in-

310

terrupt getch; (b) signal receipt interrupts getch and

311

causes it to return ERR with errno set to EINTR. Under

312

the ncurses implementation, handled signals never inter-

313

rupt getch.

314

315

The has_key function is unique to ncurses. We recommend

316

that any code using it be conditionalized on the NCURS-

317

ES_VERSION feature macro.

</PRE>

<A HREF="ncurses.3x.html">curses(3x)</A>, <A HREF="curs_inopts.3x.html">curs_inopts(3x)</A>, <A HREF="curs_mouse.3x.html">curs_mouse(3x)</A>,

323

<A HREF="curs_move.3x.html">curs_move(3x)</A>, <A HREF="curs_refresh.3x.html">curs_refresh(3x)</A>, <A HREF="resizeterm.3x.html">resizeterm(3x)</A>.

324

325

Comparable functions in the wide-character (ncursesw) li-

326

brary are described in <A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A>.

<A HREF="curs_getch.3x.html">curs_getch(3x)</A>

</PRE>

<HR>

Man(1) output converted with

</ADDRESS>

</BODY>

</HTML>