# (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!

""" Color classes and corresponding trait types for Pyface.

The base Color class holds red, green, blue and alpha channel values as
a tuple of normalized values from 0.0 to 1.0.  Various property traits
pull out the individual channel values and supply values for the HSV
and HSL colour spaces (with and without alpha).

The ``from_toolkit`` and ``to_toolkit`` methods allow conversion to and
from native toolkit color objects.
"""

import colorsys

from traits.api import (
    Bool, HasStrictTraits, Property, Range, Tuple, cached_property
)

from pyface.util.color_helpers import channels_to_ints, is_dark
from pyface.util.color_helpers import ints_to_channels  # noqa: F401
from pyface.util.color_parser import parse_text


#: A trait holding a single channel value.
Channel = Range(0.0, 1.0, value=1.0, channel=True)

#: A trait holding three channel values.
ChannelTuple = Tuple(Channel, Channel, Channel)

#: A trait holding four channel values.
AlphaChannelTuple = Tuple(Channel, Channel, Channel, Channel)


class Color(HasStrictTraits):
    """ A mutable specification of a color with alpha.

    This is a class designed to be used by user interface elements which
    need to color some or all of the interface element.  Each color has a
    number of different representations as channel tuples, each channel
    holding a value between 0.0 and 1.0, inclusive.  The standard red,
    green, blue and alpha channels are also provided as convenience
    properties.

    Methods are provided to convert to and from toolkit-specific color
    objects.

    Colors implement equality testing, but are not hashable as they are
    mutable, and so are not suitable for use as dictionary keys.  If you
    need a dictionary key, use an appropriate channel tuple from the
    object.
    """

    #: A tuple holding the red, green, blue, and alpha channels.
    rgba = AlphaChannelTuple()

    #: A tuple holding the red, green, and blue channels.
    rgb = Property(ChannelTuple(), observe='rgba')

    #: The red channel.
    red = Property(Channel, observe='rgba')

    #: The green channel.
    green = Property(Channel, observe='rgba')

    #: The blue channel.
    blue = Property(Channel, observe='rgba')

    #: The alpha channel.
    alpha = Property(Channel, observe='rgba')

    #: A tuple holding the hue, saturation, value, and alpha channels.
    hsva = Property(AlphaChannelTuple, observe='rgba')

    #: A tuple holding the hue, saturation, and value channels.
    hsv = Property(ChannelTuple, observe='rgb')

    #: A tuple holding the hue, lightness, saturation, and alpha channels.
    hlsa = Property(AlphaChannelTuple, observe='rgba')

    #: A tuple holding the hue, lightness, and saturation channels.
    hls = Property(ChannelTuple, observe='rgb')

    #: Whether the color is dark for contrast purposes.
    is_dark = Property(Bool, observe='rgba')

    @classmethod
    def from_str(cls, text, **traits):
        """ Create a new Color object from a string.

        Parameters
        ----------
        text : str
            A string holding the representation of the color.  This can be:

            - a color name, including all CSS color names, plus any additional
              names found in pyface.color.color_table.  The names are
              normalized to lower case and stripped of whitespace, hyphens and
              underscores.

            - a hex representation of the color in the form '#RGB', '#RGBA',
              '#RRGGBB', '#RRGGBBAA', '#RRRRGGGGBBBB', or '#RRRRGGGGBBBBAAAA'.

        **traits
            Any additional trait values to be passed as keyword arguments.

        Raises
        ------
        ColorParseError
            If the string cannot be converted to a valid color.
        """
        space, channels = parse_text(text)
        if space in traits:
            raise TypeError(
                "from_str() got multiple values for keyword argument "
                + repr(space)
            )
        traits[space] = channels
        return cls(**traits)

    @classmethod
    def from_toolkit(cls, toolkit_color, **traits):
        """ Create a new Color object from a toolkit color object.

        Parameters
        ----------
        toolkit_color : toolkit object
            A toolkit color object, such as a Qt QColor or a Wx wx.Colour.
        **traits
            Any additional trait values to be passed as keyword arguments.
        """
        from pyface.toolkit import toolkit_object
        toolkit_color_to_rgba = toolkit_object('color:toolkit_color_to_rgba')
        rgba = toolkit_color_to_rgba(toolkit_color)
        return cls(rgba=rgba, **traits)

    def to_toolkit(self):
        """ Create a new toolkit color object from a Color object.

        Returns
        -------
        toolkit_color : toolkit object
            A toolkit color object, such as a Qt QColor or a Wx wx.Colour.
        """
        from pyface.toolkit import toolkit_object
        rgba_to_toolkit_color = toolkit_object('color:rgba_to_toolkit_color')
        return rgba_to_toolkit_color(self.rgba)

    def hex(self):
        """ Provide a hex representation of the Color object.

        Note that because the hex value is restricted to 0-255 integer values
        for each channel, the representation is not exact.

        Returns
        -------
        hex : str
            A hex string in standard ``#RRGGBBAA`` format that represents
            the color.
        """
        values = channels_to_ints(self.rgba)
        return "#{:02X}{:02X}{:02X}{:02X}".format(*values)

    def __eq__(self, other):
        if isinstance(other, Color):
            return self.rgba == other.rgba
        return NotImplemented

    def __str__(self):
        return "({:0.5}, {:0.5}, {:0.5}, {:0.5})".format(*self.rgba)

    def __repr__(self):
        return "{}(rgba={!r})".format(self.__class__.__name__, self.rgba)

    def _get_red(self):
        return self.rgba[0]

    def _set_red(self, value):
        r, g, b, a = self.rgba
        self.rgba = (value, g, b, a)

    def _get_green(self):
        return self.rgba[1]

    def _set_green(self, value):
        r, g, b, a = self.rgba
        self.rgba = (r, value, b, a)

    def _get_blue(self):
        return self.rgba[2]

    def _set_blue(self, value):
        r, g, b, a = self.rgba
        self.rgba = (r, g, value, a)

    def _get_alpha(self):
        return self.rgba[3]

    def _set_alpha(self, value):
        r, g, b, a = self.rgba
        self.rgba = (r, g, b, value)

    @cached_property
    def _get_rgb(self):
        return self.rgba[:-1]

    def _set_rgb(self, value):
        r, g, b = value
        self.rgba = (r, g, b, self.rgba[3])

    @cached_property
    def _get_hsva(self):
        r, g, b, a = self.rgba
        h, s, v = colorsys.rgb_to_hsv(r, g, b)
        return (h, s, v, a)

    def _set_hsva(self, value):
        h, s, v, a = value
        r, g, b = colorsys.hsv_to_rgb(h, s, v)
        self.rgba = (r, g, b, a)

    @cached_property
    def _get_hsv(self):
        r, g, b = self.rgb
        return colorsys.rgb_to_hsv(r, g, b)

    def _set_hsv(self, value):
        h, s, v = value
        r, g, b = colorsys.hsv_to_rgb(h, s, v)
        self.rgb = (r, g, b)

    @cached_property
    def _get_hlsa(self):
        r, g, b, a = self.rgba
        h, l, s = colorsys.rgb_to_hls(r, g, b)
        return (h, l, s, a)

    def _set_hlsa(self, value):
        h, l, s, a = value
        r, g, b = colorsys.hls_to_rgb(h, l, s)
        self.rgba = (r, g, b, a)

    @cached_property
    def _get_hls(self):
        r, g, b = self.rgb
        return colorsys.rgb_to_hls(r, g, b)

    def _set_hls(self, value):
        h, l, s = value
        r, g, b = colorsys.hls_to_rgb(h, l, s)
        self.rgb = (r, g, b)

    @cached_property
    def _get_is_dark(self):
        return is_dark(self.rgb)