Graphics::ColorNames(3pm)

1Graphics::ColorNames(3)User Contributed Perl DocumentatioGnraphics::ColorNames(3)
2
3
4

NAME

6       Graphics::ColorNames - defines RGB values for common color names
7

REQUIREMENTS

9       "Graphics::ColorNames" should work on Perl 5.6.0.  It requires the fol‐
10       lowing non-standard modules:
11
12         Module::Load
13
14       Installation
15
16       Installation is pretty standard:
17
18         perl Makefile.PL
19         make
20         make test
21         make install
22

SYNOPSIS

24         use Graphics::ColorNames qw( hex2tuple tuple2hex );
25
26         tie %NameTable, 'Graphics::ColorNames', 'X';
27
28         my $rgbhex1 = $NameTable{'green'};    # returns '00ff00'
29         my $rgbhex2 = tuple2hex( 0, 255, 0 ); # returns '00ff00'
30         my @rgbtup  = hex2tuple( $rgbhex );   # returns (0, 255, 0)
31
32         my $rgbhex3 = $NameTable{'#123abc'};  # returns '123abc'
33         my $rgbhex4 = $NameTable{'123abc'};   # returns '123abc'
34

DESCRIPTION

36       This module defines RGB values for common color names. The intention is
37       to (1) provide a common module that authors can use with other modules
38       to specify colors; and (2) free module authors from having to
39       "re-invent the wheel" whenever they decide to give the users the option
40       of specifying a color by name rather than RGB value.
41
42       For example,
43
44         use Graphics::ColorNames 'hex2tuple';
45         tie %COLORS, 'Graphics::ColorNames';
46
47         use GD;
48
49         $img = new GD::Image(100, 100);
50
51         $bgColor = $img->colorAllocate( hex2tuple( $COLORS{'CadetBlue3'} ) );
52
53       Though a little 'bureaucratic', the meaning of this code is clearer:
54       $bgColor (or background color) is 'CadetBlue3' (which is easier to for
55       one to understand than "0x7A, 0xC5, 0xCD"). The variable is named for
56       its function, not form (ie, $CadetBlue3) so that if the author later
57       changes the background color, the variable name need not be changed.
58
59       As an added feature, a hexidecimal RGB value in the form of #RRGGBB or
60       RRGGBB will return itself:
61
62         my $rgbhex3 = $NameTable{'#123abc'};  # returns '123abc'
63
64       Tied Interface
65
66       The standard interface (prior to version 0.40) is through a tied hash:
67
68         tie %NAMETABLE, 'Graphics::ColorNames', @SCHEME
69
70       where %NAMETABLE is the tied hash and @SCHEME is a list of color
71       schemes or the path to or open filehandle for a rgb.txt file.
72
73       Multiple schemes can be used:
74
75         tie %COLORS, 'Graphics::ColorNames', qw(HTML Windows Netscape);
76
77       In this case, if the name is not a valid HTML color, the Windows name
78       will be used; if it is not a valid Windows name, then the Netscape name
79       will be used.
80
81       RGB values can be retrieved with a case-insensitive hash key:
82
83         $rgb = $colors{'AliceBlue'};
84
85       The value returned is in the six-digit hexidecimal format used in HTML
86       and CSS (without the initial '#'). To convert it to separate red,
87       green, and blue values (between 0 and 255), use the "hex2tuple" func‐
88       tion.
89
90       Object-Oriented Interface
91
92       If you prefer, an object-oriented interface is available:
93
94         $obj = Graphics::ColorNames->new('/etc/rgb.txt');
95
96         $hex = $obj->hex('skyblue'); # returns "87ceeb"
97
98         @rgb = $obj->rgb('skyblue'); # returns (0x87, 0xce, 0xeb)
99
100       The interface is similar to the Color::Rgb module:
101
102       new
103             $obj = Graphics::ColorNames->new( @SCHEMES );
104
105           Creates the object, using the default color schemes.  If none are
106           specified, it uses the "X" scheme.
107
108       hex
109             $hex = $obj->hex($name, $prefix);
110
111           Returns a 6-digit hexidecimal RGB code for the color.  If an
112           optional prefix is specified, it will prefix the code with that
113           string.  For example,
114
115             $hex = $obj->hex('blue', '#'); # returns "#0000ff"
116
117       rgb
118             @rgb = $obj->rgb($name);
119
120             $rgb = $obj->rgb($name, $separator);
121
122           If called in a list context, returns a triplet.
123
124           If called in a scalar context, returns a string separated by an
125           optional separator (which defauls to a comma).  For example,
126
127             @rgb = $obj->rgb('blue');      # returns (0, 0, 255)
128
129             $rgb = $obj->rgb('blue', ','); # returns "0,0,255"
130
131       Utility Functions
132
133       These functions are not exported by default, so much be specified to be
134       used:
135
136         use Graphics::ColorNames qw( hex2tuple tuple2hex );
137
138       hex2tuple
139             ($red, $green, $blue) = hex2tuple( $colors{'AliceBlue'});
140
141       tuple2hex
142             $rgb = tuple2hex( $red, $green, $blue );
143
144       Color Schemes
145
146       The following schemes are available by default:
147
148       X   About 750 color names used in X-Windows. This is the default naming
149           scheme, since it provides the most names.
150
151       HTML
152           16 common color names defined in the HTML 4.0 specification. These
153           names are also used with CSS and SVG.
154
155       Netscape
156           100 color names names associated Netscape 1.1 (I cannot determine
157           whether they were once usable in Netscape or were arbitrary names
158           for RGB values-- many of these names are not recognized by later
159           versions of Netscape).
160
161           This scheme may be deprecated in future versions, but available as
162           a separate module.
163
164       Windows
165           16 commom color names used with Microsoft Windows and related prod‐
166           ucts.  These are actually the same colors as "HTML", although with
167           different names.
168
169       Rather than a color scheme, the path or open filehandle for a rgb.txt
170       file may be specified.
171
172       Additional color schemes may be available on CPAN.
173
174       Adding Naming Schemes
175
176       You can add naming scheme files by creating a Perl module is the name
177       "Graphics::ColorNames::SCHEMENAME" which has a subroutine named "Names‐
178       RgbTable" that returns a hash of color names and RGB values.
179
180       The color names must be in all lower-case, and the RGB values must be
181       24-bit numbers containing the red, green, and blue values in most- sig‐
182       nificant to least- significant byte order.
183
184       An example naming schema is below:
185
186         package Graphics::ColorNames::Metallic;
187
188         sub NamesRgbTable() {
189           use integer;
190           return {
191             copper => 0xb87333,
192             gold   => 0xcd7f32,
193             silver => 0xe6e8fa,
194           };
195         }
196
197       You would use the above schema as follows:
198
199         tie %colors, 'Graphics::ColorNames', 'Metallic';
200
201       An example of an additional module is Steve Pomeroy's Graphics::Color‐
202       Names::Mozilla module.
203
204       Since version 1.03, "NamesRgbTable" may also return a code reference:
205
206         package Graphics::ColorNames::Orange;
207
208         sub NamesRgbTable() {
209           return sub {
210             my $name = shift;
211             return 0xffa500;
212           };
213         }
214
215       See Graphics::ColorNames::GrayScale for an example.
216
217       Note that extentions of the form "Graphics::ColourNames::*" are not
218       supported.
219

