Search documentation of Plushie

# Plushie.Type.Color (Plushie v0.7.2)

Copy Markdown View Source

Color type for iced widget properties.

All colors are canonical hex strings: `"#rrggbb"` or `"#rrggbbaa"`.

Use the constructors `from_rgb/3`, `from_rgba/4`, and `from_hex/1` to build colors. Use `cast/1` to normalize any supported input form (named atoms, named strings, or hex strings) into a canonical hex string.

All 148 CSS Color Module Level 4 named colors are supported, plus `:transparent`.

## Examples

    iex> Plushie.Type.Color.from_rgb(255, 128, 0)
    "#ff8000"

    iex> Plushie.Type.Color.from_hex("ff8800")
    "#ff8800"

    iex> Plushie.Type.Color.cast(:red)
    {:ok, "#ff0000"}

    iex> Plushie.Type.Color.cast(:cornflowerblue)
    {:ok, "#6495ed"}

## Summary

### Types

input()

Any value accepted by `cast/1`: hex string, short hex, named color atom, named color string, or float RGB/RGBA map.

named()

Named CSS color atom (148 CSS Color Module Level 4 colors plus `:transparent`).

t()

Canonical hex color string (`"#rrggbb"` or `"#rrggbbaa"`).

### Functions

black()

Returns black as a hex string.

cast(name)

Normalizes any supported color input to a canonical hex string.

encode(color)

Encodes a color for the wire format. Identity since all colors are hex strings.

from_hex(hex)

Normalizes a hex string (with or without leading `#`) to canonical form.

from_rgb(r, g, b)

Creates a hex color string from 0-255 RGB integer values.

from_rgba(r, g, b, a)

Creates a hex color string with alpha from 0-255 RGB integers and a 0.0-1.0 alpha float.

named_colors()

Returns the map of all supported named colors.

transparent()

Returns fully transparent black as a hex string.

white()

Returns white as a hex string.

## Types

# input()

    @type input() ::
      named()
      | String.t()
      | %{r: float(), g: float(), b: float(), a: float()}
      | %{r: float(), g: float(), b: float()}

Any value accepted by `cast/1`: hex string, short hex, named color atom, named color string, or float RGB/RGBA map.

# named()

    @type named() ::
      :transparent
      | :darkcyan
      | :tomato
      | :cornsilk
      | :lightsteelblue
      | :darkblue
      | :deeppink
      | :mediumslateblue
      | :mediumturquoise
      | :fuchsia
      | :darkorchid
      | :brown
      | :peru
      | :floralwhite
      | :lightblue
      | :darkorange
      | :olivedrab
      | :plum
      | :mediumpurple
      | :darksalmon
      | :rosybrown
      | :coral
      | :lavender
      | :thistle
      | :snow
      | :mintcream
      | :slategrey
      | :violet
      | :lightgrey
      | :paleturquoise
      | :steelblue
      | :lightcoral
      | :chocolate
      | :navy
      | :papayawhip
      | :mediumaquamarine
      | :black
      | :lightyellow
      | :firebrick
      | :skyblue
      | :lightcyan
      | :oldlace
      | :darkred
      | :darkolivegreen
      | :peachpuff
      | :white
      | :dimgrey
      | :springgreen
      | :bisque
      | :crimson
      | :darkkhaki
      | :blue
      | :darkslategrey
      | :gray
      | :seagreen
      | :azure
      | :wheat
      | :darkmagenta
      | :darkgrey
      | :lawngreen
      | :yellowgreen
      | :salmon
      | :goldenrod
      | :sienna
      | :ghostwhite
      | :antiquewhite
      | :palevioletred
      | :royalblue
      | :magenta
      | :gold
      | :yellow
      | :saddlebrown
      | :darkgray
      | :blanchedalmond
      | :lightgoldenrodyellow
      | :darkslategray
      | :mediumseagreen
      | :gainsboro
      | :darkviolet
      | :purple
      | :silver
      | :orchid
      | :sandybrown
      | :midnightblue
      | :indigo
      | :blueviolet
      | :darkgreen
      | :lightpink
      | :palegoldenrod
      | :maroon
      | :orangered
      | :lime
      | :indianred
      | :red
      | :mediumblue
      | :khaki
      | :lightslategray
      | :dimgray
      | :lightseagreen
      | :cornflowerblue
      | :grey
      | :darkslateblue
      | :green
      | :powderblue
      | :navajowhite
      | :lightgray
      | :burlywood
      | :linen
      | :tan
      | :cadetblue
      | :deepskyblue
      | :slategray
      | :mediumvioletred
      | :mediumorchid
      | :mistyrose
      | :seashell
      | :hotpink
      | :ivory
      | :greenyellow
      | :darkseagreen
      | :olive
      | :rebeccapurple
      | :pink
      | :mediumspringgreen
      | :lemonchiffon
      | :lightsalmon
      | :cyan
      | :aqua
      | :darkturquoise
      | :orange
      | :moccasin
      | :lightskyblue
      | :chartreuse
      | :beige
      | :limegreen
      | :teal
      | :whitesmoke
      | :forestgreen
      | :lavenderblush
      | :darkgoldenrod
      | :lightslategrey
      | :slateblue
      | :turquoise
      | :honeydew
      | :dodgerblue
      | :lightgreen
      | :palegreen
      | :aquamarine
      | :aliceblue

