    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.renderer.category;
    034
    035import java.awt.Color;
    036import com.orsoncharts.Range;
    037import com.orsoncharts.data.category.CategoryDataset3D;
    038import com.orsoncharts.data.Values3D;
    039import com.orsoncharts.graphics3d.Dimension3D;
    040import com.orsoncharts.graphics3d.World;
    041import com.orsoncharts.plot.CategoryPlot3D;
    042import com.orsoncharts.renderer.Renderer3D;
    043import com.orsoncharts.renderer.Renderer3DChangeEvent;
    044
    045/**
    046 * Defines the methods that all renderers must support to work with a
    047 * {@link CategoryPlot3D}.
    048 */
    049public interface CategoryRenderer3D extends Renderer3D {
    050
    051    /**
    052     * Returns the plot that this renderer is assigned to.
    053     *
    054     * @return The plot (possibly {@code null}).
    055     */
    056    CategoryPlot3D getPlot();
    057
    058    /**
    059     * Sets the plot that the renderer is assigned to.  Although this method
    060     * is part of the public API, client code should not need to call it.
    061     *
    062     * @param plot  the plot ({@code null} permitted).
    063     */
    064    void setPlot(CategoryPlot3D plot);
    065
    066    /**
    067     * Returns the color source for the renderer, which is an object that
    068     * is responsible for providing the colors used by the renderer to draw
    069     * data (and legend) items.
    070     *
    071     * @return The paint source (never {@code null}).
    072     */
    073    CategoryColorSource getColorSource();
    074
    075    /**
    076     * Sets the color source for the renderer and sends a
    077     * {@link Renderer3DChangeEvent} to all registered listeners.
    078     *
    079     * @param source  the color source ({@code null} not permitted).
    080     */
    081    void setColorSource(CategoryColorSource source);
    082
    083    /**
    084     * Sets the colors for the renderer.
    085     *
    086     * @param colors  the colors.
    087     *
    088     * @since 1.2
    089     */
    090    void setColors(Color... colors);
    091
    092    /**
    093     * Returns the range that should be used on the value axis to display all
    094     * the specified data using this renderer.  Normally this will return the
    095     * minimum and maximum values in the dataset, but some renderers require
    096     * a larger range (for example, the stacked bar renderer).
    097     *
    098     * @param data  the data values ({@code null} not permitted).
    099     *
    100     * @return The data range.
    101     */
    102    Range findValueRange(Values3D<? extends Number> data);
    103
    104    /**
    105     * Constructs and places one item from the specified dataset into the given
    106     * world.  This method will be called by the {@link CategoryPlot3D} class
    107     * while iterating over the items in the dataset.
    108     *
    109     * @param dataset  the dataset ({@code null} not permitted).
    110     * @param series  the series index.
    111     * @param row  the row index.
    112     * @param column  the column index.
    113     * @param world  the world ({@code null} not permitted).
    114     * @param dimensions  the plot dimensions ({@code null} not permitted).
    115     * @param xOffset  the x-offset.
    116     * @param yOffset  the y-offset.
    117     * @param zOffset  the z-offset.
    118     */
    119    void composeItem(CategoryDataset3D dataset, int series, int row, int column,
    120            World world, Dimension3D dimensions,
    121            double xOffset, double yOffset, double zOffset);
    122
    123}