X-Git-Url: http://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getch.3x.html;h=adc503b5cb66537c18152ac6ae711a8ce6ec3420;hb=eccca377f55c70b12e3e92621d94d1e1c1fcfb7d;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..adc503b5 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,7 +1,7 @@
- +-curs_getch(3x) curs_getch(3x) +curs_getch(3x) curs_getch(3x) --
- 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> 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 newline + (nocbreak mode). In half-delay mode, the program waits until a charac- + ter is typed or the specified timeout has been reached. + + 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 follow- + ing 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 alert- + ed 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 echoing. + + o Otherwise the character is simply output to the screen. + + If the window is not a pad, and it has been moved or modified 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: + + o The predefined function keys are listed in <curses.h> as macros + with values outside the range of 8-bit characters. Their names be- + gin with KEY_. + + o Other (user-defined) function keys which may be defined using de- + fine_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 re- + ceived (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 expe- + rience a delay between the time a user presses the escape 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 win- + dows. + + +
+ The following special keys are defined in <curses.h>. + + o Except for the special case KEY_RESIZE, it is necessary to enable + keypad for getch to return these codes. + + o Not all of these are necessarily supported on any particular termi- + nal. + + o The naming convention may seem obscure, with some apparent mis- + spellings (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. + + Name Key name + ------------------------------------------------- + KEY_BREAK Break key + KEY_DOWN The four arrow keys ... + KEY_UP + KEY_LEFT + KEY_RIGHT + KEY_HOME Home key (upward+left arrow) + KEY_BACKSPACE Backspace + KEY_F0 Function keys; space for 64 keys + is reserved. + KEY_F(n) For 0 <= n <= 63 + KEY_DL Delete line + KEY_IL Insert line + KEY_DC Delete character + KEY_IC Insert char or enter insert mode + KEY_EIC Exit insert char mode + KEY_CLEAR Clear screen + KEY_EOS Clear to end of screen + KEY_EOL Clear to end of line + KEY_SF Scroll 1 line forward + 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 + 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_A1 Upper left of keypad + KEY_A3 Upper right of keypad + + KEY_B2 Center of keypad + KEY_C1 Lower left of keypad + KEY_C3 Lower right of keypad + KEY_BTAB Back tab key + KEY_BEG Beg(inning) key + KEY_CANCEL Cancel key + KEY_CLOSE Close key + KEY_COMMAND Cmd (command) key + KEY_COPY Copy key + KEY_CREATE Create key + KEY_END End key + KEY_EXIT Exit key + 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 + KEY_PREVIOUS Previous object key + 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 + KEY_SBEG Shifted beginning key + KEY_SCANCEL Shifted cancel key + KEY_SCOMMAND Shifted command key + KEY_SCOPY Shifted copy key + KEY_SCREATE Shifted create key + KEY_SDC Shifted delete char key + KEY_SDL Shifted delete line key + KEY_SELECT Select key + KEY_SEND Shifted end key + KEY_SEOL Shifted clear line key + KEY_SEXIT Shifted exit key + KEY_SFIND Shifted find key + KEY_SHELP Shifted help key + KEY_SHOME Shifted home key + KEY_SIC Shifted input key + KEY_SLEFT Shifted left arrow key + KEY_SMESSAGE Shifted message key + KEY_SMOVE Shifted move key + KEY_SNEXT Shifted next key + KEY_SOPTIONS Shifted options key + KEY_SPREVIOUS Shifted prev key + KEY_SPRINT Shifted print key + 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 + KEY_SUNDO Shifted undo key + KEY_SUSPEND Suspend key + KEY_UNDO Undo key + Keypad is arranged like this: --
- 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 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. - - 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 to- - ken for that function key is returned instead of the raw - characters. Possible function keys are defined in <curs- - es.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 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. - - 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. + +-----+------+-------+ + | A1 | up | A3 | + +-----+------+-------+ + |left | B2 | right | + +-----+------+-------+ + | C1 | down | C3 | + +-----+------+-------+ + 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 initscr(3x) and resizeterm(3x)). This code is returned + whether or not keypad has been enabled. --
- 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 - ------------------------------------------------- - KEY_BREAK Break key - KEY_DOWN The four arrow keys ... - KEY_UP - KEY_LEFT - KEY_RIGHT - KEY_HOME Home key (upward+left arrow) - KEY_BACKSPACE Backspace - KEY_F0 Function keys; space for 64 keys - is reserved. - KEY_F(n) For 0 <= n <= 63 - KEY_DL Delete line - KEY_IL Insert line - KEY_DC Delete character - KEY_IC Insert char or enter insert mode - KEY_EIC Exit insert char mode - KEY_CLEAR Clear screen - KEY_EOS Clear to end of screen - KEY_EOL Clear to end of line - KEY_SF Scroll 1 line forward - 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 - 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_A1 Upper left of keypad - KEY_A3 Upper right of keypad - KEY_B2 Center of keypad - KEY_C1 Lower left of keypad - KEY_C3 Lower right of keypad - KEY_BTAB Back tab key - KEY_BEG Beg(inning) key - KEY_CANCEL Cancel key - KEY_CLOSE Close key - KEY_COMMAND Cmd (command) key - KEY_COPY Copy key - KEY_CREATE Create key - KEY_END End key - KEY_EXIT Exit key - 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 - KEY_PREVIOUS Previous object key - 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 - KEY_SBEG Shifted beginning key - KEY_SCANCEL Shifted cancel key - KEY_SCOMMAND Shifted command key - KEY_SCOPY Shifted copy key - KEY_SCREATE Shifted create key - KEY_SDC Shifted delete char key - KEY_SDL Shifted delete line key - KEY_SELECT Select key - KEY_SEND Shifted end key - KEY_SEOL Shifted clear line key - KEY_SEXIT Shifted exit key - KEY_SFIND Shifted find key - KEY_SHELP Shifted help key - KEY_SHOME Shifted home key - KEY_SIC Shifted input key - KEY_SLEFT Shifted left arrow key - KEY_SMESSAGE Shifted message key - KEY_SMOVE Shifted move key - KEY_SNEXT Shifted next key - KEY_SOPTIONS Shifted options key - KEY_SPREVIOUS Shifted prev key - KEY_SPRINT Shifted print key - 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 - KEY_SUNDO Shifted undo key - KEY_SUSPEND Suspend key - KEY_UNDO Undo key + o KEY_MOUSE is returned for mouse-events (see curs_mouse(3x)). This + code relies upon whether or not keypad(3x) has been enabled, be- + cause (e.g., with xterm mouse prototocol) ncurses must read escape + sequences, just like a function key. - Keypad is arranged like this: +
+ The has_key routine takes a key-code value from the above list, and re- + turns TRUE or FALSE according to whether the current terminal type rec- + ognizes a key with that value. - +-----+------+-------+ - | A1 | up | A3 | - +-----+------+-------+ - |left | B2 | right | - +-----+------+-------+ - | 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. + The library also supports these extensions: + define_key + defines a key-code for a given string (see define_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. + +
+ 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. + 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. + returns ERR if the window pointer is null, or if its timeout + expires without having any data, or if the execution was inter- + rupted by a signal (errno will be set to EINTR). - 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. + Functions with a "mv" prefix first perform a cursor movement 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 - 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. - - Generally, KEY_ENTER denotes the character(s) sent by the - Enter key on the numeric keypad: +
+ 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. + + Some keys may be the same as commonly used control keys, e.g., KEY_EN- + TER versus control/M, KEY_BACKSPACE versus control/H. Some curses im- + plementations may differ according 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_EN- + TER is control/M, getch will return KEY_ENTER when you press control/M. + + 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 the Enter key on the regular keyboard is already handled by the + standard ASCII characters for carriage-return 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 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. + 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 un- - desirable results. + 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. - 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. + Historically, the set of keypad macros was largely defined by the ex- + tremely function-key-rich keyboard of the AT&T 7300, aka 3B1, aka Sa- + fari 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, - 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 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. - - 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- - rupt getch. - - The has_key function is unique to ncurses. We recommend - that any code using it be conditionalized on the NCURS- - ES_VERSION feature macro. +
+ The *get* functions are described in the XSI Curses standard, 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 documentation. This descrip- + tion is adopted from the XSI Curses standard. --
- curses(3x), curs_inopts(3x), curs_outopts(3x), - curs_mouse(3x), curs_move(3x), curs_refresh(3x), re- - sizeterm(3x). + The behavior of getch 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 read(2) + call in progress or not, and also (in some implementations) depending + on whether an input timeout or non-blocking mode has been set. + + KEY_MOUSE is mentioned in XSI Curses, along with a few related terminfo + capabilities, but no higher-level functions use the feature. The im- + plementation in ncurses is an extension. + + KEY_RESIZE is an extension first implemented for ncurses. NetBSD curs- + es 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. + + 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_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). + Comparable functions in the wide-character (ncursesw) library are de- + scribed in curs_get_wch(3x). - curs_getch(3x) + curs_getch(3x)