<!--
****************************************************************************
- * Copyright (c) 2001-2012,2015 Free Software Foundation, Inc. *
+ * Copyright (c) 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 *
* sale, use or other dealings in this Software without prior written *
* authorization. *
****************************************************************************
- * @Id: curs_getcchar.3x,v 1.17 2015/07/21 09:30:38 tom Exp @
+ * @Id: curs_getcchar.3x,v 1.18 2017/03/31 10:50:54 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
-</PRE>
-<H2><a name="h2-NAME">NAME</a></H2><PRE>
+</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
<STRONG>getcchar</STRONG>, <STRONG>setcchar</STRONG> - Get a wide character string and ren-
dition from a <STRONG>cchar_t</STRONG> or set a <STRONG>cchar_t</STRONG> from a wide-charac-
ter string
-</PRE>
-<H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
+</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
<STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
<STRONG>int</STRONG> <STRONG>getcchar(</STRONG>
<STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM> <STRONG>);</STRONG>
-</PRE>
-<H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
+</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
-</PRE>
-<H3><a name="h3-getcchar">getcchar</a></H3><PRE>
+</PRE><H3><a name="h3-getcchar">getcchar</a></H3><PRE>
The <STRONG>getcchar</STRONG> function gets a wide-character string and
rendition from a <STRONG>cchar_t</STRONG> argument. When <EM>wch</EM> is not a null
pointer, the <STRONG>getcchar</STRONG> function does the following:
<EM>color</EM><STRONG>_</STRONG><EM>pair</EM>
-</PRE>
-<H3><a name="h3-setcchar">setcchar</a></H3><PRE>
+</PRE><H3><a name="h3-setcchar">setcchar</a></H3><PRE>
The <STRONG>setcchar</STRONG> function initializes the location pointed to
by <EM>wcval</EM> by using:
allowed.
-</PRE>
-<H2><a name="h2-NOTES">NOTES</a></H2><PRE>
- The <EM>opts</EM> argument is reserved for future use. Currently,
- an application must provide a null pointer as <EM>opts</EM>.
+</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
+ X/Open Curses documents the <EM>opts</EM> argument as reserved for
+ future use, saying that it must be null. This implementa-
+ tion uses that parameter in ABI 6 for the functions which
+ have a color-pair parameter to support extended color
+ pairs:
+ <STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>setc-</STRONG>
+ <STRONG>char</STRONG>, if <EM>opts</EM> is set it is treated as a pointer to
+ <STRONG>int</STRONG>, and used to set the color pair instead of the
+ <STRONG>short</STRONG> pair parameter.
+
+ <STRONG>o</STRONG> For functions which retrieve the color, e.g., <STRONG>getc-</STRONG>
+ <STRONG>char</STRONG>, if <EM>opts</EM> is set it is treated as a pointer to
+ <STRONG>int</STRONG>, and used to retrieve the color pair as an <STRONG>int</STRONG>
+ value, in addition retrieving it via the standard
+ pointer to <STRONG>short</STRONG> parameter.
+
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
The <EM>wcval</EM> argument may be a value generated by a call to
<STRONG>setcchar</STRONG> or by a function that has a <STRONG>cchar_t</STRONG> output argu-
ment. If <EM>wcval</EM> is constructed by any other means, the
effect is unspecified.
-</PRE>
-<H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
When <EM>wch</EM> is a null pointer, <STRONG>getcchar</STRONG> returns the number of
wide characters referenced by <EM>wcval</EM>, including one for a
trailing null.
wise, it returns <STRONG>ERR</STRONG>.
-</PRE>
-<H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
Functions: <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,
<STRONG>wcwidth(3)</STRONG>.
<li><a href="#h3-setcchar">setcchar</a></li>
</ul>
</li>
+<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
projects / ncurses.git / blobdiff