X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_getch.3x;h=1ef0601388a8fe5f344155b471ee715dbe207b71;hb=4b386ffba9ebe520ddc51fe46ba88e008056a67e;hp=8a57bb02d076aed9f6fed964aaeae352ccaabc10;hpb=32f9f5f12cd9159261f9db228461049e8c770404;p=ncurses.git

diff --git a/man/curs_getch.3x b/man/curs_getch.3x
index 8a57bb02..1ef06013 100644
--- a/man/curs_getch.3x
+++ b/man/curs_getch.3x
@@ -27,7 +27,7 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_getch.3x,v 1.41 2015/07/16 09:29:33 tom Exp $
+.\" $Id: curs_getch.3x,v 1.44 2015/12/20 01:43:03 tom Exp $
 .TH curs_getch 3X ""
 .na
 .hy 0
@@ -48,15 +48,15 @@
 .PP
 \fBint getch(void);\fR
 .br
-\fBint wgetch(WINDOW *win);\fR
+\fBint wgetch(WINDOW *\fP\fIwin);\fR
 .br
-\fBint mvgetch(int y, int x);\fR
+\fBint mvgetch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
 .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
-\fBint ungetch(int ch);\fR
+\fBint ungetch(int \fP\fIch\fP\fB);\fR
 .br
-\fBint has_key(int ch);\fR
+\fBint has_key(int \fP\fIch\fP\fB);\fR
 .br
 .SH DESCRIPTION
 .SS Reading characters
@@ -117,11 +117,18 @@ 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
-.SS Function Keys
-The following function keys, defined in \fB<curses.h>\fR, might be returned by
-\fBgetch\fR if \fBkeypad\fR has been enabled.
-Note that not all of these are
-necessarily supported on any particular terminal.
+.SS Predefined key-codes
+The following special keys are defined in \fB<curses.h>\fR.
+.bP
+Except for the special case \fBKEY_RESIZE\fP,
+it is necessary to enable \fBkeypad\fR for \fBgetch\fP to return these codes.
+.bP
+Not all of these are necessarily supported on any particular terminal.
+.bP
+The naming convention may seem obscure, with some apparent
+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.
 .PP
 .TS
 center tab(/) ;
@@ -227,7 +234,7 @@ KEY_UNDO/Undo key
 .TE
 .PP
 Keypad is arranged like this:
-.sp
+.br
 .TS
 center allbox tab(/) ;
 c c c .
@@ -236,13 +243,35 @@ c c c .
 \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.
-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
@@ -268,7 +297,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
-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
@@ -331,6 +360,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
+\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