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.37 2020/12/30 18:37:43 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        /* extension */
  63        <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>
  64
  65        <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <EM>labnum</EM><STRONG>);</STRONG>
  66
  67        <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
  70        <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
  72
  73        <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  74        <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  75        <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  76        <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
  77        <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>
  78        <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>
  79
  80        <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
  81
  82        <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <EM>pair</EM><STRONG>);</STRONG>
  83        /* extension */
  84        <STRONG>int</STRONG> <STRONG>extended_slk_color(int</STRONG> <EM>pair</EM><STRONG>);</STRONG>
  85
  86
  87 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  88        The slk* functions manipulate the set of soft function-key labels  that
  89        exist on many terminals.  For those terminals that do not have soft la-
  90        bels, <STRONG>curses</STRONG> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing the size of
  91        <STRONG>stdscr</STRONG>  and the variable <STRONG>LINES</STRONG>.  <STRONG>curses</STRONG> standardizes on eight labels of
  92        up to eight characters each.  In addition to this, the  ncurses  imple-
  93        mentation  supports  a  mode where it simulates 12 labels of up to five
  94        characters each.  This is useful for PC-like enduser devices.   ncurses
  95        simulates this mode by taking over up to two lines at the bottom of the
  96        screen; it does not try to use any hardware support for 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 for <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG>
 121                or <STRONG>3</STRONG>);
 122
 123           <EM>label</EM>
 124                is be the string to put on the label, up to eight (five for <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  <EM>lab-</EM>
 133        <EM>num</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  corre-
 151        spond  to  <STRONG>attron</STRONG>,  <STRONG>attrset</STRONG>,  <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>, respectively.  They
 152        have an effect only if soft labels are simulated on the bottom line  of
 153        the  screen.   The default highlight for soft keys is A_STANDOUT (as in
 154        System V curses, 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  inte-
 163        ger 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 ini-
 178                tialized.
 179
 180           <STRONG>slk_attrset</STRONG>
 181                returns an error if the terminal or the softkeys were not  ini-
 182                tialized.
 183
 184           <STRONG>slk_attr_set</STRONG>
 185                returns  an error if the terminal or the softkeys were not ini-
 186                tialized, or the  color  pair  is  outside  the  range  0..COL-
 187                OR_PAIRS-1.
 188
 189           <STRONG>slk_color</STRONG>
 190                returns  an error if the terminal or the softkeys were not ini-
 191                tialized, or the  color  pair  is  outside  the  range  0..COL-
 192                OR_PAIRS-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  ini-
 203                tialized, or the <EM>labnum</EM> parameter is outside the range of label
 204                counts, or if the format parameter is outside the  range  0..2,
 205                or if memory for the labels cannot be allocated.
 206
 207
 208 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 209        SVr3 introduced these functions:
 210          slk_clear
 211          slk_init
 212          slk_label
 213          slk_noutrefresh
 214          slk_refresh
 215          slk_restore
 216          slk_set
 217          slk_touch
 218
 219        SVr4 added these functions:
 220          slk_attroff
 221          slk_attron
 222          slk_attrset
 223          slk_start
 224
 225        X/Open Curses added these:
 226          slk_attr_off
 227          slk_attr_on
 228          slk_attr_set
 229          slk_color
 230          slk_wset
 231
 232
 233 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 234        X/Open  Curses  documents the <EM>opts</EM> argument as reserved for future use,
 235        saying that it must be null.  This implementation uses  that  parameter
 236        in ABI 6 for the functions which have a color-pair parameter to support
 237        extended color pairs.
 238
 239        For  functions  which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM>  is
 240        set  it  is  treated  as a pointer to <STRONG>int</STRONG>, and used to  set  the  color
 241        pair instead of the <STRONG>short</STRONG> pair parameter.
 242
 243
 244 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 245        Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is like-
 246        ly to follow soon.
 247
 248
 249 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 250        The  XSI  Curses  standard,  Issue 4, described the soft-key functions,
 251        with some differences from SVr4 curses:
 252
 253        <STRONG>o</STRONG>   It added functions like the SVr4  attribute-manipulation  functions
 254            <STRONG>slk_attron</STRONG>,  <STRONG>slk_attroff</STRONG>, <STRONG>slk_attrset</STRONG>, but which use <STRONG>attr_t</STRONG> parame-
 255            ters (rather than <STRONG>chtype</STRONG>), along with a reserved <EM>opts</EM> parameter.
 256
 257            Two of these new functions (unlike the SVr4 functions) have no pro-
 258            vision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
 259
 260            The third function (<STRONG>slk_attr_set</STRONG>) has a color-pair parameter.
 261
 262        <STRONG>o</STRONG>   It added <STRONG>const</STRONG> qualifiers to parameters (unnecessarily), and
 263
 264        <STRONG>o</STRONG>   It added <STRONG>slk_color</STRONG>.
 265
 266        The  format  codes  <STRONG>2</STRONG>  and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> and the function <STRONG>slk_attr</STRONG> are
 267        specific to ncurses.
 268
 269        X/Open Curses does not specify a limit for the  number  of  colors  and
 270        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 271        for the parameters, it carries over SVr4's  implementation  detail  for
 272        the compiled terminfo database, which uses signed 16-bit numbers.  This
 273        implementation provides extended versions of those functions which  use
 274        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
 275        numbers.
 276
 277
 278 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 279        <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>,
 280        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 281
 282
 283
 284                                                                   <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 285 </PRE>
 286 <div class="nav">
 287 <ul>
 288 <li><a href="#h2-NAME">NAME</a></li>
 289 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 290 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 291 <ul>
 292 <li><a href="#h3-Initialization">Initialization</a></li>
 293 <li><a href="#h3-Labels">Labels</a></li>
 294 <li><a href="#h3-Screen-updates">Screen updates</a></li>
 295 <li><a href="#h3-Video-attributes">Video attributes</a></li>
 296 <li><a href="#h3-Colors">Colors</a></li>
 297 </ul>
 298 </li>
 299 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 300 <li><a href="#h2-HISTORY">HISTORY</a></li>
 301 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 302 <li><a href="#h2-NOTES">NOTES</a></li>
 303 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 304 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 305 </ul>
 306 </div>
 307 </BODY>
 308 </HTML>