Class JFormattedTextField
- All Implemented Interfaces:
ImageObserver,MenuContainer,Serializable,Accessible,Scrollable,SwingConstants
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.COMMIT_OR_REVERT,
refer to setFocusLostBehavior(int) for more information on this.
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 itself,
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 committed. Similarly, if the focus lost policy is
JFormattedTextField.COMMIT and an exception
is thrown from stringToValue, the
AbstractFormatterFactory will not be queried when focus is
lost or gained.
JFormattedTextField.AbstractFormatter
is also responsible for determining when values are committed 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(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
has been added to the java.beans package.
Please see XMLEncoder.
- Since:
- 1.4
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classInstances ofAbstractFormatterare used byJFormattedTextFieldto handle the conversion both from an Object to a String, and back from a String to an Object.static classInstances ofAbstractFormatterFactoryare used byJFormattedTextFieldto obtain instances ofAbstractFormatterwhich in turn are used to format values.Nested classes/interfaces declared in class javax.swing.JTextField
JTextField.AccessibleJTextFieldNested classes/interfaces declared in class javax.swing.text.JTextComponent
JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBindingNested classes/interfaces declared in class javax.swing.JComponent
JComponent.AccessibleJComponentNested classes/interfaces declared in class java.awt.Container
Container.AccessibleAWTContainerNested classes/interfaces declared in class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intConstant identifying that when focus is lost,commitEditshould be invoked.static final intConstant identifying that when focus is lost,commitEditshould be invoked.static final intConstant identifying that when focus is lost, the edited value should be left.static final intConstant identifying that when focus is lost, editing value should be reverted to current value set on theJFormattedTextField.Fields declared in class javax.swing.JTextField
notifyActionFields declared in class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEYFields declared in class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOWFields declared in class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTFields declared in interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTHFields declared in 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 -
Constructor Summary
ConstructorsConstructorDescriptionCreates aJFormattedTextFieldwith noAbstractFormatterFactory.JFormattedTextField(Object value) Creates a JFormattedTextField with the specified value.JFormattedTextField(Format format) Creates aJFormattedTextField.Creates aJFormattedTextFieldwith the specifiedAbstractFormatter.Creates aJFormattedTextFieldwith the specifiedAbstractFormatterFactory.JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue) Creates aJFormattedTextFieldwith the specifiedAbstractFormatterFactoryand initial value. -
Method Summary
Modifier and TypeMethodDescriptionvoidForces the current value to be taken from theAbstractFormatterand set as the current value.Action[]Fetches the command list for the editor.intReturns the behavior when focus is lost.Returns theAbstractFormatterthat is used to format and parse the current value.Returns the currentAbstractFormatterFactory.Gets the class ID for a UI.getValue()Returns the last valid value.protected voidInvoked when the user inputs an invalid value.booleanReturns true if the current value being edited is valid.protected voidProcesses any focus events, such asFocusEvent.FOCUS_GAINEDorFocusEvent.FOCUS_LOST.protected voidProcesses any input method events, such asInputMethodEvent.INPUT_METHOD_TEXT_CHANGEDorInputMethodEvent.CARET_POSITION_CHANGED.voidsetDocument(Document doc) Associates the editor with a text document.voidsetFocusLostBehavior(int behavior) Sets the behavior when focus is lost.protected voidSets the currentAbstractFormatter.voidSets theAbstractFormatterFactory.voidSets the value that will be formatted by anAbstractFormatterobtained from the currentAbstractFormatterFactory.Methods declared in 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, setScrollOffsetMethods declared in class javax.swing.text.JTextComponent
addCaretListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, modelToView2D, moveCaretPosition, paste, print, print, print, read, removeCaretListener, removeKeymap, replaceSelection, restoreComposedText, saveComposedText, select, selectAll, setCaret, setCaretColor, setCaretPosition, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, viewToModel2D, writeMethods declared in class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, updateMethods declared in class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTreeMethods declared in class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Field Details
-
COMMIT
public static final int COMMITConstant identifying that when focus is lost,commitEditshould be invoked. If in committing the new value aParseExceptionis thrown, the invalid value will remain.- See Also:
-
COMMIT_OR_REVERT
public static final int COMMIT_OR_REVERTConstant identifying that when focus is lost,commitEditshould be invoked. If in committing the new value aParseExceptionis thrown, the value will be reverted.- See Also:
-
REVERT
public static final int REVERTConstant identifying that when focus is lost, editing value should be reverted to current value set on theJFormattedTextField.- See Also:
-
PERSIST
public static final int PERSISTConstant identifying that when focus is lost, the edited value should be left.- See Also:
-
-
Constructor Details
-
JFormattedTextField
public JFormattedTextField()Creates aJFormattedTextFieldwith noAbstractFormatterFactory. UsesetMaskorsetFormatterFactoryto configure theJFormattedTextFieldto edit a particular type of value. -
JFormattedTextField
Creates a JFormattedTextField with the specified value. This will create anAbstractFormatterFactorybased on the type ofvalue.- Parameters:
value- Initial value for the JFormattedTextField
-
JFormattedTextField
Creates aJFormattedTextField.formatis wrapped in an appropriateAbstractFormatterwhich is then wrapped in anAbstractFormatterFactory.- Parameters:
format- Format used to look up an AbstractFormatter
-
JFormattedTextField
Creates aJFormattedTextFieldwith the specifiedAbstractFormatter. TheAbstractFormatteris placed in anAbstractFormatterFactory.- Parameters:
formatter- AbstractFormatter to use for formatting.
-
JFormattedTextField
Creates aJFormattedTextFieldwith the specifiedAbstractFormatterFactory.- Parameters:
factory- AbstractFormatterFactory used for formatting.
-
JFormattedTextField
public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue) Creates aJFormattedTextFieldwith the specifiedAbstractFormatterFactoryand initial value.- Parameters:
factory-AbstractFormatterFactoryused for formatting.currentValue- Initial value to use
-
-
Method Details
-
setFocusLostBehavior
@BeanProperty(bound=false, enumerationValues={"JFormattedTextField.COMMIT","JFormattedTextField.COMMIT_OR_REVERT","JFormattedTextField.REVERT","JFormattedTextField.PERSIST"}, description="Behavior when component loses focus") public void setFocusLostBehavior(int behavior) Sets the behavior when focus is lost. This will be one ofJFormattedTextField.COMMIT_OR_REVERT,JFormattedTextField.REVERT,JFormattedTextField.COMMITorJFormattedTextField.PERSISTNote that someAbstractFormatters may push changes as they occur, so that the value of this will have no effect.This will throw an
IllegalArgumentExceptionif the object passed in is not one of the afore mentioned values.The default value of this property is
JFormattedTextField.COMMIT_OR_REVERT.- Parameters:
behavior- Identifies behavior when focus is lost- Throws:
IllegalArgumentException- if behavior is not one of the known values
-
getFocusLostBehavior
public int getFocusLostBehavior()Returns the behavior when focus is lost. This will be one ofCOMMIT_OR_REVERT,COMMIT,REVERTorPERSISTNote that someAbstractFormatters may push changes as they occur, so that the value of this will have no effect.- Returns:
- returns behavior when focus is lost
-
setFormatterFactory
@BeanProperty(visualUpdate=true, description="AbstractFormatterFactory, responsible for returning an AbstractFormatter that can format the current value.") public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf) Sets theAbstractFormatterFactory.AbstractFormatterFactoryis able to return an instance ofAbstractFormatterthat is used to format a value for display, as well an enforcing an editing policy.If you have not explicitly set an
AbstractFormatterFactoryby way of this method (or a constructor) anAbstractFormatterFactoryand consequently anAbstractFormatterwill be used based on theClassof the value.NumberFormatterwill be used forNumbers,DateFormatterwill be used forDates, otherwiseDefaultFormatterwill be used.This is a JavaBeans bound property.
- Parameters:
tf-AbstractFormatterFactoryused to lookup instances ofAbstractFormatter
-
getFormatterFactory
Returns the currentAbstractFormatterFactory.- Returns:
AbstractFormatterFactoryused to determineAbstractFormatters- See Also:
-
setFormatter
Sets the currentAbstractFormatter.You should not normally invoke this, instead set the
AbstractFormatterFactoryor set the value.JFormattedTextFieldwill invoke this as the state of theJFormattedTextFieldchanges and requires the value to be reset.JFormattedTextFieldpasses in theAbstractFormatterobtained from theAbstractFormatterFactory.This is a JavaBeans bound property.
- Parameters:
format- AbstractFormatter to use for formatting- See Also:
-
getFormatter
@BeanProperty(visualUpdate=true, description="TextFormatter, responsible for formatting the current value") public JFormattedTextField.AbstractFormatter getFormatter()Returns theAbstractFormatterthat is used to format and parse the current value.- Returns:
- AbstractFormatter used for formatting
-
setValue
@BeanProperty(visualUpdate=true, description="The value to be formatted.") public void setValue(Object value) Sets the value that will be formatted by anAbstractFormatterobtained from the currentAbstractFormatterFactory. If noAbstractFormatterFactoryhas been specified, this will attempt to create one based on the type ofvalue.The default value of this property is null.
This is a JavaBeans bound property.
- Parameters:
value- Current value to display
-
getValue
Returns the last valid value. Based on the editing policy of theAbstractFormatterthis may not return the current value. The currently edited value can be obtained by invokingcommitEditfollowed bygetValue.- Returns:
- Last valid value
-
commitEdit
Forces the current value to be taken from theAbstractFormatterand set as the current value. This has no effect if there is no currentAbstractFormatterinstalled.- Throws:
ParseException- if theAbstractFormatteris not able to format the current value
-
isEditValid
Returns true if the current value being edited is valid. The value of this is managed by the currentAbstractFormatter, as such there is no public setter for it.- Returns:
- true if the current value being edited is valid.
-
invalidEdit
protected void invalidEdit()Invoked when the user inputs an invalid value. This gives the component a chance to provide feedback. The default implementation beeps. -
processInputMethodEvent
Processes any input method events, such asInputMethodEvent.INPUT_METHOD_TEXT_CHANGEDorInputMethodEvent.CARET_POSITION_CHANGED.- Overrides:
processInputMethodEventin classComponent- Parameters:
e- theInputMethodEvent- See Also:
-
processFocusEvent
Processes any focus events, such asFocusEvent.FOCUS_GAINEDorFocusEvent.FOCUS_LOST.- Overrides:
processFocusEventin classComponent- Parameters:
e- theFocusEvent- See Also:
-
getActions
Fetches the command list for the editor. This is the list of commands supported by the plugged-in UI augmented by the collection of commands that the editor itself supports. These are useful for binding to events, such as in a keymap.- Overrides:
getActionsin classJTextField- Returns:
- the command list
-
getUIClassID
Gets the class ID for a UI.- Overrides:
getUIClassIDin classJTextField- Returns:
- the string "FormattedTextFieldUI"
- See Also:
-
setDocument
@BeanProperty(expert=true, description="the text document model") public void setDocument(Document doc) Associates the editor with a text document. The currently registered factory is used to build a view for the document, which gets displayed by the editor after revalidation. A PropertyChange event ("document") is propagated to each listener.- Overrides:
setDocumentin classJTextField- Parameters:
doc- the document to display/edit- See Also:
-