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

public Class DefaultFormatter

extends AbstractFormatter
implements Cloneable, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Cloneable
Known Direct Subclasses
javax.swing.text.InternationalFormatter, javax.swing.text.MaskFormatter
Annotations
@SuppressWarnings:serial
Imports
sun.swing.SwingUtilities2, java.io.Serializable, java.lang.reflect.*, java.text.ParseException, javax.swing.*

DefaultFormatter formats arbitrary objects. Formatting is done by invoking the toString method. In order to convert the value back to a String, your class must provide a constructor that takes a String argument. If no single argument constructor that takes a String is found, the returned value will be the String passed into stringToValue.

Instances of DefaultFormatter can not be used in multiple instances of JFormattedTextField. To obtain a copy of an already configured DefaultFormatter, use the clone method.

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
javax.swing.JFormattedTextField.AbstractFormatter

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
DefaultFormatter.DefaultDocumentFilter

DocumentFilter implementation that calls back to the replace method of DefaultFormatter.

private class
DefaultFormatter.DefaultNavigationFilter

NavigationFilter implementation that calls back to methods with same name in DefaultFormatter.

pack-priv static class
DefaultFormatter.ReplaceHolder

ReplaceHolder is used to track where insert/remove/replace is going to happen.

Field Summary

Modifier and TypeField and Description
private boolean
allowsInvalid

Indicates if the value being edited must match the mask.

private boolean
commitOnEdit

If true, any time a valid edit happens commitEdit is invoked.

private DocumentFilter
documentFilter

DocumentFilter that forwards calls back to DefaultFormatter.

private boolean
overwriteMode

If true, overwrite mode is enabled.

pack-priv transient DefaultFormatter.ReplaceHolder
replaceHolder

Used during replace to track the region to replace.

private Class<?>
valueClass

Class used to create new instances.

Constructor Summary

AccessConstructor and Description
public
DefaultFormatter()

Creates a DefaultFormatter.

Method Summary

Modifier and TypeMethod and Description
pack-priv boolean
canReplace(DefaultFormatter.ReplaceHolder rh)

Returns true if the edit described by rh will result in a legal value.

public Object

Returns:

copy of the DefaultFormatter
clone
()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.clone.

Creates a copy of the DefaultFormatter.

pack-priv void
commitEdit()

Invokes commitEdit on the JFormattedTextField.

public boolean

Returns:

false if the edited value must always be valid
getAllowsInvalid
()

Returns whether or not the value being edited is allowed to be invalid for a length of time.

public boolean

Returns:

true if edits are committed after every valid edit
getCommitsOnValidEdit
()

Returns when edits are published back to the JFormattedTextField.

protected DocumentFilter

Returns:

DocumentFilter to restrict edits
getDocumentFilter
()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getDocumentFilter.

Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.

pack-priv int
getInitialVisualPosition()

Returns the initial location to position the cursor at.

protected NavigationFilter

Returns:

NavigationFilter to restrict navigation
getNavigationFilter
()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getNavigationFilter.

Returns the NavigationFilter used to restrict where the cursor can be placed.

pack-priv int
getNextCursorPosition(int offset, int direction)

Returns the next cursor position from offset by incrementing direction.

private int
getNextNavigatableChar(int offset, int direction)

Returns the next editable character starting at offset incrementing the offset by direction.

pack-priv int
getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet)

Finds the next navigable character.

public boolean

Returns:

true if newly inserted characters overwrite existing characters
getOverwriteMode
()

Returns the behavior when inserting characters.

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

Returns the ReplaceHolder to track the replace of the specified text.

pack-priv String
getReplaceString(int offset, int deleteLength, String replaceString)

A convenience methods to return the result of deleting deleteLength characters at offset and inserting replaceString at offset in the current text field.

public Class<?>

Returns:

Class used to construct return value from stringToValue
getValueClass
()

Returns that class that is used to create new Objects.

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

Overrides javax.swing.JFormattedTextField.AbstractFormatter.install.

