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
@@ -76,26 +75,46 @@
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 oth-
- er 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 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.
+ 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-
@@ -106,18 +125,38 @@
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.
- FunctionKeys
- 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>.
+
+ 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.
NameKeyname
+ -------------------------------------------------
KEY_BREAK Break key
KEY_DOWN The four arrow keys ...
KEY_UP
@@ -140,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 +218,6 @@
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
@@ -206,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
@@ -215,7 +255,6 @@
Keypad is arranged like this:
-
+-----+------+-------+
| A1 | up | A3 |
+-----+------+-------+
@@ -223,102 +262,147 @@
+-----+------+-------+
| 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:
+ oKEY_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.
-
-
RETURN VALUE
- All routines return the integer ERR upon failure and an
+ oKEY_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 an error if there is no more room in
- the FIFO.
+ ungetch
+ returns ERR if there is no more room in the FIFO.
- wgetch
- returns an error if the window pointer is
- null, or if its timeout expires without having
- any data.
+ 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.
+
+ 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
- When using getch, wgetch, mvgetch, or mvwgetch, nocbreak
+ 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-
+ 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.
+ 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 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.
-