# Color

All properties and functions that expect color values in the form of instances of Color objects, also accept named colors and hex values as strings which are then converted to instances of `Color` internally.

#### Example:Named color values:

Run

#### Example:Hex color values:

Run

## Constructors

`Color(red, green, blue[, alpha])`

Creates a RGB Color object.

#### Parameters:

- `red:` `Number` — the amount of red in the color as a value between `0` and `1`
- `green:` `Number` — the amount of green in the color as a value between `0` and `1`
- `blue:` `Number` — the amount of blue in the color as a value between `0` and `1`
- `alpha:` `Number` — the alpha of the color as a value between `0` and `1` — optional

#### Returns:

- ``Color``

#### Example:Creating a RGB Color:

Run
`Color(gray[, alpha])`

Creates a gray Color object.

#### Parameters:

- `gray:` `Number` — the amount of gray in the color as a value between `0` and `1`
- `alpha:` `Number` — the alpha of the color as a value between `0` and `1` — optional

#### Returns:

- ``Color``

#### Example:Creating a gray Color:

Run
`Color(object)`

Creates a HSB, HSL or gradient Color object from the properties of the provided object:

#### Options:

- `hsb.hue: `Number`` — the hue of the color as a value in degrees between `0` and `360`
- `hsb.saturation: `Number`` — the saturation of the color as a value between `0` and `1`
- `hsb.brightness: `Number`` — the brightness of the color as a value between `0` and `1`
- `hsb.alpha: `Number`` — the alpha of the color as a value between `0` and `1`
- `hsl.hue: `Number`` — the hue of the color as a value in degrees between `0` and `360`
- `hsl.saturation: `Number`` — the saturation of the color as a value between `0` and `1`
- `hsl.lightness: `Number`` — the lightness of the color as a value between `0` and `1`
- `hsl.alpha: `Number`` — the alpha of the color as a value between `0` and `1`
- `gradient.gradient: `Gradient`` — the gradient object that describes the color stops and type of gradient to be used
- `gradient.origin: `Point`` — the origin point of the gradient
- `gradient.destination: `Point`` — the destination point of the gradient
- `gradient.stops: undefined` — {GradientStop[]} the gradient stops describing the gradient, as an alternative to providing a gradient object
- `gradient.radial: `Boolean`` — controls whether the gradient is radial, as an alternative to providing a gradient object

#### Parameters:

- `object:` `Object` — an object describing the components and properties of the color

#### Returns:

- ``Color``

#### Example:Creating a HSB Color:

Run

#### Example:Creating a HSL Color:

Run

#### Example:Creating a gradient color from an object literal:

Run
`Color(gradient, origin, destination[, highlight])`

Creates a gradient Color object.

#### Parameters:

- `gradient:` `Gradient`
- `origin:` `Point`
- `destination:` `Point`
- `highlight:` `Point` — optional

#### Returns:

- ``Color``

#### Example:Applying a linear gradient color containing evenly distributed color stops:

Run

#### Example:Applying a radial gradient color containing unevenly distributed color stops:

Run

## Operators

``+number`, `+color``

Returns the addition of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to add

#### Returns:

- ``Color`` — the addition of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color + 1;
    console.log(result); // { red: 1, blue: 1, green: 1 }

Returns the addition of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to add

#### Returns:

- ``Color`` — the addition of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(1, 0, 0);
    var result = color1 + color2;
    console.log(result); // { red: 1, blue: 1, green: 1 }

``-number`, `-color``

Returns the subtraction of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to subtract

#### Returns:

- ``Color`` — the subtraction of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color - 1;
    console.log(result); // { red: 0, blue: 0, green: 0 }

Returns the subtraction of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to subtract

#### Returns:

- ``Color`` — the subtraction of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(1, 0, 0);
    var result = color1 - color2;
    console.log(result); // { red: 0, blue: 1, green: 1 }

``*number`, `*color``

Returns the multiplication of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to multiply

#### Returns:

- ``Color`` — the multiplication of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color * 0.5;
    console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 }

Returns the multiplication of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to multiply

#### Returns:

- ``Color`` — the multiplication of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(0.5, 0, 0.5);
    var result = color1 * color2;
    console.log(result); // { red: 0, blue: 0, green: 0.5 }

``/number`, `/color``

Returns the division of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to divide

#### Returns:

- ``Color`` — the division of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color / 2;
    console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 }

Returns the division of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to divide

#### Returns:

- ``Color`` — the division of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(0.5, 0, 0.5);
    var result = color1 / color2;
    console.log(result); // { red: 0, blue: 0, green: 1 }

## Properties

`type`

The type of the color as a string.

#### Type:

- `String`

#### Example:

    var color = new Color(1, 0, 0);
    console.log(color.type); // 'rgb'

`components`

The color components that define the color, including the alpha value if defined.

Read only.

#### Type:

- `Number`

`alpha`

