1curs_slk(3X) curs_slk(3X)
2
6 slk_init, slk_set, slk_wset, slk_refresh, slk_noutrefresh, slk_label,
7 slk_clear, slk_restore, slk_touch, slk_attron, slk_attrset,
8 slk_attroff, slk_attr_on, slk_attr_set, slk_attr_off, slk_attr,
9 slk_color - curses soft label routines
10
12 #include <curses.h>
13 int slk_init(int fmt);
15 int slk_set(int labnum, const char *label, int fmt);
16 int slk_refresh(void);
17 int slk_noutrefresh(void);
18 char *slk_label(int labnum);
19 int slk_clear(void);
20 int slk_restore(void);
21 int slk_touch(void);
22 int slk_attron(const chtype attrs);
23 int slk_attroff(const chtype attrs);
24 int slk_attrset(const chtype attrs);
25 int slk_attr_on(attr_t attrs, void* opts);
26 int slk_attr_off(const attr_t attrs, void * opts);
27 int slk_attr_set(const attr_t attrs, short color_pair, void* opts);
28 attr_t slk_attr(void);
29 int slk_color(short color_pair);
30 int slk_wset(int labnum, const wchar_t *label, int fmt);
31
33 The slk* functions manipulate the set of soft function-key labels that
34 exist on many terminals. For those terminals that do not have soft la‐
35 bels, curses takes over the bottom line of stdscr, reducing the size of
36 stdscr and the variable LINES. curses standardizes on eight labels of
37 up to eight characters each. In addition to this, the ncurses imple‐
38 mentation supports a mode where it simulates 12 labels of up to five
39 characters each. This is useful for today's PC-like enduser devices.
40 ncurses simulates this mode by taking over up to two lines at the bot‐
41 tom of the screen; it does not try to use any hardware support for this
42 mode.
43 The slk_init routine must be called before initscr or newterm is
45 called. If initscr eventually uses a line from stdscr to emulate the
46 soft labels, then fmt determines how the labels are arranged on the
47 screen:
48 0 indicates a 3-2-3 arrangement of the labels.
50 1 indicates a 4-4 arrangement
52 2 indicates the PC-like 4-4-4 mode.
54 3 is again the PC-like 4-4-4 mode, but in addition an index
56 line is generated, helping the user to identify the key num‐
57 bers easily.
58 The slk_set routine (and the slk_wset routine for the wide-character
60 library) has three parameters:
61 labnum
63 is the label number, from 1 to 8 (12 for fmt in slk_init is
64 2 or 3);
65 label
67 is be the string to put on the label, up to eight (five for
68 fmt in slk_init is 2 or 3) characters in length. A null
69 string or a null pointer sets up a blank label.
70 fmt is either 0, 1, or 2, indicating whether the label is to be
72 left-justified, centered, or right-justified, respectively,
73 within the label.
74 The slk_refresh and slk_noutrefresh routines correspond to the wrefresh
76 and wnoutrefresh routines.
77 The slk_label routine returns the current label for label number lab‐
79 num, with leading and trailing blanks stripped.
80 The slk_clear routine clears the soft labels from the screen.
82 The slk_restore routine restores the soft labels to the screen after a
84 slk_clear has been performed.
85 The slk_touch routine forces all the soft labels to be output the next
87 time a slk_noutrefresh is performed.
88 The slk_attron, slk_attrset, slk_attroff and slk_attr routines corre‐
90 spond to attron, attrset, attroff and attr_get. They have an effect
91 only if soft labels are simulated on the bottom line of the screen.
92 The default highlight for soft keys is A_STANDOUT (as in System V curs‐
93 es, which does not document this fact).
94 The slk_color routine corresponds to color_set. It has an effect only
96 if soft labels are simulated on the bottom line of the screen.
97
99 These routines return ERR upon failure and OK (SVr4 specifies only "an
100 integer value other than ERR") upon successful completion.
101 X/Open defines no error conditions. In this implementation
103 slk_attr
105 returns the attribute used for the soft keys.
106 slk_attroff, slk_attron, slk_clear, slk_noutrefresh,
108 slk_refresh, slk_touch
109 return an error if the terminal or the softkeys were not
110 initialized.
111 slk_attrset
113 returns an error if the terminal or the softkeys were not
114 initialized.
115 slk_attr_set
117 returns an error if the terminal or the softkeys were not
118 initialized, or the color pair is outside the range 0..COL‐
119 OR_PAIRS-1, or opts is not null.
120 slk_color
122 returns an error if the terminal or the softkeys were not
123 initialized, or the color pair is outside the range 0..COL‐
124 OR_PAIRS-1.
125 slk_init
127 returns an error if the format parameter is outside the
128 range 0..3.
129 slk_label
131 returns NULL on error.
132 slk_set
134 returns an error if the terminal or the softkeys were not
135 initialized, or the labnum parameter is outside the range
136 of label counts, or if the format parameter is outside the
137 range 0..2, or if memory for the labels cannot be allocat‐
138 ed.
139
141 Most applications would use slk_noutrefresh because a wrefresh is like‐
142 ly to follow soon.
143
145 The XSI Curses standard, Issue 4, describes these functions. It
146 changes the argument type of the attribute-manipulation functions
147 slk_attron, slk_attroff, slk_attrset to be attr_t, and adds const qual‐
148 ifiers. The format codes 2 and 3 for slk_init() and the function
149 slk_attr are specific to ncurses.
150
152 curses(3X), curs_attr(3X), curs_initscr(3X), curs_refresh(3X),
153 curs_variables(3X).
154 curs_slk(3X)