usr/src/man/man3curses/curs_slk.3curses

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH CURS_SLK 3CURSES "Dec 31, 1996"
   8 .SH NAME
   9 curs_slk, slk_init, slk_set, slk_refresh, slk_noutrefresh, slk_label,
  10 slk_clear, slk_restore, slk_touch, slk_attron, slk_attrset, slk_attroff \-
  11 curses soft label routines
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lcurses\fR [ \fIlibrary\fR ... ]
  16 #include <curses.h>
  17
  18 \fBint\fR \fBslk_init\fR(\fBint\fR \fIfmt\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBslk_set\fR(\fBint\fR \fIlabnum\fR, \fBchar *\fR\fIlabel\fR, \fBint\fR \fIfmt\fR);
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBslk_refresh\fR(\fBvoid\fR);
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBint\fR \fBslk_noutrefresh\fR(\fBvoid\fR);
  34 .fi
  35
  36 .LP
  37 .nf
  38 \fBchar *\fR\fBslk_label\fR(\fBint\fR \fIlabnum\fR);
  39 .fi
  40
  41 .LP
  42 .nf
  43 \fBint\fR \fBslk_clear\fR(\fBvoid\fR);
  44 .fi
  45
  46 .LP
  47 .nf
  48 \fBint\fR \fBslk_restore\fR(\fBvoid\fR);
  49 .fi
  50
  51 .LP
  52 .nf
  53 \fBint\fR \fBslk_touch\fR(\fBvoid\fR);
  54 .fi
  55
  56 .LP
  57 .nf
  58 \fBint\fR \fBslk_attron\fR(\fBchtype\fR \fIattrs\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBint\fR \fBslk_attrset\fR(\fBchtype\fR \fIattrs\fR);
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBint\fR \fBslk_attroff\fR(\fBchtype\fR \fIattrs\fR);
  69 .fi
  70
  71 .SH DESCRIPTION
  72 .sp
  73 .LP
  74 \fBcurses\fR manipulates the set of soft function-key labels that exist on many
  75 terminals. For those terminals that do not have soft labels, \fBcurses\fR takes
  76 over the bottom line of \fBstdscr\fR, reducing the size of \fBstdscr\fR and the
  77 variable \fBLINES\fR. \fBcurses\fR standardizes on eight labels of up to eight
  78 characters each.
  79 .sp
  80 .LP
  81 To use soft labels, the \fBslk_init()\fR routine must be called before
  82 \fBinitscr()\fR or \fBnewterm()\fR is called. If \fBinitscr()\fR eventually
  83 uses a line from \fBstdscr\fR to emulate the soft labels, then \fBfmt\fR
  84 determines how the labels are arranged on the screen. Setting \fBfmt\fR to
  85 \fB0\fR indicates a 3-2-3 arrangement of the labels; \fB1\fR indicates a 4-4
  86 arrangement.
  87 .sp
  88 .LP
  89 With the \fBslk_set()\fR routine, \fIlabnum\fR is the label number, from
  90 \fB1\fR to \fB8\fR. \fIlabel\fR is the string to be put on the label, up to
  91 eight characters in length. A null string or a null pointer sets up a blank
  92 label. \fBfmt\fR is either \fB0\fR, \fB1\fR, or \fB2\fR, indicating whether the
  93 label is to be left-justified, centered, or right-justified, respectively,
  94 within the label.
  95 .sp
  96 .LP
  97 The \fBslk_refresh()\fR and \fBslk_noutrefresh()\fR routines correspond to the
  98 \fBwrefresh()\fR and \fBwnoutrefresh()\fR routines.
  99 .sp
 100 .LP
 101 With the \fBslk_label()\fR routine, the current label for label number
 102 \fIlabnum\fR is returned with leading and trailing blanks stripped.
 103 .sp
 104 .LP
 105 With the \fBslk_clear()\fR routine, the soft labels are cleared from the
 106 screen.
 107 .sp
 108 .LP
 109 With the \fBslk_restore()\fR routine, the soft labels are restored to the
 110 screen after a \fBslk_clear()\fR is performed.
 111 .sp
 112 .LP
 113 With the \fBslk_touch()\fR routine, all the soft labels are forced to be output
 114 the next time a \fBslk_noutrefresh()\fR is performed.
 115 .sp
 116 .LP
 117 The \fBslk_attron()\fR, \fBslk_attrset()\fR, and \fBslk_attroff()\fR routines
 118 correspond to \fBattron()\fR, \fBattrset()\fR, and \fBattroff()\fR. They have
 119 an effect only if soft labels are simulated on the bottom line of the screen.
 120 .SH RETURN VALUES
 121 .sp
 122 .LP
 123 Routines that return an integer return \fBERR\fR upon failure and an integer
 124 value other than \fBERR\fR upon successful completion.
 125 .sp
 126 .LP
 127 \fBslk_label()\fR returns \fINULL\fR on error.
 128 .SH ATTRIBUTES
 129 .sp
 130 .LP
 131 See \fBattributes\fR(5) for descriptions of the following attributes:
 132 .sp
 133
 134 .sp
 135 .TS
 136 box;
 137 c | c
 138 l | l .
 139 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 140 _
 141 MT-Level        Unsafe
 142 .TE
 143
 144 .SH SEE ALSO
 145 .sp
 146 .LP
 147 \fBcurs_attr\fR(3CURSES), \fBcurs_initscr\fR(3CURSES),
 148 \fBcurs_refresh\fR(3CURSES), \fBcurses\fR(3CURSES), \fBattributes\fR(5)
 149 .SH NOTES
 150 .sp
 151 .LP
 152 The header <\fBcurses.h\fR> automatically includes the headers  <\fBstdio.h\fR>
 153 and <\fBunctrl.h\fR>.
 154 .sp
 155 .LP
 156 Most applications would use \fBslk_noutrefresh()\fR because a \fBwrefresh()\fR
 157 is likely to follow soon.