    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.axis;
    034
    035import java.util.List;
    036import com.orsoncharts.data.category.CategoryDataset3D;
    037import com.orsoncharts.marker.CategoryMarker;
    038import com.orsoncharts.marker.MarkerData;
    039import com.orsoncharts.plot.CategoryPlot3D;
    040
    041/**
    042 * An axis that displays categories and is used with a {@link CategoryPlot3D}
    043 * for the row and column axes.  Most of the methods in this interface are
    044 * intended to be called by the plot that the axis is assigned to, they won't
    045 * normally be called by external code.
    046 */
    047public interface CategoryAxis3D extends Axis3D {
    048
    049    /**
    050     * Returns {@code true} if this axis is being used as the row axis
    051     * in a plot, and {@code false} otherwise.
    052     *
    053     * @return A boolean.
    054     *
    055     * @since 1.3
    056     */
    057    boolean isRowAxis();
    058
    059    /**
    060     * Returns {@code true} if this axis is being used as the column axis
    061     * in a plot, and {@code false} otherwise.
    062     *
    063     * @return A boolean.
    064     *
    065     * @since 1.3
    066     */
    067    boolean isColumnAxis();
    068
    069    /**
    070     * Configure the axis as a row axis for the specified plot.  Note that this
    071     * method will be called by the plot, it will not normally be called by
    072     * external code.
    073     *
    074     * @param plot  the plot ({@code null} not permitted).
    075     */
    076    void configureAsRowAxis(CategoryPlot3D plot);
    077
    078    /**
    079     * Configure the axis as a column axis for the specified plot.  Note that
    080     * this method will be called by the plot, it will not normally be called
    081     * by external code.
    082     *
    083     * @param plot  the plot ({@code null} not permitted).
    084     */
    085    void configureAsColumnAxis(CategoryPlot3D plot);
    086
    087    /**
    088     * Returns the width of a single category in units corresponding to
    089     * the current axis range.
    090     *
    091     * @return The width of a single category.
    092     */
    093    double getCategoryWidth();
    094
    095    /**
    096     * Returns the numerical value along the axis that corresponds to the
    097     * specified category.  If the category is unknown, this method will
    098     * return {@code Double.NaN}.
    099     *
    100     * @param category  the category ({@code null} not permitted).
    101     *
    102     * @return The axis value.
    103     */
    104    double getCategoryValue(Comparable<?> category);
    105
    106    /**
    107     * Generates the tick data for the axis (assumes the axis is being used
    108     * as the row axis).  The dataset is passed as an argument to provide the
    109     * opportunity to incorporate dataset-specific info into tick labels (for
    110     * example, a row label might show the total for that row in the dataset)
    111     * ---whether or not this is used depends on the axis implementation.
    112     *
    113     * @param dataset  the dataset ({@code null} not permitted).
    114     *
    115     * @return The tick data.
    116     *
    117     * @since 1.2
    118     */
    119    List<TickData> generateTickDataForRows(CategoryDataset3D dataset);
    120
    121    /**
    122     * Generates the tick data for the axis (assumes the axis is being used
    123     * as the row axis).  The dataset is passed as an argument to provide the
    124     * opportunity to incorporate dataset-specific info into tick labels (for
    125     * example, a row label might show the total for that row in the dataset)
    126     * ---whether or not this is used depends on the axis implementation.
    127     *
    128     * @param dataset  the dataset ({@code null} not permitted).
    129     *
    130     * @return The tick data.
    131     *
    132     * @since 1.2
    133     */
    134    List<TickData> generateTickDataForColumns(CategoryDataset3D dataset);
    135
    136    /**
    137     * Returns a list of marker data instances for the markers that fall
    138     * within the current axis range.
    139     *
    140     * @return A list of marker data.
    141     */
    142    List<MarkerData> generateMarkerData();
    143
    144    /**
    145     * Returns the marker with the specified key, if there is one.
    146     *
    147     * @param key  the key ({@code null} not permitted).
    148     *
    149     * @return The marker (possibly {@code null}).
    150     *
    151     * @since 1.2
    152     */
    153    CategoryMarker getMarker(String key);
    154}