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.
DragTool¶
The 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 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 DragTool
subclass that allows a user to move a component around
its container by dragging.
ResizeTool¶
A DragTool
subclass that allows a user to resize a component by
dragging from the edges of the component.
ValueDragTool¶
A DragTool
subclass that allows a drag operation to set an
arbitrary value.
Undo/Redo Support¶
The enable.tools.pyface package has a number of modules that provide classes for working with Pyface’s Undo/Redo stack. This permits Enable tools to add Commands to the Undo/Redo stack, and provides variants of the MoveTool and ResizeTool that are undoable.
In addition, a tool is provided which binds keystrokes to send undo and redo requests to the Pyface UndoManager.
High-Level Tools¶
There are three tools that provide convenient facilities and reference implementations of interacting with the undo/redo stack.
UndoTool¶
The
UndoTool
binds keystrokes to undo and redo operations. Theundo_keys
andredo_keys
attributes each take a list ofKeySpec
objects which should trigger the relevant operations. The default values bind undo to ‘Ctrl+Z’ and redo to ‘Ctrl+Shift+Z’.The
UndoTool
must be provided with anIUndoManager
that will actually perform the undo and redo operations.For example, to bind undo to ‘Ctrl+Left arrow’, and redo to ‘Ctrl+Right arrow’:
undo_tool = UndoTool( my_component, undo_manager=my_undo_manager, undo_keys=[KeySpec('Left', 'control')], redo_keys=[KeySpec('Right', 'control')] ) my_component.tools.append(undo_tool)
MoveCommandTool¶
The
MoveCommandTool
is a subclass ofMoveTool
that by default issues aMoveCommand
at the end of every successful drag move. AMoveCommand
stores the new and previous position of the component so that it can undo and redo the move. TheMoveCommandTool
needs to be provided with anICommandStack
instance that it will push commands to, but is otherwise identical to the usualMoveTool
.The command tool has a
mergeable
attribute which indicates whether subsequent move operations with the same component immediately following this one can be merged into one single move operation.Typical usage would be something like this:
move_tool = MoveCommandTool(my_component, command_stack=my_command_stack) my_component.tools.append(move_tool)Users of the tool can provide a different factory to create appropriate
Command
instances by setting thecommand
trait to a callable that should expect keyword argumentscomponent
,data
(the new position),previous_position
, andmergeable
.
ResizeCommandTool¶
The
ResizeCommandTool
is a subclass ofResizeTool
that issuesResizeCommand
s at the end of every successful drag move. AResizeCommand
stores the new and previous position and bounds of the component so that it can undo and redo the resize. TheResizeCommandTool
needs to be provided with anICommandStack
instance that it will push commands to, but is otherwise identical to the usualResizeTool
.The command tool has a
mergeable
attribute which indicates whether subsequent resize operations with the same component immediately following this one can be merged into one single resize operation.Typical usage would be something like this:
move_tool = ResizeTool(my_component, command_stack=my_command_stack) my_component.tools.append(move_tool)Users of the tool can provide a different factory to create appropriate
Command
instances by setting thecommand
trait to a callable that should expect keyword argumentscomponent
,data
(the new rectangle as a tuple(x, y, width, height)
),previous_rectangle
, andmergeable
.
Command Classes¶
The library provides some useful Command
subclasses that users may want
to create specialized instances or subclass to customize the behaviour
of their applications. They may also be of use to CommandAction
subclasses
outside of the Enable framework (such as menu items or toolbar buttons) which
want to interact with Enable components.
ResizeCommand
This command handles changing the size of a component. The constructor expects arguments
component
,new_rectangle
and (optionally)previous_rectangle
, plus optional additional traits. Ifprevious_rectangle
is not provided, then the component’s current rectangle is used.Instances hold references to the
Component
being resized in thecomponent
attribute, the new and previous rectangles of the component as tuples(x, y, width, height)
in thedata
andprevious_rectangle
attributes, and whether or not subsequent resize operations on the same component should be merged together.The tool handles the logic of changing the position and bounds of the component appropriately, as well as invalidating layout and requesting redraws.
It also provides a default
name
attribute ofResize `` plus the ``component_name
(which in turn defaults to a more human-readable variant of the component’s class). Instances can improve this by either supplying a full replacement for thename
attribute, or for thecomponent_name
.Finally, there is a
move_command
class method that creates aResizeCommand
that just performs a move and is suitable as the command factory of aMoveCommandTool
, which allows easy merging between resize and move operations, if required for the application.
MoveCommand
This command handles changing the position of a component. The constructor expects arguments
component
,previous_position
and (optionally)new_position
, plus optional additional traits. Ifnew_position
is not provided, then the component’s current position is used.Instances hold references to the
Component
being moved in thecomponent
attribute, the new and previous positions of the component as tuples(x, y)
in thedata
andprevious_position
attributes, and whether or not subsequent move operations on the same component should be merged together.The tool handles the logic of changing the position of the component appropriately, as well as invalidating layout and requesting redraws.
It also provides a default
name
attribute ofMove `` plus the ``component_name
(which in turn defaults to a more human-readable variant of the component’s class). Instances can improve this by either supplying a full replacement for thename
attribute, or for thecomponent_name
.
Base Classes¶
There are two simple base classes of tools that are potentially of use to authors of new tools.
BaseUndoTool
Tools which need to be able to trigger undo and redo actions, or otherwise interact with an undo manager (for example, to set the current command stack or clear the command history) can inherit from this class.
It has an
undo_manager
attribute which holds a reference to anIUndoManager
and provides convenience methods forundo
andredo
using the undo manager.
BaseCommandTool
Tools which need to perform undoable actions may want to inherit from this class. It provides a standard
command_stack
attribute which holds a reference to anICommandStack
. It also has acommand
callable trait that can be overriden by subclasses to create an appropriate command when demanded by the UI.
In addition to these simple base tools, authors of Tools or Actions that
perform undoable operations on Enable or Chaco components may want to make use
of the following Command
subclass:
ComponentCommand
This class is an abstract base class for commands which act on Enable
Components
. It provides acomponent
attribute which holds a reference to the component that the command should be performed on, and acomponent_name
attribute that can be used to help build thename
of theCommand
to be used in textual representations of the command (eg. in menu item labels).The default
component_name
is just a more human-friendly version of the component’s class name, with camel-case converted to words. Users are encouraged to override with something even more user-friendly.