001/* ===========================================================
002 * JFreeChart : a free chart library for the Java(tm) platform
003 * ===========================================================
004 *
005 * (C) Copyright 2000-2013, 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 * [Oracle and Java are registered trademarks of Oracle and/or its affiliates. 
025 * Other names may be trademarks of their respective owners.]
026 *
027 * --------------------------------
028 * StandardXYZToolTipGenerator.java
029 * --------------------------------
030 * (C) Copyright 2004-2013, by Object Refinery Limited.
031 *
032 * Original Author:  David Gilbert (for Object Refinery Limited);
033 * Contributor(s):   -;
034 *
035 * Changes
036 * -------
037 * 11-May-2003 : Version 1, split from StandardXYZItemLabelGenerator (DG);
038 * 15-Jul-2004 : Switched getZ() and getZValue() methods (DG);
039 * 03-Jul-2013 : Use ParamChecks (DG);
040 *
041 */
042
043package org.jfree.chart.labels;
044
045import java.io.Serializable;
046import java.text.DateFormat;
047import java.text.MessageFormat;
048import java.text.NumberFormat;
049import org.jfree.chart.util.ParamChecks;
050
051import org.jfree.data.xy.XYDataset;
052import org.jfree.data.xy.XYZDataset;
053import org.jfree.util.ObjectUtilities;
054
055/**
056 * A standard item label generator for use with {@link XYZDataset} data.  Each
057 * value can be formatted as a number or as a date.
058 */
059public class StandardXYZToolTipGenerator extends StandardXYToolTipGenerator
060        implements XYZToolTipGenerator, Serializable {
061
062    /** For serialization. */
063    private static final long serialVersionUID = -2961577421889473503L;
064
065    /** The default tooltip format. */
066    public static final String DEFAULT_TOOL_TIP_FORMAT = "{0}: ({1}, {2}, {3})";
067
068    /**
069     * A number formatter for the z value - if this is null, then zDateFormat
070     * must be non-null.
071     */
072    private NumberFormat zFormat;
073
074    /**
075     * A date formatter for the z-value - if this is null, then zFormat must be
076     * non-null.
077     */
078    private DateFormat zDateFormat;
079
080    /**
081     * Creates a new tool tip generator using default number formatters for the
082     * x, y and z-values.
083     */
084    public StandardXYZToolTipGenerator() {
085        this(
086            DEFAULT_TOOL_TIP_FORMAT,
087            NumberFormat.getNumberInstance(),
088            NumberFormat.getNumberInstance(),
089            NumberFormat.getNumberInstance()
090        );
091    }
092
093    /**
094     * Constructs a new tool tip generator using the specified number
095     * formatters.
096     *
097     * @param formatString  the format string.
098     * @param xFormat  the format object for the x values (<code>null</code>
099     *                 not permitted).
100     * @param yFormat  the format object for the y values (<code>null</code>
101     *                 not permitted).
102     * @param zFormat  the format object for the z values (<code>null</code>
103     *                 not permitted).
104     */
105    public StandardXYZToolTipGenerator(String formatString, 
106            NumberFormat xFormat, NumberFormat yFormat, NumberFormat zFormat) {
107        super(formatString, xFormat, yFormat);
108        ParamChecks.nullNotPermitted(zFormat, "zFormat");
109        this.zFormat = zFormat;
110    }
111
112    /**
113     * Constructs a new tool tip generator using the specified date formatters.
114     *
115     * @param formatString  the format string.
116     * @param xFormat  the format object for the x values (<code>null</code>
117     *                 not permitted).
118     * @param yFormat  the format object for the y values (<code>null</code>
119     *                 not permitted).
120     * @param zFormat  the format object for the z values (<code>null</code>
121     *                 not permitted).
122     */
123    public StandardXYZToolTipGenerator(String formatString, DateFormat xFormat,
124            DateFormat yFormat, DateFormat zFormat) {
125        super(formatString, xFormat, yFormat);
126        ParamChecks.nullNotPermitted(zFormat, "zFormat");
127        this.zDateFormat = zFormat;
128    }
129
130    // TODO:  add constructors for combinations of number and date formatters.
131
132    /**
133     * Returns the number formatter for the z-values.
134     *
135     * @return The number formatter (possibly <code>null</code>).
136     */
137    public NumberFormat getZFormat() {
138        return this.zFormat;
139    }
140
141    /**
142     * Returns the date formatter for the z-values.
143     *
144     * @return The date formatter (possibly <code>null</code>).
145     */
146    public DateFormat getZDateFormat() {
147        return this.zDateFormat;
148    }
149
150    /**
151     * Generates a tool tip text item for a particular item within a series.
152     *
153     * @param dataset  the dataset (<code>null</code> not permitted).
154     * @param series  the series index (zero-based).
155     * @param item  the item index (zero-based).
156     *
157     * @return The tooltip text (possibly <code>null</code>).
158     */
159    @Override
160    public String generateToolTip(XYZDataset dataset, int series, int item) {
161        return generateLabelString(dataset, series, item);
162    }
163
164    /**
165     * Generates a label string for an item in the dataset.
166     *
167     * @param dataset  the dataset (<code>null</code> not permitted).
168     * @param series  the series (zero-based index).
169     * @param item  the item (zero-based index).
170     *
171     * @return The label (possibly <code>null</code>).
172     */
173    @Override
174    public String generateLabelString(XYDataset dataset, int series, int item) {
175        String result;
176        Object[] items = createItemArray((XYZDataset) dataset, series, item);
177        result = MessageFormat.format(getFormatString(), items);
178        return result;
179    }
180
181    /**
182     * Creates the array of items that can be passed to the
183     * {@link MessageFormat} class for creating labels.
184     *
185     * @param dataset  the dataset (<code>null</code> not permitted).
186     * @param series  the series (zero-based index).
187     * @param item  the item (zero-based index).
188     *
189     * @return The items (never <code>null</code>).
190     */
191    protected Object[] createItemArray(XYZDataset dataset,
192                                       int series, int item) {
193
194        Object[] result = new Object[4];
195        result[0] = dataset.getSeriesKey(series).toString();
196
197        Number x = dataset.getX(series, item);
198        DateFormat xf = getXDateFormat();
199        if (xf != null) {
200            result[1] = xf.format(x);
201        }
202        else {
203            result[1] = getXFormat().format(x);
204        }
205
206        Number y = dataset.getY(series, item);
207        DateFormat yf = getYDateFormat();
208        if (yf != null) {
209            result[2] = yf.format(y);
210        }
211        else {
212            result[2] = getYFormat().format(y);
213        }
214
215        Number z = dataset.getZ(series, item);
216        if (this.zDateFormat != null) {
217            result[3] = this.zDateFormat.format(z);
218        }
219        else {
220            result[3] = this.zFormat.format(z);
221        }
222
223        return result;
224
225    }
226
227    /**
228     * Tests this object for equality with an arbitrary object.
229     *
230     * @param obj  the other object (<code>null</code> permitted).
231     *
232     * @return A boolean.
233     */
234    @Override
235    public boolean equals(Object obj) {
236        if (obj == this) {
237            return true;
238        }
239        if (!(obj instanceof StandardXYZToolTipGenerator)) {
240            return false;
241        }
242        if (!super.equals(obj)) {
243            return false;
244        }
245        StandardXYZToolTipGenerator that = (StandardXYZToolTipGenerator) obj;
246        if (!ObjectUtilities.equal(this.zFormat, that.zFormat)) {
247            return false;
248        }
249        if (!ObjectUtilities.equal(this.zDateFormat, that.zDateFormat)) {
250            return false;
251        }
252        return true;
253
254    }
255
256}