ncurses 6.5 - patch 20240511

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

diff --git a/man/curs_get_wch.3x b/man/curs_get_wch.3x
index b0d69166f44efe68c700fe92ded06ecb253d806d..c190a7ea10e85c2eabe1662f9177fe00cf877f6d 100644 (file)
--- a/man/curs_get_wch.3x
+++ b/man/curs_get_wch.3x
@@ -27,8 +27,8 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_get_wch.3x,v 1.36 2024/03/23 20:00:03 tom Exp $
-.TH curs_get_wch 3X 2024-03-23 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.\" $Id: curs_get_wch.3x,v 1.41 2024/05/11 20:39:53 tom Exp $
+.TH curs_get_wch 3X 2024-05-11 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .ie \n(.g \{\
 .ds `` \(lq
 .ds '' \(rq
@@ -60,17 +60,15 @@ get (or push back) a wide character from \fIcurses\fR terminal keyboard
 \fBint mvget_wch(int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP);
 \fBint mvwget_wch(WINDOW *\fIwin\fP, int \fIy\fP, int \fIx\fP, wint_t *\fIwch\fP);
 .PP
-\fBint unget_wch(const wchar_t \fIwch\fP);
+\fBint unget_wch(const wchar_t \fIwc\fP);
 .fi
 .SH DESCRIPTION
 .SS "Reading Characters"
 .B \%wget_wch
-gathers a key stroke
-.I wch
-from the terminal keyboard associated with a
+gathers a key event from the terminal keyboard associated with a
 .I curses
 window
-.IR win ,
+.IR win ","
 returning
 .B OK
 if a wide character is read,
@@ -84,11 +82,13 @@ if no key event is available.
 When input is pending,
 .B \%wget_wch
 stores an integer
-identifying the key stroke in
-.IR wch ;
+identifying the key event in
+.IR wch ";"
 for alphanumeric and punctuation keys,
 this value corresponds to the character encoding used by the terminal.
-Use of the control key as a modifier often results in a distinct code.
+Use of the control key as a modifier,
+by holding it down while pressing and releasing another key,
+often results in a distinct code.
 The behavior of other keys depends on whether
 .I win
 is in keypad mode;
@@ -99,7 +99,7 @@ If no input is pending,
 then if the no-delay flag is set in the window
 (see \fB\%nodelay\fP(3X)),
 the function returns
-.BR ERR ;
+.BR ERR ";"
 otherwise,
 .I curses
 waits until the terminal has input.
@@ -112,7 +112,7 @@ it occurs when the next newline is read.
 If \fB\%halfdelay\fP(3X)
 has been called,
 .I curses
-waits until a character is typed or the specified delay elapses.
+waits until input is available or the specified delay elapses.
 .PP
 If \fB\%echo\fP(3X) has been called,
 and the window is not a pad,
@@ -142,19 +142,20 @@ writes any other
 to the window,
 as with \fB\%wecho_wchar\fP(3X).
 .bP
-If the window has been moved or modified since the last call to
+If the window
+.I win
+has been moved or modified since the last call to
 \fB\%wrefresh\fP(3X),
 .I curses
 calls
-.BR \%wrefresh .
+.B \%wrefresh
+on it.
 .PP
 If
 .I wch
 is a carriage return and \fBnl\fP(3X) has been called,
 .B \%wgetch
-stores the the character code for newline
-(line feed)
-in
+stores the the character code for line feed in
 .I wch
 instead.
 .SS "Ungetting Characters"
@@ -162,8 +163,8 @@ instead.
 places
 .I wch
 into the input queue to be returned by the next call to
-.BR \%wget_wch .
-A single input queue serves all windows.
+.BR \%wget_wch "."
+A single input queue serves all windows associated with the terminal.
 .SH RETURN VALUE
 .B \%wget_wch
 returns
@@ -178,7 +179,7 @@ if
 the
 .I \%WINDOW
 pointer is
-.BR NULL ,
+.BR NULL ","
 or
 .bP
 its timeout expires without any data arriving,
@@ -188,15 +189,13 @@ execution was interrupted by a signal,
 in which case
 .B \%errno
 is set to
-.BR \%EINTR .
+.BR \%EINTR "."
 .PP
-Functions with a \*(``mv\*('' prefix first perform cursor movement using
-\fB\%wmove\fP(3X) and fail if the position is outside the window,
-or
-(for \*(``mvw\*('' functions)
-if the
-.I win
-parameter is a null pointer.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x ")"
+is outside the window boundaries.
 .PP
 .B \%unget_wch
 returns
@@ -220,18 +219,16 @@ and its variants store the value of the input character in an additional
 parameter instead of the return value.
 .PP
 Unlike
-.BR \%ungetch ,
+.BR \%ungetch ","
 .B \%unget_wch
-cannot distinguish function key codes
-.B \%wget_wch
-from conventional character codes.
+cannot distinguish function key codes from conventional character codes.
 An application can overcome this limitation by pushing function key
 codes with
 .B \%ungetch
 and subsequently checking the return value of
 .B \%wget_wch
 for a match with
-.BR \%KEY_CODE_YES .
+.BR \%KEY_CODE_YES "."
 .SH EXTENSIONS
 See the \*(``EXTENSIONS\*('' section of \fB\%wgetch\fP(3X).
 .SH PORTABILITY
@@ -241,7 +238,8 @@ extensions should condition their use on the visibility of the
 .B \%NCURSES_VERSION
 preprocessor macro.
 .PP
-X/Open Curses, Issue 4, describes these functions.
+X/Open Curses,
+Issue 4 describes these functions.
 It specifies no error conditions for them.
 .PP
 See the \*(``PORTABILITY\*('' section of \fB\%wgetch\fP(3X) regarding
@@ -249,12 +247,12 @@ the interaction of
 .B \%wget_wch
 with signal handlers.
 .SH SEE ALSO
+\fB\%curs_getch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
 \fB\%curses\fP(3X),
 \fB\%curs_add_wch\fP(3X),
 \fB\%curs_inopts\fP(3X),
 \fB\%curs_move\fP(3X),
 \fB\%curs_refresh\fP(3X)
-.PP
-\fB\%curs_getch\fP(3X) describes comparable functions of the
-.I \%ncurses
-library in its non-wide-character configuration.