can_change_color(3xcurses)

1can_change_color(3XCURSESX)/Open Curses Library Functiocnasn_change_color(3XCURSES)
2
3
4

NAME

6       can_change_color,  color_content,  COLOR_PAIR,  has_colors, init_color,
7       init_pair, pair_content, PAIR_NUMBER, start_color, COLOR_PAIRS,  COLORS
8       - manipulate color information
9

SYNOPSIS

11       cc [ flag... ] file... -I /usr/xpg4/include  -L  /usr/xpg4/lib \
12        -R  /usr/xpg4/lib  -lcurses  [ library... ]
13
14       c89 [ flag... ] file... -lcurses [ library... ]
15
16       #include <curses.h>
17
18       bool can_change_color(void);
19
20
21       int color_content(short color, short *red, short *green, short *blue);
22
23
24       int COLOR_PAIR(int n);
25
26
27       bool has_colors(void);
28
29
30       int init_color(short color, short red, short green, short blue);
31
32
33       int init_pair(short pair, short f, short b);
34
35
36       int pair_content(short pair, short *f, short *b);
37
38
39       int PAIR_NUMBER(int value);
40
41
42       int start_color(voidextern int COLOR_PAIRS;
43
44       extern int COLORS;
45
46

DESCRIPTION

48       These functions manipulate color on terminals that support color.
49
50    Querying Capabilities
51       The  has_colors()  function  indicates  whether the terminal is a color
52       terminal. The can_change_color() function indicates whether the  termi‐
53       nal is a color terminal on which colors can be redefined.
54
55   Initialization
56       The  start_color()  function must be called to enable use of colors and
57       before any color manipulation function is called. The function initial‐
58       izes  eight  basic  colors  (black,  red, green, yellow, blue, magenta,
59       cyan, and white) that can be specified by the  color  macros  (such  as
60       COLOR_BLACK)  defined  in  <curses.h>.  The initial appearance of these
61       colors is unspecified.
62
63
64       The function also initializes two global external variables:
65
66           o      COLORS defines the number of colors that the  terminal  sup‐
67                  ports.  See  Color Identification below. If COLORS is 0, the
68                  terminal  does  not  support  redefinition  of  colors   and
69                  can_change_color() will return FALSE.
70
71           o      COLOR_PAIRS  defines  the maximum number of color-pairs that
72                  the terminal supports. See User-defined Color Pairs below.
73
74
75       The start_color() function also restores the colors on the terminal  to
76       terminal-specific  initial  values.  The  initial  background  color is
77       assumed to be black for all terminals.
78
79   Color Identification
80       The init_color() function redefines color number  color,  on  terminals
81       that  support  the  redefinition of colors, to have the red, green, and
82       blue intensity components specified by red, green,  and  blue,  respec‐
83       tively. Calling init_color() also changes all occurrences of the speci‐
84       fied color on the screen to the new definition.
85
86
87       The color_content() function identifies  the  intensity  components  of
88       color number color. It stores the red, green, and blue intensity compo‐
89       nents of this color in the addresses pointed  to  by  red,  green,  and
90       blue, respectively.
91
92
93       For  both  functions, the color argument must be in the range from 0 to
94       and including COLORS−1. Valid intensity value range from 0  (no  inten‐
95       sity  component)  up  to  and including 1000 (maximum intensity in that
96       component).
97
98   User-defined Color Pairs
99       Calling init_pair() defines or redefines color-pair number pair to have
100       foreground  color f and background color b. Calling init_pair() changes
101       any characters that were displayed in the color pair's  old  definition
102       to the new definition and refreshes the screen.
103
104
105       After  defining  the  color  pair,  the macro COLOR_PAIR(n) returns the
106       value of color pair n. This value is the color attribute as it would be
107       extracted  from  a  chtype.  Controversy, the macro COLOR_NUMBER(value)
108       returns the color pair  number  associated  with  the  color  attribute
109       value.
110
111
112       The  pair_content() retrieves the component colors of a color-pair num‐
113       ber pair. It stores the foreground and background color numbers in  the
114       variables pointed to by f and b, respectively.
115
116
117       With  init_pair()  and  pair_content(),  the value of pair must be in a
118       range from 0 to and including COLOR_PAIRS−1. Valid values for f  and  b
119       are the range from 0 to and including COLORS−1.
120

PARAMETERS

122       color    Is the number of the color for which to provide information (0
123                to  COLORS−1).
124
125
126       red      Is a pointer to the RGB value for the amount of red in color.
127
128
129       green    Is a pointer to the RGB value  for  the  amount  of  green  in
130                color.
131
132
133       blue     Is a pointer to the RGB value for the amount of blue in color.
134
135
136       n        Is the number of a color pair.
137
138
139       pair     Is  the number of the color pair for which to provide informa‐
140                tion (1 to  COLOR_PAIRS−1).
141
142
143       f        Is a pointer to the number of the foreground color (0 to  COL‐
144                ORS−1) in pair.
145
146
147       b        Is  a pointer to the number of the background color (0 to COL‐
148                ORS−1) in  pair.
149
150
151       value    Is a color attribute value.
152
153

RETURN VALUES

155       The has_colors() function returns TRUE if the terminal  can  manipulate
156       colors. Otherwise, it returns FALSE.
157
158
159       The  can_change_color() function returns TRUE if the terminal  supports
160       colors and is able to change their definitions. Otherwise,  it  returns
161       FALSE.
162
163
164       Upon  successful  completion, the other functions return OK. Otherwise,
165       they return ERR.
166

ERRORS

168       No errors are defined.
169

USAGE

171       To use these functions, start_color() must  be  called,  usually  right
172       after initscr(3XCURSES).
173
174
175       The  can_change_color()  and  has_colors() functions facilitate writing
176       terminal-independent applications. For example, a  programmer  can  use
177       them to decide whether to use color or some other video attribute.
178
179
180       On  color terminals, a typical value of COLORS is 8 and the macros such
181       as COLOR_BLACK return a value within the range from 0 to and  including
182       7. However, applications cannot rely on this to be true.
183

ATTRIBUTES

185       See attributes(5) for descriptions of the following attributes:
186
187
188
189
190       ┌─────────────────────────────┬─────────────────────────────┐
191       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │Interface Stability          │Standard                     │
194       ├─────────────────────────────┼─────────────────────────────┤
195       │MT-Level                     │Unsafe                       │
196       └─────────────────────────────┴─────────────────────────────┘
197