    001/* ===========================================================
    002 * Orson Charts : a 3D chart library for the Java(tm) platform
    003 * ===========================================================
    004 *
    005 * (C)opyright 2013-2016, by Object Refinery Limited.  All rights reserved.
    006 *
    007 * http://www.object-refinery.com/orsoncharts/index.html
    008 *
    009 * This program is free software: you can redistribute it and/or modify
    010 * it under the terms of the GNU General Public License as published by
    011 * the Free Software Foundation, either version 3 of the License, or
    012 * (at your option) any later version.
    013 *
    014 * This program is distributed in the hope that it will be useful,
    015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
    016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    017 * GNU General Public License for more details.
    018 *
    019 * You should have received a copy of the GNU General Public License
    020 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
    021 *
    022 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates.
    023 * Other names may be trademarks of their respective owners.]
    024 *
    025 * If you do not wish to be bound by the terms of the GPL, an alternative
    026 * commercial license can be purchased.  For details, please see visit the
    027 * Orson Charts home page:
    028 *
    029 * http://www.object-refinery.com/orsoncharts/index.html
    030 *
    031 */
    032
    033package com.orsoncharts.legend;
    034
    035import java.io.Serializable;
    036
    037import com.orsoncharts.plot.CategoryPlot3D;
    038import com.orsoncharts.plot.Plot3D;
    039import com.orsoncharts.plot.XYZPlot;
    040import com.orsoncharts.renderer.ColorScale;
    041import com.orsoncharts.renderer.ColorScaleRenderer;
    042import com.orsoncharts.renderer.FixedColorScale;
    043import com.orsoncharts.renderer.category.CategoryRenderer3D;
    044import com.orsoncharts.renderer.xyz.XYZRenderer;
    045import com.orsoncharts.table.TableElement;
    046import com.orsoncharts.util.Anchor2D;
    047import com.orsoncharts.util.Orientation;
    048import com.orsoncharts.Chart3D;
    049import com.orsoncharts.style.ChartStyle;
    050
    051/**
    052 * A legend builder that creates a legend representing a {@link ColorScale}.
    053 * This builder will only create a legend if the plot uses a renderer
    054 * that implements the {@link ColorScaleRenderer} interface.
    055 * <br><br>
    056 * The orientation and anchor point for the legend are properties of the
    057 * {@link Chart3D} class.
    058 * <br><br>
    059 * NOTE: This class is serializable, but the serialization format is subject
    060 * to change in future releases and should not be relied upon for persisting
    061 * instances of this class.
    062 *
    063 * @since 1.1
    064 */
    065@SuppressWarnings("serial")
    066public class ColorScaleLegendBuilder implements LegendBuilder, Serializable {
    067
    068    /** The width of the bar showing the color scale (in Java2D units). */
    069    private double barWidth;
    070
    071    /** The length of the bar showing the color scale (in Java2D units). */
    072    private double barLength;
    073
    074    /**
    075     * A flag to determine whether or not FixedColorScale is ignored (defaults
    076     * to {@code true}).
    077     */
    078    private boolean ignoreFixedColorScale;
    079
    080    /**
    081     * Creates a new instance.
    082     */
    083    public ColorScaleLegendBuilder() {
    084        this.barWidth = 16.0;
    085        this.barLength = 140.0;
    086        this.ignoreFixedColorScale = true;
    087    }
    088
    089    /**
    090     * Returns the width of the bar displaying the color scale.
    091     *
    092     * @return The width (in Java2D units).
    093     */
    094    public double getBarWidth() {
    095        return this.barWidth;
    096    }
    097
    098    /**
    099     * Sets the width of the bar displaying the color scale.
    100     *
    101     * @param width  the width (in Java2D units).
    102     */
    103    public void setBarWidth(double width) {
    104        this.barWidth = width;
    105    }
    106
    107    /**
    108     * Returns the length of the bar displaying the color scale.
    109     *
    110     * @return The length (in Java2D units).
    111     */
    112    public double getBarLength() {
    113        return this.barLength;
    114    }
    115
    116    /**
    117     * Sets the length of the bar displaying the color scale.
    118     *
    119     * @param length  the length (in Java2D units).
    120     */
    121    public void setBarLength(double length) {
    122        this.barLength = length;
    123    }
    124
    125    /**
    126     * Returns the flag that controls whether or not a {@link FixedColorScale}
    127     * will be ignored for the purposes of generating a legend.
    128     *
    129     * @return A boolean.
    130     */
    131    public boolean getIgnoreFixedColorScale() {
    132        return this.ignoreFixedColorScale;
    133    }
    134
    135    /**
    136     * Sets the flag that controls whether or not a {@link FixedColorScale}
    137     * will be ignored for the purposes of generating a legend.
    138     *
    139     * @param ignore  the new flag value.
    140     */
    141    public void setIgnoreFixedColorScale(boolean ignore) {
    142        this.ignoreFixedColorScale = ignore;
    143    }
    144
    145    /**
    146     * Creates a new color scale legend with the specified orientation.
    147     * If the plot does not use a renderer that implements
    148     * {@link ColorScaleRenderer} then this method will return {@code null}
    149     * and no legend will be drawn on the chart.
    150     *
    151     * @param plot  the plot ({@code null} not permitted).
    152     * @param anchor  the anchor ({@code null} not permitted).
    153     * @param orientation  the orientation ({@code null} not permitted).
    154     * @param style  the chart style ({@code null} not permitted).
    155     *
    156     * @return A color scale legend (possibly {@code null}).
    157     */
    158    @Override
    159    public TableElement createLegend(Plot3D plot, Anchor2D anchor,
    160            Orientation orientation, ChartStyle style) {
    161        ColorScaleRenderer renderer = null;
    162        if (plot instanceof CategoryPlot3D) {
    163            CategoryRenderer3D r = ((CategoryPlot3D) plot).getRenderer();
    164            if (r instanceof ColorScaleRenderer) {
    165                renderer = (ColorScaleRenderer) r;
    166            }
    167        } else if (plot instanceof XYZPlot) {
    168            XYZRenderer r = ((XYZPlot) plot).getRenderer();
    169            if (r instanceof ColorScaleRenderer) {
    170                renderer = (ColorScaleRenderer) r;
    171            }
    172        }
    173        if (renderer == null) {
    174            return null;
    175        }
    176        // it doesn't make much sense to display a color scale legend for a
    177        // FixedColorScale so we check for that and ignore it (unless the
    178        // developer switched the ignoreFixedColorScale flag, in which case
    179        // you can have your legend)...
    180        if (this.ignoreFixedColorScale
    181                && renderer.getColorScale() instanceof FixedColorScale) {
    182            return null;
    183        }
    184        return createColorScaleLegend(renderer, orientation, anchor, style);
    185    }
    186
    187    private TableElement createColorScaleLegend(ColorScaleRenderer r,
    188            Orientation orientation, Anchor2D anchor, ChartStyle style) {
    189        ColorScale scale = r.getColorScale();
    190        ColorScaleElement element = new ColorScaleElement(scale, orientation,
    191                this.barWidth, this.barLength, style.getLegendItemFont(),
    192                style.getLegendItemColor());
    193        element.setBackgroundColor(style.getLegendItemBackgroundColor());
    194        element.setRefPoint(anchor.getRefPt());
    195        return element;
    196    }
    197
    198    /**
    199     * Tests this builder for equality with an arbitrary object.
    200     *
    201     * @param obj  the object ({@code null} permitted).
    202     *
    203     * @return A boolean.
    204     */
    205    @Override
    206    public boolean equals(Object obj) {
    207        if (obj == this) {
    208            return true;
    209        }
    210        if (!(obj instanceof ColorScaleLegendBuilder)) {
    211            return false;
    212        }
    213        ColorScaleLegendBuilder that = (ColorScaleLegendBuilder) obj;
    214        if (this.barWidth != that.barWidth) {
    215            return false;
    216        }
    217        if (this.barLength != that.barLength) {
    218            return false;
    219        }
    220        return true;
    221    }
    222}