Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Graphics::ColorNames(3User Contributed Perl DocumentatiGraphics::ColorNames(3)

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

SYNOPSIS
	 use Graphics::ColorNames 2.10;

	 $po = new Graphics::ColorNames(qw( X ));

	 $rgb =	$po->hex('green');	    # returns '00ff00'
	 $rgb =	$po->hex('green', '0x');    # returns '0x00ff00'
	 $rgb =	$po->hex('green', '#');	    # returns '#00ff00'

	 $rgb =	$po->rgb('green');	    # returns '0,255,0'
	 @rgb =	$po->rgb('green');	    # returns (0, 255, 0)

	 $rgb =	$po->green;		    # same as $po->hex('green');

	 tie %ph, 'Graphics::ColorNames', (qw( X ));

	 $rgb =	$ph{green};		    # same as $po->hex('green');

DESCRIPTION
       This module provides a common interface for obtaining the RGB values of
       colors by standard names.  The intention	is to (1) provide a common
       module that authors can use with	other modules to specify colors	by
       name; 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 2.10;

	 use GD;

	 $pal =	new Graphics::ColorNames;

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

	 $bgColor = $img->colorAllocate( $pal->rgb('CadetBlue3') );

       Although	this is	a little "bureaucratic", the meaning of	this code is
       clear: $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.

       You can also define "Custom Color Schemes" for specialised palettes for
       websites	or institutional publications:

	 $color	= $pal->hex('MenuBackground');

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

	 $color	= $pal->hex('#123abc');		# returns '123abc'

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

	 tie %pal, 'Graphics::ColorNames', @schemes;

       where %pal is the tied hash and @schemes	is a list of color schemes.

       A valid color scheme may	be the name of a color scheme (such as "X" or
       a full module name such as "Graphics::ColorNames::X"), a	reference to a
       color scheme hash or subroutine,	or to the path or open filehandle for
       a rgb.txt file.

       As of version 2.1002, one can also use Color::Library dictionaries:

	 tie %pal, 'Graphics::ColorNames', qw(Color::Library::Dictionary::HTML);

       This is an experimental feature which may change	in later versions (see
       "SEE ALSO" for a	discussion of the differences between modules).

       Multiple	schemes	can be used:

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

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

       One can load all	available schemes in the Graphics::ColorNames
       namespace (as of	version	2.0):

	 use Graphics::ColorNames 2.0, 'all_schemes';
	 tie %NameTable, 'Graphics::ColorNames', all_schemes();

       When multiple color schemes define the same name, then the earlier one
       listed has priority (however, hash-based	color schemes always have
       priority	over code-based	color schemes).

       When no color scheme is specified, the X-Windows	scheme is assumed.

       Color names are case insensitive, and spaces or punctuation are
       ignored.	 So "Alice Blue" returns the same value	as "aliceblue",
       "ALICE-BLUE" and	"a*lICEbl-ue".	(If you	are using color	names based on
       user input, you may want	to add additional validation of	the color
       names.)

       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:

	 use Graphics::ColorNames 0.40;

	 $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.

       load_scheme
	     $obj->load_scheme(	$scheme	);

	   Loads a scheme dynamically.	The scheme may be any hash or code
	   reference.

       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"

       Since version 2.10_02, the interface will assume	method names are color
       names and return	the hex	value,

	 $obj->black eq	$obj->hex("black")

       Method names are	case-insensitive, and underscores are ignored.

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

	 use Graphics::ColorNames qw( all_schemes hex2tuple tuple2hex );

       all_schemes
	     @schemes =	all_schemes();

	   Returns a list of all available color schemes installed on the
	   machine in the Graphics::ColorNames namespace.

	   The order has no significance.

       hex2tuple
	     ($red, $green, $blue) = hex2tuple(	$colors{'AliceBlue'});

       tuple2hex
	     $rgb = tuple2hex( $red, $green, $blue );

   Color Schemes
       The following schemes are available by default:

       X   About 750 color names used in X-Windows (although about 90+ of them
	   are duplicate names with spaces).

       HTML
	   16 common color names defined in the	HTML 4.0 specification.	These
	   names are also used with older CSS and SVG specifications. (You may
	   want	to see Graphics::ColorNames::SVG for a complete	list.)

       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).

	   This	scheme may be deprecated in future versions, but available as
	   a separate module.

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

       Rather than a color scheme, the path or open filehandle for a rgb.txt
       file may	be specified.

       Additional color	schemes	may be available on CPAN.

   Custom Color	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.
       (Schemes	with a different base namespace	will require the fill
       namespace to be given.)

       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';

       The behavior of specifying multiple keys	with the same name is
       undefined as to which one takes precedence.

       As of version 2.10, case, spaces	and punctuation	are ignored in color
       names. So a name	like "Willy's Favorite Shade-of-Blue" is treated the
       same as "willysfavoroteshadeofblue".  (If your scheme does not include
       duplicate entrieswith spaces and	punctuation, then the minimum version
       of Graphics::ColorNames should be 2.10 in your requirements.)

       An example of an	additional module is the Graphics::ColorNames::Mozilla
       module by Steve Pomeroy.

       Since version 1.03, "NamesRgbTable" may also return a code reference:

	 package Graphics::ColorNames::Orange;

	 sub NamesRgbTable() {
	   return sub {
	     my	$name =	shift;
	     return 0xffa500;
	   };
	 }

       See Graphics::ColorNames::GrayScale for an example.

   Graphics::ColourNames
       The alias "Graphics::ColourNames" (British spelling) is no longer
       available as of version 2.01.

       It seems	absurd to maintain it when all the modules does	is provide an
       alternative spelling for	the module name	without	doing anything about
       the component colors of each scheme, and	when most other	modules	(and
       non-Perl	software) does not bother with such things.

SEE ALSO
       Color::Library provides an extensive library of color schemes. A
       notable difference is that it supports more complex schemes which
       contain additional information about individual colors and map multiple
       colors to a single name.

       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.

       Acme::AutoColor provides	subroutines corresponding to color names.

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>, "chemboy" <chemboy at perlmonk.org>
       and "magnus" <magnus at mbox604.swipnet.se> who pointed out issues with
       various color schemes.

   Suggestions and Bug Reporting
       Feedback	is always welcome.  Please use the CPAN	Request	Tracker	at
       <http://rt.cpan.org> to submit bug reports.

       There is	a Sourceforge project for this package at
       <http://sourceforge.net/projects/colornames/>.

       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-2008 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.

perl v5.24.1			  2017-07-02	       Graphics::ColorNames(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Graphics::ColorNames&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help