1.\" $NetBSD: curses_color.3,v 1.5 2003/04/16 13:35:00 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 January 27, 2003 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 . 133.Pp 134The function 135.Fn pair_content pair *fore *back 136stores the foreground and background color numbers of color-pair 137.Fa pair 138in the variables 139.Fa fore 140and 141.Fa back , 142respectively. 143.Pp 144The macro 145.Fn COLOR_PAIR n 146gives the attribute value of color-pair number 147.Fa n . 148This is the value that is used to set the attribute of a character to this 149color-pair. 150For example, 151.Fo attrset 152.Fo COLOR_PAIR 153.Fa 2 154.Fc 155.Fc 156will display characters using color-pair 2. 157.Pp 158The macro 159.Fn PAIR_NUMBER val 160gives the color-pair number associated with the attribute value 161.Fa val . 162.Pp 163The function 164.Fn init_color color red green blue 165sets the red, green and blue intensity components of color 166.Fa color 167to the values 168.Fa red , 169.Fa green 170and 171.Fa blue , 172respectively. 173The minimum intensity value is 0 and the maximum intensity value is 1000. 174.Pp 175The function 176.Fn color_content color *red *green *blue 177stores the red, green and blue intensity components of color 178.Fa color 179in the variables 180.Fa red , 181.Fa green , 182and 183.Fa blue , 184respectively. 185.Pp 186The function 187.Fn no_color_video 188returns those attributes that a terminal is unable to combine with color. 189.Sh RETURN VALUES 190The functions 191.Fn start_color , 192.Fn init_pair , 193.Fn pair_content , 194.Fn init_color 195and 196.Fn color_content 197return OK on success and ERR on failure. 198.Sh SEE ALSO 199.Xr curses_attributes 3 , 200.Xr curses_background 3 , 201.Xr curses_default_colors 3 202.Sh STANDARDS 203The 204.Nx 205Curses library complies with the X/Open Curses specification, part of the 206Single Unix Specification. 207.Pp 208The function 209.Fn no_color_video 210is an extension to the X/Open Curses specification. 211.Sh HISTORY 212These functions first appeared in 213.Nx 1.5 . 214.Sh BUGS 215Changing the background or foreground color of color-pair 0 has no effect. 216