# (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!


""" Implements the DockWindowFeature base class.

    A DockWindowFeature is an optional feature of a DockControl that can be
    dynamically contributed to the package. Whenever a DockControl is added to
    a DockWindow, each feature will be given the opportunity to add itself to
    the DockControl.

    Each feature is manifested as an image that appears on the DockControl tab
    (or drag bar). The user interacts wth the feature using mouse clicks and
    drag and drop operations (depending upon how the feature is implemented).
"""


from weakref import ref

from traits.api import (
    HasPrivateTraits, Instance, Int, Str, Bool, Property, observe
)
from traitsui.menu import Menu, Action

from pyface.timer.api import do_later
from pyface.ui_traits import Image
from .dock_window import DockWindow
from .dock_sizer import DockControl, add_feature
from .ifeature_tool import IFeatureTool

# -------------------------------------------------------------------------------
#  'DockWindowFeature' class:
# -------------------------------------------------------------------------------


class DockWindowFeature(HasPrivateTraits):
    """ Implements "features" on DockWindows.

    See "The DockWindowFeature Feature of DockWindows" document (.doc or .pdf)
    in pyface.doc for details on using this class.

    Traits are defined on each feature instance. One or more feature instances
    are created for each application component that a feature class applies to.
    A given feature class might or might not apply to a specific application
    component. The feature class determines whether it applies to an application
    component when the feature is activated, or when a new application
    component is added to the DockWindow (and the feature is already active).
    """

    # ---------------------------------------------------------------------------
    #  Class variables:
    # ---------------------------------------------------------------------------

    # A string value that is the user interface name of the feature as it
    # should appear in the DockWindow Features sub-menu (e.g., 'Connect'). An
    # empty string (the default) means that the feature does not appear in the
    # Features sub-menu and cannot be enabled or disabled by the user. Avoid
    # feature names that conflict with other, known features.
    feature_name = ""

    # An integer that specifies th current state of the feature
    # (0 = uninstalled, 1 = active, 2 = disabled). Usually you do not need to
    # change this value explicitly; DockWindows normally manages the value
    # automatically, setting it when the user enables or disables the feature.
    state = 0

    # List of weak references to all current instances.
    instances = []

    # ---------------------------------------------------------------------------
    #  Trait definitions:
    # ---------------------------------------------------------------------------

    # -- Public Traits --------------------------------------------------------------

    # The DockControl instance associated with this feature. Note that features
    # not directly associated with application components, and instead are
    # associated with the DockControl object that manages an application
    # component. The DockControl object provides the feature with access to
    # information about the parent DockWindow object, other DockControl objects
    # contained within the same DockWindow, as well as the application
    # component. This trait is automatically set by the DockWindow when the
    # feature instance is created and associated with an application component.
    dock_control = Instance(DockControl)

    # -- Public Traits (new defaults can be defined by subclasses) ------------------

    # The image (icon) to display on the feature bar. If **None**, no image
    # is displayed. For images that never change, the value can be declared
    # statically in the class definition. However, the feature is free to
    # change the value at any time. Changing the value to a new
    # **ImageResource** object causes the associated image to be updated on the
    # feature bar. Setting the value to **None** removes the image from the
    # feature bar.
    image = Image()

    # The tooltip to display when the pointer hovers over the image. The value
    # can be changed dynamically to reflect changes in the feature's state.
    tooltip = Str()

    # The x-coordinate of a pointer event that occurred over the feature's
    # image. This can be used in cases where the event-handling for a feature is
    # sensitive to the position of the pointer relative to the feature image.
    # This is not normally the case, but the information is available if it is
    # needed.
    x = Int()

    # The y-coordinate of a pointer event that occurred over the feature's
    # image.
    y = Int()

    # A boolean value that specifies whether the shift key was being held down
    # when a mouse event occurred.
    shift_down = Bool(False)

    # A boolean value that specifies whether the control key was being held down
    # when a mouse event occurred.
    control_down = Bool(False)

    # A boolean value that specifies whether the alt key was being held down
    # when a mouse event occurred.
    alt_down = Bool(False)

    # -- Private Traits -------------------------------------------------------------

    # The current bitmap to display on the feature bar.
    bitmap = Property

    # -- Overridable Public Methods -------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Handles the user left clicking on the feature image:
    # ---------------------------------------------------------------------------

    def click(self):
        """ Handles the user left-clicking on a feature image.

        This method is designed to be overridden by subclasses. The default
        implementation attempts to perform a 'quick drag' operation (see the
        'quick_drag' method). Returns nothing.
        """
        self.quick_drag()

    # ---------------------------------------------------------------------------
    #  Handles the user right clicking on the feature image:
    # ---------------------------------------------------------------------------

    def right_click(self):
        """ Handles the user right-clicking on a feature image.

        This method is designed to be overridden by subclasses. The default
        implementation attempts to perform a 'quick drag' operation (see the
        'quick_right_drag' method). Returns nothing. Typically, you override
        this method to display the feature's shortcut menu.
        """
        self.quick_right_drag()

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user drags the feature image:
    # ---------------------------------------------------------------------------

    def drag(self):
        """ Returns the object to be dragged when the user drags a feature
        image.

        This method can be overridden by subclasses. If dragging is supported
        by the feature, then the method returns the object to be dragged;
        otherwise it returns **None**. The default implementation returns
        **None**.
        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user drags the feature image
    #  while holding down the 'Ctrl' key:
    # ---------------------------------------------------------------------------

    def control_drag(self):
        """ Returns the object to be dragged when the user drags a feature
        image while pressing the 'Ctrl' key.

        This method is designed to be overridden by subclasses. If
        control-dragging is supported by the feature, then the method returns
        the object to be dragged; otherwise it returns **None**. The default
        implementation returns **None**.
        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user drags the feature image
    #  while holding down the 'Shift' key:
    # ---------------------------------------------------------------------------

    def shift_drag(self):
        """ Returns the object to be dragged when the user drags a feature
        image while pressing the 'Shift' key.

        This method is designed to be overridden by subclasses. If
        shift-dragging is supported by the feature, then the method returns
        the object to be dragged; otherwise it returns **None**. The default
        implementation returns **None**.

        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user drags the feature image
    #  while holding down the 'Alt' key:
    # ---------------------------------------------------------------------------

    def alt_drag(self):
        """ Returns the object to be dragged when the user drags a feature
        image while pressing the 'Alt' key.

        This method is designed to be overridden by subclasses. If
        Alt-dragging is supported by the feature, then the method returns
        the object to be dragged; otherwise it returns **None**. The default
        implementation returns **None**.

        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user right mouse button drags
    #  the feature image:
    # ---------------------------------------------------------------------------

    def right_drag(self):
        """ Returns the object to be dragged when the user right mouse button
        drags a feature image.

        This method can be overridden by subclasses. If right dragging is
        supported by the feature, then the method returns the object to be
        dragged; otherwise it returns **None**. The default implementation
        returns **None**.
        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user right mouse button drags
    #  the feature image while holding down the 'Ctrl' key:
    # ---------------------------------------------------------------------------

    def control_right_drag(self):
        """ Returns the object to be dragged when the user right mouse button
        drags a feature image while pressing the 'Ctrl' key.

        This method is designed to be overridden by subclasses. If
        right control-dragging is supported by the feature, then the method
        returns the object to be dragged; otherwise it returns **None**. The
        default implementation returns **None**.
        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user right mouse button drags
    #  the feature image while holding down the 'Shift' key:
    # ---------------------------------------------------------------------------

    def shift_control_drag(self):
        """ Returns the object to be dragged when the user right mouse button
        drags a feature image while pressing the 'Shift' key.

        This method is designed to be overridden by subclasses. If right
        shift-dragging is supported by the feature, then the method returns
        the object to be dragged; otherwise it returns **None**. The default
        implementation returns **None**.

        """
        return None

    # ---------------------------------------------------------------------------
    #  Returns the object to be dragged when the user right mouse button drags
    #  the feature image while holding down the 'Alt' key:
    # ---------------------------------------------------------------------------

    def alt_right_drag(self):
        """ Returns the object to be dragged when the user right mouse button
        drags a feature image while pressing the 'Alt' key.

        This method is designed to be overridden by subclasses. If right
        Alt-dragging is supported by the feature, then the method returns
        the object to be dragged; otherwise it returns **None**. The default
        implementation returns **None**.

        """
        return None

    # ---------------------------------------------------------------------------
    #  Handles the user dropping a specified object on the feature image:
    # ---------------------------------------------------------------------------

    def drop(self, object):
        """ Handles the user dropping a specified object on a feature image.

        Parameters
        ----------
        object : Any object
            The object being dropped onto the feature image

        Returns
        -------
        Nothing.

        Description
        -----------
        This method is designed to be overridden by subclasses. It is called
        whenever the user drops an object on the feature's tab or drag bar
        image. This method can be called only if a previous call to
        **can_drop()** for the same object returned **True**. The default
        implementation does nothing.
        """
        return

    # ---------------------------------------------------------------------------
    #  Returns whether a specified object can be dropped on the feature image:
    # ---------------------------------------------------------------------------

    def can_drop(self, object):
        """ Returns whether a specified object can be dropped on a feature
        image.

        Parameters
        ----------
        object : Any object
            The object being dragged onto the feature image

        Returns
        -------
        **True** if *object* is a valid object for the feature to process;
        **False** otherwise.

        Description
        -----------
        This method is designed to be overridden by subclasses. It is called
        whenever the user drags an icon over the feature's tab or drag bar
        image. The method does not perform any processing on *object*; it only
        examines it. Processing of the object occurs in the **drop()** method,
        which is called when the user release the object over the feature's
        image, which typically occurs after the **can_drop()** method has
        indicated that the feature can process the object, by returning
        **True**. The default implementation returns **False**, indicating that
        the feature does not accept any objects for dropping.
        """
        return False

    # ---------------------------------------------------------------------------
    #  Performs any clean-up needed when the feature is being removed:
    # ---------------------------------------------------------------------------

    def dispose(self):
        """ Performs any clean-up needed when the feature is removed from its
        associated application component (for example, when the user disables
        the feature).

        This method is designed to be overridden by subclasses. The method
        performs any clean-up actions needed by the feature, such as closing
        files, removing trait listeners, and so on. The method does not return
        a result. The default implementation does nothing.
        """
        pass

    # -- Public Methods -------------------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Displays a pop-up menu:
    # ---------------------------------------------------------------------------

    def popup_menu(self, menu):
        """ Displays a shortcut menu.

        Parameters
        ----------
        menu : traitsui.menu.Menu object
            The menu to be displayed

        Returns
        -------
        Nothing.

        Description
        -----------
        This helper method displays the shortcut menu specified by *menu* at a
        point near the feature object's current (x,y) value, as specified by
        the **x** and **y** traits. Normally, the (x,y) value contains the
        screen location where the user clicked on the feature's tab or drag
        bar image. The effect is that the menu is displayed near the feature's
        icon, with the pointer directly over the top menu option.
        """
        window = self.dock_control.control.GetParent()
        wx, wy = window.GetScreenPosition()
        window.PopupMenu(
            menu.create_menu(window, self), self.x - wx - 10, self.y - wy - 10
        )

    # ---------------------------------------------------------------------------
    #  Refreshes the display of the feature image:
    # ---------------------------------------------------------------------------

    def refresh(self):
        """ Refreshes the display of the feature image.

        Returns
        -------
        Nothing.

        Description
        -----------
        This helper method requests the containing DockWindow to refresh the
        feature bar.
        """
        self.dock_control.feature_changed = True

    # ---------------------------------------------------------------------------
    #  Disables the feature:
    # ---------------------------------------------------------------------------

    def disable(self):
        """ Disables the feature.

        Returns
        -------
        Nothing.

        Description
        -----------
        This helper method temporarily disables the feature for the associated
        application component. The feature can be re-enabled by calling the
        **enable()** method. Disabling the feature removes the feature's icon
        from the feature bar, without actually deleting the feature (i.e., the
        **dispose()** method is not called).
        """
        self._image = self.image
        self.image = None
        if self._image is not None:
            self.dock_control.feature_changed = True

    # ---------------------------------------------------------------------------
    #  Enables the feature:
    # ---------------------------------------------------------------------------

    def enable(self):
        """ Enables the feature.

        Returns
        -------
        Nothing.

        Description
        -----------
        This helper method re-enables a previously disabled feature for its
        associated application component. Enabling a feature restores the
        feature bar icon that the feature displayed at the time it was disabled.
        """
        self.image = self._image
        self._image = None
        if self.image is not None:
            self.dock_control.feature_changed = True

    # ---------------------------------------------------------------------------
    #  Performs a quick drag and drop operation by displaying a pop-up menu
    #  containing all targets that the feature's xxx_drag() method can be
    #  dropped on. Selecting an item drops the item on the selected target.
    # ---------------------------------------------------------------------------

    def quick_drag(self):
        """ Performs a quick drag and drop operation by displaying a pop-up menu
            containing all targets that the feature's xxx_drag() method can be
            dropped on. Selecting an item drops the item on the selected target.
        """
        # Get the object that would have been dragged:
        if self.control_down:
            object = self.control_drag()
        elif self.alt_down:
            object = self.alt_drag()
        elif self.shift_down:
            object = self.shift_drag()
        else:
            object = self.drag()

        # If there is an object, pop up the menu:
        if object is not None:
            self._quick_drag_menu(object)

    # ---------------------------------------------------------------------------
    #  Performs a quick drag and drop operation with the right mouse button by
    #  displaying a pop-up menu containing all targets that the feature's
    #  xxx_right_drag() method can be dropped on. Selecting an item drops the
    #  item on the selected target.
    # ---------------------------------------------------------------------------

    def quick_right_drag(self):
        """ Performs a quick drag and drop operation with the right mouse button
            by displaying a pop-up menu containing all targets that the
            feature's xxx_right_drag() method can be dropped on. Selecting an
            item drops the item on the selected target.
        """
        # Get the object that would have been dragged:
        if self.control_down:
            object = self.control_right_drag()
        elif self.alt_down:
            object = self.alt_right_drag()
        elif self.shift_down:
            object = self.shift_right_drag()
        else:
            object = self.right_drag()

        # If there is an object, pop up the menu:
        if object is not None:
            self._quick_drag_menu(object)

    # -- Overridable Class Methods ---------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Returns a single new feature object or list of new feature objects for a
    #  specified DockControl (or None if the feature does not apply to it):
    # ---------------------------------------------------------------------------

    @classmethod
    def feature_for(cls, dock_control):
        """ Returns a single new feature object or list of new feature objects
        for a specified DockControl.

        Parameters
        ----------
        dock_control : pyface.dock.api.DockControl
            The DockControl object that corresponds to the application
            component being added, or for which the feature is being enabled.

        Returns
        -------
        An instance or list of instances of this class that will be associated
        with the application component; **None** if the feature does not apply
        to the application component.

        Description
        -----------
        This class method is designed to be overridden by subclasses. Normally,
        a feature class determines whether it applies to an application
        component by examining the component to see if it is an instance of a
        certain class, supports a specified interface, or has trait attributes
        with certain types of metadata. The application component is available
        through the *dock_control.object* trait attribute. Note that it is
        possible for *dock_control.object* to be **None**.

        The default implementation for this method calls the
        **is_feature_for()** class method to determine whether the feature
        applies to the specified DockControl. If it does, it calls the
        **new_feature()** class method to create the feature instances to be
        returned. If it does not, it simply returns **None**.
        """
        if cls.is_feature_for(dock_control):
            return cls.new_feature(dock_control)

        return None

    # ---------------------------------------------------------------------------
    #  Returns a new feature instance for a specified DockControl:
    # ---------------------------------------------------------------------------

    @classmethod
    def new_feature(cls, dock_control):
        """ Returns a new feature instance for a specified DockControl.

        Parameters
        ----------
        dock_control : pyface.dock.api.DockControl
            The DockControl object that corresponds to the application
            component being added, or for which the feature is being enabled.

        Returns
        -------
        An instance or list of instances of this class to be associated
        with the application component; it can also return **None**.

        Description
        -----------
        This method is designed to be overridden by subclasses. This method is
        called by the default implementation of the **feature_for()** class
        method to create the feature instances to be associated with the
        application component specified by *dock_control*. The default
        implementation returns the result of calling the class constructor as
        follows::

            cls( dock_control=dock_control )

        """
        return cls(dock_control=dock_control)

    # ---------------------------------------------------------------------------
    #  Returns whether or not the DockWindowFeature is a valid feature for a
    #  specified DockControl:
    # ---------------------------------------------------------------------------

    @classmethod
    def is_feature_for(self, dock_control):
        """ Returns whether this class is a valid feature for the application
        object corresponding to a specified DockControl.

        Parameters
        ----------
        dock_control : pyface.dock.api.DockControl
            The DockControl object that corresponds to the application
            component being added, or for which the feature is being enabled.

        Returns
        -------
        **True** if the feature applies to the application object associated
        with the *dock_control*; **False** otherwise.

        Description
        -----------
        This class method is designed to be overridden by subclasses. It is
        called by the default implementation of the **feature_for()** class
        method to determine whether the feature applies to the application
        object specified by *dock_control*. The default implementation always
        returns **True**.
        """
        return True

    # -- Private Methods ------------------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Sets the feature's 'event' traits for a specified mouse 'event':
    # ---------------------------------------------------------------------------

    def _set_event(self, event):
        """ Sets the feature's 'event' traits for a specified mouse 'event'.
        """
        x, y = event.GetEventObject().GetScreenPosition()
        self.trait_set(
            x=event.GetX() + x,
            y=event.GetY() + y,
            shift_down=event.ShiftDown(),
            control_down=event.ControlDown(),
            alt_down=event.AltDown(),
        )

    # ---------------------------------------------------------------------------
    #  Displays the quick drag menu for a specified drag object:
    # ---------------------------------------------------------------------------

    def _quick_drag_menu(self, object):
        """ Displays the quick drag menu for a specified drag object.
        """

        # Get all the features it could be dropped on:
        feature_lists = []
        if isinstance(object, IFeatureTool):
            msg = "Apply to"
            for dc in self.dock_control.dock_controls:
                if dc.visible and (
                    object.feature_can_drop_on(dc.object)
                    or object.feature_can_drop_on_dock_control(dc)
                ):
                    from .feature_tool import FeatureTool

                    feature_lists.append([FeatureTool(dock_control=dc)])
        else:
            msg = "Send to"
            for dc in self.dock_control.dock_controls:
                if dc.visible:
                    allowed = [
                        f
                        for f in dc.features
                        if (f.feature_name != "") and f.can_drop(object)
                    ]
                    if len(allowed) > 0:
                        feature_lists.append(allowed)

        # If there are any compatible features:
        if len(feature_lists) > 0:
            # Create the pop-up menu:
            features = []
            actions = []
            for list in feature_lists:
                if len(list) > 1:
                    sub_actions = []
                    for feature in list:
                        sub_actions.append(
                            Action(
                                name="%s Feature" % feature.feature_name,
                                action="self._drop_on(%d)" % len(features),
                            )
                        )
                        features.append(feature)
                    actions.append(
                        Menu(
                            name="%s the %s"
                            % (msg, feature.dock_control.name),
                            *sub_actions
                        )
                    )
                else:
                    actions.append(
                        Action(
                            name="%s %s" % (msg, list[0].dock_control.name),
                            action="self._drop_on(%d)" % len(features),
                        )
                    )
                    features.append(list[0])

            # Display the pop-up menu:
            self._object = object
            self._features = features
            self.popup_menu(Menu(name="popup", *actions))
            self._object = self._features = None

    # ---------------------------------------------------------------------------
    #  Drops the current object on the feature selected by the user (used by
    #  the 'quick_drag' method:
    # ---------------------------------------------------------------------------

    def _drop_on(self, index):
        """ Drops the current object on the feature selected by the user.
        """
        object = self._object
        if isinstance(object, IFeatureTool):
            dc = self._features[index].dock_control
            object.feature_dropped_on(dc.object)
            object.feature_dropped_on_dock_control(dc)
        else:
            self._features[index].drop(object)

    # -- Public Class Methods -------------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Returns a feature object for use with the specified DockControl (or None
    #  if the feature does not apply to the DockControl object):
    # ---------------------------------------------------------------------------

    @classmethod
    def new_feature_for(cls, dock_control):
        """ Returns a feature object for use with the specified DockControl (or
        **None** if the feature does not apply to the DockControl object).

        """
        result = cls.feature_for(dock_control)
        if result is not None:
            cls.instances = [
                aref for aref in cls.instances if aref() is not None
            ]
            if isinstance(result, DockWindowFeature):
                result = [result]
            cls.instances.extend([ref(feature) for feature in result])

        return result

    # ---------------------------------------------------------------------------
    #  Toggles the feature on/off:
    # ---------------------------------------------------------------------------

    @classmethod
    def toggle_feature(cls, event):
        """ Toggles the feature on or off.
        """
        if cls.state == 0:
            cls.state = 1
            add_feature(cls)
            for control in event.window.control.GetChildren():
                window = getattr(control, "owner", None)
                if isinstance(window, DockWindow):
                    do_later(window.update_layout)
        else:
            method = "disable"
            cls.state = 3 - cls.state
            if cls.state == 1:
                method = "enable"
            cls.instances = [
                aref for aref in cls.instances if aref() is not None
            ]
            for aref in cls.instances:
                feature = aref()
                if feature is not None:
                    getattr(feature, method)()

    # -- Event Handlers -------------------------------------------------------------

    # ---------------------------------------------------------------------------
    #  Handles the 'image' trait being changed:
    # ---------------------------------------------------------------------------

    @observe('image')
    def _reset_bitmap(self, event):
        self._bitmap = None

    # -- Property Implementations ---------------------------------------------------

    def _get_bitmap(self):
        if (self._bitmap is None) and (self.image is not None):
            self._bitmap = self.image.create_image().ConvertToBitmap()

        return self._bitmap

    # -- Pyface menu interface implementation ---------------------------------------

    # ---------------------------------------------------------------------------
    #  Adds a menu item to the menu bar being constructed:
    # ---------------------------------------------------------------------------

    def add_to_menu(self, menu_item):
        """ Adds a menu item to the menu bar being constructed.
        """
        pass

    # ---------------------------------------------------------------------------
    #  Adds a tool bar item to the tool bar being constructed:
    # ---------------------------------------------------------------------------

    def add_to_toolbar(self, toolbar_item):
        """ Adds a tool bar item to the tool bar being constructed.
        """
        pass

    # ---------------------------------------------------------------------------
    #  Returns whether the menu action should be defined in the user interface:
    # ---------------------------------------------------------------------------

    def can_add_to_menu(self, action):
        """ Returns whether the action should be defined in the user interface.
        """
        return True

    # ---------------------------------------------------------------------------
    #  Returns whether the toolbar action should be defined in the user
    #  interface:
    # ---------------------------------------------------------------------------

    def can_add_to_toolbar(self, action):
        """ Returns whether the toolbar action should be defined in the user
            interface.
        """
        return True

    # ---------------------------------------------------------------------------
    #  Performs the action described by a specified Action object:
    # ---------------------------------------------------------------------------

    def perform(self, action):
        """ Performs the action described by a specified Action object.
        """
        action = action.action
        if action[:5] == "self.":
            eval(action, globals(), {"self": self})
        else:
            getattr(self, action)()