+ The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen.
+
+ The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a
+ <STRONG>slk_clear</STRONG> has been performed.
+
+ The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next
+ time a <STRONG>slk_noutrefresh</STRONG> is performed.
+
+
+</PRE><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><PRE>
+ The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines
+ correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively.
+ They have an effect only if soft labels are simulated on the bottom
+ line of the screen. The default highlight for soft key labels is
+ <STRONG>A_STANDOUT</STRONG> (as in System V <EM>curses</EM>, which does not document this fact).
+
+
+</PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
+ The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only
+ if soft labels are simulated on the bottom line of the screen.
+
+ Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values,
+ this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM>
+ value of at least 32 bits.
+
+
+</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
+ Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
+ specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful
+ completion.
+
+ X/Open Curses defines no error conditions.
+
+ In this implementation
+
+ <STRONG>slk_attr</STRONG>
+ returns the attribute used for the soft keys.
+
+ <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>,
+ <STRONG>slk_touch</STRONG>
+ return an error if the terminal or the softkeys were not
+ initialized.
+
+ <STRONG>slk_attrset</STRONG>
+ returns an error if the terminal or the softkeys were not
+ initialized.
+
+ <STRONG>slk_attr_set</STRONG>
+ returns an error if the terminal or the softkeys were not
+ initialized, or the color pair is outside the range
+ 0..<STRONG>COLOR_PAIRS</STRONG>-1.
+
+ <STRONG>slk_color</STRONG>
+ returns an error if the terminal or the softkeys were not
+ initialized, or the color pair is outside the range
+ 0..<STRONG>COLOR_PAIRS</STRONG>-1.
+
+ <STRONG>slk_init</STRONG>
+ returns an error if the format parameter is outside the range
+ 0..3.
+
+ <STRONG>slk_label</STRONG>
+ returns <STRONG>NULL</STRONG> on error.
+
+ <STRONG>slk_set</STRONG>
+ returns an error if the terminal or the softkeys were not
+ initialized, or the <EM>labnum</EM> parameter is outside the range of
+ label counts, or if the format parameter is outside the range
+ 0..2, or if memory for the labels cannot be allocated.
+
+
+</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
+ Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is
+ likely to follow soon.
+
+
+</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 implementation uses that parameter
+ in ABI 6 for the functions which have a color pair parameter to support
+ extended color pairs.
+
+ For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is
+ set it is treated as a pointer to <EM>int</EM>, and used to set the color pair
+ instead of the <EM>short</EM> pair parameter.
+
+
+</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
+ X/Open Curses, Issue 4, describes these functions, with some
+ differences from SVr4 <EM>curses</EM>:
+
+ <STRONG>o</STRONG> X/Open added functions like the SVr4 attribute-manipulation
+ functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use
+ <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> parameters (rather than <EM>chtype</EM>), along with a reserved <EM>opts</EM>
+ parameter.
+
+ Two of these new functions (unlike the SVr4 functions) have no
+ provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
+
+ The third function (<STRONG>slk_attr_set</STRONG>) has a color pair parameter.
+
+ <STRONG>o</STRONG> It added <EM>const</EM> qualifiers to parameters (unnecessarily), and
+
+ <STRONG>o</STRONG> It added <STRONG>slk_color</STRONG>.
+
+ Although <STRONG>slk_start</STRONG> is declared in the <EM>curses</EM> header file, it was not
+ documented by SVr4 other than its presence in a list of libtermlib.so.1
+ symbols. Reading the source code (i.e., Illumos):
+
+ <STRONG>o</STRONG> <STRONG>slk_start</STRONG> has two parameters:
+
+ <STRONG>o</STRONG> <EM>ng</EM> (number of groups) and
+
+ <STRONG>o</STRONG> <EM>gp</EM> (group pointer).
+
+ <STRONG>o</STRONG> Soft-key groups are an array of <EM>ng</EM> integers.
+
+ <STRONG>o</STRONG> In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>. For this
+ case, <STRONG>slk_start</STRONG> uses the number of groups <EM>ng</EM> (3 for the 3-2-3
+ layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided.
+
+ If <EM>ng</EM> is neither 2 or 3, <STRONG>slk_start</STRONG> checks the terminfo <STRONG>fln</STRONG>
+ (label_format) capability, interpreting that as a comma-separated
+ list of numbers, e.g., "3,2,3" for the 3-2-3 layout.
+
+ Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
+
+ <STRONG>o</STRONG> If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of
+ the group of soft-keys, up to 16.
+
+ If there are more than 16 elements, <STRONG>slk_start</STRONG> returns an error.
+
+ <STRONG>o</STRONG> The format codes <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> were added by <EM>ncurses</EM> in
+ 1996. PDCurses 2.4 added this feature in 2001.
+
+ The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996.
+
+ X/Open Curses does not specify a limit for the number of colors and
+ color pairs which a terminal can support. However, in its use of <EM>short</EM>
+ for the parameters, it carries over SVr4's implementation detail for
+ the compiled terminfo database, which uses signed 16-bit numbers. This
+ implementation provides extended versions of those functions which use
+ <EM>int</EM> parameters, allowing applications to use larger color- and pair-
+ numbers.
+
+
+</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
+ SVr3 introduced these functions:
+ <STRONG>slk_clear</STRONG>
+ <STRONG>slk_init</STRONG>
+ <STRONG>slk_label</STRONG>
+ <STRONG>slk_noutrefresh</STRONG>
+ <STRONG>slk_refresh</STRONG>
+ <STRONG>slk_restore</STRONG>
+ <STRONG>slk_set</STRONG>
+ <STRONG>slk_touch</STRONG>
+
+ SVr4 added these functions:
+ <STRONG>slk_attroff</STRONG>
+ <STRONG>slk_attron</STRONG>
+ <STRONG>slk_attrset</STRONG>
+ <STRONG>slk_start</STRONG>
+
+ X/Open Curses added these:
+ <STRONG>slk_attr_off</STRONG>
+ <STRONG>slk_attr_on</STRONG>
+ <STRONG>slk_attr_set</STRONG>
+ <STRONG>slk_color</STRONG>
+ <STRONG>slk_wset</STRONG>
+
+
+</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
+ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
+ <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
projects / ncurses.git / blobdiff