Installs the DefaultFormatter onto a particular JFormattedTextField.

pack-priv boolean
isLegalInsertText(String text)

Returns true if the text in text can be inserted.

pack-priv boolean
isNavigatable(int offset)

Subclasses should override this if they want cursor navigation to skip certain characters.

pack-priv boolean
pack-priv void
moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

NavigationFilter method, subclasses that wish finer control should override this.

pack-priv void
positionCursorAtInitialLocation()

Positions the cursor at the initial location.

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

DocumentFilter method, funnels into replace.

pack-priv boolean
replace(DefaultFormatter.ReplaceHolder rh)

If the edit described by rh is legal, this will return true, commit the edit (if necessary) and update the cursor position.

pack-priv void
repositionCursor(int offset, int direction)

Resets the cursor by using getNextCursorPosition.

public void
setAllowsInvalid(boolean
Used to indicate if the edited value must always be valid
allowsInvalid
)

Sets whether or not the value being edited is allowed to be invalid for a length of time (that is, stringToValue throws a ParseException).

public void
setCommitsOnValidEdit(boolean
Used to indicate when edits are committed back to the JTextComponent
commit
)

Sets when edits are published back to the JFormattedTextField.

pack-priv void
setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

NavigationFilter method, subclasses that wish finer control should override this.

public void
setOverwriteMode(boolean
Indicates if overwrite mode is used
overwriteMode
)

Configures the behavior when inserting characters.

public void
setValueClass(Class<?>
Class used to construct return value from stringToValue
valueClass
)

Sets that class that is used to create new Objects.

public Object

Returns:

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

Implements abstract javax.swing.JFormattedTextField.AbstractFormatter.stringToValue.

Converts the passed in String into an instance of getValueClass by way of the constructor that takes a String argument.

pack-priv void
updateValue()

Pushes the value to the JFormattedTextField if the current value is valid and invokes setEditValid based on the validity of the value.

pack-priv void
updateValue(Object value)

Pushes the value to the editor if we are to commit on edits.

public String

Returns:

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

Implements abstract javax.swing.JFormattedTextField.AbstractFormatter.valueToString.

Converts the passed in Object into a String by way of the toString method.

Inherited from javax.swing.JFormattedTextField.AbstractFormatter:
getActionsgetFormattedTextFieldinvalidEditsetEditValiduninstall

Field Detail

allowsInvalidback to summary
private boolean allowsInvalid

Indicates if the value being edited must match the mask.

commitOnEditback to summary
private boolean commitOnEdit

If true, any time a valid edit happens commitEdit is invoked.

documentFilterback to summary
private DocumentFilter documentFilter

DocumentFilter that forwards calls back to DefaultFormatter.

overwriteModeback to summary
private boolean overwriteMode

If true, overwrite mode is enabled.

replaceHolderback to summary
pack-priv transient DefaultFormatter.ReplaceHolder replaceHolder

Used during replace to track the region to replace.

valueClassback to summary
private Class<?> valueClass

Class used to create new instances.

Constructor Detail

DefaultFormatterback to summary
public DefaultFormatter()

Creates a DefaultFormatter.

Method Detail

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

Returns true if the edit described by rh will result in a legal value.

cloneback to summary
public Object clone() throws CloneNotSupportedException

Overrides javax.swing.JFormattedTextField.AbstractFormatter.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.

commitEditback to summary
pack-priv void commitEdit() throws ParseException

Invokes commitEdit on the JFormattedTextField.

getAllowsInvalidback to summary
public boolean getAllowsInvalid()

Returns whether or not the value being edited is allowed to be invalid for a length of time.

Returns:boolean

false if the edited value must always be valid

getCommitsOnValidEditback to summary
public boolean getCommitsOnValidEdit()

Returns when edits are published back to the JFormattedTextField.

Returns:boolean

true if edits are committed after every valid edit

getDocumentFilterback to summary
protected DocumentFilter getDocumentFilter()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getDocumentFilter.

