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