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

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2018,2020 Free Software Foundation, Inc.              *
   4   *                                                                          *
   5   * Permission is hereby granted, free of charge, to any person obtaining a  *
   6   * copy of this software and associated documentation files (the            *
   7   * "Software"), to deal in the Software without restriction, including      *
   8   * without limitation the rights to use, copy, modify, merge, publish,      *
   9   * distribute, distribute with modifications, sublicense, and/or sell       *
  10   * copies of the Software, and to permit persons to whom the Software is    *
  11   * furnished to do so, subject to the following conditions:                 *
  12   *                                                                          *
  13   * The above copyright notice and this permission notice shall be included  *
  14   * in all copies or substantial portions of the Software.                   *
  15   *                                                                          *
  16   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17   * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18   * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19   * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20   * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21   * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22   * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23   *                                                                          *
  24   * Except as contained in this notice, the name(s) of the above copyright   *
  25   * holders shall not be used in advertising or otherwise to promote the     *
  26   * sale, use or other dealings in this Software without prior written       *
  27   * authorization.                                                           *
  28   ****************************************************************************
  29   * @Id: curs_slk.3x,v 1.35 2020/01/18 22:49:38 tom Exp @
  30 -->
  31 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  32 <HTML>
  33 <HEAD>
  34 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  35 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>curs_slk 3x</TITLE>
  37 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  38 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  39 </HEAD>
  40 <BODY>
  41 <H1 class="no-header">curs_slk 3x</H1>
  42 <PRE>
  43 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>                                                      <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
  44
  45
  46
  47
  48 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
  49        <STRONG>slk_init</STRONG>, <STRONG>slk_set</STRONG>, <STRONG>slk_wset</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_label</STRONG>,
  50        <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>,
  51        <STRONG>slk_attroff</STRONG>, <STRONG>slk_attr_on</STRONG>, <STRONG>slk_attr_set</STRONG>, <STRONG>slk_attr_off</STRONG>, <STRONG>slk_attr</STRONG>,
  52        <STRONG>slk_color</STRONG>, <STRONG>extended_slk_color</STRONG> - <STRONG>curses</STRONG> soft label routines
  53
  54
  55 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  56        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  57
  58        <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <EM>fmt</EM><STRONG>);</STRONG>
  59
  60        <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>
  61        <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>
  62
  63        <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <EM>labnum</EM><STRONG>);</STRONG>
  64
  65        <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
  66        <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
  67        <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
  70
  71        <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  72        <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  73        <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
  74        <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>void*</STRONG> <EM>opts</EM><STRONG>);</STRONG>
  75        <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>
  76        <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>
  77
  78        <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
  79
  80        <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <EM>pair</EM><STRONG>);</STRONG>
  81        /* extension */
  82        <STRONG>int</STRONG> <STRONG>extended_slk_color(int</STRONG> <EM>pair</EM><STRONG>);</STRONG>
  83
  84
  85 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  86        The slk* functions manipulate the set of soft function-key labels  that
  87        exist on many terminals.  For those terminals that do not have soft la-
  88        bels, <STRONG>curses</STRONG> takes over the bottom line of <STRONG>stdscr</STRONG>, reducing the size of
  89        <STRONG>stdscr</STRONG>  and the variable <STRONG>LINES</STRONG>.  <STRONG>curses</STRONG> standardizes on eight labels of
  90        up to eight characters each.  In addition to this, the  ncurses  imple-
  91        mentation  supports  a  mode where it simulates 12 labels of up to five
  92        characters each.  This is useful for PC-like enduser devices.   ncurses
  93        simulates this mode by taking over up to two lines at the bottom of the
  94        screen; it does not try to use any hardware support for this mode.
  95
  96
  97 </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
  98        The <STRONG>slk_init</STRONG> routine must  be  called  before  <STRONG>initscr</STRONG>  or  <STRONG>newterm</STRONG>  is
  99        called.   If  <STRONG>initscr</STRONG> eventually uses a line from <STRONG>stdscr</STRONG> to emulate the
 100        soft labels, then <EM>fmt</EM> determines how the labels  are  arranged  on  the
 101        screen:
 102
 103           <STRONG>0</STRONG>  indicates a 3-2-3 arrangement of the labels.
 104
 105           <STRONG>1</STRONG>  indicates a 4-4 arrangement
 106
 107           <STRONG>2</STRONG>  indicates the PC-like 4-4-4 mode.
 108
 109           <STRONG>3</STRONG>  is again the PC-like 4-4-4 mode, but in addition an index line is
 110              generated, helping the user to identify the key numbers easily.
 111
 112
 113 </PRE><H3><a name="h3-Labels">Labels</a></H3><PRE>
 114        The <STRONG>slk_set</STRONG> routine (and the <STRONG>slk_wset</STRONG> routine  for  the  wide-character
 115        library) has three parameters:
 116
 117           <EM>labnum</EM>
 118                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>
 119                or <STRONG>3</STRONG>);
 120
 121           <EM>label</EM>
 122                is be the string to put on the label, up to eight (five for <EM>fmt</EM>
 123                in  <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length.  A null string or
 124                a null pointer sets up a blank label.
 125
 126           <EM>fmt</EM>  is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the  label  is  to  be
 127                left-justified,  centered,  or  right-justified,  respectively,
 128                within the label.
 129
 130        The <STRONG>slk_label</STRONG> routine returns the current label for label  number  <EM>lab-</EM>
 131        <EM>num</EM>, with leading and trailing blanks stripped.
 132
 133
 134 </PRE><H3><a name="h3-Screen-updates">Screen updates</a></H3><PRE>
 135        The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to the <STRONG>wrefresh</STRONG>
 136        and <STRONG>wnoutrefresh</STRONG> routines.
 137
 138        The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen.
 139
 140        The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after  a
 141        <STRONG>slk_clear</STRONG> has been performed.
 142
 143        The  <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next
 144        time a <STRONG>slk_noutrefresh</STRONG> is performed.
 145
 146
 147 </PRE><H3><a name="h3-Video-attributes">Video attributes</a></H3><PRE>
 148        The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG>  routines  corre-
 149        spond  to  <STRONG>attron</STRONG>,  <STRONG>attrset</STRONG>,  <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>, respectively.  They
 150        have an effect only if soft labels are simulated on the bottom line  of
 151        the  screen.   The default highlight for soft keys is A_STANDOUT (as in
 152        System V curses, which does not document this fact).
 153
 154
 155 </PRE><H3><a name="h3-Colors">Colors</a></H3><PRE>
 156        The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>.  It has an effect  only
 157        if soft labels are simulated on the bottom line of the screen.
 158
 159        Because  <STRONG>slk_color</STRONG>  accepts  only <STRONG>short</STRONG> (signed 16-bit integer) values,
 160        this implementation provides <STRONG>extended_slk_color</STRONG> which accepts an  inte-
 161        ger value, e.g., 32-bits.
 162
 163
 164 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 165        These  routines return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 specifies only "an
 166        integer value other than <STRONG>ERR</STRONG>") upon successful completion.
 167
 168        X/Open defines no error conditions.  In this implementation
 169
 170           <STRONG>slk_attr</STRONG>
 171                returns the attribute used for the soft keys.
 172
 173           <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>,
 174           <STRONG>slk_touch</STRONG>
 175                return  an  error if the terminal or the softkeys were not ini-
 176                tialized.
 177
 178           <STRONG>slk_attrset</STRONG>
 179                returns an error if the terminal or the softkeys were not  ini-
 180                tialized.
 181
 182           <STRONG>slk_attr_set</STRONG>
 183                returns  an error if the terminal or the softkeys were not ini-
 184                tialized, or the  color  pair  is  outside  the  range  0..COL-
 185                OR_PAIRS-1.
 186
 187           <STRONG>slk_color</STRONG>
 188                returns  an error if the terminal or the softkeys were not ini-
 189                tialized, or the  color  pair  is  outside  the  range  0..COL-
 190                OR_PAIRS-1.
 191
 192           <STRONG>slk_init</STRONG>
 193                returns  an  error if the format parameter is outside the range
 194                0..3.
 195
 196           <STRONG>slk_label</STRONG>
 197                returns <STRONG>NULL</STRONG> on error.
 198
 199           <STRONG>slk_set</STRONG>
 200                returns an error if the terminal or the softkeys were not  ini-
 201                tialized, or the <EM>labnum</EM> parameter is outside the range of label
 202                counts, or if the format parameter is outside the  range  0..2,
 203                or if memory for the labels cannot be allocated.
 204
 205
 206 </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
 207        SVr3 introduced these functions:
 208          slk_clear
 209          slk_init
 210          slk_label
 211          slk_noutrefresh
 212          slk_refresh
 213          slk_restore
 214          slk_set
 215          slk_touch
 216
 217        SVr4 added these functions:
 218          slk_attroff
 219          slk_attron
 220          slk_attrset
 221          slk_start
 222
 223        X/Open Curses added these:
 224          slk_attr_off
 225          slk_attr_on
 226          slk_attr_set
 227          slk_color
 228          slk_wset
 229
 230
 231 </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
 232        X/Open  Curses  documents the <EM>opts</EM> argument as reserved for future use,
 233        saying that it must be null.  This implementation uses  that  parameter
 234        in ABI 6 for the functions which have a color-pair parameter to support
 235        extended color pairs.
 236
 237        For  functions  which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM>  is
 238        set  it  is  treated  as a pointer to <STRONG>int</STRONG>, and used to  set  the  color
 239        pair instead of the <STRONG>short</STRONG> pair parameter.
 240
 241
 242 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 243        Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wrefresh</STRONG> is like-
 244        ly to follow soon.
 245
 246
 247 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 248        The  XSI  Curses  standard,  Issue 4, described the soft-key functions,
 249        with some differences from SVr4 curses:
 250
 251        <STRONG>o</STRONG>   It added functions like the SVr4  attribute-manipulation  functions
 252            <STRONG>slk_attron</STRONG>,  <STRONG>slk_attroff</STRONG>, <STRONG>slk_attrset</STRONG>, but which use <STRONG>attr_t</STRONG> parame-
 253            ters (rather than <STRONG>chtype</STRONG>), along with a reserved <EM>opts</EM> parameter.
 254
 255            Two of these new functions (unlike the SVr4 functions) have no pro-
 256            vision for color: <STRONG>slk_attr_on</STRONG> and <STRONG>slk_attr_off</STRONG>.
 257
 258            The third function (<STRONG>slk_attr_set</STRONG>) has a color-pair parameter.
 259
 260        <STRONG>o</STRONG>   It added <STRONG>const</STRONG> qualifiers to parameters (unnecessarily), and
 261
 262        <STRONG>o</STRONG>   It added <STRONG>slk_color</STRONG>.
 263
 264        The  format  codes  <STRONG>2</STRONG>  and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> and the function <STRONG>slk_attr</STRONG> are
 265        specific to ncurses.
 266
 267        X/Open Curses does not specify a limit for the  number  of  colors  and
 268        color pairs which a terminal can support.  However, in its use of <STRONG>short</STRONG>
 269        for the parameters, it carries over SVr4's  implementation  detail  for
 270        the compiled terminfo database, which uses signed 16-bit numbers.  This
 271        implementation provides extended versions of those functions which  use
 272        <STRONG>short</STRONG>  parameters, allowing applications to use larger color- and pair-
 273        numbers.
 274
 275
 276 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 277        <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>,
 278        <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 279
 280
 281
 282                                                                   <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 283 </PRE>
 284 <div class="nav">
 285 <ul>
 286 <li><a href="#h2-NAME">NAME</a></li>
 287 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 288 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 289 <ul>
 290 <li><a href="#h3-Initialization">Initialization</a></li>
 291 <li><a href="#h3-Labels">Labels</a></li>
 292 <li><a href="#h3-Screen-updates">Screen updates</a></li>
 293 <li><a href="#h3-Video-attributes">Video attributes</a></li>
 294 <li><a href="#h3-Colors">Colors</a></li>
 295 </ul>
 296 </li>
 297 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 298 <li><a href="#h2-HISTORY">HISTORY</a></li>
 299 <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
 300 <li><a href="#h2-NOTES">NOTES</a></li>
 301 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 302 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 303 </ul>
 304 </div>
 305 </BODY>
 306 </HTML>