001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2007, by Object Refinery Limited and Contributors.
006 *
007 * Project Info:  http://www.jfree.org/jfreechart/index.html
008 *
009 * This library is free software; you can redistribute it and/or modify it 
010 * under the terms of the GNU Lesser General Public License as published by 
011 * the Free Software Foundation; either version 2.1 of the License, or 
012 * (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful, but 
015 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
016 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 
017 * License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, 
022 * USA.  
023 *
024 * [Java is a trademark or registered trademark of Sun Microsystems, Inc. 
025 * in the United States and other countries.]
026 *
027 * ---------------------------
028 * CategoryTextAnnotation.java
029 * ---------------------------
030 * (C) Copyright 2003-2007, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes:
036 * --------
037 * 02-Apr-2003 : Version 1 (DG);
038 * 02-Jul-2003 : Added new text alignment and rotation options (DG);
039 * 04-Jul-2003 : Added a category anchor option (DG);
040 * 19-Aug-2003 : Added equals() method and implemented Cloneable (DG);
041 * 21-Jan-2004 : Update for renamed method in ValueAxis (DG);
042 * 30-Sep-2004 : Moved drawRotatedString() from RefineryUtilities 
043 *               --> TextUtilities (DG);
044 * ------------- JFREECHART 1.0.x -------------------------------------------
045 * 06-Mar-2007 : Implemented hashCode() (DG);
046 *
047 */
048
049package org.jfree.chart.annotations;
050
051import java.awt.Graphics2D;
052import java.awt.geom.Rectangle2D;
053import java.io.Serializable;
054
055import org.jfree.chart.axis.CategoryAnchor;
056import org.jfree.chart.axis.CategoryAxis;
057import org.jfree.chart.axis.ValueAxis;
058import org.jfree.chart.plot.CategoryPlot;
059import org.jfree.chart.plot.Plot;
060import org.jfree.chart.plot.PlotOrientation;
061import org.jfree.data.category.CategoryDataset;
062import org.jfree.text.TextUtilities;
063import org.jfree.ui.RectangleEdge;
064
065/**
066 * A text annotation that can be placed on a {@link CategoryPlot}.
067 */
068public class CategoryTextAnnotation extends TextAnnotation
069                                    implements CategoryAnnotation, 
070                                               Cloneable, Serializable {
071
072    /** For serialization. */
073    private static final long serialVersionUID = 3333360090781320147L;
074    
075    /** The category. */
076    private Comparable category;
077
078    /** The category anchor (START, MIDDLE, or END). */
079    private CategoryAnchor categoryAnchor;
080     
081    /** The value. */
082    private double value;
083
084    /**
085     * Creates a new annotation to be displayed at the given location.
086     *
087     * @param text  the text (<code>null</code> not permitted).
088     * @param category  the category (<code>null</code> not permitted).
089     * @param value  the value.
090     */
091    public CategoryTextAnnotation(String text, Comparable category, 
092                                  double value) {
093        super(text);
094        if (category == null) {
095            throw new IllegalArgumentException("Null 'category' argument.");   
096        }
097        this.category = category;
098        this.value = value;
099        this.categoryAnchor = CategoryAnchor.MIDDLE;
100    }
101
102    /**
103     * Returns the category.
104     * 
105     * @return The category (never <code>null</code>).
106     * 
107     * @see #setCategory(Comparable)
108     */
109    public Comparable getCategory() {
110        return this.category;
111    }
112    
113    /**
114     * Sets the category that the annotation attaches to.
115     * 
116     * @param category  the category (<code>null</code> not permitted).
117     * 
118     * @see #getCategory()
119     */
120    public void setCategory(Comparable category) {
121        if (category == null) {
122            throw new IllegalArgumentException("Null 'category' argument.");   
123        }
124        this.category = category;
125    }
126    
127    /**
128     * Returns the category anchor point.
129     * 
130     * @return The category anchor point.
131     * 
132     * @see #setCategoryAnchor(CategoryAnchor)
133     */
134    public CategoryAnchor getCategoryAnchor() {
135        return this.categoryAnchor;
136    }
137    
138    /**
139     * Sets the category anchor point.
140     * 
141     * @param anchor  the anchor point (<code>null</code> not permitted).
142     * 
143     * @see #getCategoryAnchor()
144     */
145    public void setCategoryAnchor(CategoryAnchor anchor) {
146        if (anchor == null) {
147            throw new IllegalArgumentException("Null 'anchor' argument.");   
148        }
149        this.categoryAnchor = anchor;    
150    }
151    
152    /**
153     * Returns the value that the annotation attaches to.
154     * 
155     * @return The value.
156     * 
157     * @see #setValue(double)
158     */
159    public double getValue() {
160        return this.value;
161    }
162    
163    /**
164     * Sets the value.
165     * 
166     * @param value  the value.
167     * 
168     * @see #getValue()
169     */
170    public void setValue(double value) {
171        this.value = value;    
172    }
173    
174    /**
175     * Draws the annotation.
176     *
177     * @param g2  the graphics device.
178     * @param plot  the plot.
179     * @param dataArea  the data area.
180     * @param domainAxis  the domain axis.
181     * @param rangeAxis  the range axis.
182     */
183    public void draw(Graphics2D g2, CategoryPlot plot, Rectangle2D dataArea,
184                     CategoryAxis domainAxis, ValueAxis rangeAxis) {
185
186        CategoryDataset dataset = plot.getDataset();
187        int catIndex = dataset.getColumnIndex(this.category);
188        int catCount = dataset.getColumnCount();
189
190        float anchorX = 0.0f;
191        float anchorY = 0.0f;
192        PlotOrientation orientation = plot.getOrientation();
193        RectangleEdge domainEdge = Plot.resolveDomainAxisLocation(
194                plot.getDomainAxisLocation(), orientation);
195        RectangleEdge rangeEdge = Plot.resolveRangeAxisLocation(
196                plot.getRangeAxisLocation(), orientation);
197        
198        if (orientation == PlotOrientation.HORIZONTAL) {
199            anchorY = (float) domainAxis.getCategoryJava2DCoordinate(
200                    this.categoryAnchor, catIndex, catCount, dataArea, 
201                    domainEdge);
202            anchorX = (float) rangeAxis.valueToJava2D(this.value, dataArea, 
203                    rangeEdge);
204        }
205        else if (orientation == PlotOrientation.VERTICAL) {
206            anchorX = (float) domainAxis.getCategoryJava2DCoordinate(
207                    this.categoryAnchor, catIndex, catCount, dataArea, 
208                    domainEdge);
209            anchorY = (float) rangeAxis.valueToJava2D(this.value, dataArea, 
210                    rangeEdge);
211        }
212        g2.setFont(getFont());
213        g2.setPaint(getPaint());
214        TextUtilities.drawRotatedString(getText(), g2, anchorX, anchorY,
215                getTextAnchor(), getRotationAngle(), getRotationAnchor());
216
217    }
218
219    /**
220     * Tests this object for equality with another.
221     * 
222     * @param obj  the object (<code>null</code> permitted).
223     * 
224     * @return <code>true</code> or <code>false</code>.
225     */
226    public boolean equals(Object obj) {
227        if (obj == this) {
228            return true;
229        }
230        if (!(obj instanceof CategoryTextAnnotation)) {
231            return false;
232        }
233        CategoryTextAnnotation that = (CategoryTextAnnotation) obj;
234        if (!super.equals(obj)) {
235            return false;
236        }
237        if (!this.category.equals(that.getCategory())) {
238            return false;
239        }
240        if (!this.categoryAnchor.equals(that.getCategoryAnchor())) {
241            return false;
242        }
243        if (this.value != that.getValue()) {
244            return false;    
245        }
246        return true;
247    }
248    
249    /**
250     * Returns a hash code for this instance.
251     * 
252     * @return A hash code.
253     */
254    public int hashCode() {
255        int result = super.hashCode();
256        result = 37 * result + this.category.hashCode();
257        result = 37 * result + this.categoryAnchor.hashCode();
258        long temp = Double.doubleToLongBits(this.value);
259        result = 37 * result + (int) (temp ^ (temp >>> 32));
260        return result;
261    }
262    
263    /**
264     * Returns a clone of the annotation.
265     * 
266     * @return A clone.
267     * 
268     * @throws CloneNotSupportedException  this class will not throw this 
269     *         exception, but subclasses (if any) might.
270     */
271    public Object clone() throws CloneNotSupportedException {
272        return super.clone();    
273    }
274    
275}