ncurses 6.5 - patch 20240525

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

diff --git a/man/curs_in_wch.3x b/man/curs_in_wch.3x
index 2603414597fab4e1e43a9da1749689633383628c..1775752a976067f402636912dd98f22364a801e1 100644 (file)
--- a/man/curs_in_wch.3x
+++ b/man/curs_in_wch.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright 2018-2020,2021 Thomas E. Dickey                                *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
 .\" Copyright 2002-2010,2017 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
@@ -27,45 +27,88 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_in_wch.3x,v 1.12 2021/12/25 21:49:32 tom Exp $
-.TH curs_in_wch 3X ""
-.ie \n(.g .ds `` \(lq
-.el       .ds `` ``
-.ie \n(.g .ds '' \(rq
-.el       .ds '' ''
+.\" $Id: curs_in_wch.3x,v 1.33 2024/05/18 20:19:38 tom Exp $
+.TH curs_in_wch 3X 2024-05-18 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el   .ds `` ""
+.ie t .ds '' ''
+.el   .ds '' ""
+.\}
 .SH NAME
-\fBin_wch\fP,
-\fBmvin_wch\fP,
-\fBmvwin_wch\fP,
-\fBwin_wch\fP \- extract a complex character and rendition from a window
+\fB\%in_wch\fP,
+\fB\%mvin_wch\fP,
+\fB\%mvwin_wch\fP,
+\fB\%win_wch\fP \-
+get a \fIcurses\fR complex character from a window
 .SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBint in_wch(cchar_t *\fP\fIwcval\fP\fB);\fP
-.br
-\fBint win_wch(WINDOW *\fP\fIwin\fP\fB, cchar_t *\fP\fIwcval\fP\fB);\fP
-.sp
-\fBint mvin_wch(int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwcval\fP\fB);\fP
-.br
-\fBint mvwin_wch(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB, cchar_t *\fP\fIwcval\fP\fB);\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBint in_wch(cchar_t * \fIwch\fP);
+\fBint win_wch(WINDOW * \fIwin\fP, cchar_t * \fIwch\fP);
+\fBint mvin_wch(int \fIy\fP, int \fIx\fP, cchar_t * \fIwch\fP);
+\fBint mvwin_wch(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP, cchar_t * \fIwch\fP);
+.fi
 .SH DESCRIPTION
-These functions extract the complex character and rendition from
-the current position in the named window into the \fBcchar_t\fP object
-referenced by wcval.
+.B \%win_wch
+copies the
+.I curses
+complex character at the cursor position in
+.I win
+into
+.IR wch "."
+Use \fB\%getcchar\fP(3X) to extract its character code,
+attributes,
+and color pair identifier.
+\fB\%ncurses\fP(3X) describes the variants of this function.
 .SH RETURN VALUE
-No errors are defined in the XSI Curses standard.
-This implementation checks for null pointers, returns \fBERR\fP in that case.
-Also, the \fImv\fP routines check for error moving the cursor,
-returning \fBERR\fP in that case.
-Otherwise they return \fBOK\fP.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+In
+.IR \%ncurses ","
+.B \%win_wch
+returns
+.B ERR
+if
+.I win
+is
+.BR NULL "."
 .PP
-Functions with a \*(``mv\*('' prefix first perform a cursor movement using
-\fBwmove\fP, and return an error if the position is outside the window,
-or if the window pointer is null.
+Functions prefixed with \*(``mv\*('' first perform cursor movement and
+fail if the position
+.RI ( y ,
+.IR x )
+is outside the window boundaries.
 .SH NOTES
-Note that all of these routines may be macros.
+.BR \%in_wch ","
+.BR mvin_wch ","
+and
+.B mvwin_wch
+may be implemented as macros.
+.PP
+Unlike \fB\%winch\fP(3X),
+.B \%win_wch
+and its variants store the value of the retrieved character in an
+additional
+.I wch
+parameter instead of the return value.
 .SH PORTABILITY
-These functions are described in the XSI Curses standard, Issue 4.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
 .SH SEE ALSO
-\fBcurses\fP(3X),
-\fBcurs_inch\fP(3X).
+\fB\%curs_inch\fP(3X) describes comparable functions of the
+.I \%ncurses
+library in its non-wide-character configuration.
+.PP
+\fB\%curses\fP(3X),
+\fB\%curs_inwstr\fP(3X)