html/man/curs_slk.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright (c) 1998-2007,2010 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.22 2010/12/04 18:38:55 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 http://invisible-island.net/scripts/readme.html#others_scripts">
  36 <TITLE>curs_slk 3x</TITLE>
  37 <link rev=made 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>
  49 <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>,
  51        <STRONG>slk_label</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>,
  52        <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, <STRONG>slk_attr_on</STRONG>, <STRONG>slk_attr_set</STRONG>,
  53        <STRONG>slk_attr_off</STRONG>, <STRONG>slk_attr</STRONG>, <STRONG>slk_color</STRONG> - <STRONG>curses</STRONG> soft label
  54        routines
  55
  56
  57 </PRE>
  58 <H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  59        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  60
  61        <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <STRONG>fmt);</STRONG>
  62        <STRONG>int</STRONG> <STRONG>slk_set(int</STRONG> <STRONG>labnum,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*label,</STRONG> <STRONG>int</STRONG> <STRONG>fmt);</STRONG>
  63        <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
  64        <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
  65        <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <STRONG>labnum);</STRONG>
  66        <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
  67        <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
  68        <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
  69        <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
  70        <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
  71        <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
  72        <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
  73        <STRONG>int</STRONG> <STRONG>slk_attr_off(const</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <STRONG>opts);</STRONG>
  74        <STRONG>int</STRONG>  <STRONG>slk_attr_set(const</STRONG>  <STRONG>attr_t</STRONG>  <STRONG>attrs,</STRONG>  <STRONG>short</STRONG> <STRONG>color_pair,</STRONG>
  75        <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
  76        <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
  77        <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <STRONG>color_pair);</STRONG>
  78        <STRONG>int</STRONG> <STRONG>slk_wset(int</STRONG> <STRONG>labnum,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*label,</STRONG> <STRONG>int</STRONG> <STRONG>fmt);</STRONG>
  79
  80
  81 </PRE>
  82 <H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  83        The slk* functions manipulate the set of soft function-key
  84        labels  that exist on many terminals.  For those terminals
  85        that do not have soft labels, <STRONG>curses</STRONG> takes over the bottom
  86        line  of <STRONG>stdscr</STRONG>, reducing the size of <STRONG>stdscr</STRONG> and the vari-
  87        able <STRONG>LINES</STRONG>.  <STRONG>curses</STRONG> standardizes on eight labels of up  to
  88        eight  characters  each.  In addition to this, the ncurses
  89        implementation supports a mode where it simulates  12  la-
  90        bels  of  up  to five characters each.  This is useful for
  91        today's PC-like enduser devices.  ncurses  simulates  this
  92        mode  by  taking over up to two lines at the bottom of the
  93        screen; it does not try to use any  hardware  support  for
  94        this mode.
  95
  96        The  <STRONG>slk_init</STRONG>  routine  must  be  called before <STRONG>initscr</STRONG> or
  97        <STRONG>newterm</STRONG> is called.  If <STRONG>initscr</STRONG> eventually uses a line from
  98        <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM> determines how
  99        the labels are arranged on the screen:
 100
 101               <STRONG>0</STRONG>  indicates a 3-2-3 arrangement of the labels.
 102
 103               <STRONG>1</STRONG>  indicates a 4-4 arrangement
 104
 105               <STRONG>2</STRONG>  indicates the PC-like 4-4-4 mode.
 106
 107               <STRONG>3</STRONG>  is again the PC-like 4-4-4 mode, but in addition
 108                  an  index line is generated, helping the user to
 109                  identify the key numbers easily.
 110
 111        The <STRONG>slk_set</STRONG> routine (and  the  <STRONG>slk_wset</STRONG>  routine  for  the
 112        wide-character library) has three parameters:
 113
 114               <EM>labnum</EM>
 115                    is  the  label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 for <EM>fmt</EM>
 116                    in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>);
 117
 118               <EM>label</EM>
 119                    is be the string to put on the  label,  up  to
 120                    eight  (five  for  <EM>fmt</EM>  in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>)
 121                    characters in length.  A null string or a null
 122                    pointer sets up a blank label.
 123
 124               <EM>fmt</EM>  is  either  <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the
 125                    label is to be  left-justified,  centered,  or
 126                    right-justified,  respectively, within the la-
 127                    bel.
 128
 129        The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to
 130        the <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> routines.
 131
 132        The  <STRONG>slk_label</STRONG> routine returns the current label for label
 133        number <EM>labnum</EM>, with leading and trailing blanks stripped.
 134
 135        The <STRONG>slk_clear</STRONG> routine clears  the  soft  labels  from  the
 136        screen.
 137
 138        The  <STRONG>slk_restore</STRONG>  routine  restores the soft labels to the
 139        screen after a <STRONG>slk_clear</STRONG> has been performed.
 140
 141        The <STRONG>slk_touch</STRONG> routine forces all the  soft  labels  to  be
 142        output the next time a <STRONG>slk_noutrefresh</STRONG> is performed.
 143
 144        The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG> rou-
 145        tines correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>.
 146        They  have  an effect only if soft labels are simulated on
 147        the bottom line of the screen.  The default highlight  for
 148        soft keys is A_STANDOUT (as in System V curses, which does
 149        not document this fact).
 150
 151        The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>.  It has an
 152        effect  only  if  soft  labels are simulated on the bottom
 153        line of the screen.
 154
 155
 156 </PRE>
 157 <H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 158        These routines return <STRONG>ERR</STRONG> upon failure and OK (SVr4 speci-
 159        fies only "an integer value other than <STRONG>ERR</STRONG>") upon success-
 160        ful completion.
 161
 162        X/Open defines no error conditions.  In  this  implementa-
 163        tion
 164
 165               <STRONG>slk_attr</STRONG>
 166                    returns the attribute used for the soft keys.
 167
 168               <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>,
 169               <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_touch</STRONG>
 170                    return an error if the terminal or  the  soft-
 171                    keys were not initialized.
 172
 173               <STRONG>slk_attrset</STRONG>
 174                    returns  an error if the terminal or the soft-
 175                    keys were not initialized.
 176
 177               <STRONG>slk_attr_set</STRONG>
 178                    returns an error if the terminal or the  soft-
 179                    keys  were  not initialized, or the color pair
 180                    is outside the range 0..COLOR_PAIRS-1, or opts
 181                    is not null.
 182
 183               <STRONG>slk_color</STRONG>
 184                    returns  an error if the terminal or the soft-
 185                    keys were not initialized, or the  color  pair
 186                    is outside the range 0..COLOR_PAIRS-1.
 187
 188               <STRONG>slk_init</STRONG>
 189                    returns  an  error  if the format parameter is
 190                    outside the range 0..3.
 191
 192               <STRONG>slk_label</STRONG>
 193                    returns <STRONG>NULL</STRONG> on error.
 194
 195               <STRONG>slk_set</STRONG>
 196                    returns an error if the terminal or the  soft-
 197                    keys  were  not initialized, or the <EM>labnum</EM> pa-
 198                    rameter is outside the range of label  counts,
 199                    or  if  the  format  parameter  is outside the
 200                    range 0..2, or if memory for the labels cannot
 201                    be allocated.
 202
 203
 204 </PRE>
 205 <H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 206        Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wre-</STRONG>
 207        <STRONG>fresh</STRONG> is likely to follow soon.
 208
 209
 210 </PRE>
 211 <H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 212        The XSI Curses standard, Issue 4,  describes  these  func-
 213        tions.   It changes the argument type of the attribute-ma-
 214        nipulation functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>,  <STRONG>slk_attrset</STRONG>
 215        to be <STRONG>attr_t</STRONG>, and adds <STRONG>const</STRONG> qualifiers.  The format codes
 216        <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init()</STRONG> and the function <STRONG>slk_attr</STRONG> are  spe-
 217        cific to ncurses.
 218
 219
 220 </PRE>
 221 <H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 222        <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>curs_re-</STRONG>
 223        <STRONG><A HREF="curs_refresh.3x.html">fresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>.
 224
 225
 226
 227                                                            <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
 228 </PRE>
 229 <div class="nav">
 230 <ul>
 231 <li><a href="#h2-NAME">NAME</a></li>
 232 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 233 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li>
 234 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 235 <li><a href="#h2-NOTES">NOTES</a></li>
 236 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 237 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 238 </ul>
 239 </div>
 240 </BODY>
 241 </HTML>