X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getch.3x.html;h=9b3bdc42ace740ac19afab4f0338722043e7e989;hb=6a530b46563470c2ca73579d1994a0c8e275dd98;hp=70553d2ef6dc5757ac799b7fa085f8fa17c78fc2;hpb=c6cfd97b8beaf0f6deafbf8aac7281cf6aa7f012;p=ncurses.git diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index 70553d2e..9b3bdc42 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,7 +1,7 @@ @@ -39,8 +39,7 @@
-curs_getch(3x) curs_getch(3x) @@ -58,15 +57,18 @@ #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 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 character from the window. In no-delay mode, if no input is waiting, the value ERR is returned. In delay mode, the @@ -100,6 +102,9 @@ 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 to- ken for that function key is returned instead of the raw characters. Possible function keys are defined in <curs- @@ -117,17 +122,20 @@ experience a delay between the time a user presses the es- cape 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. There is just one input queue for all windows.-
- 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. +Predefined key-codes
+ The following special keys, defined in <curses.h>, may be + returned by getch if keypad has been enabled. Not all of + these are necessarily supported on any particular termi- + nal. Name Key name ------------------------------------------------- @@ -178,10 +186,10 @@ 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 @@ -228,7 +236,6 @@ Keypad is arranged like this: - +-----+------+-------+ | A1 | up | A3 | +-----+------+-------+ @@ -236,18 +243,36 @@ +-----+------+-------+ | C1 | down | C3 | +-----+------+-------+ - 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. Note that - a few values do not correspond to a real key, e.g., - KEY_RESIZE and KEY_MOUSE. See resizeterm(3x) for more de- - tails about KEY_RESIZE, and curs_mouse(3x) for a discus- - sion of KEY_MOUSE. + A few of these predefined values do not correspond to a + real key: + + o KEY_RESIZE is returned when the SIGWINCH signal has + been detected (see curs_initscr(3x) and resizeterm(3x)). + + o KEY_MOUSE is returned for mouse-events (see + curs_mouse(3x)). + + ++Testing key-codes
+ The has_key routine takes a key-code value from the above + list, and returns TRUE or FALSE according to whether the + current terminal type recognizes a key with that value. + + The library also supports these extensions: + + define_key + defines a key-code for a given string (see de- + fine_key(3x)). + + key_defined + checks if there is a key-code defined for a given + string (see key_defined(3x)).RETURN VALUE
- All routines return the integer ERR upon failure and an + All routines return the integer ERR upon failure and an integer value other than ERR (OK in the case of ungetch()) upon successful completion. @@ -255,94 +280,94 @@ returns ERR if there is no more room in the FIFO. wgetch - returns ERR if the window pointer is null, or if + returns ERR if the window pointer is null, or if its timeout expires without having any data. - Functions with a "mv" prefix first perform a cursor move- - ment using wmove, and return an error if the position is + Functions with a "mv" prefix first perform a cursor move- + ment using wmove, and return an error if the position is outside the window, or if the window pointer is null.NOTES
Use of the escape key by a programmer for a single charac- - ter function is discouraged, as it will cause a delay of + ter function is discouraged, as it will cause a delay of up to one second while the keypad code looks for a follow- ing function-key sequence. - 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. + 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 accord- + ing to whether they treat these control keys specially + (and ignore the terminfo), or use the terminfo defini- + tions. Ncurses uses the terminfo definition. If it says + that KEY_ENTER is control/M, getch will return KEY_ENTER + when you press control/M. - Generally, KEY_ENTER denotes the character(s) sent by the + Generally, KEY_ENTER denotes the character(s) sent by the Enter key on the numeric keypad: o the terminal description lists the most useful keys, - o the Enter key on the regular keyboard is already han- + o the Enter key on the regular keyboard is already han- dled by the standard ASCII characters for carriage-re- turn and line-feed, - o depending on whether nl or nonl was called, pressing - "Enter" on the regular keyboard may return either a + o depending on whether nl or nonl was called, pressing + "Enter" on the regular keyboard may return either a carriage-return or line-feed, and finally - o "Enter or send" is the standard description for this + o "Enter or send" is the standard description for this key. - When using getch, wgetch, mvgetch, or mvwgetch, nocbreak + 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 un- + the same time. Depending on the state of the tty driver + when each character is typed, the program may produce un- desirable results. 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, + 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.PORTABILITY
- 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- + 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 Curs- es 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 im- - plementation 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 im- + plementation 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 has been set. Programmers concerned about portability should be prepared - for either of two cases: (a) signal receipt does not in- - terrupt 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- + for either of two cases: (a) signal receipt does not in- + terrupt 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 NCURS- + The has_key function is unique to ncurses. We recommend + that any code using it be conditionalized on the NCURS- ES_VERSION feature macro. @@ -352,7 +377,7 @@ curs_mouse(3x), curs_move(3x), curs_refresh(3x), re- sizeterm(3x). - Comparable functions in the wide-character (ncursesw) li- + Comparable functions in the wide-character (ncursesw) li- brary are described in curs_get_wch(3x). @@ -365,7 +390,11 @@