APIdia Launch Partner
Top Description Inners Fields Constructors Methods
javax.swing.text

public Class InternationalFormatter

extends DefaultFormatter
Class Inheritance
Known Direct Subclasses
javax.swing.text.NumberFormatter, javax.swing.text.DateFormatter
Annotations
@SuppressWarnings:serial
Imports
java.awt.event.ActionEvent, java.io.*, java.text.*, .AttributedCharacterIterator.Attribute, java.util.*, javax.swing.*

InternationalFormatter extends DefaultFormatter, using an instance of java.text.Format to handle the conversion to a String, and the conversion from a String.

If getAllowsInvalid() is false, this will ask the Format to format the current text on every edit.

You can specify a minimum and maximum value by way of the setMinimum and setMaximum methods. In order for this to work the values returned from stringToValue must be comparable to the min/max values by way of the Comparable interface.

Be careful how you configure the Format and the InternationalFormatter, as it is possible to create a situation where certain values can not be input. Consider the date format 'M/d/yy', an InternationalFormatter that is always valid (setAllowsInvalid(false)), is in overwrite mode (setOverwriteMode(true)) and the date 7/1/99. In this case the user will not be able to enter a two digit month or day of month. To avoid this, the format should be 'MM/dd/yy'.

If InternationalFormatter is configured to only allow valid values (setAllowsInvalid(false)), every valid edit will result in the text of the JFormattedTextField being completely reset from the Format. The cursor position will also be adjusted as literal characters are added/removed from the resulting String.

InternationalFormatter's behavior of stringToValue is slightly different than that of DefaultTextFormatter, it does the following:

  1. parseObject is invoked on the Format specified by setFormat
  2. If a Class has been set for the values (setValueClass), supers implementation is invoked to convert the value returned from parseObject to the appropriate class.
  3. If a ParseException has not been thrown, and the value is outside the min/max a ParseException is thrown.
  4. The value is returned.
InternationalFormatter implements stringToValue in this manner so that you can specify an alternate Class than Format may return.

Warning

Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans package. Please see java.beans.XMLEncoder.

Since
1.4
See Also
java.text.Format, java.lang.Comparable

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
InternationalFormatter.ExtendedReplaceHolder

As InternationalFormatter replaces the complete text on every edit, ExtendedReplaceHolder keeps track of the offset and length passed into canReplace.

private class
InternationalFormatter.IncrementAction

IncrementAction is used to increment the value by a certain amount.

Field Summary

Modifier and TypeField and Description
private static final Format.Field[]
EMPTY_FIELD_ARRAY

Used by getFields.

private Format
format

Object used to handle the conversion.

private transient boolean
ignoreDocumentMutate

If true, DocumentFilter methods are unconditionally allowed, and no checking is done on their values.

private transient AttributedCharacterIterator
iterator

Used to iterate over characters.

private transient BitSet
literalMask

A bit is set for every index identified in the AttributedCharacterIterator that is not considered decoration.

private Comparable<?>
max

Can be used to impose a maximum value.

private Comparable<?>
min

Can be used to impose a minimum value.

private transient String
string

Current value being displayed.

private transient boolean
validMask

True if the Format was able to convert the value to a String and back.

Inherited from javax.swing.text.DefaultFormatter:
replaceHolder

Constructor Summary

AccessConstructor and Description
public
InternationalFormatter()

Creates an InternationalFormatter with no Format specified.

public
InternationalFormatter(Format
Format instance used for converting from/to Strings
format
)

Creates an InternationalFormatter with the specified Format instance.

Method Summary

Modifier and TypeMethod and Description
pack-priv Object
adjustValue(Object value, Map<?, ?> attributes, Object field, int direction)

Subclasses supporting incrementing must override this to handle the actual incrementing.

pack-priv boolean
canIncrement(Object field, int cursorPosition)

Returns true if field is non-null.

pack-priv boolean
canReplace(DefaultFormatter.ReplaceHolder rh)

