# curs_slk

## NAME



           **slk_init** , **slk_set** , **slk_wset** , **slk_refresh** , **slk_noutrefresh** ,
           **slk_label** , **slk_clear** , **slk_restore** , **slk_touch** , **slk_attron** ,
           **slk_attrset** , **slk_attroff** , **slk_attr_on** , **slk_attr_set** , **slk_attr_off** ,
           **slk_attr** , **slk_color** , **extended_slk_color** - **curses** soft label
           routines
    


## SYNOPSIS



           **#include <curses.h>**
    
           **int slk_init(int** _fmt_**);**
    
           **int slk_set(int** _labnum_**, const char ***_label_**, int** _fmt_**);**
           **int slk_wset(int** _labnum_**, const wchar_t ***_label_**, int** _fmt_**);**
    
           **char *slk_label(int** _labnum_**);**
    
           **int slk_refresh(void);**
           **int slk_noutrefresh(void);**
           **int slk_clear(void);**
           **int slk_restore(void);**
           **int slk_touch(void);**
    
           **int slk_attron(const chtype** _attrs_**);**
           **int slk_attroff(const chtype** _attrs_**);**
           **int slk_attrset(const chtype** _attrs_**);**
           **int slk_attr_on(attr_t** _attrs_**, void***_opts_**);**
           **int slk_attr_off(const attr_t** _attrs_**, void ***_opts_**);**
           **int slk_attr_set(const attr_t** _attrs_**, short** _pair_**, void***_opts_**);**
           /* extension */
           **attr_t slk_attr(void);**
    
           **int slk_color(short** _pair_**);**
           /* extension */
           **int extended_slk_color(int** _pair_**);**
    


## DESCRIPTION



           The  slk* functions manipulate the set of soft function-key labels
           that exist on many terminals.  For those  terminals  that  do  not
           have soft labels, **curses** takes over the bottom line of **stdscr** , re‐
           ducing  the  size  of **stdscr** and the variable **LINES**.  **curses** stan‐
           dardizes on eight labels of up to eight characters each.  In addi‐
           tion to this, the ncurses implementation 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 tak‐
           ing over up to two lines at the bottom of the screen; it does  not
           try to use any hardware support for this mode.
    
       **Initialization**
           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:
    
              **0** indicates a 3-2-3 arrangement of the labels.
    
              **1** indicates a 4-4 arrangement
    
              **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 num‐
                 bers easily.
    
       **Labels**
           The **slk_set** routine (and the **slk_wset** routine for the wide-charac‐
           ter library) has three parameters:
    
              _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 if
                   _fmt_ in **slk_init** is **2** or **3**) characters in length.  A null
                   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, respec‐
                   tively, within the label.
    
           The **slk_label** routine returns the current label for label number
           _labnum_ , with leading and trailing blanks stripped.
    
       **Screen updates**
           The **slk_refresh** and **slk_noutrefresh** routines correspond to the
           **wrefresh** and **wnoutrefresh** routines.
    
           The **slk_clear** routine clears the soft labels from the screen.
    
           The **slk_restore** routine restores the soft labels to the screen af‐
           ter a **slk_clear** has been performed.
    
           The **slk_touch** routine forces all the soft labels to be output the
           next time a **slk_noutrefresh** is performed.
    
       **Video attributes**
           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 bot‐
           tom line of the screen.  The default highlight for soft keys is
           A_STANDOUT (as in System V curses, which does not document this
           fact).
    
       **Colors**
           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) val‐
           ues, this implementation provides **extended_slk_color** which accepts
           an integer value, e.g., 32-bits.
    


## RETURN VALUE



           These routines return **ERR** upon failure and **OK**(SVr4 specifies only
           "an integer value other than **ERR** ") upon successful completion.
    
           X/Open defines no error conditions.  In this implementation
    
              **slk_attr**
                   returns the attribute used for the soft keys.
    
              **slk_attroff** , **slk_attron** , **slk_clear** , **slk_noutrefresh** ,
              **slk_refresh** , **slk_touch**
                   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
                   initialized.
    
              **slk_attr_set**
                   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
                   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 0..3.
    
              **slk_label**
                   returns **NULL** on error.
    
              **slk_set**
                   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 allocat‐
                   ed.
    


## EXTENSIONS



           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 para‐
           meter 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.
    


## NOTES



           Most applications would use **slk_noutrefresh** because a **wrefresh** is
           likely to follow soon.
    


## PORTABILITY



           The XSI Curses standard, Issue 4, described the soft-key func‐
           tions, with some differences from SVr4 curses:
    
           •   It added functions like the SVr4 attribute-manipulation func‐
               tions **slk_attron** , **slk_attroff** , **slk_attrset** , but which use **at‐**
               **tr_t** parameters (rather than **chtype**), along with a reserved
               _opts_ parameter.
    
               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.
    
           •   It added **const** qualifiers to parameters (unnecessarily), and
    
           •   It added **slk_color**.
    
           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):
    
           •   **slk_start** has two parameters:
    
               •   _ng_ (number of groups) and
    
               •   _gp_ (group pointer).
    
           •   Soft-key groups are an array of _ng_ integers.
    
           •   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-sepa‐
               rated 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.
    
           •   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 er‐
               ror.
    
           •   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 **int** parameters, allowing applications to
           use larger color- and pair-numbers.
    


* * *