ncurses 4.1
[ncurses.git] / Ada95 / html / curs_slk.3x.html
1 <HTML>
2 <BODY BGCOLOR="#99ccbb" TEXT="#000000" LINK="#4060b0" VLINK="#000080" ALINK="#ff4040">
3 <PRE>
4        <STRONG>slk_init</STRONG>,     <STRONG>slk_set</STRONG>,    <STRONG>slk_refresh</STRONG>,    <STRONG>slk_noutrefresh</STRONG>,
5        <STRONG>slk_label</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>,  <STRONG>slk_attron</STRONG>,
6        <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> - <STRONG>curses</STRONG> soft label routines
7
8
9 </PRE>
10 <H2>SYNOPSIS</H2><PRE>
11        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
12
13        <STRONG>int</STRONG> <STRONG>slk_init(int</STRONG> <STRONG>fmt);</STRONG>
14        <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>
15        <STRONG>int</STRONG> <STRONG>slk_refresh(void);</STRONG>
16        <STRONG>int</STRONG> <STRONG>slk_noutrefresh(void);</STRONG>
17        <STRONG>char</STRONG> <STRONG>*slk_label(int</STRONG> <STRONG>labnum);</STRONG>
18        <STRONG>int</STRONG> <STRONG>slk_clear(void);</STRONG>
19        <STRONG>int</STRONG> <STRONG>slk_restore(void);</STRONG>
20        <STRONG>int</STRONG> <STRONG>slk_touch(void);</STRONG>
21        <STRONG>int</STRONG> <STRONG>slk_attron(attr_t</STRONG> <STRONG>attrs);</STRONG>
22        <STRONG>int</STRONG> <STRONG>slk_attrset(attr_t</STRONG> <STRONG>attrs);</STRONG>
23        <STRONG>attr_t</STRONG> <STRONG>slk_attr(void);</STRONG>
24        <STRONG>int</STRONG> <STRONG>slk_attroff(attr_t</STRONG> <STRONG>attrs);</STRONG>
25
26
27 </PRE>
28 <H2>DESCRIPTION</H2><PRE>
29        The slk* functions manipulate the set of soft function-key
30        labels that exist on many terminals.  For those  terminals
31        that do not have soft labels, <STRONG>curses</STRONG> takes over the bottom
32        line of <STRONG>stdscr</STRONG>, reducing the size of <STRONG>stdscr</STRONG> and the  vari-
33        able  <STRONG>LINES</STRONG>.  <STRONG>curses</STRONG> standardizes on eight labels of up to
34        eight characters each. In addition to  this,  the  ncurses
35        implementation  supports  a  mode  where  it  simulates 12
36        labels of up to five characters each. This is most  common
37        for  todays  PC  like  enduser  devices.  Please note that
38        ncurses simulates this mode by taking over up to two lines
39        at  the  bottom  of  the screen, it doesn't try to use any
40        hardware support for this mode.
41
42        The <STRONG>slk_init</STRONG> routine must  be  called  before  <STRONG>initscr</STRONG>  or
43        <STRONG>newterm</STRONG> is called.  If <STRONG>initscr</STRONG> eventually uses a line from
44        <STRONG>stdscr</STRONG> to emulate the soft labels, then <EM>fmt</EM> determines how
45        the  labels  are arranged on the screen.  Setting <EM>fmt</EM> to <STRONG>0</STRONG>
46        indicates a 3-2-3 arrangement of the labels, <STRONG>1</STRONG> indicates a
47        4-4 arrangement and <STRONG>2</STRONG> indicates the PC like 4-4-4 mode. If
48        <STRONG>fmt</STRONG> is set to <STRONG>3</STRONG>, it is again the PC like 4-4-4  mode,  but
49        in  addition  an index line is generated, helping the user
50        to identify the key numbers easily.
51
52        The <STRONG>slk_set</STRONG> routine requires <EM>labnum</EM> to be a label  number,
53        from <STRONG>1</STRONG> to <STRONG>8</STRONG> (resp. <STRONG>12</STRONG>); <EM>label</EM> must be the string to be put
54        on the label, up  to  eight  (resp.  five)  characters  in
55        length.   A  null string or a null pointer sets up a blank
56        label. <EM>fmt</EM> is either <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>,  indicating  whether  the
57        label  is  to be left-justified, centered, or right-justi-
58        fied, respectively, within the label.
59
60
61        The  <STRONG>slk_label</STRONG> routine returns the current label for label
62        number <EM>labnum</EM>, with leading and trailing blanks  stripped.
63
64        The  <STRONG>slk_clear</STRONG>  routine  clears  the  soft labels from the
65        screen.
66
67        The <STRONG>slk_restore</STRONG> routine, restores the soft labels  to  the
68        screen after a <STRONG>slk_clear</STRONG> has been performed.
69
70        The  <STRONG>slk_touch</STRONG>  routine  forces  all the soft labels to be
71        output the next time a <STRONG>slk_noutrefresh</STRONG> is performed.
72
73        The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG> and <STRONG>slk_attr</STRONG> rou-
74        tines correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG> and <STRONG>attr_get</STRONG>.
75        They have an effect only if soft labels are  simulated  on
76        the  bottom line of the screen.  The default highlight for
77        soft keys is A_STANDOUT (as in System V curses, which does
78        not document this fact).
79
80
81 </PRE>
82 <H2>RETURN VALUE</H2><PRE>
83        These routines return <STRONG>ERR</STRONG> upon failure and OK (SVr4 speci-
84        fies only "an integer value other than <STRONG>ERR</STRONG>") upon success-
85        ful  completion.  <STRONG>slk_attr</STRONG>  returns the attribute used for
86        the soft keys.
87
88        <STRONG>slk_label</STRONG> returns <STRONG>NULL</STRONG> on error.
89
90
91 </PRE>
92 <H2>NOTES</H2><PRE>
93        Most applications would use <STRONG>slk_noutrefresh</STRONG> because a <STRONG>wre-</STRONG>
94        <STRONG>fresh</STRONG> is likely to follow soon.
95
96
97 </PRE>
98 <H2>PORTABILITY</H2><PRE>
99        The  XSI  Curses  standard, Issue 4, describes these func-
100        tions.  It changes the argument  type  of  the  attribute-
101        manipulation     functions     <STRONG>slk_attron</STRONG>,    <STRONG>slk_attroff</STRONG>,
102        <STRONG>slk_attrset</STRONG> to be <STRONG>attr_t</STRONG>, and adds <STRONG>const</STRONG>  qualifiers.  The
103        format  codes  <STRONG>2</STRONG>  and  <STRONG>3</STRONG>  for  <STRONG>slk_init()</STRONG> and the function
104        <STRONG>slk_attr</STRONG> are specific to ncurses.
105
106
107 </PRE>
108 <H2>SEE ALSO</H2><PRE>
109        <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>,
110        <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3X)</A></STRONG>
111
112
113
114
115
116
117
118
119
120 </PRE>
121 </BODY>
122 </HTML>