Overrides javax.swing.text.DefaultFormatter.canReplace.

Overridden in an attempt to honor the literals.

public Object

Returns:

copy of the DefaultFormatter
clone
()

Overrides javax.swing.text.DefaultFormatter.clone.

Creates a copy of the DefaultFormatter.

protected Action[]
getActions()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getActions.

If getSupportsIncrement returns true, this returns two Actions suitable for incrementing/decrementing the value.

pack-priv Object
getAdjustField(int start, Map<?, ?> attributes)

Returns the field that will be adjusted by adjustValue.

pack-priv Map<AttributedCharacterIterator.Attribute, Object>
getAttributes(int index)

Returns a Set of the attribute identifiers at index.

pack-priv int
getAttributeStart(AttributedCharacterIterator.Attribute id)

Returns the start of the first run that contains the attribute id.

pack-priv char
getBufferedChar(int index)

Returns the character from the mask that has been buffered at index.

public Format.Field[]

Returns:

Format.Field constants associated with the text at the given position.
getFields
(int
offset into text to be examined
offset
)

Returns the Format.Field constants associated with the text at offset.

private int
getFieldTypeCountTo(Object f, int start)

Returns the number of occurrences of f before the location start in the current AttributedCharacterIterator.

public Format

Returns:

Format instance used for converting from/to Strings
getFormat
()

Returns the format that dictates the legal values that can be edited and displayed.

pack-priv AttributedCharacterIterator
getIterator()

Returns the AttributedCharacterIterator used to format the last value.

pack-priv char
getLiteral(int index)

Returns the literal character at index.

pack-priv int
getLiteralCountTo(int index)

Returns the number of literal characters before index.

public Comparable<?>

Returns:

Maximum legal value that can be input
getMaximum
()

Returns the maximum permissible value.

public Comparable<?>

Returns:

Minimum legal value that can be input
getMinimum
()

Returns the minimum permissible value.

private int
getNextNonliteralIndex(int index, int
Amount to increment looking for non-literal
direction
)

Returns the index of the next non-literal character starting at index.

pack-priv DefaultFormatter.ReplaceHolder
getReplaceHolder(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs)

Overrides javax.swing.text.DefaultFormatter.getReplaceHolder.

Overridden to return an instance of ExtendedReplaceHolder.

pack-priv boolean
getSupportsIncrement()

Returns false, indicating InternationalFormatter does not allow incrementing of the value.

public void
install(JFormattedTextField
JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.
ftf
)

Overrides javax.swing.text.DefaultFormatter.install.

Installs the DefaultFormatter onto a particular JFormattedTextField.

pack-priv boolean
isLiteral(int index)

Returns true if the character at index is a literal, that is not editable.

pack-priv boolean
isLiteral(Map<?, ?> attributes)

Returns true if attributes is null or empty.

pack-priv boolean
isNavigatable(int offset)

Overrides javax.swing.text.DefaultFormatter.isNavigatable.

Returns true if the character at offset is navigable too.

pack-priv boolean
isValidMask()

Returns true if the current mask is valid.

pack-priv boolean
isValidValue(Object value, boolean
If false, and a ClassCastException is thrown in comparing the values, the exception is consumed and false is returned.
wantsCCE
)

Returns true if value is between the min/max.

private void
readObject(ObjectInputStream s)

Subclassed to update the internal representation of the mask after the default read operation has completed.

pack-priv void
replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs)

Overrides javax.swing.text.DefaultFormatter.replace.

Overridden to unconditionally allow the replace if ignoreDocumentMutate is true.

pack-priv boolean
replace(DefaultFormatter.ReplaceHolder rh)

Overrides javax.swing.text.DefaultFormatter.replace.

When in !allowsInvalid mode the text is reset on every edit, thus supers implementation will position the cursor at the wrong position.

private void
repositionCursor(int startLiteralCount, int end, int direction)

Repositions the cursor.

pack-priv void
resetValue(Object value)

