Manual Pages for UNIX Darwin command on man can_change

Manual Pages for UNIX Darwin command on man can_change_color

curscolor(3X) curscolor(3X)

NAME

ssttaarrttccoolloorr, iinniittppaaiirr, iinniittccoolloorr, hhaassccoolloorrss, ccaanncchhaannggeeccoolloorr,

ccoolloorrccoonntteenntt, ppaaiirrccoonntteenntt, CCOOLLOORRPPAAIIRR - ccuurrsseess color manipulation

routines

SYNOPSIS

## iinncclluuddee <>

iinntt ssttaarrttccoolloorr((vvooiidd));; iinntt iinniittppaaiirr((sshhoorrtt ppaaiirr,, sshhoorrtt ff,, sshhoorrtt bb));; iinntt iinniittccoolloorr((sshhoorrtt ccoolloorr,, sshhoorrtt rr,, sshhoorrtt gg,, sshhoorrtt bb));; bbooooll hhaassccoolloorrss((vvooiidd));; bbooooll ccaanncchhaannggeeccoolloorr((vvooiidd));; iinntt ccoolloorrccoonntteenntt((sshhoorrtt ccoolloorr,, sshhoorrtt **rr,, sshhoorrtt **gg,, sshhoorrtt **bb));; iinntt ppaaiirrccoonntteenntt((sshhoorrtt ppaaiirr,, sshhoorrtt **ff,, sshhoorrtt **bb));;

DESCRIPTION

OOvveerrvviieeww ccuurrsseess support color attributes on terminals with that capability. To use these routines ssttaarrttccoolloorr must be called, usually right after

iinniittssccrr. Colors are always used in pairs (referred to as color-pairs).

A color-pair consists of a foreground color (for characters) and a

background color (for the blank field on which the characters are dis-

played). A programmer initializes a color-pair with the routine

iinniittppaaiirr. After it has been initialized, CCOOLLOORRPPAAIIRR(n), a macro de-

fined in <>, can be used as a new video attribute. If a termi-

nal is capable of redefining colors, the programmer can use the routine

iinniittccoolloorr to change the definition of a color. The routines hhaassccooll-

oorrss and ccaanncchhaannggeeccoolloorr return TTRRUUEE or FFAALLSSEE, depending on whether the terminal has color capabilities and whether the programmer can change the colors. The routine ccoolloorrccoonntteenntt allows a programmer to extract the amounts of red, green, and blue components in an initialized color. The routine ppaaiirrccoonntteenntt allows a programmer to find out how a given

color-pair is currently defined.

RRoouuttiinnee DDeessccrriippttiioonnss The ssttaarrttccoolloorr routine requires no arguments. It must be called if

the programmer wants to use colors, and before any other color manipu-

lation routine is called. It is good practice to call this routine right after iinniittssccrr. ssttaarrttccoolloorr initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global variables, CCOOLLOORRSS and CCOOLLOORRPPAAIIRRSS (respectively defining the

maximum number of colors and color-pairs the terminal can support). It

also restores the colors on the terminal to the values they had when the terminal was just turned on. The iinniittppaaiirr routine changes the

definition of a color-pair. It takes three arguments: the number of

the color-pair to be changed, the foreground color number, and the

background color number. For portable applications:

- The value of the first argument must be between 11 and CCOOLL-

OORRPPAAIIRRSS-11.

- The value of the second and third arguments must be between 0 and

CCOOLLOORRSS. Color pair 0 is assumed to be white on black, but is ac-

tually whatever the terminal implements before color is initial-

ized. It cannot be modified by the application.

If the color-pair was previously initialized, the screen is refreshed

and all occurrences of that color-pair are changed to the new defini-

tion. As an extension, ncurses allows you to set color pair 0 via the aassssuummeeddeeffaauullttccoolloorrss routine, or to specify the use of default colors

(color number -11) if you first invoke the uusseeddeeffaauullttccoolloorrss routine.

The iinniittccoolloorr routine changes the definition of a color. It takes four arguments: the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). The value of the first argument must be between 00 and CCOOLLOORRSS. (See the section CCoolloorrss for the default color index.) Each of the last three arguments must be a value between 0 and 1000. When iinniittccoolloorr is used, all occurrences of that color on the screen immediately change to the

new definition. The hhaassccoolloorrss routine requires no arguments. It re-

turns TTRRUUEE if the terminal can manipulate colors; otherwise, it returns

