001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2003-2006, Geotools Project Managment Committee (PMC)
005: * (C) 2000, Institut de Recherche pour le Développement
006: * (C) 1999, Pêches et Océans Canada
007: *
008: * This library is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU Lesser General Public
010: * License as published by the Free Software Foundation; either
011: * version 2.1 of the License, or (at your option) any later version.
012: *
013: * This library is distributed in the hope that it will be useful,
014: * but WITHOUT ANY WARRANTY; without even the implied warranty of
015: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
016: * Lesser General Public License for more details.
017: */
018: package org.geotools.axis;
019:
020: import java.awt.Font;
021: import java.awt.RenderingHints;
022: import java.beans.PropertyChangeListener;
023: import java.text.Format;
024: import java.util.Locale;
025: import javax.units.Unit;
026:
027: /**
028: * An axis's graduation. A {@code Graduation} object encompass minimal
029: * and maximal values for an axis in arbitrary units, and allow access to
030: * tick locations and labels through a {@link TickIterator} object.
031: * <p>
032: * Different implementations may compute tick locations in different ways.
033: * For example a graduation for dates is handled in a different way than a
034: * graduation for numbers.
035: *
036: * @since 2.0
037: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/extension/widgets-swing/src/main/java/org/geotools/axis/Graduation.java $
038: * @version $Id: Graduation.java 27576 2007-10-22 13:54:24Z desruisseaux $
039: * @author Martin Desruisseaux
040: */
041: public interface Graduation {
042: /**
043: * Rendering hint for the axis length, in pixels or points (1/72 of inch).
044: * Values for this key must be {@link Number} objects. This hint is used
045: * together with {@link #VISUAL_TICK_SPACING} during {@link TickIterator}
046: * creation in order to compute a tick increment value.
047: *
048: * @see #getTickIterator
049: */
050: RenderingHints.Key VISUAL_AXIS_LENGTH = new RenderingHintKey(
051: Number.class, 0);
052:
053: /**
054: * Rendering hint for the preferred spacing between ticks, in pixels or points
055: * (1/72 of inch). Values for this key must be {@link Number} objects. This hint
056: * is used together with {@link #VISUAL_AXIS_LENGTH} during {@link TickIterator}
057: * creation in order to compute a tick increment value. The tick spacing really
058: * used may be slightly different, since {@link TickIterator} may choose a rounded
059: * value.
060: *
061: * @see #getTickIterator
062: */
063: RenderingHints.Key VISUAL_TICK_SPACING = new RenderingHintKey(
064: Number.class, 1);
065:
066: /**
067: * The font to use for rendering tick labels. Value for this key must be a {@link Font}
068: * object. If this hint is not provided, a default font will be used.
069: *
070: * @see Axis2D#paint
071: */
072: RenderingHints.Key TICK_LABEL_FONT = new RenderingHintKey(
073: Font.class, 2);
074:
075: /**
076: * The font to use for rendering the title. Value for this key must be a {@link Font} object.
077: * If this hint is not provided, a default font will be used.
078: *
079: * @see Axis2D#paint
080: */
081: RenderingHints.Key AXIS_TITLE_FONT = new RenderingHintKey(
082: Font.class, 3);
083:
084: /**
085: * Returns the minimal value for this graduation.
086: *
087: * @return The minimal value in {@link #getUnit} units.
088: *
089: * @see #getMaximum
090: * @see #getRange
091: */
092: double getMinimum();
093:
094: /**
095: * Returns the maximal value for this graduation.
096: *
097: * @return The maximal value in {@link #getUnit} units.
098: *
099: * @see #getMinimum
100: * @see #getRange
101: */
102: double getMaximum();
103:
104: /**
105: * Returns the graduation's range. This is equivalents to computing
106: * <code>{@link #getMaximum}-{@link #getMinimum}</code>. However, some
107: * implementation may optimize this computation in order to avoid rounding errors.
108: */
109: double getRange();
110:
111: /**
112: * Returns the axis title. If {@code includeUnits} is {@code true}, then the returned string
113: * will includes units as in "Temperature (°C)", or time zone as in "Start time (UTC)". The
114: * exact formatting is local-dependent.
115: *
116: * @param includeSymbol {@code true} to format the unit or timezone symbol after the name.
117: * @return The graduation name (also to be use as axis title).
118: */
119: String getTitle(final boolean includeSymbol);
120:
121: /**
122: * Returns the graduation's units, or {@code null} if unknow.
123: */
124: Unit getUnit();
125:
126: /**
127: * Returns the locale to use for formatting title and labels.
128: */
129: Locale getLocale();
130:
131: /**
132: * Returns the format to use for formatting labels. The format really used by
133: * {@link TickIterator#currentLabel} may not be the same. For example, some
134: * iterators may adjust automatically the number of fraction digits.
135: */
136: Format getFormat();
137:
138: /**
139: * Returns an iterator object that iterates along the graduation ticks and provides access to
140: * the graduation values. If an optional {@link RenderingHints} is specified, tick locations are
141: * adjusted according values for {@link #VISUAL_AXIS_LENGTH} and {@link #VISUAL_TICK_SPACING}
142: * keys.
143: *
144: * @param hints Rendering hints for the axis, or {@code null} for the default hints.
145: * @param reuse An iterator to reuse if possible, or {@code null} to create a new one. A
146: * non-null object may help to reduce the number of object garbage-collected when
147: * rendering the axis.
148: * @return A iterator to use for iterating through the graduation. This
149: * iterator may or may not be the {@code reuse} object.
150: */
151: TickIterator getTickIterator(RenderingHints hints,
152: TickIterator reuse);
153:
154: /**
155: * Adds a {@link PropertyChangeListener} to the listener list.
156: * The listener is registered for all properties, such as "label"
157: * and "locale".
158: */
159: void addPropertyChangeListener(PropertyChangeListener listener);
160:
161: /**
162: * Removes a {@link PropertyChangeListener} from the listener list.
163: */
164: void removePropertyChangeListener(PropertyChangeListener listener);
165: }
|