1curs_slk(3X)                                                      curs_slk(3X)
2
3
4

NAME

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

SYNOPSIS

12       #include <curses.h>
13
14       int slk_init(int fmt);
15
16       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
20       char *slk_label(int labnum);
21
22       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
28       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
35       attr_t slk_attr(void);
36
37       int slk_color(short pair);
38       /* extension */
39       int extended_slk_color(int pair);
40

DESCRIPTION

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
52   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
58          0  indicates a 3-2-3 arrangement of the labels.
59
60          1  indicates a 4-4 arrangement
61
62          2  indicates the PC-like 4-4-4 mode.
63
64          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
67   Labels
68       The slk_set routine (and the slk_wset routine  for  the  wide-character
69       library) has three parameters:
70
71          labnum
72               is  the  label number, from 1 to 8 (12 for fmt in slk_init is 2
73               or 3);
74
75          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
80          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
84       The slk_label routine returns the current label for label  number  lab‐
85       num, with leading and trailing blanks stripped.
86
87   Screen updates
88       The slk_refresh and slk_noutrefresh routines correspond to the wrefresh
89       and wnoutrefresh routines.
90
91       The slk_clear routine clears the soft labels from the screen.
92
93       The slk_restore routine restores the soft labels to the screen after  a
94       slk_clear has been performed.
95
96       The  slk_touch routine forces all the soft labels to be output the next
97       time a slk_noutrefresh is performed.
98
99   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
106   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
110       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

RETURN VALUE

115       These  routines return ERR upon failure and OK (SVr4 specifies only "an
116       integer value other than ERR") upon successful completion.
117
118       X/Open defines no error conditions.  In this implementation
119
120          slk_attr
121               returns the attribute used for the soft keys.
122
123          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
128          slk_attrset
129               returns an error if the terminal or the softkeys were not  ini‐
130               tialized.
131
132          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
137          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
142          slk_init
143               returns  an  error if the format parameter is outside the range
144               0..3.
145
146          slk_label
147               returns NULL on error.
148
149          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

HISTORY

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
166       SVr4 added these functions:
167         slk_attroff
168         slk_attron
169         slk_attrset
170         slk_start
171
172       X/Open Curses added these:
173         slk_attr_off
174         slk_attr_on
175         slk_attr_set
176         slk_color
177         slk_wset
178

EXTENSIONS

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
185       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

NOTES

190       Most applications would use slk_noutrefresh because a wrefresh is like‐
191       ly to follow soon.
192

PORTABILITY

194       The  XSI  Curses  standard,  Issue 4, described the soft-key functions,
195       with some differences from SVr4 curses:
196
197       •   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
201           Two of these new functions (unlike the SVr4 functions) have no pro‐
202           vision for color: slk_attr_on and slk_attr_off.
203
204           The third function (slk_attr_set) has a color-pair parameter.
205
206       •   It added const qualifiers to parameters (unnecessarily), and
207
208       •   It added slk_color.
209
210       The  format  codes  2  and 3 for slk_init and the function slk_attr are
211       specific to ncurses.
212
213       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

SEE ALSO

222       curses(3X),    curs_attr(3X),    curs_initscr(3X),    curs_refresh(3X),
223       curs_variables(3X).
224
225
226
227                                                                  curs_slk(3X)
Impressum