public class JFormattedTextField extends JTextField
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 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 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.
| Modifier and Type | Class and Description |
|---|---|
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. |
JTextField.AccessibleJTextFieldJTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBindingJComponent.AccessibleJComponentContainer.AccessibleAWTContainerComponent.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy| Modifier and Type | Field and Description |
|---|---|
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. |
notifyActionDEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEYlistenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOWaccessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTBOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WESTABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH| Constructor and Description |
|---|
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.
|
| Modifier and Type | Method and Description |
|---|---|
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. |
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, setScrollOffsetaddCaretListener, addInputMethodListener, 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, moveCaretPosition, paste, print, print, print, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, restoreComposedText, saveComposedText, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, setUI, updateUI, viewToModel, writeaddAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, 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, 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, updateadd, 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, validateTreeaction, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, 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, getPeer, 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, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCyclepublic static final int COMMIT
commitEdit should be invoked. If in committing the
new value a ParseException is thrown, the invalid
value will remain.setFocusLostBehavior(int),
Constant Field Valuespublic static final int COMMIT_OR_REVERT
commitEdit should be invoked. If in committing the new
value a ParseException is thrown, the value will be
reverted.setFocusLostBehavior(int),
Constant Field Valuespublic static final int REVERT
JFormattedTextField.setFocusLostBehavior(int),
Constant Field Valuespublic static final int PERSIST
setFocusLostBehavior(int),
Constant Field Valuespublic JFormattedTextField()
JFormattedTextField with no
AbstractFormatterFactory. Use setMask or
setFormatterFactory to configure the
JFormattedTextField to edit a particular type of
value.public JFormattedTextField(Object value)
AbstractFormatterFactory based on the
type of value.value - Initial value for the JFormattedTextFieldpublic JFormattedTextField(Format format)
JFormattedTextField. format is
wrapped in an appropriate AbstractFormatter which is
then wrapped in an AbstractFormatterFactory.format - Format used to look up an AbstractFormatterpublic JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
JFormattedTextField with the specified
AbstractFormatter. The AbstractFormatter
is placed in an AbstractFormatterFactory.formatter - AbstractFormatter to use for formatting.public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
JFormattedTextField with the specified
AbstractFormatterFactory.factory - AbstractFormatterFactory used for formatting.public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory, Object currentValue)
JFormattedTextField with the specified
AbstractFormatterFactory and initial value.factory - AbstractFormatterFactory used for
formatting.currentValue - Initial value to usepublic void setFocusLostBehavior(int behavior)
JFormattedTextField.COMMIT_OR_REVERT,
JFormattedTextField.REVERT,
JFormattedTextField.COMMIT or
JFormattedTextField.PERSIST
Note that some AbstractFormatters may push changes as
they occur, so that the value of this will have no effect.
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.
behavior - Identifies behavior when focus is lostIllegalArgumentException - if behavior is not one of the known
valuespublic int getFocusLostBehavior()
COMMIT_OR_REVERT,
COMMIT,
REVERT or
PERSIST
Note that some AbstractFormatters may push changes as
they occur, so that the value of this will have no effect.public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)
AbstractFormatterFactory.
AbstractFormatterFactory is
able to return an instance of AbstractFormatter that is
used to format a value for display, as well an enforcing an editing
policy.
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.
tf - AbstractFormatterFactory used to lookup
instances of AbstractFormatterpublic JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
AbstractFormatterFactory.AbstractFormatterFactory used to determine
AbstractFormatterssetFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)protected void setFormatter(JFormattedTextField.AbstractFormatter format)
AbstractFormatter.
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.
format - AbstractFormatter to use for formattingsetFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)public JFormattedTextField.AbstractFormatter getFormatter()
AbstractFormatter that is used to format and
parse the current value.public void setValue(Object value)
AbstractFormatter obtained from the current
AbstractFormatterFactory. If no
AbstractFormatterFactory has been specified, this will
attempt to create one based on the type of value.
The default value of this property is null.
This is a JavaBeans bound property.
value - Current value to displaypublic Object getValue()
AbstractFormatter this may not return the current
value. The currently edited value can be obtained by invoking
commitEdit followed by getValue.public void commitEdit()
throws ParseException
AbstractFormatter and set as the current value.
This has no effect if there is no current
AbstractFormatter installed.ParseException - if the AbstractFormatter is not able
to format the current valuepublic boolean isEditValid()
AbstractFormatter, as such
there is no public setter for it.protected void invalidEdit()
protected void processInputMethodEvent(InputMethodEvent e)
InputMethodEvent.INPUT_METHOD_TEXT_CHANGED or
InputMethodEvent.CARET_POSITION_CHANGED.processInputMethodEvent in class JTextComponente - the InputMethodEventInputMethodEventprotected void processFocusEvent(FocusEvent e)
FocusEvent.FOCUS_GAINED or
FocusEvent.FOCUS_LOST.processFocusEvent in class Componente - the FocusEventFocusEventpublic Action[] getActions()
getActions in class JTextFieldpublic String getUIClassID()
getUIClassID in class JTextFieldJComponent.getUIClassID()public void setDocument(Document doc)
setDocument in class JTextFielddoc - the document to display/editJTextComponent.getDocument() Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2024, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.