KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > jcckit > plot > Plot


1 /*
2  * Copyright 2003-2004, Franz-Josef Elmer, All rights reserved
3  *
4  * This library is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License as published by
6  * the Free Software Foundation; either version 2.1 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU Lesser General Public License for more details
13  * (http://www.gnu.org/copyleft/lesser.html).
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  */

19 package jcckit.plot;
20
21 import java.util.Vector JavaDoc;
22
23 import jcckit.data.DataCurve;
24 import jcckit.data.DataEvent;
25 import jcckit.data.DataListener;
26 import jcckit.data.DataPlot;
27 import jcckit.data.DataPoint;
28 import jcckit.graphic.ClippingShape;
29 import jcckit.graphic.GraphPoint;
30 import jcckit.graphic.GraphicalComposite;
31 import jcckit.graphic.GraphicalElement;
32 import jcckit.transformation.Transformation;
33 import jcckit.util.ConfigParameters;
34 import jcckit.util.Factory;
35
36 /**
37  * A plot is determined by a {@link CoordinateSystem}, {@link Curve Curves},
38  * an optional annotation layer and an optional {@link Legend}. When rendered
39  * these components are draw in this order.
40  * <p>
41  * Registrated {@link PlotListener PlotListeners} will be informed
42  * when the plot changes.
43  * <p>
44  * A {@link DataPlot} can be connected with a <tt>Plot</tt> instance.
45  * This is done with the method {@link #connect connect()} which registrates
46  * this <tt>Plot</tt> instance as
47  * a {@link DataListener} at the connected <tt>DataPlot</tt>.
48  * After an received {@link DataEvent DataEvents} has been handled
49  * the registrated <tt>PlotListeners</tt> will receive a
50  * {@link PlotEvent} of the type {@link PlotEventType#DATA_PLOT_CHANGED}.
51  *
52  * @author Franz-Josef Elmer
53  */

