XYItemRenderer


1   /* ======================================
2    * JFreeChart : a free Java chart library
3    * ======================================
4    *
5    * Project Info:  http://www.jfree.org/jfreechart/index.html
6    * Project Lead:  David Gilbert (david.gilbert@object-refinery.com);
7    *
8    * (C) Copyright 2000-2003, by Object Refinery Limited and Contributors.
9    *
10   * This library is free software; you can redistribute it and/or modify it under the terms
11   * of the GNU Lesser General Public License as published by the Free Software Foundation;
12   * either version 2.1 of the License, or (at your option) any later version.
13   *
14   * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
15   * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16   * See the GNU Lesser General Public License for more details.
17   *
18   * You should have received a copy of the GNU Lesser General Public License along with this
19   * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
20   * Boston, MA 02111-1307, USA.
21   *
22   * -------------------
23   * XYItemRenderer.java
24   * -------------------
25   * (C) Copyright 2001-2003, by Object Refinery Limited and Contributors.
26   *
27   * Original Author:  David Gilbert (for Object Refinery Limited);
28   * Contributor(s):   Mark Watson (www.markwatson.com);
29   *                   Sylvain Vieujot;
30   *                   Focus Computer Services Limited;
31   *                   Richard Atkinson;
32   *
33   * $Id: XYItemRenderer.java,v 1.16 2003/11/03 14:21:28 mungady Exp $
34   *
35   * Changes
36   * -------
37   * 19-Oct-2001 : Version 1, based on code by Mark Watson (DG);
38   * 22-Oct-2001 : Renamed DataSource.java --> Dataset.java etc. (DG);
39   * 13-Dec-2001 : Changed return type of drawItem from void --> Shape.  The area returned can
40   *               be used as the tooltip region.
41   * 23-Jan-2002 : Added DrawInfo parameter to drawItem(...) method (DG);
42   * 28-Mar-2002 : Added a property change listener mechanism.  Now renderers do not have to be
43   *               immutable (DG);
44   * 04-Apr-2002 : Added the initialise(...) method (DG);
45   * 09-Apr-2002 : Removed the translated zero from the drawItem method, it can be calculated inside
46   *               the initialise method if it is required.  Added a new getToolTipGenerator()
47   *               method.  Changed the return type for drawItem() to void (DG);
48   * 24-May-2002 : Added ChartRenderingInfo the initialise method API (DG);
49   * 25-Jun-2002 : Removed redundant import (DG);
50   * 20-Aug-2002 : Added get/setURLGenerator methods to interface (DG);
51   * 02-Oct-2002 : Fixed errors reported by Checkstyle (DG);
52   * 18-Nov-2002 : Added methods for drawing grid lines (DG);
53   * 17-Jan-2003 : Moved plot classes into a separate package (DG);
54   * 27-Jan-2003 : Added shape lookup table (DG);
55   * 05-Jun-2003 : Added domain and range grid bands (sponsored by Focus Computer Services Ltd) (DG);
56   * 27-Jul-2003 : Added getRangeType() to support stacked XY area charts (RA);
57   * 16-Sep-2003 : Changed ChartRenderingInfo --> PlotRenderingInfo (DG);
58   *
59   */
60  
61  package org.jfree.chart.renderer;
62  
63  import java.awt.Graphics2D  ;
64  import java.awt.Paint  ;
65  import java.awt.Shape  ;
66  import java.awt.Stroke  ;
67  import java.awt.geom.Rectangle2D  ;
68  import java.beans.PropertyChangeListener  ;
69  
70  import org.jfree.chart.CrosshairInfo;
71  import org.jfree.chart.LegendItem;
72  import org.jfree.chart.Marker;
73  import org.jfree.chart.axis.ValueAxis;
74  import org.jfree.chart.labels.XYToolTipGenerator;
75  import org.jfree.chart.plot.PlotRenderingInfo;
76  import org.jfree.chart.plot.XYPlot;
77  import org.jfree.chart.urls.XYURLGenerator;
78  import org.jfree.data.XYDataset;
79  
80  /**
81   * Interface for rendering the visual representation of a single (x, y) item on an
82   * {@link XYPlot}.
83   * <p>
84   * To support cloning charts, it is recommended that renderers implement both the {@link Cloneable} 
85   * and <code>PublicCloneable</code> interfaces.
86   *
87   * @author David Gilbert
88   */
89  public interface XYItemRenderer {
90  
91      /**
92       * Initialises the renderer then returns the number of 'passes' through the data that the
93       * renderer will require (usually just one).  This method will be called before the first
94       * item is rendered, giving the renderer an opportunity to initialise any
95       * state information it wants to maintain.  The renderer can do nothing if it chooses.
96       *
97       * @param g2  the graphics device.
98       * @param dataArea  the area inside the axes.
99       * @param plot  the plot.
100      * @param data  the data.
101      * @param info  an optional info collection object to return data back to the caller.
102      *
103      * @return The number of passes the renderer requires.
104      */
105     public XYItemRendererState initialise(Graphics2D   g2,
106                                           Rectangle2D   dataArea,
107                                           XYPlot plot,
108                                           XYDataset data,
109                                           PlotRenderingInfo info);
110 
111     /**
112      * Returns the number of passes through the data required by the renderer.
113      * 
114      * @return The pass count.
115      */
116     public int getPassCount();
117     
118     /**
119      * Returns the tool tip generator for the renderer (possibly null).
120      *
121      * @return the tool tip generator.
122      */
123     public XYToolTipGenerator getToolTipGenerator();
124 
125     /**
126      * Sets the tool tip generator for the renderer.
127      *
128      * @param toolTipGenerator  the tool tip generator (null permitted).
129      */
130     public void setToolTipGenerator(XYToolTipGenerator toolTipGenerator);
131 
132     /**
133      * Returns the URL generator for HTML image maps.
134      *
135      * @return the URL generator (possibly null).
136      */
137     public XYURLGenerator getURLGenerator();
138 
139     /**
140      * Sets the URL generator for HTML image maps.
141      *
142      * @param urlGenerator the URL generator (null permitted).
143      */
144     public void setURLGenerator(XYURLGenerator urlGenerator);
145 
146     /**
147      * Adds a property change listener to the renderer.
148      *
149      * @param listener  the listener.
150      */
151     public void addPropertyChangeListener(PropertyChangeListener   listener);
152 
153     /**
154      * Removes a property change listener from the renderer.
155      *
156      * @param listener  the listener.
157      */
158     public void removePropertyChangeListener(PropertyChangeListener   listener);
159 
160 
161     /**
162      * Returns the paint used to fill an item.
163      *
164      * @param series  the series index (zero-based).
165      * @param item  the item index (zero-based).
166      *
167      * @return The paint.
168      */
169     public Paint   getItemPaint(int series, int item);
170 
171     /**
172      * Returns the paint used to fill items in a series.
173      *
174      * @param series  the series index (zero-based).
175      *
176      * @return The paint.
177      */
178     public Paint   getSeriesPaint(int series);
179 
180     /**
181      * Sets the paint for a series in the primary dataset.
182      *
183      * @param series  the series index (zero-based).
184      * @param paint  the paint.
185      */
186     public void setSeriesPaint(int series, Paint   paint);
187 
188     /**
189      * Returns the paint used to outline an item.
190      *
191      * @param series  the series index (zero-based).
192      * @param item  the item index (zero-based).
193      *
194      * @return The paint.
195      */
196     public Paint   getItemOutlinePaint(int series, int item);
197 
198     /**
199      * Returns the paint used to outline items in a series.
200      *
201      * @param series  the series index (zero-based).
202      *
203      * @return The paint.
204      */
205     public Paint   getSeriesOutlinePaint(int series);
206 
207     // STROKE 
208     
209     /**
210      * Returns the stroke for an item.
211      *
212      * @param series  the series index (zero-based).
213      * @param item  the item index (zero-based).
214      *
215      * @return The stroke.
216      */
217     public Stroke   getItemStroke(int series, int item);
218 
219     /**
220      * Returns the stroke for a series.
221      *
222      * @param series  the series index (zero-based).
223      *
224      * @return The stroke.
225      */
226     public Stroke   getSeriesStroke(int series);
227 
228     /**
229      * Sets the stroke for ALL series (optional).
230      *
231      * @param stroke  the stroke.
232      */
233     public void setStroke(Stroke   stroke);
234     
235     /**
236      * Sets the stroke for a series in the primary dataset.
237      *
238      * @param series  the series index (zero-based).
239      * @param stroke  the stroke.
240      */
241     public void setSeriesStroke(int series, Stroke   stroke);
242 
243     /**
244      * Returns the base stroke.
245      *
246      * @return The stroke.
247      */
248     public Stroke   getBaseStroke();
249 
250     /**
251      * Sets the base stroke.
252      *
253      * @param stroke  the stroke.
254      */
255     public void setBaseStroke(Stroke   stroke);
256 
257     /**
258      * Returns the shape for an item.
259      *
260      * @param series  the series index (zero-based).
261      * @param item  the item index (zero-based).
262      *
263      * @return The shape.
264      */
265     public Shape   getItemShape(int series, int item);
266 
267     /**
268      * Returns the shape for a series.
269      *
270      * @param series  the series index (zero-based).
271 
272      *
273      * @return The shape.
274      */
275     public Shape   getSeriesShape(int series);
276 
277     /**
278      * Called for each item to be plotted.
279      * <p>
280      * The {@link XYPlot} can make multiple passes through the dataset, depending on the value
281      * returned by the renderer's {@link #initialise} method.
282      *
283      * @param g2  the graphics device.
284      * @param state  the renderer state.
285      * @param dataArea  the area within which the data is being rendered.
286      * @param info  collects drawing info.
287      * @param plot  the plot (can be used to obtain standard color information etc).
288      * @param domainAxis  the domain axis.
289      * @param rangeAxis  the range axis.
290      * @param dataset  the dataset.
291      * @param series  the series index (zero-based).
292      * @param item  the item index (zero-based).
293      * @param crosshairInfo  collects information about crosshairs.
294      * @param pass  the pass index.
295      */
296     public void drawItem(Graphics2D   g2,
297                          XYItemRendererState state,
298                          Rectangle2D   dataArea,
299                          PlotRenderingInfo info,
300                          XYPlot plot,
301                          ValueAxis domainAxis,
302                          ValueAxis rangeAxis,
303                          XYDataset dataset,
304                          int series,
305                          int item,
306                          CrosshairInfo crosshairInfo,
307                          int pass);
308 
309     /**
310      * Returns a legend item for a series from a dataset.
311      *
312      * @param datasetIndex  the dataset index.
313      * @param series  the series (zero-based index).
314      *
315      * @return the legend item.
316      */
317     public LegendItem getLegendItem(int datasetIndex, int series);
318 
319     /**
320      * Fills a band between two values on the axis.  This can be used to color bands between the
321      * grid lines.
322      *
323      * @param g2  the graphics device.
324      * @param plot  the plot.
325      * @param axis  the domain axis.
326      * @param dataArea  the data area.
327      * @param start  the start value.
328      * @param end  the end value.
329      */
330     public void fillDomainGridBand(Graphics2D   g2,
331                                    XYPlot plot,
332                                    ValueAxis axis,
333                                    Rectangle2D   dataArea,
334                                    double start, double end);
335 
336     /**
337      * Fills a band between two values on the range axis.  This can be used to color bands between
338      * the grid lines.
339      *
340      * @param g2  the graphics device.
341      * @param plot  the plot.
342      * @param axis  the range axis.
343      * @param dataArea  the data area.
344      * @param start  the start value.
345      * @param end  the end value.
346      */
347     public void fillRangeGridBand(Graphics2D   g2,
348                                   XYPlot plot,
349                                   ValueAxis axis,
350                                   Rectangle2D   dataArea,
351                                   double start, double end);
352 
353     /**
354      * Draws a grid line against the domain axis.
355      *
356      * @param g2  the graphics device.
357      * @param plot  the plot.
358      * @param axis  the value axis.
359      * @param dataArea  the area for plotting data (not yet adjusted for any 3D effect).
360      * @param value  the value.
361      */
362     public void drawDomainGridLine(Graphics2D   g2,
363                                    XYPlot plot,
364                                    ValueAxis axis,
365                                    Rectangle2D   dataArea,
366                                    double value);
367 
368     /**
369      * Draws a grid line against the range axis.
370      *
371      * @param g2  the graphics device.
372      * @param plot  the plot.
373      * @param axis  the value axis.
374      * @param dataArea  the area for plotting data (not yet adjusted for any 3D effect).
375      * @param value  the value.
376      */
377     public void drawRangeGridLine(Graphics2D   g2,
378                                   XYPlot plot,
379                                   ValueAxis axis,
380                                   Rectangle2D   dataArea,
381                                   double value);
382 
383     /**
384      * Draws a vertical line on the chart to represent a 'range marker'.
385      *
386      * @param g2  the graphics device.
387      * @param plot  the plot.
388      * @param axis  the value axis.
389      * @param marker  the marker line.
390      * @param dataArea  the axis data area.
391      */
392     public void drawDomainMarker(Graphics2D   g2,
393                                  XYPlot plot,
394                                  ValueAxis axis,
395                                  Marker marker,
396                                  Rectangle2D   dataArea);
397 
398     /**
399      * Draws a horizontal line across the chart to represent a 'range marker'.
400      *
401      * @param g2  the graphics device.
402      * @param plot  the plot.
403      * @param axis  the value axis.
404      * @param marker  the marker line.
405      * @param dataArea  the axis data area.
406      */
407     public void drawRangeMarker(Graphics2D   g2,
408                                 XYPlot plot,
409                                 ValueAxis axis,
410                                 Marker marker,
411                                 Rectangle2D   dataArea);
412 
413     /**
414      * Returns the plot that this renderer has been assigned to.
415      *
416      * @return the plot.
417      */
418     public XYPlot getPlot();
419 
420     /**
421      * Sets the plot that this renderer is assigned to.
422      * <P>
423      * This method will be called by the plot class...you do not need to call it yourself.
424      *
425      * @param plot  the plot.
426      */
427     public void setPlot(XYPlot plot);
428 
429     /**
430      * Returns the range type for the renderer.  The plot needs to know this information in order
431      * to determine an appropriate axis range (when the axis auto-range calculation is on).
432      * <P>
433      * Two types are recognised:
434      * <ul>
435      *   <li><code>STANDARD</code> - data items are plotted individually, so the axis range should
436      *     extend from the smallest value to the largest value;</li>
437      * <li><code>STACKED</code> - data items are stacked on top of one another, so to determine
438      *     the axis range, all the items in a series need to be summed together.</li>
439      * </ul>
440      *
441      * If the data values are stacked, this affects the axis range required to
442      * display all the data items.
443      *
444      * @return a flag indicating whether or not the data values are stacked.
445      */
446     public RangeType getRangeType();
447 
448 }
449
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags