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       int slk_wset(int labnum, const wchar_t *label, int fmt);
18
19       char *slk_label(int labnum);
20
21       int slk_refresh(void);
22       int slk_noutrefresh(void);
23       int slk_clear(void);
24       int slk_restore(void);
25       int slk_touch(void);
26
27       int slk_attron(const chtype attrs);
28       int slk_attroff(const chtype attrs);
29       int slk_attrset(const chtype attrs);
30       int slk_attr_on(attr_t attrs, void* opts);
31       int slk_attr_off(const attr_t attrs, void * opts);
32       int slk_attr_set(const attr_t attrs, short pair, void* opts);
33
34       attr_t slk_attr(void);
35
36       int slk_color(short pair);
37       /* extension */
38       int extended_slk_color(int pair);
39

DESCRIPTION

41       The slk* functions manipulate the set of soft function-key labels  that
42       exist on many terminals.  For those terminals that do not have soft la‐
43       bels, curses takes over the bottom line of stdscr, reducing the size of
44       stdscr  and the variable LINES.  curses standardizes on eight labels of
45       up to eight characters each.  In addition to this, the  ncurses  imple‐
46       mentation  supports  a  mode where it simulates 12 labels of up to five
47       characters each.  This is useful for PC-like enduser devices.   ncurses
48       simulates this mode by taking over up to two lines at the bottom of the
49       screen; it does not try to use any hardware support for this mode.
50
51   Initialization
52       The slk_init routine must  be  called  before  initscr  or  newterm  is
53       called.   If  initscr eventually uses a line from stdscr to emulate the
54       soft labels, then fmt determines how the labels  are  arranged  on  the
55       screen:
56
57          0  indicates a 3-2-3 arrangement of the labels.
58
59          1  indicates a 4-4 arrangement
60
61          2  indicates the PC-like 4-4-4 mode.
62
63          3  is again the PC-like 4-4-4 mode, but in addition an index line is
64             generated, helping the user to identify the key numbers easily.
65
66   Labels
67       The slk_set routine (and the slk_wset routine  for  the  wide-character
68       library) has three parameters:
69
70          labnum
71               is  the  label number, from 1 to 8 (12 for fmt in slk_init is 2
72               or 3);
73
74          label
75               is be the string to put on the label, up to eight (five for fmt
76               in  slk_init is 2 or 3) characters in length.  A null string or
77               a null pointer sets up a blank label.
78
79          fmt  is either 0, 1, or 2, indicating whether the  label  is  to  be
80               left-justified,  centered,  or  right-justified,  respectively,
81               within the label.
82
83       The slk_label routine returns the current label for label  number  lab‐
84       num, with leading and trailing blanks stripped.
85
86   Screen updates
87       The slk_refresh and slk_noutrefresh routines correspond to the wrefresh
88       and wnoutrefresh routines.
89
90       The slk_clear routine clears the soft labels from the screen.
91
92       The slk_restore routine restores the soft labels to the screen after  a
93       slk_clear has been performed.
94
95       The  slk_touch routine forces all the soft labels to be output the next
96       time a slk_noutrefresh is performed.
97
98   Video attributes
99       The slk_attron, slk_attrset, slk_attroff and slk_attr  routines  corre‐
100       spond  to  attron,  attrset,  attroff and attr_get, respectively.  They
101       have an effect only if soft labels are simulated on the bottom line  of
102       the  screen.   The default highlight for soft keys is A_STANDOUT (as in
103       System V curses, which does not document this fact).
104
105   Colors
106       The slk_color routine corresponds to color_set.  It has an effect  only
107       if soft labels are simulated on the bottom line of the screen.
108
109       Because  slk_color  accepts  only short (signed 16-bit integer) values,
110       this implementation provides extended_slk_color which accepts an  inte‐
111       ger value, e.g., 32-bits.
112

RETURN VALUE

114       These  routines return ERR upon failure and OK (SVr4 specifies only "an
115       integer value other than ERR") upon successful completion.
116
117       X/Open defines no error conditions.  In this implementation
118
119          slk_attr
120               returns the attribute used for the soft keys.
121
122          slk_attroff, slk_attron, slk_clear, slk_noutrefresh, slk_refresh,
123          slk_touch
124               return  an  error if the terminal or the softkeys were not ini‐
125               tialized.
126
127          slk_attrset
128               returns an error if the terminal or the softkeys were not  ini‐
129               tialized.
130
131          slk_attr_set
132               returns  an error if the terminal or the softkeys were not ini‐
133               tialized, or the  color  pair  is  outside  the  range  0..COL‐
134               OR_PAIRS-1.
135
136          slk_color
137               returns  an error if the terminal or the softkeys were not ini‐
138               tialized, or the  color  pair  is  outside  the  range  0..COL‐
139               OR_PAIRS-1.
140
141          slk_init
142               returns  an  error if the format parameter is outside the range
143               0..3.
144
145          slk_label
146               returns NULL on error.
147
148          slk_set
149               returns an error if the terminal or the softkeys were not  ini‐
150               tialized, or the labnum parameter is outside the range of label
151               counts, or if the format parameter is outside the  range  0..2,
152               or if memory for the labels cannot be allocated.
153

EXTENSIONS

155       X/Open  Curses  documents the opts argument as reserved for future use,
156       saying that it must be null.  This implementation uses  that  parameter
157       in ABI 6 for the functions which have a color-pair parameter to support
158       extended color pairs.
159
160       For  functions  which modify the color, e.g., slk_attr_set, if opts  is
161       set  it  is  treated  as a pointer to int, and used to  set  the  color
162       pair instead of the short pair parameter.
163

NOTES

165       Most applications would use slk_noutrefresh because a wrefresh is like‐
166       ly to follow soon.
167

PORTABILITY

169       The  XSI  Curses  standard,  Issue 4, described the soft-key functions,
170       with some differences from SVr4 curses:
171
172       ·   It added functions like the SVr4  attribute-manipulation  functions
173           slk_attron,  slk_attroff, slk_attrset, but which use attr_t parame‐
174           ters (rather than chtype), along with a reserved opts parameter.
175
176           Two of these new functions (unlike the SVr4 functions) have no pro‐
177           vision for color: slk_attr_on and slk_attr_off.
178
179           The third function (slk_attr_set) has a color-pair parameter.
180
181       ·   It added const qualifiers to parameters (unnecessarily), and
182
183       ·   It added slk_color.
184
185       The  format  codes  2  and 3 for slk_init and the function slk_attr are
186       specific to ncurses.
187
188       X/Open Curses does not specify a limit for the  number  of  colors  and
189       color pairs which a terminal can support.  However, in its use of short
190       for the parameters, it carries over SVr4's  implementation  detail  for
191       the compiled terminfo database, which uses signed 16-bit numbers.  This
192       implementation provides extended versions of those functions which  use
193       short  parameters, allowing applications to use larger color- and pair-
194       numbers.
195

SEE ALSO

197       curses(3X),    curs_attr(3X),    curs_initscr(3X),    curs_refresh(3X),
198       curs_variables(3X).
199
200
201
202                                                                  curs_slk(3X)
Impressum