001    /* ===========================================================
002     * JFreeChart : a free chart library for the Java(tm) platform
003     * ===========================================================
004     *
005     * (C) Copyright 2000-2006, 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     * LabelBlock.java
029     * ---------------
030     * (C) Copyright 2004-2006, by Object Refinery Limited.
031     *
032     * Original Author:  David Gilbert (for Object Refinery Limited);
033     * Contributor(s):   Pierre-Marie Le Biot;
034     *
035     * $Id: LabelBlock.java,v 1.8.2.4 2006/08/04 11:47:23 mungady Exp $
036     *
037     * Changes:
038     * --------
039     * 22-Oct-2004 : Version 1 (DG);
040     * 19-Apr-2005 : Added optional tooltip and URL text items,
041     *               draw() method now returns entities if 
042     *               requested (DG);
043     * 13-May-2005 : Added methods to set the font (DG);
044     * 01-Sep-2005 : Added paint management (PMLB);
045     *               Implemented equals() and clone() (PublicCloneable) (DG);
046     * ------------- JFREECHART 1.0.0 ---------------------------------------------
047     * 20-Jul-2006 : Fixed entity area in draw() method (DG);
048     * 
049     */
050    
051    package org.jfree.chart.block;
052    
053    import java.awt.Color;
054    import java.awt.Font;
055    import java.awt.Graphics2D;
056    import java.awt.Paint;
057    import java.awt.Shape;
058    import java.awt.geom.Rectangle2D;
059    
060    import org.jfree.chart.entity.ChartEntity;
061    import org.jfree.chart.entity.StandardEntityCollection;
062    import org.jfree.text.TextBlock;
063    import org.jfree.text.TextBlockAnchor;
064    import org.jfree.text.TextUtilities;
065    import org.jfree.ui.Size2D;
066    import org.jfree.util.ObjectUtilities;
067    import org.jfree.util.PaintUtilities;
068    import org.jfree.util.PublicCloneable;
069    
070    /**
071     * A block containing a label.
072     */
073    public class LabelBlock extends AbstractBlock 
074                                    implements Block, PublicCloneable {
075        
076        /** 
077         * The text for the label - retained in case the label needs 
078         * regenerating (for example, to change the font). 
079         */
080        private String text;
081        
082        /** The label. */
083        private TextBlock label;
084        
085        /** The font. */
086        private Font font;
087        
088        /** The tool tip text (can be <code>null</code>). */
089        private String toolTipText;
090        
091        /** The URL text (can be <code>null</code>). */
092        private String urlText;
093        
094        /** The default color. */
095        public static final Paint DEFAULT_PAINT = Color.black;
096    
097        /** The paint. */
098        private Paint paint;
099        
100        /**
101         * Creates a new label block.
102         * 
103         * @param label  the label (<code>null</code> not permitted).
104         */
105        public LabelBlock(String label) {
106            this(label, new Font("SansSerif", Font.PLAIN, 10), DEFAULT_PAINT);
107        }
108        
109        /**
110         * Creates a new label block.
111         * 
112         * @param text  the text for the label (<code>null</code> not permitted).
113         * @param font  the font (<code>null</code> not permitted).
114         */
115        public LabelBlock(String text, Font font) {        
116            this(text, font, DEFAULT_PAINT);
117        }
118        
119        /**
120         * Creates a new label block.
121         *
122         * @param text  the text for the label (<code>null</code> not permitted).
123         * @param font  the font (<code>null</code> not permitted).
124         * @param paint the paint (<code>null</code> not permitted).
125         */
126        public LabelBlock(String text, Font font, Paint paint) {        
127            this.text = text;
128            this.paint = paint; 
129            this.label = TextUtilities.createTextBlock(text, font, this.paint); 
130            this.font = font;
131            this.toolTipText = null;
132            this.urlText = null;
133        }
134        
135        /**
136         * Returns the font.
137         *
138         * @return The font (never <code>null</code>).
139         */
140        public Font getFont() {
141            return this.font;    
142        }
143        
144        /**
145         * Sets the font and regenerates the label.
146         *
147         * @param font  the font (<code>null</code> not permitted).
148         */
149        public void setFont(Font font) {
150            if (font == null) {
151                throw new IllegalArgumentException("Null 'font' argument.");
152            }
153            this.font = font;
154            this.label = TextUtilities.createTextBlock(this.text, font, this.paint);
155        }
156       
157        /**
158         * Returns the paint.
159         *
160         * @return The paint (never <code>null</code>).
161         */
162        public Paint getPaint() {
163            return this.paint;   
164        }
165       
166        /**
167         * Sets the paint and regenerates the label.
168         *
169         * @param paint  the paint (<code>null</code> not permitted).
170         */
171        public void setPaint(Paint paint) {
172            if (paint == null) {
173                throw new IllegalArgumentException("Null 'paint' argument.");
174            }
175            this.paint = paint;
176            this.label = TextUtilities.createTextBlock(this.text, font, this.paint);
177        }
178    
179        /**
180         * Returns the tool tip text.
181         * 
182         * @return The tool tip text (possibly <code>null</code>).
183         */
184        public String getToolTipText() {
185            return this.toolTipText;
186        }
187        
188        /**
189         * Sets the tool tip text.
190         * 
191         * @param text  the text (<code>null</code> permitted).
192         */
193        public void setToolTipText(String text) {
194            this.toolTipText = text;   
195        }
196        
197        /**
198         * Returns the URL text.
199         * 
200         * @return The URL text (possibly <code>null</code>).
201         */
202        public String getURLText() {
203            return this.urlText;
204        }
205        
206        /**
207         * Sets the URL text.
208         * 
209         * @param text  the text (<code>null</code> permitted).
210         */
211        public void setURLText(String text) {
212            this.urlText = text;   
213        }
214        
215        /**
216         * Arranges the contents of the block, within the given constraints, and 
217         * returns the block size.
218         * 
219         * @param g2  the graphics device.
220         * @param constraint  the constraint (<code>null</code> not permitted).
221         * 
222         * @return The block size (in Java2D units, never <code>null</code>).
223         */
224        public Size2D arrange(Graphics2D g2, RectangleConstraint constraint) {
225            g2.setFont(this.font);
226            Size2D s = this.label.calculateDimensions(g2);
227            return new Size2D(calculateTotalWidth(s.getWidth()), 
228                    calculateTotalHeight(s.getHeight()));
229        }
230        
231        /**
232         * Draws the block.
233         * 
234         * @param g2  the graphics device.
235         * @param area  the area.
236         */
237        public void draw(Graphics2D g2, Rectangle2D area) {
238            draw(g2, area, null);
239        }
240        
241        /**
242         * Draws the block within the specified area.
243         * 
244         * @param g2  the graphics device.
245         * @param area  the area.
246         * @param params  ignored (<code>null</code> permitted).
247         * 
248         * @return Always <code>null</code>.
249         */
250        public Object draw(Graphics2D g2, Rectangle2D area, Object params) {
251            area = trimMargin(area);
252            drawBorder(g2, area);
253            area = trimBorder(area);
254            area = trimPadding(area);
255            
256            // check if we need to collect chart entities from the container
257            EntityBlockParams ebp = null;
258            StandardEntityCollection sec = null;
259            Shape entityArea = null;
260            if (params instanceof EntityBlockParams) {
261                ebp = (EntityBlockParams) params;
262                if (ebp.getGenerateEntities()) {
263                    sec = new StandardEntityCollection();
264                    entityArea = (Shape) area.clone();
265                }
266            }
267            g2.setPaint(this.paint);
268            g2.setFont(this.font);
269            this.label.draw(g2, (float) area.getX(), (float) area.getY(), 
270                    TextBlockAnchor.TOP_LEFT);
271            BlockResult result = null;
272            if (ebp != null && sec != null) {
273                if (this.toolTipText != null || this.urlText != null) {
274                    ChartEntity entity = new ChartEntity(entityArea, 
275                            this.toolTipText, this.urlText);   
276                    sec.add(entity);
277                    result = new BlockResult();
278                    result.setEntityCollection(sec);
279                }
280            }
281            return result;
282        }
283        
284        /**
285         * Tests this <code>LabelBlock</code> for equality with an arbitrary 
286         * object.
287         * 
288         * @param obj  the object (<code>null</code> permitted).
289         * 
290         * @return A boolean.
291         */
292        public boolean equals(Object obj) {
293            if (!(obj instanceof LabelBlock)) {
294                return false;
295            }
296            LabelBlock that = (LabelBlock) obj;
297            if (!this.text.equals(that.text)) {
298                return false;
299            }
300            if (!this.font.equals(that.font)) {
301                return false;
302            }
303            if (!PaintUtilities.equal(this.paint, that.paint)) {
304                return false;
305            }
306            if (!ObjectUtilities.equal(this.toolTipText, that.toolTipText)) {
307                return false;
308            }
309            if (!ObjectUtilities.equal(this.urlText, that.urlText)) {
310                return false;
311            }
312            if (!super.equals(obj)) {
313                return false;
314            }
315            return true;
316        }
317    
318        /**
319         * Returns a clone of this <code>LabelBlock</code> instance.
320         * 
321         * @return A clone.
322         * 
323         * @throws CloneNotSupportedException if there is a problem cloning.
324         */
325        public Object clone() throws CloneNotSupportedException {
326            return super.clone();
327        }
328    }