1.\" $NetBSD: curses_color.3,v 1.2 2002/10/21 14:17:54 wiz 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 October 13, 2002 32.Dt CURSES_COLOR 3 33.Os 34.Sh NAME 35.Nm curses_color , 36.Nm has_colors , 37.Nm can_change_colors , 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.Nd curses color manipulation routines 46.Sh LIBRARY 47.Lb libcurses 48.Sh SYNOPSIS 49.Fd #include \*[Lt]curses.h\*[Gt] 50.Ft bool 51.Fn has_colors void 52.Ft bool 53.Fn can_change_color void 54.Ft int 55.Fn start_color void 56.Ft int 57.Fn init_pair "short pair" "short fore" "short back" 58.Ft int 59.Fn pair_content "short pair" "short *fore" "short *back" 60.Ft int 61.Fn COLOR_PAIR "int n" 62.Ft int 63.Fn PAIR_NUMBER "int val" 64.Ft int 65.Fn init_color "short color" "short red" "short green" "short blue" 66.Ft int 67.Fn color_content "short color" "short *red" "short *green" "short *blue" 68.Ft extern int 69.Dv COLOR_PAIRS 70.Ft extern int 71.Dv 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_colors 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.Dv COLORS 107and 108.Dv COLOR_PAIRS . 109.Dv COLORS 110defines the number of colors that the terminal supports and 111.Dv 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 . 130.Pp 131The function 132.Fn pair_content pair *fore *back 133stores the foreground and background color numbers of color-pair 134.Fa pair 135in the variables 136.Fa fore 137and 138.Fa back , 139respectively. 140.Pp 141The macro 142.Fn COLOR_PAIR n 143gives the attribute value of color-pair number 144.Fa n . 145This is the value that is used to set the attribute of a character to this 146color-pair. 147For example, 148.Fo attrset 149.Fo COLOR_PAIR 150.Fa 2 151.Fc 152.Fc 153will display characters using color-pair 2. 154.Pp 155The macro 156.Fn PAIR_NUMBER val 157gives the color-pair number associated with the attribute value 158.Fa val . 159.Pp 160The function 161.Fn init_color color red green blue 162sets the red, green and blue intensity components of color 163.Fa color 164to the values 165.Fa red , 166.Fa green 167and 168.Fa blue , 169respectively. 170The minimum intensity value is 0 and the maximum intensity value is 1000. 171.Pp 172The function 173.Fn color_content color *red *green *blue 174stores the red, green and blue intensity components of color 175.Fa color 176in the variables 177.Fa red , 178.Fa green , 179and 180.Fa blue , 181respectively. 182.Sh RETURN VALUES 183The functions 184.Fn start_color , 185.Fn init_pair , 186.Fn pair_content , 187.Fn init_color 188and 189.Fn color_content 190return OK on success and ERR on failure. 191.Sh SEE ALSO 192.Xr curses_attributes 3 , 193.Xr curses_background 3 , 194.Xr curses_default_colors 3 195.Sh STANDARDS 196The 197.Nx 198Curses library complies with the X/Open Curses specification, part of the 199Single Unix Specification. 200.Sh HISTORY 201These functions first appeared in 202.Nx 1.5 . 203.Sh BUGS 204Changing the background or foreground color of color-pair 0 has no effect. 205