X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=07d5456206d697c7947eaa8463f1861295ffd7a2;hp=092c8b78d4f90d428fc874239241f23e74ba592e;hb=74433bcf4f6fe40862a28f3c00edaedcd5054b01;hpb=3a9b6a3bf0269231bef7de74757a910dedd04e0c diff --git a/man/curs_getch.3x b/man/curs_getch.3x index 092c8b78..07d54562 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,75 +1,164 @@ -.\" $Id: curs_getch.3x,v 1.10 1997/01/05 11:57:54 Jesse.Thilo Exp $ +'\" t +.\"*************************************************************************** +.\" Copyright 2018-2020,2021 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_getch.3x,v 1.61 2021/12/25 21:49:32 tom Exp $ .TH curs_getch 3X "" +.na +.hy 0 +.ie \n(.g .ds `` \(lq +.el .ds `` `` +.ie \n(.g .ds '' \(rq +.el .ds '' '' +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. .SH NAME -\fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, -\fBmvwgetch\fR, \fBungetch\fR - get (or push back) characters from -\fBcurses\fR terminal keyboard +\fBgetch\fP, +\fBwgetch\fP, +\fBmvgetch\fP, +\fBmvwgetch\fP, +\fBungetch\fP, +\fBhas_key\fP \- get (or push back) characters from \fBcurses\fP terminal keyboard +.ad +.hy .SH SYNOPSIS -\fB#include \fR - -\fBint getch(void);\fR +\fB#include \fP +.PP +\fBint getch(void);\fP .br -\fBint wgetch(WINDOW *win);\fR -.br -\fBint mvgetch(int y, int x);\fR -.br -\fBint mvwgetch(WINDOW *win, int y, int x);\fR +\fBint wgetch(WINDOW *\fP\fIwin);\fP +.sp +\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP .br -\fBint ungetch(int ch);\fR +\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fP +.sp +\fBint ungetch(int \fP\fIch\fP\fB);\fP +.sp +/* extension */ .br -\fBint has_key(int ch);\fR +\fBint has_key(int \fP\fIch\fP\fB);\fP .br .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 +.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. - -If \fBnoecho\fR has been set, then the character will also be echoed into the +.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\fR had been called. -If the character value is any other \fBKEY_\fR define, the user is alerted -with a \fBbeep\fR call. +as if \fBdelch\fP had been called. +.bP +If the character value is any other \fBKEY_\fP define, the user is alerted +with a \fBbeep\fP call. +.bP +If the character is a carriage-return, +and if \fBnl\fP is enabled, +it is translated to a line-feed after echoing. +.bP Otherwise the character is simply output to the screen. - +.PP 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 +call to \fBwrefresh\fP, \fBwrefresh\fP 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 +.SS Keypad mode +.PP +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: +.bP +The predefined function +keys are listed in \fB\fP as macros with values outside the range +of 8-bit characters. +Their names begin with \fBKEY_\fP. +.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. +.PP +Thus, a variable intended to hold the return value of a function key must be of short size 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\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 +(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. - -The \fBungetch\fR routine places \fIch\fR back onto the input queue to be -returned by the next call to \fBwgetch\fR. Note that there is, in effect, -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 +.PP +In \fBncurses\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. +.SS Ungetting characters +.PP +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. +.PP +.SS Predefined key-codes +The following special keys are defined in \fB\fP. +.bP +Except for the special case \fBKEY_RESIZE\fP, +it is necessary to enable \fBkeypad\fP for \fBgetch\fP to return these codes. +.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. +.PP .TS center tab(/) ; -l l l l . -\fIName\fR/\fIKey\fR \fIname\fR - +\fBName\fP/\fBKey\fP \fBname\fP +_ KEY_BREAK/Break key KEY_DOWN/The four arrow keys ... KEY_UP @@ -80,8 +169,8 @@ 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{ +For 0 \(<= \fIn\fP \(<= 63 T} KEY_DL/Delete line KEY_IL/Insert line @@ -102,7 +191,7 @@ 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_LL/Home down or bottom (lower left) KEY_A1/Upper left of keypad KEY_A3/Upper right of keypad KEY_B2/Center of keypad @@ -121,6 +210,7 @@ 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 @@ -130,6 +220,7 @@ 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 @@ -165,75 +256,163 @@ KEY_SUNDO/Shifted undo key KEY_SUSPEND/Suspend key KEY_UNDO/Undo key .TE - +.PP Keypad is arranged like this: -.sp +.br .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 +\fBA1\fP/\fBup\fP/\fBA3\fP +\fBleft\fP/\fBB2\fP/\fBright\fP +\fBC1\fP/\fBdown\fP/\fBC3\fP .TE .sp -The \fBhas_key\fR routine takes a key value from the above list, and -returns TRUE or FALSE according as the current terminal type recognizes -a key with that value. - +A few of these predefined values do \fInot\fP 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. +.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) ncurses must +read escape sequences, +just like a function key. +.SS Testing key-codes +.PP +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 +.PP .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 +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 +if the window pointer is null, or +if its timeout expires without having any data, or +if the execution was interrupted by a signal (\fBerrno\fP will be set to +\fBEINTR\fP). +.RE +.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. .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. - -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 +.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. +\fBNcurses\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. +.PP +Generally, \fBKEY_ENTER\fP denotes the character(s) sent by the \fIEnter\fP +key on the numeric keypad: +.bP +the terminal description lists the most useful keys, +.bP +the \fIEnter\fP key on the regular keyboard is already handled by +the standard ASCII characters for carriage-return and line-feed, +.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 +.bP +\*(``Enter or send\*('' is the standard description for this key. +.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. - -Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR may be macros. - +.PP +Note that \fBgetch\fP, \fBmvgetch\fP, and \fBmvwgetch\fP may be macros. +.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\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. +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. .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 +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\fP on failure, but specifies no error conditions. +.PP +The echo behavior of these functions on input of \fBKEY_\fP 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 +.PP +The behavior of \fBgetch\fP 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 +implementation of handled signal receipt interrupts a \fBread\fP(2) call in progress or not, and also (in some implementations) depending on whether an -input timeout or non-blocking mode hsd been set. - +input timeout or non-blocking mode has been set. +.PP +\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related +terminfo capabilities, but no higher-level functions use the feature. +The implementation in ncurses is an extension. +.PP +\fBKEY_RESIZE\fP is an extension first implemented for ncurses. +NetBSD 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\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 NCURSES feature macro. +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 \fBncurses\fP. +We recommend that +any code using it be conditionalized on the \fBNCURSES_VERSION\fP feature macro. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_inopts\fR(3X), \fBcurs_move\fR(3X), -\fBcurs_refresh\fR(3X). -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fBcurses\fP(3X), +\fBcurs_inopts\fP(3X), +\fBcurs_mouse\fP(3X), +\fBcurs_move\fP(3X), +\fBcurs_outopts\fP(3X), +\fBcurs_refresh\fP(3X), +\fBcurs_variables\fP(3X), +\fBresizeterm\fP(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_get_wch\fP(3X).