Package Summary Overview Summary

### class:JFormattedTextField [NONE]
- All Implemented Interfaces: ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants
      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 `PropertyChangeEvent`s 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.
  The default is `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.AbstractFormatter`s 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™ has been added to the `java.beans` package. Please see `XMLEncoder`. Since: 1.4

### field:COMMIT [NONE]
- #### COMMIT
      public static final int COMMIT
Constant identifying that when focus is lost, `commitEdit` should be invoked. If in committing the new value a `ParseException` is thrown, the invalid value will remain. See Also: `setFocusLostBehavior(int)`, Constant Field Values

### field:COMMIT_OR_REVERT [NONE]
- #### COMMIT_OR_REVERT
      public static final int COMMIT_OR_REVERT
Constant identifying that when focus is lost, `commitEdit` should be invoked. If in committing the new value a `ParseException` is thrown, the value will be reverted. See Also: `setFocusLostBehavior(int)`, Constant Field Values

### field:REVERT [NONE]
- #### REVERT
      public static final int REVERT
Constant identifying that when focus is lost, editing value should be reverted to current value set on the `JFormattedTextField`. See Also: `setFocusLostBehavior(int)`, Constant Field Values

### field:PERSIST [NONE]
- #### PERSIST
      public static final int PERSIST
Constant identifying that when focus is lost, the edited value should be left. See Also: `setFocusLostBehavior(int)`, Constant Field Values

### constructor:JFormattedTextField() [NONE]
- #### JFormattedTextField
      public JFormattedTextField()
Creates a `JFormattedTextField` with no `AbstractFormatterFactory`. Use `setMask` or `setFormatterFactory` to configure the `JFormattedTextField` to edit a particular type of value.

### constructor:JFormattedTextField(java.lang.Object) [NONE]
- #### JFormattedTextField
      public JFormattedTextField(Object value)
Creates a JFormattedTextField with the specified value. This will create an `AbstractFormatterFactory` based on the type of `value`. Parameters: `value` - Initial value for the JFormattedTextField

### constructor:JFormattedTextField(java.text.Format) [NONE]
- #### JFormattedTextField
      public JFormattedTextField(Format format)
Creates a `JFormattedTextField`. `format` is wrapped in an appropriate `AbstractFormatter` which is then wrapped in an `AbstractFormatterFactory`. Parameters: `format` - Format used to look up an AbstractFormatter

### constructor:JFormattedTextField(javax.swing.JFormattedTextField.AbstractFormatter) [NONE]
- #### JFormattedTextField
      public JFormattedTextField(JFormattedTextField.AbstractFormatter formatter)
Creates a `JFormattedTextField` with the specified `AbstractFormatter`. The `AbstractFormatter` is placed in an `AbstractFormatterFactory`. Parameters: `formatter` - AbstractFormatter to use for formatting.

### constructor:JFormattedTextField(javax.swing.JFormattedTextField.AbstractFormatterFactory) [NONE]
- #### JFormattedTextField
      public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory)
Creates a `JFormattedTextField` with the specified `AbstractFormatterFactory`. Parameters: `factory` - AbstractFormatterFactory used for formatting.

### constructor:JFormattedTextField(javax.swing.JFormattedTextField.AbstractFormatterFactory, java.lang.Object) [NONE]
- #### JFormattedTextField
      public JFormattedTextField(JFormattedTextField.AbstractFormatterFactory factory,
                                 Object currentValue)
Creates a `JFormattedTextField` with the specified `AbstractFormatterFactory` and initial value. Parameters: `factory` - `AbstractFormatterFactory` used for formatting. `currentValue` - Initial value to use

### method:setFocusLostBehavior(int) [NONE]
- #### setFocusLostBehavior
      public void setFocusLostBehavior(int behavior)