Resets the value of the JFormattedTextField to be value.

pack-priv void
selectField(Object f, int count)

Selects the fields identified by attributes.

public void
setFormat(Format
Format instance used for converting from/to Strings
format
)

Sets the format that dictates the legal values that can be edited and displayed.

public void
setMaximum(Comparable<?>
Maximum legal value that can be input
max
)

Sets the maximum permissible value.

public void
setMinimum(Comparable<?>
Minimum legal value that can be input
minimum
)

Sets the minimum permissible value.

public Object

Returns:

Object representation of text
stringToValue
(String
String to convert
text
)

Overrides javax.swing.text.DefaultFormatter.stringToValue.

Returns the Object representation of the String text.

pack-priv Object
stringToValue(String text, Format f)

Invokes parseObject on f, returning its value.

pack-priv void
updateMask()

Updates the AttributedCharacterIterator by invoking formatToCharacterIterator on the Format.

private void
updateMask(AttributedCharacterIterator iterator)

Updates the internal bitset from iterator.

pack-priv void
updateMaskIfNecessary()

Updates the AttributedCharacterIterator and bitset, if necessary.

pack-priv void
updateValue(Object value)

Overrides javax.swing.text.DefaultFormatter.updateValue.

Overridden to update the mask after invoking supers implementation.

public String

Returns:

String representation of value
valueToString
(Object
Value to convert
value
)

Overrides javax.swing.text.DefaultFormatter.valueToString.

Returns a String representation of the Object value.

Inherited from javax.swing.text.DefaultFormatter:
commitEditgetAllowsInvalidgetCommitsOnValidEditgetDocumentFiltergetInitialVisualPositiongetNavigationFiltergetNextCursorPositiongetNextVisualPositionFromgetOverwriteModegetReplaceStringgetValueClassisLegalInsertTextisValidEditmoveDotpositionCursorAtInitialLocationrepositionCursorsetAllowsInvalidsetCommitsOnValidEditsetDotsetOverwriteModesetValueClassupdateValue

Field Detail

EMPTY_FIELD_ARRAYback to summary
private static final Format.Field[] EMPTY_FIELD_ARRAY

Used by getFields.

formatback to summary
private Format format

Object used to handle the conversion.

ignoreDocumentMutateback to summary
private transient boolean ignoreDocumentMutate

If true, DocumentFilter methods are unconditionally allowed, and no checking is done on their values. This is used when incrementing/decrementing via the actions.

iteratorback to summary
private transient AttributedCharacterIterator iterator

Used to iterate over characters.

literalMaskback to summary
private transient BitSet literalMask

A bit is set for every index identified in the AttributedCharacterIterator that is not considered decoration. This should only be used if validMask is true.

maxback to summary
private Comparable<?> max

Can be used to impose a maximum value.

minback to summary
private Comparable<?> min

Can be used to impose a minimum value.

stringback to summary
private transient String string

Current value being displayed.

validMaskback to summary
private transient boolean validMask

True if the Format was able to convert the value to a String and back.

Constructor Detail

InternationalFormatterback to summary
public InternationalFormatter()

Creates an InternationalFormatter with no Format specified.

InternationalFormatterback to summary
public InternationalFormatter(Format format)

Creates an InternationalFormatter with the specified Format instance.

Parameters
format:Format

Format instance used for converting from/to Strings

Method Detail

adjustValueback to summary
pack-priv Object adjustValue(Object value, Map<?, ?> attributes, Object field, int direction) throws BadLocationException, ParseException

Subclasses supporting incrementing must override this to handle the actual incrementing. value is the current value, attributes gives the field the cursor is in (may be null depending upon canIncrement) and direction is the amount to increment by.

canIncrementback to summary
pack-priv boolean canIncrement(Object field, int cursorPosition)

Returns true if field is non-null. Subclasses that wish to allow incrementing to happen outside of the known fields will need to override this.

