1.\" $NetBSD: curses_color.3,v 1.12 2009/07/22 16:57:14 roy 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 73These functions manipulate color on terminals that support color attributes. 74.Pp 75The function 76.Fn has_colors 77indicates whether a terminal is capable of displaying color attributes. 78It returns 79.Dv TRUE 80if the terminal is capable of displaying color attributes and 81.Dv FALSE 82otherwise. 83.Pp 84The function 85.Fn can_change_color 86indicates whether a terminal is capable of redefining colors. 87It returns 88.Dv TRUE 89if colors can be redefined and 90.Dv FALSE 91if they can not. 92.Pp 93The function 94.Fn start_color 95initializes the curses color support on a terminal. 96It must be called before any color manipulation functions are called on that 97terminal. 98The function initializes the eight basic colors (black, red, green, yellow, 99blue, magenta, cyan and white) that are specified using the color macros 100(such as 101.Dv COLOR_BLACK ) 102defined in 103.Em \*[Lt]curses.h\*[Gt] . 104.Fn start_color 105also initializes the global external variables 106.Va COLORS 107and 108.Va COLOR_PAIRS . 109.Va COLORS 110defines the number of colors that the terminal supports and 111.Va COLOR_PAIRS 112defines the number of color-pairs that the terminal supports. 113These color-pairs are initialized to white foreground on black background. 114.Fn start_color 115sets the colors on the terminal to the curses defaults of white 116foreground on black background unless the functions 117.Fn assume_default_colors 118or 119.Fn use_default_colors 120have been called previously. 121.Pp 122The function 123.Fn init_pair pair fore back 124sets foreground color 125.Fa fore 126and background color 127.Fa back 128for color-pair number 129.Fa pair . 130The valid range for the color-pair 131.Fa pair 132is from 1 to 133.Va COLOR_PAIRS 134\&- 1 135and the valid range for the colors is any number less than 136.Va COLORS . 137Specifying a negative number will set that color to the default foreground 138or background color. 139The 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 150Color-pair 0 is used as the default color pair, so changing this will 151have no effect. 152Use the function 153.Fn assume_default_colors 154to change the default colors. 155.Pp 156The function 157.Fn pair_content pair *fore *back 158stores the foreground and background color numbers of color-pair 159.Fa pair 160in the variables 161.Fa fore 162and 163.Fa back , 164respectively. 165.Pp 166The macro 167.Fn COLOR_PAIR n 168gives the attribute value of color-pair number 169.Fa n . 170This is the value that is used to set the attribute of a character to this 171color-pair. 172For example, 173.Dl attrset(COLOR_PAIR(2)) 174will display characters using color-pair 2. 175.Pp 176The macro 177.Fn PAIR_NUMBER val 178gives the color-pair number associated with the attribute value 179.Fa val . 180.Pp 181The function 182.Fn init_color color red green blue 183sets the red, green and blue intensity components of color 184.Fa color 185to the values 186.Fa red , 187.Fa green 188and 189.Fa blue , 190respectively. 191The minimum intensity value is 0 and the maximum intensity value is 1000. 192.Pp 193The function 194.Fn color_content color *red *green *blue 195stores the red, green and blue intensity components of color 196.Fa color 197in the variables 198.Fa red , 199.Fa green , 200and 201.Fa blue , 202respectively. 203.Pp 204The function 205.Fn no_color_attributes 206returns those attributes that a terminal is unable to combine with color. 207.Sh RETURN VALUES 208The functions 209.Fn start_color , 210.Fn init_pair , 211.Fn pair_content , 212.Fn init_color 213and 214.Fn color_content 215return 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 221The 222.Nx 223Curses library complies with the X/Open Curses specification, part of the 224Single Unix Specification. 225.Pp 226The function 227.Fn no_color_attributes 228and the use of negative color numbers 229are extensions to the X/Open Curses specification. 230.Sh HISTORY 231These functions first appeared in 232.Nx 1.5 . 233