Sets the behavior when focus is lost. This will be one of `JFormattedTextField.COMMIT_OR_REVERT`, `JFormattedTextField.REVERT`, `JFormattedTextField.COMMIT` or `JFormattedTextField.PERSIST` Note that some `AbstractFormatter`s 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`. Parameters: `behavior` - Identifies behavior when focus is lost Throws: `IllegalArgumentException` - if behavior is not one of the known values

### method:getFocusLostBehavior() [NONE]
- #### getFocusLostBehavior
      public int getFocusLostBehavior()
Returns the behavior when focus is lost. This will be one of `COMMIT_OR_REVERT`, `COMMIT`, `REVERT` or `PERSIST` Note that some `AbstractFormatter`s may push changes as they occur, so that the value of this will have no effect. Returns: returns behavior when focus is lost

### method:setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory) [NONE]
- #### setFormatterFactory
      public void setFormatterFactory(JFormattedTextField.AbstractFormatterFactory tf)
Sets the `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 `Number`s, `DateFormatter` will be used for `Dates`, otherwise `DefaultFormatter` will be used. This is a JavaBeans bound property. Parameters: `tf` - `AbstractFormatterFactory` used to lookup instances of `AbstractFormatter`

### method:getFormatterFactory() [NONE]
- #### getFormatterFactory
      public JFormattedTextField.AbstractFormatterFactory getFormatterFactory()
Returns the current `AbstractFormatterFactory`. Returns: `AbstractFormatterFactory` used to determine `AbstractFormatter`s See Also: `setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)`

### method:setFormatter(javax.swing.JFormattedTextField.AbstractFormatter) [NONE]
- #### setFormatter
      protected void setFormatter(JFormattedTextField.AbstractFormatter format)
Sets the current `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. Parameters: `format` - AbstractFormatter to use for formatting See Also: `setFormatterFactory(javax.swing.JFormattedTextField.AbstractFormatterFactory)`

### method:getFormatter() [NONE]
- #### getFormatter
      public JFormattedTextField.AbstractFormatter getFormatter()
Returns the `AbstractFormatter` that is used to format and parse the current value. Returns: AbstractFormatter used for formatting

### method:setValue(java.lang.Object) [NONE]
- #### setValue
      public void setValue(Object value)
Sets the value that will be formatted by an `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. Parameters: `value` - Current value to display

### method:getValue() [NONE]
- #### getValue
      public Object getValue()
Returns the last valid value. Based on the editing policy of the `AbstractFormatter` this may not return the current value. The currently edited value can be obtained by invoking `commitEdit` followed by `getValue`. Returns: Last valid value

### method:commitEdit() [NONE]
- #### commitEdit
      public void commitEdit()
                      throws ParseException
Forces the current value to be taken from the `AbstractFormatter` and set as the current value. This has no effect if there is no current `AbstractFormatter` installed. Throws: `ParseException` - if the `AbstractFormatter` is not able to format the current value

### method:isEditValid() [NONE]
- #### isEditValid
      public boolean isEditValid()
Returns true if the current value being edited is valid. The value of this is managed by the current `AbstractFormatter`, as such there is no public setter for it. Returns: true if the current value being edited is valid.

### method:invalidEdit() [NONE]
- #### 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.

### method:processInputMethodEvent(java.awt.event.InputMethodEvent) [NONE]
- #### processInputMethodEvent
      protected void processInputMethodEvent(InputMethodEvent e)
Processes any input method events, such as `InputMethodEvent.INPUT_METHOD_TEXT_CHANGED` or `InputMethodEvent.CARET_POSITION_CHANGED`. Overrides: `processInputMethodEvent` in class `JTextComponent` Parameters: `e` - the `InputMethodEvent` See Also: `InputMethodEvent`

### method:processFocusEvent(java.awt.event.FocusEvent) [NONE]
- #### processFocusEvent
      protected void processFocusEvent(FocusEvent e)
Processes any focus events, such as `FocusEvent.FOCUS_GAINED` or `FocusEvent.FOCUS_LOST`. Overrides: `processFocusEvent` in class `Component` Parameters: `e` - the `FocusEvent` See Also: `FocusEvent`

### method:getActions() [NONE]
- #### getActions
      public Action[] 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: `getActions` in class `JTextField` Returns: the command list

### method:getUIClassID() [NONE]
- #### getUIClassID
      public String getUIClassID()
Gets the class ID for a UI. Overrides: `getUIClassID` in class `JTextField` Returns: the string "FormattedTextFieldUI" See Also: `JComponent.getUIClassID()`

### method:setDocument(javax.swing.text.Document) [NONE]
- #### setDocument
      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: `setDocument` in class `JTextField` Parameters: `doc` - the document to display/edit See Also: `JTextComponent.getDocument()`