Commonly Used Modules and Classes¶
All visual components in Chaco subclass from PlotComponent. It defines all of the common visual attributes like background color, border styles and color, and whether the component is visible. (Actually, most of these visual attributes are inherited from the Enable drawing framework.) More importantly, it provides the base behaviors for participating in layout, handling event dispatch to tools and overlays, and drawing various layers in the correct order. Subclasses almost never need to override or customize these base behaviors, but if they do, there are several easy extension points.
PlotComponent is a subclass of Enable Component. It has its own default drawing order. It redefines the inherited traits draw_order and draw_layer, but it doesn’t define any new traits. Therefore, you may need to refer to the API documentation for Enable Component, even when you have subclassed Chaco PlotComponent.
If you subclass PlotComponent, you need to implement do_layout(), if you want to size the component correctly.
A data source is a wrapper object for the actual data that it will be handling. It provides methods for retrieving data, estimating a size of the dataset, indications about the dimensionality of the data, a place for metadata (such as selections and annotations), and events that fire when the data gets changed. There are two primary reasons for a data source class:
It provides a way for different plotting objects to reference the same data.
It defines the interface for embedding Chaco into an existing application. In most cases, the standard ArrayDataSource will suffice.
Subclasses: ArrayDataSource, MultiArrayDataSource, PointDataSource, GridDataSource, ImageData
A data range expresses bounds on data space of some dimensionality. The simplest data range is just a set of two scalars representing (low, high) bounds in 1-D. One of the important aspects of data ranges is that their bounds can be set to auto, which means that they automatically scale to fit their associated datasources. (Each data source can be associated with multiple ranges, and each data range can be associated with multiple data sources.)
Subclasses: BaseDataRange, DataRange1D, DataRange2D
A data source is an object that supplies data to Chaco. For the most part, a data source looks like an array of values, with an optional mask and metadata.
Subclasses: ArrayDataSource, DataContextDataSource, GridDataSource, ImageData, MultiArrayDataSource, PointDataSource
The metadata trait attribute is a dictionary where you can stick stuff for other tools to find, without inserting it in the actual data.
Events that are fired on data sources are:
Mappers perform the job of mapping a data space region to screen space, and vice versa. Bounds on mappers are set by data range objects.
Subclasses: Base1DMapper, LinearMapper, LogMapper, GridMapper, PolarMapper
PlotContainer is Chaco’s way of handling layout. Because it logically partitions the screen space, it also serves as a way for efficient event dispatch. It is very similar to sizers or layout grids in GUI toolkits like WX. Containers are subclasses of PlotComponent, thus allowing them to be nested. BasePlotContainer implements the logic to correctly render and dispatch events to sub-components, while its subclasses implement the different layout calculations.
A container gets the preferred size from its components, and tries to allocate space for them. Non-resizeable components get their required size; whatever is left over is divided among the resizeable components.
Chaco currently has three types of containers, described in the following sections.
Subclasses: OverlayPlotContainer, HPlotContainer, VPlotContainer, GridPlotContainer
The listed subclasses are defined in the module chaco.plot_containers.
Plot renderers are the classes that actually draw a type of plot.
Interface: AbstractPlotRenderer Subclasses:
- ImagePlot: displays an image file, or color-maps scalar data to make an image
- BaseXYPlot: This class is often emulated by writers of other plot renderers, but renderers don’t need to be structured this way. By convention, many have a hittest() method. They do need to implement map_screen(), map_data(), and map_index() from AbstractPlotRenderer.
- PolarLineRenderer: NOTE: doesn’t play well with others
You can use these classes to compose more interesting plots.
The module chaco.plot_factory contains various convenience functions for creating plots, which simplify the set-up.
The chaco.plot.Plot class (called “capital P Plot” when speaking) represents what the user usually thinks of as a “plot”: a set of data, renderers, and axes in a single screen region. It is a subclass of DataView.
Tools attach to a component, which gives events to the tool.
All tools subclass from Enable’s BaseTool, which is in turn an Enable Interactor. Do not try to make tools that draw: use an overlay for that.
Some tool subclasses exist in both Enable and Chaco, because they were created first in Chaco, and then moved into Enable.
Interface: BaseTool Subclasses:
- BroadcasterTool: Keeps a list of other tools, and broadcasts events it receives to all those tools.
- DataPrinter: Prints the data-space position of the point under the cursor.
- enable.tools.api.DragTool: Enable base class for tools that do dragging.
- chaco.tools.api.DragTool: Chaco base class for tools that do dragging.
DragTool is a base class for tools that do dragging.
Other tools do things like panning, moving, highlighting, line segments, range selection, drag zoom, move data labels, scatter inspection, Traits UI.