ncurses 5.1
[ncurses.git] / doc / html / man / curs_slk.3x.html
1 <HTML>
2 <BODY>
3 <PRE>
4 <!-- Manpage converted by man2html 3.0.1 -->
5
6 </PRE>
7 <H2>NAME</H2><PRE>
8        <B>slk_init</B>,     <B>slk_set</B>,    <B>slk_refresh</B>,    <B>slk_noutrefresh</B>,
9        <B>slk_label</B>, <B>slk_clear</B>, <B>slk_restore</B>, <B>slk_touch</B>,  <B>slk_attron</B>,
10        <B>slk_attrset</B>,   <B>slk_attroff</B>,   <B>slk_attr_on</B>,   <B>slk_attr_set</B>,
11        <B>slk_attr_off</B>, <B>slk_attr</B> <B>slk_color</B> - <B>curses</B> soft label  rou-
12        tines
13
14
15 </PRE>
16 <H2>SYNOPSIS</H2><PRE>
17        <B>#include</B> <B>&lt;curses.h&gt;</B>
18
19        <B>int</B> <B>slk_init(int</B> <B>fmt);</B>
20        <B>int</B> <B>slk_set(int</B> <B>labnum,</B> <B>const</B> <B>char</B> <B>*label,</B> <B>int</B> <B>fmt);</B>
21        <B>int</B> <B>slk_refresh(void);</B>
22        <B>int</B> <B>slk_noutrefresh(void);</B>
23        <B>char</B> <B>*slk_label(int</B> <B>labnum);</B>
24        <B>int</B> <B>slk_clear(void);</B>
25        <B>int</B> <B>slk_restore(void);</B>
26        <B>int</B> <B>slk_touch(void);</B>
27        <B>int</B> <B>slk_attron(const</B> <B>chtype</B> <B>attrs);</B>
28        <B>int</B> <B>slk_attroff(const</B> <B>chtype</B> <B>attrs);</B>
29        <B>int</B> <B>slk_attrset(const</B> <B>chtype</B> <B>attrs);</B>
30        <B>int</B> <B>slk_attr_on(attr_t</B> <B>attrs,</B> <B>void*</B> <B>opts);</B>
31        <B>int</B> <B>slk_attr_off(const</B> <B>attr_t</B> <B>attrs,</B> <B>void</B> <B>*</B> <B>opts);</B>
32        <B>int</B> <B>slk_attr_set(const</B> <B>attr_t</B> <B>attrs,</B>
33             <B>short</B> <B>color_pair_number,</B> <B>void*</B> <B>opts);</B>
34        <B>attr_t</B> <B>slk_attr(void);</B>
35        <B>int</B> <B>slk_color(short</B> <B>color_pair_number);</B>
36
37
38 </PRE>
39 <H2>DESCRIPTION</H2><PRE>
40        The slk* functions manipulate the set of soft function-key
41        labels that exist on many terminals.  For those  terminals
42        that do not have soft labels, <B>curses</B> takes over the bottom
43        line of <B>stdscr</B>, reducing the size of <B>stdscr</B> and the  vari-
44        able  <B>LINES</B>.  <B>curses</B> standardizes on eight labels of up to
45        eight characters each. In addition to  this,  the  ncurses
46        implementation  supports  a  mode  where  it  simulates 12
47        labels of up to five characters each. This is most  common
48        for  todays  PC  like  enduser  devices.  Please note that
49        ncurses simulates this mode by taking over up to two lines
50        at  the  bottom  of  the screen, it doesn't try to use any
51        hardware support for this mode.
52
53        The <B>slk_init</B> routine must  be  called  before  <B>initscr</B>  or
54        <B>newterm</B> is called.  If <B>initscr</B> eventually uses a line from
55        <B>stdscr</B> to emulate the soft labels, then <I>fmt</I> determines how
56        the  labels  are arranged on the screen.  Setting <I>fmt</I> to <B>0</B>
57        indicates a 3-2-3 arrangement of the labels, <B>1</B> indicates a
58        4-4 arrangement and <B>2</B> indicates the PC like 4-4-4 mode. If
59        <B>fmt</B> is set to <B>3</B>, it is again the PC like 4-4-4  mode,  but
60        in  addition  an index line is generated, helping the user
61        to identify the key numbers easily.
62
63        The <B>slk_set</B> routine requires <I>labnum</I> to be a label  number,
64        from <B>1</B> to <B>8</B> (resp. <B>12</B>); <I>label</I> must be the string to be put
65        on the label, up  to  eight  (resp.  five)  characters  in
66        length.   A  null string or a null pointer sets up a blank
67        label. <I>fmt</I> is either <B>0</B>, <B>1</B>, or <B>2</B>,  indicating  whether  the
68        label  is  to be left-justified, centered, or right-justi-
69        fied, respectively, within the label.
70
71        The <B>slk_refresh</B> and <B>slk_noutrefresh</B> routines correspond to
72        the <B>wrefresh</B> and <B>wnoutrefresh</B> routines.
73
74        The  <B>slk_label</B> routine returns the current label for label
75        number <I>labnum</I>, with leading and trailing blanks  stripped.
76
77        The  <B>slk_clear</B>  routine  clears  the  soft labels from the
78        screen.
79
80        The <B>slk_restore</B> routine, restores the soft labels  to  the
81        screen after a <B>slk_clear</B> has been performed.
82
83        The  <B>slk_touch</B>  routine  forces  all the soft labels to be
84        output the next time a <B>slk_noutrefresh</B> is performed.
85
86        The <B>slk_attron</B>, <B>slk_attrset</B>, <B>slk_attroff</B> and <B>slk_attr</B> rou-
87        tines correspond to <B>attron</B>, <B>attrset</B>, <B>attroff</B> and <B>attr_get</B>.
88        They have an effect only if soft labels are  simulated  on
89        the  bottom line of the screen.  The default highlight for
90        soft keys is A_STANDOUT (as in System V curses, which does
91        not document this fact).
92
93        The  <B>slk_color</B> routine corresponds to <B>color_set</B>. It has an
94        effect only if soft labels are  simulated  on  the  bottom
95        line of the screen.
96
97
98
99 </PRE>
100 <H2>RETURN VALUE</H2><PRE>
101        These routines return <B>ERR</B> upon failure and OK (SVr4 speci-
102        fies only "an integer value other than <B>ERR</B>") upon success-
103        ful  completion.  <B>slk_attr</B>  returns the attribute used for
104        the soft keys.
105
106        <B>slk_label</B> returns <B>NULL</B> on error.
107
108
109 </PRE>
110 <H2>NOTES</H2><PRE>
111        Most applications would use <B>slk_noutrefresh</B> because a <B>wre-</B>
112        <B>fresh</B> is likely to follow soon.
113
114
115 </PRE>
116 <H2>PORTABILITY</H2><PRE>
117        The  XSI  Curses  standard, Issue 4, describes these func-
118        tions.  It changes the argument  type  of  the  attribute-
119        manipulation     functions     <B>slk_attron</B>,    <B>slk_attroff</B>,
120        <B>slk_attrset</B> to be <B>attr_t</B>, and adds <B>const</B>  qualifiers.  The
121        format  codes  <B>2</B>  and  <B>3</B>  for  <B>slk_init()</B> and the function
122        <B>slk_attr</B> are specific to ncurses.
123
124
125
126 </PRE>
127 <H2>SEE ALSO</H2><PRE>
128        <B><A HREF="ncurses.3x.html">curses(3x)</A></B>,        <B><A HREF="curs_attr.3x.html">curs_attr(3x)</A></B>,        <B><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></B>,
129        <B><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></B>
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181 </PRE>
182 <HR>
183 <ADDRESS>
184 Man(1) output converted with
185 <a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
186 </ADDRESS>
187 </BODY>
188 </HTML>