X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getch.3x.html;h=76b20e49b4e9b4eb6a325dd912700594aa88f99f;hp=833b88e6ba33edb39e18269b9bdce5cc33365aaf;hb=refs%2Ftags%2Fv5.3;hpb=c633e5103a29a38532cf1925257b91cea33fd090 diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index 833b88e6..76b20e49 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,62 +1,101 @@ + + +
+- getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get - (or push back) characters from curses terminal keyboard + getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get + (or push back) characters from curses terminal keyboard
- #include <curses.h> + #include <curses.h> - int getch(void); - int wgetch(WINDOW *win); - int mvgetch(int y, int x); - int mvwgetch(WINDOW *win, int y, int x); - int ungetch(int ch); - int has_key(int ch); + int getch(void); + int wgetch(WINDOW *win); + int mvgetch(int y, int x); + int mvwgetch(WINDOW *win, int y, int x); + int ungetch(int ch); + int has_key(int ch);
- The getch, wgetch, mvgetch and mvwgetch, routines read a + The getch, wgetch, mvgetch and mvwgetch, routines read a character from the window. In no-delay mode, if no input - is waiting, the value ERR is returned. In delay mode, the + is waiting, the value ERR is returned. In delay mode, the program waits until the system passes text through to the - program. Depending on the setting of cbreak, this is + program. Depending on the setting of cbreak, this is after one character (cbreak mode), or after the first new- line (nocbreak mode). In half-delay mode, the program waits until a character is typed or the specified timeout has been reached. - Unless noecho has been set, then the character will also + Unless noecho has been set, then the character will also be echoed into the designated window according to the fol- lowing rules: If the character is the current erase char- acter, left arrow, or backspace, the cursor is moved one space to the left and that screen position is erased as if - delch had been called. If the character value is any - other KEY_ define, the user is alerted with a beep call. + delch had been called. If the character value is any + other KEY_ define, the user is alerted with a beep call. Otherwise the character is simply output to the screen. If the window is not a pad, and it has been moved or modi- - fied since the last call to wrefresh, wrefresh will be + fied since the last call to wrefresh, wrefresh will be called before another character is read. - If keypad is TRUE, and a function key is pressed, the + If keypad is TRUE, 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 - <curses.h> as macros with values outside the range of - 8-bit characters whose names begin with KEY_. Thus, a + <curses.h> as macros with values outside the range of + 8-bit characters whose names begin with KEY_. 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), curses sets a timer. If the remainder + escape character), curses 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 @@ -64,18 +103,18 @@ presses the escape key and the escape is returned to the program. - The ungetch routine places ch back onto the input queue to - be returned by the next call to wgetch. Note that there - is, in effect, just one input queue for all windows. + The ungetch routine places ch back onto the input queue to + be returned by the next call to wgetch. There is just one + input queue for all windows. - Function Keys - The following function keys, defined in <curses.h>, might - be returned by getch if keypad has been enabled. Note + Function Keys + The following function keys, defined in <curses.h>, might + be returned by getch if keypad has been enabled. Note that not all of these are necessarily supported on any particular terminal. - Name Key name + Name Key name KEY_BREAK Break key KEY_DOWN The four arrow keys ... @@ -86,7 +125,7 @@ KEY_BACKSPACE Backspace KEY_F0 Function keys; space for 64 keys is reserved. - KEY_F(n) For 0 <= n <= 63 + KEY_F(n) For 0 <= n <= 63 KEY_DL Delete line KEY_IL Insert line KEY_DC Delete character @@ -176,22 +215,22 @@ Keypad is arranged like this: +-----+------+-------+ - | A1 | up | A3 | + | A1 | up | A3 | +-----+------+-------+ - |left | B2 | right | + |left | B2 | right | +-----+------+-------+ - | C1 | down | C3 | + | C1 | down | C3 | +-----+------+-------+ - The has_key routine takes a key value from the above list, - and returns TRUE or FALSE according as the current termi- - nal type recognizes a key with that value. + The has_key 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.
- All routines return the integer ERR upon failure and an - integer value other than ERR (OK in the case of ungetch()) + All routines return the integer ERR upon failure and an + integer value other than ERR (OK in the case of ungetch()) upon successful completion. @@ -202,70 +241,70 @@ up to one second while the keypad code looks for a follow- ing function-key sequence. - When using getch, wgetch, mvgetch, or mvwgetch, nocbreak - mode (nocbreak) and echo mode (echo) 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 + Note that some keys may be the same as commonly used con- + trol 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 spe- + cially (and ignore the terminfo), or use the terminfo def- + initions. Ncurses uses the terminfo definition. If it + says that KEY_ENTER is control/M, getch, will return + KEY_ENTER when you press control/M. + + When using getch, wgetch, mvgetch, or mvwgetch, nocbreak + mode (nocbreak) and echo mode (echo) 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 getch, mvgetch, and mvwgetch may be macros. + Note that getch, mvgetch, and mvwgetch 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 KEY_UP, - KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, - KEY_NPAGE, KEY_PPAGE, and function keys 1 through 12. The - Ins key is usually mapped to KEY_IC. + 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 KEY_UP, + KEY_DOWN, KEY_LEFT, KEY_RIGHT, KEY_HOME, KEY_END, + KEY_NPAGE, KEY_PPAGE, and function keys 1 through 12. The + Ins key is usually mapped to KEY_IC.
- The *get* functions are described in the XSI Curses stan- - dard, Issue 4. They read single-byte characters only. - The standard specifies that they return ERR on failure, + The *get* functions are described in the XSI Curses stan- + dard, Issue 4. They read single-byte characters only. + The standard specifies that they return ERR on failure, but specifies no error conditions. - The echo behavior of these functions on input of KEY_ or - backspace characters was not specified in the SVr4 docu- - mentation. This description is adopted from the XSI + The echo behavior of these functions on input of KEY_ or + backspace characters was not specified in the SVr4 docu- + mentation. This description is adopted from the XSI Curses standard. - The behavior of getch and friends in the presence of han- - dled 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 - read(2) call in progress or not, and also (in some imple- - mentations) depending on whether an input timeout or non- + The behavior of getch and friends in the presence of han- + dled 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 + read(2) call in progress or not, and also (in some imple- + mentations) 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 getch; (b) signal receipt interrupts getch and - causes it to return ERR with errno set to EINTR. Under - the ncurses implementation, handled signals never inter- - rupt getch. + for either of two cases: (a) signal receipt does not + interrupt getch; (b) signal receipt interrupts getch and + causes it to return ERR with errno set to EINTR. Under + the ncurses implementation, handled signals never inter- + rupt getch. - The has_key function is unique to ncurses. We recommend - that any code using it be conditionalized on the - NCURSES_VERSION feature macro. + The has_key function is unique to ncurses. We recommend + that any code using it be conditionalized on the + NCURSES_VERSION feature macro.
- curses(3x), curs_inopts(3x), curs_mouse(3x), - curs_move(3x), curs_refresh(3x). resizeterm(3x). - - - - - - - - - + curses(3x), curs_inopts(3x), curs_mouse(3x), + curs_move(3x), curs_refresh(3x). resizeterm(3x).