diff options
Diffstat (limited to 'man/curs_getcchar.3x')
| -rw-r--r-- | man/curs_getcchar.3x | 78 |
1 files changed, 71 insertions, 7 deletions
diff --git a/man/curs_getcchar.3x b/man/curs_getcchar.3x index a974c73..fafe782 100644 --- a/man/curs_getcchar.3x +++ b/man/curs_getcchar.3x @@ -1,5 +1,6 @@ .\"*************************************************************************** -.\" Copyright (c) 2001-2010,2012 Free Software Foundation, Inc. * +.\" Copyright 2019,2020 Thomas E. Dickey * +.\" Copyright 2001-2015,2017 Free Software Foundation, Inc. * .\" * .\" Permission is hereby granted, free of charge, to any person obtaining a * .\" copy of this software and associated documentation files (the * @@ -26,10 +27,11 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_getcchar.3x,v 1.16 2012/11/03 23:03:59 tom Exp $ +.\" $Id: curs_getcchar.3x,v 1.24 2020/02/02 23:34:34 tom Exp $ .TH curs_getcchar 3X "" .de bP -.IP \(bu 4 +.ie n .IP \(bu 4 +.el .IP \(bu 2 .. .SH NAME \fBgetcchar\fP, @@ -59,8 +61,9 @@ .br .B " short \fIcolor_pair\fP," .br -.B " void *\fIopts\fP );" +.B " const void *\fIopts\fP );" .SH DESCRIPTION +.SS getcchar .PP The \fBgetcchar\fP function gets a wide-character string and rendition from a \fBcchar_t\fP argument. @@ -88,6 +91,7 @@ Does not change the data referenced by \fIattrs\fP or \fIcolor_pair\fP +.SS setcchar .PP The \fBsetcchar\fP function initializes the location pointed to by \fIwcval\fP by using: @@ -108,10 +112,23 @@ Additional nonspacing characters are ignored. .IP The string may contain a single control character instead. In that case, no nonspacing characters are allowed. -.SH NOTES +.SH EXTENSIONS .PP -The \fIopts\fP argument is reserved for future use. -Currently, an application must provide a null pointer as \fIopts\fP. +X/Open Curses documents the \fIopts\fP argument as reserved for future use, +saying that it must be null. +This implementation +uses that parameter in ABI 6 for the functions which have a color-pair +parameter to support extended color pairs: +.bP +For functions which modify the color, e.g., \fBsetcchar\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to set the color pair instead of the \fBshort\fP pair parameter. +.bP +For functions which retrieve the color, e.g., \fBgetcchar\fP, +if \fIopts\fP is set it is treated as a pointer to \fBint\fP, +and used to retrieve the color pair as an \fBint\fP value, +in addition retrieving it via the standard pointer to \fBshort\fP parameter. +.SH NOTES .PP The \fIwcval\fP argument may be a value generated by a call to \fBsetcchar\fP or by a function that has a \fBcchar_t\fP output argument. @@ -129,6 +146,53 @@ and \fBERR\fP otherwise. .PP Upon successful completion, \fBsetcchar\fP returns \fBOK\fP. Otherwise, it returns \fBERR\fP. +.SH PORTABILITY +The \fBCCHARW_MAX\fP symbol is specific to ncurses. +X/Open Curses does not provide details for the layout of the \fBcchar_t\fP +structure. +It tells what data are stored in it: +.bP +a spacing character (\fBwchar_t\fP, i.e., 32-bits). +.bP +non-spacing characters (again, \fBwchar_t\fP's). +.bP +attributes (at least 16 bits, inferred from the various ACS- and WACS-flags). +.bP +color pair (at least 16 bits, inferred from the \fBunsigned short\fP type). +.PP +The non-spacing characters are optional, +in the sense that zero or more may be stored in a \fBcchar_t\fP. +XOpen/Curses specifies a limit: +.RS 4 +.PP +Implementations may limit the number of non-spacing characters that can be +associated with a spacing character, provided any limit is at least 5. +.RE +.PP +The Unix implementations at the time follow that limit: +.bP +AIX\ 4 and OSF1\ 4 use the same declaration with an array of 5 non-spacing +characters \fIz\fP and a single spacing character \fIc\fP. +.bP +HP-UX\ 10 uses an opaque structure with 28 bytes, +which is large enough for the 6 \fBwchar_t\fP values. +.bP +Solaris xpg4 curses uses a single array of 6 \fBwchar_t\fP values. +.PP +This implementation's \fBcchar_t\fP was defined in 1995 +using \fB5\fP for the total of spacing and non-spacing characters +(\fBCCHARW_MAX\fP). +That was probably due to a misreading of the AIX\ 4 header files, +because the X/Open Curses document was not generally available at that time. +Later (in 2002), this detail was overlooked when beginning to implement +the functions using the structure. +.PP +In practice, even four non-spacing characters may seem enough. +X/Open Curses documents possible uses for non-spacing characters, +including using them for ligatures between characters +(a feature apparently not supported by any curses implementation). +Unicode does not limit the (analogous) number of combining characters, +so some applications may be affected. .SH SEE ALSO .PP Functions: |