ncurses 6.0 - patch 20150919

[ncurses.git] / man / curs_getch.3x

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 8a57bb02d076aed9f6fed964aaeae352ccaabc10..e81923f0570cd5cba601b33284166a3e940ed7d8 100644 (file)
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"

-.\" $Id: curs_getch.3x,v 1.41 2015/07/16 09:29:33 tom Exp $
+.\" $Id: curs_getch.3x,v 1.43 2015/09/19 22:25:05 tom Exp $

 .TH curs_getch 3X ""
 .na
 .hy 0
 .TH curs_getch 3X ""
 .na
 .hy 0


@@ -48,15 +48,15 @@
 .PP
 \fBint getch(void);\fR
 .br
 .PP
 \fBint getch(void);\fR
 .br

-\fBint wgetch(WINDOW *win);\fR
+\fBint wgetch(WINDOW *\fP\fIwin);\fR

 .br
 .br

-\fBint mvgetch(int y, int x);\fR
+\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR

 .br
 .br

-\fBint mvwgetch(WINDOW *win, int y, int x);\fR
+\fBint mvwgetch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR

 .br
 .br

-\fBint ungetch(int ch);\fR
+\fBint ungetch(int \fP\fIch\fP\fB);\fR

 .br
 .br

-\fBint has_key(int ch);\fR
+\fBint has_key(int \fP\fIch\fP\fB);\fR

 .br
 .SH DESCRIPTION
 .SS Reading characters
 .br
 .SH DESCRIPTION
 .SS Reading characters


@@ -117,11 +117,10 @@ The \fBungetch\fR routine places \fIch\fR back onto the input queue to be
 returned by the next call to \fBwgetch\fR.
 There is just one input queue for all windows.
 .PP
 returned by the next call to \fBwgetch\fR.
 There is just one input queue for all windows.
 .PP

-.SS Function Keys
-The following function keys, defined in \fB<curses.h>\fR, might be returned by
+.SS Predefined key-codes
+The following special keys, defined in \fB<curses.h>\fR, may be returned by

 \fBgetch\fR if \fBkeypad\fR has been enabled.
 \fBgetch\fR if \fBkeypad\fR has been enabled.

-Note that not all of these are
-necessarily supported on any particular terminal.
+Not all of these are necessarily supported on any particular terminal.

 .PP
 .TS
 center tab(/) ;
 .PP
 .TS
 center tab(/) ;


@@ -227,7 +226,7 @@ KEY_UNDO/Undo key
 .TE
 .PP
 Keypad is arranged like this:
 .TE
 .PP
 Keypad is arranged like this:

-.sp
+.br

 .TS
 center allbox tab(/) ;
 c c c .
 .TS
 center allbox tab(/) ;
 c c c .


@@ -236,13 +235,35 @@ c c c .
 \fBC1\fR/\fBdown\fR/\fBC3\fR
 .TE
 .sp
 \fBC1\fR/\fBdown\fR/\fBC3\fR
 .TE
 .sp

-The \fBhas_key\fR routine takes a key value from the above list, and
+A few of these predefined values do \fInot\fP correspond to a real key:
+.bP
+.B KEY_RESIZE
+is returned when the \fBSIGWINCH\fP signal has been detected
+(see \fBinitscr\fP(3X) and \fBresizeterm\fR(3X)).
+This code is returned whether or not \fBkeypad\fP has been enabled.
+.bP
+.B KEY_MOUSE
+is returned for mouse-events (see \fBcurs_mouse\fR(3X)).
+This code relies upon whether or not \fBkeypad\fP(3X) has been enabled,
+because (e.g., with \fIxterm\fP mouse prototocol) ncurses must
+read escape sequences,
+just like a function key.
+.SS Testing key-codes
+.PP
+The \fBhas_key\fR routine takes a key-code value from the above list, and

 returns \fBTRUE\fP or \fBFALSE\fP according to whether
 the current terminal type recognizes a key with that value.
 returns \fBTRUE\fP or \fBFALSE\fP 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., \fBKEY_RESIZE\fP and \fBKEY_MOUSE\fP.
-See \fBinitscr\fP(3X) and \fBresizeterm\fR(3X) for more details about \fBKEY_RESIZE\fP, and
-\fBcurs_mouse\fR(3X) for a discussion of \fBKEY_MOUSE\fP.
+.PP
+The library also supports these extensions:
+.RS 3
+.TP 5
+.B define_key
+defines a key-code for a given string (see \fBdefine_key\fP(3X)).
+.TP 5
+.B key_defined
+checks if there is a key-code defined for a given
+string (see \fBkey_defined\fP(3X)).
+.RE

 .PP
 .SH RETURN VALUE
 All routines return the integer \fBERR\fR upon failure and an integer value
 .PP
 .SH RETURN VALUE
 All routines return the integer \fBERR\fR upon failure and an integer value


@@ -268,7 +289,7 @@ 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.
 .PP
 discouraged, as it will cause a delay of up to one second while the
 keypad code looks for a following function-key sequence.
 .PP

-Note that some keys may be the same as commonly used control
+Some keys may be the same as commonly used control

 keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H.
 Some curses implementations may differ according to whether they
 treat these control keys specially (and ignore the terminfo), or
 keys, e.g., \fBKEY_ENTER\fP versus control/M, \fBKEY_BACKSPACE\fP versus control/H.
 Some curses implementations may differ according to whether they
 treat these control keys specially (and ignore the terminfo), or


@@ -331,6 +352,13 @@ implementation of handled signal receipt interrupts a \fBread\fR(2) call in
 progress or not, and also (in some implementations) depending on whether an
 input timeout or non-blocking mode has been set.
 .PP
 progress or not, and also (in some implementations) depending on whether an
 input timeout or non-blocking mode has been set.
 .PP

+\fBKEY_MOUSE\fP is mentioned in XSI Curses, along with a few related
+terminfo capabilities, but no higher-level functions use the feature.
+The implementation in ncurses is an extension.
+.PP
+\fBKEY_RESIZE\fP is an extension first implemented for ncurses. 
+NetBSD curses later added this extension.
+.PP

 Programmers concerned about portability should be prepared for either of two
 cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
 interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to
 Programmers concerned about portability should be prepared for either of two
 cases: (a) signal receipt does not interrupt \fBgetch\fR; (b) signal receipt
 interrupts \fBgetch\fR and causes it to return ERR with \fBerrno\fR set to