Named CSS color atom (148 CSS Color Module Level 4 colors plus `:transparent`).

# t()

    @type t() :: String.t()

Canonical hex color string (`"#rrggbb"` or `"#rrggbbaa"`).

## Functions

# black()

    @spec black() :: t()

Returns black as a hex string.

# cast(name)

    @spec cast(color :: input()) :: {:ok, t()} | :error

Normalizes any supported color input to a canonical hex string.

Accepts:

- Named atoms: all 148 CSS Color Module Level 4 named colors (e.g. `:red`, `:cornflowerblue`, `:rebeccapurple`) plus `:transparent`
- Named strings: same names as atoms, case-insensitive (e.g. `"red"`, `"CornflowerBlue"`)
- Hex strings: `"#rrggbb"`, `"#rrggbbaa"`, `"#rgb"`, `"#rgba"` (normalized to canonical 6/8-char lowercase hex)
- Float RGBA map: `%{r: 1.0, g: 0.0, b: 0.0, a: 0.5}` (values clamped to 0.0-1.0)
- Float RGB map: `%{r: 1.0, g: 0.0, b: 0.0}` (alpha defaults to 1.0)

Raises `ArgumentError` for unsupported atoms.

## Examples

    iex> Plushie.Type.Color.cast(:black)
    {:ok, "#000000"}

    iex> Plushie.Type.Color.cast(:transparent)
    {:ok, "#00000000"}

    iex> Plushie.Type.Color.cast("#FF0000")
    {:ok, "#ff0000"}

    iex> Plushie.Type.Color.cast(:cornflowerblue)
    {:ok, "#6495ed"}

    iex> Plushie.Type.Color.cast("red")
    {:ok, "#ff0000"}

    iex> Plushie.Type.Color.cast("CornflowerBlue")
    {:ok, "#6495ed"}

# encode(color)

    @spec encode(color :: t()) :: t()

Encodes a color for the wire format. Identity since all colors are hex strings.

## Examples

    iex> Plushie.Type.Color.encode("#ff0000")
    "#ff0000"

# from_hex(hex)

    @spec from_hex(hex :: String.t()) :: t()

Normalizes a hex string (with or without leading `#`) to canonical form.

Downcases the hex digits for consistency.

## Examples

    iex> Plushie.Type.Color.from_hex("#FF8800")
    "#ff8800"

    iex> Plushie.Type.Color.from_hex("ff8800")
    "#ff8800"

    iex> Plushie.Type.Color.from_hex("#ff880080")
    "#ff880080"

# from_rgb(r, g, b)

    @spec from_rgb(r :: integer(), g :: integer(), b :: integer()) :: t()

Creates a hex color string from 0-255 RGB integer values.

## Examples

    iex> Plushie.Type.Color.from_rgb(0, 0, 0)
    "#000000"

    iex> Plushie.Type.Color.from_rgb(255, 255, 255)
    "#ffffff"

    iex> Plushie.Type.Color.from_rgb(255, 128, 0)
    "#ff8000"

# from_rgba(r, g, b, a)

    @spec from_rgba(r :: integer(), g :: integer(), b :: integer(), a :: float()) :: t()

Creates a hex color string with alpha from 0-255 RGB integers and a 0.0-1.0 alpha float.

## Examples

    iex> Plushie.Type.Color.from_rgba(255, 0, 0, 1.0)
    "#ff0000ff"

    iex> Plushie.Type.Color.from_rgba(0, 0, 0, 0.0)
    "#00000000"

    iex> Plushie.Type.Color.from_rgba(255, 128, 0, 0.5)
    "#ff800080"

# named_colors()

    @spec named_colors() :: %{required(atom()) => t()}

Returns the map of all supported named colors.

Keys are atoms, values are canonical hex strings.

# transparent()

    @spec transparent() :: t()

Returns fully transparent black as a hex string.

# white()

    @spec white() :: t()

Returns white as a hex string.