001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2017, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it
010 * under the terms of the GNU Lesser General Public License as published by
011 * the Free Software Foundation; either version 2.1 of the License, or
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301,
022 * USA.
023 *
024 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * --------------------
028 * XYShapeRenderer.java
029 * --------------------
030 * (C) Copyright 2008-2017 by Andreas Haumer, xS+S and Contributors.
031 *
032 * Original Author:  Martin Hoeller (x Software + Systeme  xS+S - Andreas
033 *                       Haumer);
034 * Contributor(s):   David Gilbert (for Object Refinery Limited);
035 *
036 * Changes:
037 * --------
038 * 17-Sep-2008 : Version 1, based on a contribution from Martin Hoeller with
039 *               amendments by David Gilbert (DG);
040 * 16-Feb-2010 : Added findZBounds() (patch 2952086) (MH);
041 * 19-Oct-2011 : Fixed NPE in findRangeBounds() (bug 3026341) (DG);
042 * 03-Jul-2013 : Use ParamChecks (DG);
043 * 09-Sep-2015 : Add update for crosshair (DG);
044 * 18-Feb-2017 : Updates for crosshairs (bug #36) (DG);
045 *
046 */
047
048package org.jfree.chart.renderer.xy;
049
050import java.awt.BasicStroke;
051import java.awt.Color;
052import java.awt.Graphics2D;
053import java.awt.Paint;
054import java.awt.Shape;
055import java.awt.Stroke;
056import java.awt.geom.Ellipse2D;
057import java.awt.geom.Line2D;
058import java.awt.geom.Rectangle2D;
059import java.io.IOException;
060import java.io.ObjectInputStream;
061import java.io.ObjectOutputStream;
062import java.io.Serializable;
063
064import org.jfree.chart.axis.ValueAxis;
065import org.jfree.chart.entity.EntityCollection;
066import org.jfree.chart.event.RendererChangeEvent;
067import org.jfree.chart.plot.CrosshairState;
068import org.jfree.chart.plot.PlotOrientation;
069import org.jfree.chart.plot.PlotRenderingInfo;
070import org.jfree.chart.plot.XYPlot;
071import org.jfree.chart.renderer.LookupPaintScale;
072import org.jfree.chart.renderer.PaintScale;
073import org.jfree.chart.util.Args;
074import org.jfree.chart.util.PublicCloneable;
075import org.jfree.chart.util.SerialUtils;
076import org.jfree.chart.util.ShapeUtils;
077import org.jfree.data.Range;
078import org.jfree.data.general.DatasetUtils;
079import org.jfree.data.xy.XYDataset;
080import org.jfree.data.xy.XYZDataset;
081
082/**
083 * A renderer that draws shapes at (x, y) coordinates and, if the dataset
084 * is an instance of {@link XYZDataset}, fills the shapes with a paint that
085 * is based on the z-value (the paint is obtained from a lookup table).  The
086 * renderer also allows for optional guidelines, horizontal and vertical lines
087 * connecting the shape to the edges of the plot.
088 * <br><br>
089 * The example shown here is generated by the
090 * {@code XYShapeRendererDemo1.java} program included in the JFreeChart
091 * demo collection:
092 * <br><br>
093 * <img src="../../../../../images/XYShapeRendererSample.png"
094 * alt="XYShapeRendererSample.png">
095 * <br><br>
096 * This renderer has similarities to, but also differences from, the
097 * {@link XYLineAndShapeRenderer}.
098 *
099 * @since 1.0.11
100 */
101public class XYShapeRenderer extends AbstractXYItemRenderer
102        implements XYItemRenderer, Cloneable, Serializable {
103
104    /** Auto generated serial version id. */
105    private static final long serialVersionUID = 8320552104211173221L;
106
107    /** The paint scale (never null). */
108    private PaintScale paintScale;
109
110    /** A flag that controls whether or not the shape outlines are drawn. */
111    private boolean drawOutlines;
112
113    /**
114     * A flag that controls whether or not the outline paint is used (if not,
115     * the regular paint is used).
116     */
117    private boolean useOutlinePaint;
118
119    /**
120     * A flag that controls whether or not the fill paint is used (if not,
121     * the fill paint is used).
122     */
123    private boolean useFillPaint;
124
125    /** Flag indicating if guide lines should be drawn for every item. */
126    private boolean guideLinesVisible;
127
128    /** The paint used for drawing the guide lines (never null). */
129    private transient Paint guideLinePaint;
130
131    /** The stroke used for drawing the guide lines (never null). */
132    private transient Stroke guideLineStroke;
133
134    /**
135     * Creates a new {@code XYShapeRenderer} instance with default
136     * attributes.
137     */
138    public XYShapeRenderer() {
139        this.paintScale = new LookupPaintScale();
140        this.useFillPaint = false;
141        this.drawOutlines = false;
142        this.useOutlinePaint = true;
143        this.guideLinesVisible = false;
144        this.guideLinePaint = Color.darkGray;
145        this.guideLineStroke = new BasicStroke();
146        setDefaultShape(new Ellipse2D.Double(-5.0, -5.0, 10.0, 10.0));
147        setAutoPopulateSeriesShape(false);
148    }
149
150    /**
151     * Returns the paint scale used by the renderer.
152     *
153     * @return The paint scale (never {@code null}).
154     *
155     * @see #setPaintScale(PaintScale)
156     */
157    public PaintScale getPaintScale() {
158        return this.paintScale;
159    }
160
161    /**
162     * Sets the paint scale used by the renderer and sends a
163     * {@link RendererChangeEvent} to all registered listeners.
164     *
165     * @param scale  the scale ({@code null} not permitted).
166     *
167     * @see #getPaintScale()
168     */
169    public void setPaintScale(PaintScale scale) {
170        Args.nullNotPermitted(scale, "scale");
171        this.paintScale = scale;
172        notifyListeners(new RendererChangeEvent(this));
173    }
174
175    /**
176     * Returns {@code true} if outlines should be drawn for shapes, and
177     * {@code false} otherwise.
178     *
179     * @return A boolean.
180     *
181     * @see #setDrawOutlines(boolean)
182     */
183    public boolean getDrawOutlines() {
184        return this.drawOutlines;
185    }
186
187    /**
188     * Sets the flag that controls whether outlines are drawn for
189     * shapes, and sends a {@link RendererChangeEvent} to all registered
190     * listeners.
191     * <P>
192     * In some cases, shapes look better if they do NOT have an outline, but
193     * this flag allows you to set your own preference.
194     *
195     * @param flag  the flag.
196     *
197     * @see #getDrawOutlines()
198     */
199    public void setDrawOutlines(boolean flag) {
200        this.drawOutlines = flag;
201        fireChangeEvent();
202    }
203
204    /**
205     * Returns {@code true} if the renderer should use the fill paint
206     * setting to fill shapes, and {@code false} if it should just
207     * use the regular paint.
208     * <p>
209     * Refer to {@code XYLineAndShapeRendererDemo2.java} to see the
210     * effect of this flag.
211     *
212     * @return A boolean.
213     *
214     * @see #setUseFillPaint(boolean)
215     * @see #getUseOutlinePaint()
216     */
217    public boolean getUseFillPaint() {
218        return this.useFillPaint;
219    }
220
221    /**
222     * Sets the flag that controls whether the fill paint is used to fill
223     * shapes, and sends a {@link RendererChangeEvent} to all
224     * registered listeners.
225     *
226     * @param flag  the flag.
227     *
228     * @see #getUseFillPaint()
229     */
230    public void setUseFillPaint(boolean flag) {
231        this.useFillPaint = flag;
232        fireChangeEvent();
233    }
234
235    /**
236     * Returns the flag that controls whether the outline paint is used for
237     * shape outlines.  If not, the regular series paint is used.
238     *
239     * @return A boolean.
240     *
241     * @see #setUseOutlinePaint(boolean)
242     */
243    public boolean getUseOutlinePaint() {
244        return this.useOutlinePaint;
245    }
246
247    /**
248     * Sets the flag that controls whether the outline paint is used for shape
249     * outlines, and sends a {@link RendererChangeEvent} to all registered
250     * listeners.
251     *
252     * @param use  the flag.
253     *
254     * @see #getUseOutlinePaint()
255     */
256    public void setUseOutlinePaint(boolean use) {
257        this.useOutlinePaint = use;
258        fireChangeEvent();
259    }
260
261    /**
262     * Returns a flag that controls whether or not guide lines are drawn for
263     * each data item (the lines are horizontal and vertical "crosshairs"
264     * linking the data point to the axes).
265     *
266     * @return A boolean.
267     *
268     * @see #setGuideLinesVisible(boolean)
269     */
270    public boolean isGuideLinesVisible() {
271        return this.guideLinesVisible;
272    }
273
274    /**
275     * Sets the flag that controls whether or not guide lines are drawn for
276     * each data item and sends a {@link RendererChangeEvent} to all registered
277     * listeners.
278     *
279     * @param visible  the new flag value.
280     *
281     * @see #isGuideLinesVisible()
282     */
283    public void setGuideLinesVisible(boolean visible) {
284        this.guideLinesVisible = visible;
285        fireChangeEvent();
286    }
287
288    /**
289     * Returns the paint used to draw the guide lines.
290     *
291     * @return The paint (never {@code null}).
292     *
293     * @see #setGuideLinePaint(Paint)
294     */
295    public Paint getGuideLinePaint() {
296        return this.guideLinePaint;
297    }
298
299    /**
300     * Sets the paint used to draw the guide lines and sends a
301     * {@link RendererChangeEvent} to all registered listeners.
302     *
303     * @param paint  the paint ({@code null} not permitted).
304     *
305     * @see #getGuideLinePaint()
306     */
307    public void setGuideLinePaint(Paint paint) {
308        Args.nullNotPermitted(paint, "paint");
309        this.guideLinePaint = paint;
310        fireChangeEvent();
311    }
312
313    /**
314     * Returns the stroke used to draw the guide lines.
315     *
316     * @return The stroke.
317     *
318     * @see #setGuideLineStroke(Stroke)
319     */
320    public Stroke getGuideLineStroke() {
321        return this.guideLineStroke;
322    }
323
324    /**
325     * Sets the stroke used to draw the guide lines and sends a
326     * {@link RendererChangeEvent} to all registered listeners.
327     *
328     * @param stroke  the stroke ({@code null} not permitted).
329     *
330     * @see #getGuideLineStroke()
331     */
332    public void setGuideLineStroke(Stroke stroke) {
333        Args.nullNotPermitted(stroke, "stroke");
334        this.guideLineStroke = stroke;
335        fireChangeEvent();
336    }
337
338    /**
339     * Returns the lower and upper bounds (range) of the x-values in the
340     * specified dataset.
341     *
342     * @param dataset  the dataset ({@code null} permitted).
343     *
344     * @return The range ({@code null} if the dataset is {@code null}
345     *         or empty).
346     */
347    @Override
348    public Range findDomainBounds(XYDataset dataset) {
349        if (dataset == null) {
350            return null;
351        }
352        Range r = DatasetUtils.findDomainBounds(dataset, false);
353        if (r == null) {
354            return null;
355        }
356        double offset = 0; // TODO getSeriesShape(n).getBounds().width / 2;
357        return new Range(r.getLowerBound() + offset,
358                         r.getUpperBound() + offset);
359    }
360
361    /**
362     * Returns the range of values the renderer requires to display all the
363     * items from the specified dataset.
364     *
365     * @param dataset  the dataset ({@code null} permitted).
366     *
367     * @return The range ({@code null} if the dataset is {@code null}
368     *         or empty).
369     */
370    @Override
371    public Range findRangeBounds(XYDataset dataset) {
372        if (dataset == null) {
373            return null;
374        }
375        Range r = DatasetUtils.findRangeBounds(dataset, false);
376        if (r == null) {
377            return null;
378        }
379        double offset = 0; // TODO getSeriesShape(n).getBounds().height / 2;
380        return new Range(r.getLowerBound() + offset, r.getUpperBound()
381                + offset);
382    }
383
384    /**
385     * Return the range of z-values in the specified dataset.
386     *  
387     * @param dataset  the dataset ({@code null} permitted).
388     * 
389     * @return The range ({@code null} if the dataset is {@code null}
390     *         or empty).
391     */
392    public Range findZBounds(XYZDataset dataset) {
393        if (dataset != null) {
394            return DatasetUtils.findZBounds(dataset);
395        } else {
396            return null;
397        }
398    }
399
400    /**
401     * Returns the number of passes required by this renderer.
402     *
403     * @return {@code 2}.
404     */
405    @Override
406    public int getPassCount() {
407        return 2;
408    }
409
410    /**
411     * Draws the block representing the specified item.
412     *
413     * @param g2  the graphics device.
414     * @param state  the state.
415     * @param dataArea  the data area.
416     * @param info  the plot rendering info.
417     * @param plot  the plot.
418     * @param domainAxis  the x-axis.
419     * @param rangeAxis  the y-axis.
420     * @param dataset  the dataset.
421     * @param series  the series index.
422     * @param item  the item index.
423     * @param crosshairState  the crosshair state.
424     * @param pass  the pass index.
425     */
426    @Override
427    public void drawItem(Graphics2D g2, XYItemRendererState state,
428            Rectangle2D dataArea, PlotRenderingInfo info, XYPlot plot,
429            ValueAxis domainAxis, ValueAxis rangeAxis, XYDataset dataset,
430            int series, int item, CrosshairState crosshairState, int pass) {
431
432        Shape hotspot;
433        EntityCollection entities = null;
434        if (info != null) {
435            entities = info.getOwner().getEntityCollection();
436        }
437
438        double x = dataset.getXValue(series, item);
439        double y = dataset.getYValue(series, item);
440        if (Double.isNaN(x) || Double.isNaN(y)) {
441            // can't draw anything
442            return;
443        }
444
445        double transX = domainAxis.valueToJava2D(x, dataArea,
446                plot.getDomainAxisEdge());
447        double transY = rangeAxis.valueToJava2D(y, dataArea,
448                plot.getRangeAxisEdge());
449
450        PlotOrientation orientation = plot.getOrientation();
451
452        // draw optional guide lines
453        if ((pass == 0) && this.guideLinesVisible) {
454            g2.setStroke(this.guideLineStroke);
455            g2.setPaint(this.guideLinePaint);
456            if (orientation == PlotOrientation.HORIZONTAL) {
457                g2.draw(new Line2D.Double(transY, dataArea.getMinY(), transY,
458                        dataArea.getMaxY()));
459                g2.draw(new Line2D.Double(dataArea.getMinX(), transX,
460                        dataArea.getMaxX(), transX));
461            } else {
462                g2.draw(new Line2D.Double(transX, dataArea.getMinY(), transX,
463                        dataArea.getMaxY()));
464                g2.draw(new Line2D.Double(dataArea.getMinX(), transY,
465                        dataArea.getMaxX(), transY));
466            }
467        } else if (pass == 1) {
468            Shape shape = getItemShape(series, item);
469            if (orientation == PlotOrientation.HORIZONTAL) {
470                shape = ShapeUtils.createTranslatedShape(shape, transY,
471                        transX);
472            } else if (orientation == PlotOrientation.VERTICAL) {
473                shape = ShapeUtils.createTranslatedShape(shape, transX,
474                        transY);
475            }
476            hotspot = shape;
477            if (shape.intersects(dataArea)) {
478                //if (getItemShapeFilled(series, item)) {
479                    g2.setPaint(getPaint(dataset, series, item));
480                    g2.fill(shape);
481               //}
482                if (this.drawOutlines) {
483                    if (getUseOutlinePaint()) {
484                        g2.setPaint(getItemOutlinePaint(series, item));
485                    } else {
486                        g2.setPaint(getItemPaint(series, item));
487                    }
488                    g2.setStroke(getItemOutlineStroke(series, item));
489                    g2.draw(shape);
490                }
491            }
492            
493            int datasetIndex = plot.indexOf(dataset);
494            updateCrosshairValues(crosshairState, x, y, datasetIndex,
495                    transX, transY, orientation);
496
497            // add an entity for the item...
498            if (entities != null) {
499                addEntity(entities, hotspot, dataset, series, item, 0.0, 0.0);
500            }
501        }
502    }
503
504    /**
505     * Get the paint for a given series and item from a dataset.
506     *
507     * @param dataset  the dataset.
508     * @param series  the series index.
509     * @param item  the item index.
510     *
511     * @return The paint.
512     */
513    protected Paint getPaint(XYDataset dataset, int series, int item) {
514        Paint p;
515        if (dataset instanceof XYZDataset) {
516            double z = ((XYZDataset) dataset).getZValue(series, item);
517            p = this.paintScale.getPaint(z);
518        } else {
519            if (this.useFillPaint) {
520                p = getItemFillPaint(series, item);
521            }
522            else {
523                p = getItemPaint(series, item);
524            }
525        }
526        return p;
527    }
528
529    /**
530     * Tests this instance for equality with an arbitrary object.  This method
531     * returns {@code true} if and only if:
532     * <ul>
533     * <li>{@code obj} is an instance of {@code XYShapeRenderer} (not
534     *     {@code null});</li>
535     * <li>{@code obj} has the same field values as this
536     *     {@code XYShapeRenderer};</li>
537     * </ul>
538     *
539     * @param obj  the object ({@code null} permitted).
540     *
541     * @return A boolean.
542     */
543    @Override
544    public boolean equals(Object obj) {
545        if (obj == this) {
546            return true;
547        }
548        if (!(obj instanceof XYShapeRenderer)) {
549            return false;
550        }
551        XYShapeRenderer that = (XYShapeRenderer) obj;
552        if (!this.paintScale.equals(that.paintScale)) {
553            return false;
554        }
555        if (this.drawOutlines != that.drawOutlines) {
556            return false;
557        }
558        if (this.useOutlinePaint != that.useOutlinePaint) {
559            return false;
560        }
561        if (this.useFillPaint != that.useFillPaint) {
562            return false;
563        }
564        if (this.guideLinesVisible != that.guideLinesVisible) {
565            return false;
566        }
567        if (!this.guideLinePaint.equals(that.guideLinePaint)) {
568            return false;
569        }
570        if (!this.guideLineStroke.equals(that.guideLineStroke)) {
571            return false;
572        }
573        return super.equals(obj);
574    }
575
576    /**
577     * Returns a clone of this renderer.
578     *
579     * @return A clone of this renderer.
580     *
581     * @throws CloneNotSupportedException if there is a problem creating the
582     *     clone.
583     */
584    @Override
585    public Object clone() throws CloneNotSupportedException {
586        XYShapeRenderer clone = (XYShapeRenderer) super.clone();
587        if (this.paintScale instanceof PublicCloneable) {
588            PublicCloneable pc = (PublicCloneable) this.paintScale;
589            clone.paintScale = (PaintScale) pc.clone();
590        }
591        return clone;
592    }
593
594    /**
595     * Provides serialization support.
596     *
597     * @param stream  the input stream.
598     *
599     * @throws IOException  if there is an I/O error.
600     * @throws ClassNotFoundException  if there is a classpath problem.
601     */
602    private void readObject(ObjectInputStream stream)
603            throws IOException, ClassNotFoundException {
604        stream.defaultReadObject();
605        this.guideLinePaint = SerialUtils.readPaint(stream);
606        this.guideLineStroke = SerialUtils.readStroke(stream);
607    }
608
609    /**
610     * Provides serialization support.
611     *
612     * @param stream  the output stream.
613     *
614     * @throws IOException  if there is an I/O error.
615     */
616    private void writeObject(ObjectOutputStream stream) throws IOException {
617        stream.defaultWriteObject();
618        SerialUtils.writePaint(this.guideLinePaint, stream);
619        SerialUtils.writeStroke(this.guideLineStroke, stream);
620    }
621
622}