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

SYNOPSIS

9         use Graphics::ColorNames 2.10;
10
11         $po = new Graphics::ColorNames(qw( X ));
12
13         $rgb = $po->hex('green');          # returns '00ff00'
14         $rgb = $po->hex('green', '0x');    # returns '0x00ff00'
15         $rgb = $po->hex('green', '#');     # returns '#00ff00'
16
17         $rgb = $po->rgb('green');          # returns '0,255,0'
18         @rgb = $po->rgb('green');          # returns (0, 255, 0)
19
20         $rgb = $po->green;                 # same as $po->hex('green');
21
22         tie %ph, 'Graphics::ColorNames', (qw( X ));
23
24         $rgb = $ph{green};                 # same as $po->hex('green');
25

DESCRIPTION

27       This module provides a common interface for obtaining the RGB values of
28       colors by standard names.  The intention is to (1) provide a common
29       module that authors can use with other modules to specify colors by
30       name; and (2) free module authors from having to "re-invent the wheel"
31       whenever they decide to give the users the option of specifying a color
32       by name rather than RGB value.
33
34       For example,
35
36         use Graphics::ColorNames 2.10;
37
38         use GD;
39
40         $pal = new Graphics::ColorNames;
41
42         $img = new GD::Image(100, 100);
43
44         $bgColor = $img->colorAllocate( $pal->rgb('CadetBlue3') );
45
46       Although this is a little "bureaucratic", the meaning of this code is
47       clear: $bgColor (or background color) is 'CadetBlue3' (which is easier
48       to for one to understand than "0x7A, 0xC5, 0xCD"). The variable is
49       named for its function, not form (ie, $CadetBlue3) so that if the
50       author later changes the background color, the variable name need not
51       be changed.
52
53       You can also define "Custom Color Schemes" for specialised palettes for
54       websites or institutional publications:
55
56         $color = $pal->hex('MenuBackground');
57
58       As an added feature, a hexidecimal RGB value in the form of #RRGGBB,
59       0xRRGGBB or RRGGBB will return itself:
60
61         $color = $pal->hex('#123abc');         # returns '123abc'
62
63   Tied Interface
64       The standard interface (prior to version 0.40) is through a tied hash:
65
66         tie %pal, 'Graphics::ColorNames', @schemes;
67
68       where %pal is the tied hash and @schemes is a list of color schemes.
69
70       A valid color scheme may be the name of a color scheme (such as "X" or
71       a full module name such as "Graphics::ColorNames::X"), a reference to a
72       color scheme hash or subroutine, or to the path or open filehandle for
73       a rgb.txt file.
74
75       As of version 2.1002, one can also use Color::Library dictionaries:
76
77         tie %pal, 'Graphics::ColorNames', qw(Color::Library::Dictionary::HTML);
78
79       This is an experimental feature which may change in later versions (see
80       "SEE ALSO" for a discussion of the differences between modules).
81
82       Multiple schemes can be used:
83
84         tie %pal, 'Graphics::ColorNames', qw(HTML Netscape);
85
86       In this case, if the name is not a valid HTML color, the Netscape name
87       will be used.
88
89       One can load all available schemes in the Graphics::ColorNames
90       namespace (as of version 2.0):
91
92         use Graphics::ColorNames 2.0, 'all_schemes';
93         tie %NameTable, 'Graphics::ColorNames', all_schemes();
94
95       When multiple color schemes define the same name, then the earlier one
96       listed has priority (however, hash-based color schemes always have
97       priority over code-based color schemes).
98
99       When no color scheme is specified, the X-Windows scheme is assumed.
100
101       Color names are case insensitive, and spaces or punctuation are
102       ignored.  So "Alice Blue" returns the same value as "aliceblue",
103       "ALICE-BLUE" and "a*lICEbl-ue".  (If you are using color names based on
104       user input, you may want to add additional validation of the color
105       names.)
106
107       The value returned is in the six-digit hexidecimal format used in HTML
108       and CSS (without the initial '#'). To convert it to separate red,
109       green, and blue values (between 0 and 255), use the "hex2tuple"
110       function.
111
112   Object-Oriented Interface
113       If you prefer, an object-oriented interface is available:
114
115         use Graphics::ColorNames 0.40;
116
117         $obj = Graphics::ColorNames->new('/etc/rgb.txt');
118
119         $hex = $obj->hex('skyblue'); # returns "87ceeb"
120         @rgb = $obj->rgb('skyblue'); # returns (0x87, 0xce, 0xeb)
121
122       The interface is similar to the Color::Rgb module:
123
124       new
125             $obj = Graphics::ColorNames->new( @SCHEMES );
126
127           Creates the object, using the default color schemes.  If none are
128           specified, it uses the "X" scheme.
129
130       load_scheme
131             $obj->load_scheme( $scheme );
132
133           Loads a scheme dynamically.  The scheme may be any hash or code
134           reference.
135
136       hex
137             $hex = $obj->hex($name, $prefix);
138
139           Returns a 6-digit hexidecimal RGB code for the color.  If an
140           optional prefix is specified, it will prefix the code with that
141           string.  For example,
142
143             $hex = $obj->hex('blue', '#'); # returns "#0000ff"
144
145       rgb
146             @rgb = $obj->rgb($name);
147
148             $rgb = $obj->rgb($name, $separator);
149
150           If called in a list context, returns a triplet.
151
152           If called in a scalar context, returns a string separated by an
153           optional separator (which defauls to a comma).  For example,
154
155             @rgb = $obj->rgb('blue');      # returns (0, 0, 255)
156
157             $rgb = $obj->rgb('blue', ','); # returns "0,0,255"
158
159       Since version 2.10_02, the interface will assume method names are color
160       names and return the hex value,
161
162         $obj->black eq $obj->hex("black")
163
164       Method names are case-insensitive, and underscores are ignored.
165
166   Utility Functions
167       These functions are not exported by default, so much be specified to be
168       used:
169
170         use Graphics::ColorNames qw( all_schemes hex2tuple tuple2hex );
171
172       all_schemes
173             @schemes = all_schemes();
174
175           Returns a list of all available color schemes installed on the
176           machine in the Graphics::ColorNames namespace.
177
178           The order has no significance.
179
180       hex2tuple
181             ($red, $green, $blue) = hex2tuple( $colors{'AliceBlue'});
182
183       tuple2hex
184             $rgb = tuple2hex( $red, $green, $blue );
185
186   Color Schemes
187       The following schemes are available by default:
188
189       X   About 750 color names used in X-Windows (although about 90+ of them
190           are duplicate names with spaces).
191
192       HTML
193           16 common color names defined in the HTML 4.0 specification. These
194           names are also used with older CSS and SVG specifications. (You may
195           want to see Graphics::ColorNames::SVG for a complete list.)
196
197       Netscape
198           100 color names names associated Netscape 1.1 (I cannot determine
199           whether they were once usable in Netscape or were arbitrary names
200           for RGB values-- many of these names are not recognized by later
201           versions of Netscape).
202
203           This scheme may be deprecated in future versions, but available as
204           a separate module.
205
206       Windows
207           16 commom color names used with Microsoft Windows and related
208           products.  These are actually the same colors as the "HTML" scheme,
209           although with different names.
210
211       Rather than a color scheme, the path or open filehandle for a rgb.txt
212       file may be specified.
213
214       Additional color schemes may be available on CPAN.
215
216   Custom Color Schemes
217       You can add naming scheme files by creating a Perl module is the name
218       "Graphics::ColorNames::SCHEMENAME" which has a subroutine named
219       "NamesRgbTable" that returns a hash of color names and RGB values.
220       (Schemes with a different base namespace will require the fill
221       namespace to be given.)
222
223       The color names must be in all lower-case, and the RGB values must be
224       24-bit numbers containing the red, green, and blue values in most-
225       significant to least- significant byte order.
226
227       An example naming schema is below:
228
229         package Graphics::ColorNames::Metallic;
230
231         sub NamesRgbTable() {
232           use integer;
233           return {
234             copper => 0xb87333,
235             gold   => 0xcd7f32,
236             silver => 0xe6e8fa,
237           };
238         }
239
240       You would use the above schema as follows:
241
242         tie %colors, 'Graphics::ColorNames', 'Metallic';
243
244       The behavior of specifying multiple keys with the same name is
245       undefined as to which one takes precedence.
246
247       As of version 2.10, case, spaces and punctuation are ignored in color
248       names. So a name like "Willy's Favorite Shade-of-Blue" is treated the
249       same as "willysfavoroteshadeofblue".  (If your scheme does not include
250       duplicate entrieswith spaces and punctuation, then the minimum version
251       of Graphics::ColorNames should be 2.10 in your requirements.)
252
253       An example of an additional module is the Graphics::ColorNames::Mozilla
254       module by Steve Pomeroy.
255
256       Since version 1.03, "NamesRgbTable" may also return a code reference:
257
258         package Graphics::ColorNames::Orange;
259
260         sub NamesRgbTable() {
261           return sub {
262             my $name = shift;
263             return 0xffa500;
264           };
265         }
266
267       See Graphics::ColorNames::GrayScale for an example.
268
269   Graphics::ColourNames
270       The alias "Graphics::ColourNames" (British spelling) is no longer
271       available as of version 2.01.
272
273       It seems absurd to maintain it when all the modules does is provide an
274       alternative spelling for the module name without doing anything about
275       the component colors of each scheme, and when most other modules (and
276       non-Perl software) does not bother with such things.
277

AUTHOR

293       Robert Rothenberg <rrwo at cpan.org>
294
295   Acknowledgements
296       Alan D. Salewski <alans at cji.com> for feedback and the addition of
297       "tuple2hex".
298
299       Steve Pomeroy <xavier at cpan.org>, "chemboy" <chemboy at perlmonk.org>
300       and "magnus" <magnus at mbox604.swipnet.se> who pointed out issues with
301       various color schemes.
302
303   Suggestions and Bug Reporting
304       Feedback is always welcome.  Please use the CPAN Request Tracker at
305       <http://rt.cpan.org> to submit bug reports.
306
307       There is a Sourceforge project for this package at
308       <http://sourceforge.net/projects/colornames/>.
309
310       If you create additional color schemes, please make them available
311       separately in CPAN rather than submit them to me for inclusion into
312       this module.
313

LICENSE

315       Copyright (c) 2001-2008 Robert Rothenberg. All rights reserved.  This
316       program is free software; you can redistribute it and/or modify it
317       under the same terms as Perl itself.
318
319
320
321perl v5.12.0                      2010-05-02           Graphics::ColorNames(3)