001/* ===========================================================
002 * Orson Charts : a 3D chart library for the Java(tm) platform
003 * ===========================================================
004 * 
005 * (C)opyright 2013-2022, by David Gilbert.  All rights reserved.
006 * 
007 * https://github.com/jfree/orson-charts
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 org.jfree.chart3d.renderer.category;
034
035import java.awt.Color;
036import org.jfree.chart3d.data.Range;
037import org.jfree.chart3d.data.Values3D;
038import org.jfree.chart3d.data.category.CategoryDataset3D;
039import org.jfree.chart3d.graphics3d.Dimension3D;
040import org.jfree.chart3d.graphics3d.World;
041import org.jfree.chart3d.plot.CategoryPlot3D;
042import org.jfree.chart3d.renderer.Renderer3D;
043import org.jfree.chart3d.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}