Source-Changes-HG archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

[src/trunk]: src Provide basic documentation on getcchar(3) and setcchar(3).



details:   https://anonhg.NetBSD.org/src/rev/6a6d9a4e28fe
branches:  trunk
changeset: 837093:6a6d9a4e28fe
user:      uwe <uwe%NetBSD.org@localhost>
date:      Mon Nov 19 01:08:21 2018 +0000

description:
Provide basic documentation on getcchar(3) and setcchar(3).

Looks like we don't have any of wide curses stuff documented, so this
seems to be a good place to start.  Needs more exposition on wide
attr_t and how it's related to non-wide chtype, etc, etc.

diffstat:

 distrib/sets/lists/comp/mi   |   11 ++-
 lib/libcurses/Makefile       |    5 +-
 lib/libcurses/curses_cchar.3 |  154 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 168 insertions(+), 2 deletions(-)

diffs (265 lines):

diff -r 1072250fa70b -r 6a6d9a4e28fe distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sun Nov 18 23:50:48 2018 +0000
+++ b/distrib/sets/lists/comp/mi        Mon Nov 19 01:08:21 2018 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.2238 2018/11/15 10:06:06 maxv Exp $
+#      $NetBSD: mi,v 1.2239 2018/11/19 01:08:21 uwe Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 ./etc/mtree/set.comp                           comp-sys-root
@@ -6247,6 +6247,7 @@
 ./usr/share/man/cat3/curses_attributes.0       comp-c-catman           .cat
 ./usr/share/man/cat3/curses_background.0       comp-c-catman           .cat
 ./usr/share/man/cat3/curses_border.0           comp-c-catman           .cat
+./usr/share/man/cat3/curses_cchar.0            comp-c-catman           .cat
 ./usr/share/man/cat3/curses_chgat.0            comp-c-catman           .cat
 ./usr/share/man/cat3/curses_clear.0            comp-c-catman           .cat
 ./usr/share/man/cat3/curses_color.0            comp-c-catman           .cat
@@ -7111,6 +7112,7 @@
 ./usr/share/man/cat3/getc.0                    comp-c-catman           .cat
 ./usr/share/man/cat3/getc_unlocked.0           comp-c-catman           .cat
 ./usr/share/man/cat3/getcap.0                  comp-obsolete           obsolete
+./usr/share/man/cat3/getcchar.0                        comp-obsolete           obsolete
 ./usr/share/man/cat3/getch.0                   comp-c-catman           .cat
 ./usr/share/man/cat3/getchar.0                 comp-c-catman           .cat
 ./usr/share/man/cat3/getchar_unlocked.0                comp-c-catman           .cat
@@ -9461,6 +9463,7 @@
 ./usr/share/man/cat3/set_top_row.0             comp-c-catman           .cat
 ./usr/share/man/cat3/setbuf.0                  comp-c-catman           .cat
 ./usr/share/man/cat3/setbuffer.0               comp-c-catman           .cat
+./usr/share/man/cat3/setcchar.0                        comp-c-catman           .cat
 ./usr/share/man/cat3/setclasscontext.0         comp-c-catman           .cat
 ./usr/share/man/cat3/setdisktab.0              comp-c-catman           .cat
 ./usr/share/man/cat3/setdomainname.0           comp-c-catman           .cat
@@ -14151,6 +14154,7 @@
 ./usr/share/man/html3/curses_attributes.html   comp-c-htmlman          html
 ./usr/share/man/html3/curses_background.html   comp-c-htmlman          html
 ./usr/share/man/html3/curses_border.html       comp-c-htmlman          html
+./usr/share/man/html3/curses_cchar.html                comp-c-htmlman          html
 ./usr/share/man/html3/curses_chgat.html                comp-c-htmlman          html
 ./usr/share/man/html3/curses_clear.html                comp-c-htmlman          html
 ./usr/share/man/html3/curses_color.html                comp-c-htmlman          html
@@ -15023,6 +15027,7 @@
 ./usr/share/man/html3/getc.html                        comp-c-htmlman          html
 ./usr/share/man/html3/getc_unlocked.html       comp-c-htmlman          html
 ./usr/share/man/html3/getcap.html              comp-obsolete           obsolete
