001 /* InternationalFormatter.java -- 002 Copyright (C) 2005, 2006 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package javax.swing.text; 039 040 import java.text.AttributedCharacterIterator; 041 import java.text.Format; 042 import java.text.ParseException; 043 import java.util.Iterator; 044 import java.util.Map; 045 import java.util.Set; 046 047 import javax.swing.Action; 048 import javax.swing.JFormattedTextField; 049 050 /** 051 * This extends {@link DefaultFormatter} so that the value to string 052 * conversion is done via a {@link Format} object. This allows 053 * various additional formats to be handled by JFormattedField. 054 * 055 * @author Roman Kennke (roman@kennke.org) 056 */ 057 public class InternationalFormatter 058 extends DefaultFormatter 059 { 060 /** The serialization UID (compatible with JDK1.5). */ 061 private static final long serialVersionUID = 2436068675711756856L; 062 063 /** The format that handles value to string conversion. */ 064 Format format; 065 066 /** The minimal permissable value. */ 067 Comparable minimum; 068 069 /** The maximal permissable value. */ 070 Comparable maximum; 071 072 /** 073 * Creates a new InternationalFormatter with no Format specified. 074 */ 075 public InternationalFormatter() 076 { 077 super(); 078 minimum = null; 079 maximum = null; 080 format = null; 081 setCommitsOnValidEdit(false); 082 setOverwriteMode(false); 083 } 084 085 /** 086 * Creates a new InternationalFormatter that uses the specified 087 * Format object for value to string conversion. 088 * 089 * @param format the Format object to use for value to string conversion 090 */ 091 public InternationalFormatter(Format format) 092 { 093 this(); 094 setFormat(format); 095 } 096 097 /** 098 * Sets the Format object that is used to convert values to strings. 099 * 100 * @param format the Format to use for value to string conversion 101 * 102 * @see Format 103 */ 104 public void setFormat(Format format) 105 { 106 this.format = format; 107 } 108 109 /** 110 * Returns the currently used Format object that is used to format 111 * the JFormattedField. 112 * 113 * @return the current Format 114 */ 115 public Format getFormat() 116 { 117 return format; 118 } 119 120 /** 121 * Sets the minimum value that is allowed by this Formatter. The minimum 122 * value is given as an object that implements the {@link Comparable} 123 * interface. 124 * 125 * If <code>minValue</code> is null, then the Formatter has no restrictions 126 * at the lower end. 127 * 128 * If value class is not yet specified and <code>minValue</code> is not 129 * null, then <code>valueClass</code> is set to the class of the minimum 130 * value. 131 * 132 * @param minValue the minimum permissable value 133 * 134 * @see Comparable 135 */ 136 public void setMinimum(Comparable minValue) 137 { 138 minimum = minValue; 139 if (valueClass == null && minValue != null) 140 valueClass = minValue.getClass(); 141 } 142 143 /** 144 * Returns the minimal value that is allowed by this Formatter. 145 * 146 * A <code>null</code> value means that there is no restriction. 147 * 148 * @return the minimal value that is allowed by this Formatter or 149 * <code>null</code> if there is no restriction 150 */ 151 public Comparable getMinimum() 152 { 153 return minimum; 154 } 155 156 /** 157 * Sets the maximum value that is allowed by this Formatter. The maximum 158 * value is given as an object that implements the {@link Comparable} 159 * interface. 160 * 161 * If <code>maxValue</code> is null, then the Formatter has no restrictions 162 * at the upper end. 163 * 164 * If value class is not yet specified and <code>maxValue</code> is not 165 * null, then <code>valueClass</code> is set to the class of the maximum 166 * value. 167 * 168 * @param maxValue the maximum permissable value 169 * 170 * @see Comparable 171 */ 172 public void setMaximum(Comparable maxValue) 173 { 174 maximum = maxValue; 175 if (valueClass == null && maxValue != null) 176 valueClass = maxValue.getClass(); 177 } 178 179 /** 180 * Returns the maximal value that is allowed by this Formatter. 181 * 182 * A <code>null</code> value means that there is no restriction. 183 * 184 * @return the maximal value that is allowed by this Formatter or 185 * <code>null</code> if there is no restriction 186 */ 187 public Comparable getMaximum() 188 { 189 return maximum; 190 } 191 192 /** 193 * Installs the formatter on the specified {@link JFormattedTextField}. 194 * 195 * This method does the following things: 196 * <ul> 197 * <li>Display the value of #valueToString in the 198 * <code>JFormattedTextField</code></li> 199 * <li>Install the Actions from #getActions on the <code>JTextField</code> 200 * </li> 201 * <li>Install the DocumentFilter returned by #getDocumentFilter</li> 202 * <li>Install the NavigationFilter returned by #getNavigationFilter</li> 203 * </ul> 204 * 205 * This method is typically not overridden by subclasses. Instead override 206 * one of the mentioned methods in order to customize behaviour. 207 * 208 * @param ftf the {@link JFormattedTextField} in which this formatter 209 * is installed 210 */ 211 public void install(JFormattedTextField ftf) 212 { 213 super.install(ftf); 214 } 215 216 /** 217 * Converts a value object into a String. This is done by invoking 218 * {@link Format#format(Object)} on the specified <code>Format</code> object. 219 * If no format is set, then {@link DefaultFormatter#valueToString(Object)} 220 * is called as a fallback. 221 * 222 * @param value the value to be converted 223 * 224 * @return the string representation of the value 225 * 226 * @throws ParseException if the value cannot be converted 227 */ 228 public String valueToString(Object value) 229 throws ParseException 230 { 231 if (value == null) 232 return ""; 233 if (format != null) 234 return format.format(value); 235 else 236 return super.valueToString(value); 237 } 238 239 /** 240 * Converts a String (from the JFormattedTextField input) to a value. 241 * This is achieved by invoking {@link Format#parseObject(String)} on 242 * the specified <code>Format</code> object. 243 * 244 * This implementation differs slightly from {@link DefaultFormatter}, 245 * it does: 246 * <ol> 247 * <li>Convert the string to an <code>Object</code> using the 248 * <code>Formatter</code>.</li> 249 * <li>If a <code>valueClass</code> has been set, this object is passed to 250 * {@link DefaultFormatter#stringToValue(String)} so that the value 251 * has the correct type. This may or may not work correctly, depending on 252 * the implementation of toString() in the value class and if the class 253 * implements a constructor that takes one String as argument.</li> 254 * <li>If no {@link ParseException} has been thrown so far, we check if the 255 * value exceeds either <code>minimum</code> or <code>maximum</code> if 256 * one of those has been specified and throw a <code>ParseException</code> 257 * if it does.</li> 258 * <li>Return the value.</li> 259 * </ol> 260 * 261 * If no format has been specified, then 262 * {@link DefaultFormatter#stringToValue(String)} is invoked as fallback. 263 * 264 * @param string the string to convert 265 * 266 * @return the value for the string 267 * 268 * @throws ParseException if the string cannot be converted into 269 * a value object (e.g. invalid input) 270 */ 271 public Object stringToValue(String string) 272 throws ParseException 273 { 274 if (format != null) 275 { 276 Object o = format.parseObject(string); 277 278 // If a value class has been set, call super in order to get 279 // the class right. That is what the JDK API docs suggest, so we do 280 // it that way. 281 if (valueClass != null) 282 o = super.stringToValue(o.toString()); 283 284 // Check for minimum and maximum bounds 285 if (minimum != null && minimum.compareTo(o) > 0) 286 throw new ParseException("The value may not be less than the" 287 + " specified minimum", 0); 288 if (maximum != null && maximum.compareTo(o) < 0) 289 throw new ParseException("The value may not be greater than the" 290 + " specified maximum", 0); 291 return o; 292 } 293 else 294 return super.stringToValue(string); 295 } 296 297 /** 298 * Returns the {@link Format.Field} constants that are associated with 299 * the specified position in the text. 300 * 301 * If <code>offset</code> is not a valid location in the input field, 302 * an empty array of fields is returned. 303 * 304 * @param offset the position in the text from which we want to fetch 305 * the fields constants 306 * 307 * @return the field values associated with the specified position in 308 * the text 309 */ 310 public Format.Field[] getFields(int offset) 311 { 312 // TODO: don't know if this is correct 313 AttributedCharacterIterator aci = format.formatToCharacterIterator 314 (getFormattedTextField().getValue()); 315 aci.setIndex(offset); 316 Map atts = aci.getAttributes(); 317 Set keys = atts.keySet(); 318 Format.Field[] fields = new Format.Field[keys.size()]; 319 int index = 0; 320 for (Iterator i = keys.iterator(); i.hasNext(); index++) 321 fields[index] = (Format.Field) i.next(); 322 return fields; 323 } 324 325 /** 326 * This creates and returns a clone of this Formatter. 327 * 328 * @return a clone of this formatter 329 * 330 * @throws CloneNotSupportedException not thrown here, since cloning is 331 * supported 332 */ 333 public Object clone() 334 throws CloneNotSupportedException 335 { 336 // TODO: it has to be considered, if we should return a deep or shallow 337 // clone here. for now we return a shallow clone 338 Object clone = super.clone(); 339 return clone; 340 } 341 342 /** 343 * Returns the Actions that are supported by this Formatter. 344 * 345 * @specnote the JDK API docs say here: <cite>If 346 * <code>getSupportsIncrement</code> returns true, this returns two 347 * Actions suitable for incrementing/decrementing the value.</cite> 348 * The questsion is, which method <code>getSupportsIncrement</code>? 349 * There is no such method in the whole API! So we just call 350 * super.getActions here. 351 */ 352 protected Action[] getActions() 353 { 354 return super.getActions(); 355 } 356 }