- The slk* functions manipulate the set of soft function-key labels that
- exist on many terminals. For those terminals that do not have soft la-
- bels, curses takes over the bottom line of stdscr, reducing the size of
- stdscr and the variable LINES. curses standardizes on eight labels of
- up to eight characters each. In addition to this, the ncurses imple-
- mentation supports a mode where it simulates 12 labels of up to five
- characters each. This is useful for PC-like enduser devices. ncurses
- simulates this mode by taking over up to two lines at the bottom of the
- screen; it does not try to use any hardware support for this mode.
+ These functions manipulate the soft function key labels that some
+ hardware terminals support. For those terminals that do not have soft
+ labels, curses takes over the bottom line of stdscr, reducing its
+ vertical size and the value of LINES by one. By default, curses uses
+ eight labels of up to eight characters each.
+
+ ncurses furthermore supports a mode comprising twelve labels of up to
+ five characters each, following a convention associated with the IBM
+ PC/AT keyboard. ncurses simulates this mode by taking over up to two
+ lines at the bottom of the screen; it does not try to use any hardware
+ support for this mode.
- The slk_init routine must be called before initscr or newterm is
- called. If initscr eventually uses a line from stdscr to emulate the
- soft labels, then fmt determines how the labels are arranged on the
- screen:
+ slk_init must be called before initscr or newterm. If initscr
+ eventually uses a line from stdscr to emulate the soft labels, then fmt
+ determines how the labels are arranged on the screen.
- 0 indicates a 3-2-3 arrangement of the labels.
+ 0 indicates a 3-2-3 arrangement of the labels.
- 1 indicates a 4-4 arrangement
+ 1 indicates a 4-4 arrangement
- 2 indicates the PC-like 4-4-4 mode.
+ 2 indicates the PC-like 4-4-4 mode.
- 3 is again the PC-like 4-4-4 mode, but in addition an index line is
- generated, helping the user to identify the key numbers easily.
+ 3 is again the PC-like 4-4-4 mode, but in addition an index line is
+ generated, helping the user to associate each label with its
+ numbered function key. LINES and the vertical size of stdscr are
+ further reduced.
- The slk_set routine (and the slk_wset routine for the wide-character
- library) has three parameters:
+ Populate the labels with normal strings (slk_set) or wide-character
+ strings (slk_wset). Each function takes three parameters.
- labnum
- is the label number, from 1 to 8 (12 for fmt in slk_init is 2
- or 3);
+ labnum is the label number, from 1 to 8 (12 if fmt in slk_init is 2 or
+ 3);
- label
- is be the string to put on the label, up to eight (five for fmt
- in slk_init is 2 or 3) characters in length. A null string or
+ label is be the string to put on the label, up to eight (five if fmt
+ in slk_init is 2 or 3) characters in length. A empty string or
a null pointer sets up a blank label.
- fmt is either 0, 1, or 2, indicating whether the label is to be
- left-justified, centered, or right-justified, respectively,
- within the label.
+ align is 0, 1, or 2, aligning label to the left, center, or right,
+ respectively, within the 8 (5) character cells housing it.
- The slk_label routine returns the current label for label number lab-
- num, with leading and trailing blanks stripped.
+ slk_label obtains the string assigned to label number labnum, with any
+ leading and trailing blanks stripped.
-
+ slk_refresh and slk_noutrefresh affect the soft key label lines as
+ wrefresh and wnoutrefresh do the curses window.
The slk_clear routine clears the soft labels from the screen.
@@ -144,117 +145,175 @@
time a slk_noutrefresh is performed.
-
- The slk_attron, slk_attrset, slk_attroff and slk_attr routines corre-
- spond to attron, attrset, attroff and attr_get. They have an effect
- only if soft labels are simulated on the bottom line of the screen.
- The default highlight for soft keys is A_STANDOUT (as in System V curs-
- es, which does not document this fact).
+
+ The slk_attron, slk_attrset, slk_attroff, and slk_attr routines
+ correspond to attron, attrset, attroff, and attr_get, 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
+ A_STANDOUT (as in System V curses, which does not document this fact).
The slk_color routine corresponds to color_set. It has an effect only
if soft labels are simulated on the bottom line of the screen.
- Because slk_color accepts only short (signed 16-bit integer) values,
- this implementation provides extended_slk_color which accepts an inte-
- ger value, e.g., 32-bits.
+ Because slk_color accepts only short (signed 16-bit integer) values,
+ this implementation provides extended_slk_color, which accepts an int
+ value of at least 32 bits.
- These routines return ERR upon failure and OK (SVr4 specifies only "an
- integer value other than ERR") upon successful completion.
+ Routines that return an integer return ERR upon failure and OK (SVr4
+ specifies only "an integer value other than ERR") upon successful
+ completion.
+
+ X/Open Curses defines no error conditions.
- X/Open defines no error conditions. In this implementation
+ In this implementation
slk_attr
returns the attribute used for the soft keys.
- slk_attroff, slk_attron, slk_clear, slk_noutrefresh, slk_refresh,
+ slk_attroff, slk_attron, slk_clear, slk_noutrefresh, slk_refresh,
slk_touch
- return an error if the terminal or the softkeys were not ini-
- tialized.
+ return an error if the terminal or the softkeys were not
+ initialized.
slk_attrset
- returns an error if the terminal or the softkeys were not ini-
- tialized.
+ returns an error if the terminal or the softkeys were not
+ initialized.
slk_attr_set
- returns an error if the terminal or the softkeys were not ini-
- tialized, or the color pair is outside the range 0..COL-
- OR_PAIRS-1.
+ returns an error if the terminal or the softkeys were not
+ initialized, or the color pair is outside the range
+ 0..COLOR_PAIRS-1.
slk_color
- returns an error if the terminal or the softkeys were not ini-
- tialized, or the color pair is outside the range 0..COL-
- OR_PAIRS-1.
+ returns an error if the terminal or the softkeys were not
+ initialized, or the color pair is outside the range
+ 0..COLOR_PAIRS-1.
slk_init
- returns an error if the format parameter is outside the range
+ returns an error if the format parameter is outside the range
0..3.
slk_label
returns NULL on error.
slk_set
- returns an error if the terminal or the softkeys were not ini-
- tialized, or the labnum 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.
+ returns an error if the terminal or the softkeys were not
+ initialized, or the labnum 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.
+
+
+
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
+ 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., slk_attr_set, 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.
-
-
-
- Most applications would use slk_noutrefresh because a wrefresh is like-
- ly to follow soon.
+ For functions which modify the color, e.g., slk_attr_set, 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.
- The XSI Curses standard, Issue 4, described the soft-key functions,
- with some differences from SVr4 curses:
+ X/Open Curses, Issue 4 describes these functions, with some differences
+ from SVr4 curses:
- o It added functions like the SVr4 attribute-manipulation functions
- slk_attron, slk_attroff, slk_attrset, but which use attr_t parame-
- ters (rather than chtype), along with a reserved opts parameter.
+ o X/Open added functions like the SVr4 attribute-manipulation
+ functions slk_attron, slk_attroff, and slk_attrset, but which use
+ attr_t parameters (rather than chtype), along with a reserved opts
+ parameter.
- Two of these new functions (unlike the SVr4 functions) have no pro-
- vision for color: slk_attr_on and slk_attr_off.
+ Two of these new functions (unlike the SVr4 functions) have no
+ provision for color: slk_attr_on and slk_attr_off.
- The third function (slk_attr_set) has a color-pair parameter.
+ The third function (slk_attr_set) has a color pair parameter.
- o It added const qualifiers to parameters (unnecessarily), and
+ o It added const qualifiers to parameters (unnecessarily), and
o It added slk_color.
- The format codes 2 and 3 for slk_init and the function slk_attr are
- specific to ncurses.
+ Although slk_start is declared in the curses 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):
+
+ oslk_start has two parameters:
+
+ ong (number of groups) and
+
+ ogp (group pointer).
+
+ o Soft-key groups are an array of ng integers.
- 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 short
- for the parameters, it carries over SVr4's implementation detail for
+ o In SVr4, slk_init calls slk_start passing a null for gp. For this
+ case, slk_start uses the number of groups ng (3 for the 3-2-3
+ layout, 2 for the 4-4 layout) which slk_init provided.
+
+ If ng is neither 2 or 3, slk_start checks the terminfo fln
+ (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 fln capability, slk_start returns ERR.
+
+ o If slk_start is given a non-null gp, it copies the ng elements of
+ the group of soft-keys, up to 16.
+
+ If there are more than 16 elements, slk_start returns an error.
+
+ o The format codes 2 and 3 for slk_init were added by ncurses in
+ 1996. PDCurses 2.4 added this feature in 2001.
+
+ The function slk_attr was added by ncurses 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 short
+ 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
- short parameters, allowing applications to use larger color- and pair-
+ implementation provides extended versions of those functions which use
+ int parameters, allowing applications to use larger color- and pair-
numbers.
+