54 public class Plot implements DataListener {
55   /** Configuration parameter key. */
56   public static final String JavaDoc COORDINATE_SYSTEM_KEY = "coordinateSystem",
57                              CURVE_FACTORY_KEY = "curveFactory",
58                              LEGEND_VISIBLE_KEY = "legendVisible",
59                              LEGEND_KEY = "legend",
60                              INITIAL_HINT_FOR_NEXT_CURVE_KEY
61                                       = "initialHintForNextCurve";
62   private final Vector JavaDoc _plotListeners = new Vector JavaDoc();
63   private DataPlot _dataPlot;
64   private final CurveFactory _curveFactory;
65   private final Vector JavaDoc _curves = new Vector JavaDoc();
66   private final Vector JavaDoc _nextCurveHints = new Vector JavaDoc();
67   private final Hint _initialHintForNextCurve;
68   private final Legend _legend;
69   private final boolean _legendVisibility;
70
71   private GraphicalElement _coordinateSystemView;
72   private ClippingShape _clippingShape;
73   private Transformation _transformation;
74   private GraphicalElement _annotation;
75   private GraphicalComposite _legendView = new GraphicalComposite(null);
76
77   /**
78    * Creates an instance from the specified configuration parameters.
79    * <table border=1 cellpadding=5>
80    * <tr><th>Key &amp; Default Value</th><th>Type</th><th>Mandatory</th>
81    * <th>Description</th></tr>
82    * <tr><td><tt>coordinateSystem = </tt>{@link CartesianCoordinateSystem}</td>
83    * <td><tt>ConfigParameters</tt></td><td>no</td>
84    * <td>Definition of the {@link CoordinateSystem}.</td></tr>
85    * <tr><td><tt>curveFactory = </tt>{@link SimpleCurveFactory}</td>
86    * <td><tt>ConfigParameters</tt></td><td>no</td>
87    * <td>Definition of the {@link CurveFactory}.</td></tr>
88    * <tr><td><tt>initialHintForNextCurve = null</tt></td>
89    * <td><tt>ConfigParameters</tt></td><td>no</td>
90    * <td>Definition of the initial {@link Hint} which is needed by some
91    * {@link SymbolFactory SymbolFactories} like {@link BarFactory}.
92    * </td></tr>
93    * <tr><td><tt>legend = </tt>default values of {@link Legend}</td>
94    * <td><tt>ConfigParameters</tt></td><td>no</td>
95    * <td>Configuration parameters of a {@link Legend}.</td></tr>
96    * <tr><td><tt>legendVisible = true</tt></td>
97    * <td><tt>boolean</tt></td><td>no</td>
98    * <td>If <tt>true</tt> the {@link Legend} will be created.</td></tr>
99    * </table>
100    */

101   public Plot(ConfigParameters config) {
102     CoordinateSystem coordinateSystem = (CoordinateSystem) Factory.create(
103         config.getNode(COORDINATE_SYSTEM_KEY),
104         CartesianCoordinateSystem.class.getName());
105     setCoordinateSystem(coordinateSystem);
106     _curveFactory = (CurveFactory) Factory.create(
107         config.getNode(CURVE_FACTORY_KEY),
108         SimpleCurveFactory.class.getName());
109     _initialHintForNextCurve = (Hint) Factory.createOrGet(
110                     config.getNode(INITIAL_HINT_FOR_NEXT_CURVE_KEY), null);
111     _legend = new Legend(config.getNode(LEGEND_KEY));
112     _legendVisibility = config.getBoolean(LEGEND_VISIBLE_KEY, true);
113   }
114
115   /**
116    * Sets the coordinate system. All curves will be regenerated and a
117    * {@link PlotEvent} of type {@link PlotEventType#COODINATE_SYSTEM_CHANGED}
118    * will be fired.
119    *
120    * @param coordinateSystem New coordinate system.
121    */

122   public void setCoordinateSystem(CoordinateSystem coordinateSystem)
123   {
124     _coordinateSystemView = coordinateSystem.getView();
125     _clippingShape = coordinateSystem.getClippingShape();
126     _transformation = coordinateSystem.getTransformation();
127     if (_dataPlot != null)
128     {
129       generateCurves(_dataPlot);
130     }
131     notifyListeners(
132         new PlotEvent(this, PlotEventType.COODINATE_SYSTEM_CHANGED, null));
133   }
134
135   /**
136    * Adds the specified {@link PlotListener}. Does nothing if
137    * already added.
138    */

139   public void addPlotListener(PlotListener listener) {
140     if (!_plotListeners.contains(listener)) {
141       _plotListeners.addElement(listener);
142     }
143   }
144
145   /**
146    * Removes the specfied {@link PlotListener}. Does nothing if
147    * already removed.
148    */

149   public void removePlotListener(PlotListener listener) {
150     _plotListeners.removeElement(listener);
151   }
152
153   /**
154    * Sends all registrated {@link PlotListener PlotListeners}
155    * the specified event.
156    */

157   protected void notifyListeners(PlotEvent event) {
158     for (int i = 0, n = _plotListeners.size(); i < n; i++) {
159       ((PlotListener) _plotListeners.elementAt(i)).plotChanged(event);
160     }
161   }
162
163   /**
164    * Connect the specified {@link DataPlot} with this instance.
165    * <p>
166    * If this <tt>Plot</tt> instance is already connected with a
167    * <tt>DataPlot</tt> the connection will be released and a
168    * {@link PlotEvent} of the type {@link PlotEventType#DATA_PLOT_DISCONNECTED}
169    * will be sent to all registrated {@link PlotListener PlotListeners}.
170    * <p>
171    * It registers itself at <tt>dataPlot</tt> and
172    * all its {@link DataCurve DataCurves}.
173    * <p>
174    * Finally all curves will be generated and a <tt>PlotEvent</tt>
175    * of the type {@link PlotEventType#DATA_PLOT_CONNECTED} will be transmitted.
176    * @param dataPlot Data to be connected with this plot instance.
177    * Can be <tt>null</tt> in order to disconnect this instance from
178    * any <tt>DataPlot</tt>.
179    */

180   public void connect(DataPlot dataPlot) {
181     if (_dataPlot != null) {
182       _dataPlot.removeDataListener(this);
183       notifyListeners(new PlotEvent(this, PlotEventType.DATA_PLOT_DISCONNECTED,
184                                     _dataPlot));
185     }
186     _dataPlot = dataPlot;
187     if (_dataPlot != null)
188     {
189       _dataPlot.addDataListener(this);
190       generateCurves(_dataPlot);
191       notifyListeners(new PlotEvent(this, PlotEventType.DATA_PLOT_CONNECTED,
192                                     _dataPlot));
193     }
194   }
195   
196   /**
197    * Transforms a point from device-independent coordinates into
198    * data coordinates.
199    * @param point Point in device-independent coordinates.
200    * @return transform <tt>point</tt>.
201    */

202   public DataPoint transform(GraphPoint point) {
203     return _transformation.transformToData(point);
204   }
205
206   /**
207    * Creates a graphical representation of the complete plot.
208    * @return <tt>GraphicalComposite</tt> containing the views of the
209    * coordinate system, the curves, and optionally the legend (in this order).
210    */

211   public GraphicalComposite getCompletePlot() {
212     GraphicalComposite result = new GraphicalComposite(null);
213     result.addElement(_coordinateSystemView);
214     GraphicalElement[] curves = getCurves();
215     for (int i = 0; i < curves.length; i++) {
216       result.addElement(curves[i]);
217     }
218     if (_annotation != null) {
219       result.addElement(_annotation);
220     }
221     if (_legendVisibility) {
222       result.addElement(getLegend());
223     }
224     return result;
225   }
226
227   /** Returns the view of the coordinate system. */
228   public GraphicalElement getCoordinateSystem() {
229     return _coordinateSystemView;
230   }
231
232   /** Returns the graphical representations of all curves. */
233   public GraphicalElement[] getCurves() {
234     synchronized (_curves) {
235       GraphicalElement[] curves = new GraphicalElement[_curves.size()];
236       for (int i = 0; i < curves.length; i++) {
237         curves[i] = ((Curve) _curves.elementAt(i)).getView();
238       }
239       return curves;
240     }
241   }
242   
243   /**
244    * Returns the annotation layer.
245    * @return <tt>null</tt> if no annotation layer.
246    */

247   public GraphicalElement getAnnotation()
248   {
249     return _annotation;
250   }
251   
252   /**
253    * Sets the annotation layer.
254    * @param annotation Any kind of graphics which will be drawn on the
255    * top of the curves but may be covered by the legend.
256    * Can be <tt>null</tt>.
257    */

258   public void setAnnotation(GraphicalElement annotation)
259   {
260     _annotation = annotation;
261   }
262
263   /** Returns <tt>true</tt> if the legend is visible. */
264   public boolean isLegendVisible() {
265     return _legendVisibility;
266   }
267
268   /** Returns the graphical representations of the legend. */
269   public GraphicalElement getLegend() {
270     return _legendView;
271   }
272
273   /**
274    * Handles the received {@link DataEvent} and notifies
275    * {@link PlotListener PlotListeners} by an event of the type
276    * {@link PlotEventType#DATA_CURVE_CHANGED} or
277    * {@link PlotEventType#DATA_PLOT_CHANGED}. The following table shows what
278    * this method does:
279    * <table border=1 cellpadding=5>
280    * <tr><th>Source of <tt>event</tt></th>
281    * <th>All hints for the next curve are <tt>null</tt>?</th>
282    * <th>Action</th><th>Type of sent {@link PlotEvent}</th></tr>
283    * <tr><td>{@link DataCurve}</td><td>Yes</td><td>Recreate changed curve.<td>
284    * <td><tt>DATA_CURVE_CHANGED</tt></td></tr>
285    * <tr><td>{@link DataCurve}</td><td>No</td><td>Recreate changed curve
286    * and all curves with large curve index.<td>
287    * <td><tt>DATA_PLOT_CHANGED</tt></td></tr>
288    * <tr><td>{@link DataPlot}</td><td>-</td><td>Recreate all curves
289    * and {@link Legend} view.<td>
290    * <td><tt>DATA_PLOT_CHANGED</tt></td></tr>
291    * </table>
292    */

293   public void dataChanged(DataEvent event) {
294     Integer JavaDoc index = new Integer JavaDoc(0);
295     PlotEventType type = PlotEventType.DATA_PLOT_CHANGED;
296     synchronized (_curves) {
297       int numberOfCurves = _curves.size();
298       if (event.getContainer() instanceof DataCurve
299           && numberOfCurves == _dataPlot.getNumberOfElements()) {
300         DataCurve curve = (DataCurve) event.getContainer();
301         index = new Integer JavaDoc(curve.getContainer().getIndexOf(curve));
302         type = PlotEventType.DATA_CURVE_CHANGED;
303         fillCurve(index.intValue(), curve);
304         if (index.intValue() < numberOfCurves - 1) {
305           Vector JavaDoc curveHints
306               = (Vector JavaDoc) _nextCurveHints.elementAt(index.intValue());
307           for (int i = 0, n = curveHints.size(); i < n; i++) {
308             if (curveHints.elementAt(i) != null) {
309               type = PlotEventType.DATA_PLOT_CHANGED;
310               for (int j = index.intValue()+1; j < numberOfCurves; j++) {
311                 fillCurve(j, (DataCurve) _dataPlot.getElement(j));
312               }
313               break;
314             }
315           }
316         }
317       } else {
318         generateCurves(_dataPlot);
319       }
320     }
321     notifyListeners(new PlotEvent(Plot.this, type, index));
322   }
323
324   /**
325    * Generates all curves based on the specified data.
326    * In addition the legend view is created.
327    */

328   private void generateCurves(DataPlot dataPlot) {
329     synchronized (_curves) {
330       _legendView = new GraphicalComposite(null);
331       _legendView.addElement(_legend.getBox());
332       _curves.setSize(0);
333       _nextCurveHints.setSize(0);
334       for (int i = 0, n = dataPlot.getNumberOfElements(); i < n; i++) {
335         Curve curve = _curveFactory.create(i, n, _clippingShape, _legend);
336         _curves.addElement(curve);
337         _nextCurveHints.addElement(new Vector JavaDoc());
338         DataCurve dataCurve = (DataCurve) dataPlot.getElement(i);
339         _legendView.addElement(curve.getLegendSymbol());
340         _legendView.addElement(
341             _legend.createCurveTitle(i, n, dataCurve.getTitle()));
342         fillCurve(i, dataCurve);
343       }
344     }
345   }
346
347   private void fillCurve(int curveIndex, DataCurve dataCurve) {
348     Vector JavaDoc curveHints = (Vector JavaDoc) _nextCurveHints.elementAt(curveIndex);
349     Curve curve = (Curve) _curves.elementAt(curveIndex);
350     curve.removeAllPoints();
351     for (int i = 0, n = dataCurve.getNumberOfElements(); i < n; i++) {
352       setHintForNextCurve(curveHints, i,
353           curve.addPoint(_transformation.transformToGraph(
354                                           (DataPoint) dataCurve.getElement(i)),
355                          getHintForNextCurve(curveIndex - 1, i)));
356     }
357   }
358   
359   private Hint getHintForNextCurve(int curveIndex, int pointIndex) {
360     Hint result = _initialHintForNextCurve;
361     if (curveIndex >= 0) {
362       Vector JavaDoc curveHints = (Vector JavaDoc) _nextCurveHints.elementAt(curveIndex);
363       result = pointIndex < curveHints.size() ?
364                    (Hint) curveHints.elementAt(pointIndex)
365                    : getHintForNextCurve(curveIndex - 1, pointIndex);
366     }
367     return result;
368   }
369   
370   private void setHintForNextCurve(Vector JavaDoc curveHints, int pointIndex,
371                                    Hint hint) {
372     while (curveHints.size() <= pointIndex) {
373       curveHints.addElement(_initialHintForNextCurve);
374     }
375     curveHints.setElementAt(hint, pointIndex);
376   }
377 }
378
Popular Tags