ITrace2D


1   /*
2    * ITrace2D, the interface for all traces used by the Chart2D.
3    * Copyright (C) 2002  Achim Westermann, Achim.Westermann@gmx.de
4    *
5    *  This library is free software; you can redistribute it and/or
6    *  modify it under the terms of the GNU Lesser General Public
7    *  License as published by the Free Software Foundation; either
8    *  version 2.1 of the License, or (at your option) any later version.
9    * 
10   *  This library is distributed in the hope that it will be useful,
11   *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12   *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13   *  Lesser General Public License for more details.
14   * 
15   *  You should have received a copy of the GNU Lesser General Public
16   *  License along with this library; if not, write to the Free Software
17   *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
18   *
19   *  If you modify or optimize the code in a useful way please let me know.
20   *  Achim.Westermann@gmx.de
21   */
22  package info.monitorenter.gui.chart;
23  
24  import info.monitorenter.util.collections.IComparableProperty;
25  
26  import java.awt.Color  ;
27  import java.awt.Stroke  ;
28  import java.beans.PropertyChangeListener  ;
29  import java.util.Set  ;
30  
31  /**
32   * An interface used by <code>Chart2D</code>. ITrace2D contains the values to
33   * display, the color for displaying and a suitable label. It may be seen as a
34   * trace of the <code>Chart2D</code> that displays it. <br>
35   * Implementations may be optimized for different use- cases: <br>
36   * RingBuffers for fast changing data to keep the amount of tracepoints and
37   * consumption of memory constant, internal Lists for allowing the sorting the
38   * internal <code>TracePoint2D</code>- instances or Arrays for unordered Data
39   * (in the order of adding) for fast performance. Even an <code>ITrace2D</code>
40   * constructed by a "function- Object" may be thinkable.
41   * <p>
42   * There are various constraints for Traces: <br>- ordered by x-values <br>-
43   * ordered by the order of <code>addPoint</code>- invocation (control form
44   * outside) <br>- unique, single x- values <br>- limitation of tracepoints
45   * <br>- time- critical (fast- changing tracepoints) <br>
46   * <br>
47   * Therefore there are various <code>ITrace2D</code>- implementations. Read
48   * their description to find the one you need. Some may not have been written
49   * yet.
50   * </p>
51   * <p>
52   * {@link java.lang.Comparable} should be implemented by using the internal
53   * property zIndex (see {@link #getZIndex()}, {@link #setZIndex(Integer)}).
54   * </p>
55   * 
56   * @author <a HREF="mailto:Achim.Westermann@gmx.de">Achim Westermann </a>
57   * 
58   * @version $Revision: 1.4 $
59   */
60  public interface ITrace2D extends IComparableProperty {
61  
62    /**
63     * The property key defining the <code>color</code> property. Use in
64     * combination with
65     * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
66     */
67    public static final String   PROPERTY_COLOR = "trace.color";
68  
69    /**
70     * The property key defining the <code>maxX</code> property. Use in
71     * combination with
72     * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
73     */
74    public static final String   PROPERTY_MAX_X = "trace.maxX";
75  
76    /**
77     * The property key defining the <code>maxY</code> property. Use in
78     * combination with
79     * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
80     */
81    public static final String   PROPERTY_MAX_Y = "trace.maxY";
82  
83    /**
84     * The property key defining the <code>minX</code> property. Use in
85     * combination with
86     * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
87     */
88    public static final String   PROPERTY_MIN_X = "trace.minX";
89  
90    /**
91     * The property key defining the <code>minY</code> property. Use in
92     * combination with
93     * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
94     */
95    public static final String   PROPERTY_MIN_Y = "trace.minY";
96  
97    /**
98     * The property key defining the <code>name</code> property. Use in
99     * combination with
100    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
101    */
102   public static final String   PROPERTY_NAME = "trace.name";
103 
104   /**
105    * The property key defining the <code>physicalUnits</code> property. Use in
106    * combination with
107    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
108    */
109   public static final String   PROPERTY_PHYSICALUNITS = "trace.physicalUnits";
110 
111   /**
112    * The property key defining the <code>stroke</code> property. Use in
113    * combination with
114    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
115    */
116   public static final String   PROPERTY_STROKE = "trace.stroke";
117 
118   /**
119    * The property key defining a change in the collection of
120    * <code>{@link TracePoint2D}</code> instances within this trace. Use in
121    * combination with
122    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
123    */
124   public static final String   PROPERTY_TRACEPOINT = "trace.tracepoint";
125 
126   /**
127    * The property key defining the <code>visible</code> property. Use in
128    * combination with
129    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
130    */
131   public static final String   PROPERTY_VISIBLE = "trace.visible";
132 
133   /**
134    * The property key defining a change in the set of
135    * <code>{@link ITracePainter}</code> instances. Use in combination with
136    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
137    */
138   public static final String   PROPERTY_PAINTERS = "trace.painters";
139 
140   /**
141    * <p>
142    * The property key defining the <code>zIndex</code> property. Use in
143    * combination with
144    * {@link #addPropertyChangeListener(String, PropertyChangeListener)}.
145    * </p>
146    */
147   public static final String   PROPERTY_ZINDEX = "trace.zIndex";
148 
149   /**
150    * The minimum value for property zIndex: 0.
151    * 
152    * @see #getZIndex()
153    * @see #setZIndex(Integer)
154    */
155   public static final int Z_INDEX_MIN = 0;
156 
157   /**
158    * The maximum value for property zIndex: 100.
159    * <p>
160    * the descriptive name for this trace.
161    * <p>
162    * 
163    * @see #getZIndex()
164    * @see #setZIndex(Integer)
165    */
166   public static final int ZINDEX_MAX = 100;
167 
168   /**
169    * <p>
170    * Adds a tracepoint to the internal data.
171    * </p>
172    * 
173    * @see #addPoint(TracePoint2D p)
174    * @param x
175    *          the x-value of the point to add.
176    * @param y
177    *          the y-value of the point to add.
178    * @return true if the operation was successful, false else.
179    */
180   boolean addPoint(double x, double y);
181 
182   /**
183    * <p>
184    * Adds the given <code>TracePoint2D </code> to the internal data.
185    * </p>
186    * <p>
187    * Try to pass instances of <code>TracePoint2D</code> to this instance
188    * instead of invoking <code>{@link #addPoint(double, double)}</code> to
189    * increase performace. Else the given point has to be copied into such an
190    * instance from the other method and delegated to this method.
191    * </p>
192    * <p>
193    * Implementations decide wether the point will be accepted or not. So they
194    * have to update the internal properties <code>minX</code>,
195    * <code>maxX</code>,<code>maxY</code> and <code>minY</code> and also
196    * care about firing property change events for those properties by method
197    * <code>{@link java.beans.PropertyChangeSupport#firePropertyChange(java.beans.PropertyChangeEvent)}</code>.
198    * </p>
199    * 
200    * @param p
201    *          the point to add.
202    * @return true if the operation was successful, false else.
203    */
204   boolean addPoint(TracePoint2D p);
205 
206   /**
207    * <p>
208    * Registers a property change listener that will be informed about changes of
209    * the property identified by the given <code>propertyName</code>.
210    * </p>
211    * 
212    * @param propertyName
213    *          the name of the property the listener is interested in
214    * 
215    * @param listener
216    *          a listener that will only be informed if the property identified
217    *          by the argument <code>propertyName</code> changes
218    * 
219    * 
220    */
221   public void addPropertyChangeListener(String   propertyName, PropertyChangeListener   listener);
222 
223   /**
224    * Adds the given trace painter to the internal set of trace painters.
225    * <p>
226    * 
227    * It will be the last painter to paint (most forward).
228    * <p>
229    * 
230    * @param painter
231    *          the painter to add for rendering this trace.
232    * 
233    * @return true if the painter was added (class of instance not contained
234    *         before).
235    */
236   public boolean addTracePainter(ITracePainter painter);
237 
238   /**
239    * Returns true if the given painter is contained in this compound painter.
240    * <p>
241    * 
242    * @param painter
243    *          the painter to check wether it is contained.
244    * 
245    * @return true if the given painter is contained in this compound painter.
246    */
247   public boolean containsTracePainter(final ITracePainter painter);
248 
249   /**
250    * Because the color is data common to a trace of a <code>Chart2D</code> it
251    * is stored here. <br>
252    * On the other hand only the corresponding <code>Chart2D </code> may detect
253    * the same color chosen for different <code>IChart2D</code> instances to be
254    * displayed. Therefore it is allowed to return null. This is a message to the
255    * <code>Chart2D</code> to leave it the choice of the color. Then the
256    * <code>Chart2D</code> will chose a color not owned by another
257    * <code>ITrace2D</code> instance managed and assign it to the null-
258    * returning instance.
259    * <p>
260    * The <code>Chart2D </code> will often call this method. So try to cache the
261    * value in implementation and only check on modifications of
262    * <code>TracePoint</code> instances or on <code>add</code>- invocations
263    * for changes.
264    * </p>
265    * 
266    * @return The chosen java.awt.Color or null if the decision for the color
267    *         should be made by the corresponding <code>Chart2D</code>.
268    */
269   Color   getColor();
270 
271   /**
272    * <p>
273    * Callback method for the <code>Chart2D</code> that returns a
274    * <code>String</code> describing the label of the <code>ITrace2D</code>
275    * that will be displayed below the drawing area of the <code>Chart2D</code>.
276    * </p>
277    * <p>
278    * This method should be implemented and finalized ASAP in the inheritance
279    * tree and rely on the property <code>name</code> and
280    * <code>physicalUnits</code>.
281    * </p>
282    * 
283    * @return a String describing the Axis being accessed.
284    * 
285    */
286   String   getLable();
287 
288   /**
289    * <p>
290    * Returns the maximum amount of {@link TracePoint2D} instances that may be
291    * added. For implementations that limit the maximum amount this is a
292    * reasonable amount. Non-limiting implementations should return
293    * {@link Integer#MAX_VALUE}. This allows to detect the unlimitedness. Of
294    * course no implementation could store that amount of points.
295    * </p>
296    * 
297    * @return The maximum amount of {@link TracePoint2D} instances that may be
298    *         added.
299    * 
300    */
301   public int getMaxSize();
302 
303   /**
304    * Returns the maximum value to be displayed on the x- axis of the
305    * <code>Chart2D</code>. Implementations should be synchronized for
306    * multithreaded use. No exception is thrown. In case of empty data (no
307    * tracepoints) 0 should be returned, to let the Chart2D know.
308    * <p>
309    * The <code>Chart2D </code> will often call this method. So try to cache the
310    * value in implementation and only check on modifications of
311    * <code>TracePoint</code> instances or on <code>add</code>- invocations
312    * for changes.
313    * </p>
314    * 
315    * @return the maximum value of the internal data for the x- dimension.
316    */
317   double getMaxX();
318 
319   /**
320    * Returns the maximum value to be displayed on the y- axis of the Chart2D.
321    * Implementations should be synchronized for multithreaded use. No exception
322    * is thrown. In case of empty data (no tracepoints) 0 should be returned.
323    * (watch division with zero).
324    * 
325    * @return the maximum value of the internal data for the y- dimension.
326    */
327   double getMaxY();
328 
329   /**
330    * Returns the minimum value to be displayed on the x- axis of the Chart2D.
331    * Implementations should be synchronized for multithreaded use. No exception
332    * is thrown. In case of empty data (no tracepoints) 0 should be returned.
333    * (watch division with zero).
334    * <p>
335    * The <code>Chart2D </code> will often call this method. So try to cache the
336    * value in implementation and only check on modifications of
337    * <code>TracePoint</code> instances or on <code>add</code>- invocations
338    * for changes.
339    * </p>
340    * 
341    * @return the minimum value of the internal data for the x- dimension.
342    */
343 
344   double getMinX();
345 
346   /**
347    * Returns the minimum value to be displayed on the y- axis of the Chart2D.
348    * Implementations should be synchronized for multithreaded use. No exception
349    * is thrown. In case of empty data (no tracepoints) 0 should be returned.
350    * (watch division with zero).
351    * <p>
352    * The <code>Chart2D </code> will often call this method. So try to cache the
353    * value in implementation and only check on modifications of
354    * <code>TracePoint</code> instances or on <code>add</code>- invocations
355    * for changes.
356    * </p>
357    * 
358    * @return the minimum value of the internal data for the y- dimension.
359    */
360 
361   double getMinY();
362 
363   /**
364    * @see #setName(String s)
365    */
366   public String   getName();
367 
368   /**
369    * 
370    * @see #setPhysicalUnits(String x,String y)
371    */
372   public String   getPhysicalUnits();
373 
374   /**
375    * <p>
376    * Returns all property change listeners for the given property.
377    * </p>
378    * 
379    * @param property
380    *          one of the constants with teh <code>PROPERTY_</code> prefix
381    *          defined in this class or subclasses.
382    * 
383    * @return the property change listeners for the given property.
384    */
385   public PropertyChangeListener  [] getPropertyChangeListeners(String   property);
386 
387   /**
388    * @return Returns the renderer.
389    */
390   public Chart2D getRenderer();
391 
392   /**
393    * @return The amount of {@link TracePoint2D} instances currently contained.
394    */
395   public int getSize();
396 
397   /**
398    * @return the Stroke that is used to render this instance.
399    * @see #setStroke(Stroke)
400    * 
401    */
402   Stroke   getStroke();
403 
404   /**
405    * Returns the <code>Set&lt;{@link ITracePainter}&gt;</code> that will be
406    * used to paint this trace.
407    * <p>
408    * 
409    * @return the <code>Set&lt;{@link ITracePainter}&gt;</code> that will be
410    *         used to paint this trace.
411    */
412   public Set   getTracePainters();
413 
414   /**
415    * @return true if this instance should be rendered.
416    * 
417    */
418   public boolean isVisible();
419 
420   /**
421    * <p>
422    * The z-index defines the order in which this instance will be painted. A
423    * lower value will bring it more "to the front".
424    * </p>
425    * 
426    * @return the z-index that will define the order in which this instance will
427    *         be painted.
428    * 
429    */
430   public Integer   getZIndex();
431 
432   /**
433    * <p>
434    * Returns false if internal <code>{@link TracePoint2D}</code> instances are
435    * contained or true if not.
436    * </p>
437    * 
438    * @return <tt>false</tt> if internal <code>{@link TracePoint2D}</code>
439    *         instances are contained or <tt>true</tt> if not.
440    * 
441    */
442   boolean isEmpty();
443 
444   /**
445    * <p>
446    * Returns an <code>Iterator</code> over the internal
447    * <code>{@link TracePoint2D}</code> instances.
448    * </p>
449    * <p>
450    * Implementations should be synchronized. This method is meant to allow
451    * modifications of the intenal <code>TracePoint2D</code> instances, so the
452    * original points should be returned.
453    * </p>
454    * <p>
455    * There is no guarantee that changes made to the contained tracepoints will
456    * be reflected in the display immediately. The order the iterator returns the
457    * <code>TracePoint2D</code> instances decides how the <code>Chart2D</code>
458    * will paint the trace.
459    * </p>
460    * 
461    * @return an <code>Iterator</code> over the internal
462    *         <code>{@link TracePoint2D}</code> instances.
463    */
464   java.util.Iterator   iterator();
465 
466   /**
467    * Removes all internal <code>TracePoint2D</code>.{@link #isEmpty()} will
468    * return true afterwards.
469    * 
470    */
471   public void removeAllPoints();
472 
473   /**
474    * <p>
475    * Removes the given point from this trace.
476    * </p>
477    * 
478    * @param point
479    *          the point to remove.
480    * 
481    * @return true if the remove opertation was successful, false else.
482    * 
483    */
484   public boolean removePoint(TracePoint2D point);
485 
486   /**
487    * <p>
488    * Deregisters a property change listener that has been registerd for
489    * listening on all properties.
490    * </p>
491    * 
492    * @param listener
493    *          a listener that will only be informed if the property identified
494    *          by the argument <code>propertyName</code> changes
495    * 
496    * 
497    */
498   public void removePropertyChangeListener(PropertyChangeListener   listener);
499 
500   /**
501    * <p>
502    * Removes a property change listener for listening on the given property.
503    * </p>
504    * 
505    * @param property
506    *          one of the constants with teh <code>PROPERTY_</code> prefix
507    *          defined in this class or subclasses.
508    * 
509    * @param listener
510    *          the listener for this property change.
511    */
512   public void removePropertyChangeListener(String   property, PropertyChangeListener   listener);
513 
514   /**
515    * Removes the given trace painter, if it's class is contained and if more
516    * painters are remaining.
517    * <p>
518    * 
519    * @param painter
520    *          the trace painter to remove.
521    * 
522    * @return true if a trace painter of the class of the given argument was
523    *         removed.
524    */
525   public boolean removeTracePainter(final ITracePainter painter);
526 
527   /**
528    * <p>
529    * Set a <code>java.awt.Color</code> for this trace.
530    * </p>
531    * 
532    * @param color
533    *          the <tt>Color</tt> to set.
534    */
535   void setColor(Color   color);
536 
537   /**
538    * Assingns a specific name to the <code>ITrace2D</code> which will be
539    * displayed by the <code>Chart2D</code>.
540    * <p>
541    * 
542    * @param name
543    *          the name for this trace.
544    */
545   public void setName(String   name);
546 
547   /**
548    * Assings a specific String representing the physical unit to the <code>
549    *  ITrace2D</code>
550    * (e.g. Volt, Ohm, lux, ...) which will be displayed by the
551    * <code>{@link Chart2D}</code>
552    * <p>
553    * 
554    * @param xunit
555    *          the physical unit for the x axis.
556    * 
557    * @param yunit
558    *          the physical unit for the y axis.
559    */
560   public void setPhysicalUnits(final String   xunit, final String   yunit);
561 
562   /**
563    * This is a callback from {@link Chart2D#addTrace(ITrace2D)} and must not be
564    * invoked from elswhere (needed for synchronization). Not the best design to
565    * put this to an interface, but Char2D should handle this interface only.
566    * 
567    * @param renderer
568    *          The renderer to set.
569    */
570   public void setRenderer(Chart2D renderer);
571 
572   /**
573    * Allows to specify the rendering of the ITrace2D. This Stroke will be
574    * assigned to the {@link java.awt.Graphics2D} by the rendering
575    * {@link Chart2D} when painting this instance.
576    * <p>
577    * 
578    * @param stroke
579    *          the stroke to use for painting this trace.
580    * 
581    */
582   void setStroke(Stroke   stroke);
583 
584   /**
585    * Replaces all internal trace painters by the new one.
586    * <p>
587    * 
588    * @param painter
589    *          the new sole painter to use.
590    * 
591    * @return the <code>Set&lt;{@link ITracePainter}&gt;</code> that was used
592    *         before.
593    */
594   public Set   setTracePainter(ITracePainter painter);
595 
596   /**
597    * Set the visibility. If argument is false, this instance will not be
598    * rendered by a Chart2D.
599    * <p>
600    * 
601    * @param visible
602    *          true if this trace should be painted, false else.
603    * 
604    */
605   public void setVisible(boolean visible);
606 
607   /**
608    * <p>
609    * Sets the internal z-index property. This decides the order in which
610    * different traces within the same <code>{@link Chart2D}</code> are
611    * painted. The lower the given value is the more this trace will be brought
612    * to front.
613    * <p>
614    * The value must not be lower than {@link #Z_INDEX_MIN}(0) and higher than
615    * {@link #ZINDEX_MAX}(100).
616    * </p>
617    * <p>
618    * This might not be tested for increased performance but ignoring these
619    * bounds may result in wrong ordering of display.
620    * </p>
621    * 
622    * @see #getZIndex()
623    * 
624    */
625   public void setZIndex(Integer   zIndex);
626 
627 }
628
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags