java.lang.Object java.awt.Component java.awt.Container javax.swing.JComponent javax.swing.text.JTextComponent javax.swing.JTextField javax.swing.JFormattedTextField
public class JFormattedTextField
JFormattedTextField extends JTextField adding support for formatting arbitrary values, as well as retrieving a particular object once the user has edited the text. The following illustrates configuring a JFormattedTextField to edit dates:
JFormattedTextField ftf = new JFormattedTextField(); ftf.setValue(new Date());
Once a JFormattedTextField has been created, you can listen for editing changes by way of adding a PropertyChangeListener and listening for PropertyChangeEvents with the property name value.
JFormattedTextField allows configuring what action should be taken when focus is lost. The possible configurations are:
Value |
Description |
---|---|
JFormattedTextField.REVERT | Revert the display to match that of getValue, possibly losing the current edit. |
JFormattedTextField.COMMIT | Commits the current value. If the value being edited isn't considered a legal value by the AbstractFormatter that is, a ParseException is thrown, then the value will not change, and then edited value will persist. |
JFormattedTextField.COMMIT_OR_REVERT | Similar to COMMIT, but if the value isn't legal, behave like REVERT. |
JFormattedTextField.PERSIST | Do nothing, don't obtain a new AbstractFormatter, and don't update the value. |
JFormattedTextField allows the focus to leave, even if the currently edited value is invalid. To lock the focus down while the JFormattedTextField is an invalid edit state you can attach an InputVerifier. The following code snippet shows a potential implementation of such an InputVerifier:
public class FormattedTextFieldVerifier extends InputVerifier { public boolean verify(JComponent input) { if (input instanceof JFormattedTextField) { JFormattedTextField ftf = (JFormattedTextField)input; AbstractFormatter formatter = ftf.getFormatter(); if (formatter != null) { String text = ftf.getText(); try { formatter.stringToValue(text); return true; } catch (ParseException pe) { return false; } } } return true; } public boolean shouldYieldFocus(JComponent input) { return verify(input); } }
Alternatively, you could invoke commitEdit, which would also commit the value.
JFormattedTextField does not do the formatting it self, rather formatting is done through an instance of JFormattedTextField.AbstractFormatter which is obtained from an instance of JFormattedTextField.AbstractFormatterFactory. Instances of JFormattedTextField.AbstractFormatter are notified when they become active by way of the install method, at which point the JFormattedTextField.AbstractFormatter can install whatever it needs to, typically a DocumentFilter. Similarly when JFormattedTextField no longer needs the AbstractFormatter, it will invoke uninstall.
JFormattedTextField typically queries the AbstractFormatterFactory for an AbstractFormat when it gains or loses focus. Although this can change based on the focus lost policy. If the focus lost policy is JFormattedTextField.PERSIST and the JFormattedTextField has been edited, the AbstractFormatterFactory will not be queried until the value has been commited. Similarly if the focus lost policy is JFormattedTextField.COMMIT and an exception is thrown from stringToValue, the AbstractFormatterFactory will not be querired when focus is lost or gained.
JFormattedTextField.AbstractFormatter is also responsible for determining when values are commited to the JFormattedTextField. Some JFormattedTextField.AbstractFormatters will make new values available on every edit, and others will never commit the value. You can force the current value to be obtained from the current JFormattedTextField.AbstractFormatter by way of invoking commitEdit. commitEdit will be invoked whenever return is pressed in the JFormattedTextField.
If an AbstractFormatterFactory has not been explicitly set, one will be set based on the Class of the value type after setValue has been invoked (assuming value is non-null). For example, in the following code an appropriate AbstractFormatterFactory and AbstractFormatter will be created to handle formatting of numbers:
JFormattedTextField tf = new JFormattedTextField(); tf.setValue(new Number(100));
Warning: As the AbstractFormatter will typically install a DocumentFilter on the Document, and a NavigationFilter on the JFormattedTextField you should not install your own. If you do, you are likely to see odd behavior in that the editing policy of the AbstractFormatter will not be enforced.
Warning: Swing is not thread safe. For more information see Swing's Threading Policy .
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 TM has been added to the java.beans package. Please see XMLEncoder .
Nested Class Summary | |
---|---|
static class |
JFormattedTextField.AbstractFormatter
Instances of AbstractFormatter are used by JFormattedTextField to handle the conversion both from an Object to a String, and back from a String to an Object. |
static class |
JFormattedTextField.AbstractFormatterFactory
Instances of AbstractFormatterFactory are used by JFormattedTextField to obtain instances of AbstractFormatter which in turn are used to format values. |
Nested classes/interfaces inherited from class javax.swing. JTextField |
---|
JTextField.AccessibleJTextField |
Nested classes/interfaces inherited from class javax.swing.text. JTextComponent |
---|
JTextComponent.AccessibleJTextComponent , JTextComponent.DropLocation , JTextComponent.KeyBinding |
Nested classes/interfaces inherited from class javax.swing. JComponent |
---|
JComponent.AccessibleJComponent |
Nested classes/interfaces inherited from class java.awt. Container |
---|
Container.AccessibleAWTContainer |
Nested classes/interfaces inherited from class java.awt. Component |
---|
Component.AccessibleAWTComponent , Component.BaselineResizeBehavior , Component.BltBufferStrategy , Component.FlipBufferStrategy |
Field Summary | |
---|---|
static int |
COMMIT
Constant identifying that when focus is lost, commitEdit should be invoked. |
static int |
COMMIT_OR_REVERT
Constant identifying that when focus is lost, commitEdit should be invoked. |
static int |
PERSIST
Constant identifying that when focus is lost, the edited value should be left. |
static int |
REVERT
Constant identifying that when focus is lost, editing value should be reverted to current value set on the JFormattedTextField. |
Fields inherited from class javax.swing. JTextField |
---|
notifyAction |
Fields inherited from class javax.swing.text. JTextComponent |
---|
DEFAULT_KEYMAP , FOCUS_ACCELERATOR_KEY |
Fields inherited from class javax.swing. JComponent |
---|
accessibleContext , listenerList , TOOL_TIP_TEXT_KEY , ui , UNDEFINED_CONDITION , WHEN_ANCESTOR_OF_FOCUSED_COMPONENT , WHEN_FOCUSED , WHEN_IN_FOCUSED_WINDOW |
Fields inherited from class java.awt. Component |
---|
BOTTOM_ALIGNMENT , CENTER_ALIGNMENT , LEFT_ALIGNMENT , RIGHT_ALIGNMENT , TOP_ALIGNMENT |
Fields inherited from interface javax.swing. SwingConstants |
---|
BOTTOM , CENTER , EAST , HORIZONTAL , LEADING , LEFT , NEXT , NORTH , NORTH_EAST , NORTH_WEST , PREVIOUS , RIGHT , SOUTH , SOUTH_EAST , SOUTH_WEST , TOP , TRAILING , VERTICAL , WEST |
Fields inherited from interface java.awt.image. ImageObserver |
---|
ABORT , ALLBITS , ERROR , FRAMEBITS , HEIGHT , PROPERTIES , SOMEBITS , WIDTH |
Constructor Summary | |
---|---|
JFormattedTextField
() Creates a JFormattedTextField with no AbstractFormatterFactory. |
|
JFormattedTextField
(
Format
format) Creates a JFormattedTextField. |
|
JFormattedTextField
(
JFormattedTextField.AbstractFormatter
formatter) Creates a JFormattedTextField with the specified AbstractFormatter. |
|
JFormattedTextField
(
JFormattedTextField.AbstractFormatterFactory
factory) Creates a JFormattedTextField with the specified AbstractFormatterFactory. |
|
JFormattedTextField
(
JFormattedTextField.AbstractFormatterFactory
factory,
Object
currentValue) Creates a JFormattedTextField with the specified AbstractFormatterFactory and initial value. |
|
JFormattedTextField
(
Object
value) Creates a JFormattedTextField with the specified value. |
Method Summary | |
---|---|
void |
commitEdit
() Forces the current value to be taken from the AbstractFormatter and set as the current value. |
Action [] |
getActions
() Fetches the command list for the editor. |
int |
getFocusLostBehavior
() Returns the behavior when focus is lost. |
JFormattedTextField.AbstractFormatter |
getFormatter
() Returns the AbstractFormatter that is used to format and parse the current value. |
JFormattedTextField.AbstractFormatterFactory |
getFormatterFactory
() Returns the current AbstractFormatterFactory. |
String |
getUIClassID
() Gets the class ID for a UI. |
Object |
getValue
() Returns the last valid value. |
protected void |
invalidEdit
() Invoked when the user inputs an invalid value. |
boolean |
isEditValid
() Returns true if the current value being edited is valid. |
protected void |
processFocusEvent
(
FocusEvent
e) Processes any focus events, such as FocusEvent.FOCUS_GAINED or FocusEvent.FOCUS_LOST. |
protected void |
processInputMethodEvent
(
InputMethodEvent
e) Processes any input method events, such as InputMethodEvent.INPUT_METHOD_TEXT_CHANGED or InputMethodEvent.CARET_POSITION_CHANGED. |
void |
setDocument
(
Document
doc) Associates the editor with a text document. |
void |
setFocusLostBehavior
(int behavior) Sets the behavior when focus is lost. |
protected void |
setFormatter
(
JFormattedTextField.AbstractFormatter
format) Sets the current AbstractFormatter. |
void |
setFormatterFactory
(
JFormattedTextField.AbstractFormatterFactory
tf) Sets the AbstractFormatterFactory. |
void |
setValue
(
Object
value) Sets the value that will be formatted by an AbstractFormatter obtained from the current AbstractFormatterFactory. |
Methods inherited from class javax.swing. JTextField |
---|
actionPropertyChanged , addActionListener , configurePropertiesFromAction , createActionPropertyChangeListener , createDefaultModel , fireActionPerformed , getAccessibleContext , getAction , getActionListeners , getColumns , getColumnWidth , getHorizontalAlignment , getHorizontalVisibility , getPreferredSize , getScrollOffset , isValidateRoot , paramString , postActionEvent , removeActionListener , scrollRectToVisible , setAction , setActionCommand , setColumns , setFont , setHorizontalAlignment , setScrollOffset |
Methods inherited from class java.lang. Object |
---|
clone , equals , finalize , getClass , hashCode , notify , notifyAll , wait , wait , wait |
Field Detail |
---|
public static final int COMMIT
public static final int COMMIT_OR_REVERT
public static final int REVERT
public static final int PERSIST
Constructor Detail |
---|
public JFormattedTextField()
public JFormattedTextField(Object value)
public JFormattedTextField(Format format)
public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue)
Method Detail |
---|
public void setFocusLostBehavior(int behavior)
This will throw an IllegalArgumentException if the object passed in is not one of the afore mentioned values.
The default value of this property is JFormattedTextField.COMMIT_OR_REVERT.
public int getFocusLostBehavior()
public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)
If you have not explicitly set an AbstractFormatterFactory by way of this method (or a constructor) an AbstractFormatterFactory and consequently an AbstractFormatter will be used based on the Class of the value. NumberFormatter will be used for Numbers, DateFormatter will be used for Dates, otherwise DefaultFormatter will be used.
This is a JavaBeans bound property.
public JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
protected void setFormatter(JFormattedTextField.AbstractFormatter format)
You should not normally invoke this, instead set the AbstractFormatterFactory or set the value. JFormattedTextField will invoke this as the state of the JFormattedTextField changes and requires the value to be reset. JFormattedTextField passes in the AbstractFormatter obtained from the AbstractFormatterFactory.
This is a JavaBeans bound property.
public JFormattedTextField.AbstractFormatter getFormatter()
public void setValue(Object value)
The default value of this property is null.
This is a JavaBeans bound property.
public Object getValue()
public void commitEdit() throws ParseException
public boolean isEditValid()
protected void invalidEdit()
protected void processInputMethodEvent(InputMethodEvent e)
protected void processFocusEvent(FocusEvent e)
public Action[] getActions()
public String getUIClassID()
public void setDocument(Document doc)