X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_getcchar.3x.html;h=0c78ef7470cacf7a6fbefaadea93388db41003bd;hp=ecc6ba7c385f077633de8dc28728c1549f10d772;hb=9f479192e3ca3413d235c66bf058f8cc63764898;hpb=8f6d94b8d6211a2323caef53fa4c96c475ec9a62 diff --git a/doc/html/man/curs_getcchar.3x.html b/doc/html/man/curs_getcchar.3x.html index ecc6ba7c..0c78ef74 100644 --- a/doc/html/man/curs_getcchar.3x.html +++ b/doc/html/man/curs_getcchar.3x.html @@ -1,6 +1,7 @@ -
--curs_getcchar(3x) curs_getcchar(3x) +curs_getcchar(3X) curs_getcchar(3X)
- getcchar, setcchar - Get a wide character string and rendition from a - cchar_t or set a cchar_t from a wide-character string + getcchar, setcchar - Get a wide character string and rendition from a + cchar_t or set a cchar_t from a wide-character string
- #include <curses.h> + #include <curses.h> - int getcchar( - const cchar_t *wcval, - wchar_t *wch, - attr_t *attrs, - short *color_pair, - void *opts ); + int getcchar( + const cchar_t *wcval, + wchar_t *wch, + attr_t *attrs, + short *color_pair, + void *opts ); - int setcchar( - cchar_t *wcval, - const wchar_t *wch, - const attr_t attrs, - short color_pair, - const void *opts ); + int setcchar( + cchar_t *wcval, + const wchar_t *wch, + const attr_t attrs, + short color_pair, + 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 func- - tion does the following: + 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: - o Extracts information from a cchar_t value wcval + o Extracts information from a cchar_t value wcval - o Stores the character attributes in the location pointed to by attrs + o Stores the character attributes in the location pointed to by attrs - o Stores the color-pair in the location pointed to by color_pair + o Stores the color-pair in the location pointed to by color_pair - o Stores the wide-character string, characters referenced by wcval, - into the array pointed to by wch. + o Stores the wide-character string, characters referenced by wcval, + into the array pointed to by wch. - When wch is a null pointer, the getcchar function does the following: + When wch is a null pointer, the getcchar function does the following: - o Obtains the number of wide characters pointed to by wcval + o Obtains the number of wide characters pointed to by wcval - o Does not change the data referenced by attrs or color_pair + o Does not change the data referenced by attrs or color_pair
- The setcchar function initializes the location pointed to by wcval by + The setcchar function initializes the location pointed to by wcval by using: - o The character attributes in attrs + o The character attributes in attrs - o The color pair in color_pair + o The color pair in color_pair - o The wide-character string pointed to by wch. The string must be + o The wide-character string pointed to by wch. The string must be L'\0' terminated, contain at most one spacing character, which must be the first. - Up to CCHARW_MAX-1 nonspacing characters may follow. Additional + Up to CCHARW_MAX-1 nonspacing characters may follow. Additional nonspacing characters are ignored. The string may contain a single control character instead. In that @@ -111,44 +112,91 @@
- X/Open Curses documents the opts argument as reserved for future use, + 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 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 stan- - dard pointer to short 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 wcval argument may be a value generated by a call to setcchar or by - a function that has a cchar_t output argument. If wcval is constructed + The wcval argument may be a value generated by a call to setcchar or by + a function that has a cchar_t output argument. If wcval is constructed by any other means, the effect is unspecified.
- When wch is a null pointer, getcchar returns the number of wide charac- - ters referenced by wcval, including one for a trailing null. + When wch is a null pointer, getcchar returns the number of wide + characters referenced by wcval, including one for a trailing null. - When wch is not a null pointer, getcchar returns OK upon successful - completion, and ERR otherwise. + When wch is not a null pointer, getcchar returns OK upon successful + completion, and ERR otherwise. - Upon successful completion, setcchar returns OK. Otherwise, it returns - ERR. + Upon successful completion, setcchar returns OK. Otherwise, it returns + ERR. + + +
+ 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.
- Functions: curs_attr(3x), curs_color(3x), curses(3x), wcwidth(3). + Functions: curs_attr(3X), curs_color(3X), curses(3X), wcwidth(3). - curs_getcchar(3x) + curs_getcchar(3X)