Returns the DocumentFilter used to restrict the characters that can be input into the JFormattedTextField.

Returns:DocumentFilter

DocumentFilter to restrict edits

getInitialVisualPositionback to summary
pack-priv int getInitialVisualPosition()

Returns the initial location to position the cursor at. This forwards the call to getNextNavigatableChar.

getNavigationFilterback to summary
protected NavigationFilter getNavigationFilter()

Overrides javax.swing.JFormattedTextField.AbstractFormatter.getNavigationFilter.

Returns the NavigationFilter used to restrict where the cursor can be placed.

Returns:NavigationFilter

NavigationFilter to restrict navigation

getNextCursorPositionback to summary
pack-priv int getNextCursorPosition(int offset, int direction)

Returns the next cursor position from offset by incrementing direction. This uses getNextNavigatableChar as well as constraining the location to the max position.

getNextNavigatableCharback to summary
private int getNextNavigatableChar(int offset, int direction)

Returns the next editable character starting at offset incrementing the offset by direction.

getNextVisualPositionFromback to summary
pack-priv int getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) throws BadLocationException

Finds the next navigable character.

getOverwriteModeback to summary
public boolean getOverwriteMode()

Returns the behavior when inserting characters.

Returns:boolean

true if newly inserted characters overwrite existing characters

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

Returns the ReplaceHolder to track the replace of the specified text.

getReplaceStringback to summary
pack-priv String getReplaceString(int offset, int deleteLength, String replaceString)

A convenience methods to return the result of deleting deleteLength characters at offset and inserting replaceString at offset in the current text field.

getValueClassback to summary
public Class<?> getValueClass()

Returns that class that is used to create new Objects.

Returns:Class<?>

Class used to construct return value from stringToValue

installback to summary
public void install(JFormattedTextField ftf)

Overrides javax.swing.JFormattedTextField.AbstractFormatter.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.

isLegalInsertTextback to summary
pack-priv boolean isLegalInsertText(String text)

Returns true if the text in text can be inserted. This does not mean the text will ultimately be inserted, it is used if text can trivially reject certain characters.

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

Subclasses should override this if they want cursor navigation to skip certain characters. A return value of false indicates the character at offset should be skipped when navigating through the field.

isValidEditback to summary
pack-priv boolean isValidEdit(DefaultFormatter.ReplaceHolder rh)
moveDotback to summary
pack-priv void moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

NavigationFilter method, subclasses that wish finer control should override this.

positionCursorAtInitialLocationback to summary
pack-priv void positionCursorAtInitialLocation()

Positions the cursor at the initial location.

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

DocumentFilter method, funnels into replace.

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

If the edit described by rh is legal, this will return true, commit the edit (if necessary) and update the cursor position. This forwards to canReplace and isLegalInsertText as necessary to determine if the edit is in fact legal.

All of the DocumentFilter methods funnel into here, you should generally only have to override this.

repositionCursorback to summary
pack-priv void repositionCursor(int offset, int direction)

Resets the cursor by using getNextCursorPosition.

setAllowsInvalidback to summary
public void setAllowsInvalid(boolean allowsInvalid)

Sets whether or not the value being edited is allowed to be invalid for a length of time (that is, stringToValue throws a ParseException). It is often convenient to allow the user to temporarily input an invalid value.

Parameters
allowsInvalid:boolean

Used to indicate if the edited value must always be valid

setCommitsOnValidEditback to summary
public void setCommitsOnValidEdit(boolean commit)

Sets when edits are published back to the JFormattedTextField. If true, commitEdit is invoked after every valid edit (any time the text is edited). On the other hand, if this is false than the DefaultFormatter does not publish edits back to the JFormattedTextField. As such, the only time the value of the JFormattedTextField will change is when commitEdit is invoked on JFormattedTextField, typically when enter is pressed or focus leaves the JFormattedTextField.

Parameters
commit:boolean

