X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=a8c4bc1f080b7d1ab9396336c55d55f20c233285;hb=HEAD;hp=73e1a29679b1f4c9814ca3f37993495fd4057254;hpb=46722468f47c2b77b3987729b4bcf2321cccfd01;p=ncurses.git diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 73e1a296..a66e68a2 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,6 +1,7 @@ '\" t .\"*************************************************************************** -.\" Copyright (c) 1998-2001,2002 Free Software Foundation, Inc. * +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2016,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -27,279 +28,686 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getch.3x,v 1.21 2002/03/17 14:36:21 tom Exp $ -.TH curs_getch 3X "" +.\" $Id: curs_getch.3x,v 1.97 2024/06/08 20:26:46 tom Exp $ +.TH curs_getch 3X 2024-06-08 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "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 +.. .SH NAME -\fBgetch\fR, -\fBwgetch\fR, -\fBmvgetch\fR, -\fBmvwgetch\fR, -\fBungetch\fR, -\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard +\fB\%getch\fP, +\fB\%wgetch\fP, +\fB\%mvgetch\fP, +\fB\%mvwgetch\fP, +\fB\%ungetch\fP, +\fB\%has_key\fP \- +get (or push back) characters from \fIcurses\fR terminal keyboard .SH SYNOPSIS -\fB#include \fR - -\fBint getch(void);\fR -.br -\fBint wgetch(WINDOW *win);\fR -.br -\fBint mvgetch(int y, int x);\fR -.br -\fBint mvwgetch(WINDOW *win, int y, int x);\fR -.br -\fBint ungetch(int ch);\fR -.br -\fBint has_key(int ch);\fR -.br +.nf +.B #include +.PP +.B int getch(void); +.B int wgetch(WINDOW *\fIwin\fP); +.B int mvgetch(int \fIy\fP, int \fIx\fP); +.B int mvwgetch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP); +.PP +.B int ungetch(int \fIc\fP); +.PP +.\" XXX: Move has_key into its own page like define_key and key_defined? +\fI/* extension */\fP +.B int has_key(int \fIc\fP); +.fi .SH DESCRIPTION -The \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR and \fBmvwgetch\fR, routines read -a character from the window. -In no-delay mode, if no input is waiting, the value \fBERR\fR is returned. -In delay mode, the program waits until the system -passes text through to the program. -Depending on the setting of \fBcbreak\fR, -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. - -Unless \fBnoecho\fR has been set, -then the character will also be echoed into the -designated window according to the following rules: -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\fR had been called. -If the character value is any other \fBKEY_\fR define, the user is alerted -with a \fBbeep\fR call. -Otherwise the character is simply output to the screen. - -If the window is not a pad, and it has been moved or modified since the last -call to \fBwrefresh\fR, \fBwrefresh\fR will be called before another character -is read. - -If \fBkeypad\fR is \fBTRUE\fR, and a function key is pressed, the token for -that function key is returned instead of the raw characters. -Possible function -keys are defined in \fB\fR as macros with values outside the range -of 8-bit characters whose names begin with \fBKEY_.\fR Thus, a variable -intended to hold the return value of a function key must be of short size or -larger. - -When a character that could be the beginning of a function key is received -(which, on modern terminals, means an escape character), -\fBcurses\fR 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. - -The \fBungetch\fR routine places \fIch\fR back onto the input queue to be -returned by the next call to \fBwgetch\fR. -There is just one input queue for all windows. - -.SS Function Keys -The following function keys, defined in \fB\fR, might be returned by -\fBgetch\fR if \fBkeypad\fR has been enabled. -Note that not all of these are -necessarily supported on any particular terminal. -.sp +.SS "Reading Characters" +.B \%wgetch +gathers a key event from the terminal keyboard associated with a +.I curses +window +.IR win "." +\fB\%ncurses\fP(3X) describes the variants of this function. +.PP +When input is pending, +.B \%wgetch +returns an integer identifying the key event; +for alphanumeric and punctuation keys, +this value corresponds to the character encoding used by the terminal. +Use of the control key as a modifier, +by holding it down while pressing and releasing another key, +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) or \fB\%noraw\fP(3X) +has been called, +it occurs when the next newline is read. +(Because the terminal's normal or \*(``cooked\*('' mode +is line-buffered, +multiple +.B \%wgetch +calls may then be necessary to empty the input queue.) +If \fB\%halfdelay\fP(3X) +has been called, +.I curses +waits until input is available 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 c +to the window +(at the cursor position) +per the following rules. +.bP +If +.I c +matches the terminal's erase character +(see \fB\%erasechar\fP(3X)), +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 +.I curses +writes any other +.I c +to the window, +as with \fB\%wechochar\fP(3X). +.bP +If the window +.I win +has been moved or modified since the last call to +\fB\%wrefresh\fP(3X), +.I curses +calls +.B \%wrefresh +on it. +.PP +If +.I c +is a carriage return and \fBnl\fP(3X) has been called, +.B \%wgetch +returns the character code for line feed instead. +.SS "Keypad Mode" +To +.IR curses "," +key strokes not from the alphabetic section of the keyboard +(those corresponding to the ECMA-6 character set\(emsee +\fI\%ascii\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 +.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 +In +.IR \%ncurses "," +.I "user-defined function keys" +are configured with \fB\%define_key\fP(3X); +they have no names, +but are also expected to have values outside the range of eight-bit +codes. +.PP +A variable intended to hold a function key code must thus be of type +.I short +or larger. +.PP +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 distinguish a user's press of the escape key +(assuming it sends ESC) +from 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 the escape key is pressed +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 ESC, +the terminal may appear to hang in no time-out mode after the user +presses the escape key. +Generally, +further typing \*(``awakens\*('' +.IR curses "." +.SS "Ungetting Characters" +.B \%ungetch +places +.I c +into the input queue to be returned by the next call to +.BR \%wgetch "." +A single input queue serves all windows associated with the terminal. +.SS "Predefined Key Codes" +The header file +.I \%curses.h +defines the following function key codes. +.bP +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 +.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 -center tab(/) ; -l l -l l . -\fIName\fR/\fIKey\fR \fIname\fR - -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\fR)/T{ -For 0 \(<= \fIn\fR \(<= 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 read -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 input 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_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 - -Keypad is arranged like this: -.sp +.RE +.PP +Many keyboards feature a nine-key directional pad. +.PP +.RS .TS -center allbox tab(/) ; -c c c . -\fBA1\fR/\fBup\fR/\fBA3\fR -\fBleft\fR/\fBB2\fR/\fBright\fR -\fBC1\fR/\fBdown\fR/\fBC3\fR +allbox center; +C C C. +A1 up A3 +left B2 right +C1 down C3 .TE +.RE .sp -The \fBhas_key\fR routine takes a key value from the above list, and -returns TRUE or FALSE according to whether -the current terminal type recognizes a key with that value. - +Two of the symbols in the list above do +.I not +correspond to a physical key. +.bP +.B \%wgetch +returns +.BR \%KEY_RESIZE "," +even if the window's keypad mode is disabled, +if +.I \%ncurses +has handled a +.B \%SIGWINCH +signal since +.B \%wgetch +was called; +see \fB\%initscr\fP(3X) and \fB\%resizeterm\fP(3X). +.bP +.B \%wgetch +returns +.B \%KEY_MOUSE +to indicate that a mouse event is pending collection; +see \fB\%curs_mouse\fP(3X). +Receipt of this code requires a window's keypad mode to be enabled, +because to interpret mouse input +(as with with \fI\%xterm\fP(1)'s mouse protocol), +.I \%ncurses +must read an escape sequence, +as with a function key. +.SS "Testing Key Codes" +In +.IR \%ncurses "," +.B \%has_key +returns a Boolean value indicating whether the terminal type recognizes +its parameter as a key code value. +See also +\fB\%define_key\fP(3X) and \fB\%key_defined\fP(3X). .SH RETURN VALUE -All routines return the integer \fBERR\fR upon failure and an integer value -other than \fBERR\fR (\fBOK\fR in the case of ungetch()) upon successful -completion. +Except for +.BR \%has_key "," +these functions return +.B OK +on success and +.B ERR +on failure. +.PP +Functions taking a +.I \%WINDOW +pointer argument fail if the pointer is +.BR NULL "." +.PP +Functions prefixed with \*(``mv\*('' first perform cursor movement and +fail if the position +.RI ( y , +.IR x ")" +is outside the window boundaries. +.PP +.B \%wgetch +also fails if +.bP +its timeout expires without any data arriving, +or +.bP +execution was interrupted by a signal, +in which case +.B \%errno +is set to +.BR \%EINTR "." +.PP +.B \%ungetch +fails if there is no more room in the input queue. +.PP +.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. - -Note that some keys may be the same as commonly used control -keys, e.g., KEY_ENTER versus control/M, KEY_BACKSPACE 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. -\fBNcurses\fR uses the terminfo definition. -If it says that KEY_ENTER is control/M, \fBgetch\fR, will return KEY_ENTER -when you press control/M. - -When using \fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, or -\fBmvwgetch\fR, nocbreak mode (\fBnocbreak\fR) and echo mode -(\fBecho\fR) 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. - -Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros. - -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\fR, \fBKEY_DOWN\fR, -\fBKEY_LEFT\fR, \fBKEY_RIGHT\fR, \fBKEY_HOME\fR, \fBKEY_END\fR, -\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. -The Ins key -is usually mapped to \fBKEY_IC\fR. +.BR \%getch "," +.BR \%mvgetch "," +and +.B \%mvwgetch +may be implemented as macros. +.PP +.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 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 +.I \%term\%info +entry for the terminal type 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 +.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 +.I \%term\%info +.B \%key_enter +.RB ( kent ) +capability describes the character (sequence) sent by the Enter key of +a terminal's numeric +(or similar) +keypad. +.bP +\*(``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 +It usually produces a control code for carriage return +.RB ( \*^M ) +or line feed +.RB ( \*^J ). +.bP +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 +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 +Historically, +the list of key code macros above was influenced by the keyboard of the +AT&T 7300 +(also known variously as the \*(``3B1\*('', \*(``Safari 4\*('', and +\*(``UNIX PC\*(''), +a 1985 machine rich in function keys. +Today's computer keyboards are based on that of the IBM PC/AT +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. +.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 +.B \%has_key +was designed for +.IR \%ncurses "," +and is not found in SVr4 +.IR curses "," +4.4BSD +.IR curses "," +or any other previous +.I curses +implementation. .SH PORTABILITY -The *get* functions are described in the XSI Curses standard, Issue 4. -They -read single-byte characters only. -The standard specifies that they return -\fBERR\fR on failure, but specifies no error conditions. - -The echo behavior of these functions on input of \fBKEY_\fR or backspace -characters was not specified in the SVr4 documentation. -This description is -adopted from the XSI Curses standard. - -The behavior of \fBgetch\fR and friends in the presence of handled signals is -unspecified in the SVr4 and XSI Curses documentation. -Under historical curses -implementations, it varied depending on whether the operating system's -implementation of handled signal receipt interrupts a \fBread\fR(2) call in -progress or not, and also (in some implementations) depending on whether an -input timeout or non-blocking mode hsd been set. - -Programmers concerned about portability should be prepared for either of two -cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt -interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to -\fBEINTR\fR. -Under the \fBncurses\fR implementation, handled signals never -interrupt \fBgetch\fR. - -The \fBhas_key\fR function is unique to \fBncurses\fR. -We recommend that -any code using it be conditionalized on the \fBNCURSES_VERSION\fR feature macro. +Applications employing +.I \%ncurses +extensions should condition their use on the visibility of the +.B \%NCURSES_VERSION +preprocessor macro. +.PP +Except as noted in section \*(``EXTENSIONS\*('' above, +X/Open Curses, +Issue 4 describes these functions. +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 is not documented in SVr4 +.IR curses "." +.PP +The behavior of +.B \%wgetch +in the presence of signal handlers is not documented in SVr4 +.I curses +and is unspecified by X/Open Curses. +In historical +.I curses +implementations, +it varied depending on whether the operating system's dispatch of a +signal to a handler interrupted a \fIread\fP(2) call in progress, +and also +(in some implementations) +whether an input timeout or non-blocking mode had been set. +A portable +.I curses +application prepares for 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 +is mentioned in X/Open Curses, +along with a few related +.I \%term\%info +capabilities, +but no higher-level functions use the feature. +The implementation in +.I \%ncurses +is an extension. +.PP +.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 +.\" https://web.archive.org/web/20200923185647/https://man.netbsd.org/curses_input.3 +had added them along with +.BR \%KEY_MOUSE "." .SH SEE ALSO -\fBcurses\fR(3X), -\fBcurs_inopts\fR(3X), -\fBcurs_mouse\fR(3X), -\fBcurs_move\fR(3X), -\fBcurs_refresh\fR(3X). -\fBresizeterm\fR(3X). -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +ECMA-6 \*(``7-bit coded Character Set\*('' +\% +.PP +ECMA-48 \*(``Control Functions for Coded Character Sets\*('' +\% +.PP +\fB\%curs_get_wch\fP(3X) describes comparable functions of the +.I \%ncurses +library in its wide-character configuration +.RI \%( ncursesw ). +.PP +\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\%ascii\fP(7)