canReplaceback to summary
pack-priv boolean canReplace(DefaultFormatter.ReplaceHolder rh)

Overrides javax.swing.text.DefaultFormatter.canReplace.

Overridden in an attempt to honor the literals.

If we do not allow invalid values and are in overwrite mode, this rh.length is corrected as to preserve trailing literals. If not in overwrite mode, and there is text to insert it is inserted at the next non literal index going forward. If there is only text to remove, it is removed from the next non literal index going backward.

cloneback to summary
public Object clone() throws CloneNotSupportedException

Overrides javax.swing.text.DefaultFormatter.clone.

Creates a copy of the DefaultFormatter.

Returns:Object

copy of the DefaultFormatter

Exceptions
CloneNotSupportedException:

Doc from java.lang.Object.clone.

if the object's class does not support the Cloneable interface. Subclasses that override the clone method can also throw this exception to indicate that an instance cannot be cloned.

getActionsback to summary
protected Action[] getActions()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getActions.

If getSupportsIncrement returns true, this returns two Actions suitable for incrementing/decrementing the value.

getAdjustFieldback to summary
pack-priv Object getAdjustField(int start, Map<?, ?> attributes)

Returns the field that will be adjusted by adjustValue.

getAttributesback to summary
pack-priv Map<AttributedCharacterIterator.Attribute, Object> getAttributes(int index)

Returns a Set of the attribute identifiers at index.

getAttributeStartback to summary
pack-priv int getAttributeStart(AttributedCharacterIterator.Attribute id)

Returns the start of the first run that contains the attribute id. This will return -1 if the attribute can not be found.

getBufferedCharback to summary
pack-priv char getBufferedChar(int index)

Returns the character from the mask that has been buffered at index.

getFieldsback to summary
public Format.Field[] getFields(int offset)

Returns the Format.Field constants associated with the text at offset. If offset is not a valid location into the current text, this will return an empty array.

Parameters
offset:int

offset into text to be examined

Returns:Format.Field[]

Format.Field constants associated with the text at the given position.

getFieldTypeCountToback to summary
private int getFieldTypeCountTo(Object f, int start)

Returns the number of occurrences of f before the location start in the current AttributedCharacterIterator.

getFormatback to summary
public Format getFormat()

Returns the format that dictates the legal values that can be edited and displayed.

Returns:Format

Format instance used for converting from/to Strings

getIteratorback to summary
pack-priv AttributedCharacterIterator getIterator()

Returns the AttributedCharacterIterator used to format the last value.

getLiteralback to summary
pack-priv char getLiteral(int index)

Returns the literal character at index.

getLiteralCountToback to summary
pack-priv int getLiteralCountTo(int index)

Returns the number of literal characters before index.

getMaximumback to summary
public Comparable<?> getMaximum()

Returns the maximum permissible value.

Returns:Comparable<?>

Maximum legal value that can be input

getMinimumback to summary
public Comparable<?> getMinimum()

Returns the minimum permissible value.

Returns:Comparable<?>

Minimum legal value that can be input

getNextNonliteralIndexback to summary
private int getNextNonliteralIndex(int index, int direction)

Returns the index of the next non-literal character starting at index. If index is not a literal, it will be returned.

Parameters
direction:int

Amount to increment looking for non-literal

getReplaceHolderback to summary
pack-priv DefaultFormatter.ReplaceHolder getReplaceHolder(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs)

Overrides javax.swing.text.DefaultFormatter.getReplaceHolder.

Overridden to return an instance of ExtendedReplaceHolder.

getSupportsIncrementback to summary
pack-priv boolean getSupportsIncrement()

Returns false, indicating InternationalFormatter does not allow incrementing of the value. Subclasses that wish to support incrementing/decrementing the value should override this and return true. Subclasses should also override adjustValue.

installback to summary
public void install(JFormattedTextField ftf)

Overrides javax.swing.text.DefaultFormatter.install.

