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     * ChartEntity.java
029     * ----------------
030     * (C) Copyright 2002-2007, by Object Refinery Limited and Contributors.
031     *
032     * Original Author:  David Gilbert (for Object Refinery Limited);
033     * Contributor(s):   Richard Atkinson;
034     *                   Xavier Poinsard;
035     *                   Robert Fuller;
036     *
037     * $Id: ChartEntity.java,v 1.8.2.2 2007/02/06 11:28:53 mungady Exp $
038     *
039     * Changes:
040     * --------
041     * 23-May-2002 : Version 1 (DG);
042     * 12-Jun-2002 : Added Javadoc comments (DG);
043     * 26-Jun-2002 : Added methods for image maps (DG);
044     * 05-Aug-2002 : Added constructor and accessors for URL support in image maps
045     *               Added getImageMapAreaTag() - previously in subclasses (RA);
046     * 05-Sep-2002 : Added getImageMapAreaTag(boolean) to support OverLIB for 
047     *               tooltips http://www.bosrup.com/web/overlib (RA);
048     * 03-Oct-2002 : Fixed errors reported by Checkstyle (DG);
049     * 08-Oct-2002 : Changed getImageMapAreaTag to use title instead of alt 
050     *               attribute so HTML image maps now work in Mozilla and Opera as 
051     *               well as Internet Explorer (RA);
052     * 13-Mar-2003 : Change getImageMapAreaTag to only return a tag when there is a
053     *               tooltip or URL, as suggested by Xavier Poinsard (see Feature 
054     *               Request 688079) (DG);
055     * 12-Aug-2003 : Added support for custom image maps using 
056     *               ToolTipTagFragmentGenerator and URLTagFragmentGenerator (RA);
057     * 02-Sep-2003 : Incorporated fix (791901) submitted by Robert Fuller (DG);
058     * 19-May-2004 : Added equals() method and implemented Cloneable and 
059     *               Serializable (DG);
060     * 29-Sep-2004 : Implemented PublicCloneable (DG);
061     * 13-Jan-2005 : Fixed for compliance with XHTML 1.0 (DG);
062     * 18-Apr-2005 : Use StringBuffer (DG);
063     * 20-Apr-2005 : Added toString() implementation (DG);
064     * ------------- JFREECHART 1.0.x ---------------------------------------------
065     * 06-Feb-2007 : API doc update (DG);
066     *
067     */
068    
069    package org.jfree.chart.entity;
070    
071    import java.awt.Shape;
072    import java.awt.geom.PathIterator;
073    import java.awt.geom.Rectangle2D;
074    import java.io.IOException;
075    import java.io.ObjectInputStream;
076    import java.io.ObjectOutputStream;
077    import java.io.Serializable;
078    
079    import org.jfree.chart.imagemap.ToolTipTagFragmentGenerator;
080    import org.jfree.chart.imagemap.URLTagFragmentGenerator;
081    import org.jfree.io.SerialUtilities;
082    import org.jfree.util.ObjectUtilities;
083    import org.jfree.util.PublicCloneable;
084    
085    /**
086     * A class that captures information about some component of a chart (a bar, 
087     * line etc).
088     */
089    public class ChartEntity implements Cloneable, PublicCloneable, Serializable {
090    
091        /** For serialization. */
092        private static final long serialVersionUID = -4445994133561919083L;
093        
094        /** The area occupied by the entity (in Java 2D space). */
095        private transient Shape area;
096    
097        /** The tool tip text for the entity. */
098        private String toolTipText;
099    
100        /** The URL text for the entity. */
101        private String urlText;
102    
103        /**
104         * Creates a new chart entity.
105         *
106         * @param area  the area (<code>null</code> not permitted).
107         */
108        public ChartEntity(Shape area) {
109            // defer argument checks...
110            this(area, null);
111        }
112    
113        /**
114         * Creates a new chart entity.
115         *
116         * @param area  the area (<code>null</code> not permitted).
117         * @param toolTipText  the tool tip text (<code>null</code> permitted).
118         */
119        public ChartEntity(Shape area, String toolTipText) {
120            // defer argument checks...
121            this(area, toolTipText, null);
122        }
123    
124        /**
125         * Creates a new entity.
126         *
127         * @param area  the area (<code>null</code> not permitted).
128         * @param toolTipText  the tool tip text (<code>null</code> permitted).
129         * @param urlText  the URL text for HTML image maps (<code>null</code> 
130         *                 permitted).
131         */
132        public ChartEntity(Shape area, String toolTipText, String urlText) {
133            if (area == null) {
134                throw new IllegalArgumentException("Null 'area' argument.");   
135            }
136            this.area = area;
137            this.toolTipText = toolTipText;
138            this.urlText = urlText;
139        }
140    
141        /**
142         * Returns the area occupied by the entity (in Java 2D space).
143         *
144         * @return The area (never <code>null</code>).
145         */
146        public Shape getArea() {
147            return this.area;
148        }
149    
150        /**
151         * Sets the area for the entity.
152         * <P>
153         * This class conveys information about chart entities back to a client.
154         * Setting this area doesn't change the entity (which has already been
155         * drawn).
156         *
157         * @param area  the area (<code>null</code> not permitted).
158         */
159        public void setArea(Shape area) {
160            if (area == null) {
161                throw new IllegalArgumentException("Null 'area' argument.");   
162            }
163            this.area = area;
164        }
165    
166        /**
167         * Returns the tool tip text for the entity.
168         *
169         * @return The tool tip text (possibly <code>null</code>).
170         */
171        public String getToolTipText() {
172            return this.toolTipText;
173        }
174    
175        /**
176         * Sets the tool tip text.
177         *
178         * @param text  the text (<code>null</code> permitted).
179         */
180        public void setToolTipText(String text) {
181            this.toolTipText = text;
182        }
183    
184        /**
185         * Returns the URL text for the entity.
186         *
187         * @return The URL text (possibly <code>null</code>).
188         */
189        public String getURLText() {
190            return this.urlText;
191        }
192    
193        /**
194         * Sets the URL text.
195         *
196         * @param text the text (<code>null</code> permitted).
197         */
198        public void setURLText(String text) {
199            this.urlText = text;
200        }
201    
202        /**
203         * Returns a string describing the entity area.  This string is intended
204         * for use in an AREA tag when generating an image map.
205         *
206         * @return The shape type (never <code>null</code>).
207         */
208        public String getShapeType() {
209            if (this.area instanceof Rectangle2D) {
210                return "rect";
211            }
212            else {
213                return "poly";
214            }
215        }
216    
217        /**
218         * Returns the shape coordinates as a string.
219         *
220         * @return The shape coordinates (never <code>null</code>).
221         */
222        public String getShapeCoords() {
223            if (this.area instanceof Rectangle2D) {
224                return getRectCoords((Rectangle2D) this.area);
225            }
226            else {
227                return getPolyCoords(this.area);
228            }
229        }
230    
231        /**
232         * Returns a string containing the coordinates (x1, y1, x2, y2) for a given
233         * rectangle.  This string is intended for use in an image map.
234         *
235         * @param rectangle  the rectangle (<code>null</code> not permitted).
236         *
237         * @return Upper left and lower right corner of a rectangle.
238         */
239        private String getRectCoords(Rectangle2D rectangle) {
240            if (rectangle == null) {
241                throw new IllegalArgumentException("Null 'rectangle' argument.");   
242            }
243            int x1 = (int) rectangle.getX();
244            int y1 = (int) rectangle.getY();
245            int x2 = x1 + (int) rectangle.getWidth();
246            int y2 = y1 + (int) rectangle.getHeight();
247            //      fix by rfuller
248            if (x2 == x1) {
249                x2++;
250            }
251            if (y2 == y1) {
252                y2++;
253            }
254            //      end fix by rfuller
255            return x1 + "," + y1 + "," + x2 + "," + y2;
256        }
257    
258        /**
259         * Returns a string containing the coordinates for a given shape.  This
260         * string is intended for use in an image map.
261         *
262         * @param shape  the shape (<code>null</code> not permitted).
263         *
264         * @return The coordinates for a given shape as string.
265         */
266        private String getPolyCoords(Shape shape) {
267            if (shape == null) {
268                throw new IllegalArgumentException("Null 'shape' argument.");   
269            }
270            StringBuffer result = new StringBuffer();
271            boolean first = true;
272            float[] coords = new float[6];
273            PathIterator pi = shape.getPathIterator(null, 1.0);
274            while (!pi.isDone()) {
275                pi.currentSegment(coords);
276                if (first) {
277                    first = false;
278                    result.append((int) coords[0]);
279                    result.append(",").append((int) coords[1]);
280                }
281                else {
282                    result.append(",");
283                    result.append((int) coords[0]);
284                    result.append(",");
285                    result.append((int) coords[1]);
286                }
287                pi.next();
288            }
289            return result.toString();
290        }
291    
292        /**
293         * Returns an HTML image map tag for this entity.  The returned fragment
294         * should be <code>XHTML 1.0</code> compliant.
295         *
296         * @param toolTipTagFragmentGenerator  a generator for the HTML fragment
297         *     that will contain the tooltip text (<code>null</code> not permitted 
298         *     if this entity contains tooltip information).
299         * @param urlTagFragmentGenerator  a generator for the HTML fragment that
300         *     will contain the URL reference (<code>null</code> not permitted if 
301         *     this entity has a URL).
302         * 
303         * @return The HTML tag.
304         */
305        public String getImageMapAreaTag(
306                ToolTipTagFragmentGenerator toolTipTagFragmentGenerator,
307                URLTagFragmentGenerator urlTagFragmentGenerator) {
308    
309            StringBuffer tag = new StringBuffer();
310            boolean hasURL = (this.urlText == null ? false 
311                    : !this.urlText.equals(""));
312            boolean hasToolTip = (this.toolTipText == null ? false 
313                    : !this.toolTipText.equals(""));
314            if (hasURL || hasToolTip) {
315                tag.append("<area shape=\"" + getShapeType() + "\"" + " coords=\"" 
316                        + getShapeCoords() + "\"");
317                if (hasToolTip) {
318                    tag.append(toolTipTagFragmentGenerator.generateToolTipFragment(
319                            this.toolTipText));
320                }
321                if (hasURL) {
322                    tag.append(urlTagFragmentGenerator.generateURLFragment(
323                            this.urlText));
324                }
325                // if there is a tool tip, we expect it to generate the title and
326                // alt values, so we only add an empty alt if there is no tooltip
327                if (!hasToolTip) {
328                    tag.append(" alt=\"\"");
329                }
330                tag.append("/>");
331            }
332            return tag.toString();
333        }
334        
335        /**
336         * Returns a string representation of the chart entity, useful for 
337         * debugging.
338         * 
339         * @return A string.
340         */
341        public String toString() {
342            StringBuffer buf = new StringBuffer("ChartEntity: ");
343            buf.append("tooltip = ");
344            buf.append(this.toolTipText);
345            return buf.toString();
346        }
347        
348        /**
349         * Tests the entity for equality with an arbitrary object.
350         * 
351         * @param obj  the object to test against (<code>null</code> permitted).
352         * 
353         * @return A boolean.
354         */
355        public boolean equals(Object obj) {
356            if (obj == this) {
357                return true;   
358            }
359            if (obj instanceof ChartEntity) {
360                ChartEntity that = (ChartEntity) obj;
361                if (!this.area.equals(that.area)) {
362                    return false;   
363                }
364                if (!ObjectUtilities.equal(this.toolTipText, that.toolTipText)) {
365                    return false;   
366                }
367                if (!ObjectUtilities.equal(this.urlText, that.urlText)) {
368                    return false;   
369                }
370                return true;
371            }
372            return false;
373        }
374        
375        /**
376         * Returns a clone of the entity.
377         * 
378         * @return A clone.
379         * 
380         * @throws CloneNotSupportedException if there is a problem cloning the 
381         *         entity.
382         */
383        public Object clone() throws CloneNotSupportedException {
384            return super.clone();    
385        }
386        
387        /**
388         * Provides serialization support.
389         *
390         * @param stream  the output stream.
391         *
392         * @throws IOException  if there is an I/O error.
393         */
394        private void writeObject(ObjectOutputStream stream) throws IOException {
395            stream.defaultWriteObject();
396            SerialUtilities.writeShape(this.area, stream);
397         }
398    
399        /**
400         * Provides serialization support.
401         *
402         * @param stream  the input stream.
403         *
404         * @throws IOException  if there is an I/O error.
405         * @throws ClassNotFoundException  if there is a classpath problem.
406         */
407        private void readObject(ObjectInputStream stream) 
408            throws IOException, ClassNotFoundException {
409            stream.defaultReadObject();
410            this.area = SerialUtilities.readShape(stream);
411        }
412    
413    }