Merge fc6dda7 into 0b881f4

docs/source/enable_basic_tools.rst

@@ -0,0 +1,71 @@
+Enable Tools
+============
+
+Enable ``Tools`` are ``Interator`` subclasses that do not have to have any
+visual representation, and which can be dynamically added and removed from
+components by adding or removing them from the component's ``tools`` list.
+This permits developers to quickly build up complex behaviours from simple,
+reproducible parts without having complex inheritance hierarchies.
+
+Basic Tools
+-----------
+
+Enable provides a number of basic tools for common interactions.
+
+ButtonTool
+~~~~~~~~~~
+
+The :py:class:`ButtonTool` provides basic push-button or checkbox
+interactions, depending on how it is configured.  The primary interface it
+provides is a :py:attr:`clicked` event which is fired when the user clicks in
+the region of the underlying component, or when the :py:meth:`click` method is
+called.  The :py:attr:`clicked` event is fired on mouse up.
+
+To get checkbox-style behaviour, set :py:attr:`togglable` to ``True`` and
+then every click will invert the :py:attr:`checked` trait.  The toggle state
+can also be  changed via the :py:meth:`toggle` method, which does not fire the
+:py:attr:`clicked` event when called.  For buttons with multi-state toggles,
+subclasses can override the :py:meth:`toggle` method to perform more complex
+state changes.
+
+By default, the tool responds to clicks that are within the associated
+component, but subclasses can override this behaviour by replacing the
+:py:method:``is_clickable`` method with something else.
+
+It will commonly be the case that components or :py:class:`ButtonTool`
+subclasses which draw may wish to respond to user interactions by drawing
+themselves in a highlighted or selected mode when the mouse is down inside
+the button region.  The :py:attr:`down` trait provides this information
+conveniently, so that users of the tool can change their drawing state and
+request redraws when it changes.
+
+DragTool
+~~~~~~~~
+
+The :py:class:`DragTool` is an abstract base class that provides basic
+interaction support for draging within Enable.  Many other tools within
+Enable and Chaco use it.
+
+HoverTool
+~~~~~~~~~
+
+The :py:class:`HoverTool` is a simple tool that calls a callback when the
+mouse has been held steadily over the component for a period of time.
+
+MoveTool
+~~~~~~~~
+
+A :py:class:`DragTool` subclass that allows a user to move a component around
+its container by dragging.
+
+ResizeTool
+~~~~~~~~~~
+
+A :py:class:`DragTool` subclass that allows a user to resize a component by
+dragging from the edges of the component.
+
+ValueDragTool
+~~~~~~~~~~~~~
+
+A :py:class:`DragTool` that allows a drag operation to set an arbitrary
+value.

docs/source/index.rst

@@ -7,6 +7,7 @@ Enable Documentation
   enable_concepts.rst
   enable_constraints_layout.rst
   enable_key_events.rst
+  enable_basic_tools.rst
   enable_drag_and_drop.rst
 
   kiva.rst

enable/testing.py

@@ -308,7 +308,7 @@ def mouse_up(self, interactor, x, y, button='left', window=None,
 
     def mouse_leave(self, interactor, x, y, window=None,
                     alt_down=False, control_down=False, shift_down=False):
-        """ Send a mouse click event to the interactor.
+        """ Send a mouse leave event to the interactor.
 
         Parameters
         ----------
@@ -352,6 +352,52 @@ def mouse_leave(self, interactor, x, y, window=None,
         self._mouse_event_dispatch(interactor, event, 'mouse_leave')
         return event
 
+    def mouse_enter(self, interactor, x, y, window=None,
+                    alt_down=False, control_down=False, shift_down=False):
+        """ Send a mouse enter event to the interactor.
+
+        Parameters
+        ----------
+        interactor : Interactor
+            The interactor (or subclass) where to dispatch the event.
+
+        x : float
+            The x coordinates of the mouse position
+
+        y : float
+            The y coordinates of the mouse position
+
+        window : AbstractWindow, optional
+            The enable AbstractWindow to associate with the event. Default
+            is to create a mock class instance. If the window has a mouse
+            owner then that interactor is used.
+
+        alt_down : boolean, optional
+            The button is pressed while `alt` is down. Default value is False.
+
+        control_down : boolean, optional
+            The button is pressed while `control` is down. Default value is
+            False.
+
+        shift_down : boolean, optional
+            The button is pressed while `shift` is down. Default value is
+            False.
+
+        Returns
+        -------
+        event : MouseEvent
+            The event instance after it has be processed by the `interactor`.
+
+        """
+        window = self.create_mock_window() if window is None else window
+        event = self.create_mouse_event(x=x, y=y,
+                                        window=window,
+                                        alt_down=alt_down,
+                                        control_down=control_down,
+                                        shift_down=shift_down)
+        self._mouse_event_dispatch(interactor, event, 'mouse_enter')
+        return event
+
     def send_key(self, interactor, key, window=None):
         """ Sent a key press event to the interactor.