usr/src/man/man3xcurses/slk_attroff.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SLK_ATTROFF 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 slk_attroff, slk_attr_off, slk_attron, slk_attr_on, slk_attrset, slk_attr_set,
   9 slk_clear, slk_color, slk_init, slk_label, slk_noutrefresh, slk_refresh,
  10 slk_restore, slk_set, slk_touch, slk_wset \- soft label functions
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  15 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  16
  17 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  18
  19 #include <curses.h>
  20
  21 \fBint\fR \fBslk_attroff\fR(\fBconst chtype\fR \fIattrs\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBint\fR \fBslk_attr_off\fR(\fBconst attr_t\fR \fIattrs\fR, \fBvoid *\fR\fIopts\fR);
  27 .fi
  28
  29 .LP
  30 .nf
  31 \fBint\fR \fBslk_attron\fR(\fBconst chtype\fR \fIattrs\fR);
  32 .fi
  33
  34 .LP
  35 .nf
  36 \fBint\fR \fBslk_attr_on\fR(\fBconst attr_t\fR \fIattrs\fR, \fBvoid *\fR\fIopts\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBslk_attrset\fR(\fBconst chtype\fR \fIattrs\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBslk_attr_set\fR(\fBconst attr_t\fR \fIattrs\fR, \fBshort\fR \fIcolor_pair_number\fR, \fBvoid *\fR\fIopts\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBint\fR \fBslk_clear\fR(\fBvoid\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBint\fR \fBslk_color\fR(\fBshort\fR \fIcolor_pair_number\fR);
  57 .fi
  58
  59 .LP
  60 .nf
  61 \fBint\fR \fBslk_init\fR(\fBint\fR \fIfmt\fR);
  62 .fi
  63
  64 .LP
  65 .nf
  66 \fBchar *\fR\fBslk_label\fR(\fBint\fR \fIlabnum\fR);
  67 .fi
  68
  69 .LP
  70 .nf
  71 \fBint\fR \fBslk_noutrefresh\fR(\fBvoid\fR);
  72 .fi
  73
  74 .LP
  75 .nf
  76 \fBint\fR \fBslk_refresh\fR(\fBvoid\fR);
  77 .fi
  78
  79 .LP
  80 .nf
  81 \fBint\fR \fBslk_restore\fR(\fBvoid\fR);
  82 .fi
  83
  84 .LP
  85 .nf
  86 \fBint\fR \fBslk_set\fR(\fBint\fR \fIlabnum\fR, \fBconst char *\fR\fIlabel\fR, \fBint\fR \fIjustify\fR);
  87 .fi
  88
  89 .LP
  90 .nf
  91 \fBint\fR \fBslk_touch\fR(\fBvoid\fR);
  92 .fi
  93
  94 .LP
  95 .nf
  96 \fBint\fR \fBslk_wset\fR(\fBint\fR \fIlabnum\fR, \fBconst wchar_t *\fR\fIlabel\fR, \fBint\fR \fIjustify\fR);
  97 .fi
  98
  99 .SH PARAMETERS
 100 .sp
 101 .ne 2
 102 .na
 103 \fB\fIattrs\fR\fR
 104 .ad
 105 .RS 21n
 106 are the window attributes to be added or removed.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fIopts\fR\fR
 113 .ad
 114 .RS 21n
 115 Is reserved for future use. Currently, this must be a null pointer.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fIcolor_pair_number\fR\fR
 122 .ad
 123 .RS 21n
 124 Is a color pair.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fIfmt\fR\fR
 131 .ad
 132 .RS 21n
 133 Is the format of how the labels are arranged on the screen.
 134 .RE
 135
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fIlabnum\fR\fR
 140 .ad
 141 .RS 21n
 142 Is the number of the soft label.
 143 .RE
 144
 145 .sp
 146 .ne 2
 147 .na
 148 \fB\fIlabel\fR\fR
 149 .ad
 150 .RS 21n
 151 Is the name to be given to a soft label.
 152 .RE
 153
 154 .sp
 155 .ne 2
 156 .na
 157 \fB\fIjustify\fR\fR
 158 .ad
 159 .RS 21n
 160 Is a number indicating how to justify the label name.
 161 .RE
 162
 163 .SH DESCRIPTION
 164 .sp
 165 .LP
 166 The Curses interface manipulates the set of soft function-key labels that exist
 167 on many terminals. For those terminals that do not have soft labels, Curses
 168 takes over the bottom line of \fIstdscr\fR, reducing the size of \fIstdscr\fR
 169 and the value of the \fBLINES\fR external variable. There can be up to eight
 170 labels of up to eight display columns each.
 171 .sp
 172 .LP
 173 To use soft labels, \fBslk_init()\fR must be called before calling
 174 \fBinitscr\fR(3XCURSES), \fBnewterm\fR(3XCURSES), or
 175 \fBripoffline\fR(3XCURSES). If \fBinitscr()\fR eventually uses a line from
 176 \fIstdscr\fR to emulate the soft labels, then \fIfmt\fR determines how the
 177 labels are arranged on the screen. Setting \fIfmt\fR to 0 indicates a 3-2-3
 178 arrangement of the labels; 1 indicates a 4-4 arrangement. Other values for
 179 \fIfmt\fR are unspecified.
 180 .sp
 181 .LP
 182 The \fBslk_init()\fR function has the effect of calling \fBripoffline()\fR to
 183 reserve one screen line to accommodate the requested format.
 184 .sp
 185 .LP
 186 The \fBslk_set()\fR and \fBslk_wset()\fR functions specify the text of soft
 187 label number \fIlabnum\fR, within the range from 1 to and including 8. The
 188 \fIlabel\fR argument is the string to be put the lable. With \fBslk_set()\fR
 189 and \fBslk_wset()\fR, the width of the label is limited to eight columns
 190 positions. A null string or a null pointer specifies a blank label. The
 191 \fIjustify\fR argument can have the following values to indicate how to justify
 192 \fIlabel\fR within the space reserved for it:
 193 .sp
 194 .ne 2
 195 .na
 196 \fB0\fR
 197 .ad
 198 .RS 5n
 199 Align the start of \fIlabel\fR with the start of the space
 200 .RE
 201
 202 .sp
 203 .ne 2
 204 .na
 205 \fB1\fR
 206 .ad
 207 .RS 5n
 208 Center \fIlabel\fR within the space
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB2\fR
 215 .ad
 216 .RS 5n
 217 Align the end of \fIlabel\fR with the end of the space
 218 .RE
 219
 220 .sp
 221 .LP
 222 The \fBslk_refresh()\fR and \fBslk_noutrefresh()\fR functions correspond to the
 223 \fBwrefresh\fR(3XCURSES) and \fBwnoutrefresh\fR(3XCURSES) functions.
 224 .sp
 225 .LP
 226 The \fBslk_label()\fR function obtains soft label number \fIlabnum\fR.
 227 .sp
 228 .LP
 229 The \fBslk_clear()\fR function immediately clears the soft labels from the
 230 screen.
 231 .sp
 232 .LP
 233 The \fBslk_restore()\fR function immediately restores the soft labels to the
 234 screen after a call to \fBslk_clear()\fR.
 235 .sp
 236 .LP
 237 The \fBslk_touch()\fR function forces all the soft labels to be output the next
 238 time \fBslk_refresh()\fR or \fBslk_noutrefresh()\fR is called.
 239 .sp
 240 .LP
 241 The \fBslk_attron()\fR, \fBslk_attrset()\fR, and \fBslk_attroff()\fR functions
 242 correspond to the \fBattron\fR(3XCURSES), \fBattrset\fR(3XCURSES), and
 243 \fBattroff\fR(3XCURSES) functions. They have an effect only if soft labels are
 244 stimulated on the bottom line of the screen.
 245 .sp
 246 .LP
 247 The \fBslk_attr_on()\fR, \fBslk_attr_off()\fR, \fBslk_attr_set()\fR and
 248 \fBslk_color()\fR functions correspond to the \fBattr_on\fR(3XCURSES),
 249 \fBattr_off\fR(3XCURSES), \fBattr_set\fR(3XCURSES), and
 250 \fBcolor_set\fR(3XCURSES) functions. As a result, they support color and the
 251 attribute constants with the \fBWA_\fR prefix.
 252 .sp
 253 .LP
 254 The \fIopts\fR argument is reserved for definition in a future release.
 255 Currently, the \fIopts\fR argument is a null pointer.
 256 .SH RETURN VALUES
 257 .sp
 258 .LP
 259  Upon successful completion, the \fBslk_label()\fR function returns the
 260 requested label with leading and trailing blanks stripped. Otherwise, it
 261 returns a null pointer.
 262 .sp
 263 .LP
 264  Upon successful completion, the other functions return \fBOK\fR. Otherwise,
 265 they return \fBERR\fR.
 266 .SH ERRORS
 267 .sp
 268 .LP
 269 No errors are defined.
 270 .SH USAGE
 271 .sp
 272 .LP
 273  When using multi-byte character sets, applications should check the width of
 274 the string by calling \fBmbstowcs\fR(3C) and then \fBwcswidth\fR(3C) before
 275 calling \fBslk_set()\fR. When using wide characters, applications should check
 276 the width of the string by calling \fBwcswidth()\fR before calling
 277 \fBslk_set()\fR.
 278 .sp
 279 .LP
 280 Since the number of columns that a wide string will occupy is codeset-specific,
 281 call \fBwcwidth\fR(3C) and \fBwcswidth\fR(3C) to check the number of column
 282 positions in the string before calling \fBslk_wset()\fR.
 283 .sp
 284 .LP
 285  Most applications would use \fBslk_noutrefresh()\fR because a \fBwrefresh()\fR
 286 is likely to follow soon.
 287 .SH ATTRIBUTES
 288 .sp
 289 .LP
 290 See \fBattributes\fR(5) for descriptions of the following attributes:
 291 .sp
 292
 293 .sp
 294 .TS
 295 box;
 296 c | c
 297 l | l .
 298 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 299 _
 300 Interface Stability     Standard
 301 _
 302 MT-Level        Unsafe
 303 .TE
 304
 305 .SH SEE ALSO
 306 .sp
 307 .LP
 308 \fBattr_get\fR(3XCURSES), \fBattroff\fR(3XCURSES), \fBdelscreen\fR(3XCURSES),
 309 \fBlibcurses\fR(3XCURSES), \fBmbstowcs\fR(3C), \fBripoffline\fR(3XCURSES),
 310 \fBwcswidth\fR(3C), \fBwcwidth\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)