    001    /* ===========================================================
    002     * JFreeChart : a free chart library for the Java(tm) platform
    003     * ===========================================================
    004     *
    005     * (C) Copyright 2000-2008, 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     * Marker.java
    029     * -----------
    030     * (C) Copyright 2002-2008, by Object Refinery Limited.
    031     *
    032     * Original Author:  David Gilbert (for Object Refinery Limited);
    033     * Contributor(s):   Nicolas Brodu;
    034     *
    035     * Changes
    036     * -------
    037     * 02-Jul-2002 : Added extra constructor, standard header and Javadoc
    038     *               comments (DG);
    039     * 20-Aug-2002 : Added the outline stroke attribute (DG);
    040     * 02-Oct-2002 : Fixed errors reported by Checkstyle (DG);
    041     * 16-Oct-2002 : Added new constructor (DG);
    042     * 26-Mar-2003 : Implemented Serializable (DG);
    043     * 21-May-2003 : Added labels (DG);
    044     * 11-Sep-2003 : Implemented Cloneable (NB);
    045     * 05-Nov-2003 : Added checks to ensure some attributes are never null (DG);
    046     * 11-Feb-2003 : Moved to org.jfree.chart.plot package, plus significant API
    047     *               changes to support IntervalMarker in plots (DG);
    048     * 14-Jun-2004 : Updated equals() method (DG);
    049     * 21-Jan-2005 : Added settings to control direction of horizontal and
    050     *               vertical label offsets (DG);
    051     * 01-Jun-2005 : Modified to use only one label offset type - this will be
    052     *               applied to the domain or range axis as appropriate (DG);
    053     * 06-Jun-2005 : Fix equals() method to handle GradientPaint (DG);
    054     * 19-Aug-2005 : Changed constructor from public --> protected (DG);
    055     * ------------- JFREECHART 1.0.x ---------------------------------------------
    056     * 05-Sep-2006 : Added MarkerChangeListener support (DG);
    057     * 26-Sep-2007 : Fix for serialization bug 1802195 (DG);
    058     *
    059     */
    060
    061    package org.jfree.chart.plot;
    062
    063    import java.awt.BasicStroke;
    064    import java.awt.Color;
    065    import java.awt.Font;
    066    import java.awt.Paint;
    067    import java.awt.Stroke;
    068    import java.io.IOException;
    069    import java.io.ObjectInputStream;
    070    import java.io.ObjectOutputStream;
    071    import java.io.Serializable;
    072    import java.util.EventListener;
    073
    074    import javax.swing.event.EventListenerList;
    075
    076    import org.jfree.chart.event.MarkerChangeEvent;
    077    import org.jfree.chart.event.MarkerChangeListener;
    078    import org.jfree.io.SerialUtilities;
    079    import org.jfree.ui.LengthAdjustmentType;
    080    import org.jfree.ui.RectangleAnchor;
    081    import org.jfree.ui.RectangleInsets;
    082    import org.jfree.ui.TextAnchor;
    083    import org.jfree.util.ObjectUtilities;
    084    import org.jfree.util.PaintUtilities;
    085
    086    /**
    087     * The base class for markers that can be added to plots to highlight a value
    088     * or range of values.
    089     * <br><br>
    090     * An event notification mechanism was added to this class in JFreeChart
    091     * version 1.0.3.
    092     */
    093    public abstract class Marker implements Cloneable, Serializable {
    094
    095        /** For serialization. */
    096        private static final long serialVersionUID = -734389651405327166L;
    097
    098        /** The paint (null is not allowed). */
    099        private transient Paint paint;
    100
    101        /** The stroke (null is not allowed). */
    102        private transient Stroke stroke;
    103
    104        /** The outline paint. */
    105        private transient Paint outlinePaint;
    106
    107        /** The outline stroke. */
    108        private transient Stroke outlineStroke;
    109
    110        /** The alpha transparency. */
    111        private float alpha;
    112
    113        /** The label. */
    114        private String label = null;
    115
    116        /** The label font. */
    117        private Font labelFont;
    118
    119        /** The label paint. */
    120        private transient Paint labelPaint;
    121
    122        /** The label position. */
    123        private RectangleAnchor labelAnchor;
    124
    125        /** The text anchor for the label. */
    126        private TextAnchor labelTextAnchor;
    127
    128        /** The label offset from the marker rectangle. */
    129        private RectangleInsets labelOffset;
    130
    131        /**
    132         * The offset type for the domain or range axis (never <code>null</code>).
    133         */
    134        private LengthAdjustmentType labelOffsetType;
    135
    136        /** Storage for registered change listeners. */
    137        private transient EventListenerList listenerList;
    138
    139        /**
    140         * Creates a new marker with default attributes.
    141         */
    142        protected Marker() {
    143            this(Color.gray);
    144        }
    145
    146        /**
    147         * Constructs a new marker.
    148         *
    149         * @param paint  the paint (<code>null</code> not permitted).
    150         */
    151        protected Marker(Paint paint) {
    152            this(paint, new BasicStroke(0.5f), Color.gray, new BasicStroke(0.5f),
    153                    0.80f);
    154        }
    155
    156        /**
    157         * Constructs a new marker.
    158         *
    159         * @param paint  the paint (<code>null</code> not permitted).
    160         * @param stroke  the stroke (<code>null</code> not permitted).
    161         * @param outlinePaint  the outline paint (<code>null</code> permitted).
    162         * @param outlineStroke  the outline stroke (<code>null</code> permitted).
    163         * @param alpha  the alpha transparency (must be in the range 0.0f to
    164         *     1.0f).
    165         *
    166         * @throws IllegalArgumentException if <code>paint</code> or
    167         *     <code>stroke</code> is <code>null</code>, or <code>alpha</code> is
    168         *     not in the specified range.
    169         */
    170        protected Marker(Paint paint, Stroke stroke,
    171                         Paint outlinePaint, Stroke outlineStroke,
    172                         float alpha) {
    173
    174            if (paint == null) {
    175                throw new IllegalArgumentException("Null 'paint' argument.");
    176            }
    177            if (stroke == null) {
    178                throw new IllegalArgumentException("Null 'stroke' argument.");
    179            }
    180            if (alpha < 0.0f || alpha > 1.0f)
    181                throw new IllegalArgumentException(
    182                        "The 'alpha' value must be in the range 0.0f to 1.0f");
    183
    184            this.paint = paint;
    185            this.stroke = stroke;
    186            this.outlinePaint = outlinePaint;
    187            this.outlineStroke = outlineStroke;
    188            this.alpha = alpha;
    189
    190            this.labelFont = new Font("SansSerif", Font.PLAIN, 9);
    191            this.labelPaint = Color.black;
    192            this.labelAnchor = RectangleAnchor.TOP_LEFT;
    193            this.labelOffset = new RectangleInsets(3.0, 3.0, 3.0, 3.0);
    194            this.labelOffsetType = LengthAdjustmentType.CONTRACT;
    195            this.labelTextAnchor = TextAnchor.CENTER;
    196
    197            this.listenerList = new EventListenerList();
    198        }
    199
    200        /**
    201         * Returns the paint.
    202         *
    203         * @return The paint (never <code>null</code>).
    204         *
    205         * @see #setPaint(Paint)
    206         */
    207        public Paint getPaint() {
    208            return this.paint;
    209        }
    210
    211        /**
    212         * Sets the paint and sends a {@link MarkerChangeEvent} to all registered
    213         * listeners.
    214         *
    215         * @param paint  the paint (<code>null</code> not permitted).
    216         *
    217         * @see #getPaint()
    218         */
    219        public void setPaint(Paint paint) {
    220            if (paint == null) {
    221                throw new IllegalArgumentException("Null 'paint' argument.");
    222            }
    223            this.paint = paint;
    224            notifyListeners(new MarkerChangeEvent(this));
    225        }
    226
    227        /**
    228         * Returns the stroke.
    229         *
    230         * @return The stroke (never <code>null</code>).
    231         *
    232         * @see #setStroke(Stroke)
    233         */
    234        public Stroke getStroke() {
    235            return this.stroke;
    236        }
    237
    238        /**
    239         * Sets the stroke and sends a {@link MarkerChangeEvent} to all registered
    240         * listeners.
    241         *
    242         * @param stroke  the stroke (<code>null</code> not permitted).
    243         *
    244         * @see #getStroke()
    245         */
    246        public void setStroke(Stroke stroke) {
    247            if (stroke == null) {
    248                throw new IllegalArgumentException("Null 'stroke' argument.");
    249            }
    250            this.stroke = stroke;
    251            notifyListeners(new MarkerChangeEvent(this));
    252        }
    253
    254        /**
    255         * Returns the outline paint.
    256         *
    257         * @return The outline paint (possibly <code>null</code>).
    258         *
    259         * @see #setOutlinePaint(Paint)
    260         */
    261        public Paint getOutlinePaint() {
    262            return this.outlinePaint;
    263        }
    264
    265        /**
    266         * Sets the outline paint and sends a {@link MarkerChangeEvent} to all
    267         * registered listeners.
    268         *
    269         * @param paint  the paint (<code>null</code> permitted).
    270         *
    271         * @see #getOutlinePaint()
    272         */
    273        public void setOutlinePaint(Paint paint) {
    274            this.outlinePaint = paint;
    275            notifyListeners(new MarkerChangeEvent(this));
    276        }
    277
    278        /**
    279         * Returns the outline stroke.
    280         *
    281         * @return The outline stroke (possibly <code>null</code>).
    282         *
    283         * @see #setOutlineStroke(Stroke)
    284         */
    285        public Stroke getOutlineStroke() {
    286            return this.outlineStroke;
    287        }
    288
    289        /**
    290         * Sets the outline stroke and sends a {@link MarkerChangeEvent} to all
    291         * registered listeners.
    292         *
    293         * @param stroke  the stroke (<code>null</code> permitted).
    294         *
    295         * @see #getOutlineStroke()
    296         */
    297        public void setOutlineStroke(Stroke stroke) {
    298            this.outlineStroke = stroke;
    299            notifyListeners(new MarkerChangeEvent(this));
    300        }
    301
    302        /**
    303         * Returns the alpha transparency.
    304         *
    305         * @return The alpha transparency.
    306         *
    307         * @see #setAlpha(float)
    308         */
    309        public float getAlpha() {
    310            return this.alpha;
    311        }
    312
    313        /**
    314         * Sets the alpha transparency that should be used when drawing the
    315         * marker, and sends a {@link MarkerChangeEvent} to all registered
    316         * listeners.  The alpha transparency is a value in the range 0.0f
    317         * (completely transparent) to 1.0f (completely opaque).
    318         *
    319         * @param alpha  the alpha transparency (must be in the range 0.0f to
    320         *     1.0f).
    321         *
    322         * @throws IllegalArgumentException if <code>alpha</code> is not in the
    323         *     specified range.
    324         *
    325         * @see #getAlpha()
    326         */
    327        public void setAlpha(float alpha) {
    328            if (alpha < 0.0f || alpha > 1.0f)
    329                throw new IllegalArgumentException(
    330                        "The 'alpha' value must be in the range 0.0f to 1.0f");
    331            this.alpha = alpha;
    332            notifyListeners(new MarkerChangeEvent(this));
    333        }
    334
    335        /**
    336         * Returns the label (if <code>null</code> no label is displayed).
    337         *
    338         * @return The label (possibly <code>null</code>).
    339         *
    340         * @see #setLabel(String)
    341         */
    342        public String getLabel() {
    343            return this.label;
    344        }
    345
    346        /**
    347         * Sets the label (if <code>null</code> no label is displayed) and sends a
    348         * {@link MarkerChangeEvent} to all registered listeners.
    349         *
    350         * @param label  the label (<code>null</code> permitted).
    351         *
    352         * @see #getLabel()
    353         */
    354        public void setLabel(String label) {
    355            this.label = label;
    356            notifyListeners(new MarkerChangeEvent(this));
    357        }
    358
    359        /**
    360         * Returns the label font.
    361         *
    362         * @return The label font (never <code>null</code>).
    363         *
    364         * @see #setLabelFont(Font)
    365         */
    366        public Font getLabelFont() {
    367            return this.labelFont;
    368        }
    369
    370        /**
    371         * Sets the label font and sends a {@link MarkerChangeEvent} to all
    372         * registered listeners.
    373         *
    374         * @param font  the font (<code>null</code> not permitted).
    375         *
    376         * @see #getLabelFont()
    377         */
    378        public void setLabelFont(Font font) {
    379            if (font == null) {
    380                throw new IllegalArgumentException("Null 'font' argument.");
    381            }
    382            this.labelFont = font;
    383            notifyListeners(new MarkerChangeEvent(this));
    384        }
    385
    386        /**
    387         * Returns the label paint.
    388         *
    389         * @return The label paint (never </code>null</code>).
    390         *
    391         * @see #setLabelPaint(Paint)
    392         */
    393        public Paint getLabelPaint() {
    394            return this.labelPaint;
    395        }
    396
    397        /**
    398         * Sets the label paint and sends a {@link MarkerChangeEvent} to all
    399         * registered listeners.
    400         *
    401         * @param paint  the paint (<code>null</code> not permitted).
    402         *
    403         * @see #getLabelPaint()
    404         */
    405        public void setLabelPaint(Paint paint) {
    406            if (paint == null) {
    407                throw new IllegalArgumentException("Null 'paint' argument.");
    408            }
    409            this.labelPaint = paint;
    410            notifyListeners(new MarkerChangeEvent(this));
    411        }
    412
    413        /**
    414         * Returns the label anchor.  This defines the position of the label
    415         * anchor, relative to the bounds of the marker.
    416         *
    417         * @return The label anchor (never <code>null</code>).
    418         *
    419         * @see #setLabelAnchor(RectangleAnchor)
    420         */
    421        public RectangleAnchor getLabelAnchor() {
    422            return this.labelAnchor;
    423        }
    424
    425        /**
    426         * Sets the label anchor and sends a {@link MarkerChangeEvent} to all
    427         * registered listeners.  The anchor defines the position of the label
    428         * anchor, relative to the bounds of the marker.
    429         *
    430         * @param anchor  the anchor (<code>null</code> not permitted).
    431         *
    432         * @see #getLabelAnchor()
    433         */
    434        public void setLabelAnchor(RectangleAnchor anchor) {
    435            if (anchor == null) {
    436                throw new IllegalArgumentException("Null 'anchor' argument.");
    437            }
    438            this.labelAnchor = anchor;
    439            notifyListeners(new MarkerChangeEvent(this));
    440        }
    441
    442        /**
    443         * Returns the label offset.
    444         *
    445         * @return The label offset (never <code>null</code>).
    446         *
    447         * @see #setLabelOffset(RectangleInsets)
    448         */
    449        public RectangleInsets getLabelOffset() {
    450            return this.labelOffset;
    451        }
    452
    453        /**
    454         * Sets the label offset and sends a {@link MarkerChangeEvent} to all
    455         * registered listeners.
    456         *
    457         * @param offset  the label offset (<code>null</code> not permitted).
    458         *
    459         * @see #getLabelOffset()
    460         */
    461        public void setLabelOffset(RectangleInsets offset) {
    462            if (offset == null) {
    463                throw new IllegalArgumentException("Null 'offset' argument.");
    464            }
    465            this.labelOffset = offset;
    466            notifyListeners(new MarkerChangeEvent(this));
    467        }
    468
    469        /**
    470         * Returns the label offset type.
    471         *
    472         * @return The type (never <code>null</code>).
    473         *
    474         * @see #setLabelOffsetType(LengthAdjustmentType)
    475         */
    476        public LengthAdjustmentType getLabelOffsetType() {
    477            return this.labelOffsetType;
    478        }
    479
    480        /**
    481         * Sets the label offset type and sends a {@link MarkerChangeEvent} to all
    482         * registered listeners.
    483         *
    484         * @param adj  the type (<code>null</code> not permitted).
    485         *
    486         * @see #getLabelOffsetType()
    487         */
    488        public void setLabelOffsetType(LengthAdjustmentType adj) {
    489            if (adj == null) {
    490                throw new IllegalArgumentException("Null 'adj' argument.");
    491            }
    492            this.labelOffsetType = adj;
    493            notifyListeners(new MarkerChangeEvent(this));
    494        }
    495
    496        /**
    497         * Returns the label text anchor.
    498         *
    499         * @return The label text anchor (never <code>null</code>).
    500         *
    501         * @see #setLabelTextAnchor(TextAnchor)
    502         */
    503        public TextAnchor getLabelTextAnchor() {
    504            return this.labelTextAnchor;
    505        }
    506
    507        /**
    508         * Sets the label text anchor and sends a {@link MarkerChangeEvent} to
    509         * all registered listeners.
    510         *
    511         * @param anchor  the label text anchor (<code>null</code> not permitted).
    512         *
    513         * @see #getLabelTextAnchor()
    514         */
    515        public void setLabelTextAnchor(TextAnchor anchor) {
    516            if (anchor == null) {
    517                throw new IllegalArgumentException("Null 'anchor' argument.");
    518            }
    519            this.labelTextAnchor = anchor;
    520            notifyListeners(new MarkerChangeEvent(this));
    521        }
    522
    523        /**
    524         * Registers an object for notification of changes to the marker.
    525         *
    526         * @param listener  the object to be registered.
    527         *
    528         * @see #removeChangeListener(MarkerChangeListener)
    529         *
    530         * @since 1.0.3
    531         */
    532        public void addChangeListener(MarkerChangeListener listener) {
    533            this.listenerList.add(MarkerChangeListener.class, listener);
    534        }
    535
    536        /**
    537         * Unregisters an object for notification of changes to the marker.
    538         *
    539         * @param listener  the object to be unregistered.
    540         *
    541         * @see #addChangeListener(MarkerChangeListener)
    542         *
    543         * @since 1.0.3
    544         */
    545        public void removeChangeListener(MarkerChangeListener listener) {
    546            this.listenerList.remove(MarkerChangeListener.class, listener);
    547        }
    548
    549        /**
    550         * Notifies all registered listeners that the marker has been modified.
    551         *
    552         * @param event  information about the change event.
    553         *
    554         * @since 1.0.3
    555         */
    556        public void notifyListeners(MarkerChangeEvent event) {
    557
    558            Object[] listeners = this.listenerList.getListenerList();
    559            for (int i = listeners.length - 2; i >= 0; i -= 2) {
    560                if (listeners[i] == MarkerChangeListener.class) {
    561                    ((MarkerChangeListener) listeners[i + 1]).markerChanged(event);
    562                }
    563            }
    564
    565        }
    566
    567        /**
    568         * Returns an array containing all the listeners of the specified type.
    569         *
    570         * @param listenerType  the listener type.
    571         *
    572         * @return The array of listeners.
    573         *
    574         * @since 1.0.3
    575         */
    576        public EventListener[] getListeners(Class listenerType) {
    577            return this.listenerList.getListeners(listenerType);
    578        }
    579
    580        /**
    581         * Tests the marker for equality with an arbitrary object.
    582         *
    583         * @param obj  the object (<code>null</code> permitted).
    584         *
    585         * @return A boolean.
    586         */
    587        public boolean equals(Object obj) {
    588            if (obj == this) {
    589                return true;
    590            }
    591            if (!(obj instanceof Marker)) {
    592                return false;
    593            }
    594            Marker that = (Marker) obj;
    595            if (!PaintUtilities.equal(this.paint, that.paint)) {
    596                return false;
    597            }
    598            if (!ObjectUtilities.equal(this.stroke, that.stroke)) {
    599                return false;
    600            }
    601            if (!PaintUtilities.equal(this.outlinePaint, that.outlinePaint)) {
    602                return false;
    603            }
    604            if (!ObjectUtilities.equal(this.outlineStroke, that.outlineStroke)) {
    605                return false;
    606            }
    607            if (this.alpha != that.alpha) {
    608                return false;
    609            }
    610            if (!ObjectUtilities.equal(this.label, that.label)) {
    611                return false;
    612            }
    613            if (!ObjectUtilities.equal(this.labelFont, that.labelFont)) {
    614                return false;
    615            }
    616            if (!PaintUtilities.equal(this.labelPaint, that.labelPaint)) {
    617                return false;
    618            }
    619            if (this.labelAnchor != that.labelAnchor) {
    620                return false;
    621            }
    622            if (this.labelTextAnchor != that.labelTextAnchor) {
    623                return false;
    624            }
    625            if (!ObjectUtilities.equal(this.labelOffset, that.labelOffset)) {
    626                return false;
    627            }
    628            if (!this.labelOffsetType.equals(that.labelOffsetType)) {
    629                return false;
    630            }
    631            return true;
    632        }
    633
    634        /**
    635         * Creates a clone of the marker.
    636         *
    637         * @return A clone.
    638         *
    639         * @throws CloneNotSupportedException never.
    640         */
    641        public Object clone() throws CloneNotSupportedException {
    642            return super.clone();
    643        }
    644
    645        /**
    646         * Provides serialization support.
    647         *
    648         * @param stream  the output stream.
    649         *
    650         * @throws IOException  if there is an I/O error.
    651         */
    652        private void writeObject(ObjectOutputStream stream) throws IOException {
    653            stream.defaultWriteObject();
    654            SerialUtilities.writePaint(this.paint, stream);
    655            SerialUtilities.writeStroke(this.stroke, stream);
    656            SerialUtilities.writePaint(this.outlinePaint, stream);
    657            SerialUtilities.writeStroke(this.outlineStroke, stream);
    658            SerialUtilities.writePaint(this.labelPaint, stream);
    659        }
    660
    661        /**
    662         * Provides serialization support.
    663         *
    664         * @param stream  the input stream.
    665         *
    666         * @throws IOException  if there is an I/O error.
    667         * @throws ClassNotFoundException  if there is a classpath problem.
    668         */
    669        private void readObject(ObjectInputStream stream)
    670            throws IOException, ClassNotFoundException {
    671            stream.defaultReadObject();
    672            this.paint = SerialUtilities.readPaint(stream);
    673            this.stroke = SerialUtilities.readStroke(stream);
    674            this.outlinePaint = SerialUtilities.readPaint(stream);
    675            this.outlineStroke = SerialUtilities.readStroke(stream);
    676            this.labelPaint = SerialUtilities.readPaint(stream);
    677            this.listenerList = new EventListenerList();
    678        }
    679
    680    }