usr/src/man/man3xcurses/vidattr.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 VIDATTR 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 vidattr, vid_attr, vidputs, vid_puts \- output attributes to the terminal
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <curses.h>
  18
  19 \fBint\fR \fBvidattr\fR(\fBchtype\fR \fIattr\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBvid_attr\fR(\fBattr_t\fR \fIattr\fR, \fBshort\fR \fIcolor_pair_number\fR, \fBvoid *\fR\fIopt\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBvidputs\fR(\fBchtype\fR \fIattr\fR, \fBint (*\fR\fIputfunc\fR) (int));
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBvid_puts\fR(\fBattr_t\fR \fIattr\fR, \fBshort\fR \fIcolor_pair_number\fR, \fBvoid *\fR\fIopt\fR,
  35      \fBint (*\fR\fIputfunc\fR) (int));
  36 .fi
  37
  38 .SH PARAMETERS
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIattr\fR\fR
  43 .ad
  44 .RS 21n
  45 Is the rendition of the foreground window.
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIcolor_pair_number\fR\fR
  52 .ad
  53 .RS 21n
  54 Is a color pair.
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIopt\fR\fR
  61 .ad
  62 .RS 21n
  63 Is reserved for future use.  Currently, this must be a null pointer.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIputfunc\fR\fR
  70 .ad
  71 .RS 21n
  72 Is a user-supplied output function.
  73 .RE
  74
  75 .SH DESCRIPTION
  76 .sp
  77 .LP
  78 These functions output commands to the terminal that change the terminal's
  79 attributes.
  80 .sp
  81 .LP
  82 If the \fBterminfo\fR database indicates that the terminal in use can display
  83 characters in the rendition specified by \fIattr\fR, then \fBvidattr()\fR
  84 outputs one or more commands to request that the terminal display subsequent
  85 characters in that rendition. The function outputs by calling
  86 \fBputchar\fR(3C). The \fBvidattr()\fR function neither relies on your updates
  87 the model which Curses maintains of the prior rendition mode.
  88 .sp
  89 .LP
  90 The \fBvidputs()\fR function computes the terminal output string that
  91 \fBvidattr()\fR does, based on \fIattr\fR, but \fBvidputs()\fR outputs by
  92 calling the user-supplied function \fIputfunc\fR. The \fBvid_attr()\fR and
  93 \fBvid_puts()\fR functions correspond to \fBvidattr()\fR and \fBvidputs()\fR
  94 respectively, but take a set of arguments, one of type \fBattr_t\fR for the
  95 attributes, one of type \fBshort\fR for the color pair number, and a \fBvoid
  96 *\fR, and thus support the attribute constants with the \fBWA_\fR prefix.
  97 .sp
  98 .LP
  99 The \fIopts\fR argument is reserved for definition in a future release.
 100 Currently, it is implemented as a null pointer.
 101 .sp
 102 .LP
 103 The user-supplied function \fIputfunc\fR (which can be specified as an argument
 104 to either \fBvidputs()\fR or \fBvid_puts()\fR) is either \fBputchar()\fR or
 105 some other function with the same prototype.  Both the \fBvidputs()\fR and
 106 \fBvid_puts()\fR functions ignore the return value of \fIputfunc\fR.
 107 .SH RETURN VALUES
 108 .sp
 109 .LP
 110 Upon successful completion, these functions return \fBOK\fR. Otherwise, they
 111 return \fBERR\fR.
 112 .SH ERRORS
 113 .sp
 114 .LP
 115 No errors are defined.
 116 .SH  USAGE
 117 .sp
 118 .LP
 119 After use of any of these functions, the model Curses maintains of the state of
 120 the terminal might not match the actual state of the terminal. The application
 121 should touch and refresh the window before resuming conventional use of Curses.
 122 .sp
 123 .LP
 124 Of these functions requires that the application contain so much information
 125 about a particular class of terminal that it defeats the purpose of using
 126 Curses.
 127 .sp
 128 .LP
 129 On some terminals, a command to change rendition conceptually occupies space in
 130 the screen buffer (with or without width). Thus, a command to set the terminal
 131 to a new rendition would change the rendition of some characters already
 132 displayed.
 133 .SH ATTRIBUTES
 134 .sp
 135 .LP
 136 See \fBattributes\fR(5) for descriptions of the following attributes:
 137 .sp
 138
 139 .sp
 140 .TS
 141 box;
 142 c | c
 143 l | l .
 144 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 145 _
 146 Interface Stability     Standard
 147 _
 148 MT-Level        Unsafe
 149 .TE
 150
 151 .SH SEE ALSO
 152 .sp
 153 .LP
 154 \fBdoupdate\fR(3XCURSES), \fBis_linetouched\fR(3XCURSES),
 155 \fBlibcurses\fR(3XCURSES), \fBputchar\fR(3C), \fBtigetflag\fR(3XCURSES),
 156 \fBattributes\fR(5), \fBstandards\fR(5)