The color’s alpha value as a number between `0` and `1`. All colors of the different subclasses support alpha values.

#### Type:

- `Number`

#### Example:A filled path with a half transparent stroke:

Run

### RGB Components

`red`

The amount of red in the color as a value between `0` and `1`.

#### Type:

- `Number`

#### Example:Changing the amount of red in a color:

Run
`green`

The amount of green in the color as a value between `0` and `1`.

#### Type:

- `Number`

#### Example:Changing the amount of green in a color:

Run
`blue`

The amount of blue in the color as a value between `0` and `1`.

#### Type:

- `Number`

#### Example:Changing the amount of blue in a color:

Run

### Gray Components

`gray`

The amount of gray in the color as a value between `0` and `1`.

#### Type:

- `Number`

### HSB Components

`hue`

The hue of the color as a value in degrees between `0` and `360`.

#### Type:

- `Number`

#### Example:Changing the hue of a color:

Run

#### Example:Hue cycling:

Run
`saturation`

The saturation of the color as a value between `0` and `1`.

#### Type:

- `Number`

`brightness`

The brightness of the color as a value between `0` and `1`.

#### Type:

- `Number`

### HSL Components

`lightness`

The lightness of the color as a value between `0` and `1`.

Note that all other components are shared with HSB.

#### Type:

- `Number`

### Gradient Components

`gradient`

The gradient object describing the type of gradient and the stops.

#### Type:

- `Gradient`

`highlight`

The highlight point of the gradient.

#### Type:

- `Point`

#### Example:Create a circle shaped path at the center of the view, using 40% of the height of the view as its radius and fill it with a radial gradient color:

Run

## Methods

`convert(type)`

Converts the color another type.

#### Parameters:

- `type:` `String` — the color type to convert to. Possible values: `‘rgb’`, `‘gray’`, `‘hsb’`, `‘hsl’`

#### Returns:

- ``Color`` — the converted color as a new instance

`hasAlpha()`

Checks if the color has an alpha value.

#### Returns:

- ``Boolean`` — `true` if the color has an alpha value, `false` otherwise

`equals(color)`

Checks if the component color values of the color are the same as those of the supplied one.

#### Parameters:

- `color:` `Color` — the color to compare with

#### Returns:

- ``Boolean`` — `true` if the colors are the same, `false` otherwise

`clone()`

#### Returns:

- ``Color`` — a copy of the color object

### String Representations

`toString()`

#### Returns:

- ``String`` — a string representation of the color

`toCSS(hex)`

Returns the color as a CSS string.

#### Parameters:

- `hex:` `Boolean` — whether to return the color in hexadecimal representation or as a CSS RGB / RGBA string.

#### Returns:

- ``String`` — a CSS string representation of the color

`transform(matrix)`

Transform the gradient color by the specified matrix.

#### Parameters:

- `matrix:` `Matrix` — the matrix to transform the gradient color by

### Math Operator Functions

`add(number)`

Returns the addition of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to add

#### Returns:

- ``Color`` — the addition of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color + 1;
    console.log(result); // { red: 1, blue: 1, green: 1 }

`add(color)`

Returns the addition of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to add

#### Returns:

- ``Color`` — the addition of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(1, 0, 0);
    var result = color1 + color2;
    console.log(result); // { red: 1, blue: 1, green: 1 }

`subtract(number)`

Returns the subtraction of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to subtract

#### Returns:

- ``Color`` — the subtraction of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color - 1;
    console.log(result); // { red: 0, blue: 0, green: 0 }

`subtract(color)`

Returns the subtraction of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to subtract

#### Returns:

- ``Color`` — the subtraction of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(1, 0, 0);
    var result = color1 - color2;
    console.log(result); // { red: 0, blue: 1, green: 1 }

`multiply(number)`

Returns the multiplication of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to multiply

#### Returns:

- ``Color`` — the multiplication of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color * 0.5;
    console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 }

`multiply(color)`

Returns the multiplication of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to multiply

#### Returns:

- ``Color`` — the multiplication of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(0.5, 0, 0.5);
    var result = color1 * color2;
    console.log(result); // { red: 0, blue: 0, green: 0.5 }

`divide(number)`

Returns the division of the supplied value to both coordinates of the color as a new color. The object itself is not modified!

#### Parameters:

- `number:` `Number` — the number to divide

#### Returns:

- ``Color`` — the division of the color and the value as a new color

#### Example:

    var color = new Color(0.5, 1, 1);
    var result = color / 2;
    console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 }

`divide(color)`

Returns the division of the supplied color to the color as a new color. The object itself is not modified!

#### Parameters:

- `color:` `Color` — the color to divide

#### Returns:

- ``Color`` — the division of the two colors as a new color

#### Example:

    var color1 = new Color(0, 1, 1);
    var color2 = new Color(0.5, 0, 0.5);
    var result = color1 / color2;
    console.log(result); // { red: 0, blue: 0, green: 1 }