+./usr/share/man/html3/getcchar.html            comp-c-htmlman          html
 ./usr/share/man/html3/getch.html               comp-c-htmlman          html
 ./usr/share/man/html3/getchar.html             comp-c-htmlman          html
 ./usr/share/man/html3/getchar_unlocked.html    comp-c-htmlman          html
@@ -17352,6 +17357,7 @@
 ./usr/share/man/html3/set_top_row.html         comp-c-htmlman          html
 ./usr/share/man/html3/setbuf.html              comp-c-htmlman          html
 ./usr/share/man/html3/setbuffer.html           comp-c-htmlman          html
+./usr/share/man/html3/setcchar.html            comp-c-htmlman          html
 ./usr/share/man/html3/setclasscontext.html     comp-c-htmlman          html
 ./usr/share/man/html3/setdisktab.html          comp-c-htmlman          html
 ./usr/share/man/html3/setdomainname.html       comp-c-htmlman          html
@@ -21997,6 +22003,7 @@
 ./usr/share/man/man3/curses_attributes.3       comp-c-man              .man
 ./usr/share/man/man3/curses_background.3       comp-c-man              .man
 ./usr/share/man/man3/curses_border.3           comp-c-man              .man
+./usr/share/man/man3/curses_cchar.3            comp-c-man              .man
 ./usr/share/man/man3/curses_chgat.3            comp-c-man              .man
 ./usr/share/man/man3/curses_clear.3            comp-c-man              .man
 ./usr/share/man/man3/curses_color.3            comp-c-man              .man
@@ -22872,6 +22879,7 @@
 ./usr/share/man/man3/getc.3                    comp-c-man              .man
 ./usr/share/man/man3/getc_unlocked.3           comp-c-man              .man
 ./usr/share/man/man3/getcap.3                  comp-obsolete           obsolete
+./usr/share/man/man3/getcchar.3                        comp-c-man              .man
 ./usr/share/man/man3/getch.3                   comp-c-man              .man
 ./usr/share/man/man3/getchar.3                 comp-c-man              .man
 ./usr/share/man/man3/getchar_unlocked.3                comp-c-man              .man
@@ -25246,6 +25254,7 @@
 ./usr/share/man/man3/set_top_row.3             comp-c-man              .man
 ./usr/share/man/man3/setbuf.3                  comp-c-man              .man
 ./usr/share/man/man3/setbuffer.3               comp-c-man              .man
+./usr/share/man/man3/setcchar.3                        comp-c-man              .man
 ./usr/share/man/man3/setclasscontext.3         comp-c-man              .man
 ./usr/share/man/man3/setdisktab.3              comp-c-man              .man
 ./usr/share/man/man3/setdomainname.3           comp-c-man              .man
diff -r 1072250fa70b -r 6a6d9a4e28fe lib/libcurses/Makefile
--- a/lib/libcurses/Makefile    Sun Nov 18 23:50:48 2018 +0000
+++ b/lib/libcurses/Makefile    Mon Nov 19 01:08:21 2018 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.88 2018/11/18 01:23:57 uwe Exp $
+#      $NetBSD: Makefile,v 1.89 2018/11/19 01:08:22 uwe Exp $
 #      @(#)Makefile    8.2 (Berkeley) 1/2/94
 
 .include <bsd.own.mk>
@@ -28,6 +28,7 @@
 
 MAN=   curses.3 curses_addch.3 curses_addchstr.3 curses_addstr.3 \
        curses_attributes.3 curses_background.3 curses_border.3 \
+       curses_cchar.3 \
        curses_chgat.3 curses_clear.3 curses_color.3 \
        curses_cursor.3 curses_default_colors.3 \
        curses_delch.3 curses_deleteln.3 curses_echochar.3 curses_fileio.3 \
@@ -60,6 +61,8 @@
         curses_attributes.3 attrset.3 curses_tty.3 beep.3 \
         curses_background.3 bkgd.3 curses_background.3 bkgdset.3 \
         curses_border.3 border.3 curses_border.3 box.3 \
