- 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 AbstractFormatterthat is, aParseExceptionis 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 likeREVERT. | 
| 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.
- Since:
- 1.4
- 
Nested Class SummaryNested 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.JTextFieldJTextField.AccessibleJTextFieldNested classes/interfaces declared in class javax.swing.text.JTextComponentJTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBindingNested classes/interfaces declared in class javax.swing.JComponentJComponent.AccessibleJComponentNested classes/interfaces declared in class java.awt.ContainerContainer.AccessibleAWTContainerNested classes/interfaces declared in class java.awt.ComponentComponent.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
- 
Field SummaryFieldsModifier 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.JTextFieldnotifyActionFields declared in class javax.swing.text.JTextComponentDEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEYFields declared in class javax.swing.JComponentlistenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOWFields declared in class java.awt.ComponentaccessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTFields declared in interface java.awt.image.ImageObserverABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTHFields declared in interface javax.swing.SwingConstantsBOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
- 
Constructor SummaryConstructorsConstructorDescriptionCreates 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 SummaryModifier 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.JTextFieldactionPropertyChanged, 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.JTextComponentaddCaretListener, 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.JComponentaddAncestorListener, 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.Containeradd, 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.Componentaction, 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- 
COMMITpublic 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_REVERTpublic 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:
 
- 
REVERTpublic static final int REVERTConstant identifying that when focus is lost, editing value should be reverted to current value set on theJFormattedTextField.- See Also:
 
- 
PERSISTpublic static final int PERSISTConstant identifying that when focus is lost, the edited value should be left.- See Also:
 
 
- 
- 
Constructor Details- 
JFormattedTextFieldpublic JFormattedTextField()Creates aJFormattedTextFieldwith noAbstractFormatterFactory. UsesetMaskorsetFormatterFactoryto configure theJFormattedTextFieldto edit a particular type of value.
- 
JFormattedTextFieldCreates a JFormattedTextField with the specified value. This will create anAbstractFormatterFactorybased on the type ofvalue.- Parameters:
- value- Initial value for the JFormattedTextField
 
- 
JFormattedTextFieldCreates aJFormattedTextField.formatis wrapped in an appropriateAbstractFormatterwhich is then wrapped in anAbstractFormatterFactory.- Parameters:
- format- Format used to look up an AbstractFormatter
 
- 
JFormattedTextFieldCreates aJFormattedTextFieldwith the specifiedAbstractFormatter. TheAbstractFormatteris placed in anAbstractFormatterFactory.- Parameters:
- formatter- AbstractFormatter to use for formatting.
 
- 
JFormattedTextFieldCreates aJFormattedTextFieldwith the specifiedAbstractFormatterFactory.- Parameters:
- factory- AbstractFormatterFactory used for formatting.
 
- 
JFormattedTextFieldpublic 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
 
- 
getFocusLostBehaviorpublic 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 of- AbstractFormatter
 
- 
getFormatterFactoryReturns the currentAbstractFormatterFactory.- Returns:
- AbstractFormatterFactoryused to determine- AbstractFormatters
- See Also:
 
- 
setFormatterSets 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
 
- 
getValueReturns 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
 
- 
commitEditForces 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 the- AbstractFormatteris not able to format the current value
 
- 
isEditValidReturns 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.
 
- 
invalidEditprotected void invalidEdit()Invoked when the user inputs an invalid value. This gives the component a chance to provide feedback. The default implementation beeps.
- 
processInputMethodEventProcesses any input method events, such asInputMethodEvent.INPUT_METHOD_TEXT_CHANGEDorInputMethodEvent.CARET_POSITION_CHANGED.- Overrides:
- processInputMethodEventin class- Component
- Parameters:
- e- the- InputMethodEvent
- See Also:
 
- 
processFocusEventProcesses any focus events, such asFocusEvent.FOCUS_GAINEDorFocusEvent.FOCUS_LOST.- Overrides:
- processFocusEventin class- Component
- Parameters:
- e- the- FocusEvent
- See Also:
 
- 
getActionsFetches 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 class- JTextField
- Returns:
- the command list
 
- 
getUIClassIDGets the class ID for a UI.- Overrides:
- getUIClassIDin class- JTextField
- 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 class- JTextField
- Parameters:
- doc- the document to display/edit
- See Also:
 
 
-