    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.text.Format;
    036
    037/**
    038 * <p>Provides standard tick sizes and formatting for numerical axes.
    039 * Conceptually, the selector maintains a list of standard tick sizes (ordered
    040 * by size), and a pointer to the current (selected) tick size.  Clients of
    041 * the selector will initialise the pointer by calling the
    042 * {@link #select(double)} method with a reference value (a guess, based on
    043 * context, of the largest usable tick size - for example, one half of the
    044 * axis length) then, as required, move the pointer to a smaller or larger
    045 * tick size (using the {@link #next()} and {@link #previous()} methods) to
    046 * find the most appropriate standard size to use.</p>
    047 *
    048 * <p>The {@link NumberTickSelector} class provides a standard implementation,
    049 * but you can create your own if necessary.</p>
    050 */
    051public interface TickSelector {
    052
    053    /**
    054     * Selects and returns a standard tick size that is greater than or equal to
    055     * the specified reference value and, ideally, as close to it as possible
    056     * (to minimise the number of iterations used by axes to determine the tick
    057     * size to use).  After a call to this method, the
    058     * {@link #getCurrentTickSize()} method should return the selected tick
    059     * size (there is a "cursor" that points to this tick size), the
    060     * {@link #next()} method should move the pointer to the next (larger)
    061     * standard tick size, and the {@link #previous()} method should move the
    062     * pointer to the  previous (smaller) standard tick size.
    063     *
    064     * @param reference  the reference value (must be positive and finite).
    065     *
    066     * @return The selected tick size.
    067     */
    068    double select(double reference);
    069
    070    /**
    071     * Move the cursor to the next (larger) tick size, if there is one.
    072     * Returns {@code true} in the case that the cursor is moved, and
    073     * {@code false} where there are a finite number of tick sizes and the
    074     * current tick size is the largest available.
    075     *
    076     * @return A boolean.
    077     */
    078    boolean next();
    079
    080    /**
    081     * Move the cursor to the previous (smaller) tick size, if there is one.
    082     * Returns {@code true} in the case that the cursor is moved, and
    083     * {@code false} where there are a finite number of tick sizes and the
    084     * current tick size is the smallest available.
    085     *
    086     * @return A boolean.
    087     */
    088    boolean previous();
    089
    090    /**
    091     * Returns the tick size that the cursor is currently referencing.
    092     *
    093     * @return The tick size.
    094     */
    095    double getCurrentTickSize();
    096
    097    /**
    098     * Returns the tick formatter associated with the tick size that the
    099     * cursor is currently referencing.
    100     *
    101     * @return The formatter.
    102     */
    103    Format getCurrentTickLabelFormat();
    104
    105}