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