1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
3 ****************************************************************************
4 * Copyright (c) 1998,2000 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.11 2001/03/03 21:05:41 Todd.C.Miller 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 -->
46 <STRONG>slk_init</STRONG>, <STRONG>slk_set</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_noutrefresh</STRONG>,
47 <STRONG>slk_label</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>,
48 <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, <STRONG>slk_attr_on</STRONG>, <STRONG>slk_attr_set</STRONG>,
49 <STRONG>slk_attr_off</STRONG>, <STRONG>slk_attr</STRONG>, <STRONG>slk_color</STRONG> - <STRONG>curses</STRONG> soft label rou-
54 <H2>SYNOPSIS</H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <STRONG>fmt);</STRONG>
58 <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>
59 <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
60 <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
61 <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <STRONG>labnum);</STRONG>
62 <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
63 <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
64 <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
65 <STRONG>int</STRONG> <STRONG>slk_attron(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
66 <STRONG>int</STRONG> <STRONG>slk_attroff(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
67 <STRONG>int</STRONG> <STRONG>slk_attrset(const</STRONG> <STRONG>chtype</STRONG> <STRONG>attrs);</STRONG>
68 <STRONG>int</STRONG> <STRONG>slk_attr_on(attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
69 <STRONG>int</STRONG> <STRONG>slk_attr_off(const</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <STRONG>opts);</STRONG>
70 <STRONG>int</STRONG> <STRONG>slk_attr_set(const</STRONG> <STRONG>attr_t</STRONG> <STRONG>attrs,</STRONG>
71 <STRONG>short</STRONG> <STRONG>color_pair_number,</STRONG> <STRONG>void*</STRONG> <STRONG>opts);</STRONG>
72 <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
73 <STRONG>int</STRONG> <STRONG>slk_color(short</STRONG> <STRONG>color_pair_number);</STRONG>
77 <H2>DESCRIPTION</H2><PRE>
78 The slk* functions manipulate the set of soft function-key
79 labels that exist on many terminals. For those terminals
80 that do not have soft labels, <STRONG>curses</STRONG> takes over the bottom
81 line of <STRONG>stdscr</STRONG>, reducing the size of <STRONG>stdscr</STRONG> and the vari-
82 able <STRONG>LINES</STRONG>. <STRONG>curses</STRONG> standardizes on eight labels of up to
83 eight characters each. In addition to this, the ncurses
84 implementation supports a mode where it simulates 12
85 labels of up to five characters each. This is most common
86 for todays PC like enduser devices. Please note that
87 ncurses simulates this mode by taking over up to two lines
88 at the bottom of the screen, it doesn't try to use any
89 hardware support for this mode.
91 The <STRONG>slk_init</STRONG> routine must be called before <STRONG>initscr</STRONG> or
92 <STRONG>newterm</STRONG> is called. If <STRONG>initscr</STRONG> eventually uses a line from
93 <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM> determines how
94 the labels are arranged on the screen. Setting <EM>fmt</EM> to <STRONG>0</STRONG>
95 indicates a 3-2-3 arrangement of the labels, <STRONG>1</STRONG> indicates a
96 4-4 arrangement and <STRONG>2</STRONG> indicates the PC like 4-4-4 mode. If
97 <STRONG>fmt</STRONG> is set to <STRONG>3</STRONG>, it is again the PC like 4-4-4 mode, but
98 in addition an index line is generated, helping the user
99 to identify the key numbers easily.
101 The <STRONG>slk_set</STRONG> routine requires <EM>labnum</EM> to be a label number,
102 from <STRONG>1</STRONG> to <STRONG>8</STRONG> (resp. <STRONG>12</STRONG>); <EM>label</EM> must be the string to be put
103 on the label, up to eight (resp. five) characters in
104 length. A null string or a null pointer sets up a blank
105 label. <EM>fmt</EM> is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, indicating whether the
106 label is to be left-justified, centered, or right-justi-
107 fied, respectively, within the label.
109 The <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> routines correspond to
110 the <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> routines.
112 The <STRONG>slk_label</STRONG> routine returns the current label for label
113 number <EM>labnum</EM>, with leading and trailing blanks stripped.
115 The <STRONG>slk_clear</STRONG> routine clears the soft labels from the
118 The <STRONG>slk_restore</STRONG> routine, restores the soft labels to the
119 screen after a <STRONG>slk_clear</STRONG> has been performed.
121 The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be
122 output the next time a <STRONG>slk_noutrefresh</STRONG> is performed.
124 The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG> rou-
125 tines correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>.
126 They have an effect only if soft labels are simulated on
127 the bottom line of the screen. The default highlight for
128 soft keys is A_STANDOUT (as in System V curses, which does
129 not document this fact).
131 The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an
132 effect only if soft labels are simulated on the bottom
138 <H2>RETURN VALUE</H2><PRE>
139 These routines return <STRONG>ERR</STRONG> upon failure and OK (SVr4 speci-
140 fies only "an integer value other than <STRONG>ERR</STRONG>") upon success-
141 ful completion. <STRONG>slk_attr</STRONG> returns the attribute used for
144 <STRONG>slk_label</STRONG> returns <STRONG>NULL</STRONG> on error.
149 Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wre-</STRONG>
150 <STRONG>fresh</STRONG> is likely to follow soon.
154 <H2>PORTABILITY</H2><PRE>
155 The XSI Curses standard, Issue 4, describes these func-
156 tions. It changes the argument type of the attribute-
157 manipulation functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>,
158 <STRONG>slk_attrset</STRONG> to be <STRONG>attr_t</STRONG>, and adds <STRONG>const</STRONG> qualifiers. The
159 format codes <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init()</STRONG> and the function
160 <STRONG>slk_attr</STRONG> are specific to ncurses.
165 <H2>SEE ALSO</H2><PRE>
166 <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>,
167 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>
222 Man(1) output converted with
223 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>