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

   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.73 2024/05/25 20:10:58 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-05-25 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-05-25 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>&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>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  <STRONG>ERR</STRONG>  if  the  terminal  or  the   softkeys   were   not
 180                initialized.
 181
 182           <STRONG>slk_attrset</STRONG>
 183                returns   <STRONG>ERR</STRONG>   if  the  terminal  or  the  softkeys  were  not
 184                initialized.
 185
 186           <STRONG>slk_attr_set</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_color</STRONG>
 192                returns  <STRONG>ERR</STRONG>  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 <STRONG>ERR</STRONG> if the format parameter is outside the range 0..3.
 198
 199           <STRONG>slk_label</STRONG>
 200                returns <STRONG>NULL</STRONG> on error.
 201
 202           <STRONG>slk_set</STRONG>
 203                returns  <STRONG>ERR</STRONG>  if  the  terminal  or  the  softkeys   were   not
 204                initialized,  or  the  <EM>labnum</EM> parameter is outside the range of
 205                label counts, or if the format parameter is outside  the  range
 206                0..2, or if memory for the labels cannot be allocated.
 207
 208
 209 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 210        Most  applications  would  use  <STRONG>slk_noutrefresh</STRONG>  because  a <STRONG>wrefresh</STRONG> is
 211        likely to follow soon.
 212
 213
 214 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 215        X/Open Curses documents the <EM>opts</EM> argument as reserved for  future  use,
 216        saying  that  it must be null.  This implementation uses that parameter
 217        in ABI 6 for the functions which have a color pair parameter to support
 218        extended color pairs.
 219
 220        For  functions  which  modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is
 221        set it is treated as a pointer to <EM>int</EM>, and used to set the  color  pair
 222        instead of the <EM>short</EM> pair parameter.
 223
 224
 225 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 226        X/Open Curses, Issue 4 describes these functions, with some differences
 227        from SVr4 <EM>curses</EM>:
 228
 229        <STRONG>o</STRONG>   X/Open  added  functions  like  the   SVr4   attribute-manipulation
 230            functions  <STRONG>slk_attron</STRONG>,  <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use
 231            <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> parameters (rather than <EM>chtype</EM>), along with a reserved  <EM>opts</EM>
 232            parameter.
 233
 234            Two  of  these  new  functions  (unlike the SVr4 functions) have no
 235            provision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
 236
 237            The third function (<STRONG>slk_attr_set</STRONG>) has a color pair parameter.
 238
 239        <STRONG>o</STRONG>   It added <EM>const</EM> qualifiers to parameters (unnecessarily), and
 240
 241        <STRONG>o</STRONG>   It added <STRONG>slk_color</STRONG>.
 242
 243        Although <STRONG>slk_start</STRONG> is declared in the <EM>curses</EM> header file,  it  was  not
 244        documented by SVr4 other than its presence in a list of libtermlib.so.1
 245        symbols.  Reading the source code (i.e., Illumos):
 246
 247        <STRONG>o</STRONG>   <STRONG>slk_start</STRONG> has two parameters:
 248
 249            <STRONG>o</STRONG>   <EM>ng</EM> (number of groups) and
 250
 251            <STRONG>o</STRONG>   <EM>gp</EM> (group pointer).
 252
 253        <STRONG>o</STRONG>   Soft-key groups are an array of <EM>ng</EM> integers.
 254
 255        <STRONG>o</STRONG>   In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>.  For  this
 256            case,  <STRONG>slk_start</STRONG>  uses  the  number  of  groups <EM>ng</EM> (3 for the 3-2-3
 257            layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided.
 258
 259            If <EM>ng</EM> is  neither  2  or  3,  <STRONG>slk_start</STRONG>  checks  the  terminfo  <STRONG>fln</STRONG>
 260            (label_format)  capability,  interpreting that as a comma-separated
 261            list of numbers, e.g., "3,2,3" for the 3-2-3 layout.
 262
 263            Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
 264
 265        <STRONG>o</STRONG>   If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM>  elements  of
 266            the group of soft-keys, up to 16.
 267
 268            If there are more than 16 elements, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>.
 269
 270        <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
 271            1996.  PDCurses 2.4 added this feature in 2001.
 272
 273        The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996.
 274
 275        X/Open Curses does not specify a limit for the  number  of  colors  and
 276        color pairs which a terminal can support.  However, in its use of <EM>short</EM>
 277        for the parameters, it carries over SVr4's  implementation  detail  for
 278        the compiled terminfo database, which uses signed 16-bit numbers.  This
 279        implementation provides extended versions of those functions which  use
 280        <EM>int</EM>  parameters,  allowing  applications to use larger color- and pair-
 281        numbers.
 282
 283
 284 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 285        SVr3 introduced these functions:
 286          <STRONG>slk_clear</STRONG>
 287          <STRONG>slk_init</STRONG>
 288          <STRONG>slk_label</STRONG>
 289          <STRONG>slk_noutrefresh</STRONG>
 290          <STRONG>slk_refresh</STRONG>
 291          <STRONG>slk_restore</STRONG>
 292          <STRONG>slk_set</STRONG>
 293          <STRONG>slk_touch</STRONG>
 294
 295        SVr4 added these functions:
 296          <STRONG>slk_attroff</STRONG>
 297          <STRONG>slk_attron</STRONG>
 298          <STRONG>slk_attrset</STRONG>
 299          <STRONG>slk_start</STRONG>
 300
 301        X/Open Curses added these:
 302          <STRONG>slk_attr_off</STRONG>
 303          <STRONG>slk_attr_on</STRONG>
 304          <STRONG>slk_attr_set</STRONG>
 305          <STRONG>slk_color</STRONG>
 306          <STRONG>slk_wset</STRONG>
 307
 308
 309 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 310        <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>,
 311        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>
 312
 313
 314
 315 ncurses 6.5                       2024-05-25                      <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 316 </PRE>
 317 <div class="nav">
 318 <ul>
 319 <li><a href="#h2-NAME">NAME</a></li>
 320 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 321 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 322 <ul>
 323 <li><a href="#h3-Initialization">Initialization</a></li>
 324 <li><a href="#h3-Labels">Labels</a></li>
 325 <li><a href="#h3-Screen-Updates">Screen Updates</a></li>
 326 <li><a href="#h3-Video-Attributes">Video Attributes</a></li>
 327 <li><a href="#h3-Colors">Colors</a></li>
 328 </ul>
 329 </li>
 330 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 331 <li><a href="#h2-NOTES">NOTES</a></li>
 332 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 333 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 334 <li><a href="#h2-HISTORY">HISTORY</a></li>
 335 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 336 </ul>
 337 </div>
 338 </BODY>
 339 </HTML>