* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getch.3x,v 1.42 2015/07/21 08:44:04 tom Exp @
+ * @Id: curs_getch.3x,v 1.43 2015/09/19 22:25:05 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
real key:
<STRONG>o</STRONG> <STRONG>KEY_RESIZE</STRONG> is returned when the <STRONG>SIGWINCH</STRONG> signal has
- been detected (see <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>).
+ been detected (see <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>).
+ This code is returned whether or not <STRONG>keypad</STRONG> has been
+ enabled.
<STRONG>o</STRONG> <STRONG>KEY_MOUSE</STRONG> is returned for mouse-events (see
- <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>).
+ <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>). This code relies upon whether or not
+ <STRONG><A HREF="keypad.3x.html">keypad(3x)</A></STRONG> has been enabled, because (e.g., with <EM>xterm</EM>
+ mouse prototocol) ncurses must read escape sequences,
+ just like a function key.
</PRE>
<H3><a name="h3-Testing-key-codes">Testing key-codes</a></H3><PRE>
- The <STRONG>has_key</STRONG> routine takes a key-code value from the above
- list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the
+ The <STRONG>has_key</STRONG> routine takes a key-code value from the above
+ list, and returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> according to whether the
current terminal type recognizes a key with that value.
The library also supports these extensions:
<STRONG>define_key</STRONG>
- defines a key-code for a given string (see <STRONG>de-</STRONG>
+ defines a key-code for a given string (see <STRONG>de-</STRONG>
<STRONG><A HREF="define_key.3x.html">fine_key(3x)</A></STRONG>).
<STRONG>key_defined</STRONG>
- checks if there is a key-code defined for a given
+ checks if there is a key-code defined for a given
string (see <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>).
</PRE>
<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
- All routines return the integer <STRONG>ERR</STRONG> upon failure and an
+ All routines return the integer <STRONG>ERR</STRONG> upon failure and an
integer value other than <STRONG>ERR</STRONG> (<STRONG>OK</STRONG> in the case of ungetch())
upon successful completion.
returns ERR if there is no more room in the FIFO.
<STRONG>wgetch</STRONG>
- 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 <STRONG>wmove</STRONG>, and return an error if the position is
+ Functions with a "mv" prefix first perform a cursor move-
+ ment using <STRONG>wmove</STRONG>, and return an error if the position is
outside the window, or if the window pointer is null.
</PRE>
<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
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.
- Some keys may be the same as commonly used control keys,
- e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> versus
+ Some keys may be the same as commonly used control keys,
+ e.g., <STRONG>KEY_ENTER</STRONG> versus control/M, <STRONG>KEY_BACKSPACE</STRONG> 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. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says
- that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
+ ing to whether they treat these control keys specially
+ (and ignore the terminfo), or use the terminfo defini-
+ tions. <STRONG>Ncurses</STRONG> uses the terminfo definition. If it says
+ that <STRONG>KEY_ENTER</STRONG> is control/M, <STRONG>getch</STRONG> will return <STRONG>KEY_ENTER</STRONG>
when you press control/M.
- Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
+ Generally, <STRONG>KEY_ENTER</STRONG> denotes the character(s) sent by the
<EM>Enter</EM> key on the numeric keypad:
<STRONG>o</STRONG> the terminal description lists the most useful keys,
- <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
+ <STRONG>o</STRONG> the <EM>Enter</EM> key on the regular keyboard is already han-
dled by the standard ASCII characters for carriage-re-
turn and line-feed,
- <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
- "Enter" on the regular keyboard may return either a
+ <STRONG>o</STRONG> depending on whether <STRONG>nl</STRONG> or <STRONG>nonl</STRONG> was called, pressing
+ "Enter" on the regular keyboard may return either a
carriage-return or line-feed, and finally
- <STRONG>o</STRONG> "Enter or send" is the standard description for this
+ <STRONG>o</STRONG> "Enter or send" is the standard description for this
key.
- When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
+ When using <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, or <STRONG>mvwgetch</STRONG>, nocbreak
mode (<STRONG>nocbreak</STRONG>) and echo mode (<STRONG>echo</STRONG>) 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 <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> 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 <STRONG>KEY_UP</STRONG>,
- <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
+ 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 <STRONG>KEY_UP</STRONG>,
+ <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>,
<STRONG>KEY_NPAGE</STRONG>, <STRONG>KEY_PPAGE</STRONG>, and function keys 1 through 12. The
Ins key is usually mapped to <STRONG>KEY_IC</STRONG>.
</PRE>
<H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
- 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 <STRONG>ERR</STRONG> 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 <STRONG>ERR</STRONG> on failure,
but specifies no error conditions.
- The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
- backspace characters was not specified in the SVr4 docu-
+ The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or
+ backspace characters was not specified in the SVr4 docu-
mentation. This description is adopted from the XSI Curs-
es standard.
- The behavior of <STRONG>getch</STRONG> 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
- <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
- mentations) depending on whether an input timeout or non-
+ The behavior of <STRONG>getch</STRONG> 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
+ <STRONG>read(2)</STRONG> call in progress or not, and also (in some imple-
+ mentations) depending on whether an input timeout or non-
blocking mode has been set.
+ <STRONG>KEY_MOUSE</STRONG> 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.
+
+ <STRONG>KEY_RESIZE</STRONG> 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 <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
- causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
- the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
+ for either of two cases: (a) signal receipt does not in-
+ terrupt <STRONG>getch</STRONG>; (b) signal receipt interrupts <STRONG>getch</STRONG> and
+ causes it to return ERR with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. Under
+ the <STRONG>ncurses</STRONG> implementation, handled signals never inter-
rupt <STRONG>getch</STRONG>.
- The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
- that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
+ The <STRONG>has_key</STRONG> function is unique to <STRONG>ncurses</STRONG>. We recommend
+ that any code using it be conditionalized on the <STRONG>NCURS-</STRONG>
<STRONG>ES_VERSION</STRONG> feature macro.
<STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG>re-</STRONG>
<STRONG><A HREF="resizeterm.3x.html">sizeterm(3x)</A></STRONG>.
- Comparable functions in the wide-character (ncursesw) li-
+ Comparable functions in the wide-character (ncursesw) li-
brary are described in <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG>.
projects / ncurses.git / blobdiff