X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=71fed5f7b60d6134afe5de9fe79a1b233a7d604c;hp=c621338a951ec372e3c196e9189121542c791124;hb=d803343ca3e2a419085e76fc9f04a6fbd14498b8;hpb=661078ddbde3ce0f3b06e95642fbb9b5fef7dca1 diff --git a/man/curs_getch.3x b/man/curs_getch.3x index c621338a..71fed5f7 100644 --- a/man/curs_getch.3x +++ b/man/curs_getch.3x @@ -1,13 +1,48 @@ '\" t -.\" $Id: curs_getch.3x,v 1.12 1997/12/13 22:39:05 tom Exp $ +.\"*************************************************************************** +.\" Copyright (c) 1998-2005,2006 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.30 2006/12/02 17:02:53 tom Exp $ .TH curs_getch 3X "" +.na +.hy 0 .SH NAME -\fBgetch\fR, \fBwgetch\fR, \fBmvgetch\fR, -\fBmvwgetch\fR, \fBungetch\fR - get (or push back) characters from -\fBcurses\fR terminal keyboard +\fBgetch\fR, +\fBwgetch\fR, +\fBmvgetch\fR, +\fBmvwgetch\fR, +\fBungetch\fR, +\fBhas_key\fR \- get (or push back) characters from \fBcurses\fR terminal keyboard +.ad +.hy .SH SYNOPSIS \fB#include \fR - +.PP \fBint getch(void);\fR .br \fBint wgetch(WINDOW *win);\fR @@ -22,14 +57,19 @@ .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 +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. - -If \fBnoecho\fR has been set, then the character will also be echoed into the +.PP +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 @@ -37,32 +77,36 @@ 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. - +.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 is read. - +.PP 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 +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 +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. - +.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\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. - +.PP 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. - +returned by the next call to \fBwgetch\fR. +There is just one input queue for all windows. +.PP .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 +\fBgetch\fR if \fBkeypad\fR has been enabled. +Note that not all of these are necessarily supported on any particular terminal. .sp .TS @@ -70,7 +114,6 @@ center tab(/) ; l l l l . \fIName\fR/\fIKey\fR \fIname\fR - KEY_BREAK/Break key KEY_DOWN/The four arrow keys ... KEY_UP @@ -103,7 +146,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 @@ -168,7 +211,7 @@ KEY_SUNDO/Shifted undo key KEY_SUSPEND/Suspend key KEY_UNDO/Undo key .TE - +.PP Keypad is arranged like this: .sp .TS @@ -180,64 +223,103 @@ c c c . .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. - +returns TRUE or FALSE according to whether +the current terminal type recognizes a key with that value. +Note that a few values do not correspond to a real key, +e.g., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP. +See \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and +\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP. +.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 completion. +.RS +.TP 5 +\fBungetch\fP +returns an error +if there is no more room in the FIFO. +.TP 5 +\fBwgetch\fP +returns an error +if the window pointer is null, or +if its timeout expires without having any data. +.RE .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. - +.PP +Note that 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\fR uses the terminfo definition. +If it says that \fBKEY_ENTER\fP is control/M, +\fBgetch\fR will return \fBKEY_ENTER\fP +when you press control/M. +.PP 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 +(\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. - +.PP Note that \fBgetch\fR, \fBmvgetch\fR, and \fBmvwgetch\fR 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 +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 +\fBKEY_NPAGE\fR, \fBKEY_PPAGE\fR, and function keys 1 through 12. +The Ins key is usually mapped to \fBKEY_IC\fR. .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 +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. - +.PP The echo behavior of these functions on input of \fBKEY_\fR or backspace -characters was not specified in the SVr4 documentation. This description is +characters was not specified in the SVr4 documentation. +This description is adopted from the XSI Curses standard. - +.PP 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 +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. - +input timeout or non-blocking mode has been set. +.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 +\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 +.PP +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. .SH SEE ALSO \fBcurses\fR(3X), \fBcurs_inopts\fR(3X), \fBcurs_mouse\fR(3X), \fBcurs_move\fR(3X), -\fBcurs_refresh\fR(3X). +\fBcurs_refresh\fR(3X), \fBresizeterm\fR(3X). +.PP +Comparable functions in the wide-character (ncursesw) library are +described in +\fBcurs_get_wch\fR(3X). .\"# .\"# The following sets edit modes for GNU EMACS .\"# Local Variables: