2
.. _modules_and_classes:
4
Commonly Used Modules and Classes
5
=================================
8
-----------------------------------------------------------------------------
10
.. rubric:: Plot Component
12
All visual components in Chaco subclass from :class:`PlotComponent`. It defines
13
all of the common visual attributes like background color, border styles and
14
color, and whether the component is visible. (Actually, most of these visual
15
attributes are inherited from the Enable drawing framework.) More importantly,
16
it provides the base behaviors for participating in layout, handling event
17
dispatch to tools and overlays, and drawing various layers in the correct order.
18
Subclasses almost never need to override or customize these base behaviors, but
19
if they do, there are several easy extension points.
21
PlotComponent is a subclass of Enable :class:`Component`. It has its
22
own default drawing order. It redefines the inherited traits :attr:`draw_order`
23
and :attr:`draw_layer`, but it doesn't define any new traits. Therefore, you
24
may need to refer to the API documentation for Enable Component,
25
even when you have subclassed Chaco PlotComponent.
27
If you subclass PlotComponent, you need to implement :meth:`do_layout`,
28
if you want to size the component correctly.
32
-----------------------------------------------------------------------------
34
.. rubric:: Data Source
36
A data source is a wrapper object for the actual data that it will be
37
handling. It provides methods for retrieving data, estimating a size of the
38
dataset, indications about the dimensionality of the data, a place for metadata
39
(such as selections and annotations), and events that fire when the data gets
40
changed. There are two primary reasons for a data source class:
42
* It provides a way for different plotting objects to reference the same data.
43
* It defines the interface for embedding Chaco into an existing application.
44
In most cases, the standard ArrayDataSource will suffice.
46
*Interface:* :class:`AbstractDataSource`
48
*Subclasses:* :class:`ArrayDataSource`, :class:`MultiArrayDataSource`,
49
:class:`PointDataSource`, :class:`GridDataSource`, :class:`ImageData`
51
.. rubric:: Data Range
53
A data range expresses bounds on data space of some dimensionality. The simplest
54
data range is just a set of two scalars representing (low, high) bounds in 1-D.
55
One of the important aspects of data ranges is that their bounds can be set to
56
``auto``, which means that they automatically scale to fit their associated
57
datasources. (Each data source can be associated with multiple ranges,
58
and each data range can be associated with multiple data sources.)
60
*Interface*: :class:`AbstractDataRange`
62
*Subclasses*: :class:`BaseDataRange`, :class:`DataRange1D`,
65
.. rubric:: Data Source
67
A data source is an object that supplies data to Chaco. For the most part, a
68
data source looks like an array of values, with an optional mask and metadata.
70
*Interface*: :class:AbstractDataSource`
72
*Subclasses*: :class:`ArrayDataSource`, :class:`DataContextDataSource`,
73
:class:`GridDataSource`, :class:`ImageData`, :class:`MultiArrayDataSource`,
74
:class:`PointDataSource`
76
The :attr:`metadata` trait attribute is a dictionary where you can stick
77
stuff for other tools to find, without inserting it in the actual data.
79
Events that are fired on data sources are:
81
* :attr:`data_changed`
82
* :attr:`bounds_changed`
83
* :attr:`metadata_changed`
88
Mappers perform the job of mapping a data space region to screen space, and
89
vice versa. Bounds on mappers are set by data range objects.
91
*Interface*: :class:`AbstractMapper`
93
*Subclasses*: :class:`Base1DMapper`, :class:`LinearMapper`,
94
:class:`LogMapper`, :class:`GridMapper`, :class:`PolarMapper`
98
-----------------------------------------------------------------------------
100
.. rubric:: PlotContainer
102
:class:`PlotContainer` is Chaco's way of handling layout. Because it logically
103
partitions the screen space, it also serves as a way for efficient event
104
dispatch. It is very similar to sizers or layout grids in GUI toolkits like
105
WX. Containers are subclasses of PlotComponent, thus allowing them to
106
be nested. :class:`BasePlotContainer` implements the logic to correctly render
107
and dispatch events to sub-components, while its subclasses implement the
108
different layout calculations.
110
A container gets the preferred size from its components, and tries to allocate
111
space for them. Non-resizeable components get their required size; whatever is
112
left over is divided among the resizeable components.
114
Chaco currently has three types of containers,
115
described in the following sections.
117
*Interface*: :class:`BasePlotContainer`
119
*Subclasses*: :class:`OverlayPlotContainer`, :class:`HPlotContainer`,
120
:class:`VPlotContainer`, :class:`GridPlotContainer`
122
The listed subclasses are defined in the module
123
:mod:`chaco.plot_containers`.
127
-----------------------------------------------------------------------------
129
Plot renderers are the classes that actually draw a type of plot.
131
*Interface*: :class:`AbstractPlotRenderer`
135
* :class:`Base2DPlot`
137
* :class:`ContourLinePlot`
138
* :class:`ContourPolyPlot`
139
* :class:`ImagePlot`: displays an image file, or color-maps scalar
140
data to make an image
141
* :class:`CMapImagePlot`
143
* :class:`BaseXYPlot`: This class is often emulated by writers of other
144
plot renderers, but renderers don't *need* to be structured this way.
145
By convention, many have a :meth:`hittest` method. They *do* need
146
to implement :meth:`map_screen`, :meth:`map_data`, and :meth:`map_index`
147
from :class:`AbstractPlotRenderer`.
151
* :class:`ErrorBarPlot`
153
* :class:`PolygonPlot`
155
* :class:`FilledLinePlot`
157
* :class:`ScatterPlot`
159
* :class:`ColormappedScatterPlot`
162
* :class:`PolarLineRenderer`: NOTE: doesn't play well with others
164
You can use these classes to compose more interesting plots.
166
The module :mod:`chaco.plot_factory` contains various convenience
167
functions for creating plots, which simplify the set-up.
169
The :class:`chaco.plot.Plot` class (called "capital P Plot" when
170
speaking) represents what the user usually thinks of as a "plot": a set of data,
171
renderers, and axes in a single screen region. It is a subclass of
175
-----------------------------------------------------------------------------
177
Tools attach to a component, which gives events to the tool.
179
All tools subclass from Enable's :class:`BaseTool`, which is in turn an Enable
180
:class:`Interactor`. Do not try to make tools that draw: use an overlay for
183
Some tool subclasses exist in both Enable and Chaco, because they were created
184
first in Chaco, and then moved into Enable.
186
*Interface*: :class:`BaseTool`
189
* :class:`BroadcasterTool`: Keeps a list of other tools, and broadcasts
190
events it receives to all those tools.
191
* :class:`DataPrinter`: Prints the data-space position of the point
193
* :class:`enable.tools.api.DragTool`: Enable base class
194
for tools that do dragging.
197
* :class:`ResizeTool`
198
* :class:`ViewportPanTool`
200
* :class:`chaco.tools.api.DragTool`: Chaco base class
201
for tools that do dragging.
203
* :class:`BaseCursorTool`
205
* :class:`CursorTool1D`
206
* :class:`CursorTool2D`
208
* :class:`DataLabelTool`
210
* :class:`LegendTool`
213
* :class:`DrawPointsTool`
214
* :class:`HighlightTool`
216
* :class:`ImageInspectorTool`
217
* :class:`LineInspector`
220
* :class:`TrackingPanTool`
222
* :class:`PointMarker`
224
* :class:`SelectTool`
226
* :class:`ScatterInspector`
227
* :class:`SelectableLegend`
229
* :class:`enable.tools.api.TraitsTool`
230
* :class:`chaco.tools.api.TraitsTool`
234
DragTool is a base class for tools that do dragging.
236
Other tools do things like panning, moving, highlighting, line segments, range selection, drag zoom, move data labels, scatter inspection, Traits UI.
239
-----------------------------------------------------------------------------
243
-----------------------------------------------------------------------------
added
removed
docs/source/modules_and_classes.rst