Used to indicate when edits are committed back to the JTextComponent

setDotback to summary
pack-priv void setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

NavigationFilter method, subclasses that wish finer control should override this.

setOverwriteModeback to summary
public void setOverwriteMode(boolean overwriteMode)

Configures the behavior when inserting characters. If overwriteMode is true (the default), new characters overwrite existing characters in the model.

Parameters
overwriteMode:boolean

Indicates if overwrite mode is used

setValueClassback to summary
public void setValueClass(Class<?> valueClass)

Sets that class that is used to create new Objects. If the passed in class does not have a single argument constructor that takes a String, String values will be used.

Parameters
valueClass:Class<?>

Class used to construct return value from stringToValue

stringToValueback to summary
public Object stringToValue(String string) throws ParseException

Implements abstract javax.swing.JFormattedTextField.AbstractFormatter.stringToValue.

Converts the passed in String into an instance of getValueClass by way of the constructor that takes a String argument. If getValueClass returns null, the Class of the current value in the JFormattedTextField will be used. If this is null, a String will be returned. If the constructor throws an exception, a ParseException will be thrown. If there is no single argument String constructor, string will be returned.

Parameters
string:String

String to convert

Returns:Object

Object representation of text

Exceptions
ParseException:
if there is an error in the conversion
updateValueback to summary
pack-priv void updateValue()

Pushes the value to the JFormattedTextField if the current value is valid and invokes setEditValid based on the validity of the value.

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

Pushes the value to the editor if we are to commit on edits. If value is null, the current value will be obtained from the text component.

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

Implements abstract javax.swing.JFormattedTextField.AbstractFormatter.valueToString.

Converts the passed in Object into a String by way of the toString method.

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

private Class DefaultFormatter.DefaultDocumentFilter

extends DocumentFilter
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable

DocumentFilter implementation that calls back to the replace method of DefaultFormatter.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public void
insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr)

Overrides javax.swing.text.DocumentFilter.insertString.

Invoked prior to insertion of text into the specified Document.

public void
remove(DocumentFilter.FilterBypass fb, int offset, int length)

Overrides javax.swing.text.DocumentFilter.remove.

Invoked prior to removal of the specified region in the specified Document.

public void
replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attr)

Overrides javax.swing.text.DocumentFilter.replace.

Invoked prior to replacing a region of text in the specified Document.

Constructor Detail

DefaultDocumentFilterback to summary
private DefaultDocumentFilter()

Method Detail

insertStringback to summary
public void insertString(DocumentFilter.FilterBypass fb, int offset, String string, AttributeSet attr) throws BadLocationException

Overrides javax.swing.text.DocumentFilter.insertString.

Doc from javax.swing.text.DocumentFilter.insertString.

Invoked prior to insertion of text into the specified Document. Subclasses that want to conditionally allow insertion should override this and only call supers implementation as necessary, or call directly into the FilterBypass.

Exceptions
BadLocationException:
the given insert position is not a valid position within the document
removeback to summary
public void remove(DocumentFilter.FilterBypass fb, int offset, int length) throws BadLocationException

Overrides javax.swing.text.DocumentFilter.remove.

Doc from javax.swing.text.DocumentFilter.remove.

Invoked prior to removal of the specified region in the specified Document. Subclasses that want to conditionally allow removal should override this and only call supers implementation as necessary, or call directly into the FilterBypass as necessary.

Exceptions
BadLocationException:
some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.
replaceback to summary
public void replace(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attr) throws BadLocationException

Overrides javax.swing.text.DocumentFilter.replace.

Doc from javax.swing.text.DocumentFilter.replace.

Invoked prior to replacing a region of text in the specified Document. Subclasses that want to conditionally allow replace should override this and only call supers implementation as necessary, or call directly into the FilterBypass.

Exceptions
BadLocationException:
the given insert position is not a valid position within the document
javax.swing.text back to summary

private Class DefaultFormatter.DefaultNavigationFilter