Installs the DefaultFormatter onto a particular JFormattedTextField. This will invoke valueToString to convert the current value from the JFormattedTextField to a String. This will then install the Actions from getActions, the DocumentFilter returned from getDocumentFilter and the NavigationFilter returned from getNavigationFilter onto the JFormattedTextField.

Subclasses will typically only need to override this if they wish to install additional listeners on the JFormattedTextField.

If there is a ParseException in converting the current value to a String, this will set the text to an empty String, and mark the JFormattedTextField as being in an invalid state.

While this is a public method, this is typically only useful for subclassers of JFormattedTextField. JFormattedTextField will invoke this method at the appropriate times when the value changes, or its internal state changes.

Parameters
ftf:JFormattedTextField

JFormattedTextField to format for, may be null indicating uninstall from current JFormattedTextField.

isLiteralback to summary
pack-priv boolean isLiteral(int index)

Returns true if the character at index is a literal, that is not editable.

isLiteralback to summary
pack-priv boolean isLiteral(Map<?, ?> attributes)

Returns true if attributes is null or empty.

isNavigatableback to summary
pack-priv boolean isNavigatable(int offset)

Overrides javax.swing.text.DefaultFormatter.isNavigatable.

Returns true if the character at offset is navigable too. This is implemented in terms of isLiteral, subclasses may wish to provide different behavior.

isValidMaskback to summary
pack-priv boolean isValidMask()

Returns true if the current mask is valid.

isValidValueback to summary
pack-priv boolean isValidValue(Object value, boolean wantsCCE)

Returns true if value is between the min/max.

Parameters
wantsCCE:boolean

If false, and a ClassCastException is thrown in comparing the values, the exception is consumed and false is returned.

readObjectback to summary
private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException

Subclassed to update the internal representation of the mask after the default read operation has completed.

Annotations
@Serial
replaceback to summary
pack-priv void replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs) throws BadLocationException

Overrides javax.swing.text.DefaultFormatter.replace.

Overridden to unconditionally allow the replace if ignoreDocumentMutate is true.

replaceback to summary
pack-priv boolean replace(DefaultFormatter.ReplaceHolder rh) throws BadLocationException

Overrides javax.swing.text.DefaultFormatter.replace.

When in !allowsInvalid mode the text is reset on every edit, thus supers implementation will position the cursor at the wrong position. As such, this invokes supers implementation and then invokes repositionCursor to correctly reset the cursor.

repositionCursorback to summary
private void repositionCursor(int startLiteralCount, int end, int direction)

Repositions the cursor. startLiteralCount gives the number of literals to the start of the deleted range, end gives the ending location to adjust from, direction gives the direction relative to end to position the cursor from.

resetValueback to summary
pack-priv void resetValue(Object value) throws BadLocationException, ParseException

Resets the value of the JFormattedTextField to be value.

selectFieldback to summary
pack-priv void selectField(Object f, int count)

Selects the fields identified by attributes.

setFormatback to summary
public void setFormat(Format format)

Sets the format that dictates the legal values that can be edited and displayed.

Parameters
format:Format

Format instance used for converting from/to Strings

setMaximumback to summary
public void setMaximum(Comparable<?> max)

Sets the maximum permissible value. If the valueClass has not been specified, and max is non null, the valueClass will be set to that of the class of max.

Parameters
max:Comparable<?>

Maximum legal value that can be input

See Also
setValueClass
setMinimumback to summary
public void setMinimum(Comparable<?> minimum)

Sets the minimum permissible value. If the valueClass has not been specified, and minimum is non null, the valueClass will be set to that of the class of minimum.

Parameters
minimum:Comparable<?>

Minimum legal value that can be input

See Also
setValueClass
stringToValueback to summary
public Object stringToValue(String text) throws ParseException

Overrides javax.swing.text.DefaultFormatter.stringToValue.

Returns the Object representation of the String text.

Parameters
text:String

String to convert

Returns:Object

Object representation of text

