2 .\"***************************************************************************
3 .\" Copyright 2018-2023,2024 Thomas E. Dickey *
4 .\" Copyright 1998-2016,2017 Free Software Foundation, Inc. *
6 .\" Permission is hereby granted, free of charge, to any person obtaining a *
7 .\" copy of this software and associated documentation files (the *
8 .\" "Software"), to deal in the Software without restriction, including *
9 .\" without limitation the rights to use, copy, modify, merge, publish, *
10 .\" distribute, distribute with modifications, sublicense, and/or sell *
11 .\" copies of the Software, and to permit persons to whom the Software is *
12 .\" furnished to do so, subject to the following conditions: *
14 .\" The above copyright notice and this permission notice shall be included *
15 .\" in all copies or substantial portions of the Software. *
17 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 .\" Except as contained in this notice, the name(s) of the above copyright *
26 .\" holders shall not be used in advertising or otherwise to promote the *
27 .\" sale, use or other dealings in this Software without prior written *
29 .\"***************************************************************************
31 .\" $Id: curs_getch.3x,v 1.93 2024/05/25 20:57:17 tom Exp $
32 .TH curs_getch 3X 2024-05-25 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
60 get (or push back) characters from \fIcurses\fR terminal keyboard
63 .B #include <curses.h>
66 .B int wgetch(WINDOW *\fIwin\fP);
67 .B int mvgetch(int \fIy\fP, int \fIx\fP);
68 .B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP);
70 .B int ungetch(int \fIc\fP);
72 .\" XXX: Move has_key into its own page like define_key and key_defined?
74 .B int has_key(int \fIc\fP);
77 .SS "Reading Characters"
79 gathers a key event from the terminal keyboard associated with a
83 \fB\%ncurses\fP(3X) describes the variants of this function.
85 When input is pending,
87 returns an integer identifying the key event;
88 for alphanumeric and punctuation keys,
89 this value corresponds to the character encoding used by the terminal.
90 Use of the control key as a modifier,
91 by holding it down while pressing and releasing another key,
92 often results in a distinct code.
93 The behavior of other keys depends on whether
96 see subsection \*(``Keypad Mode\*('' below.
98 If no input is pending,
99 then if the no-delay flag is set in the window
100 (see \fB\%nodelay\fP(3X)),
105 waits until the terminal has input.
106 If \fB\%cbreak\fP(3X)
108 this happens after one character is read.
109 If \fB\%nocbreak\fP(3X)
111 it occurs when the next newline is read.
112 If \fB\%halfdelay\fP(3X)
115 waits until input is available or the specified delay elapses.
117 If \fB\%echo\fP(3X) has been called,
118 and the window is not a pad,
120 writes the returned character
123 (at the cursor position)
124 per the following rules.
128 matches the terminal's erase character,
129 the cursor moves leftward one position
130 and the new position is erased
131 as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
132 When the window's keypad mode is enabled
137 are handled the same way.
143 as with \fB\%wechochar\fP(3X).
147 has been moved or modified since the last call to
148 \fB\%wrefresh\fP(3X),
156 is a carriage return and \fBnl\fP(3X) has been called,
158 returns the character code for line feed instead.
162 key strokes not from the alphabetic section of the keyboard
163 (those corresponding to the ECMA-6 character set\(emsee
164 \fI\%ascii\fP(7)\(emoptionally modified by either the control or shift
171 the term \*(``function key\*('' includes but is not limited to keycaps
172 engraved with \*(``F1\*('',
175 If the window is in keypad mode,
176 these produce a numeric code corresponding to the
178 symbols listed in subsection \*(``Predefined Key Codes\*('' below;
180 they transmit a sequence of codes typically starting with the escape
182 and which must be collected with multiple
188 header file declares many
189 .I "predefined function keys"
190 whose names begin with
192 these object-like macros have values outside the range of eight-bit
197 .I "user-defined function keys"
198 are configured with \fB\%define_key\fP(3X);
200 but are also expected to have values outside the range of eight-bit
203 A variable intended to hold a function key code must thus be of type
207 Most terminals one encounters follow the ECMA-48 standard insofar as
208 their function keys produce character sequences prefixed with the
209 escape character ESC.
210 This fact implies that
212 cannot distinguish a user's press of the escape key
213 (assuming it sends ESC)
214 from the beginning of a function key's character sequence without
217 further input arrives.
220 reads such an ambiguous character,
222 If the remainder of the sequence does not arrive within the designated
225 returns the prefix character;
227 it returns the function key code corresponding to the unique sequence
228 defined by the terminal.
232 application may experience a delay after they escape key is pressed
235 disambiguates the input;
236 see section \*(``EXTENSIONS\*('' below.
237 If the window is in \*(``no time-out\*('' mode,
238 the timer does not expire;
242 See \fB\%notimeout\fP(3X).
243 Because function key sequences usually begin with ESC,
244 the terminal may appear to hang in no time-out mode after the user
245 presses the escape key.
247 further typing \*(``awakens\*(''
249 .SS "Ungetting Characters"
253 into the input queue to be returned by the next call to
255 A single input queue serves all windows associated with the terminal.
256 .SS "Predefined Key Codes"
259 defines the following function key codes.
261 Except for the special case of
263 a window's keypad mode must be enabled for
265 to read these codes from it.
267 Not all of these are necessarily supported on any particular terminal.
269 The naming convention may seem obscure,
270 with some apparent misspellings
271 (such as \*(``RSUME\*('' for \*(``resume\*('');
272 the names correspond to the
274 capability names for the keys,
275 and were standardized before the IBM PC/AT keyboard layout achieved a
276 dominant position in industry.
279 .\" XXX: Move this list into ncurses(3X), rather than duplicating it in
280 .\" get_wch(3X) or having that page cross reference this one?
291 KEY_HOME Home key (upward+left arrow)
292 KEY_BACKSPACE Backspace
294 Function keys; space for 64 keys is reserved
297 Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
301 KEY_DC Delete character
302 KEY_IC Insert character/Enter insert mode
303 KEY_EIC Exit insert character mode
304 KEY_CLEAR Clear screen
305 KEY_EOS Clear to end of screen
306 KEY_EOL Clear to end of line
307 KEY_SF Scroll one line forward
308 KEY_SR Scroll one line backward (reverse)
309 KEY_NPAGE Next page/Page up
310 KEY_PPAGE Previous page/Page down
313 KEY_CATAB Clear all tabs
315 KEY_SRESET Soft (partial) reset
316 KEY_RESET (Hard) reset
318 KEY_LL Home down/Bottom (lower left)
319 KEY_A1 Upper left of keypad
320 KEY_A3 Upper right of keypad
321 KEY_B2 Center of keypad
322 KEY_C1 Lower left of keypad
323 KEY_C3 Lower right of keypad
324 KEY_BTAB Back tab key
325 KEY_BEG Beg(inning) key
326 KEY_CANCEL Cancel key
328 KEY_COMMAND Cmd (command) key
330 KEY_CREATE Create key
336 KEY_MESSAGE Message key
337 KEY_MOUSE Mouse event occurred
339 KEY_NEXT Next object key
341 KEY_OPTIONS Options key
342 KEY_PREVIOUS Previous object key
344 KEY_REFERENCE Ref(erence) key
345 KEY_REFRESH Refresh key
346 KEY_REPLACE Replace key
347 KEY_RESIZE Screen resized
348 KEY_RESTART Restart key
349 KEY_RESUME Resume key
351 KEY_SELECT Select key
352 KEY_SUSPEND Suspend key
355 KEY_SBEG Shifted beginning key
356 KEY_SCANCEL Shifted cancel key
357 KEY_SCOMMAND Shifted command key
358 KEY_SCOPY Shifted copy key
359 KEY_SCREATE Shifted create key
360 KEY_SDC Shifted delete character key
361 KEY_SDL Shifted delete line key
362 KEY_SEND Shifted end key
363 KEY_SEOL Shifted clear line key
364 KEY_SEXIT Shifted exit key
365 KEY_SFIND Shifted find key
366 KEY_SHELP Shifted help key
367 KEY_SHOME Shifted home key
368 KEY_SIC Shifted insert key
369 KEY_SLEFT Shifted left arrow key
370 KEY_SMESSAGE Shifted message key
371 KEY_SMOVE Shifted move key
372 KEY_SNEXT Shifted next object key
373 KEY_SOPTIONS Shifted options key
374 KEY_SPREVIOUS Shifted previous object key
375 KEY_SPRINT Shifted print key
376 KEY_SREDO Shifted redo key
377 KEY_SREPLACE Shifted replace key
378 KEY_SRIGHT Shifted right arrow key
379 KEY_SRSUME Shifted resume key
380 KEY_SSAVE Shifted save key
381 KEY_SSUSPEND Shifted suspend key
382 KEY_SUNDO Shifted undo key
386 Many keyboards feature a nine-key directional pad.
398 Two of the symbols in the list above do
400 correspond to a physical key.
405 even if the window's keypad mode is disabled,
411 see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
416 to indicate that a mouse event is pending collection;
417 see \fB\%curs_mouse\fP(3X).
418 Receipt of this code requires a window's keypad mode to be enabled,
419 because to interpret mouse input
420 (as with with \fI\%xterm\fP(1)'s mouse protocol),
422 must read an escape sequence,
423 as with a function key.
424 .SS "Testing Key Codes"
428 returns a Boolean value indicating whether the terminal type recognizes
429 its parameter as a key code value.
431 \fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
435 these functions return
443 pointer argument fail if the pointer is
446 Functions prefixed with \*(``mv\*('' first perform cursor movement and
450 is outside the window boundaries.
455 its timeout expires without any data arriving,
458 execution was interrupted by a signal,
465 fails if there is no more room in the input queue.
474 discourages assignment of the ESC key to a discrete function by the
475 programmer because the library requires a delay while it awaits the
476 potential remainder of a terminal escape sequence.
478 Some key strokes are indistinguishable from control characters;
483 .\" as with att630 or pccon+keys
488 .\" as with att505 or vt52-basic
491 .\" as with pccon+keys or vt320
494 entry for the terminal type to determine whether this is the case;
495 see \fB\%infocmp\fP(1).
504 others treat such control characters specially.
507 distinguishes the Enter keys in the alphabetic and numeric keypad
508 sections of a keyboard because (most) terminals do.
510 refers to the key on the numeric keypad and,
511 like other function keys,
512 is reliably recognized only if the window's keypad mode is enabled.
518 capability describes the character (sequence) sent by the Enter key of
523 \*(``Enter or send\*('' is X/Open Curses's description of this key.
526 treats the Enter or Return key in the
528 section of the keyboard differently.
530 It usually produces a control code for carriage return
535 Depending on the terminal mode
540 and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
542 may return either a carriage return or line feed upon an Enter or Return
547 with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
551 the list of key code macros above was influenced by the keyboard of the
553 (also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and
555 a 1985 machine rich in function keys.
556 Today's computer keyboards are based that of the IBM PC/AT and tend to
560 application can expect such a keyboard to transmit key codes
585 may be implemented as macros.
589 when a window's \*(``no time-out\*('' mode is
594 variable configures the duration of the timer used to disambiguate a
595 function key character sequence from a series of key strokes beginning
596 with ESC typed by the user;
598 \fB\%curs_variables\fP(3X).
603 and is not found in SVr4
607 or any other previous
611 Applications employing
613 extensions should condition their use on the visibility of the
617 Except as noted in section \*(``EXTENSIONS\*('' above,
619 Issue 4 describes these functions.
620 It specifies no error conditions for them.
623 reads only single-byte characters.
625 The echo behavior of these functions on input of
627 or backspace characters was not specified in the SVr4 documentation.
628 This description is adapted from X/Open Curses.
632 in the presence of signal handlers is unspecified in the SVr4
633 documentation and X/Open Curses.
637 it varied depending on whether the operating system's dispatch of a
638 signal to a handler interrupted a \fIread\fP(2) call in progress,
640 (in some implementations)
641 whether an input timeout or non-blocking mode had been set.
642 Programmers concerned about portability should be prepared for either of
644 (a) signal receipt does not interrupt
647 (b) signal receipt interrupts
649 and causes it to return
657 is mentioned in X/Open Curses,
658 along with a few related
661 but no higher-level functions use the feature.
662 The implementation in
669 are extensions first implemented for
673 .\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
677 .\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
678 had added them along with
681 ECMA-6 \*(``7-bit coded Character Set\*(''
682 \%<https://\*:ecma\-international\*:.org/\
683 \*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
685 ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
686 \%<https://\*:ecma\-international\*:.org/\
687 \*:publications\-and\-standards/\*:standards/\*:ecma\-48/>
689 \fB\%curs_get_wch\fP(3X) describes comparable functions of the
691 library in its wide-character configuration
695 \fB\%curs_addch\fP(3X),
696 \fB\%curs_inopts\fP(3X),
697 \fB\%curs_mouse\fP(3X),
698 \fB\%curs_move\fP(3X),
699 \fB\%curs_outopts\fP(3X),
700 \fB\%curs_refresh\fP(3X),
701 \fB\%curs_variables\fP(3X),
702 \fB\%resizeterm\fP(3X),