extends NavigationFilter
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable

NavigationFilter implementation that calls back to methods with same name in DefaultFormatter.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
public int
getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet)

Overrides javax.swing.text.NavigationFilter.getNextVisualPositionFrom.

Returns the next visual position to place the caret at from an existing position.

public void
moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

Overrides javax.swing.text.NavigationFilter.moveDot.

Invoked prior to the Caret moving the dot.

public void
setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

Overrides javax.swing.text.NavigationFilter.setDot.

Invoked prior to the Caret setting the dot.

Constructor Detail

DefaultNavigationFilterback to summary
private DefaultNavigationFilter()

Method Detail

getNextVisualPositionFromback to summary
public int getNextVisualPositionFrom(JTextComponent text, int pos, Position.Bias bias, int direction, Position.Bias[] biasRet) throws BadLocationException

Overrides javax.swing.text.NavigationFilter.getNextVisualPositionFrom.

Doc from javax.swing.text.NavigationFilter.getNextVisualPositionFrom.

Returns the next visual position to place the caret at from an existing position. The default implementation simply forwards the method to the root View. Subclasses may wish to further restrict the location based on additional criteria.

Exceptions
BadLocationException:
for a bad location within a document model
moveDotback to summary
public void moveDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

Overrides javax.swing.text.NavigationFilter.moveDot.

Doc from javax.swing.text.NavigationFilter.moveDot.

Invoked prior to the Caret moving the dot. The default implementation calls directly into the FilterBypass with the passed in arguments. Subclasses may wish to conditionally call super with a different location, or invoke the necessary methods on the FilterBypass.

setDotback to summary
public void setDot(NavigationFilter.FilterBypass fb, int dot, Position.Bias bias)

Overrides javax.swing.text.NavigationFilter.setDot.

Doc from javax.swing.text.NavigationFilter.setDot.

Invoked prior to the Caret setting the dot. The default implementation calls directly into the FilterBypass with the passed in arguments. Subclasses may wish to conditionally call super with a different location, or invoke the necessary method on the FilterBypass

javax.swing.text back to summary

pack-priv Class DefaultFormatter.ReplaceHolder

extends Object
Class Inheritance
Known Direct Subclasses
javax.swing.text.InternationalFormatter.ExtendedReplaceHolder

ReplaceHolder is used to track where insert/remove/replace is going to happen.

Field Summary

Modifier and TypeField and Description
pack-priv AttributeSet
attrs

AttributeSet to attach to text, may be null.

pack-priv int
cursorPosition

Position the cursor should be adjusted from.

pack-priv DocumentFilter.FilterBypass
fb

The FilterBypass that was passed to the DocumentFilter method.

pack-priv int
length

Length of text to remove.

pack-priv int
offset

Offset where the remove/insert is going to occur.

pack-priv String
text

The text to insert, may be null.

pack-priv Object
value

The resulting value, this may never be set.

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
pack-priv void
reset(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

attrsback to summary
pack-priv AttributeSet attrs

AttributeSet to attach to text, may be null.

cursorPositionback to summary
pack-priv int cursorPosition

Position the cursor should be adjusted from. If this is -1 the cursor position will be adjusted based on the direction of the replace (-1: offset, 1: offset + text.length()), otherwise the cursor position is adjusted from this position.

fbback to summary
pack-priv DocumentFilter.FilterBypass fb

The FilterBypass that was passed to the DocumentFilter method.

lengthback to summary
pack-priv int length

Length of text to remove.

offsetback to summary
pack-priv int offset

Offset where the remove/insert is going to occur.

textback to summary
pack-priv String text

The text to insert, may be null.

valueback to summary
pack-priv Object value

The resulting value, this may never be set.

Constructor Detail

ReplaceHolderback to summary
pack-priv ReplaceHolder()

Method Detail

resetback to summary
pack-priv void reset(DocumentFilter.FilterBypass fb, int offset, int length, String text, AttributeSet attrs)