Exceptions
ParseException:
if there is an error in the conversion
stringToValueback to summary
pack-priv Object stringToValue(String text, Format f) throws ParseException

Invokes parseObject on f, returning its value.

updateMaskback to summary
pack-priv void updateMask()

Updates the AttributedCharacterIterator by invoking formatToCharacterIterator on the Format. If this is successful, updateMask(AttributedCharacterIterator) is then invoked to update the internal bitmask.

updateMaskback to summary
private void updateMask(AttributedCharacterIterator iterator)

Updates the internal bitset from iterator. This will set validMask to true if iterator is non-null.

updateMaskIfNecessaryback to summary
pack-priv void updateMaskIfNecessary()

Updates the AttributedCharacterIterator and bitset, if necessary.

updateValueback to summary
pack-priv void updateValue(Object value)

Overrides javax.swing.text.DefaultFormatter.updateValue.

Overridden to update the mask after invoking supers implementation.

valueToStringback to summary
public String valueToString(Object value) throws ParseException

Overrides javax.swing.text.DefaultFormatter.valueToString.

Returns a String representation of the Object value. This invokes format on the current Format.

Parameters
value:Object

Value to convert

Returns:String

String representation of value

Exceptions
ParseException:
if there is an error in the conversion
javax.swing.text back to summary

pack-priv Class InternationalFormatter.ExtendedReplaceHolder

extends ReplaceHolder
Class Inheritance

As InternationalFormatter replaces the complete text on every edit, ExtendedReplaceHolder keeps track of the offset and length passed into canReplace.

Field Summary

Modifier and TypeField and Description
pack-priv int
endOffset

Offset of the insert/remove.

pack-priv int
endTextLength

Length of the text.

Inherited from javax.swing.text.DefaultFormatter.ReplaceHolder:
attrscursorPositionfblengthoffsettextvalue

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
pack-priv void
resetFromValue(InternationalFormatter formatter)

Resets the region to delete to be the complete document and the text from invoking valueToString on the current value.

Inherited from javax.swing.text.DefaultFormatter.ReplaceHolder:
reset

Field Detail

endOffsetback to summary
pack-priv int endOffset

Offset of the insert/remove. This may differ from offset in that if !allowsInvalid the text is replaced on every edit.

endTextLengthback to summary
pack-priv int endTextLength

Length of the text. This may differ from text.length in that if !allowsInvalid the text is replaced on every edit.

Constructor Detail

ExtendedReplaceHolderback to summary
pack-priv ExtendedReplaceHolder()

Method Detail

resetFromValueback to summary
pack-priv void resetFromValue(InternationalFormatter formatter)

Resets the region to delete to be the complete document and the text from invoking valueToString on the current value.

javax.swing.text back to summary

private Class InternationalFormatter.IncrementAction

extends AbstractAction
Class Inheritance

IncrementAction is used to increment the value by a certain amount. It calls into adjustValue to handle the actual incrementing of the value.

Field Summary

Modifier and TypeField and Description
private int
Inherited from javax.swing.AbstractAction:
changeSupportenabled

Constructor Summary

AccessConstructor and Description
pack-priv
IncrementAction(String name, int direction)

Method Summary

Modifier and TypeMethod and Description
public void
actionPerformed(ActionEvent ae)

Implements java.awt.event.ActionListener.actionPerformed.

Invoked when an action occurs.

Inherited from javax.swing.AbstractAction:
addPropertyChangeListenerclonefirePropertyChangegetKeysgetPropertyChangeListenersgetValueisEnabledputValueremovePropertyChangeListenersetEnabled

Field Detail

directionback to summary
private int direction

Constructor Detail

IncrementActionback to summary
pack-priv IncrementAction(String name, int direction)

Method Detail

actionPerformedback to summary
public void actionPerformed(ActionEvent ae)

Implements java.awt.event.ActionListener.actionPerformed.

Doc from java.awt.event.ActionListener.actionPerformed.

Invoked when an action occurs.