KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > info > monitorenter > gui > chart > ILabelFormatter


1 /*
2  *
3  * ILabelFormatter.java jchart2d
4  * Copyright (C) Achim Westermann, created on 20.04.2005, 09:45:59
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19  *
20  * If you modify or optimize the code in a useful way please let me know.
21  * Achim.Westermann@gmx.de
22  *
23  */
24 package info.monitorenter.gui.chart;
25
26 import info.monitorenter.util.units.AUnit;
27
28 /**
29  * <p>
30  * An interface used by Axis to format labels and determine the maximum width
31  * for the labels.
32  * </p>
33  * <p>
34  * In order to get as much labels as possible on the Chart2D's axes, an Axis
35  * should be configured in a way that reduces the return value of the method
36  * {@link #getMaxAmountChars()}.
37  * </p>
38  *
39  * @see info.monitorenter.gui.chart.AAxis
40  *
41  * @author <a HREF="mailto:Achim.Westermann@gmx.de">Achim Westermann </a>
42  *
43  * @version $Revision: 1.3 $
44  */
45 public interface ILabelFormatter {
46
47   /**
48    * <p>
49    * Provide a String for the value. Subclasses should override the label
50    * formatting here. The raw value is passed here to allow a general treatment.
51    * Transformations of this raw value should be done here (e.g. division by
52    * multiples of 1000 for scientific unit system display, date formatting,...).
53    * </p>
54    *
55    * @param value
56    * the value to format.
57    *
58    * @return the formatted value.
59    */
60   public String JavaDoc format(double value);
61
62   /**
63    * Returns the maximum amount of characters that will be returned from
64    * {@link #format(double)}.
65    * <p>
66    *
67    * @return the maximum amount of characters that will be returned from
68    * {@link #format(double)}.
69    *
70    */
71   public int getMaxAmountChars();
72
73   /**
74    * <p>
75    * Returns the minimum change in the value to format that will cause to return
76    * a different formatted String.
77    * </p>
78    * <p>
79    * To achieve two different formatted Strings to be returned from the format
80    * method the corresponding values given to the format method have to differ
81    * at least by this value.
82    * </p>
83    * <p>
84    * Some implementations (e.g. a formatter for date) have to use their own
85    * format method an increas a value to determine when the first change will
86    * occur. This is expensive and it's recommended that this action is performed
87    * once only and the result is stored. Additionally this routine has to start
88    * with an "even" (see {@link #getNextEvenValue(double, boolean)}) value to
89    * get a correct result (the distance from even number to even number).
90    * </p>
91    *
92    * @return the minimum change in the value to format that will cause to return
93    * a different formatted String.
94    */
95   double getMinimumValueShiftForChange();
96
97   /**
98    * <p>
99    * Returns the next "even" value to the given one. "Even" means that the
100    * format method will exactly return the String for the value and not cut or
101    * round any information. A label String created with an "even" number will be
102    * exactly at the position it describes.
103    * </p>
104    *
105    * @param value
106    * the value to get the next "even" value for.
107    * @param ceiling
108    * if true, the next higher number will returned, else the next lower
109    * one.
110    * @return the next "even" value to the given one.
111    *
112    */
113   double getNextEvenValue(double value, boolean ceiling);
114
115   /**
116    * Returns the unit that is currently used by this formatter.
117    * <p>
118    *
119    * @return the unit that is currently used by this formatter.
120    */
121   public AUnit getUnit();
122
123   /**
124    * Callback method invoked by the corresponding {@link AAxis} upon start of a
125    * paint iteration of the {@link Chart2D}.
126    * <p>
127    *
128    */
129   public void initPaintIteration();
130
131   /**
132    * <p>
133    * The reverse operation to <code>{@link #format(double)}</code>.
134    * </p>
135    * <p>
136    * The given argument has to be in the format that will be generated by that
137    * method or exceptions may be thrown. <br>
138    * <code>test.parse(test.format(d))== d </code><br>
139    * has to be true if no rounding occurs by the formatter.
140    * <p>
141    *
142    * @param formatted
143    * a <code>String</code> in the format that will be produced by
144    * method <code>{@link #format(double)}</code>.
145    *
146    * @return the parsed number.
147    *
148    * @throws NumberFormatException
149    * if the format of the argument is invalid.
150    *
151    */
152   public Number JavaDoc parse(String JavaDoc formatted) throws NumberFormatException JavaDoc;
153
154   /**
155    * Allows the {@link AAxis} to register itself with the given formatter so
156    * that it may get information about the data (e.g. range) it has to format.
157    * <p>
158    *
159    * This method should only be invoked by {@link AAxis}, all other invocations
160    * will cause trouble.
161    * <p>
162    *
163    * @param axis
164    * the axis to gain information about.
165    */
166   public void setAxis(IAxis axis);
167
168 }
169
Popular Tags