DSLIP

228         R - Released
229         d - Developer
230         p - Perl-only
231         h - Hybrid interface
232         p - Standard Perl
233
234       See <http://cpan.uwinnipeg.ca/htdocs/faqs/dslip.html>
235

AUTHOR

237       Robert Rothenberg <rrwo at cpan.org>
238
239       Acknowledgements
240
241       Alan D. Salewski <alans at cji.com> for feedback and the addition of
242       "tuple2hex".
243
244       Steve Pomeroy <xavier at cpan.org> for pointing out invalid color defi‐
245       nitions in X color space.
246
247       <chemboy at perlmonk.org> who pointed out a mispelling of "fuchsia" in
248       the HTML color space <http://rt.cpan.org/Ticket/Display.html?id=1704>.
249
250       <magnus at mbox604.swipnet.se> who pointed out mispellings and naming
251       inconsistencies.
252
253       Suggestions and Bug Reporting
254
255       Feedback is always welcome.  Please use the CPAN Request Tracker at
256       <http://rt.cpan.org> to submit bug reports.
257
258       If you create additional color schemes, please make them available sep‐
259       arately in CPAN rather than submit them to me for inclusion into this
260       module.
261

LICENSE

263       Copyright (c) 2001-2005 Robert Rothenberg. All rights reserved.  This
264       program is free software; you can redistribute it and/or modify it
265       under the same terms as Perl itself.
266
267
268
269perl v5.8.8                       2007-04-17           Graphics::ColorNames(3)