Skip to content

Commit

Permalink
Add button tool, tests, docs, and mouse_enter handler to testing.
Browse files Browse the repository at this point in the history
  • Loading branch information
corranwebster committed Jan 20, 2015
1 parent 0b881f4 commit fc6dda7
Show file tree
Hide file tree
Showing 6 changed files with 625 additions and 1 deletion.
71 changes: 71 additions & 0 deletions docs/source/enable_basic_tools.rst
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
48 changes: 47 additions & 1 deletion enable/testing.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down Expand Up @@ -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.
Expand Down
Loading

0 comments on commit fc6dda7

Please sign in to comment.