1<!-- 2 **************************************************************************** 3 * Copyright 2018-2023,2024 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.71 2024/04/20 18:54:36 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 2024-04-20 ncurses 6.5 Library calls</TITLE> 38<link rel="author" href="mailto:bug-ncurses@gnu.org"> 39 40</HEAD> 41<BODY> 42<H1 class="no-header">curs_slk 3x 2024-04-20 ncurses 6.5 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 48 49</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> 50 <STRONG>slk_init</STRONG>, <STRONG>slk_set</STRONG>, <STRONG>slk_wset</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_label</STRONG>, 51 <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, 52 <STRONG>slk_attroff</STRONG>, <STRONG>slk_attr_on</STRONG>, <STRONG>slk_attr_set</STRONG>, <STRONG>slk_attr_off</STRONG>, <STRONG>slk_attr</STRONG>, 53 <STRONG>slk_color</STRONG>, <STRONG>extended_slk_color</STRONG> - <EM>curses</EM> soft label key routines 54 55 56</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> 57 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> 58 59 <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <EM>fmt</EM><STRONG>);</STRONG> 60 61 <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> 62 <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> 63 64 <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <EM>labnum</EM><STRONG>);</STRONG> 65 66 <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG> 67 <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG> 68 <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG> 69 <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG> 70 <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG> 71 72 <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> 73 <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> 74 <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> 75 <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> 76 <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> 77 <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> 78 <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> 79 <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG> 80 81 <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <EM>pair</EM><STRONG>);</STRONG> 82 <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> 83 <STRONG>int</STRONG> <STRONG>extended_slk_color(int</STRONG> <EM>pair</EM><STRONG>);</STRONG> 84 85 86</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> 87 These functions manipulate the soft function key labels that some 88 hardware terminals support. For those terminals that do not have soft 89 labels, <EM>curses</EM> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing its 90 vertical size and the value of <STRONG>LINES</STRONG> by one. By default, <EM>curses</EM> uses 91 eight labels of up to eight characters each. 92 93 <EM>ncurses</EM> furthermore supports a mode comprising twelve labels of up to 94 five characters each, following a convention associated with the IBM 95 PC/AT keyboard. <EM>ncurses</EM> simulates this mode by taking over up to two 96 lines at the bottom of the screen; it does not try to use any hardware 97 support for this mode. 98 99 100</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> 101 <STRONG>slk_init</STRONG> must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. If <STRONG>initscr</STRONG> 102 eventually uses a line from <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM> 103 determines how the labels are arranged on the screen. 104 105 <STRONG>0</STRONG> indicates a 3-2-3 arrangement of the labels. 106 107 <STRONG>1</STRONG> indicates a 4-4 arrangement 108 109 <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode. 110 111 <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is 112 generated, helping the user to associate each label with its 113 numbered function key. <STRONG>LINES</STRONG> and the vertical size of <STRONG>stdscr</STRONG> are 114 further reduced. 115 116 117</PRE><H3><a name="h3-Labels">Labels</a></H3><PRE> 118 Populate the labels with normal strings (<STRONG>slk_set</STRONG>) or wide-character 119 strings (<STRONG>slk_wset</STRONG>). Each function takes three parameters. 120 121 <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 122 <STRONG>3</STRONG>); 123 124 <EM>label</EM> is be the string to put on the label, up to eight (five if <EM>fmt</EM> 125 in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length. A empty string or 126 a null pointer sets up a blank label. 127 128 <EM>align</EM> is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, aligning <EM>label</EM> to the left, center, or right, 129 respectively, within the 8 (5) character cells housing it. 130 131 <STRONG>slk_label</STRONG> obtains the string assigned to label number <EM>labnum</EM>, with any 132 leading and trailing blanks stripped. 133 134 135</PRE><H3><a name="h3-Screen-Updates">Screen Updates</a></H3><PRE> 136 <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> affect the soft key label lines as 137 <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> do the <EM>curses</EM> window. 138 139 The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen. 140 141 The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a 142 <STRONG>slk_clear</STRONG> has been performed. 143 144 The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next 145 time a <STRONG>slk_noutrefresh</STRONG> is performed. 146 147 148</PRE><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><PRE> 149 The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines 150 correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively. 151 They have an effect only if soft labels are simulated on the bottom 152 line of the screen. The default highlight for soft key labels is 153 <STRONG>A_STANDOUT</STRONG> (as in System V <EM>curses</EM>, which does not document this fact). 154 155 156</PRE><H3><a name="h3-Colors">Colors</a></H3><PRE> 157 The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only 158 if soft labels are simulated on the bottom line of the screen. 159 160 Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values, 161 this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM> 162 value of at least 32 bits. 163 164 165</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> 166 Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 167 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful 168 completion. 169 170 X/Open Curses defines no error conditions. 171 172 In this implementation 173 174 <STRONG>slk_attr</STRONG> 175 returns the attribute used for the soft keys. 176 177 <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>, 178 <STRONG>slk_touch</STRONG> 179 return an error if the terminal or the softkeys were not 180 initialized. 181 182 <STRONG>slk_attrset</STRONG> 183 returns an error if the terminal or the softkeys were not 184 initialized. 185 186 <STRONG>slk_attr_set</STRONG> 187 returns an error 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_color</STRONG> 192 returns an error if the terminal or the softkeys were not 193 initialized, or the color pair is outside the range 194 0..<STRONG>COLOR_PAIRS</STRONG>-1. 195 196 <STRONG>slk_init</STRONG> 197 returns an error if the format parameter is outside the range 198 0..3. 199 200 <STRONG>slk_label</STRONG> 201 returns <STRONG>NULL</STRONG> on error. 202 203 <STRONG>slk_set</STRONG> 204 returns an error if the terminal or the softkeys were not 205 initialized, or the <EM>labnum</EM> parameter is outside the range of 206 label counts, or if the format parameter is outside the range 207 0..2, or if memory for the labels cannot be allocated. 208 209 210</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> 211 Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is 212 likely to follow soon. 213 214 215</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> 216 X/Open Curses documents the <EM>opts</EM> argument as reserved for future use, 217 saying that it must be null. This implementation uses that parameter 218 in ABI 6 for the functions which have a color pair parameter to support 219 extended color pairs. 220 221 For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is 222 set it is treated as a pointer to <EM>int</EM>, and used to set the color pair 223 instead of the <EM>short</EM> pair parameter. 224 225 226</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> 227 X/Open Curses, Issue 4 describes these functions, with some differences 228 from SVr4 <EM>curses</EM>: 229 230 <STRONG>o</STRONG> X/Open added functions like the SVr4 attribute-manipulation 231 functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use 232 <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> parameters (rather than <EM>chtype</EM>), along with a reserved <EM>opts</EM> 233 parameter. 234 235 Two of these new functions (unlike the SVr4 functions) have no 236 provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>. 237 238 The third function (<STRONG>slk_attr_set</STRONG>) has a color pair parameter. 239 240 <STRONG>o</STRONG> It added <EM>const</EM> qualifiers to parameters (unnecessarily), and 241 242 <STRONG>o</STRONG> It added <STRONG>slk_color</STRONG>. 243 244 Although <STRONG>slk_start</STRONG> is declared in the <EM>curses</EM> header file, it was not 245 documented by SVr4 other than its presence in a list of libtermlib.so.1 246 symbols. Reading the source code (i.e., Illumos): 247 248 <STRONG>o</STRONG> <STRONG>slk_start</STRONG> has two parameters: 249 250 <STRONG>o</STRONG> <EM>ng</EM> (number of groups) and 251 252 <STRONG>o</STRONG> <EM>gp</EM> (group pointer). 253 254 <STRONG>o</STRONG> Soft-key groups are an array of <EM>ng</EM> integers. 255 256 <STRONG>o</STRONG> In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>. For this 257 case, <STRONG>slk_start</STRONG> uses the number of groups <EM>ng</EM> (3 for the 3-2-3 258 layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided. 259 260 If <EM>ng</EM> is neither 2 or 3, <STRONG>slk_start</STRONG> checks the terminfo <STRONG>fln</STRONG> 261 (label_format) capability, interpreting that as a comma-separated 262 list of numbers, e.g., "3,2,3" for the 3-2-3 layout. 263 264 Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>. 265 266 <STRONG>o</STRONG> If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of 267 the group of soft-keys, up to 16. 268 269 If there are more than 16 elements, <STRONG>slk_start</STRONG> returns an error. 270 271 <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 272 1996. PDCurses 2.4 added this feature in 2001. 273 274 The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996. 275 276 X/Open Curses does not specify a limit for the number of colors and 277 color pairs which a terminal can support. However, in its use of <EM>short</EM> 278 for the parameters, it carries over SVr4's implementation detail for 279 the compiled terminfo database, which uses signed 16-bit numbers. This 280 implementation provides extended versions of those functions which use 281 <EM>int</EM> parameters, allowing applications to use larger color- and pair- 282 numbers. 283 284 285</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> 286 SVr3 introduced these functions: 287 <STRONG>slk_clear</STRONG> 288 <STRONG>slk_init</STRONG> 289 <STRONG>slk_label</STRONG> 290 <STRONG>slk_noutrefresh</STRONG> 291 <STRONG>slk_refresh</STRONG> 292 <STRONG>slk_restore</STRONG> 293 <STRONG>slk_set</STRONG> 294 <STRONG>slk_touch</STRONG> 295 296 SVr4 added these functions: 297 <STRONG>slk_attroff</STRONG> 298 <STRONG>slk_attron</STRONG> 299 <STRONG>slk_attrset</STRONG> 300 <STRONG>slk_start</STRONG> 301 302 X/Open Curses added these: 303 <STRONG>slk_attr_off</STRONG> 304 <STRONG>slk_attr_on</STRONG> 305 <STRONG>slk_attr_set</STRONG> 306 <STRONG>slk_color</STRONG> 307 <STRONG>slk_wset</STRONG> 308 309 310</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> 311 <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>, 312 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> 313 314 315 316ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> 317</PRE> 318<div class="nav"> 319<ul> 320<li><a href="#h2-NAME">NAME</a></li> 321<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> 322<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> 323<ul> 324<li><a href="#h3-Initialization">Initialization</a></li> 325<li><a href="#h3-Labels">Labels</a></li> 326<li><a href="#h3-Screen-Updates">Screen Updates</a></li> 327<li><a href="#h3-Video-Attributes">Video Attributes</a></li> 328<li><a href="#h3-Colors">Colors</a></li> 329</ul> 330</li> 331<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> 332<li><a href="#h2-NOTES">NOTES</a></li> 333<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> 334<li><a href="#h2-PORTABILITY">PORTABILITY</a></li> 335<li><a href="#h2-HISTORY">HISTORY</a></li> 336<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> 337</ul> 338</div> 339</BODY> 340</HTML> 341