lib/libcurses/curses_color.3

   1 .\"     $NetBSD: curses_color.3,v 1.11 2008/04/30 13:10:51 martin Exp $
   2 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Julian Coleman.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd July 20, 2009
  29 .Dt CURSES_COLOR 3
  30 .Os
  31 .Sh NAME
  32 .Nm curses_color ,
  33 .Nm has_colors ,
  34 .Nm can_change_color ,
  35 .Nm start_color ,
  36 .Nm init_pair ,
  37 .Nm pair_content ,
  38 .Nm COLOR_PAIR ,
  39 .Nm PAIR_NUMBER ,
  40 .Nm init_color ,
  41 .Nm color_content ,
  42 .Nm no_color_attributes
  43 .Nd curses color manipulation routines
  44 .Sh LIBRARY
  45 .Lb libcurses
  46 .Sh SYNOPSIS
  47 .In curses.h
  48 .Ft bool
  49 .Fn has_colors void
  50 .Ft bool
  51 .Fn can_change_color void
  52 .Ft int
  53 .Fn start_color void
  54 .Ft int
  55 .Fn init_pair "short pair" "short fore" "short back"
  56 .Ft int
  57 .Fn pair_content "short pair" "short *fore" "short *back"
  58 .Ft int
  59 .Fn COLOR_PAIR "int n"
  60 .Ft int
  61 .Fn PAIR_NUMBER "int val"
  62 .Ft int
  63 .Fn init_color "short color" "short red" "short green" "short blue"
  64 .Ft int
  65 .Fn color_content "short color" "short *red" "short *green" "short *blue"
  66 .Ft attr_t
  67 .Fn no_color_attributes void
  68 .Pp
  69 .Va extern int COLOR_PAIRS ;
  70 .Pp
  71 .Va extern int COLORS ;
  72 .Sh DESCRIPTION
  73 These functions manipulate color on terminals that support color attributes.
  74 .Pp
  75 The function
  76 .Fn has_colors
  77 indicates whether a terminal is capable of displaying color attributes.
  78 It returns
  79 .Dv TRUE
  80 if the terminal is capable of displaying color attributes and
  81 .Dv FALSE
  82 otherwise.
  83 .Pp
  84 The function
  85 .Fn can_change_color
  86 indicates whether a terminal is capable of redefining colors.
  87 It returns
  88 .Dv TRUE
  89 if colors can be redefined and
  90 .Dv FALSE
  91 if they can not.
  92 .Pp
  93 The function
  94 .Fn start_color
  95 initializes the curses color support on a terminal.
  96 It must be called before any color manipulation functions are called on that
  97 terminal.
  98 The function initializes the eight basic colors (black, red, green, yellow,
  99 blue, magenta, cyan and white) that are specified using the color macros
 100 (such as
 101 .Dv COLOR_BLACK )
 102 defined in
 103 .Em \*[Lt]curses.h\*[Gt] .
 104 .Fn start_color
 105 also initializes the global external variables
 106 .Va COLORS
 107 and
 108 .Va COLOR_PAIRS .
 109 .Va COLORS
 110 defines the number of colors that the terminal supports and
 111 .Va COLOR_PAIRS
 112 defines the number of color-pairs that the terminal supports.
 113 These color-pairs are initialized to white foreground on black background.
 114 .Fn start_color
 115 sets the colors on the terminal to the curses defaults of white
 116 foreground on black background unless the functions
 117 .Fn assume_default_colors
 118 or
 119 .Fn use_default_colors
 120 have been called previously.
 121 .Pp
 122 The function
 123 .Fn init_pair pair fore back
 124 sets foreground color
 125 .Fa fore
 126 and background color
 127 .Fa back
 128 for color-pair number
 129 .Fa pair .
 130 The valid range for the color-pair
 131 .Fa pair
 132 is from 1 to
 133 .Va COLOR_PAIRS
 134 \&- 1
 135 and the valid range for the colors is any number less than
 136 .Va COLORS .
 137 Specifying a negative number will set that color to the default foreground
 138 or background color.
 139 The 8 initial colors are defined as:
 140 .Bl -tag -width "COLOR_MAGENTA" -compact -offset indent
 141 .It COLOR_BLACK
 142 .It COLOR_RED
 143 .It COLOR_GREEN
 144 .It COLOR_YELLOW
 145 .It COLOR_BLUE
 146 .It COLOR_MAGENTA
 147 .It COLOR_CYAN
 148 .It COLOR_WHITE
 149 .El
 150 Color-pair 0 is used as the default color pair, so changing this will
 151 have no effect.
 152 Use the function
 153 .Fn assume_default_colors
 154 to change the default colors.
 155 .Pp
 156 The function
 157 .Fn pair_content pair *fore *back
 158 stores the foreground and background color numbers of color-pair
 159 .Fa pair
 160 in the variables
 161 .Fa fore
 162 and
 163 .Fa back ,
 164 respectively.
 165 .Pp
 166 The macro
 167 .Fn COLOR_PAIR n
 168 gives the attribute value of color-pair number
 169 .Fa n .
 170 This is the value that is used to set the attribute of a character to this
 171 color-pair.
 172 For example,
 173 .Dl attrset(COLOR_PAIR(2))
 174 will display characters using color-pair 2.
 175 .Pp
 176 The macro
 177 .Fn PAIR_NUMBER val
 178 gives the color-pair number associated with the attribute value
 179 .Fa val .
 180 .Pp
 181 The function
 182 .Fn init_color color red green blue
 183 sets the red, green and blue intensity components of color
 184 .Fa color
 185 to the values
 186 .Fa red ,
 187 .Fa green
 188 and
 189 .Fa blue ,
 190 respectively.
 191 The minimum intensity value is 0 and the maximum intensity value is 1000.
 192 .Pp
 193 The function
 194 .Fn color_content color *red *green *blue
 195 stores the red, green and blue intensity components of color
 196 .Fa color
 197 in the variables
 198 .Fa red ,
 199 .Fa green ,
 200 and
 201 .Fa blue ,
 202 respectively.
 203 .Pp
 204 The function
 205 .Fn no_color_attributes
 206 returns those attributes that a terminal is unable to combine with color.
 207 .Sh RETURN VALUES
 208 The functions
 209 .Fn start_color ,
 210 .Fn init_pair ,
 211 .Fn pair_content ,
 212 .Fn init_color
 213 and
 214 .Fn color_content
 215 return OK on success and ERR on failure.
 216 .Sh SEE ALSO
 217 .Xr curses_attributes 3 ,
 218 .Xr curses_background 3 ,
 219 .Xr curses_default_colors 3
 220 .Sh STANDARDS
 221 The
 222 .Nx
 223 Curses library complies with the X/Open Curses specification, part of the
 224 Single Unix Specification.
 225 .Pp
 226 The function
 227 .Fn no_color_attributes
 228 and the use of negative color numbers
 229 are extensions to the X/Open Curses specification.
 230 .Sh HISTORY
 231 These functions first appeared in
 232 .Nx 1.5 .