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