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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 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.66 2023/11/25 14:31:07 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 2023-11-25 ncurses 6.4 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 2023-11-25 ncurses 6.4 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>&lt;curses.h&gt;</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>fmt</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>fmt</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> <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        The <STRONG>slk</STRONG>* functions manipulate the set of soft function-key labels  that
  88        exist  on  many  terminals.   For those terminals that do not have soft
  89        labels, <EM>curses</EM> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing the  size
  90        of  <STRONG>stdscr</STRONG> and the variable <STRONG>LINES</STRONG>.  <EM>curses</EM> standardizes on eight labels
  91        of up to eight characters each.   In  addition  to  this,  the  <EM>ncurses</EM>
  92        implementation  supports  a  mode where it simulates 12 labels of up to
  93        five characters each.  This is  useful  for  PC-like  enduser  devices.
  94        <EM>ncurses</EM>  simulates  this  mode  by  taking  over up to two lines at the
  95        bottom of the screen; it does not try to use any hardware  support  for
  96        this mode.
  97
  98
  99 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
 100        The  <STRONG>slk_init</STRONG>  routine  must  be  called  before  <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is
 101        called.  If <STRONG>initscr</STRONG> eventually uses a line from <STRONG>stdscr</STRONG> to  emulate  the
 102        soft  labels,  then  <EM>fmt</EM>  determines how the labels are arranged on the
 103        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 identify the key numbers easily.
 113
 114
 115 </PRE><H3><a name="h3-Labels">Labels</a></H3><PRE>
 116        The  <STRONG>slk_set</STRONG>  routine  (and the <STRONG>slk_wset</STRONG> routine for the wide-character
 117        library) has three parameters:
 118
 119           <EM>labnum</EM>
 120                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
 121                <STRONG>3</STRONG>);
 122
 123           <EM>label</EM>
 124                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 null string  or
 126                a null pointer sets up a blank label.
 127
 128           <EM>fmt</EM>  is  either  <STRONG>0</STRONG>,  <STRONG>1</STRONG>,  or <STRONG>2</STRONG>, indicating whether the label is to be
 129                left-justified,  centered,  or  right-justified,  respectively,
 130                within the label.
 131
 132        The  <STRONG>slk_label</STRONG>  routine  returns  the  current  label  for label number
 133        <EM>labnum</EM>, with leading and trailing blanks stripped.
 134
 135
 136 </PRE><H3><a name="h3-Screen-updates">Screen updates</a></H3><PRE>
 137        The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to the <STRONG>wrefresh</STRONG>
 138        and <STRONG>wnoutrefresh</STRONG> routines.
 139
 140        The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen.
 141
 142        The  <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a
 143        <STRONG>slk_clear</STRONG> has been performed.
 144
 145        The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the  next
 146        time a <STRONG>slk_noutrefresh</STRONG> is performed.
 147
 148
 149 </PRE><H3><a name="h3-Video-attributes">Video attributes</a></H3><PRE>
 150        The   <STRONG>slk_attron</STRONG>,   <STRONG>slk_attrset</STRONG>,   <STRONG>slk_attroff</STRONG>  and  <STRONG>slk_attr</STRONG>  routines
 151        correspond to <STRONG>attron</STRONG>,  <STRONG>attrset</STRONG>,  <STRONG>attroff</STRONG>  and  <STRONG>attr_get</STRONG>,  respectively.
 152        They  have  an  effect  only if soft labels are simulated on the bottom
 153        line of the screen.  The default highlight for soft keys is  A_STANDOUT
 154        (as in System V <EM>curses</EM>, which does not document this fact).
 155
 156
 157 </PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
 158        The  <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>.  It has an effect only
 159        if soft labels are simulated on the bottom line of the screen.
 160
 161        Because <STRONG>slk_color</STRONG> accepts only <STRONG>short</STRONG> (signed  16-bit  integer)  values,
 162        this   implementation  provides  <STRONG>extended_slk_color</STRONG>  which  accepts  an
 163        integer value, e.g., 32-bits.
 164
 165
 166 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 167        These routines return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only  "an
 168        integer value other than <STRONG>ERR</STRONG>") upon successful completion.
 169
 170        X/Open defines no error conditions.  In this implementation
 171
 172           <STRONG>slk_attr</STRONG>
 173                returns the attribute used for the soft keys.
 174
 175           <STRONG>slk_attroff</STRONG>,  <STRONG>slk_attron</STRONG>,  <STRONG>slk_clear</STRONG>,  <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>,
 176           <STRONG>slk_touch</STRONG>
 177                return an error if  the  terminal  or  the  softkeys  were  not
 178                initialized.
 179
 180           <STRONG>slk_attrset</STRONG>
 181                returns  an  error  if  the  terminal  or the softkeys were not
 182                initialized.
 183
 184           <STRONG>slk_attr_set</STRONG>
 185                returns an error if the  terminal  or  the  softkeys  were  not
 186                initialized,   or   the   color   pair  is  outside  the  range
 187                0..<STRONG>COLOR_PAIRS</STRONG>-1.
 188
 189           <STRONG>slk_color</STRONG>
 190                returns an error if the  terminal  or  the  softkeys  were  not
 191                initialized,   or   the   color   pair  is  outside  the  range
 192                0..<STRONG>COLOR_PAIRS</STRONG>-1.
 193
 194           <STRONG>slk_init</STRONG>
 195                returns an error if the format parameter is outside  the  range
 196                0..3.
 197
 198           <STRONG>slk_label</STRONG>
 199                returns <STRONG>NULL</STRONG> on error.
 200
 201           <STRONG>slk_set</STRONG>
 202                returns  an  error  if  the  terminal  or the softkeys were not
 203                initialized, or the <EM>labnum</EM> parameter is outside  the  range  of
 204                label  counts,  or if the format parameter is outside the range
 205                0..2, or if memory for the labels cannot be allocated.
 206
 207
 208 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 209        Most applications would  use  <STRONG>slk_noutrefresh</STRONG>  because  a  <STRONG>wrefresh</STRONG>  is
 210        likely to follow soon.
 211
 212
 213 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 214        X/Open  <EM>curses</EM>  documents the <EM>opts</EM> argument as reserved for future use,
 215        saying that it must be null.  This implementation uses  that  parameter
 216        in ABI 6 for the functions which have a color-pair parameter to support
 217        extended color pairs.
 218
 219        For  functions  which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM>  is
 220        set  it  is  treated  as a pointer to <STRONG>int</STRONG>, and used to  set  the  color
 221        pair instead of the <STRONG>short</STRONG> pair parameter.
 222
 223
 224 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 225        The XSI <EM>curses</EM> standard, Issue 4,  described  the  soft-key  functions,
 226        with some differences from SVr4 <EM>curses</EM>:
 227
 228        <STRONG>o</STRONG>   It  added  functions like the SVr4 attribute-manipulation functions
 229            <STRONG>slk_attron</STRONG>,  <STRONG>slk_attroff</STRONG>,  <STRONG>slk_attrset</STRONG>,  but   which   use   <STRONG>attr_t</STRONG>
 230            parameters  (rather  than  <STRONG>chtype</STRONG>),  along  with  a  reserved  <EM>opts</EM>
 231            parameter.
 232
 233            Two of these new functions (unlike  the  SVr4  functions)  have  no
 234            provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
 235
 236            The third function (<STRONG>slk_attr_set</STRONG>) has a color-pair parameter.
 237
 238        <STRONG>o</STRONG>   It added <STRONG>const</STRONG> qualifiers to parameters (unnecessarily), and
 239
 240        <STRONG>o</STRONG>   It added <STRONG>slk_color</STRONG>.
 241
 242        Although  <STRONG>slk_start</STRONG>  is  declared in the <EM>curses</EM> header file, it was not
 243        documented by SVr4 other than its presence in a list of libtermlib.so.1
 244        symbols.  Reading the source code (i.e., Illumos):
 245
 246        <STRONG>o</STRONG>   <STRONG>slk_start</STRONG> has two parameters:
 247
 248            <STRONG>o</STRONG>   <EM>ng</EM> (number of groups) and
 249
 250            <STRONG>o</STRONG>   <EM>gp</EM> (group pointer).
 251
 252        <STRONG>o</STRONG>   Soft-key groups are an array of <EM>ng</EM> integers.
 253
 254        <STRONG>o</STRONG>   In  SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>.  For this
 255            case, <STRONG>slk_start</STRONG> uses the number of  groups  <EM>ng</EM>  (3  for  the  3-2-3
 256            layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided.
 257
 258            If  <EM>ng</EM>  is  neither  2  or  3,  <STRONG>slk_start</STRONG>  checks  the terminfo <STRONG>fln</STRONG>
 259            (label_format) capability, interpreting that as  a  comma-separated
 260            list of numbers, e.g., "3,2,3" for the 3-2-3 layout.
 261
 262            Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
 263
 264        <STRONG>o</STRONG>   If  <STRONG>slk_start</STRONG>  is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of
 265            the group of soft-keys, up to 16.
 266
 267            If there are more than 16 elements, <STRONG>slk_start</STRONG> returns an error.
 268
 269        <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
 270            1996.  PDCurses 2.4 added this feature in 2001.
 271
 272        The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996.
 273
 274        X/Open  <EM>curses</EM>  does  not  specify a limit for the number of colors and
 275        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 276        for  the  parameters,  it carries over SVr4's implementation detail for
 277        the compiled terminfo database, which uses signed 16-bit numbers.  This
 278        implementation  provides extended versions of those functions which use
 279        <STRONG>int</STRONG> parameters, allowing applications to use larger  color-  and  pair-
 280        numbers.
 281
 282
 283 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 284        SVr3 introduced these functions:
 285          <STRONG>slk_clear</STRONG>
 286          <STRONG>slk_init</STRONG>
 287          <STRONG>slk_label</STRONG>
 288          <STRONG>slk_noutrefresh</STRONG>
 289          <STRONG>slk_refresh</STRONG>
 290          <STRONG>slk_restore</STRONG>
 291          <STRONG>slk_set</STRONG>
 292          <STRONG>slk_touch</STRONG>
 293
 294        SVr4 added these functions:
 295          <STRONG>slk_attroff</STRONG>
 296          <STRONG>slk_attron</STRONG>
 297          <STRONG>slk_attrset</STRONG>
 298          <STRONG>slk_start</STRONG>
 299
 300        X/Open <EM>curses</EM> added these:
 301          <STRONG>slk_attr_off</STRONG>
 302          <STRONG>slk_attr_on</STRONG>
 303          <STRONG>slk_attr_set</STRONG>
 304          <STRONG>slk_color</STRONG>
 305          <STRONG>slk_wset</STRONG>
 306
 307
 308 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 309        <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>,
 310        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 311
 312
 313
 314 ncurses 6.4                       2023-11-25                      <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 315 </PRE>
 316 <div class="nav">
 317 <ul>
 318 <li><a href="#h2-NAME">NAME</a></li>
 319 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 320 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 321 <ul>
 322 <li><a href="#h3-Initialization">Initialization</a></li>
 323 <li><a href="#h3-Labels">Labels</a></li>
 324 <li><a href="#h3-Screen-updates">Screen updates</a></li>
 325 <li><a href="#h3-Video-attributes">Video attributes</a></li>
 326 <li><a href="#h3-Colors">Colors</a></li>
 327 </ul>
 328 </li>
 329 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 330 <li><a href="#h2-NOTES">NOTES</a></li>
 331 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 332 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 333 <li><a href="#h2-HISTORY">HISTORY</a></li>
 334 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 335 </ul>
 336 </div>
 337 </BODY>
 338 </HTML>