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     * $Id: CategoryTextAnnotation.java,v 1.6.2.3 2007/03/06 16:12:18 mungady Exp $
036     *
037     * Changes:
038     * --------
039     * 02-Apr-2003 : Version 1 (DG);
040     * 02-Jul-2003 : Added new text alignment and rotation options (DG);
041     * 04-Jul-2003 : Added a category anchor option (DG);
042     * 19-Aug-2003 : Added equals() method and implemented Cloneable (DG);
043     * 21-Jan-2004 : Update for renamed method in ValueAxis (DG);
044     * 30-Sep-2004 : Moved drawRotatedString() from RefineryUtilities 
045     *               --> TextUtilities (DG);
046     * ------------- JFREECHART 1.0.x -------------------------------------------
047     * 06-Mar-2007 : Implemented hashCode() (DG);
048     *
049     */
050    
051    package org.jfree.chart.annotations;
052    
053    import java.awt.Graphics2D;
054    import java.awt.geom.Rectangle2D;
055    import java.io.Serializable;
056    
057    import org.jfree.chart.axis.CategoryAnchor;
058    import org.jfree.chart.axis.CategoryAxis;
059    import org.jfree.chart.axis.ValueAxis;
060    import org.jfree.chart.plot.CategoryPlot;
061    import org.jfree.chart.plot.Plot;
062    import org.jfree.chart.plot.PlotOrientation;
063    import org.jfree.data.category.CategoryDataset;
064    import org.jfree.text.TextUtilities;
065    import org.jfree.ui.RectangleEdge;
066    
067    /**
068     * A text annotation that can be placed on a {@link CategoryPlot}.
069     */
070    public class CategoryTextAnnotation extends TextAnnotation
071                                        implements CategoryAnnotation, 
072                                                   Cloneable, Serializable {
073    
074        /** For serialization. */
075        private static final long serialVersionUID = 3333360090781320147L;
076        
077        /** The category. */
078        private Comparable category;
079    
080        /** The category anchor (START, MIDDLE, or END). */
081        private CategoryAnchor categoryAnchor;
082         
083        /** The value. */
084        private double value;
085    
086        /**
087         * Creates a new annotation to be displayed at the given location.
088         *
089         * @param text  the text (<code>null</code> not permitted).
090         * @param category  the category (<code>null</code> not permitted).
091         * @param value  the value.
092         */
093        public CategoryTextAnnotation(String text, Comparable category, 
094                                      double value) {
095            super(text);
096            if (category == null) {
097                throw new IllegalArgumentException("Null 'category' argument.");   
098            }
099            this.category = category;
100            this.value = value;
101            this.categoryAnchor = CategoryAnchor.MIDDLE;
102        }
103    
104        /**
105         * Returns the category.
106         * 
107         * @return The category (never <code>null</code>).
108         * 
109         * @see #setCategory(Comparable)
110         */
111        public Comparable getCategory() {
112            return this.category;
113        }
114        
115        /**
116         * Sets the category that the annotation attaches to.
117         * 
118         * @param category  the category (<code>null</code> not permitted).
119         * 
120         * @see #getCategory()
121         */
122        public void setCategory(Comparable category) {
123            if (category == null) {
124                throw new IllegalArgumentException("Null 'category' argument.");   
125            }
126            this.category = category;
127        }
128        
129        /**
130         * Returns the category anchor point.
131         * 
132         * @return The category anchor point.
133         * 
134         * @see #setCategoryAnchor(CategoryAnchor)
135         */
136        public CategoryAnchor getCategoryAnchor() {
137            return this.categoryAnchor;
138        }
139        
140        /**
141         * Sets the category anchor point.
142         * 
143         * @param anchor  the anchor point (<code>null</code> not permitted).
144         * 
145         * @see #getCategoryAnchor()
146         */
147        public void setCategoryAnchor(CategoryAnchor anchor) {
148            if (anchor == null) {
149                throw new IllegalArgumentException("Null 'anchor' argument.");   
150            }
151            this.categoryAnchor = anchor;    
152        }
153        
154        /**
155         * Returns the value that the annotation attaches to.
156         * 
157         * @return The value.
158         * 
159         * @see #setValue(double)
160         */
161        public double getValue() {
162            return this.value;
163        }
164        
165        /**
166         * Sets the value.
167         * 
168         * @param value  the value.
169         * 
170         * @see #getValue()
171         */
172        public void setValue(double value) {
173            this.value = value;    
174        }
175        
176        /**
177         * Draws the annotation.
178         *
179         * @param g2  the graphics device.
180         * @param plot  the plot.
181         * @param dataArea  the data area.
182         * @param domainAxis  the domain axis.
183         * @param rangeAxis  the range axis.
184         */
185        public void draw(Graphics2D g2, CategoryPlot plot, Rectangle2D dataArea,
186                         CategoryAxis domainAxis, ValueAxis rangeAxis) {
187    
188            CategoryDataset dataset = plot.getDataset();
189            int catIndex = dataset.getColumnIndex(this.category);
190            int catCount = dataset.getColumnCount();
191    
192            float anchorX = 0.0f;
193            float anchorY = 0.0f;
194            PlotOrientation orientation = plot.getOrientation();
195            RectangleEdge domainEdge = Plot.resolveDomainAxisLocation(
196                    plot.getDomainAxisLocation(), orientation);
197            RectangleEdge rangeEdge = Plot.resolveRangeAxisLocation(
198                    plot.getRangeAxisLocation(), orientation);
199            
200            if (orientation == PlotOrientation.HORIZONTAL) {
201                anchorY = (float) domainAxis.getCategoryJava2DCoordinate(
202                        this.categoryAnchor, catIndex, catCount, dataArea, 
203                        domainEdge);
204                anchorX = (float) rangeAxis.valueToJava2D(this.value, dataArea, 
205                        rangeEdge);
206            }
207            else if (orientation == PlotOrientation.VERTICAL) {
208                anchorX = (float) domainAxis.getCategoryJava2DCoordinate(
209                        this.categoryAnchor, catIndex, catCount, dataArea, 
210                        domainEdge);
211                anchorY = (float) rangeAxis.valueToJava2D(this.value, dataArea, 
212                        rangeEdge);
213            }
214            g2.setFont(getFont());
215            g2.setPaint(getPaint());
216            TextUtilities.drawRotatedString(getText(), g2, anchorX, anchorY,
217                    getTextAnchor(), getRotationAngle(), getRotationAnchor());
218    
219        }
220    
221        /**
222         * Tests this object for equality with another.
223         * 
224         * @param obj  the object (<code>null</code> permitted).
225         * 
226         * @return <code>true</code> or <code>false</code>.
227         */
228        public boolean equals(Object obj) {
229            if (obj == this) {
230                return true;
231            }
232            if (!(obj instanceof CategoryTextAnnotation)) {
233                return false;
234            }
235            CategoryTextAnnotation that = (CategoryTextAnnotation) obj;
236            if (!super.equals(obj)) {
237                return false;
238            }
239            if (!this.category.equals(that.getCategory())) {
240                return false;
241            }
242            if (!this.categoryAnchor.equals(that.getCategoryAnchor())) {
243                return false;
244            }
245            if (this.value != that.getValue()) {
246                return false;    
247            }
248            return true;
249        }
250        
251        /**
252         * Returns a hash code for this instance.
253         * 
254         * @return A hash code.
255         */
256        public int hashCode() {
257            int result = super.hashCode();
258            result = 37 * result + this.category.hashCode();
259            result = 37 * result + this.categoryAnchor.hashCode();
260            long temp = Double.doubleToLongBits(this.value);
261            result = 37 * result + (int) (temp ^ (temp >>> 32));
262            return result;
263        }
264        
265        /**
266         * Returns a clone of the annotation.
267         * 
268         * @return A clone.
269         * 
270         * @throws CloneNotSupportedException  this class will not throw this 
271         *         exception, but subclasses (if any) might.
272         */
273        public Object clone() throws CloneNotSupportedException {
274            return super.clone();    
275        }
276        
277    }