Merge pull request #162 from nucleic/feature-dragdrop

Feature dragdrop

enaml/application.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2013, Nucleic Development Team.
+# Copyright (c) 2014, Nucleic Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
@@ -308,6 +308,17 @@ def is_main_thread(self):
         """
         raise NotImplementedError
 
+    def create_mime_data(self):
+        """ Create a new mime data object to be filled by the user.
+
+        Returns
+        -------
+        result : MimeData
+            A concrete implementation of the MimeData class.
+
+        """
+        raise NotImplementedError
+
     #--------------------------------------------------------------------------
     # Public API
     #--------------------------------------------------------------------------

enaml/drag_drop.py

@@ -0,0 +1,179 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014, Nucleic Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#------------------------------------------------------------------------------
+from atom.api import Atom, IntEnum, Typed, Coerced
+
+from .application import Application
+from .image import Image
+from .mime_data import MimeData
+
+
+class DropAction(IntEnum):
+    """ An enum defining the possible drop actions.
+
+    """
+    #: The action is ignored.
+    Ignore = 0x0
+
+    #: The data is copied to the target.
+    Copy = 0x1
+
+    #: The data is moved from the source to the target.
+    Move = 0x2
+
+    #: Create a link from the source to the target.
+    Link = 0x4
+
+
+def mime_data_factory():
+    """ Create a new MimeData object for a drag operation.
+
+    Returns
+    -------
+    result : MimeData
+        A toolkit specific mime data object.
+
+    """
+    return Application.instance().create_mime_data()
+
+
+class DragData(Atom):
+    """ An object which initialize the data for a drag operation.
+
+    """
+    #: The mime data to use for the drag operation. This is created
+    #: automatically, but can be reassigned by the user if necessary.
+    mime_data = Typed(MimeData, factory=mime_data_factory)
+
+    #: The default drop action for the drag data. If not provided,
+    #: the toolkit will choose a suitable default from among the
+    #: supported action.
+    default_drop_action = Coerced(DropAction, (DropAction.Ignore,))
+
+    #: The supported drop actions of the drag data. This is an OR'd
+    #: combination of the available DropAction flags.
+    supported_actions = Coerced(DropAction.Flags, (DropAction.Move,))
+
+    #: The image to use for the drag. If this is not provided, the
+    #: toolkit will choose a suitable default value.
+    image = Typed(Image)
+
+
+class DropEvent(Atom):
+    """ An abstract class for defining a drag event.
+
+    Concrete implementations of this class will be created by a
+    toolkit backend and passed to the relevant frontend handlers.
+
+    Instances of this class will never be created by the user.
+
+    """
+    def pos(self):
+        """ Get the current mouse position of the operation.
+
+        Returns
+        -------
+        result : Pos
+            The mouse position of the operation in widget coordinates.
+
+        """
+        raise NotImplementedError
+
+    def mime_data(self):
+        """ Get the mime data contained in the drag operation.
+
+        Returns
+        -------
+        result : MimeData
+            The mime data contained in the drag operation.
+
+        """
+        raise NotImplementedError
+
+    def drop_action(self):
+        """ Get the action to be performed by the drop target.
+
+        Returns
+        -------
+        result : DropAction
+            A drop action enum value.
+
+        """
+        raise NotImplementedError
+
+    def possible_actions(self):
+        """ Get the OR'd combination of possible drop actions.
+
+        Returns
+        -------
+        result : DropAction.Flags
+            The combination of possible drop actions.
+
+        """
+        raise NotImplementedError
+
+    def proposed_action(self):
+        """ Get the action proposed to be taken by the drop target.
+
+        Returns
+        -------
+        result : DropAction
+            The proposed action for the drop target.
+
+        """
+        raise NotImplementedError
+
+    def accept_proposed_action(self):
+        """ Accept the event using the proposed drop action.
+
+        """
+        raise NotImplementedError
+
+    def set_drop_action(self, action):
+        """ Set the drop action to one of the possible actions.
+
+        Parameters
+        ----------
+        action : DropAction
+            The drop action to be performed by the target.
+
+        """
+        raise NotImplementedError
+
+    def is_accepted(self):
+        """ Test whether the event has been accepted.
+
+        Returns
+        -------
+        result : bool
+            True if the event is accepted, False otherwise.
+
+        """
+        raise NotImplementedError
+
+    def set_accepted(self, accepted):
+        """ Set the accepted state of the event.
+
+        Parameters
+        ----------
+        accepted : bool
+            The target accepted state of the event.
+
+        """
+        raise NotImplementedError
+
+    def accept(self):
+        """ Accept the current drop event action.
+
+        """
+        raise NotImplementedError
+
+    def ignore(self):
+        """ Ignore the current drop event action.
+
+        """
+        raise NotImplementedError

enaml/mime_data.py

@@ -0,0 +1,88 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014, Nucleic Development Team.
+#
+# Distributed under the terms of the Modified BSD License.
+#
+# The full license is in the file COPYING.txt, distributed with this software.
+#------------------------------------------------------------------------------
+from atom.api import Atom
+
+
+class MimeData(Atom):
+    """ An abstract class for defining mime data.
+
+    Concrete implementations of this class will be created by a
+    toolkit backend and passed to the relevant frontend methods.
+
+    This will never be instantiated directly by user code. A concrete
+    version can be created by calling the `create_mime_data` factory
+    method of an Application instance.
+
+    """
+    def formats(self):
+        """ Get a list of the supported mime type formats.
+
+        Returns
+        -------
+        result : list
+            A list of mime types supported by the data.
+
+        """
+        raise NotImplementedError
+
+    def has_format(self, mime_type):
+        """ Test whether the data supports the given mime type.
+
+        Parameters
+        ----------
+        mime_type : unicode
+            The mime type of interest.
+
+        Returns
+        -------
+        result : bool
+            True if there is data for the given type, False otherwise.
+
+        """
+        raise NotImplementedError
+
+    def remove_format(self, mime_type):
+        """ Remove the data entry for the given mime type.
+
+        Parameters
+        ----------
+        mime_type : unicode
+            The mime type of interest.
+
+        """
+        raise NotImplementedError
+
+    def data(self, mime_type):
+        """ Get the data for the specified mime type.
+
+        Parameters
+        ----------
+        mime_type : unicode
+            The mime type of interest.
+
+        Returns
+        -------
+        result : str
+            The data for the specified mime type.
+
+        """
+        raise NotImplementedError
+
+    def set_data(self, mime_type, data):
+        """ Set the data for the specified mime type.
+
+        Parameters
+        ----------
+        mime_type : unicode
+            The mime type of interest.
+
+        data : str
+            The serialized data for the given type.
+
+        """
+        raise NotImplementedError

enaml/qt/qt_application.py

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2013, Nucleic Development Team.
+# Copyright (c) 2014, Nucleic Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
@@ -14,6 +14,7 @@
 
 from .q_deferred_caller import deferredCall, timedCall
 from .qt_factories import QT_FACTORIES
+from .qt_mime_data import QtMimeData
 
 
 class QtApplication(Application):
@@ -101,3 +102,14 @@ def is_main_thread(self):
 
         """
         return QThread.currentThread() == self._qapp.thread()
+
+    def create_mime_data(self):
+        """ Create a new mime data object to be filled by the user.
+
+        Returns
+        -------
+        result : QtMimeData
+            A concrete implementation of the MimeData class.
+
+        """
+        return QtMimeData()