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.87 2024/04/20 19:18:18 tom Exp $
32 .TH curs_getch 3X 2024-04-20 "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 stroke 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 stroke;
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 often results in a distinct code.
91 The behavior of other keys depends on whether
94 see subsection \*(``Keypad Mode\*('' below.
96 If no input is pending,
97 then if the no-delay flag is set in the window
98 (see \fB\%nodelay\fP(3X)),
103 waits until the terminal has input.
104 If \fB\%cbreak\fP(3X)
106 this happens after one character is read.
107 If \fB\%nocbreak\fP(3X)
109 it occurs when the next newline is read.
110 If \fB\%halfdelay\fP(3X)
113 waits until a character is typed or the specified delay elapses.
115 If \fB\%echo\fP(3X) has been called,
116 and the window is not a pad,
118 writes the returned character
121 (at the cursor position)
122 per the following rules.
126 matches the terminal's erase character,
127 the cursor moves leftward one position
128 and the new position is erased
129 as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called.
130 When the window's keypad mode is enabled
135 are handled the same way.
141 as with \fB\%wechochar\fP(3X).
143 If the window has been moved or modified since the last call to
144 \fB\%wrefresh\fP(3X),
151 is a carriage return and \fBnl\fP(3X) has been called,
153 returns the character code for line feed instead.
157 key strokes not from the alphabetic section of the keyboard
158 (those corresponding to the ECMA-6 character set\(emsee
159 \fIascii\fP(7)\(emoptionally modified by either the control or shift
166 the term \*(``function key\*('' includes but is not limited to keycaps
167 engraved with \*(``F1\*('',
170 If the window is in keypad mode,
171 these produce a numeric code corresponding to the
173 symbols listed in subsection \*(``Predefined Key Codes\*('' below;
175 they transmit a sequence of codes typically starting with the escape
177 and which must be collected with multiple
183 header file declares many
184 .I "predefined function keys"
185 whose names begin with
187 these object-like macros have values outside the range of eight-bit
192 .I "user-defined function keys"
193 are configured with \fB\%define_key\fP(3X);
195 but are also expected to have values outside the range of eight-bit
198 A variable intended to hold a function key code must thus be of type
202 Most terminals one encounters follow the ECMA-48 standard insofar as
203 their function keys produce character sequences prefixed with the
204 escape character ESC.
205 This fact implies that
207 cannot know whether the terminal has sent an ESC key stroke or the
208 beginning of a function key's character sequence without waiting to see
211 further input arrives.
214 reads such an ambiguous character,
216 If the remainder of the sequence does not arrive within the designated
219 returns the prefix character;
221 it returns the function key code corresponding to the unique sequence
222 defined by the terminal.
226 application may experience a delay after pressing ESC while
228 disambiguates the input;
229 see section \*(``EXTENSIONS\*('' below.
230 If the window is in \*(``no time-out\*('' mode,
231 the timer does not expire;
235 See \fB\%notimeout\fP(3X).
236 Because function key sequences usually begin with an escape character,
237 the terminal may appear to hang in no time-out mode after the user has
240 further typing \*(``awakens\*(''
242 .SS "Ungetting Characters"
246 into the input queue to be returned by the next call to
248 A single input queue serves all windows.
249 .SS "Predefined Key Codes"
252 defines the following function key codes.
254 Except for the special case of
256 a window's keypad mode must be enabled for
258 to read these codes from it.
260 Not all of these are necessarily supported on any particular terminal.
262 The naming convention may seem obscure,
263 with some apparent misspellings
264 (such as \*(``RSUME\*('' for \*(``resume\*('');
265 the names correspond to the
267 capability names for the keys,
268 and were standardized before the IBM PC/AT keyboard layout achieved a
269 dominant position in industry.
272 .\" XXX: Move this list into ncurses(3X), rather than duplicating it in
273 .\" get_wch(3X) or having that page cross reference this one?
284 KEY_HOME Home key (upward+left arrow)
285 KEY_BACKSPACE Backspace
287 Function keys; space for 64 keys is reserved
290 Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63
294 KEY_DC Delete character
295 KEY_IC Insert character/Enter insert mode
296 KEY_EIC Exit insert character mode
297 KEY_CLEAR Clear screen
298 KEY_EOS Clear to end of screen
299 KEY_EOL Clear to end of line
300 KEY_SF Scroll one line forward
301 KEY_SR Scroll one line backward (reverse)
302 KEY_NPAGE Next page/Page up
303 KEY_PPAGE Previous page/Page down
306 KEY_CATAB Clear all tabs
308 KEY_SRESET Soft (partial) reset
309 KEY_RESET (Hard) reset
311 KEY_LL Home down/Bottom (lower left)
312 KEY_A1 Upper left of keypad
313 KEY_A3 Upper right of keypad
314 KEY_B2 Center of keypad
315 KEY_C1 Lower left of keypad
316 KEY_C3 Lower right of keypad
317 KEY_BTAB Back tab key
318 KEY_BEG Beg(inning) key
319 KEY_CANCEL Cancel key
321 KEY_COMMAND Cmd (command) key
323 KEY_CREATE Create key
329 KEY_MESSAGE Message key
330 KEY_MOUSE Mouse event occurred
332 KEY_NEXT Next object key
334 KEY_OPTIONS Options key
335 KEY_PREVIOUS Previous object key
337 KEY_REFERENCE Ref(erence) key
338 KEY_REFRESH Refresh key
339 KEY_REPLACE Replace key
340 KEY_RESIZE Screen resized
341 KEY_RESTART Restart key
342 KEY_RESUME Resume key
344 KEY_SELECT Select key
345 KEY_SUSPEND Suspend key
348 KEY_SBEG Shifted beginning key
349 KEY_SCANCEL Shifted cancel key
350 KEY_SCOMMAND Shifted command key
351 KEY_SCOPY Shifted copy key
352 KEY_SCREATE Shifted create key
353 KEY_SDC Shifted delete character key
354 KEY_SDL Shifted delete line key
355 KEY_SEND Shifted end key
356 KEY_SEOL Shifted clear line key
357 KEY_SEXIT Shifted exit key
358 KEY_SFIND Shifted find key
359 KEY_SHELP Shifted help key
360 KEY_SHOME Shifted home key
361 KEY_SIC Shifted insert key
362 KEY_SLEFT Shifted left arrow key
363 KEY_SMESSAGE Shifted message key
364 KEY_SMOVE Shifted move key
365 KEY_SNEXT Shifted next object key
366 KEY_SOPTIONS Shifted options key
367 KEY_SPREVIOUS Shifted previous object key
368 KEY_SPRINT Shifted print key
369 KEY_SREDO Shifted redo key
370 KEY_SREPLACE Shifted replace key
371 KEY_SRIGHT Shifted right arrow key
372 KEY_SRSUME Shifted resume key
373 KEY_SSAVE Shifted save key
374 KEY_SSUSPEND Shifted suspend key
375 KEY_SUNDO Shifted undo key
379 Many keyboards feature a nine-key directional pad.
391 Two of the symbols in the list above do
393 correspond to a physical key.
398 even if the window's keypad mode is disabled,
404 see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X).
409 to indicate that a mouse event is pending collection;
410 see \fB\%curs_mouse\fP(3X).
411 Receipt of this code requires a window's keypad mode to be enabled,
412 because to interpret mouse input
413 (as with with \fI\%xterm\fP(1)'s mouse prototocol),
415 must read an escape sequence,
416 as with a function key.
417 .SS "Testing Key Codes"
421 returns a Boolean value indicating whether the terminal type recognizes
422 its parameter as a key code value.
424 \fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X).
428 these functions return
436 pointer argument fail if the pointer is
439 Functions prefixed with \*(``mv\*('' first perform cursor movement and
443 is outside the window boundaries.
448 its timeout expires without any data arriving,
451 execution was interrupted by a signal,
458 fails if there is no more room in the input queue.
467 discourages assignment of the ESC key to a discrete function by the
468 programmer because the library requires a delay while it awaits the
469 potential remainder of a terminal escape sequence.
471 Some key strokes are indistinguishable from control characters;
476 .\" as with att630 or pccon+keys
481 .\" as with att505 or vt52-basic
484 .\" as with pccon+keys or vt320
485 Consult the terminal's
487 entry to determine whether this is the case;
488 see \fB\%infocmp\fP(1).
497 others treat such control characters specially.
500 distinguishes the Enter keys in the alphabetic and numeric keypad
501 sections of a keyboard because (most) terminals do.
503 refers to the key on the numeric keypad and,
504 like other function keys,
505 and is reliably recognized only if the window's keypad mode is enabled.
511 capability describes the character (sequence) sent by the Enter key of
516 \*(``Enter or send\*('' is X/Open Curses's description of this key.
519 treats the Enter or Return key in the
521 section of the keyboard differently.
523 It usually produces a control code for carriage return
528 Depending on the terminal mode
533 and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called,
535 may return either a carriage return or line feed upon an Enter or Return
540 with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X)
544 the list of key code macros above was influenced by the
545 function-key-rich keyboard of the AT&T 7300
546 (also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and
549 Today's computer keyboards are based that of the IBM PC/AT and tend to
553 application can expect such a keyboard to transmit key codes
578 may be implemented as macros.
582 when a window's \*(``no time-out\*('' mode is
587 variable configures the duration of the timer used to disambiguate a
588 function key character sequence from a series of key strokes beginning
589 with ESC typed by the user;
591 \fB\%curs_variables\fP(3X).
593 \fB\%has_key\fP was designed for \fB\%ncurses\fP(3X),
594 and is not found in SVr4
598 or any other previous curses implementation.
600 Applications employing
602 extensions should condition their use on the visibility of the
614 It specifies no error conditions for them.
617 reads only single-byte characters.
619 The echo behavior of these functions on input of
621 or backspace characters was not specified in the SVr4 documentation.
622 This description is adapted from X/Open Curses.
626 in the presence of signal handlers is unspecified in the SVr4
627 documentation and X/Open Curses.
631 it varied depending on whether the operating system's dispatch of a
632 signal to a handler interrupting a \fIread\fP(2) call in progress,
634 (in some implementations)
635 whether an input timeout or non-blocking mode has been set.
636 Programmers concerned about portability should be prepared for either of
638 (a) signal receipt does not interrupt
641 (b) signal receipt interrupts
643 and causes it to return
651 is mentioned in X/Open Curses,
652 along with a few related
655 but no higher-level functions use the feature.
656 The implementation in
663 are extensions first implemented for
667 .\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html
671 .\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3
672 had added them along with
675 \fB\%curs_get_wch\fP(3X) describes comparable functions of the
677 library in its wide-character configuration
681 \fB\%curs_addch\fP(3X),
682 \fB\%curs_inopts\fP(3X),
683 \fB\%curs_mouse\fP(3X),
684 \fB\%curs_move\fP(3X),
685 \fB\%curs_outopts\fP(3X),
686 \fB\%curs_refresh\fP(3X),
687 \fB\%curs_variables\fP(3X),
688 \fB\%resizeterm\fP(3X),
691 ECMA-6 \*(``7-bit coded Character Set\*(''
692 \%<https://\*:ecma\-international\*:.org/\
693 \*:publications\-and\-standards/\*:standards/\*:ecma\-6/>
695 ECMA-48 \*(``Control Functions for Coded Character Sets\*(''
696 \%<https://\*:ecma\-international\*:.org/\
697 \*:publications\-and\-standards/\*:standards/\*:ecma\-48/>