X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getch.3x.html;h=c72a2944ed30fc1fd322dceec2f0f0b4060d9d34;hb=603f0cb25b7acc8f04f4b18d2a2fe6f90039829a;hp=9b3bdc42ace740ac19afab4f0338722043e7e989;hpb=6a530b46563470c2ca73579d1994a0c8e275dd98;p=ncurses.git
diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html
index 9b3bdc42..c72a2944 100644
--- a/doc/html/man/curs_getch.3x.html
+++ b/doc/html/man/curs_getch.3x.html
@@ -1,7 +1,7 @@
@@ -46,14 +46,12 @@
-
-
+
getch, wgetch, mvgetch, mvwgetch, ungetch, has_key - get
(or push back) characters from curses terminal keyboard
-
-
+
#include <curses.h>
int getch(void);
@@ -64,11 +62,9 @@
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
@@ -103,15 +99,22 @@
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-
@@ -122,20 +125,35 @@
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.
-
-
- 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.
+
+ 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.
Name Key name
-------------------------------------------------
@@ -161,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
@@ -186,7 +205,6 @@
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
@@ -227,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
@@ -243,18 +262,22 @@
+-----+------+-------+
| C1 | down | C3 |
+-----+------+-------+
- A few of these predefined values do not correspond to a
+ 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_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)).
+ 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.
@@ -270,8 +293,7 @@
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.
@@ -288,8 +310,7 @@
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-
@@ -338,8 +359,7 @@
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,
@@ -359,6 +379,14 @@
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
@@ -371,11 +399,10 @@
ES_VERSION feature macro.
-
-
+
curses(3x), curs_inopts(3x), curs_outopts(3x),
- curs_mouse(3x), curs_move(3x), curs_refresh(3x), re-
- sizeterm(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).