A Color object describes a color used to draw something on screen. Each color is determined by a set of components, which specify how much of each basic/constituent color is present. The standard components are red, green, and blue (RGB). The normalized component values are always between 0.0 to mean “none” and 1.0 to mean “full”. As an example, a purple color might have 0.5 for both its red and blue components.

Alternatively, you may access color components using the “255” commands, which expect their values to be between 0 and 255. This is provided as a convenience for those accustomed to working in that system or for when dealing with HTML.

Color Type Commands

Color.white v1.2

Returns a fully opaque pure white color.

Color.black v1.2

Returns a fully opaque pure black color.

Color.red v1.2

Returns a fully opaque pure red color.

Color.green v1.2

Returns a fully opaque pure green color.

Color.blue v1.2

Returns a fully opaque pure blue color.

Color.newWithRGB red, green, blue v1.2

Returns a new fully opaque color object with the given red, green, and blue components. Each component should be between 0.0 and 1.0 inclusive or will be clipped as needed.

Color.newWithRGBA red, green, blue, opacity v1.2

Returns a new color object with the given red, green, blue, and opacity components. Each component should be between 0.0 and 1.0 inclusive or will be clipped as needed.

Color.newWithWhite white v1.2

Returns a new fully opaque color object that is some kind of grey (equal color components). The white value should be between 0.0 (for black) and 1.0 (for white) inclusive or will be clipped as needed.

Color.newWithRGB255 red255, green255, blue255 v1.2

Returns a new fully opaque color object with the given components, which should be between 0 and 255 inclusive.

Color.newWithHexTriplet hexValue v1.2

Returns a new fully opaque color object using the provided hexadecimal value. This value should be a series of six consecutive hexadecimal digits (as in HTML). The first two digits specify the red component, the next two the green component, and the final two the blue component. For example, a purplish color might have the value “FF00EE”, FF for red, 00 for green, and EE for blue.

The hex triplet value can be a mixed case string that allows either (or no) prefix. The value may also be a numeric value, eg: the following all accomplish the same:

Color.newWithHexTriplet 'ff00ee'

Color.newWithHexTriplet '0xFF00EE'

Color.newWithHexTriplet 0x0FF00EE

Color Object Properties

.copy v1.2

Returns an exact copy of the color object that is independent of the existing object. Note: copying the colors returned by type commands (eg: Color.white) is not necessary. Each time you call those commands a new independent color is created.

.red v1.2

A number describing how much red is present in the color, eg: the red component in the RGB color space. This number ranges from 0.0 to 1.0 inclusive.

.green v1.2

A number describing how much green is present in the color, eg: the green component in the RGB color space. This number ranges from 0.0 to 1.0 inclusive.

.blue v1.2

A number describing how much blue is present in the color, eg: the blue component in the RGB color space. This number ranges from 0.0 to 1.0 inclusive.

.opacity v1.2

A number describing how opaque the color is. This number ranges from 0.0 for completely transparent to 1.0 for completely opaque.

.red255 v1.2

A number describing how much red is present in the color, eg: the red component in the RGB color space. This number ranges from 0 to 255 inclusive.

.green255 v1.2

A number describing how much red is present in the color, eg: the green component in the RGB color space. This number ranges from 0 to 255 inclusive.

.blue255 v1.2

A number describing how much red is present in the color, eg: the blue component in the RGB color space. This number ranges from 0 to 255 inclusive.

.hexTriplet v1.2

This property is a hexadecimal string that can be used to represent the color in HTML code, eg: a purple color might have the property value “FF00EE”. 

When reading this property the returned string is always in uppercase hexadecimal and without the adornments “#” or “0x”. However, when setting this property value some leniency is allowed (see the command newWithHexTriplet for allowed values).

Color Object Examples

Creating a new purple color, with slightly more red than blue:

$purple = Color.newWithRGB(0.6, 0, 0.5)

Color properties are not read-only, so you can easily make adjustments to an existing color. For example, modifying a color to be slightly transparent:

$newColor = $oldColor.copy # copy so the old color is unaffected

$newColor.opacity = 0.9 # 1.0 means fully opaque