X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getcchar.3x.html;h=adee87eb87778cfc4e8a67777149076a1588e9a5;hp=0ae39ca0db553e92b93f3629917dd62185f06515;hb=HEAD;hpb=46722468f47c2b77b3987729b4bcf2321cccfd01 diff --git a/doc/html/man/curs_getcchar.3x.html b/doc/html/man/curs_getcchar.3x.html index 0ae39ca0..c1edf284 100644 --- a/doc/html/man/curs_getcchar.3x.html +++ b/doc/html/man/curs_getcchar.3x.html @@ -1,7 +1,7 @@ - - +
-- +curs_getcchar(3x) Library calls curs_getcchar(3x) --
- getcchar, setcchar - Get a wide character string and ren- - dition from a cchar_t or set a cchar_t from a wide-charac- - ter string --
+ +
+ getcchar, setcchar - convert between a wide-character string and a + curses complex character + + +
#include <curses.h> int getcchar( - const cchar_t *wcval, - wchar_t *wch, + const cchar_t *wch, + wchar_t *wc, attr_t *attrs, short *color_pair, void *opts ); int setcchar( - cchar_t *wcval, - const wchar_t *wch, + cchar_t *wch, + const wchar_t *wc, const attr_t attrs, short color_pair, - void *opts ); - + const void *opts ); --
- The getcchar function gets a wide-character string and - rendition from a cchar_t argument. When wch is not a null - pointer, the getcchar function does the following: - - Extracts information from a cchar_t value wcval +
- - Stores the character attributes in the location - pointed to by attrs +
+ The getcchar function gets a wide-character string and rendition from a + cchar_t argument. When wc is not a null pointer, the getcchar function + does the following: - - Stores the color-pair in the location pointed to by - color_pair + o Extracts information from a cchar_t value wch - - Stores the wide-character string, characters refer- - enced by wcval, into the array pointed to by wch. + o Stores the character attributes in the location pointed to by attrs - When wch is a null pointer, the getcchar function does the - following: + o Stores the color pair in the location pointed to by color_pair - - Obtains the number of wide characters pointed to by - wcval + o Stores the wide-character string, characters referenced by wch, + into the array pointed to by wc. - - Does not change the data referenced by attrs or - color_pair + When wc is a null pointer, the getcchar function does the following: - The setcchar function initializes the location pointed to - by wcval by using: + o Obtains the number of wide characters pointed to by wch - - The character attributes in attrs + o Does not change the data referenced by attrs or color_pair - - The color pair in color_pair - - The wide-character string pointed to by wch. The - string must be L'\0' terminated, contain at most one - character with strictly positive width, which must be - the first, and contain no characters of negative - width. +
+ The setcchar function initializes the location pointed to by wch by + using: + o The character attributes in attrs --
- The opts argument is reserved for future use. Currently, - an application must provide a null pointer as opts. + o The color pair in color_pair - The wcval argument may be a value generated by a call to - setcchar or by a function that has a cchar_t output argu- - ment. If wcval is constructed by any other means, the - effect is unspecified. + o The wide-character string pointed to by wc. The string must be + L'\0' terminated, contain at most one spacing character, which must + be the first. + Up to CCHARW_MAX-1 non-spacing characters may follow. Additional + non-spacing characters are ignored. --
- When wch is a null pointer, getcchar returns the number of - wide characters referenced by wcval, including the null - terminator. + The string may contain a single control character instead. In that + case, no non-spacing characters are allowed. - When wch is not a null pointer, getcchar returns OK upon - successful completion, and ERR otherwise. - Upon successful completion, setcchar returns OK. Other- - wise, it returns ERR. +
+ When wc is a null pointer, getcchar returns the number of wide + characters referenced by wch, including one for a trailing null. + When wc is not a null pointer, getcchar returns OK upon successful + completion, and ERR otherwise. --
- Functions: curses(3x), wcwidth(3x), curs_attr_get(3x), - can_change_color(3x). + Upon successful completion, setcchar returns OK. Otherwise, it returns + ERR. +
+ The wch argument may be a value generated by a call to setcchar or by a + function that has a cchar_t output argument. If wch is constructed by + any other means, the effect is unspecified. +
+ X/Open Curses documents the opts 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: + o For functions which modify the color, e.g., setcchar, if opts is + set it is treated as a pointer to int, and used to set the color + pair instead of the short pair parameter. + o For functions which retrieve the color, e.g., getcchar, if opts is + set it is treated as a pointer to int, and used to retrieve the + color pair as an int value, in addition retrieving it via the + standard pointer to short parameter. +
+ The CCHARW_MAX symbol is specific to ncurses. X/Open Curses does not + provide details for the layout of the cchar_t structure. It tells what + data are stored in it: + o a spacing character (wchar_t, i.e., 32-bits). + o non-spacing characters (again, wchar_t's). + o attributes (at least 16 bits, inferred from the various ACS- and + WACS-flags). + o color pair (at least 16 bits, inferred from the unsigned short + type). + The non-spacing characters are optional, in the sense that zero or more + may be stored in a cchar_t. XOpen/Curses specifies a limit: + Implementations may limit the number of non-spacing characters that + can be associated with a spacing character, provided any limit is + at least 5. + The Unix implementations at the time follow that limit: + o AIX 4 and OSF1 4 use the same declaration with an array of 5 non- + spacing characters z and a single spacing character c. + o HP-UX 10 uses an opaque structure with 28 bytes, which is large + enough for the 6 wchar_t values. + o Solaris xpg4 curses uses a single array of 6 wchar_t values. + This implementation's cchar_t was defined in 1995 using 5 for the total + of spacing and non-spacing characters (CCHARW_MAX). 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. + 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. +
+ curses(3x), curs_attr(3x), curs_color(3x), wcwidth(3) +ncurses 6.5 2024-04-20 curs_getcchar(3x)-