FFAALLSSEE. This routine facilitates writing terminal-independent programs.

For example, a programmer can use it to decide whether to use color or some other video attribute. The ccaanncchhaannggeeccoolloorr routine requires no arguments. It returns TTRRUUEE if the terminal supports colors and can

change their definitions; other, it returns FFAALLSSEE. This routine facil-

itates writing terminal-independent programs. The ccoolloorrccoonntteenntt rou-

tine gives programmers a way to find the intensity of the red, green, and blue (RGB) components in a color. It requires four arguments: the color number, and three addresses of sshhoorrtts for storing the information

about the amounts of red, green, and blue components in the given col-

or. The value of the first argument must be between 0 and CCOOLLOORRSS. The values that are stored at the addresses pointed to by the last three

arguments are between 0 (no component) and 1000 (maximum amount of com-

ponent). The ppaaiirrccoonntteenntt routine allows programmers to find out what

colors a given color-pair consists of. It requires three arguments:

the color-pair number, and two addresses of sshhoorrtts for storing the

foreground and the background color numbers. The value of the first

argument must be between 1 and CCOOLLOORRPPAAIIRRSS-11. The values that are

stored at the addresses pointed to by the second and third arguments are between 0 and CCOOLLOORRSS. CCoolloorrss In <> the following macros are defined. These are the default colors. ccuurrsseess also assumes that CCOOLLOORRBBLLAACCKK is the default background color for all terminals. CCOOLLOORRBBLLAACCKK CCOOLLOORRRREEDD CCOOLLOORRGGRREEEENN CCOOLLOORRYYEELLLLOOWW CCOOLLOORRBBLLUUEE CCOOLLOORRMMAAGGEENNTTAA CCOOLLOORRCCYYAANN CCOOLLOORRWWHHIITTEE RREETTUURRNN VVAALLUUEE The routines ccaanncchhaannggeeccoolloorr(()) and hhaassccoolloorrss(()) return TTRRUUEE or FFAALLSSEE. All other routines return the integer EERRRR upon failure and an OOKK (SVr4

specifies only "an integer value other than EERRRR") upon successful com-

pletion. X/Open defines no error conditions. This implementation will return

EERRRR on attempts to use color values outside the range 0 to COLORS-1

(except for the default colors extension), or use color pairs outside

the range 0 to COLORPAIR-1. Color values used in iinniittccoolloorr must be

in the range 0 to 1000. An error is returned from all functions if the terminal has not been initialized. An error is returned from secondary functions such as iinniittppaaiirr if ssttaarrttccoolloorr was not called. iinniittccoolloorr

returns an error if the terminal does not support this fea-

ture, e.g., if the initializecolor capability is absent from the terminal description. ssttaarrttccoolloorr returns an error If the color table cannot be allocated. NNOOTTEESS In the ncurses implementation, there is a separate color activation

flag, color palette, color pairs table, and associated COLORS and COL-

ORPAIRS counts for each screen; the ssttaarrttccoolloorr function only affects the current screen. The SVr4/XSI interface is not really designed with this in mind, and historical implementations may use a single shared color palette. Note that setting an implicit background color via a

color pair affects only character cells that a character write opera-

tion explicitly touches. To change the background color used when parts of a window are blanked by erasing or scrolling operations, see

ccuurrssbbkkggdd(3X). Several caveats apply on 386 and 486 machines with VGA-

compatible graphics:

- COLORYELLOW is actually brown. To get yellow, use COLORYELLOW

combined with the AABBOOLLDD attribute.

- The ABLINK attribute should in theory cause the background to go

bright. This often fails to work, and even some cards for which it mostly works (such as the Paradise and compatibles) do the wrong thing when you try to set a bright "yellow" background (you get a blinking yellow foreground instead).

- Color RGB values are not settable.

PPOORRTTAABBIILLIITTYY This implementation satisfies XSI Curses's minimum maximums for CCOOLLOORRSS and CCOOLLOORRPPAAIIRRSS.

The iinniittppaaiirr routine accepts negative values of foreground and back-

ground color to support the uusseeddeeffaauullttccoolloorrss extension, but only if that routine has been first invoked. The assumption that CCOOLLOORRBBLLAACCKK is the default background color for all terminals can be modified using the aassssuummeeddeeffaauullttccoolloorrss extension. This implementation checks the pointers, e.g., for the values returned

by ccoolloorrccoonntteenntt and ppaaiirrccoonntteenntt, and will treat those as optional pa-

rameters when null.