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.axis;
034
035import java.awt.Color;
036import java.awt.Graphics2D;
037import java.awt.geom.Point2D;
038import java.awt.Font;
039import java.util.List;
040import org.jfree.chart3d.ChartElement;
041import org.jfree.chart3d.data.Range;
042import org.jfree.chart3d.graphics3d.RenderingInfo;
043
044/**
045 * An interface that must be supported by axes for 3D plots.
046 */
047public interface Axis3D extends ChartElement {
048
049    /**
050     * Returns the flag that determines whether or not the axis is drawn 
051     * on the chart.
052     * 
053     * @return A boolean.
054     * 
055     * @see #setVisible(boolean) 
056     */
057    boolean isVisible();
058    
059    /**
060     * Sets the flag that determines whether or not the axis is drawn on the
061     * chart and sends an {@link Axis3DChangeEvent} to all registered listeners.
062     * 
063     * @param visible  the flag.
064     * 
065     * @see #isVisible() 
066     */
067    void setVisible(boolean visible);
068    
069    /**
070     * Returns the font that is used to display the main axis label.
071     * 
072     * @return The font (never {@code null}). 
073     */
074    Font getLabelFont();
075    
076    /**
077     * Sets the font for the axis label (the main label, not the tick labels)
078     * and sends an {@link Axis3DChangeEvent} to all registered listeners.
079     * 
080     * @param font  the font ({@code null} not permitted). 
081     */
082    void setLabelFont(Font font);
083    
084    /**
085     * Returns the color used to draw the axis label.
086     * 
087     * @return The color (never {@code null}).
088     * 
089     * @since 1.2
090     */
091    Color getLabelColor();
092    
093    /**
094     * Sets the color used to draw the axis label and sends an 
095     * {@link Axis3DChangeEvent} to all registered listeners.
096     * 
097     * @param color  the color ({@code null} not permitted). 
098     * 
099     * @since 1.2
100     */
101    void setLabelColor(Color color);
102    
103    /**
104     * Returns the font that is used to display the tick labels.
105     * 
106     * @return The font (never {@code null}). 
107     */
108    Font getTickLabelFont();
109    
110    /**
111     * Sets the font for the tick labels and sends an {@link Axis3DChangeEvent} 
112     * to all registered listeners.
113     * 
114     * @param font  the font ({@code null} not permitted). 
115     */
116    void setTickLabelFont(Font font);
117    
118    /**
119     * Returns the color used to draw the axis tick labels.
120     * 
121     * @return The color (never {@code null}). 
122     * 
123     * @since 1.2
124     */
125    Color getTickLabelColor();
126    
127    /**
128     * Sets the color used to draw the axis tick labels and sends an 
129     * {@link Axis3DChangeEvent} to all registered listeners.
130     * 
131     * @param color  the color ({@code null} not permitted). 
132     * 
133     * @since 1.2
134     */
135    void setTickLabelColor(Color color);
136
137    /**
138     * Returns the axis range (the minimum and maximum values displayed on 
139     * the axis).  Note that even categorical axes will have a range, although
140     * since numerical values are not displayed the range is often set to
141     * {@code (0.0, 1.0)} for convenience.
142     * 
143     * @return The axis range (never {@code null}). 
144     */
145    Range getRange();
146
147    /**
148     * Sets the axis range and sends an {@link Axis3DChangeEvent} to all
149     * registered listeners.
150     * 
151     * @param range  the range ({@code null} not permitted). 
152     */
153    void setRange(Range range);
154  
155    /**
156     * Sets the axis range and sends an {@link Axis3DChangeEvent} to all
157     * registered listeners.
158     * 
159     * @param min  the lower bound for the axis.
160     * @param max  the upper bound for the axis.
161     */
162    void setRange(double min, double max);
163    
164    /**
165     * Returns the flag that determines whether or not the order of values on 
166     * the axis is inverted.  The default value is {@code false}.
167     * 
168     * @return A boolean.
169     * 
170     * @since 1.5
171     */
172    boolean isInverted();
173    
174    /**
175     * Sets the flag that determines whether or not the order of values on the
176     * axis is inverted, and sends an {@link Axis3DChangeEvent} to all 
177     * registered listeners.
178     * 
179     * @param inverted  the new flag value.
180     * 
181     * @since 1.5
182     */
183    void setInverted(boolean inverted);
184    
185    /**
186     * Translates a data value to a world coordinate.  Since we draw the charts
187     * in a box that has one corner at {@code (0, 0, 0)}, we only need to 
188     * know the length of the side of the box along which we are translating in 
189     * order to do the calculation.
190     * 
191     * @param value  the data value.
192     * @param length  the box side length.
193     * 
194     * @return The translated value. 
195     */
196    double translateToWorld(double value, double length);
197
198    /**
199     * Draws the axis along an arbitrary line (between {@code startPt} 
200     * and {@code endPt}).  The opposing point is used as a reference
201     * point to know on which side of the axis to draw the labels.
202     * 
203     * @param g2  the graphics target ({@code null} not permitted).
204     * @param startPt  the starting point ({@code null} not permitted).
205     * @param endPt  the end point ({@code null} not permitted)
206     * @param opposingPt  an opposing point ({@code null} not permitted).
207     * @param tickData  info about the ticks to draw ({@code null} not 
208     *     permitted).
209     * @param info  an object to be populated with rendering info 
210     *     ({@code null} permitted).
211     * @param hinting  a flag that controls whether or not element hinting 
212     *     should be performed.
213     * 
214     * @since 1.3
215     */
216    void draw(Graphics2D g2, Point2D startPt, Point2D endPt, Point2D opposingPt, 
217            List<TickData> tickData, RenderingInfo info, boolean hinting);
218
219    /**
220     * Registers a listener so that it receives notification of changes to the
221     * axis.
222     * 
223     * @param listener  the listener ({@code null} not permitted).
224     */
225    void addChangeListener(Axis3DChangeListener listener);
226    
227    /**
228     * Deregisters a listener so that it no longer receives notification of
229     * changes to the axis.
230     * 
231     * @param listener  the listener ({@code null} not permitted). 
232     */
233    void removeChangeListener(Axis3DChangeListener listener);
234
235}