+        curses_cchar.3 getcchar.3 \
+        curses_cchar.3 setcchar.3 \
         curses_chgat.3 chgat.3 curses_chgat.3 mvchgat.3 \
         curses_chgat.3 mvwchgat.3 curses_chgat.3 wchgat.3 \
         curses_color.3 can_change_color.3 curses_tty.3 cbreak.3 \
diff -r 1072250fa70b -r 6a6d9a4e28fe lib/libcurses/curses_cchar.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libcurses/curses_cchar.3      Mon Nov 19 01:08:21 2018 +0000
@@ -0,0 +1,154 @@
+.\"    $NetBSD: curses_cchar.3,v 1.1 2018/11/19 01:08:22 uwe Exp $
+.\"
+.\" Copyright (c) 2018 Valery Ushakov
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd November 19, 2018
+.Dt CURSES_CCHAR 3
+.Os
+.Sh NAME
+.Nm curses_cchar ,
+.Nm getcchar ,
+.Nm setcchar
+.Nd curses representation of wide characters
+.Sh LIBRARY
+.Lb libcurses
+.Sh SYNOPSIS
+.\"
+.In curses.h
+.\"
+.Ft int
+.Fo getcchar
+.Fa "const cchar_t *wcval"
+.Fa "wchar_t *wch"
+.Fa "attr_t *attrs"
+.Fa "short *color_pair"
+.Fa "void *opts"
+.Fc
+.\"
+.Ft int
+.Fo setcchar
+.Fa "cchar_t *wcval"
+.Fa "const wchar_t *wch"
+.Fa "const attr_t attrs"
+.Fa "short color_pair"
+.Fa "const void *opts"
+.Fc
+.Sh DESCRIPTION
+Curses uses opaque type
+.Vt cchar_t
+to represent a string of wide characters up to an
+implementation-dependent length along with a color pair and zero or
+more attributes.
+A null 
+.Vt cchar_t
+object is an object that references an empty wide-character string.
+Arrays of
+.Vt cchar_t
+objects are terminated by a null
+.Vt cchar_t
+object.
+.Pp
+Objects of type
+.Vt cchar_t
+can be manipulated using
+.Nm getcchar
+and
+.Nm setcchar
+functions.
+Both these functions take as their last paramter the
+.Fa opts
+argument which is reserved for future extensions.
+Currently, the application must provide a null pointer as
+.Fa opts .
+.\"
+.Pp
+When
+.Nm getcchar
+function is called with non-null
+.Fa wch
+it extracts the information from the
+.Fa wcval
+object.
+The string of wide characters in
+.Fa wcval
+is copied to the
+.Fa wch
+array.
+The attributes are stored in
+.Fa attrs ,
+and the color pair is stored in
+.Fa color_pair .
+In this case it returns
+.Er OK
+upon successful completion, and
+.Er ERR
+otherwise.
+.Pp
+When
+.Nm getcchar
+is called with null
+.Fa wch
+it doesn't store any information but returns the number of wide
+characters referenced by
+.Fa wcval ,
+including the null terminator.
+.\"
+.Pp
+.Nm setcchar
+initializes
+.Fa wcval
+with the wide-character string
+.Fa wch ,
+attributes
+.Fa attrs ,
+and color pair
+.Fa color_pair .
+.Sh RETURN VALUES
+.Nm getchar
+called with null
+.Fa wch
+returns the the number of wide characters referenced by
+.Fa wcval ,
+including the null terminator.
+.Pp
+Otherwise these functions return one of the following values:
+.Bl -tag -width "Er ERR" -compact
+.It Er OK
+The function completed successfully.
+.It Er ERR
+An error occurred in the function.
+.El
+.\" .Sh SEE ALSO
+.\" XXX no other man pages yet for HAVE_WCHAR functions
+.Sh STANDARDS
+The
+.Nx
+Curses library complies with the X/Open Curses specification, part of
+the Single Unix Specification.
+.Sh HISTORY
+The Curses package appeared in
+.Bx 4.0 .
+.Pp
+Wide characters support appeared in
+.Nx 5.0 .



Home | Main Index | Thread Index | Old Index