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, extended_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);
17 /* extension */
18 int slk_wset(int labnum, const wchar_t *label, int fmt);
19 char *slk_label(int labnum);
21 int slk_refresh(void);
23 int slk_noutrefresh(void);
24 int slk_clear(void);
25 int slk_restore(void);
26 int slk_touch(void);
27 int slk_attron(const chtype attrs);
29 int slk_attroff(const chtype attrs);
30 int slk_attrset(const chtype attrs);
31 int slk_attr_on(attr_t attrs, void* opts);
32 int slk_attr_off(const attr_t attrs, void * opts);
33 int slk_attr_set(const attr_t attrs, short pair, void* opts);
34 attr_t slk_attr(void);
36 int slk_color(short pair);
38 /* extension */
39 int extended_slk_color(int pair);
40
42 The slk* functions manipulate the set of soft function-key labels that
43 exist on many terminals. For those terminals that do not have soft la‐
44 bels, curses takes over the bottom line of stdscr, reducing the size of
45 stdscr and the variable LINES. curses standardizes on eight labels of
46 up to eight characters each. In addition to this, the ncurses imple‐
47 mentation supports a mode where it simulates 12 labels of up to five
48 characters each. This is useful for PC-like enduser devices. ncurses
49 simulates this mode by taking over up to two lines at the bottom of the
50 screen; it does not try to use any hardware support for this mode.
51 Initialization
53 The slk_init routine must be called before initscr or newterm is
54 called. If initscr eventually uses a line from stdscr to emulate the
55 soft labels, then fmt determines how the labels are arranged on the
56 screen:
57 0 indicates a 3-2-3 arrangement of the labels.
59 1 indicates a 4-4 arrangement
61 2 indicates the PC-like 4-4-4 mode.
63 3 is again the PC-like 4-4-4 mode, but in addition an index line is
65 generated, helping the user to identify the key numbers easily.
66 Labels
68 The slk_set routine (and the slk_wset routine for the wide-character
69 library) has three parameters:
70 labnum
72 is the label number, from 1 to 8 (12 for fmt in slk_init is 2
73 or 3);
74 label
76 is be the string to put on the label, up to eight (five for fmt
77 in slk_init is 2 or 3) characters in length. A null string or
78 a null pointer sets up a blank label.
79 fmt is either 0, 1, or 2, indicating whether the label is to be
81 left-justified, centered, or right-justified, respectively,
82 within the label.
83 The slk_label routine returns the current label for label number lab‐
85 num, with leading and trailing blanks stripped.
86 Screen updates
88 The slk_refresh and slk_noutrefresh routines correspond to the wrefresh
89 and wnoutrefresh routines.
90 The slk_clear routine clears the soft labels from the screen.
92 The slk_restore routine restores the soft labels to the screen after a
94 slk_clear has been performed.
95 The slk_touch routine forces all the soft labels to be output the next
97 time a slk_noutrefresh is performed.
98 Video attributes
100 The slk_attron, slk_attrset, slk_attroff and slk_attr routines corre‐
101 spond to attron, attrset, attroff and attr_get, respectively. They
102 have an effect only if soft labels are simulated on the bottom line of
103 the screen. The default highlight for soft keys is A_STANDOUT (as in
104 System V curses, which does not document this fact).
105 Colors
107 The slk_color routine corresponds to color_set. It has an effect only
108 if soft labels are simulated on the bottom line of the screen.
109 Because slk_color accepts only short (signed 16-bit integer) values,
111 this implementation provides extended_slk_color which accepts an inte‐
112 ger value, e.g., 32-bits.
113
115 These routines return ERR upon failure and OK (SVr4 specifies only "an
116 integer value other than ERR") upon successful completion.
117 X/Open defines no error conditions. In this implementation
119 slk_attr
121 returns the attribute used for the soft keys.
122 slk_attroff, slk_attron, slk_clear, slk_noutrefresh, slk_refresh,
124 slk_touch
125 return an error if the terminal or the softkeys were not ini‐
126 tialized.
127 slk_attrset
129 returns an error if the terminal or the softkeys were not ini‐
130 tialized.
131 slk_attr_set
133 returns an error if the terminal or the softkeys were not ini‐
134 tialized, or the color pair is outside the range 0..COL‐
135 OR_PAIRS-1.
136 slk_color
138 returns an error if the terminal or the softkeys were not ini‐
139 tialized, or the color pair is outside the range 0..COL‐
140 OR_PAIRS-1.
141 slk_init
143 returns an error if the format parameter is outside the range
144 0..3.
145 slk_label
147 returns NULL on error.
148 slk_set
150 returns an error if the terminal or the softkeys were not ini‐
151 tialized, or the labnum parameter is outside the range of label
152 counts, or if the format parameter is outside the range 0..2,
153 or if memory for the labels cannot be allocated.
154
156 SVr3 introduced these functions:
157 slk_clear
158 slk_init
159 slk_label
160 slk_noutrefresh
161 slk_refresh
162 slk_restore
163 slk_set
164 slk_touch
165 SVr4 added these functions:
167 slk_attroff
168 slk_attron
169 slk_attrset
170 slk_start
171 X/Open Curses added these:
173 slk_attr_off
174 slk_attr_on
175 slk_attr_set
176 slk_color
177 slk_wset
178
180 X/Open Curses documents the opts argument as reserved for future use,
181 saying that it must be null. This implementation uses that parameter
182 in ABI 6 for the functions which have a color-pair parameter to support
183 extended color pairs.
184 For functions which modify the color, e.g., slk_attr_set, if opts is
186 set it is treated as a pointer to int, and used to set the color
187 pair instead of the short pair parameter.
188
190 Most applications would use slk_noutrefresh because a wrefresh is like‐
191 ly to follow soon.
192
194 The XSI Curses standard, Issue 4, described the soft-key functions,
195 with some differences from SVr4 curses:
196 • It added functions like the SVr4 attribute-manipulation functions
198 slk_attron, slk_attroff, slk_attrset, but which use attr_t parame‐
199 ters (rather than chtype), along with a reserved opts parameter.
200 Two of these new functions (unlike the SVr4 functions) have no pro‐
202 vision for color: slk_attr_on and slk_attr_off.
203 The third function (slk_attr_set) has a color-pair parameter.
205 • It added const qualifiers to parameters (unnecessarily), and
207 • It added slk_color.
209 The format codes 2 and 3 for slk_init and the function slk_attr are
211 specific to ncurses.
212 X/Open Curses does not specify a limit for the number of colors and
214 color pairs which a terminal can support. However, in its use of short
215 for the parameters, it carries over SVr4's implementation detail for
216 the compiled terminfo database, which uses signed 16-bit numbers. This
217 implementation provides extended versions of those functions which use
218 short parameters, allowing applications to use larger color- and pair-
219 numbers.
220
222 curses(3X), curs_attr(3X), curs_initscr(3X), curs_refresh(3X),
223 curs_variables(3X).
224 curs_slk(3X)