Debian Codegraph @

doc/html/man/curs_slk.3x.html

raw
1 <!--
2 ****************************************************************************
3 * Copyright 2018-2024,2025 Thomas E. Dickey *
4 * Copyright 1998-2016,2017 Free Software Foundation, Inc. *
5 * *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
13 * *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
16 * *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
28 * authorization. *
29 ****************************************************************************
30 * @Id: curs_slk.3x,v 1.85 2025/01/19 00:51:10 tom Exp @
31 -->
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
33 <HTML>
34 <HEAD>
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_slk 3x 2025-01-18 ncurses 6.6 Library calls</TITLE>
38 <link rel="author" href="mailto:[email protected]">
39
40 </HEAD>
41 <BODY>
42 <H1 class="no-header">curs_slk 3x 2025-01-18 ncurses 6.6 Library calls</H1>
43 <PRE>
44 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
45
46
47 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
48 <STRONG>slk_init</STRONG>, <STRONG>slk_set</STRONG>, <STRONG>slk_wset</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_label</STRONG>,
49 <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>,
50 <STRONG>slk_attroff</STRONG>, <STRONG>slk_attr_on</STRONG>, <STRONG>slk_attr_set</STRONG>, <STRONG>slk_attr_off</STRONG>, <STRONG>slk_attr</STRONG>,
51 <STRONG>slk_color</STRONG>, <STRONG>extended_slk_color</STRONG> - <EM>curses</EM> soft label key routines
52
53
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
56
57 <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <EM>fmt</EM><STRONG>);</STRONG>
58
59 <STRONG>int</STRONG> <STRONG>slk_set(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>align</EM><STRONG>);</STRONG>
60 <STRONG>int</STRONG> <STRONG>slk_wset(int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>align</EM><STRONG>);</STRONG>
61
62 <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <EM>labnum</EM><STRONG>);</STRONG>
63
64 <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
65 <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
66 <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
67 <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
68 <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
69
70 <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
71 <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
72 <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
73 <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
74 <STRONG>int</STRONG> <STRONG>slk_attr_off(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>
75 <STRONG>int</STRONG> <STRONG>slk_attr_set(const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG><EM>opts</EM><STRONG>);</STRONG>
76 <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
77 <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
78
79 <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <EM>pair</EM><STRONG>);</STRONG>
80 <EM>/*</EM> <EM>extension</EM> <EM>*/</EM>
81 <STRONG>int</STRONG> <STRONG>extended_slk_color(int</STRONG> <EM>pair</EM><STRONG>);</STRONG>
82
83
84 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
85 These functions manipulate the soft function key labels that some
86 hardware terminals support. For those terminals that do not have soft
87 labels, <EM>curses</EM> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing its
88 vertical size and the value of <STRONG>LINES</STRONG> by one. By default, <EM>curses</EM> uses
89 eight labels of up to eight characters each.
90
91 <EM>ncurses</EM> furthermore supports a mode comprising twelve labels of up to
92 five characters each, following a convention associated with the IBM
93 PC/AT keyboard. <EM>ncurses</EM> simulates this mode by taking over up to two
94 lines at the bottom of the screen; it does not try to use any hardware
95 support for this mode.
96
97
98 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
99 <STRONG>slk_init</STRONG> must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. If <STRONG>initscr</STRONG>
100 eventually uses a line from <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM>
101 determines how the labels are arranged on the screen.
102
103 <STRONG>0</STRONG> indicates a 3-2-3 arrangement of the labels.
104
105 <STRONG>1</STRONG> indicates a 4-4 arrangement
106
107 <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode.
108
109 <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is
110 generated, helping the user to associate each label with its
111 numbered function key. <STRONG>LINES</STRONG> and the vertical size of <STRONG>stdscr</STRONG> are
112 further reduced.
113
114
115 </PRE><H3><a name="h3-Labels">Labels</a></H3><PRE>
116 Populate the labels with normal strings (<STRONG>slk_set</STRONG>) or wide-character
117 strings (<STRONG>slk_wset</STRONG>). Each function takes three parameters.
118
119 <EM>labnum</EM> is the label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 if <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or
120 <STRONG>3</STRONG>);
121
122 <EM>label</EM> is be the string to put on the label, up to eight (five if <EM>fmt</EM>
123 in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length. A empty string or
124 a null pointer sets up a blank label.
125
126 <EM>align</EM> is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, aligning <EM>label</EM> to the left, center, or right,
127 respectively, within the 8 (5) character cells housing it.
128
129 <STRONG>slk_label</STRONG> obtains the string assigned to label number <EM>labnum</EM>, with any
130 leading and trailing blanks stripped.
131
132
133 </PRE><H3><a name="h3-Screen-Updates">Screen Updates</a></H3><PRE>
134 <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> affect the soft key label lines as
135 <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> do the <EM>curses</EM> window.
136
137 The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen.
138
139 The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a
140 <STRONG>slk_clear</STRONG> has been performed.
141
142 The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next
143 time a <STRONG>slk_noutrefresh</STRONG> is performed.
144
145
146 </PRE><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><PRE>
147 The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines
148 correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively.
149 They have an effect only if soft labels are simulated on the bottom
150 line of the screen. The default highlight for soft key labels is
151 <STRONG>A_STANDOUT</STRONG> (as in System V <EM>curses</EM>, which does not document this fact).
152
153
154 </PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
155 The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only
156 if soft labels are simulated on the bottom line of the screen.
157
158 Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values,
159 this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM>
160 value of at least 32 bits.
161
162
163 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
164 Functions that return integers return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon
165 success.
166
167 In <EM>ncurses</EM>,
168
169 <STRONG>slk_attr</STRONG>
170 returns the attribute used for the soft keys.
171
172 <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>,
173 <STRONG>slk_touch</STRONG>
174 return <STRONG>ERR</STRONG> if the terminal or the softkeys were not
175 initialized.
176
177 <STRONG>slk_attrset</STRONG>
178 returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not
179 initialized.
180
181 <STRONG>slk_attr_set</STRONG>
182 returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not
183 initialized, or the color pair is outside the range
184 0..<STRONG>COLOR_PAIRS</STRONG>-1.
185
186 <STRONG>slk_color</STRONG>
187 returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not
188 initialized, or the color pair is outside the range
189 0..<STRONG>COLOR_PAIRS</STRONG>-1.
190
191 <STRONG>slk_init</STRONG>
192 returns <STRONG>ERR</STRONG> if the format parameter is outside the range 0..3.
193
194 <STRONG>slk_label</STRONG>
195 returns <EM>NULL</EM> on error.
196
197 <STRONG>slk_set</STRONG>
198 returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not
199 initialized, or the <EM>labnum</EM> parameter is outside the range of
200 label counts, or if the format parameter is outside the range
201 0..2, or if memory for the labels cannot be allocated.
202
203
204 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
205 Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is
206 likely to follow soon.
207
208
209 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
210 X/Open Curses documents the <EM>opts</EM> argument as reserved for future use,
211 saying that it must be a null pointer. The <EM>ncurses</EM> 6 ABI uses it for
212 the functions that accept a color pair parameter to support extended
213 color pairs.
214
215 For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is
216 set it is treated as a pointer to <EM>int</EM>, and used to set the color pair
217 instead of the <EM>short</EM> pair parameter.
218
219
220 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
221 X/Open Curses Issue 4 describes these functions. It specifies no error
222 conditions for them.
223
224 SVr4 describes a successful return value only as "an integer value
225 other than <EM>ERR</EM>".
226
227 <STRONG>o</STRONG> X/Open added functions like the SVr4 attribute-manipulation
228 functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use
229 <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> parameters (rather than <EM>chtype</EM>), along with a reserved <EM>opts</EM>
230 parameter.
231
232 Two of these new functions (unlike the SVr4 functions) have no
233 provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
234
235 The third function (<STRONG>slk_attr_set</STRONG>) has a color pair parameter.
236
237 <STRONG>o</STRONG> It added <EM>const</EM> qualifiers to parameters (unnecessarily), and
238
239 <STRONG>o</STRONG> It added <STRONG>slk_color</STRONG>.
240
241 Although <STRONG>slk_start</STRONG> is declared in the <EM>curses</EM> header file, it was not
242 documented by SVr4 other than its presence in a list of libtermlib.so.1
243 symbols. Reading the source code (i.e., Illumos):
244
245 <STRONG>o</STRONG> <STRONG>slk_start</STRONG> has two parameters:
246
247 <STRONG>o</STRONG> <EM>ng</EM> (number of groups) and
248
249 <STRONG>o</STRONG> <EM>gp</EM> (group pointer).
250
251 <STRONG>o</STRONG> Soft-key groups are an array of <EM>ng</EM> integers.
252
253 <STRONG>o</STRONG> In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>. For this
254 case, <STRONG>slk_start</STRONG> uses the number of groups <EM>ng</EM> (3 for the 3-2-3
255 layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided.
256
257 If <EM>ng</EM> is neither 2 or 3, <STRONG>slk_start</STRONG> checks the terminfo <STRONG>fln</STRONG>
258 (label_format) capability, interpreting that as a comma-separated
259 list of numbers, e.g., "3,2,3" for the 3-2-3 layout.
260
261 Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
262
263 <STRONG>o</STRONG> If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of
264 the group of soft-keys, up to 16.
265
266 If there are more than 16 elements, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
267
268 <STRONG>o</STRONG> The format codes <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> were added by <EM>ncurses</EM> in
269 1996. <EM>PDCurses</EM> 2.4 added this feature in 2001.
270
271 The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996.
272
273 X/Open Curses does not specify a limit for the number of colors and
274 color pairs which a terminal can support. However, in its use of <EM>short</EM>
275 for the parameters, it carries over SVr4's implementation detail for
276 the compiled terminfo database, which uses signed 16-bit numbers. This
277 implementation provides extended versions of those functions which use
278 <EM>int</EM> parameters, allowing applications to use larger color- and pair-
279 numbers.
280
281
282 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
283 SVr3 introduced these functions:
284 <STRONG>slk_clear</STRONG>
285 <STRONG>slk_init</STRONG>
286 <STRONG>slk_label</STRONG>
287 <STRONG>slk_noutrefresh</STRONG>
288 <STRONG>slk_refresh</STRONG>
289 <STRONG>slk_restore</STRONG>
290 <STRONG>slk_set</STRONG>
291 <STRONG>slk_touch</STRONG>
292
293 SVr4 added these functions:
294 <STRONG>slk_attroff</STRONG>
295 <STRONG>slk_attron</STRONG>
296 <STRONG>slk_attrset</STRONG>
297 <STRONG>slk_start</STRONG>
298
299 X/Open Curses added these:
300 <STRONG>slk_attr_off</STRONG>
301 <STRONG>slk_attr_on</STRONG>
302 <STRONG>slk_attr_set</STRONG>
303 <STRONG>slk_color</STRONG>
304 <STRONG>slk_wset</STRONG>
305
306
307 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
308 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>,
309 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
310
311 ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
312 </PRE>
313 <div class="nav">
314 <ul>
315 <li><a href="#h2-NAME">NAME</a></li>
316 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
317 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
318 <ul>
319 <li><a href="#h3-Initialization">Initialization</a></li>
320 <li><a href="#h3-Labels">Labels</a></li>
321 <li><a href="#h3-Screen-Updates">Screen Updates</a></li>
322 <li><a href="#h3-Video-Attributes">Video Attributes</a></li>
323 <li><a href="#h3-Colors">Colors</a></li>
324 </ul>
325 </li>
326 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
327 <li><a href="#h2-NOTES">NOTES</a></li>
328 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
329 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
330 <li><a href="#h2-HISTORY">HISTORY</a></li>
331 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
332 </ul>
333 </div>
334 </BODY>
335 </HTML>