1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998-2007,2010 Free Software Foundation, Inc. *
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: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
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. *
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 *
29 ****************************************************************************
30 * @Id: curs_slk.3x,v 1.17 2010/01/30 21:29:04 tom Exp @
34 <TITLE>curs_slk 3x</TITLE>
35 <link rev=made href="mailto:bug-ncurses@gnu.org">
36 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
42 <!-- Manpage converted by man2html 3.0.1 -->
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>
50 <STRONG>slk_init</STRONG>, <STRONG>slk_set</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
58 <H2>SYNOPSIS</H2><PRE>
59 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
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>
75 <STRONG>short</STRONG> <STRONG>color_pair_number,</STRONG> <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_number);</STRONG>
81 <H2>DESCRIPTION</H2><PRE>
82 The slk* functions manipulate the set of soft function-key
83 labels that exist on many terminals. For those terminals
84 that do not have soft labels, <STRONG>curses</STRONG> takes over the bottom
85 line of <STRONG>stdscr</STRONG>, reducing the size of <STRONG>stdscr</STRONG> and the vari-
86 able <STRONG>LINES</STRONG>. <STRONG>curses</STRONG> standardizes on eight labels of up to
87 eight characters each. In addition to this, the ncurses
88 implementation supports a mode where it simulates 12 la-
89 bels of up to five characters each. This is useful for
90 today's PC-like enduser devices. ncurses simulates this
91 mode by taking over up to two lines at the bottom of the
92 screen; it does not try to use any hardware support for
95 The <STRONG>slk_init</STRONG> routine must be called before <STRONG>initscr</STRONG> or
96 <STRONG>newterm</STRONG> is called. If <STRONG>initscr</STRONG> eventually uses a line from
97 <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM> determines how
98 the labels are arranged on the screen:
100 <STRONG>0</STRONG> indicates a 3-2-3 arrangement of the labels.
102 <STRONG>1</STRONG> indicates a 4-4 arrangement
104 <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode.
106 <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition
107 an index line is generated, helping the user to
108 identify the key numbers easily.
110 The <STRONG>slk_set</STRONG> routine has three parameters:
113 is the label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 for <EM>fmt</EM>
114 in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>);
117 is be the string to put on the label, up to
118 eight (five for <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>)
119 characters in length. A null string or a null
120 pointer sets up a blank label.
122 <EM>fmt</EM> is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the
123 label is to be left-justified, centered, or
124 right-justified, respectively, within the la-
127 The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to
128 the <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> routines.
130 The <STRONG>slk_label</STRONG> routine returns the current label for label
131 number <EM>labnum</EM>, with leading and trailing blanks stripped.
133 The <STRONG>slk_clear</STRONG> routine clears the soft labels from the
136 The <STRONG>slk_restore</STRONG> routine restores the soft labels to the
137 screen after a <STRONG>slk_clear</STRONG> has been performed.
139 The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be
140 output the next time a <STRONG>slk_noutrefresh</STRONG> is performed.
142 The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG> rou-
143 tines correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>.
144 They have an effect only if soft labels are simulated on
145 the bottom line of the screen. The default highlight for
146 soft keys is A_STANDOUT (as in System V curses, which does
147 not document this fact).
149 The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an
150 effect only if soft labels are simulated on the bottom
155 <H2>RETURN VALUE</H2><PRE>
156 These routines return <STRONG>ERR</STRONG> upon failure and OK (SVr4 speci-
157 fies only "an integer value other than <STRONG>ERR</STRONG>") upon success-
160 X/Open defines no error conditions. In this implementa-
163 <STRONG>slk_attr</STRONG>
164 returns the attribute used for the soft keys.
166 <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>,
167 <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_touch</STRONG>
168 return an error if the terminal or the soft-
169 keys were not initialized.
171 <STRONG>slk_attrset</STRONG>
172 returns an error if the terminal or the soft-
173 keys were not initialized.
175 <STRONG>slk_attr_set</STRONG>
176 returns an error if the terminal or the soft-
177 keys were not initialized, or the color pair
178 is outside the range 0..COLOR_PAIRS-1, or opts
181 <STRONG>slk_color</STRONG>
182 returns an error if the terminal or the soft-
183 keys were not initialized, or the color pair
184 is outside the range 0..COLOR_PAIRS-1.
186 <STRONG>slk_init</STRONG>
187 returns an error if the format parameter is
188 outside the range 0..3.
190 <STRONG>slk_label</STRONG>
191 returns <STRONG>NULL</STRONG> on error.
193 <STRONG>slk_set</STRONG>
194 returns an error if the terminal or the soft-
195 keys were not initialized, or the <EM>labnum</EM> pa-
196 rameter is outside the range of label counts,
197 or if the format parameter is outside the
198 range 0..2, or if memory for the labels cannot
204 Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wre-</STRONG>
205 <STRONG>fresh</STRONG> is likely to follow soon.
209 <H2>PORTABILITY</H2><PRE>
210 The XSI Curses standard, Issue 4, describes these func-
211 tions. It changes the argument type of the attribute-ma-
212 nipulation functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, <STRONG>slk_attrset</STRONG>
213 to be <STRONG>attr_t</STRONG>, and adds <STRONG>const</STRONG> qualifiers. The format codes
214 <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init()</STRONG> and the function <STRONG>slk_attr</STRONG> are spe-
219 <H2>SEE ALSO</H2><PRE>
220 <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>
221 <STRONG><A HREF="curs_refresh.3x.html">fresh(3x)</A></STRONG>
225 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>
229 Man(1) output converted with
230 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>