slk_restore(3xcurses)

1slk_attroff(3XCURSES)   X/Open Curses Library Functions  slk_attroff(3XCURSES)
2
3
4

NAME

6       slk_attroff,   slk_attr_off,   slk_attron,   slk_attr_on,  slk_attrset,
7       slk_attr_set, slk_clear, slk_color,  slk_init,  slk_label,  slk_noutre‐
8       fresh,  slk_refresh,  slk_restore,  slk_set, slk_touch, slk_wset - soft
9       label functions
10

SYNOPSIS

12       cc [ flag... ] file... -I /usr/xpg4/include  -L  /usr/xpg4/lib \
13        -R  /usr/xpg4/lib  -lcurses  [ library... ]
14
15       c89 [ flag... ] file... -lcurses [ library... ]
16
17       #include <curses.h>
18
19       int slk_attroff(const chtype attrs);
20
21
22       int slk_attr_off(const attr_t attrs, void *opts);
23
24
25       int slk_attron(const chtype attrs);
26
27
28       int slk_attr_on(const attr_t attrs, void *opts);
29
30
31       int slk_attrset(const chtype attrs);
32
33
34       int slk_attr_set(const attr_t attrs, short color_pair_number, void *opts);
35
36
37       int slk_clear(void);
38
39
40       int slk_color(short color_pair_number);
41
42
43       int slk_init(int fmt);
44
45
46       char *slk_label(int labnum);
47
48
49       int slk_noutrefresh(void);
50
51
52       int slk_refresh(void);
53
54
55       int slk_restore(void);
56
57
58       int slk_set(int labnum, const char *label, int justify);
59
60
61       int slk_touch(void);
62
63
64       int slk_wset(int labnum, const wchar_t *label, int justify);
65
66

PARAMETERS

68       attrs                are the window attributes to be added or removed.
69
70
71       opts                 Is reserved for future use. Currently,  this  must
72                            be a null pointer.
73
74
75       color_pair_number    Is a color pair.
76
77
78       fmt                  Is  the  format  of how the labels are arranged on
79                            the screen.
80
81
82       labnum               Is the number of the soft label.
83
84
85       label                Is the name to be given to a soft label.
86
87
88       justify              Is a number indicating how to  justify  the  label
89                            name.
90
91

DESCRIPTION

93       The  Curses  interface  manipulates the set of soft function-key labels
94       that exist on many terminals. For those terminals that do not have soft
95       labels,  Curses takes over the bottom line of stdscr, reducing the size
96       of stdscr and the value of the LINES external variable. There can be up
97       to eight labels of up to eight display columns each.
98
99
100       To   use   soft  labels,  slk_init()  must  be  called  before  calling
101       initscr(3XCURSES),  newterm(3XCURSES),  or   ripoffline(3XCURSES).   If
102       initscr()  eventually  uses  a  line  from  stdscr  to emulate the soft
103       labels, then fmt determines how the labels are arranged on the  screen.
104       Setting  fmt  to 0 indicates a 3-2-3 arrangement of the labels; 1 indi‐
105       cates a 4-4 arrangement. Other values for fmt are unspecified.
106
107
108       The slk_init() function has  the  effect  of  calling  ripoffline()  to
109       reserve one screen line to accommodate the requested format.
110
111
112       The  slk_set()  and slk_wset() functions specify the text of soft label
113       number labnum, within the range from 1 to and including  8.  The  label
114       argument  is  the  string  to  be  put  the  lable.  With slk_set() and
115       slk_wset(), the width of the label is limited to  eight  columns  posi‐
116       tions.  A  null  string  or a null pointer specifies a blank label. The
117       justify argument can have the following values to indicate how to  jus‐
118       tify label within the space reserved for it:
119
120       0    Align the start of label with the start of the space
121
122
123       1    Center label within the space
124
125
126       2    Align the end of label with the end of the space
127
128
129
130       The  slk_refresh()  and  slk_noutrefresh()  functions correspond to the
131       wrefresh(3XCURSES) and wnoutrefresh(3XCURSES) functions.
132
133
134       The slk_label() function obtains soft label number labnum.
135
136
137       The slk_clear() function immediately clears the soft  labels  from  the
138       screen.
139
140
141       The  slk_restore() function immediately restores the soft labels to the
142       screen after a call to slk_clear().
143
144
145       The slk_touch() function forces all the soft labels to  be  output  the
146       next time slk_refresh() or slk_noutrefresh() is called.
147
148
149       The slk_attron(), slk_attrset(), and slk_attroff() functions correspond
150       to the attron(3XCURSES), attrset(3XCURSES), and attroff(3XCURSES) func‐
151       tions.  They  have  an effect only if soft labels are stimulated on the
152       bottom line of the screen.
153
154
155       The slk_attr_on(), slk_attr_off(), slk_attr_set() and slk_color() func‐
156       tions   correspond   to   the   attr_on(3XCURSES),  attr_off(3XCURSES),
157       attr_set(3XCURSES), and color_set(3XCURSES)  functions.  As  a  result,
158       they support color and the attribute constants with the WA_ prefix.
159
160
161       The  opts argument is reserved for definition in a future release. Cur‐
162       rently, the opts argument is a null pointer.
163

RETURN VALUES

165        Upon successful  completion,  the  slk_label()  function  returns  the
166       requested  label  with leading and trailing blanks stripped. Otherwise,
167       it returns a null pointer.
168
169
170        Upon successful completion, the other functions return OK.  Otherwise,
171       they return ERR.
172

ERRORS

174       No errors are defined.
175

USAGE

177        When  using  multi-byte  character sets, applications should check the
178       width of the string  by  calling  mbstowcs(3C)  and  then  wcswidth(3C)
179       before  calling  slk_set().  When  using  wide characters, applications
180       should check the width of the string by calling wcswidth() before call‐
181       ing slk_set().
182
183
184       Since  the number of columns that a wide string will occupy is codeset-
185       specific, call wcwidth(3C) and wcswidth(3C) to check the number of col‐
186       umn positions in the string before calling slk_wset().
187
188
189        Most  applications would use slk_noutrefresh() because a wrefresh() is
190       likely to follow soon.
191

ATTRIBUTES

193       See attributes(5) for descriptions of the following attributes:
194
195
196
197
198       ┌─────────────────────────────┬─────────────────────────────┐
199       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
200       ├─────────────────────────────┼─────────────────────────────┤
201       │Interface Stability          │Standard                     │
202       ├─────────────────────────────┼─────────────────────────────┤
203       │MT-Level                     │Unsafe                       │
204       └─────────────────────────────┴─────────────────────────────┘
205