/ 
Graphics-ColorNames-0.39_02
River stage two • 22 direct dependents • 98 total dependents
/ Graphics::ColorNames

NAME

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

REQUIREMENTS

Graphics::ColorNames should work on Perl 5.005.

It uses only standard modules.

Installation

Installation is pretty standard:

perl Makefile.PL
make
make test
make install

SYNOPSIS

use Graphics::ColorNames qw( hex2tuple tuple2hex );

tie %NameTable, 'Graphics::ColorNames', 'X';

my $rgbhex1 = $NameTable{'green'};    # returns '00ff00'
my $rgbhex2 = tuple2hex( 0, 255, 0 ); # returns '00ff00'
my @rgbtup  = hex2tuple( $rgbhex );   # returns (0, 255, 0)

my $rgbhex3 = $NameTable{'#123abc'};  # returns '123abc'
my $rgbhex4 = $NameTable{'123abc'};   # returns '123abc'

DESCRIPTION

This module defines RGB values for common color names. The intention is to (1) provide a common module that authors can use with other modules to specify colors; and (2) free module authors from having to "re-invent the wheel" whenever they decide to give the users the option of specifying a color by name rather than RGB value.

For example,

use Graphics::ColorNames 'hex2tuple';
tie %COLORS, 'Graphics::ColorNames';

use GD;

$img = new GD::Image(100, 100);

$bgColor = $img->colorAllocate( hex2tuple( $COLORS{'CadetBlue3'} ) );

Though a little 'bureaucratic', the meaning of this code is clearer: $bgColor (or background color) is 'CadetBlue3' (which is easier to for one to understand than 0x7A, 0xC5, 0xCD). The variable is named for its function, not form (ie, $CadetBlue3) so that if the author later changes the background color, the variable name need not be changed.

As an added feature, a hexidecimal RGB value in the form of #RRGGBB or RRGGBB will return itself:

my $rgbhex3 = $NameTable{'#123abc'};  # returns '123abc'

Tied Interface

The standard interface (prior to version 0.40) is through a tied hash:

tie %NAMETABLE, 'Graphics::ColorNames', @SCHEME

where %NAMETABLE is the tied hash and @SCHEME is a list of color schemes or the path to a rgb.txt file.

Multiple schemes can be used:

tie %COLORS, 'Graphics::ColorNames', qw(HTML Windows Netscape);

In this case, if the name is not a valid HTML color, the Windows name will be used; if it is not a valid Windows name, then the Netscape name will be used.

RGB values can be retrieved with a case-insensitive hash key:

$rgb = $colors{'AliceBlue'};

The value returned is in the six-digit hexidecimal format used in HTML and CSS (without the initial '#'). To convert it to separate red, green, and blue values (between 0 and 255), use the "hex2tuple" function.

Object-Oriented Interface

If you prefer, an object-oriented interface is available:

$obj = Graphics::ColorNames->new('/etc/rgb.txt');

$hex = $obj->hex('skyblue'); # returns "87ceeb"

@rgb = $obj->rgb('skyblue'); # returns (0x87, 0xce, 0xeb)

The interface is similar to the Color::Rgb module:

new
$obj = Graphics::ColorNames->new( @SCHEMES );

Creates the object, using the default color schemes. If none are specified, it uses the X scheme.

hex
$hex = $obj->hex($name, $prefix);

Returns a 6-digit hexidecimal RGB code for the color. If an optional prefix is specified, it will prefix the code with that string. For example,

$hex = $obj->hex('blue', '#'); # returns "#0000ff"
rgb
@rgb = $obj->rgb($name);

$rgb = $obj->rgb($name, $separator);

If called in a list context, returns a triplet.

If called in a scalar context, returns a string separated by an optional separator (which defauls to a comma). For example,

@rgb = $obj->rgb('blue');      # returns (0, 0, 255)

$rgb = $obj->rgb('blue', ','); # returns "0,0,255"

Utility Functions

These functions are not exported by default, so much be specified to be used:

use Graphics::ColorNames qw( hex2tuple tuple2hex );
hex2tuple
($red, $green, $blue) = hex2tuple( $colors{'AliceBlue'});
tuple2hex
$rgb = tuple2hex( $red, $green, $blue );

Color Schemes

Currently four schemes are available:

X

About 750 color names used in X-Windows. This is the default naming scheme, since it provides the most names.

HTML

16 common color names defined in the HTML 4.0 specification. These names are also used with CSS and SVG.

Netscape

100 color names names associated Netscape 1.1 (I cannot determine whether they were once usable in Netscape or were arbitrary names for RGB values-- many of these names are not recognized by later versions of Netscape).

Windows

16 commom color names used with Microsoft Windows and related products. These are actually the same colors as HTML, although with different names.

Additional color schemes may be available on CPAN.

Adding Naming Schemes

You can add naming scheme files by creating a Perl module is the name Graphics::ColorNames::SCHEMENAME which has a subroutine named NamesRgbTable that returns a hash of color names and RGB values.

The color names must be in all lower-case, and the RGB values must be 24-bit numbers containing the red, green, and blue values in most- significant to least- significant byte order.

An example naming schema is below:

package Graphics::ColorNames::Metallic;

sub NamesRgbTable() {
  use integer;
  return {
    copper => 0xb87333,
    gold   => 0xcd7f32,
    silver => 0xe6e8fa,
  };
}

You would use the above schema as follows:

tie %colors, 'Graphics::ColorNames', 'Metallic';

An example of an additional module is Steve Pomeroy's Graphics::ColorNames::Mozilla module.

SEE ALSO

Color::Rgb has a similar function to this module, but parses an rgb.txt file.

Graphics::ColorObject can convert between RGB and other color space types.

AUTHOR

Robert Rothenberg <rrwo at cpan.org>

Acknowledgements

Alan D. Salewski <alans at cji.com> for feedback and the addition of tuple2hex.

Steve Pomeroy <xavier at cpan.org> for pointing out invalid color definitions in X.pm v1.02.

<chemboy at perlmonk.org> who pointed out a mispelling of "fuchsia" in the HTML color space <https://rt.cpan.org/Ticket/Display.html?id=1704>.

<magnus at mbox604.swipnet.se> who pointed out mispellings and naming inconsistencies.

Suggestions and Bug Reporting

Feedback is always welcome. Please use the CPAN Request Tracker at http://rt.cpan.org to submit bug reports.

If you create additional color schemes, please make them available separately in CPAN rather than submit them to me for inclusion into this module.

LICENSE

Copyright (c) 2001-2004 Robert Rothenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.