diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3/curs_getch.3x')
| -rw-r--r-- | upstream/mageia-cauldron/man3/curs_getch.3x | 815 |
1 files changed, 529 insertions, 286 deletions
diff --git a/upstream/mageia-cauldron/man3/curs_getch.3x b/upstream/mageia-cauldron/man3/curs_getch.3x index fed7fa70..af510d01 100644 --- a/upstream/mageia-cauldron/man3/curs_getch.3x +++ b/upstream/mageia-cauldron/man3/curs_getch.3x @@ -28,19 +28,24 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.78 2024/02/17 19:27:03 tom Exp $ -.TH curs_getch 3X 2024-02-17 "ncurses 6.4" "Library calls" +.\" $Id: curs_getch.3x,v 1.83 2024/03/23 20:38:57 tom Exp $ +.TH curs_getch 3X 2024-03-23 "ncurses 6.4" "Library calls" .ie \n(.g \{\ .ds `` \(lq .ds '' \(rq +.ds ^ \(ha .\} .el \{\ .ie t .ds `` `` .el .ds `` "" .ie t .ds '' '' .el .ds '' "" +.ds ^ ^ .\} . +.ie \n(.g .ds : \: +.el .ds : \" empty +. .de bP .ie n .IP \(bu 4 .el .IP \(bu 2 @@ -64,318 +69,528 @@ get (or push back) characters from \fIcurses\fR terminal keyboard .PP .B int ungetch(int \fIch\fP); .PP +.\" XXX: Move has_key into its own page like define_key and key_defined? \fI/* extension */\fP .B int has_key(int \fIch\fP); .fi .SH DESCRIPTION .SS "Reading Characters" -The \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP and \fBmvwgetch\fP, routines read -a character from the window. -In no-delay mode, if no input is waiting, the value \fBERR\fP is returned. -In delay mode, the program waits until the system -passes text through to the program. -Depending on the setting of \fBcbreak\fP, -this is after one character (cbreak mode), -or after the first newline (nocbreak mode). -In half-delay mode, -the program waits until a character is typed or the -specified timeout has been reached. +.B \%wgetch +gathers a key stroke from the terminal keyboard associated with a +.I curses +window +.IR win . +\fB\%ncurses\fP(3X) describes the variants of this function. .PP -If \fBecho\fP is enabled, and the window is not a pad, -then the character will also be echoed into the -designated window according to the following rules: -.bP -If the character is the current erase character, left arrow, or backspace, -the cursor is moved one space to the left and that screen position is erased -as if \fBdelch\fP had been called. +When input is pending, +.B \%wgetch +returns an integer identifying the key stroke; +for alphanumeric and punctuation keys, +this value corresponds to the character encoding used by the terminal. +Use of the control key as a modifier often results in a distinct code. +The behavior of other keys depends on whether +.I win +is in keypad mode; +see subsection \*(``Keypad Mode\*('' below. +.PP +If no input is pending, +then if the no-delay flag is set in the window +(see \fB\%nodelay\fP(3X)), +the function returns +.BR ERR ; +otherwise, +.I curses +waits until the terminal has input. +If \fB\%cbreak\fP(3X) +has been called, +this happens after one character is read. +If \fB\%nocbreak\fP(3X) +has been called, +it occurs when the next newline is read. +If \fB\%halfdelay\fP(3X) +has been called, +.I curses +waits until a character is typed or the specified delay elapses. +.PP +If \fB\%echo\fP(3X) has been called, +and the window is not a pad, +.I curses +writes the returned character +.I ch +to the window +(at the cursor position) +per the following rules. .bP -If the character value is any other \fBKEY_\fP define, the user is alerted -with a \fBbeep\fP call. +If +.I ch +matches the terminal's erase character, +the cursor moves leftward one position +and the new position is erased +as if \fB\%wmove\fP(3X) and then \fB\%wdelch\fP(3X) were called. +When the window's keypad mode is enabled +(see below), +.B \%KEY_LEFT +and +.B \%KEY_BACKSPACE +are handled the same way. .bP -If the character is a carriage-return, -and if \fBnl\fP is enabled, -it is translated to a line-feed after echoing. +.I curses +writes any other +.I ch +to the window, +as with \fB\%wechochar\fP(3X). .bP -Otherwise the character is simply output to the screen. +If the window has been moved or modified since the last call to +\fB\%wrefresh\fP(3X), +.I curses +calls +.BR \%wrefresh . .PP -If the window is not a pad, and it has been moved or modified since the last -call to \fBwrefresh\fP, \fBwrefresh\fP will be called before another character -is read. +If +.I ch +is a carriage return and \fBnl\fP(3X) has been called, +.B \%wgetch +returns the character code for newline +(line feed) +instead. .SS "Keypad Mode" -If \fBkeypad\fP is \fBTRUE\fP, and a function key is pressed, the token for -that function key is returned instead of the raw characters: +To +.IR curses , +key strokes not from the alphabetic section of the keyboard +(those corresponding to the ECMA-6 character set\(emsee +\fIascii\fP(7)\(emoptionally modified by either the control or shift +keys) +are treated as +.I function +keys. +(In +.IR curses , +the term \*(``function key\*('' includes but is not limited to keycaps +engraved with \*(``F1\*('', +\*(``PF1\*('', +and so on.) +If the window is in keypad mode, +these produce a numeric code corresponding to the +.B KEY_ +symbols listed in subsection \*(``Predefined Key Codes\*('' below; +otherwise, +they transmit a sequence of codes typically starting with the escape +character, +and which must be collected with multiple +.B \%wgetch +calls. .bP -The predefined function -keys are listed in \fB<curses.h>\fP as macros with values outside the range -of 8-bit characters. -Their names begin with \fBKEY_\fP. +The +.I \%curses.h +header file declares many +.I "predefined function keys" +whose names begin with +.BR KEY_ ; +these object-like macros have values outside the range of eight-bit +character codes. .bP -Other (user-defined) function keys which may be defined -using \fBdefine_key\fP(3X) -have no names, but also are expected to have values outside the range of -8-bit characters. +In +.IR \%ncurses , +.I "user-defined function keys" +are configured with \fBdefine_key\fP(3X); +they have no names, +but are also expected to have values outside the range of eight-bit +codes. .PP -Thus, a variable -intended to hold the return value of a function key must be of short size or -larger. +A variable intended to hold a function key code must thus be of type +.I short +or larger. .PP -When a character that could be the beginning of a function key is received -(which, on modern terminals, means an escape character), -\fBcurses\fP sets a timer. -If the remainder of the sequence does not come in within the designated -time, the character is passed through; -otherwise, the function key value is returned. -For this reason, many terminals experience a delay between the time -a user presses the escape key and the escape is returned to the program. -.PP -In \fI\%ncurses\fP, the timer normally expires after -the value in \fBESCDELAY\fP (see \fBcurs_variables\fP(3X)). -If \fBnotimeout\fP is \fBTRUE\fP, the timer does not expire; -it is an infinite (or very large) value. -Because function keys usually begin with an escape character, -the terminal may appear to hang in notimeout mode after pressing the escape key -until another key is pressed. +Most terminals one encounters follow the ECMA-48 standard insofar as +their function keys produce character sequences prefixed with the +escape character ESC. +This fact implies that +.I curses +cannot know whether the terminal has sent an ESC key stroke or the +beginning of a function key's character sequence without waiting to see +if, +and how soon, +further input arrives. +When +.I curses +reads such an ambiguous character, +it sets a timer. +If the remainder of the sequence does not arrive within the designated +time, +.B \%wgetch +returns the prefix character; +otherwise, +it returns the function key code corresponding to the unique sequence +defined by the terminal. +Consequently, +a user of a +.I curses +application may experience a delay after pressing ESC while +.I curses +disambiguates the input. +See section \*(``EXTENSIONS\*('' below. +If the window is in \*(``no time-out\*('' mode, +the timer does not expire; +it is an infinite +(or very large) +value. +See \fB\%notimeout\fP(3X). +Because function key sequences usually begin with an escape character, +the terminal may appear to hang in no time-out mode after the user has +pressed ESC. +Generally, +further typing \*(``awakens\*('' +.IR curses . .SS "Ungetting Characters" -The \fBungetch\fP routine places \fIch\fP back onto the input queue to be -returned by the next call to \fBwgetch\fP. -There is just one input queue for all windows. +.B \%ungetch +places +.I ch +into the input queue to be returned by the next call to +.BR \%wgetch . +A single input queue serves all windows. .SS "Predefined Key Codes" -The following special keys are defined in \fB<curses.h>\fP. +The header file +.I \%curses.h +defines the following function key codes. .bP -Except for the special case \fBKEY_RESIZE\fP, -it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes. +Except for the special case of +.BR \%KEY_RESIZE , +a window's keypad mode must be enabled for +.B \%wgetch +to read these codes from it. .bP Not all of these are necessarily supported on any particular terminal. .bP -The naming convention may seem obscure, with some apparent -misspellings (such as \*(``RSUME\*('' for \*(``resume\*(''). -The names correspond to the long terminfo capability names for the keys, -and were defined long ago, in the 1980s. +The naming convention may seem obscure, +with some apparent misspellings +(such as \*(``RSUME\*('' for \*(``resume\*(''); +The names correspond to the +.I \%term\%info +capability names for the keys, +and were standardized before the IBM PC/AT keyboard layout achieved a +dominant position in industry. .PP .RS +.\" XXX: Move this list into ncurses(3X), rather than duplicating it in +.\" get_wch(3X) or having that page cross reference this one? .TS -tab(/) ; -l l . -\fBName\fP/\fBKey\fP \fBname\fP -_ -KEY_BREAK/Break key -KEY_DOWN/The four arrow keys ... -KEY_UP -KEY_LEFT -KEY_RIGHT -KEY_HOME/Home key (upward+left arrow) -KEY_BACKSPACE/Backspace -KEY_F0/T{ -Function keys; space for 64 keys is reserved. +Lb Lb +Lb Lx. +Symbol Key name += +KEY_BREAK Break key +KEY_DOWN Arrow keys +KEY_UP \^ +KEY_LEFT \^ +KEY_RIGHT \^ +KEY_HOME Home key (upward+left arrow) +KEY_BACKSPACE Backspace +KEY_F0 T{ +Function keys; space for 64 keys is reserved T} -KEY_F(\fIn\fP)/T{ -For 0 \(<= \fIn\fP \(<= 63 +KEY_F(\fIn\fP) T{ +Function key \fIn\fP where 0 \(<= \fIn\fP \(<= 63 T} -KEY_DL/Delete line -KEY_IL/Insert line -KEY_DC/Delete character -KEY_IC/Insert char or enter insert mode -KEY_EIC/Exit insert char mode -KEY_CLEAR/Clear screen -KEY_EOS/Clear to end of screen -KEY_EOL/Clear to end of line -KEY_SF/Scroll 1 line forward -KEY_SR/Scroll 1 line backward (reverse) -KEY_NPAGE/Next page -KEY_PPAGE/Previous page -KEY_STAB/Set tab -KEY_CTAB/Clear tab -KEY_CATAB/Clear all tabs -KEY_ENTER/Enter or send -KEY_SRESET/Soft (partial) reset -KEY_RESET/Reset or hard reset -KEY_PRINT/Print or copy -KEY_LL/Home down or bottom (lower left) -KEY_A1/Upper left of keypad -KEY_A3/Upper right of keypad -KEY_B2/Center of keypad -KEY_C1/Lower left of keypad -KEY_C3/Lower right of keypad -KEY_BTAB/Back tab key -KEY_BEG/Beg(inning) key -KEY_CANCEL/Cancel key -KEY_CLOSE/Close key -KEY_COMMAND/Cmd (command) key -KEY_COPY/Copy key -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 -KEY_MOUSE/Mouse event occurred -KEY_MOVE/Move key -KEY_NEXT/Next object key -KEY_OPEN/Open key -KEY_OPTIONS/Options key -KEY_PREVIOUS/Previous object key -KEY_REDO/Redo key -KEY_REFERENCE/Ref(erence) key -KEY_REFRESH/Refresh key -KEY_REPLACE/Replace key -KEY_RESIZE/Screen resized -KEY_RESTART/Restart key -KEY_RESUME/Resume key -KEY_SAVE/Save key -KEY_SBEG/Shifted beginning key -KEY_SCANCEL/Shifted cancel key -KEY_SCOMMAND/Shifted command key -KEY_SCOPY/Shifted copy key -KEY_SCREATE/Shifted create key -KEY_SDC/Shifted delete char key -KEY_SDL/Shifted delete line key -KEY_SELECT/Select key -KEY_SEND/Shifted end key -KEY_SEOL/Shifted clear line key -KEY_SEXIT/Shifted exit key -KEY_SFIND/Shifted find key -KEY_SHELP/Shifted help key -KEY_SHOME/Shifted home key -KEY_SIC/Shifted insert key -KEY_SLEFT/Shifted left arrow key -KEY_SMESSAGE/Shifted message key -KEY_SMOVE/Shifted move key -KEY_SNEXT/Shifted next key -KEY_SOPTIONS/Shifted options key -KEY_SPREVIOUS/Shifted prev key -KEY_SPRINT/Shifted print key -KEY_SREDO/Shifted redo key -KEY_SREPLACE/Shifted replace key -KEY_SRIGHT/Shifted right arrow key -KEY_SRSUME/Shifted resume key -KEY_SSAVE/Shifted save key -KEY_SSUSPEND/Shifted suspend key -KEY_SUNDO/Shifted undo key -KEY_SUSPEND/Suspend key -KEY_UNDO/Undo key +KEY_DL Delete line +KEY_IL Insert line +KEY_DC Delete character +KEY_IC Insert character/Enter insert mode +KEY_EIC Exit insert character mode +KEY_CLEAR Clear screen +KEY_EOS Clear to end of screen +KEY_EOL Clear to end of line +KEY_SF Scroll one line forward +KEY_SR Scroll one line backward (reverse) +KEY_NPAGE Next page/Page up +KEY_PPAGE Previous page/Page down +KEY_STAB Set tab +KEY_CTAB Clear tab +KEY_CATAB Clear all tabs +KEY_ENTER Enter/Send +KEY_SRESET Soft (partial) reset +KEY_RESET (Hard) reset +KEY_PRINT Print/Copy +KEY_LL Home down/Bottom (lower left) +KEY_A1 Upper left of keypad +KEY_A3 Upper right of keypad +KEY_B2 Center of keypad +KEY_C1 Lower left of keypad +KEY_C3 Lower right of keypad +KEY_BTAB Back tab key +KEY_BEG Beg(inning) key +KEY_CANCEL Cancel key +KEY_CLOSE Close key +KEY_COMMAND Cmd (command) key +KEY_COPY Copy key +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 +KEY_MOUSE Mouse event occurred +KEY_MOVE Move key +KEY_NEXT Next object key +KEY_OPEN Open key +KEY_OPTIONS Options key +KEY_PREVIOUS Previous object key +KEY_REDO Redo key +KEY_REFERENCE Ref(erence) key +KEY_REFRESH Refresh key +KEY_REPLACE Replace key +KEY_RESIZE Screen resized +KEY_RESTART Restart key +KEY_RESUME Resume key +KEY_SAVE Save key +KEY_SELECT Select key +KEY_SUSPEND Suspend key +KEY_UNDO Undo key +_ +KEY_SBEG Shifted beginning key +KEY_SCANCEL Shifted cancel key +KEY_SCOMMAND Shifted command key +KEY_SCOPY Shifted copy key +KEY_SCREATE Shifted create key +KEY_SDC Shifted delete character key +KEY_SDL Shifted delete line key +KEY_SEND Shifted end key +KEY_SEOL Shifted clear line key +KEY_SEXIT Shifted exit key +KEY_SFIND Shifted find key +KEY_SHELP Shifted help key +KEY_SHOME Shifted home key +KEY_SIC Shifted insert key +KEY_SLEFT Shifted left arrow key +KEY_SMESSAGE Shifted message key +KEY_SMOVE Shifted move key +KEY_SNEXT Shifted next object key +KEY_SOPTIONS Shifted options key +KEY_SPREVIOUS Shifted previous object key +KEY_SPRINT Shifted print key +KEY_SREDO Shifted redo key +KEY_SREPLACE Shifted replace key +KEY_SRIGHT Shifted right arrow key +KEY_SRSUME Shifted resume key +KEY_SSAVE Shifted save key +KEY_SSUSPEND Shifted suspend key +KEY_SUNDO Shifted undo key .TE .RE .PP -Keypad is arranged like this: +The keypad is arranged as follows. .PP .RS .TS -allbox tab(/) ; -c c c . -\fBA1\fP/\fBup\fP/\fBA3\fP -\fBleft\fP/\fBB2\fP/\fBright\fP -\fBC1\fP/\fBdown\fP/\fBC3\fP +allbox center; +C C C. +A1 up A3 +left B2 right +C1 down C3 .TE .RE .sp -A few of these predefined values do \fInot\fP correspond to a real key: +Two of these symbols do +.I not +correspond to a real key. .bP -.B KEY_RESIZE -is returned when the \fBSIGWINCH\fP signal has been detected -(see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X)). -This code is returned whether or not \fBkeypad\fP has been enabled. +.B \%wgetch +returns +.B \%KEY_RESIZE +(even if the window's keypad mode is disabled) +when +.I \%ncurses +detects the +.B \%SIGWINCH +signal; +see \fBinitscr\fP(3X) and \fBresizeterm\fP(3X). .bP -.B KEY_MOUSE -is returned for mouse-events (see \fBcurs_mouse\fP(3X)). -This code relies upon whether or not \fBkeypad\fP(3X) has been enabled, -because -(e.g., -with \fBxterm\fP(1) mouse prototocol) -\fI\%ncurses\fP must read escape sequences, -just like a function key. +.B \%wgetch +returns +.B \%KEY_MOUSE +to indicate that a mouse event is pending collection; +see \fBcurs_mouse\fP(3X). +Receipt of this code requires a window's keypad mode to be enabled, +because to interpret mouse input +(as with with \fIxterm\fP(1)'s mouse prototocol), +.I \%ncurses +must read an escape sequence, +as with a function key. .SS "Testing Key Codes" -The \fBhas_key\fP routine takes a key-code value from the above list, and -returns \fBTRUE\fP or \fBFALSE\fP according to whether -the current terminal type recognizes a key with that value. -.PP -The library also supports these extensions: -.RS 3 -.TP 5 -.B define_key -defines a key-code for a given string (see \fBdefine_key\fP(3X)). -.TP 5 -.B key_defined -checks if there is a key-code defined for a given -string (see \fBkey_defined\fP(3X)). -.RE +In +.IR \%ncurses , +.B \%has_key +takes a key code value from the above list, +and returns a Boolean value indicating the terminal's recognition of it. +See also +\fBdefine_key\fP(3X) and \fBkey_defined\fP(3X). .SH RETURN VALUE -All routines return the integer \fBERR\fP upon failure and an integer value -other than \fBERR\fP (\fBOK\fP in the case of \fBungetch\fP) upon successful -completion. -.RS 3 -.TP 5 -\fBungetch\fP -returns \fBERR\fP -if there is no more room in the FIFO. -.TP -\fBwgetch\fP -returns \fBERR\fP -.RS +.B \%wgetch +returns +.B ERR +if .bP -if the window pointer is null, or +the +.I \%WINDOW +pointer is +.BR NULL , +or .bP -if its timeout expires without having any data, or +its timeout expires without any data arriving, +or .bP -if the execution was interrupted by a signal (\fBerrno\fP will be set to -\fBEINTR\fP). -.RE -.RE +execution was interrupted by a signal, +in which case +.B \%errno +is set to +.BR \%EINTR . +.PP +Functions with a \*(``mv\*('' prefix first perform cursor movement using +\fB\%wmove\fP(3X) and fail if the position is outside the window, +or +(for \*(``mvw\*('' functions) +if the +.I win +parameter is a null pointer. +.PP +.B \%ungetch +returns +.B OK +on success and +.B ERR +if there is no more room in the input queue. .PP -Functions with a \*(``mv\*('' prefix first perform a cursor movement using -\fBwmove\fP, and return an error if the position is outside the window, -or if the window pointer is null. +.B \%has_key +returns +.B TRUE +or +.BR FALSE . .SH NOTES -Use of the escape key by a programmer for a single character function is -discouraged, as it will cause a delay of up to one second while the -keypad code looks for a following function-key sequence. +.I curses +discourages assignment of the ESC key to a discrete function by the +programmer because the library requires a delay while it awaits the +potential remainder of a terminal escape sequence. .PP -Some keys may be the same as commonly used control -keys, e.g., -\fBKEY_ENTER\fP versus control/M, -\fBKEY_BACKSPACE\fP versus control/H. -Some curses implementations may differ according to whether they -treat these control keys specially (and ignore the terminfo), or -use the terminfo definitions. -\fI\%ncurses\fP uses the terminfo definition. -If it says that \fBKEY_ENTER\fP is control/M, -\fBgetch\fP will return \fBKEY_ENTER\fP -when you press control/M. +Some key strokes are indistinguishable from control characters; +for example, +.B \%KEY_ENTER +may be the same as +.BR \*^M , +.\" as with att630 or pccon+keys +and +.B \%KEY_BACKSPACE +may be the same as +.B \*^H +.\" as with att505 or vt52-basic +or +.BR \*^? . +.\" as with pccon+keys or vt320 +Consult the terminal's +.I \%term\%info +entry to determine whether this is the case; +see \fB\%infocmp\fP(1). +Some +.I curses +implementations, +including +.IR \%ncurses , +honor the +.I \%term\%info +key definitions; +others treat such control characters specially. .PP -Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP -key on the numeric keypad: +.I curses +distinguishes the Enter keys in the alphabetic and numeric keypad +sections of a keyboard because (most) terminals do. +.B \%KEY_ENTER +refers to the key on the (numeric) keypad and, +like other function keys, +is reliably recognized only if the window's keypad mode is enabled. .bP -the terminal description lists the most useful keys, +The +.I \%term\%info +.B \%key_enter +.RB ( kent ) +capability describes the character (sequence) sent by the terminal's +keypad Enter key. .bP -the \fIEnter\fP key on the regular keyboard is already handled by -the standard ASCII characters for carriage-return and line-feed, +\*(``Enter or send\*('' is X/Open Curses's description of this key. +.PP +.I curses +treats the Enter or Return key in the +.I alphabetic +section of the keyboard differently. .bP -depending on whether \fBnl\fP or \fBnonl\fP was called, -pressing \*(``Enter\*('' on the regular keyboard -may return either a carriage-return or line-feed, and finally +It usually produces a control code for carriage return +.RB ( \*^M ) +or line feed +.RB ( \*^J ). .bP -\*(``Enter or send\*('' is the standard description for this key. +Depending on the terminal mode +(raw, +cbreak, +or +\*(``cooked\*(''), +and whether \fB\%nl\fP(3X) or \fB\%nonl\fP(3X) has been called, +.B \%wgetch +may return either a carriage return or line feed upon an Enter or Return +key stroke. .PP -When using \fBgetch\fP, \fBwgetch\fP, \fBmvgetch\fP, or -\fBmvwgetch\fP, nocbreak mode (\fBnocbreak\fP) and echo mode -(\fBecho\fP) should not be used at the same time. -Depending on the -state of the tty driver when each character is typed, the program may -produce undesirable results. +Use of +.B \%wgetch +with \fB\%echo\fP(3X) and neither \fB\%cbreak\fP(3X) nor \fB\%raw\fP(3X) +is not well-defined. .PP -Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros. +Historically, +the list of key code macros above was influenced by the +function-key-rich keyboard of the AT&T 7300 +(also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and +\*(``UNIX PC\*(''), +a 1985 machine. +Today's computer keyboards are based on the IBM PC/AT keyboard and tend +to have fewer. +A +.I curses +application can expect such a keyboard to transmit key codes +.BR \%KEY_UP , +.BR \%KEY_DOWN , +.BR \%KEY_LEFT , +.BR \%KEY_RIGHT , +.BR \%KEY_HOME , +.BR \%KEY_END , +.B \%KEY_PPAGE +(Page Up), +.B \%KEY_NPAGE +(Page Down), +.B \%KEY_IC +(Insert), +.B \%KEY_DC +(Delete), +and +.BI \%KEY_F( n ) +for 1 \(<= +.I n +\(<= 12. .PP -Historically, the set of keypad macros was largely defined by the extremely -function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Safari 4. -Modern -personal computers usually have only a small subset of these. -IBM PC-style -consoles typically support little more than \fBKEY_UP\fP, \fBKEY_DOWN\fP, -\fBKEY_LEFT\fP, \fBKEY_RIGHT\fP, \fBKEY_HOME\fP, \fBKEY_END\fP, -\fBKEY_NPAGE\fP, \fBKEY_PPAGE\fP, and function keys 1 through 12. -The Ins key -is usually mapped to \fBKEY_IC\fP. +.BR \%getch , +.BR \%mvgetch , +and +.B \%mvwgetch +may be implemented as macros. .SH EXTENSIONS +In +.IR \%ncurses , +when a window's \*(``no time-out\*('' mode is +.I not +set, +the +.B \%ESCDELAY +variable configures the duration of the timer used to disambiguate a +function key character sequence from a series of key strokes beginning +with ESC typed by the user; +see +\fB\%curs_variables\fP(3X). +.PP \fB\%has_key\fP was designed for \fB\%ncurses\fP(3X), and is not found in SVr4 .IR curses , @@ -389,32 +604,50 @@ extensions should condition their use on the visibility of the .B \%NCURSES_VERSION preprocessor macro. .PP -X/Open Curses, Issue 4, Version 2, describes +X/Open Curses, Issue 4, describes \fB\%getch\fP, \fB\%wgetch\fP, \fB\%mvgetch\fP, \fB\%mvwgetch\fP, and \fB\%ungetch\fP. -They read single-byte characters only. -The standard specifies that they return \fBERR\fP on failure, -but describes no failure conditions. +It specifies no error conditions for them. +.PP +.B \%wgetch +reads only single-byte characters. .PP The echo behavior of these functions on input of .B KEY_ or backspace characters was not specified in the SVr4 documentation. This description is adapted from X/Open Curses. .PP -The behavior of \fBgetch\fP and friends in the presence of signal -handlers is unspecified in the SVr4 documentation and X/Open Curses. -Under historical curses implementations, +The behavior of +.B \%wgetch +in the presence of signal handlers is unspecified in the SVr4 +documentation and X/Open Curses. +In historical +.I curses +implementations, it varied depending on whether the operating system's dispatch of a -signal to a handler interrupts a \fBread\fP(2) call in progress or not, +signal to a handler interrupts a \fIread\fP(2) call in progress or not, and also (in some implementations) whether an input timeout or non-blocking mode has been set. +Programmers concerned about portability should be prepared for either of +two cases: +(a) signal receipt does not interrupt +.BR \%wgetch ; +or +(b) signal receipt interrupts +.B \%wgetch +and causes it to return +.B ERR +with +.B \%errno +set to +.BR \%EINTR . .PP -.B KEY_MOUSE +.B \%KEY_MOUSE is mentioned in X/Open Curses, along with a few related .I \%term\%info @@ -424,31 +657,41 @@ The implementation in .I \%ncurses is an extension. .PP -.B KEY_RESIZE -is an extension first implemented for -.I \%ncurses. +.B \%KEY_RESIZE +and +.B \%has_key +are extensions first implemented for +.IR \%ncurses . +By 2022, +.I \%PDCurses +.\" https://web.archive.org/web/20220117232009/https://pdcurses.org/docs/MANUAL.html +and NetBSD .I curses -later added this extension. -.PP -Programmers concerned about portability should be prepared for either of two -cases: (a) signal receipt does not interrupt \fBgetch\fP; (b) signal receipt -interrupts \fBgetch\fP and causes it to return \fBERR\fP with \fBerrno\fP set to -\fBEINTR\fP. -.PP -The \fBhas_key\fP function is unique to \fI\%ncurses\fP. -We recommend that -any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro. +.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3 +had added them along with +.BR \%KEY_MOUSE . .SH SEE ALSO \fB\%curses\fP(3X), +\fB\%curs_addch\fP(3X), \fB\%curs_inopts\fP(3X), \fB\%curs_mouse\fP(3X), \fB\%curs_move\fP(3X), \fB\%curs_outopts\fP(3X), \fB\%curs_refresh\fP(3X), \fB\%curs_variables\fP(3X), -\fB\%resizeterm\fP(3X) +\fB\%resizeterm\fP(3X), +\fB\%ascii\fP(7) +.PP +\fB\%curs_get_wch\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI ( \%ncursesw ). +.PP +ECMA-6 \*(``7-bit coded Character Set\*('' +\%<https://\*:ecma\-international\*:.org/\ +\*:publications\-and\-standards/\*:standards/\*:ecma\-6/> .PP -Comparable functions in the wide-character (ncursesw) library are -described in -\fB\%curs_get_wch\fP(3X). +ECMA-48 \*(``Control Functions for Coded Character Sets\*('' +\%<https://\*:ecma\-international\*:.org/\ +\*:publications\-and\-standards/\*:standards/\*:ecma\-48/> |