Tools

BetterZoom

class chaco.tools.api.BetterZoom(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool, chaco.tools.tool_history_mixin.ToolHistoryMixin

Traits:

zoom_in_key : Instance(KeySpec, args=(‘+’), kw={‘ignore’: [‘shift’]})

Keys to zoom in/out

zoom_out_key : Instance(KeySpec, args=(‘-‘))

zoom_in_x_key : Instance(KeySpec, args=(‘Right’, ‘shift’))

Keys to zoom in/out in x direction only

zoom_out_x_key : Instance(KeySpec, args=(‘Left’, ‘shift’))

zoom_in_y_key : Instance(KeySpec, args=(‘Up’, ‘shift’))

Keys to zoom in/out in y direction only

zoom_out_y_key : Instance(KeySpec, args=(‘Down’, ‘shift’))

prev_state_key : Instance(KeySpec, args=(‘z’, ‘control’))

Key to go to the previous state in the history.

next_state_key : Instance(KeySpec, args=(‘y’, ‘control’))

Key to go to the next state in the history.

enable_wheel : Bool(True)

Enable the mousewheel for zooming?

zoom_to_mouse : Bool(True)

if the mouse pointer should be used to control the center of the zoom action

keys_zoom_to_mouse : Bool(True)

if the mouse pointer should be used to control the center of the zoom action even for key events based zoom

axis : Enum(‘both’, ‘index’, ‘value’)

The axis to which the selection made by this tool is perpendicular. This only applies in ‘range’ mode.

x_max_zoom_factor : Float(100000.0)

The maximum ratio between the original data space bounds and the zoomed-in data space bounds. If No limit is desired, set to inf

y_max_zoom_factor : Float(100000.0)

x_min_zoom_factor : Float(1e-05)

The maximum ratio between the zoomed-out data space bounds and the original bounds. If No limit is desired, set to -inf

y_min_zoom_factor : Float(1e-05)

zoom_factor : Float(2.0)

The amount to zoom in by. The zoom out will be inversely proportional

position : Tuple(Float, Float)

: the position to zoom on (usually the mouse location)

normal_key_pressed(event)

Handles a key being pressed when the tool is in the ‘normal’ state.

normal_mouse_enter(event)

Try to set the focus to the window when the mouse enters, otherwise the keypress events will not be triggered.

position = None

BetterSelectingZoom

class chaco.tools.api.BetterSelectingZoom(component=None, *args, **kw)

Bases: chaco.abstract_overlay.AbstractOverlay, chaco.tools.better_zoom.BetterZoom

Zooming tool which allows the user to draw a box which defines the desired region to zoom in to

Traits:

tool_mode : Enum(‘box’, ‘range’)

The selection mode:

range:

Select a range across a single index or value axis.

box:

Perform a “box” selection on two axes.

always_on : Bool(False)

Is the tool always “on”? If True, left-clicking always initiates a zoom operation; if False, the user must press a key to enter zoom mode.

always_on_modifier : Enum(‘control’, ‘shift’, ‘control’, ‘alt’)

Defines a meta-key, that works with always_on to set the zoom mode. This is useful when the zoom tool is used in conjunction with the pan tool.

drag_button : Enum(‘left’, ‘right’, None)

The mouse button that initiates the drag. If “None”, then the tool will not respond to drag. (It can still respond to mousewheel events.)

minimum_screen_delta : Int(10)

The minimum amount of screen space the user must select in order for the tool to actually take effect.

wheel_zoom_step : Property(Float, depends_on=’zoom_factor’)

Conversion ratio from wheel steps to zoom factors.

enter_zoom_key : Instance(KeySpec, args=(‘z’))

The key press to enter zoom mode, if always_on is False. Has no effect if always_on is True.

exit_zoom_key : Instance(KeySpec, args=(‘z’))

The key press to leave zoom mode, if always_on is False. Has no effect if always_on is True.

disable_on_complete : Property()

Disable the tool after the zoom is completed?

pointer : ‘magnifier’

The pointer to use when drawing a zoom box.

color : ColorTrait(‘lightskyblue’)

The color of the selection box.

alpha : Trait(0.4, None, Float)

The alpha value to apply to color when filling in the selection region. Because it is almost certainly useless to have an opaque zoom rectangle, but it’s also extremely useful to be able to use the normal named colors from Enable, this attribute allows the specification of a separate alpha value that replaces the alpha value of color at draw time.

border_color : ColorTrait(‘dodgerblue’)

The color of the outside selection rectangle.

border_size : Int(1)

The thickness of selection rectangle border.

event_state : Enum(‘normal’, ‘selecting’, ‘pre_selecting’)

The possible event states of this zoom tool.

normal_key_pressed(event)

Handles a key being pressed when the tool is in the ‘normal’ state.

normal_left_down(event)

Handles the left mouse button being pressed while the tool is in the ‘normal’ state.

If the tool is enabled or always on, it starts selecting.

normal_right_down(event)

Handles the right mouse button being pressed while the tool is in the ‘normal’ state.

If the tool is enabled or always on, it starts selecting.

overlay(component, gc, view_bounds=None, mode='normal')

Draws this component overlaid on another component.

Overrides AbstractOverlay.

pre_selecting_key_pressed(event)

Handle key presses, specifically the exit zoom key

pre_selecting_left_down(event)

The user pressed the key to turn on the zoom mode, now handle the click to start the select mode

reset(event=None)

Resets the tool to normal state, with no start or end position.

selecting_key_pressed(event)

Handle key presses, specifically the exit zoom key

selecting_left_up(event)

Handles the left mouse button being released when the tool is in the ‘selecting’ state.

Finishes selecting and does the zoom.

selecting_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘selecting’ state.

Ends the selection operation without zooming.

selecting_mouse_move(event)

Handles the mouse moving when the tool is in the ‘selecting’ state.

The selection is extended to the current mouse position.

selecting_right_up(event)

Handles the right mouse button being released when the tool is in the ‘selecting’ state.

Finishes selecting and does the zoom.

BroadcasterTool

class chaco.tools.api.BroadcasterTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

A simple tool that keeps a list of other tools, and broadcasts events it receives to all of the tools.

Traits:

tools : List

The tools to which this tool broadcasts events.

mouse_owners : Dict

Mapping from tools to transforms, for tools that can be mouse owners. (See enable.AbstractWindow.)

dispatch(event, suffix)

Dispatches a mouse event based on the current event state.

Overrides BaseTool.

DataPrinter

class chaco.tools.api.DataPrinter(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

Simple listener tool that prints the (x,y) data space position of the point under the cursor.

Traits:

visible : False

This tool is a listener, and does not display anything (overrides BaseTool).

draw_mode : ‘none’

Turn off drawing, because the tool prints to stdout.

format : Str(‘(%.3f, %.3f)’)

The string to format the (x,y) value in data space.

normal_mouse_move(event)

Handles the mouse being moved in the ‘normal’ state.

Prints the data space position of the current mouse position.

DataLabelTool

class chaco.tools.api.DataLabelTool(component=None, **kwtraits)

Bases: enable.tools.drag_tool.DragTool

A tool for dragging a data label.

Attach this tool to a DataLabel object by setting the tool’s component to the DataLabel.

Traits:

drag_button : Enum(‘left’, ‘right’)

The mouse button that initiates the drag.

auto_arrow_root : Bool(True)

Use the root of the label’s arrow (if any) as the closest corner of the label?

drag_end(event)

Called when a mouse event causes the drag operation to end.

Implements DragTool.

drag_start(event)

Called when the drag operation starts.

Implements DragTool.

dragging(event)

This method is called for every mouse_move event that the tool receives while the user is dragging the mouse.

Implements DragTool. Moves and redraws the label.

is_draggable(x, y)

Returns whether the (x,y) position is in a region that is OK to drag.

Overrides DragTool.

DragTool

class chaco.tools.api.DragTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

Base class for tools that are activated by a drag operation.

This tool insulates the drag operation from double clicks and the like, and gracefully manages the transition into and out of drag mode.

Traits:

drag_button : Enum(‘left’, ‘right’)

The mouse button used for this drag operation.

end_drag_on_leave : Bool(True)

End the drag operation if the mouse leaves the associated component?

cancel_keys : List(Str, [‘Esc’])

These keys, if pressed during drag, cause the drag operation to reset.

mouse_down_position : Tuple(0.0, 0.0)

The position of the initial mouse click that started the drag. Typically, tools that move things around use this position to do hit-testing to determine what object to “pick up”.

modifier_key : Enum(‘none’, ‘shift’, ‘alt’, ‘control’)

The modifier key that must be used to activate the tool.

capture_mouse : Bool(True)

Whether or not to capture the mouse during the drag operation. In general this is a good idea.

drag_cancel(event)

Called when the drag is cancelled.

A drag is usually cancelled by receiving a mouse_leave event when end_drag_on_leave is True, or by the user pressing any of the cancel_keys.

drag_end(event)

Called when a mouse event causes the drag operation to end.

drag_start(event)

Called when the drag operation starts.

The event parameter is the mouse event that established the drag operation; its x and y attributes correspond to the current location of the mouse, and not to the position of the mouse when the initial left_down or right_down event happened.

dragging(event)

This method is called for every mouse_move event that the tool receives while the user is dragging the mouse.

It is recommended that subclasses do most of their work in this method.

is_draggable(x, y)

Returns whether the (x,y) position is in a region that is OK to drag.

Used by the tool to determine when to start a drag.

DrawPointsTool

class chaco.tools.api.DrawPointsTool(**kwtraits)

Bases: enable.base_tool.BaseTool

A tool that draws points onto a rectangular plot as they are clicked.

Traits:

xdata : Instance(ArrayDataSource)

A data source for the x-dimension of the drawn points.

ydata : Instance(ArrayDataSource)

A data source for the y-dimension of the drawn points.

activated : Bool(True)

Is this the active tool?

normal_left_down(event)

Handles the left mouse button being clicked when the tool is in the ‘normal’ state.

Maps the event position into data space, adds the point to the points for this tool, and redraws.

DragZoom

class chaco.tools.api.DragZoom(component=None, *args, **kw)

Bases: enable.tools.drag_tool.DragTool, chaco.tools.better_zoom.BetterZoom

A zoom tool that zooms continuously with a mouse drag movement, instead of using a zoom box or range.

By default, the tool maintains aspect ratio and zooms the plot’s X and Y axes by the same amount as the user drags up and down. (In this default configuration, the horizontal position of the drag motion has no effect.)

By setting maintain_aspect_ratio to False, this tool will separably zoom the X and Y axis ranges by the (possibly different) horizontal and vertical drag motions. This is similar to the drag zoom interaction in Matplotlib.

By setting single_axis to True, dragging will only zoom in the axis specified by the axis attribute.

By setting restrict_domain to True, the zoom will be limited to the domain of the axis mappers.

Traits:

drag_button : Enum(‘left’, ‘right’, ‘middle’)

The mouse button that initiates the drag

speed : Float(1.0)

Scaling factor on the zoom “speed”. A speed of 1.0 implies a zoom rate of 5% for every 10 pixels.

maintain_aspect_ratio : Bool(True)

Whether or not to preserve the aspect ratio of X to Y while zooming in. (See class docstring for more info.)

drag_pointer : ‘magnifier’

The pointer to use when we’re in the act of zooming

single_axis : Bool(False)

Whether or not to zoom in one axis only

restrict_domain : Bool(False)

Whether to restrict zoom to the domain of the mappers

zoom_to_mouse : Bool(False)

HighlightTool

class chaco.tools.api.HighlightTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

A tool that enables the user to select a plot to be highlighted on the graph by clicking on it.

Traits:

metadata_name : Str(‘selections’)

The name of the data source metadata which controls selections.

drag_button : Enum(‘left’, ‘right’)

The mouse button that initiates the selection.

threshold : Float(20.0)

Threshold distance for hit-testing.

draw_mode : ‘none’

This tool is not drawn. Overrides BaseTool.

visible : False

This tool is not visible. Overrides BaseTool.

normal_left_down(event)

Handles the left mouse button being pressed.

If the left mouse button initiates the selection, this method does so.

normal_right_down(event)

Handles the right mouse button being pressed.

If the right mouse button initiates the selection, this method does so.

ImageInspectorTool

class chaco.tools.api.ImageInspectorTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

A tool that captures the color and underlying values of an image plot.

Traits:

new_value : Event

This event fires whenever the mouse moves over a new image point. Its value is a dict with a key “color_value”, and possibly a key “data_value” if the plot is a color-mapped image plot.

visible : Bool(True)

Indicates whether overlays listening to this tool should be visible.

last_mouse_position : Tuple

Stores the last mouse position. This can be used by overlays to position themselves around the mouse.

inspector_key : KeySpec(‘p’)

This key will show and hide any ImageInspectorOverlays associated with this tool.

normal_mouse_move(event)

Handles the mouse being moved.

Fires the new_value event with the data (if any) from the event’s position.

ImageInspectorOverlay

class chaco.tools.api.ImageInspectorOverlay(component=None, *args, **kw)

Bases: chaco.text_box_overlay.TextBoxOverlay

An overlay that displays a box containing values from an ImageInspectorTool instance.

Traits:

image_inspector : Any

An instance of ImageInspectorTool; this overlay listens to the tool for changes, and updates its displayed text accordingly.

tooltip_mode : Bool(False)

Anchor the text to the mouse? (If False, then the text is in one of the corners.) Use the align trait to determine which corner.

visible : False

The default state of the overlay is invisible (overrides PlotComponent).

visibility : Enum(‘auto’, True, False)

Whether the overlay should auto-hide and auto-show based on the tool’s location, or whether it should be forced to be hidden or visible.

LassoSelection

class chaco.tools.api.LassoSelection(component, *args, **kw)

Bases: chaco.abstract_controller.AbstractController

A controller that represents the interaction of “lassoing” a set of points.

“Lassoing” means drawing an arbitrary selection region around the points by dragging the mouse along the outline of the region.

Traits:

dataspace_points : Property(Array)

An Nx2 array of points in data space representing all selected points.

disjoint_selections : Property(List)

A list of all the selection polygons.

updated : Event

Fires whenever dataspace_points changes, necessitating a redraw of the selection region.

selection_changed : Event

Fires when the selection mask changes.

selection_completed : Event

Fires when the user release the mouse button and finalizes the selection.

incremental_select : Bool(False)

If True, the selection mask is updated as the mouse moves, rather than only at the beginning and end of the selection operation.

selection_mode : Enum(‘include’, ‘exclude’, ‘invert’)

The selection mode of the lasso pointer: “include”, “exclude” or “invert” points from the selection. The “include” and “exclude” settings essentially invert the selection mask. The “invert” setting differs from “exclude” in that “invert” inverses the selection of all points the the lasso’ed polygon, while “exclude” operates only on points included in a previous selection.

selection_datasource : Instance(AbstractDataSource)

The data source that the mask of selected points is attached to. Note that the indices in this data source must match the indices of the data in the plot.

metadata_name : Str(‘selection’)

The name of the metadata on the datasource that we will write the selection mask to

plot : Property

Mapping from screen space to data space. By default, it is just self.component.

drag_button : Enum(‘left’, ‘right’)

The button which this tool responds to

event_state : Enum(‘normal’, ‘selecting’)

The possible event states of this selection tool (overrides enable.Interactor).

normal:

Nothing has been selected, and the user is not dragging the mouse.

selecting:

The user is dragging the mouse and is actively changing the selection region.

normal_key_pressed(event)

Handles the user pressing a key in the ‘normal’ state.

If the user presses the Escape key, the tool is reset.

normal_mouse_down(event)

Handles the left mouse button being pressed while the tool is in the ‘normal’ state.

Puts the tool into ‘selecting’ mode, and starts defining the selection.

selecting_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘selecting’ state.

Ends the selection operation.

selecting_mouse_move(event)

Handles the mouse moving when the tool is in the ‘selecting’ state.

The selection is extended to the current mouse position.

selecting_mouse_up(event)

Handles the mouse button coming up in the ‘selecting’ state.

Completes the selection and switches to the ‘normal’ state.

LegendTool

class chaco.tools.api.LegendTool(component=None, **kwtraits)

Bases: enable.tools.drag_tool.DragTool

A tool for interacting with legends.

Attach this tool to a legend by setting the tool’s component to the legend.

Traits:

drag_button : Enum(‘left’, ‘right’)

The mouse button that initiates the drag.

auto_align : Bool(True)

Whether to change the legend’s align property in accord with the quadrant into which it is dropped.

drag_end(event)

Called when a mouse event causes the drag operation to end.

Implements DragTool.

drag_start(event)

Called when the drag operation starts.

Implements DragTool.

dragging(event)

This method is called for every mouse_move event that the tool receives while the user is dragging the mouse.

Implements DragTool. Moves the legend by aligning it to a corner of its overlay component.

is_draggable(x, y)

Returns whether the (x,y) position is in a region that is OK to drag.

Overrides DragTool.

LegendHighlighter

class chaco.tools.api.LegendHighlighter(component=None, **kwtraits)

Bases: chaco.tools.legend_tool.LegendTool

A tool for legends that allows clicking on the legend to show or hide certain plots.

Traits:

drag_button : ‘right’

: Which mousebutton to use to move the legend

dim_factor : Float(3.0)

: What to divide the alpha value by when plot is not selected

line_scale : Float(2.0)

: How much to scale the line when it is selected or deselected

dim_factor = None
drag_button = None
line_scale = None

LineInspector

class chaco.tools.api.LineInspector(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

A simple tool to draw a line parallel to the index or the value axis of an X-Y plot.

This tool supports only plots with a 1-D index.

Traits:

axis : Enum(‘index’, ‘value’, ‘index_x’, ‘index_y’)

The axis that this tool is parallel to.

inspect_mode : Enum(‘space’, ‘indexed’)

The possible inspection modes of the tool.

space:

The tool maps from screen space into the data space of the plot.

indexed:

The tool maps from screen space to an index into the plot’s index array.

is_interactive : Bool(True)

Respond to user mouse events?

is_listener : Bool(False)

Does the tool respond to updates in the metadata on the data source and update its own position?

write_metadata : Bool(False)

If interactive, does the line inspector write the current data space point to the appropriate data source’s metadata?

metadata_name : Str(‘selections’)

The name of the metadata field to listen or write to.

visible : True

This tool is visible (overrides BaseTool).

draw_mode : ‘overlay’

This tool is drawn as an overlay (overrides BaseTool).

color : ColorTrait(‘black’)

Color of the line.

line_width : Float(1.0)

Width in pixels of the line.

line_style : LineStyle(‘solid’)

Dash style of the line.

draw(gc, view_bounds=None)

Draws this tool on a graphics context.

Overrides BaseTool.

normal_mouse_leave(event)

Handles the mouse leaving the plot.

normal_mouse_move(event)

Handles the mouse being moved.

overlay(component, gc, view_bounds=None, mode='normal')

Draws this component overlaid on a graphics context.

LineSegmentTool

class chaco.tools.api.LineSegmentTool(component=None, **kwtraits)

Bases: chaco.abstract_overlay.AbstractOverlay

The base class for tools that allow the user to draw a series of points connected by lines.

Traits:

component : Instance(Component)

The component that this tool overlays

line : Instance(Line, args=())

The current line segment being drawn.

points : List

A list of the points in data space as (index,value)

event_state : Enum(‘normal’, ‘selecting’, ‘dragging’)

The event states are:

normal:

The user may have selected points, and is moving the cursor around.

selecting:

The user has clicked down but hasn’t let go of the button yet, and can still drag the point around.

dragging:

The user has clicked on an existing point and is dragging it around. When the user releases the mouse button, the tool returns to the “normal” state

proximity_distance : Int(4)

The pixel distance from a vertex that is considered ‘on’ the vertex.

mouse_position : Trait(None, None, Tuple)

The data (index, value) position of the mouse cursor; this is used by various draw() routines.

original_cursor : Pointer(‘arrow’)

Cursor shape for non-tool use.

normal_cursor : Pointer(‘pencil’)

Cursor shape for drawing.

delete_cursor : Pointer(‘bullseye’)

Cursor shape for deleting points.

move_cursor : Pointer(‘sizing’)

Cursor shape for moving points.

visible : Bool(False)

The tool is initially invisible, because there is nothing to draw.

add_point(point)

Given a screen-space point (x,y), adds the corresponding data space point to the list for this tool.

dragging_draw(gc)

Draws the polygon in the ‘dragging’ state.

dragging_key_pressed(event)

Handles a key being pressed in the ‘dragging’ state.

If the key is “Esc”, the drag operation is canceled.

dragging_left_up(event)

Handles the left mouse coming up in the ‘dragging’ state.

Switches to ‘normal’ state.

dragging_mouse_leave(event)

Handles the mouse leaving the tool area in the ‘dragging’ state.

The drag is canceled and the cursor changes to an arrow.

dragging_mouse_move(event)

Handles the user moving the mouse while in the ‘dragging’ state.

The screen is updated to show the new mouse position as the end of the line segment being drawn.

get_point(index)

Retrieves the indexed point and returns its screen space value.

normal_draw(gc)

Draws the line.

normal_key_pressed(event)

Handles the user pressing a key in the ‘normal’ state.

If the user presses the Enter key, the tool is reset.

normal_left_down(event)

Handles the left mouse button being pressed while the tool is in the ‘normal’ state.

For an existing point, if the user is pressing the Control key, the point is deleted. Otherwise, the user can drag the point.

For a new point, the point is added, and the user can drag it.

normal_mouse_leave(event)

Handles the user moving the cursor away from the tool area.

normal_mouse_move(event)

Handles the user moving the mouse in the ‘normal’ state.

When the user moves the cursor over an existing point, if the Control key is pressed, the cursor changes to the delete_cursor, indicating that the point can be deleted. Otherwise, the cursor changes to the move_cursor, indicating that the point can be moved.

When the user moves the cursor over any other point, the cursor changes to (or stays) the normal_cursor.

overlay(component, gc, view_bounds, mode='normal')

Draws this component overlaid on another component.

Implements AbstractOverlay.

remove_point(index)

Removes the point for a given index from this tool’s list of points.

request_redraw()

Requests that the component redraw itself.

Overrides Enable Component.

reset()

Resets the tool, throwing away any points, and making the tool invisible.

set_point(index, point)

Sets the data-space index for a screen-space point.

MoveTool

class chaco.tools.api.MoveTool(component=None, **kwtraits)

Bases: enable.tools.drag_tool.DragTool

A tool for moving a plot component.

drag_start(event)

Called when the drag operation starts.

Implements DragTool.

dragging(event)

This method is called for every mouse_move event that the tool receives while the user is dragging the mouse.

Implements DragTool. Moves the component.

PanTool

class chaco.tools.api.PanTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

A tool that enables the user to pan a plot by clicking a mouse button and dragging.

Traits:

drag_button : Enum(‘left’, ‘middle’, ‘right’)

The mouse button that initiates the drag operation.

drag_pointer : Pointer(‘hand’)

The cursor to use when panning.

speed : Float(1.0)

Scaling factor on the panning “speed”.

constrain_key : Enum(None, ‘shift’, ‘control’, ‘alt’)

The modifier key that, if depressed when the drag is initiated, constrains the panning to happen in the only direction of largest initial motion. It is possible to permanently restrict this tool to always drag along one direction. To do so, set constrain=True, constrain_key=None, and constrain_direction to the desired direction.

pan_right_key : Instance(KeySpec, args=(‘Right’))

Keys to Pan via keyboard

pan_left_key : Instance(KeySpec, args=(‘Left’))

pan_up_key : Instance(KeySpec, args=(‘Up’))

pan_down_key : Instance(KeySpec, args=(‘Down’))

pan_keys_step : Float(0.0)

number of pixels the keys should pan disabled if 0.0

constrain : Bool(False)

Constrain the panning to one direction?

constrain_direction : Enum(None, ‘x’, ‘y’)

The direction of constrained draw. A value of None means that the user has initiated the drag and pressed the constrain_key, but hasn’t moved the mouse yet; the magnitude of the components of the next mouse_move event will determine the constrain_direction.

restrict_to_data : Bool(False)

Restrict to the bounds of the plot data

draw_mode : ‘none’

The tool does not have a visual representation (overrides BaseTool).

visible : False

The tool is not visible (overrides BaseTool).

event_state : Enum(‘normal’, ‘panning’)

The possible event states of this tool (overrides enable.Interactor).

normal_key_pressed(event)

Handles a key being pressed when the tool is in the ‘normal’ state.

normal_left_down(event)

Handles the left mouse button being pressed when the tool is in the ‘normal’ state.

Starts panning if the left mouse button is the drag button.

normal_middle_down(event)

Handles the middle mouse button being pressed when the tool is in the ‘normal’ state.

Starts panning if the middle mouse button is the drag button.

normal_right_down(event)

Handles the right mouse button being pressed when the tool is in the ‘normal’ state.

Starts panning if the right mouse button is the drag button.

panning_left_up(event)

Handles the left mouse button coming up when the tool is in the ‘panning’ state.

Stops panning if the left mouse button is the drag button.

panning_middle_up(event)

Handles the middle mouse button coming up when the tool is in the ‘panning’ state.

Stops panning if the middle mouse button is the drag button.

panning_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘panning’ state.

Ends panning.

panning_mouse_move(event)

Handles the mouse being moved when the tool is in the ‘panning’ state.

panning_right_up(event)

Handles the right mouse button coming up when the tool is in the ‘panning’ state.

Stops panning if the right mouse button is the drag button.

PointMarker

class chaco.tools.api.PointMarker(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

This tool looks at an XY plot’s index data source and draws a line corresponding to the index indicated by the “selections” metadata.

Traits:

axis : Enum(‘index’, ‘value’)

The axis that this tool is parallel to.

visible : True

This tool is visible (overrides BaseTool).

draw_mode : ‘overlay’

This tool is drawn as an overlay (overrides BaseTool).

color : ColorTrait(‘red’)

The color of the line.

line_width : Float(1.0)

The width of the line, in pixels.

draw(gc, view_bounds=None)

Draws this tool on a graphics context.

Implements BaseTool.

RangeSelection

class chaco.tools.api.RangeSelection(component, *args, **kw)

Bases: chaco.abstract_controller.AbstractController

Selects a range along the index or value axis.

The user right-click-drags to select a region, which stays selected until the user left-clicks to deselect.

Traits:

axis : Enum(‘index’, ‘value’)

The axis to which this tool is perpendicular.

selection : Property

The selected region, expressed as a tuple in data space. This updates and fires change-events as the user is dragging.

selection_mode : Enum(‘set’, ‘append’)

selection_completed : Event

This event is fired whenever the user completes the selection, or when a finalized selection gets modified. The value of the event is the data space range.

metadata_name : Str(‘selections’)

The name of the metadata on the datasource that we will write self.selection to

selection_mode_metadata_name : Str(‘selection_mode’)

Either “set” or “append”, depending on whether self.append_key was held down

mask_metadata_name : Str(‘selection_masks’)

The name of the metadata on the datasource that we will set to a numpy boolean array for masking the datasource’s data

event_state : Enum(‘normal’, ‘selecting’, ‘selected’, ‘moving’)

The possible event states of this selection tool (overrides enable.Interactor).

normal:

Nothing has been selected, and the user is not dragging the mouse.

selecting:

The user is dragging the mouse and actively changing the selection region; resizing of an existing selection also uses this mode.

selected:

The user has released the mouse and a selection has been finalized. The selection remains until the user left-clicks or self.deselect() is called.

moving:

The user moving (not resizing) the selection range.

plot : Property

The plot associated with this tool By default, this is just self.component.

mapper : Property

The mapper for associated with this tool. By default, this is the mapper on plot that corresponds to axis.

axis_index : Property

The index to use for axis. By default, this is self.plot.orientation, but it can be overriden and set to 0 or 1.

listeners : List

List of listeners that listen to selection events.

enable_resize : Bool(True)

Can the user resize the selection once it has been drawn?

resize_margin : Int(7)

The pixel distance between the mouse event and a selection endpoint at which the user action will be construed as a resize operation.

left_button_selects : Bool(False)

Allow the left button begin a selection?

disable_left_mouse : Bool(False)

Disable all left-mouse button interactions?

allow_deselection : Bool(True)

Allow the tool to be put into the deselected state via mouse clicks

minimum_selection : Int(5)

The minimum span, in pixels, of a selection region. Any attempt to select a region smaller than this will be treated as a deselection.

append_key : Instance(KeySpec, args=(None, ‘control’))

The key which, if held down while the mouse is being dragged, will indicate that the selection should be appended to an existing selection as opposed to overwriting it.

deselect(event=None)

Deselects the highlighted region.

This method essentially resets the tool. It takes the event causing the deselection as an optional argument.

moving_left_up(event)

Handles the left mouse button coming up when the tool is in the ‘moving’ state.

Switches the tool to the ‘selected’ state.

moving_mouse_leave(event)

Handles the mouse leaving the plot while the tool is in the ‘moving’ state.

If the mouse was within the selection region when it left, the method does nothing.

If the mouse was outside the selection region whe it left, the event is treated as moving the selection to the minimum or maximum.

moving_mouse_move(event)

Handles the mouse moving when the tool is in the ‘moving’ state.

Moves the selection range by an amount corresponding to the amount that the mouse has moved since its button was pressed. If the new selection range overlaps the endpoints of the data, it is truncated to that endpoint.

normal_left_down(event)

Handles the left mouse button being pressed when the tool is in the ‘normal’ state.

If the tool allows the left mouse button to start a selection, then it does so.

normal_right_down(event)

Handles the right mouse button being pressed when the tool is in the ‘normal’ state.

Puts the tool into ‘selecting’ mode, changes the cursor to show that it is selecting, and starts defining the selection.

selected_left_down(event)

Handles the left mouse button being pressed when the tool is in the ‘selected’ state.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the tool switches to the ‘selecting’ state so that the user can resize the selection.

If the event is within the bounds of the selection region, then the tool switches to the ‘moving’ states.

Otherwise, the selection becomes deselected.

selected_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘selected’ state.

Sets the cursor to an arrow.

selected_mouse_move(event)

Handles the mouse moving when the tool is in the ‘selected’ srate.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the cursor changes to indicate that the selection could be resized.

Otherwise, the cursor is set to an arrow.

selected_right_down(event)

Handles the right mouse button being pressed when the tool is in the ‘selected’ state.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the tool switches to the ‘selecting’ state so that the user can resize the selection.

Otherwise, the selection becomes deselected, and a new selection is started..

selecting_left_up(event)

Handles the left mouse button coming up when the tool is in the ‘selecting’ state.

Switches the tool to the ‘selected’ state.

selecting_mouse_enter(event)

Handles the mouse entering the plot when the tool is in the ‘selecting’ state.

If the mouse does not have the right mouse button down, this event is treated as if the right mouse button was released. Otherwise, the method sets the cursor to show that it is selecting.

selecting_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘selecting’ state.

Determines whether the event’s position is outside the component’s bounds, and if so, clips the selection. Sets the cursor to an arrow.

selecting_mouse_move(event)

Handles the mouse being moved when the tool is in the ‘selecting’ state.

Expands the selection range at the appropriate end, based on the new mouse position.

selecting_right_up(event)

Handles the right mouse button coming up when the tool is in the ‘selecting’ state.

Switches the tool to the ‘selected’ state and completes the selection.

RangeSelection2D

class chaco.tools.api.RangeSelection2D(component, *args, **kw)

Bases: chaco.tools.range_selection.RangeSelection

Selects a range along the index or value axis for plots on 2D data,
such as image plots

The user right-click-drags to select a region, which stays selected until the user left-clicks to deselect.

moving_mouse_move(event)

Handles the mouse moving when the tool is in the ‘moving’ state.

Moves the selection range by an amount corresponding to the amount that the mouse has moved since its button was pressed. If the new selection range overlaps the endpoints of the data, it is truncated to that endpoint.

normal_right_down(event)

Handles the right mouse button being pressed when the tool is in the ‘normal’ state.

Puts the tool into ‘selecting’ mode, changes the cursor to show that it is selecting, and starts defining the selection.

selected_left_down(event)

Handles the left mouse button being pressed when the tool is in the ‘selected’ state.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the tool switches to the ‘selecting’ state so that the user can resize the selection.

If the event is within the bounds of the selection region, then the tool switches to the ‘moving’ states.

Otherwise, the selection becomes deselected.

selected_mouse_move(event)

Handles the mouse moving when the tool is in the ‘selected’ state.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the cursor changes to indicate that the selection could be resized.

Otherwise, the cursor is set to an arrow.

selected_right_down(event)

Handles the right mouse button being pressed when the tool is in the ‘selected’ state.

If the user is allowed to resize the selection, and the event occurred within the resize margin of an endpoint, then the tool switches to the ‘selecting’ state so that the user can resize the selection.

Otherwise, the selection becomes deselected, and a new selection is started..

selecting_mouse_leave(event)

Handles the mouse leaving the plot when the tool is in the ‘selecting’ state.

Determines whether the event’s position is outside the component’s bounds, and if so, clips the selection. Sets the cursor to an arrow.

selecting_mouse_move(event)

Handles the mouse being moved when the tool is in the ‘selecting’ state.

Expands the selection range at the appropriate end, based on the new mouse position.

RangeSelectionOverlay

class chaco.tools.api.RangeSelectionOverlay(component=None, *args, **kw)

Bases: chaco.abstract_overlay.AbstractOverlay

Highlights the selection region on a component.

Looks at a given metadata field of self.component for regions to draw as selected.

Traits:

axis : Enum(‘index’, ‘value’)

The axis to which this tool is perpendicular.

plot : Property(depends_on=’component’)

Mapping from screen space to data space. By default, it is just self.component.

mapper : Instance(AbstractMapper)

The mapper (and associated range) that drive this RangeSelectionOverlay. By default, this is the mapper on self.plot that corresponds to self.axis.

axis_index : Property

The element of an (x,y) tuple that corresponds to the axis index. By default, this is set based on self.asix and self.plot.orientation, but it can be overriden and set to 0 or 1.

metadata_name : Str(‘selections’)

The name of the metadata to look at for dataspace bounds. The metadata can be either a tuple (dataspace_start, dataspace_end) in “selections” or a boolean array mask of seleted dataspace points with any other name

border_color : ColorTrait(‘dodgerblue’)

The color of the selection border line.

border_width : Float(1.0)

The width, in pixels, of the selection border line.

border_style : LineStyle(‘solid’)

The line style of the selection border line.

fill_color : ColorTrait(‘lightskyblue’)

The color to fill the selection region.

alpha : Float(0.3)

The transparency of the fill color.

overlay(component, gc, view_bounds=None, mode='normal')

Draws this component overlaid on another component.

Overrides AbstractOverlay.

RegressionLasso

class chaco.tools.api.RegressionLasso(component, *args, **kw)

Bases: chaco.tools.lasso_selection.LassoSelection

A controller for “lassoing” a selection of points in a regression plot.

Traits:

incremental_select : True

The regression updates as more points are added (overrides LassoSelection).

fit_params : Any

Tuple (slope, intercept) of the line that fits the data.

centroid : Any

The center point of the selected points, in data space.

RegressionOverlay

class chaco.tools.api.RegressionOverlay(component=None, *args, **kw)

Bases: chaco.lasso_overlay.LassoOverlay

Traits:

line_color : ColorTrait(‘black’)

line_style : LineStyle(‘dash’)

line_width : Float(2.0)

SaveTool

class chaco.tools.api.SaveTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

This tool allows the user to press Ctrl+S to save a snapshot image of the plot component.

Traits:

filename : Str(‘saved_plot.png’)

The file that the image is saved in. The format will be deduced from the extension.

pagesize : Enum(‘letter’, ‘A4’)

PDF format options This mirror the traits in PdfPlotGraphicsContext.

pagesize

dest_box : Tuple((0.5, 0.5, -0.5, -0.5))

dest_box_units : Enum(‘inch’, ‘cm’, ‘mm’, ‘pica’)

draw_mode : ‘none’

This tool does not have a visual representation (overrides BaseTool).

visible : False

This tool is not visible (overrides BaseTool).

normal_key_pressed(event)

Handles a key-press when the tool is in the ‘normal’ state.

Saves an image of the plot if the keys pressed are Control and S.

ScatterInspector

class chaco.tools.api.ScatterInspector(component=None, **kwtraits)

Bases: chaco.tools.select_tool.SelectTool

A tool for inspecting scatter plots.

It writes the index of the point under the cursor to the metadata of the index and value data sources, and allows clicking to select the point. Other components can listen for metadata updates on the data sources.

By default, it writes the index of the point under the cursor to the “hover” key in metadata, and the index of a clicked point to “selection”.

Traits:

persistent_hover : Bool(False)

If persistent_hover is False, then a point will be de-hovered as soon as the mouse leaves its hittesting area. If persistent_hover is True, then a point does no de-hover until another point get hover focus.

hover_metadata_name : Str(‘hover’)

The names of the data source metadata for hover and selection.

selection_metadata_name : Str(‘selections’)

visible : False

This tool is not visible

draw_mode : ‘none’

This tool does not have a visual reprentation

normal_mouse_move(event)

Handles the mouse moving when the tool is in the ‘normal’ state.

If the cursor is within threshold of a data point, the method writes the index to the plot’s data sources’ “hover” metadata.

SelectTool

class chaco.tools.api.SelectTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

Base class for tools that handle some level of click-to-select interaction. Handles the logic of different kinds of selection modes. Subclasses only need to implement a few concrete methods to handle actual selection/deselection.

Traits:

threshold : Float(5.0)

The threshold, in pixels, around the cursor location to search for points.

selection_mode : Enum(‘toggle’, ‘multi’, ‘single’, ‘off’)

How selections are handled:

“toggle”

The user clicks on points (while optionally holding down a modifier key) to select or deselect them. If the point is already selected, clicking it again deselects it. The modifier key to use is set by multiselect_modifier. The only way to deselect points is by clicking on them; clicking on a screen space outside of the plot does not deselect points.

“multi”

Like toggle mode, except that the user can deselect all points at once by clicking on the plot area away from a point.

“single”

The user can only select a single point at a time.

“off”

The user cannot select points via clicking.

multiselect_modifier : Instance(KeySpec, args=(None, ‘control’), allow_none=True)

The modifier key to use to multi-select points. Only used in toggle and multi selection modes.

normal_left_down(event)

Handles the left mouse button being pressed when the tool is in the ‘normal’ state.

If selecting is enabled and the cursor is within threshold of a data point, the method calls the subclass’s _select” or _deselect methods to perform the appropriate action, given the current selection_mode.

SimpleInspectorTool

class chaco.tools.api.SimpleInspectorTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

Simple inspector tool for plots

This is a simple tool that reports the data-space coordinates of the current mouse cursor position in a plot.

Interested overlays and other objects can listen for new_value events, which is a dictionary of data about the current location in data space, and can look at the last_mouse_position trait which holds the mouse position in screen space.

The tool also provides a visible trait which listeners can use to hide themselves. By default the ‘p’ key toggles this.

Instances can provide a value_generator function that performs computations to generate additional values in the dictionary that is passed to the new_value event. Subclasses can override gather_values() to similar effect.

Traits:

new_value : Event

This event fires whenever the mouse moves over a new image point. Its value is a dict with default keys “x”, “y”, “index” and “value”.

visible : Bool(True)

Indicates whether overlays listening to this tool should be visible.

last_mouse_position : Tuple

Stores the last mouse position. This can be used by overlays to position themselves around the mouse.

inspector_key : KeySpec(‘p’)

This key will show and hide any overlays listening to this tool.

value_generator : Callable

A callable that computes other values for the new_value event this takes a dictionary as an argument, and returns a dictionary

gather_values(event)

Generate the values for the new_value dictionary.

By default this returns a dictionary with keys “x”, “y”, “index” and “value”. If there is a value_generator callable, this will be called to modify the dictionary.

Parameters:

event :

The mouse_move event.

Returns:

A dictionary. :

map_to_data(x, y)

Returns the data space coordinates of the given x and y.

Takes into account orientation of the plot and the axis setting.

ZoomState

class chaco.tools.api.ZoomState(prev, next)

Bases: chaco.tools.tool_states.ToolState

A zoom state which can be applied and reverted.

This class exists so that subclasses can introduce new types of events which can be applied and reverted in the same manner. This greatly eases the code for managing history

PanState

class chaco.tools.api.PanState(prev, next)

Bases: chaco.tools.tool_states.ToolState

GroupedToolState

class chaco.tools.api.GroupedToolState(states)

Bases: chaco.tools.tool_states.ToolState

SelectedZoomState

class chaco.tools.api.SelectedZoomState(prev, next)

Bases: chaco.tools.tool_states.ZoomState

TrackingPanTool

class chaco.tools.api.TrackingPanTool(component=None, **kwtraits)

Bases: chaco.tools.pan_tool.PanTool

Allows the user to pan around a plot.

The user clicks a mouse button and drags to pan; the tool then returns to a tracking state.

TrackingZoom

class chaco.tools.api.TrackingZoom(component=None, *args, **kw)

Bases: chaco.tools.better_selecting_zoom.BetterSelectingZoom

Allows the user to zoom in or out on a plot that is using tracking.

The default_state of the data range determines the tracking behavior. For example, if the data range’s default_state is “low_track”, the range’s high value snaps to the right edge and the tracking, low, value follows it by the data range’s tracking_amount value (and vice versa for “high_track”).

normal_mouse_wheel(event)

Handles the mouse wheel being used when the tool is in the ‘normal’ state.

Overrides ZoomTool

TraitsTool

class chaco.tools.api.TraitsTool(component=None, **kwtraits)

Bases: enable.base_tool.BaseTool

Tool to edit the traits of plots, grids, and axes.

Traits:

draw_mode : ‘none’

This tool does not have a visual representation (overrides BaseTool).

visible : False

This tool is not visible (overrides BaseTool).

classes : List([PlotAxis, ColorBar])

The classes of components that should trigger a traits view

views : Dict

A dict of Class : View providing alternate views for a particular component

event : Str(‘left_dclick’)

The event to trigger the edit on

ZoomTool

chaco.tools.api.ZoomTool

alias of BetterSelectingZoom