X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getch.3x.html;h=c72a2944ed30fc1fd322dceec2f0f0b4060d9d34;hb=603f0cb25b7acc8f04f4b18d2a2fe6f90039829a;hp=9b7b9d9cc2a64c51ac020951357858066683a324;hpb=a8987e73ec254703634802b4f7ee30d3a485524d;p=ncurses.git diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index 9b7b9d9c..c72a2944 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,8 +1,7 @@ - +
+ +- -curs_getch(3x) curs_getch(3x) +curs_getch(3x) curs_getch(3x) --
- getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get +
+ getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get (or push back) characters from curses terminal keyboard --
+
#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 program waits until the system passes text through to the - program. Depending on the setting of cbreak, this is - after one character (cbreak mode), or after the first new- + program. Depending on the setting of cbreak, this is af- + ter 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 - 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. - Otherwise the character is simply output to the screen. + If echo 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: + + o 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 + delch had been called. + + o If the character value is any other KEY_ define, the + user is alerted with a beep call. + + o If the character is a carriage-return, and if nl is + enabled, it is translated to a line-feed after echo- + ing. + + o 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 called before another character is read. - 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 - 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 - 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. +
+ If keypad is TRUE, and a function key is pressed, the to- + ken for that function key is returned instead of the raw + characters: + + o The predefined function keys are listed in <curses.h> + as macros with values outside the range of 8-bit char- + acters. Their names begin with KEY_. + + o Other (user-defined) function keys which may be de- + fined using define_key(3x) have no names, but also are + expected to have values outside the range of 8-bit + characters. + 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 es- + cape 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 terminals + experience a delay between the time a user presses the es- + cape key and the escape is returned to the program. + + In ncurses, the timer normally expires after the value in + ESCDELAY (see curs_variables(3x)). If notimeout is TRUE, + 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 no- + timeout mode after pressing the escape key until another + key is pressed. + + +
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 - that not all of these are necessarily supported on any - particular terminal. +
+ The following special keys are defined in <curses.h>. - Name Key name + o Except for the special case KEY_RESIZE, it is neces- + sary to enable keypad for getch to return these codes. + + o Not all of these are necessarily supported on any par- + ticular terminal. + + o The naming convention may seem obscure, with some ap- + parent 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. - KEY_BREAK Break key + Name Key name + ------------------------------------------------- + KEY_BREAK Break key KEY_DOWN The four arrow keys ... KEY_UP KEY_LEFT @@ -142,6 +179,7 @@ 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 @@ -178,7 +216,6 @@ 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 @@ -208,6 +245,7 @@ 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 @@ -224,101 +262,173 @@ +-----+------+-------+ | 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. + 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)). + This code is returned whether or not keypad has been + enabled. + o KEY_MOUSE is returned for mouse-events (see + curs_mouse(3x)). This code relies upon whether or not + keypad(3x) has been enabled, because (e.g., with xterm + mouse prototocol) ncurses must read escape sequences, + just like a function key. --
+ +
+ 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)). + + +
All routines return the integer ERR upon failure and an integer value other than ERR (OK in the case of ungetch()) upon successful completion. + ungetch + returns ERR if there is no more room in the FIFO. --
+ wgetch + 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 + outside the window, or if the window pointer is null. + + +
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. - When using getch, wgetch, mvgetch, or mvwgetch, nocbreak + 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- + 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 + carriage-return or line-feed, and finally + + o "Enter or send" is the standard description for this + key. + + 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. + 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. --
- 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 - 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 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- blocking mode has been set. + KEY_MOUSE is mentioned in XSI Curses, along with a few re- + lated terminfo capabilities, but no higher-level functions + use the feature. The implementation in ncurses is an ex- + tension. + + KEY_RESIZE is an extension first implemented for ncurses. + NetBSD curses later added this extension. + 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- + 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 - NCURSES_VERSION feature macro. + The has_key function is unique to ncurses. We recommend + that any code using it be conditionalized on the NCURS- + ES_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_outopts(3x), + curs_mouse(3x), curs_move(3x), curs_refresh(3x), + curs_variables(3x), resizeterm(3x). + + Comparable functions in the wide-character (ncursesw) li- + brary are described in curs_get_wch(3x). - curs_getch(3x) + curs_getch(3x)-