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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018,2020 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.36 2020/02/02 23:34:34 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</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_slk 3x</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>                                                      <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> - <STRONG>curses</STRONG> soft label 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
  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        /* extension */
  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 slk* functions manipulate the set of soft function-key labels  that
  88        exist on many terminals.  For those terminals that do not have soft la-
  89        bels, <STRONG>curses</STRONG> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing the size of
  90        <STRONG>stdscr</STRONG>  and the variable <STRONG>LINES</STRONG>.  <STRONG>curses</STRONG> standardizes on eight labels of
  91        up to eight characters each.  In addition to this, the  ncurses  imple-
  92        mentation  supports  a  mode where it simulates 12 labels of up to five
  93        characters each.  This is useful for PC-like enduser devices.   ncurses
  94        simulates this mode by taking over up to two lines at the bottom of the
  95        screen; it does not try to use any hardware support for this mode.
  96
  97
  98 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
  99        The <STRONG>slk_init</STRONG> routine must  be  called  before  <STRONG>initscr</STRONG>  or  <STRONG>newterm</STRONG>  is
 100        called.   If  <STRONG>initscr</STRONG> eventually uses a line from <STRONG>stdscr</STRONG> to emulate the
 101        soft labels, then <EM>fmt</EM> determines how the labels  are  arranged  on  the
 102        screen:
 103
 104           <STRONG>0</STRONG>  indicates a 3-2-3 arrangement of the labels.
 105
 106           <STRONG>1</STRONG>  indicates a 4-4 arrangement
 107
 108           <STRONG>2</STRONG>  indicates the PC-like 4-4-4 mode.
 109
 110           <STRONG>3</STRONG>  is again the PC-like 4-4-4 mode, but in addition an index line is
 111              generated, helping the user to identify the key numbers easily.
 112
 113
 114 </PRE><H3><a name="h3-Labels">Labels</a></H3><PRE>
 115        The <STRONG>slk_set</STRONG> routine (and the <STRONG>slk_wset</STRONG> routine  for  the  wide-character
 116        library) has three parameters:
 117
 118           <EM>labnum</EM>
 119                is  the  label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 for <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG>
 120                or <STRONG>3</STRONG>);
 121
 122           <EM>label</EM>
 123                is be the string to put on the label, up to eight (five for <EM>fmt</EM>
 124                in  <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length.  A null string or
 125                a null pointer sets up a blank label.
 126
 127           <EM>fmt</EM>  is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the  label  is  to  be
 128                left-justified,  centered,  or  right-justified,  respectively,
 129                within the label.
 130
 131        The <STRONG>slk_label</STRONG> routine returns the current label for label  number  <EM>lab-</EM>
 132        <EM>num</EM>, with leading and trailing blanks stripped.
 133
 134
 135 </PRE><H3><a name="h3-Screen-updates">Screen updates</a></H3><PRE>
 136        The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to the <STRONG>wrefresh</STRONG>
 137        and <STRONG>wnoutrefresh</STRONG> routines.
 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  corre-
 150        spond  to  <STRONG>attron</STRONG>,  <STRONG>attrset</STRONG>,  <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>, respectively.  They
 151        have an effect only if soft labels are simulated on the bottom line  of
 152        the  screen.   The default highlight for soft keys is A_STANDOUT (as in
 153        System V curses, 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 <STRONG>short</STRONG> (signed 16-bit integer) values,
 161        this implementation provides <STRONG>extended_slk_color</STRONG> which accepts an  inte-
 162        ger value, e.g., 32-bits.
 163
 164
 165 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 166        These  routines return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only "an
 167        integer value other than <STRONG>ERR</STRONG>") upon successful completion.
 168
 169        X/Open defines no error conditions.  In this implementation
 170
 171           <STRONG>slk_attr</STRONG>
 172                returns the attribute used for the soft keys.
 173
 174           <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>,
 175           <STRONG>slk_touch</STRONG>
 176                return  an  error if the terminal or the softkeys were not ini-
 177                tialized.
 178
 179           <STRONG>slk_attrset</STRONG>
 180                returns an error if the terminal or the softkeys were not  ini-
 181                tialized.
 182
 183           <STRONG>slk_attr_set</STRONG>
 184                returns  an error if the terminal or the softkeys were not ini-
 185                tialized, or the  color  pair  is  outside  the  range  0..COL-
 186                OR_PAIRS-1.
 187
 188           <STRONG>slk_color</STRONG>
 189                returns  an error if the terminal or the softkeys were not ini-
 190                tialized, or the  color  pair  is  outside  the  range  0..COL-
 191                OR_PAIRS-1.
 192
 193           <STRONG>slk_init</STRONG>
 194                returns  an  error if the format parameter is outside the range
 195                0..3.
 196
 197           <STRONG>slk_label</STRONG>
 198                returns <STRONG>NULL</STRONG> on error.
 199
 200           <STRONG>slk_set</STRONG>
 201                returns an error if the terminal or the softkeys were not  ini-
 202                tialized, or the <EM>labnum</EM> parameter is outside the range of label
 203                counts, or if the format parameter is outside the  range  0..2,
 204                or if memory for the labels cannot be allocated.
 205
 206
 207 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 208        SVr3 introduced these functions:
 209          slk_clear
 210          slk_init
 211          slk_label
 212          slk_noutrefresh
 213          slk_refresh
 214          slk_restore
 215          slk_set
 216          slk_touch
 217
 218        SVr4 added these functions:
 219          slk_attroff
 220          slk_attron
 221          slk_attrset
 222          slk_start
 223
 224        X/Open Curses added these:
 225          slk_attr_off
 226          slk_attr_on
 227          slk_attr_set
 228          slk_color
 229          slk_wset
 230
 231
 232 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 233        X/Open  Curses  documents the <EM>opts</EM> argument as reserved for future use,
 234        saying that it must be null.  This implementation uses  that  parameter
 235        in ABI 6 for the functions which have a color-pair parameter to support
 236        extended color pairs.
 237
 238        For  functions  which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM>  is
 239        set  it  is  treated  as a pointer to <STRONG>int</STRONG>, and used to  set  the  color
 240        pair instead of the <STRONG>short</STRONG> pair parameter.
 241
 242
 243 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 244        Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is like-
 245        ly to follow soon.
 246
 247
 248 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 249        The  XSI  Curses  standard,  Issue 4, described the soft-key functions,
 250        with some differences from SVr4 curses:
 251
 252        <STRONG>o</STRONG>   It added functions like the SVr4  attribute-manipulation  functions
 253            <STRONG>slk_attron</STRONG>,  <STRONG>slk_attroff</STRONG>, <STRONG>slk_attrset</STRONG>, but which use <STRONG>attr_t</STRONG> parame-
 254            ters (rather than <STRONG>chtype</STRONG>), along with a reserved <EM>opts</EM> parameter.
 255
 256            Two of these new functions (unlike the SVr4 functions) have no pro-
 257            vision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
 258
 259            The third function (<STRONG>slk_attr_set</STRONG>) has a color-pair parameter.
 260
 261        <STRONG>o</STRONG>   It added <STRONG>const</STRONG> qualifiers to parameters (unnecessarily), and
 262
 263        <STRONG>o</STRONG>   It added <STRONG>slk_color</STRONG>.
 264
 265        The  format  codes  <STRONG>2</STRONG>  and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> and the function <STRONG>slk_attr</STRONG> are
 266        specific to ncurses.
 267
 268        X/Open Curses does not specify a limit for the  number  of  colors  and
 269        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 270        for the parameters, it carries over SVr4's  implementation  detail  for
 271        the compiled terminfo database, which uses signed 16-bit numbers.  This
 272        implementation provides extended versions of those functions which  use
 273        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
 274        numbers.
 275
 276
 277 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 278        <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>,
 279        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 280
 281
 282
 283                                                                   <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 284 </PRE>
 285 <div class="nav">
 286 <ul>
 287 <li><a href="#h2-NAME">NAME</a></li>
 288 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 289 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 290 <ul>
 291 <li><a href="#h3-Initialization">Initialization</a></li>
 292 <li><a href="#h3-Labels">Labels</a></li>
 293 <li><a href="#h3-Screen-updates">Screen updates</a></li>
 294 <li><a href="#h3-Video-attributes">Video attributes</a></li>
 295 <li><a href="#h3-Colors">Colors</a></li>
 296 </ul>
 297 </li>
 298 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 299 <li><a href="#h2-HISTORY">HISTORY</a></li>
 300 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 301 <li><a href="#h2-NOTES">NOTES</a></li>
 302 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 303 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 304 </ul>
 305 </div>
 306 </BODY>
 307 </HTML>