001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2005, 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-2005, 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.1 2005/10/25 16:51:15 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     *
047     */
048    
049    package org.jfree.chart.annotations;
050    
051    import java.awt.Graphics2D;
052    import java.awt.geom.Rectangle2D;
053    import java.io.Serializable;
054    
055    import org.jfree.chart.axis.CategoryAnchor;
056    import org.jfree.chart.axis.CategoryAxis;
057    import org.jfree.chart.axis.ValueAxis;
058    import org.jfree.chart.plot.CategoryPlot;
059    import org.jfree.chart.plot.Plot;
060    import org.jfree.chart.plot.PlotOrientation;
061    import org.jfree.data.category.CategoryDataset;
062    import org.jfree.text.TextUtilities;
063    import org.jfree.ui.RectangleEdge;
064    
065    /**
066     * A text annotation that can be placed on a 
067     * {@link org.jfree.chart.plot.CategoryPlot}.
068     */
069    public class CategoryTextAnnotation extends TextAnnotation
070                                        implements CategoryAnnotation, 
071                                                   Cloneable, Serializable {
072    
073        /** For serialization. */
074        private static final long serialVersionUID = 3333360090781320147L;
075        
076        /** The category. */
077        private Comparable category;
078    
079        /** The category anchor (START, MIDDLE, or END). */
080        private CategoryAnchor categoryAnchor;
081         
082        /** The value. */
083        private double value;
084    
085        /**
086         * Creates a new annotation to be displayed at the given location.
087         *
088         * @param text  the text (<code>null</code> not permitted).
089         * @param category  the category (<code>null</code> not permitted).
090         * @param value  the value.
091         */
092        public CategoryTextAnnotation(String text, Comparable category, 
093                                      double value) {
094            super(text);
095            if (category == null) {
096                throw new IllegalArgumentException("Null 'category' argument.");   
097            }
098            this.category = category;
099            this.value = value;
100            this.categoryAnchor = CategoryAnchor.MIDDLE;
101        }
102    
103        /**
104         * Returns the category.
105         * 
106         * @return The category (never <code>null</code>).
107         */
108        public Comparable getCategory() {
109            return this.category;
110        }
111        
112        /**
113         * Sets the category that the annotation attaches to.
114         * 
115         * @param category  the category (<code>null</code> not permitted).
116         */
117        public void setCategory(Comparable category) {
118            if (category == null) {
119                throw new IllegalArgumentException("Null 'category' argument.");   
120            }
121            this.category = category;
122        }
123        
124        /**
125         * Returns the category anchor point.
126         * 
127         * @return The category anchor point.
128         */
129        public CategoryAnchor getCategoryAnchor() {
130            return this.categoryAnchor;
131        }
132        
133        /**
134         * Sets the category anchor point.
135         * 
136         * @param anchor  the anchor point (<code>null</code> not permitted).
137         */
138        public void setCategoryAnchor(CategoryAnchor anchor) {
139            if (anchor == null) {
140                throw new IllegalArgumentException("Null 'anchor' argument.");   
141            }
142            this.categoryAnchor = anchor;    
143        }
144        
145        /**
146         * Returns the value that the annotation attaches to.
147         * 
148         * @return The value.
149         */
150        public double getValue() {
151            return this.value;
152        }
153        
154        /**
155         * Sets the value.
156         * 
157         * @param value  the value.
158         */
159        public void setValue(double value) {
160            this.value = value;    
161        }
162        
163        /**
164         * Draws the annotation.
165         *
166         * @param g2  the graphics device.
167         * @param plot  the plot.
168         * @param dataArea  the data area.
169         * @param domainAxis  the domain axis.
170         * @param rangeAxis  the range axis.
171         */
172        public void draw(Graphics2D g2, CategoryPlot plot, Rectangle2D dataArea,
173                         CategoryAxis domainAxis, ValueAxis rangeAxis) {
174    
175            CategoryDataset dataset = plot.getDataset();
176            int catIndex = dataset.getColumnIndex(this.category);
177            int catCount = dataset.getColumnCount();
178    
179            float anchorX = 0.0f;
180            float anchorY = 0.0f;
181            PlotOrientation orientation = plot.getOrientation();
182            RectangleEdge domainEdge = Plot.resolveDomainAxisLocation(
183                plot.getDomainAxisLocation(), orientation
184            );
185            RectangleEdge rangeEdge = Plot.resolveRangeAxisLocation(
186                plot.getRangeAxisLocation(), orientation
187            );
188            
189            if (orientation == PlotOrientation.HORIZONTAL) {
190                anchorY = (float) domainAxis.getCategoryJava2DCoordinate(
191                    this.categoryAnchor, catIndex, catCount, dataArea, domainEdge
192                );
193                anchorX = (float) rangeAxis.valueToJava2D(
194                    this.value, dataArea, rangeEdge
195                );
196            }
197            else if (orientation == PlotOrientation.VERTICAL) {
198                anchorX = (float) domainAxis.getCategoryJava2DCoordinate(
199                    this.categoryAnchor, catIndex, catCount, dataArea, domainEdge
200                );
201                anchorY = (float) rangeAxis.valueToJava2D(
202                    this.value, dataArea, rangeEdge
203                );
204            }
205            g2.setFont(getFont());
206            g2.setPaint(getPaint());
207            TextUtilities.drawRotatedString(
208                getText(), 
209                g2,
210                anchorX, 
211                anchorY,
212                getTextAnchor(),
213                getRotationAngle(),
214                getRotationAnchor()
215            );
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 clone of the annotation.
251         * 
252         * @return A clone.
253         * 
254         * @throws CloneNotSupportedException  this class will not throw this 
255         *         exception, but subclasses (if any) might.
256         */
257        public Object clone() throws CloneNotSupportedException {
258            return super.clone();    
259        }
260        
261    }