< prev index next >
src/java.desktop/share/classes/javax/swing/JFormattedTextField.java
Print this page
*** 33,85 ****
import javax.swing.event.*;
import javax.swing.plaf.UIResource;
import javax.swing.text.*;
/**
! * <code>JFormattedTextField</code> extends <code>JTextField</code> 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 <code>JFormattedTextField</code> to edit dates:
* <pre>
* JFormattedTextField ftf = new JFormattedTextField();
* ftf.setValue(new Date());
* </pre>
* <p>
! * Once a <code>JFormattedTextField</code> has been created, you can
* listen for editing changes by way of adding
! * a <code>PropertyChangeListener</code> and listening for
! * <code>PropertyChangeEvent</code>s with the property name <code>value</code>.
* <p>
! * <code>JFormattedTextField</code> allows
* configuring what action should be taken when focus is lost. The possible
* configurations are:
* <table summary="Possible JFormattedTextField configurations and their descriptions">
* <tr><th><p style="text-align:left">Value</p></th><th><p style="text-align:left">Description</p></th></tr>
* <tr><td>JFormattedTextField.REVERT
! * <td>Revert the display to match that of <code>getValue</code>,
* possibly losing the current edit.
* <tr><td>JFormattedTextField.COMMIT
* <td>Commits the current value. If the value being edited
* isn't considered a legal value by the
! * <code>AbstractFormatter</code> that is, a
! * <code>ParseException</code> is thrown, then the value
* will not change, and then edited value will persist.
* <tr><td>JFormattedTextField.COMMIT_OR_REVERT
! * <td>Similar to <code>COMMIT</code>, but if the value isn't
! * legal, behave like <code>REVERT</code>.
* <tr><td>JFormattedTextField.PERSIST
* <td>Do nothing, don't obtain a new
! * <code>AbstractFormatter</code>, and don't update the value.
* </table>
! * The default is <code>JFormattedTextField.COMMIT_OR_REVERT</code>,
* refer to {@link #setFocusLostBehavior} for more information on this.
* <p>
! * <code>JFormattedTextField</code> allows the focus to leave, even if
* the currently edited value is invalid. To lock the focus down while the
! * <code>JFormattedTextField</code> is an invalid edit state
! * you can attach an <code>InputVerifier</code>. The following code snippet
! * shows a potential implementation of such an <code>InputVerifier</code>:
* <pre>
* public class FormattedTextFieldVerifier extends InputVerifier {
* public boolean verify(JComponent input) {
* if (input instanceof JFormattedTextField) {
* JFormattedTextField ftf = (JFormattedTextField)input;
--- 33,85 ----
import javax.swing.event.*;
import javax.swing.plaf.UIResource;
import javax.swing.text.*;
/**
! * {@code JFormattedTextField} extends {@code 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 {@code JFormattedTextField} to edit dates:
* <pre>
* JFormattedTextField ftf = new JFormattedTextField();
* ftf.setValue(new Date());
* </pre>
* <p>
! * Once a {@code JFormattedTextField} has been created, you can
* listen for editing changes by way of adding
! * a {@code PropertyChangeListener} and listening for
! * {@code PropertyChangeEvent}s with the property name {@code value}.
* <p>
! * {@code JFormattedTextField} allows
* configuring what action should be taken when focus is lost. The possible
* configurations are:
* <table summary="Possible JFormattedTextField configurations and their descriptions">
* <tr><th><p style="text-align:left">Value</p></th><th><p style="text-align:left">Description</p></th></tr>
* <tr><td>JFormattedTextField.REVERT
! * <td>Revert the display to match that of {@code getValue},
* possibly losing the current edit.
* <tr><td>JFormattedTextField.COMMIT
* <td>Commits the current value. If the value being edited
* isn't considered a legal value by the
! * {@code AbstractFormatter} that is, a
! * {@code ParseException} is thrown, then the value
* will not change, and then edited value will persist.
* <tr><td>JFormattedTextField.COMMIT_OR_REVERT
! * <td>Similar to {@code COMMIT}, but if the value isn't
! * legal, behave like {@code REVERT}.
* <tr><td>JFormattedTextField.PERSIST
* <td>Do nothing, don't obtain a new
! * {@code AbstractFormatter}, and don't update the value.
* </table>
! * The default is {@code JFormattedTextField.COMMIT_OR_REVERT},
* refer to {@link #setFocusLostBehavior} for more information on this.
* <p>
! * {@code JFormattedTextField} allows the focus to leave, even if
* the currently edited value is invalid. To lock the focus down while the
! * {@code JFormattedTextField} is an invalid edit state
! * you can attach an {@code InputVerifier}. The following code snippet
! * shows a potential implementation of such an {@code InputVerifier}:
* <pre>
* public class FormattedTextFieldVerifier extends InputVerifier {
* public boolean verify(JComponent input) {
* if (input instanceof JFormattedTextField) {
* JFormattedTextField ftf = (JFormattedTextField)input;
*** 100,166 ****
* return verify(input);
* }
* }
* </pre>
* <p>
! * Alternatively, you could invoke <code>commitEdit</code>, which would also
* commit the value.
* <p>
! * <code>JFormattedTextField</code> does not do the formatting it self,
* rather formatting is done through an instance of
! * <code>JFormattedTextField.AbstractFormatter</code> which is obtained from
! * an instance of <code>JFormattedTextField.AbstractFormatterFactory</code>.
! * Instances of <code>JFormattedTextField.AbstractFormatter</code> are
* notified when they become active by way of the
! * <code>install</code> method, at which point the
! * <code>JFormattedTextField.AbstractFormatter</code> can install whatever
! * it needs to, typically a <code>DocumentFilter</code>. Similarly when
! * <code>JFormattedTextField</code> no longer
! * needs the <code>AbstractFormatter</code>, it will invoke
! * <code>uninstall</code>.
! * <p>
! * <code>JFormattedTextField</code> typically
! * queries the <code>AbstractFormatterFactory</code> for an
! * <code>AbstractFormat</code> when it gains or loses focus. Although this
* can change based on the focus lost policy. If the focus lost
! * policy is <code>JFormattedTextField.PERSIST</code>
! * and the <code>JFormattedTextField</code> has been edited, the
! * <code>AbstractFormatterFactory</code> will not be queried until the
* value has been committed. Similarly if the focus lost policy is
! * <code>JFormattedTextField.COMMIT</code> and an exception
! * is thrown from <code>stringToValue</code>, the
! * <code>AbstractFormatterFactory</code> will not be queried when focus is
* lost or gained.
* <p>
! * <code>JFormattedTextField.AbstractFormatter</code>
* is also responsible for determining when values are committed to
! * the <code>JFormattedTextField</code>. Some
! * <code>JFormattedTextField.AbstractFormatter</code>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 <code>JFormattedTextField.AbstractFormatter</code>
! * by way of invoking <code>commitEdit</code>. <code>commitEdit</code> will
* be invoked whenever return is pressed in the
! * <code>JFormattedTextField</code>.
* <p>
! * If an <code>AbstractFormatterFactory</code> has not been explicitly
! * set, one will be set based on the <code>Class</code> of the value type after
! * <code>setValue</code> has been invoked (assuming value is non-null).
* For example, in the following code an appropriate
! * <code>AbstractFormatterFactory</code> and <code>AbstractFormatter</code>
* will be created to handle formatting of numbers:
* <pre>
* JFormattedTextField tf = new JFormattedTextField();
* tf.setValue(100);
* </pre>
* <p>
! * <strong>Warning:</strong> As the <code>AbstractFormatter</code> will
! * typically install a <code>DocumentFilter</code> on the
! * <code>Document</code>, and a <code>NavigationFilter</code> on the
! * <code>JFormattedTextField</code> you should not install your own. If you do,
* you are likely to see odd behavior in that the editing policy of the
! * <code>AbstractFormatter</code> will not be enforced.
* <p>
* <strong>Warning:</strong> Swing is not thread safe. For more
* information see <a
* href="package-summary.html#threading">Swing's Threading
* Policy</a>.
--- 100,166 ----
* return verify(input);
* }
* }
* </pre>
* <p>
! * Alternatively, you could invoke {@code commitEdit}, which would also
* commit the value.
* <p>
! * {@code JFormattedTextField} does not do the formatting it self,
* rather formatting is done through an instance of
! * {@code JFormattedTextField.AbstractFormatter} which is obtained from
! * an instance of {@code JFormattedTextField.AbstractFormatterFactory}.
! * Instances of {@code JFormattedTextField.AbstractFormatter} are
* notified when they become active by way of the
! * {@code install} method, at which point the
! * {@code JFormattedTextField.AbstractFormatter} can install whatever
! * it needs to, typically a {@code DocumentFilter}. Similarly when
! * {@code JFormattedTextField} no longer
! * needs the {@code AbstractFormatter}, it will invoke
! * {@code uninstall}.
! * <p>
! * {@code JFormattedTextField} typically
! * queries the {@code AbstractFormatterFactory} for an
! * {@code AbstractFormat} when it gains or loses focus. Although this
* can change based on the focus lost policy. If the focus lost
! * policy is {@code JFormattedTextField.PERSIST}
! * and the {@code JFormattedTextField} has been edited, the
! * {@code AbstractFormatterFactory} will not be queried until the
* value has been committed. Similarly if the focus lost policy is
! * {@code JFormattedTextField.COMMIT} and an exception
! * is thrown from {@code stringToValue}, the
! * {@code AbstractFormatterFactory} will not be queried when focus is
* lost or gained.
* <p>
! * {@code JFormattedTextField.AbstractFormatter}
* is also responsible for determining when values are committed to
! * the {@code JFormattedTextField}. Some
! * {@code 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 {@code JFormattedTextField.AbstractFormatter}
! * by way of invoking {@code commitEdit}. {@code commitEdit} will
* be invoked whenever return is pressed in the
! * {@code JFormattedTextField}.
* <p>
! * If an {@code AbstractFormatterFactory} has not been explicitly
! * set, one will be set based on the {@code Class} of the value type after
! * {@code setValue} has been invoked (assuming value is non-null).
* For example, in the following code an appropriate
! * {@code AbstractFormatterFactory} and {@code AbstractFormatter}
* will be created to handle formatting of numbers:
* <pre>
* JFormattedTextField tf = new JFormattedTextField();
* tf.setValue(100);
* </pre>
* <p>
! * <strong>Warning:</strong> As the {@code AbstractFormatter} will
! * typically install a {@code DocumentFilter} on the
! * {@code Document}, and a {@code NavigationFilter} on the
! * {@code JFormattedTextField} you should not install your own. If you do,
* you are likely to see odd behavior in that the editing policy of the
! * {@code AbstractFormatter} will not be enforced.
* <p>
* <strong>Warning:</strong> Swing is not thread safe. For more
* information see <a
* href="package-summary.html#threading">Swing's Threading
* Policy</a>.
*** 169,179 ****
* 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 <code>java.beans</code> package.
* Please see {@link java.beans.XMLEncoder}.
*
* @since 1.4
*/
@SuppressWarnings("serial") // Same-version serialization only
--- 169,179 ----
* 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 {@code java.beans} package.
* Please see {@link java.beans.XMLEncoder}.
*
* @since 1.4
*/
@SuppressWarnings("serial") // Same-version serialization only
*** 182,213 ****
private static final Action[] defaultActions =
{ new CommitAction(), new CancelAction() };
/**
* Constant identifying that when focus is lost,
! * <code>commitEdit</code> should be invoked. If in committing the
! * new value a <code>ParseException</code> is thrown, the invalid
* value will remain.
*
* @see #setFocusLostBehavior
*/
public static final int COMMIT = 0;
/**
* Constant identifying that when focus is lost,
! * <code>commitEdit</code> should be invoked. If in committing the new
! * value a <code>ParseException</code> is thrown, the value will be
* reverted.
*
* @see #setFocusLostBehavior
*/
public static final int COMMIT_OR_REVERT = 1;
/**
* Constant identifying that when focus is lost, editing value should
* be reverted to current value set on the
! * <code>JFormattedTextField</code>.
*
* @see #setFocusLostBehavior
*/
public static final int REVERT = 2;
--- 182,213 ----
private static final Action[] defaultActions =
{ new CommitAction(), new CancelAction() };
/**
* Constant identifying that when focus is lost,
! * {@code commitEdit} should be invoked. If in committing the
! * new value a {@code ParseException} is thrown, the invalid
* value will remain.
*
* @see #setFocusLostBehavior
*/
public static final int COMMIT = 0;
/**
* Constant identifying that when focus is lost,
! * {@code commitEdit} should be invoked. If in committing the new
! * value a {@code ParseException} is thrown, the value will be
* reverted.
*
* @see #setFocusLostBehavior
*/
public static final int COMMIT_OR_REVERT = 1;
/**
* Constant identifying that when focus is lost, editing value should
* be reverted to current value set on the
! * {@code JFormattedTextField}.
*
* @see #setFocusLostBehavior
*/
public static final int REVERT = 2;
*** 265,337 ****
*/
private FocusLostHandler focusLostHandler;
/**
! * Creates a <code>JFormattedTextField</code> with no
! * <code>AbstractFormatterFactory</code>. Use <code>setMask</code> or
! * <code>setFormatterFactory</code> to configure the
! * <code>JFormattedTextField</code> to edit a particular type of
* value.
*/
public JFormattedTextField() {
super();
enableEvents(AWTEvent.FOCUS_EVENT_MASK);
setFocusLostBehavior(COMMIT_OR_REVERT);
}
/**
* Creates a JFormattedTextField with the specified value. This will
! * create an <code>AbstractFormatterFactory</code> based on the
! * type of <code>value</code>.
*
* @param value Initial value for the JFormattedTextField
*/
public JFormattedTextField(Object value) {
this();
setValue(value);
}
/**
! * Creates a <code>JFormattedTextField</code>. <code>format</code> is
! * wrapped in an appropriate <code>AbstractFormatter</code> which is
! * then wrapped in an <code>AbstractFormatterFactory</code>.
*
* @param format Format used to look up an AbstractFormatter
*/
public JFormattedTextField(java.text.Format format) {
this();
setFormatterFactory(getDefaultFormatterFactory(format));
}
/**
! * Creates a <code>JFormattedTextField</code> with the specified
! * <code>AbstractFormatter</code>. The <code>AbstractFormatter</code>
! * is placed in an <code>AbstractFormatterFactory</code>.
*
* @param formatter AbstractFormatter to use for formatting.
*/
public JFormattedTextField(AbstractFormatter formatter) {
this(new DefaultFormatterFactory(formatter));
}
/**
! * Creates a <code>JFormattedTextField</code> with the specified
! * <code>AbstractFormatterFactory</code>.
*
* @param factory AbstractFormatterFactory used for formatting.
*/
public JFormattedTextField(AbstractFormatterFactory factory) {
this();
setFormatterFactory(factory);
}
/**
! * Creates a <code>JFormattedTextField</code> with the specified
! * <code>AbstractFormatterFactory</code> and initial value.
*
! * @param factory <code>AbstractFormatterFactory</code> used for
* formatting.
* @param currentValue Initial value to use
*/
public JFormattedTextField(AbstractFormatterFactory factory,
Object currentValue) {
--- 265,337 ----
*/
private FocusLostHandler focusLostHandler;
/**
! * Creates a {@code JFormattedTextField} with no
! * {@code AbstractFormatterFactory}. Use {@code setMask} or
! * {@code setFormatterFactory} to configure the
! * {@code JFormattedTextField} to edit a particular type of
* value.
*/
public JFormattedTextField() {
super();
enableEvents(AWTEvent.FOCUS_EVENT_MASK);
setFocusLostBehavior(COMMIT_OR_REVERT);
}
/**
* Creates a JFormattedTextField with the specified value. This will
! * create an {@code AbstractFormatterFactory} based on the
! * type of {@code value}.
*
* @param value Initial value for the JFormattedTextField
*/
public JFormattedTextField(Object value) {
this();
setValue(value);
}
/**
! * Creates a {@code JFormattedTextField}. {@code format} is
! * wrapped in an appropriate {@code AbstractFormatter} which is
! * then wrapped in an {@code AbstractFormatterFactory}.
*
* @param format Format used to look up an AbstractFormatter
*/
public JFormattedTextField(java.text.Format format) {
this();
setFormatterFactory(getDefaultFormatterFactory(format));
}
/**
! * Creates a {@code JFormattedTextField} with the specified
! * {@code AbstractFormatter}. The {@code AbstractFormatter}
! * is placed in an {@code AbstractFormatterFactory}.
*
* @param formatter AbstractFormatter to use for formatting.
*/
public JFormattedTextField(AbstractFormatter formatter) {
this(new DefaultFormatterFactory(formatter));
}
/**
! * Creates a {@code JFormattedTextField} with the specified
! * {@code AbstractFormatterFactory}.
*
* @param factory AbstractFormatterFactory used for formatting.
*/
public JFormattedTextField(AbstractFormatterFactory factory) {
this();
setFormatterFactory(factory);
}
/**
! * Creates a {@code JFormattedTextField} with the specified
! * {@code AbstractFormatterFactory} and initial value.
*
! * @param factory {@code AbstractFormatterFactory} used for
* formatting.
* @param currentValue Initial value to use
*/
public JFormattedTextField(AbstractFormatterFactory factory,
Object currentValue) {
*** 339,360 ****
setFormatterFactory(factory);
}
/**
* Sets the behavior when focus is lost. This will be one of
! * <code>JFormattedTextField.COMMIT_OR_REVERT</code>,
! * <code>JFormattedTextField.REVERT</code>,
! * <code>JFormattedTextField.COMMIT</code> or
! * <code>JFormattedTextField.PERSIST</code>
! * Note that some <code>AbstractFormatter</code>s may push changes as
* they occur, so that the value of this will have no effect.
* <p>
! * This will throw an <code>IllegalArgumentException</code> if the object
* passed in is not one of the afore mentioned values.
* <p>
* The default value of this property is
! * <code>JFormattedTextField.COMMIT_OR_REVERT</code>.
*
* @param behavior Identifies behavior when focus is lost
* @throws IllegalArgumentException if behavior is not one of the known
* values
* @beaninfo
--- 339,360 ----
setFormatterFactory(factory);
}
/**
* Sets the behavior when focus is lost. This will be one of
! * {@code JFormattedTextField.COMMIT_OR_REVERT},
! * {@code JFormattedTextField.REVERT},
! * {@code JFormattedTextField.COMMIT} or
! * {@code JFormattedTextField.PERSIST}
! * Note that some {@code AbstractFormatter}s may push changes as
* they occur, so that the value of this will have no effect.
* <p>
! * This will throw an {@code IllegalArgumentException} if the object
* passed in is not one of the afore mentioned values.
* <p>
* The default value of this property is
! * {@code JFormattedTextField.COMMIT_OR_REVERT}.
*
* @param behavior Identifies behavior when focus is lost
* @throws IllegalArgumentException if behavior is not one of the known
* values
* @beaninfo
*** 372,414 ****
focusLostBehavior = behavior;
}
/**
* Returns the behavior when focus is lost. This will be one of
! * <code>COMMIT_OR_REVERT</code>,
! * <code>COMMIT</code>,
! * <code>REVERT</code> or
! * <code>PERSIST</code>
! * Note that some <code>AbstractFormatter</code>s may push changes as
* they occur, so that the value of this will have no effect.
*
* @return returns behavior when focus is lost
*/
public int getFocusLostBehavior() {
return focusLostBehavior;
}
/**
! * Sets the <code>AbstractFormatterFactory</code>.
! * <code>AbstractFormatterFactory</code> is
! * able to return an instance of <code>AbstractFormatter</code> that is
* used to format a value for display, as well an enforcing an editing
* policy.
* <p>
! * If you have not explicitly set an <code>AbstractFormatterFactory</code>
* by way of this method (or a constructor) an
! * <code>AbstractFormatterFactory</code> and consequently an
! * <code>AbstractFormatter</code> will be used based on the
! * <code>Class</code> of the value. <code>NumberFormatter</code> will
! * be used for <code>Number</code>s, <code>DateFormatter</code> will
! * be used for <code>Dates</code>, otherwise <code>DefaultFormatter</code>
* will be used.
* <p>
* This is a JavaBeans bound property.
*
! * @param tf <code>AbstractFormatterFactory</code> used to lookup
! * instances of <code>AbstractFormatter</code>
* @beaninfo
* bound: true
* attribute: visualUpdate true
* description: AbstractFormatterFactory, responsible for returning an
* AbstractFormatter that can format the current value.
--- 372,414 ----
focusLostBehavior = behavior;
}
/**
* Returns the behavior when focus is lost. This will be one of
! * {@code COMMIT_OR_REVERT},
! * {@code COMMIT},
! * {@code REVERT} or
! * {@code PERSIST}
! * Note that some {@code AbstractFormatter}s may push changes as
* they occur, so that the value of this will have no effect.
*
* @return returns behavior when focus is lost
*/
public int getFocusLostBehavior() {
return focusLostBehavior;
}
/**
! * Sets the {@code AbstractFormatterFactory}.
! * {@code AbstractFormatterFactory} is
! * able to return an instance of {@code AbstractFormatter} that is
* used to format a value for display, as well an enforcing an editing
* policy.
* <p>
! * If you have not explicitly set an {@code AbstractFormatterFactory}
* by way of this method (or a constructor) an
! * {@code AbstractFormatterFactory} and consequently an
! * {@code AbstractFormatter} will be used based on the
! * {@code Class} of the value. {@code NumberFormatter} will
! * be used for {@code Number}s, {@code DateFormatter} will
! * be used for {@code Dates}, otherwise {@code DefaultFormatter}
* will be used.
* <p>
* This is a JavaBeans bound property.
*
! * @param tf {@code AbstractFormatterFactory} used to lookup
! * instances of {@code AbstractFormatter}
* @beaninfo
* bound: true
* attribute: visualUpdate true
* description: AbstractFormatterFactory, responsible for returning an
* AbstractFormatter that can format the current value.
*** 420,450 ****
firePropertyChange("formatterFactory", oldFactory, tf);
setValue(getValue(), true, false);
}
/**
! * Returns the current <code>AbstractFormatterFactory</code>.
*
* @see #setFormatterFactory
! * @return <code>AbstractFormatterFactory</code> used to determine
! * <code>AbstractFormatter</code>s
*/
public AbstractFormatterFactory getFormatterFactory() {
return factory;
}
/**
! * Sets the current <code>AbstractFormatter</code>.
* <p>
* You should not normally invoke this, instead set the
! * <code>AbstractFormatterFactory</code> or set the value.
! * <code>JFormattedTextField</code> will
! * invoke this as the state of the <code>JFormattedTextField</code>
* changes and requires the value to be reset.
! * <code>JFormattedTextField</code> passes in the
! * <code>AbstractFormatter</code> obtained from the
! * <code>AbstractFormatterFactory</code>.
* <p>
* This is a JavaBeans bound property.
*
* @see #setFormatterFactory
* @param format AbstractFormatter to use for formatting
--- 420,450 ----
firePropertyChange("formatterFactory", oldFactory, tf);
setValue(getValue(), true, false);
}
/**
! * Returns the current {@code AbstractFormatterFactory}.
*
* @see #setFormatterFactory
! * @return {@code AbstractFormatterFactory} used to determine
! * {@code AbstractFormatter}s
*/
public AbstractFormatterFactory getFormatterFactory() {
return factory;
}
/**
! * Sets the current {@code AbstractFormatter}.
* <p>
* You should not normally invoke this, instead set the
! * {@code AbstractFormatterFactory} or set the value.
! * {@code JFormattedTextField} will
! * invoke this as the state of the {@code JFormattedTextField}
* changes and requires the value to be reset.
! * {@code JFormattedTextField} passes in the
! * {@code AbstractFormatter} obtained from the
! * {@code AbstractFormatterFactory}.
* <p>
* This is a JavaBeans bound property.
*
* @see #setFormatterFactory
* @param format AbstractFormatter to use for formatting
*** 467,491 ****
setEdited(false);
firePropertyChange("textFormatter", oldFormat, format);
}
/**
! * Returns the <code>AbstractFormatter</code> that is used to format and
* parse the current value.
*
* @return AbstractFormatter used for formatting
*/
public AbstractFormatter getFormatter() {
return format;
}
/**
* Sets the value that will be formatted by an
! * <code>AbstractFormatter</code> obtained from the current
! * <code>AbstractFormatterFactory</code>. If no
! * <code>AbstractFormatterFactory</code> has been specified, this will
! * attempt to create one based on the type of <code>value</code>.
* <p>
* The default value of this property is null.
* <p>
* This is a JavaBeans bound property.
*
--- 467,491 ----
setEdited(false);
firePropertyChange("textFormatter", oldFormat, format);
}
/**
! * Returns the {@code AbstractFormatter} that is used to format and
* parse the current value.
*
* @return AbstractFormatter used for formatting
*/
public AbstractFormatter getFormatter() {
return format;
}
/**
* Sets the value that will be formatted by an
! * {@code AbstractFormatter} obtained from the current
! * {@code AbstractFormatterFactory}. If no
! * {@code AbstractFormatterFactory} has been specified, this will
! * attempt to create one based on the type of {@code value}.
* <p>
* The default value of this property is null.
* <p>
* This is a JavaBeans bound property.
*
*** 502,528 ****
setValue(value, true, true);
}
/**
* Returns the last valid value. Based on the editing policy of
! * the <code>AbstractFormatter</code> this may not return the current
* value. The currently edited value can be obtained by invoking
! * <code>commitEdit</code> followed by <code>getValue</code>.
*
* @return Last valid value
*/
public Object getValue() {
return value;
}
/**
* Forces the current value to be taken from the
! * <code>AbstractFormatter</code> and set as the current value.
* This has no effect if there is no current
! * <code>AbstractFormatter</code> installed.
*
! * @throws ParseException if the <code>AbstractFormatter</code> is not able
* to format the current value
*/
public void commitEdit() throws ParseException {
AbstractFormatter format = getFormatter();
--- 502,528 ----
setValue(value, true, true);
}
/**
* Returns the last valid value. Based on the editing policy of
! * the {@code AbstractFormatter} this may not return the current
* value. The currently edited value can be obtained by invoking
! * {@code commitEdit} followed by {@code getValue}.
*
* @return Last valid value
*/
public Object getValue() {
return value;
}
/**
* Forces the current value to be taken from the
! * {@code AbstractFormatter} and set as the current value.
* This has no effect if there is no current
! * {@code AbstractFormatter} installed.
*
! * @throws ParseException if the {@code AbstractFormatter} is not able
* to format the current value
*/
public void commitEdit() throws ParseException {
AbstractFormatter format = getFormatter();
*** 532,542 ****
}
/**
* Sets the validity of the edit on the receiver. You should not normally
* invoke this. This will be invoked by the
! * <code>AbstractFormatter</code> as the user edits the value.
* <p>
* Not all formatters will allow the component to get into an invalid
* state, and thus this may never be invoked.
* <p>
* Based on the look and feel this may visually change the state of
--- 532,542 ----
}
/**
* Sets the validity of the edit on the receiver. You should not normally
* invoke this. This will be invoked by the
! * {@code AbstractFormatter} as the user edits the value.
* <p>
* Not all formatters will allow the component to get into an invalid
* state, and thus this may never be invoked.
* <p>
* Based on the look and feel this may visually change the state of
*** 557,567 ****
}
}
/**
* Returns true if the current value being edited is valid. The value of
! * this is managed by the current <code>AbstractFormatter</code>, as such
* there is no public setter for it.
*
* @return true if the current value being edited is valid.
*/
public boolean isEditValid() {
--- 557,567 ----
}
}
/**
* Returns true if the current value being edited is valid. The value of
! * this is managed by the current {@code AbstractFormatter}, as such
* there is no public setter for it.
*
* @return true if the current value being edited is valid.
*/
public boolean isEditValid() {
*** 577,590 ****
UIManager.getLookAndFeel().provideErrorFeedback(JFormattedTextField.this);
}
/**
* Processes any input method events, such as
! * <code>InputMethodEvent.INPUT_METHOD_TEXT_CHANGED</code> or
! * <code>InputMethodEvent.CARET_POSITION_CHANGED</code>.
*
! * @param e the <code>InputMethodEvent</code>
* @see InputMethodEvent
*/
protected void processInputMethodEvent(InputMethodEvent e) {
AttributedCharacterIterator text = e.getText();
int commitCount = e.getCommittedCharacterCount();
--- 577,590 ----
UIManager.getLookAndFeel().provideErrorFeedback(JFormattedTextField.this);
}
/**
* Processes any input method events, such as
! * {@code InputMethodEvent.INPUT_METHOD_TEXT_CHANGED} or
! * {@code InputMethodEvent.CARET_POSITION_CHANGED}.
*
! * @param e the {@code InputMethodEvent}
* @see InputMethodEvent
*/
protected void processInputMethodEvent(InputMethodEvent e) {
AttributedCharacterIterator text = e.getText();
int commitCount = e.getCommittedCharacterCount();
*** 601,614 ****
super.processInputMethodEvent(e);
}
/**
* Processes any focus events, such as
! * <code>FocusEvent.FOCUS_GAINED</code> or
! * <code>FocusEvent.FOCUS_LOST</code>.
*
! * @param e the <code>FocusEvent</code>
* @see FocusEvent
*/
protected void processFocusEvent(FocusEvent e) {
super.processFocusEvent(e);
--- 601,614 ----
super.processInputMethodEvent(e);
}
/**
* Processes any focus events, such as
! * {@code FocusEvent.FOCUS_GAINED} or
! * {@code FocusEvent.FOCUS_LOST}.
*
! * @param e the {@code FocusEvent}
* @see FocusEvent
*/
protected void processFocusEvent(FocusEvent e) {
super.processFocusEvent(e);
*** 728,738 ****
}
}
/**
* Resets the Actions that come from the TextFormatter to
! * <code>actions</code>.
*/
private void setFormatterActions(Action[] actions) {
if (actions == null) {
if (textFormatterActionMap != null) {
textFormatterActionMap.clear();
--- 728,738 ----
}
}
/**
* Resets the Actions that come from the TextFormatter to
! * {@code actions}.
*/
private void setFormatterActions(Action[] actions) {
if (actions == null) {
if (textFormatterActionMap != null) {
textFormatterActionMap.clear();
*** 764,777 ****
}
}
}
/**
! * Does the setting of the value. If <code>createFormat</code> is true,
! * this will also obtain a new <code>AbstractFormatter</code> from the
* current factory. The property change event will be fired if
! * <code>firePC</code> is true.
*/
private void setValue(Object value, boolean createFormat, boolean firePC) {
Object oldValue = this.value;
this.value = value;
--- 764,777 ----
}
}
}
/**
! * Does the setting of the value. If {@code createFormat} is true,
! * this will also obtain a new {@code AbstractFormatter} from the
* current factory. The property change event will be fired if
! * {@code firePC} is true.
*/
private void setValue(Object value, boolean createFormat, boolean firePC) {
Object oldValue = this.value;
this.value = value;
*** 847,871 ****
return new DefaultFormatterFactory(new DefaultFormatter());
}
/**
! * Instances of <code>AbstractFormatterFactory</code> are used by
! * <code>JFormattedTextField</code> to obtain instances of
! * <code>AbstractFormatter</code> which in turn are used to format values.
! * <code>AbstractFormatterFactory</code> can return different
! * <code>AbstractFormatter</code>s based on the state of the
! * <code>JFormattedTextField</code>, perhaps returning different
! * <code>AbstractFormatter</code>s when the
! * <code>JFormattedTextField</code> has focus vs when it
* doesn't have focus.
* @since 1.4
*/
public abstract static class AbstractFormatterFactory {
/**
! * Returns an <code>AbstractFormatter</code> that can handle formatting
! * of the passed in <code>JFormattedTextField</code>.
*
* @param tf JFormattedTextField requesting AbstractFormatter
* @return AbstractFormatter to handle formatting duties, a null
* return value implies the JFormattedTextField should behave
* like a normal JTextField
--- 847,871 ----
return new DefaultFormatterFactory(new DefaultFormatter());
}
/**
! * Instances of {@code AbstractFormatterFactory} are used by
! * {@code JFormattedTextField} to obtain instances of
! * {@code AbstractFormatter} which in turn are used to format values.
! * {@code AbstractFormatterFactory} can return different
! * {@code AbstractFormatter}s based on the state of the
! * {@code JFormattedTextField}, perhaps returning different
! * {@code AbstractFormatter}s when the
! * {@code JFormattedTextField} has focus vs when it
* doesn't have focus.
* @since 1.4
*/
public abstract static class AbstractFormatterFactory {
/**
! * Returns an {@code AbstractFormatter} that can handle formatting
! * of the passed in {@code JFormattedTextField}.
*
* @param tf JFormattedTextField requesting AbstractFormatter
* @return AbstractFormatter to handle formatting duties, a null
* return value implies the JFormattedTextField should behave
* like a normal JTextField
*** 873,942 ****
public abstract AbstractFormatter getFormatter(JFormattedTextField tf);
}
/**
! * Instances of <code>AbstractFormatter</code> are used by
! * <code>JFormattedTextField</code> to handle the conversion both
* from an Object to a String, and back from a String to an Object.
! * <code>AbstractFormatter</code>s can also enforce editing policies,
* or navigation policies, or manipulate the
! * <code>JFormattedTextField</code> in any way it sees fit to
* enforce the desired policy.
* <p>
! * An <code>AbstractFormatter</code> can only be active in
! * one <code>JFormattedTextField</code> at a time.
! * <code>JFormattedTextField</code> invokes
! * <code>install</code> when it is ready to use it followed
! * by <code>uninstall</code> when done. Subclasses
* that wish to install additional state should override
! * <code>install</code> and message super appropriately.
* <p>
* Subclasses must override the conversion methods
! * <code>stringToValue</code> and <code>valueToString</code>. Optionally
! * they can override <code>getActions</code>,
! * <code>getNavigationFilter</code> and <code>getDocumentFilter</code>
! * to restrict the <code>JFormattedTextField</code> in a particular
* way.
* <p>
! * Subclasses that allow the <code>JFormattedTextField</code> to be in
! * a temporarily invalid state should invoke <code>setEditValid</code>
* at the appropriate times.
* @since 1.4
*/
public abstract static class AbstractFormatter implements Serializable {
private JFormattedTextField ftf;
/**
! * Installs the <code>AbstractFormatter</code> onto a particular
! * <code>JFormattedTextField</code>.
! * This will invoke <code>valueToString</code> to convert the
! * current value from the <code>JFormattedTextField</code> to
! * a String. This will then install the <code>Action</code>s from
! * <code>getActions</code>, the <code>DocumentFilter</code>
! * returned from <code>getDocumentFilter</code> and the
! * <code>NavigationFilter</code> returned from
! * <code>getNavigationFilter</code> onto the
! * <code>JFormattedTextField</code>.
* <p>
* Subclasses will typically only need to override this if they
* wish to install additional listeners on the
! * <code>JFormattedTextField</code>.
* <p>
! * If there is a <code>ParseException</code> in converting the
* current value to a String, this will set the text to an empty
! * String, and mark the <code>JFormattedTextField</code> as being
* in an invalid state.
* <p>
* While this is a public method, this is typically only useful
! * for subclassers of <code>JFormattedTextField</code>.
! * <code>JFormattedTextField</code> will invoke this method at
* the appropriate times when the value changes, or its internal
* state changes. You will only need to invoke this yourself if
! * you are subclassing <code>JFormattedTextField</code> and
! * installing/uninstalling <code>AbstractFormatter</code> at a
! * different time than <code>JFormattedTextField</code> does.
*
* @param ftf JFormattedTextField to format for, may be null indicating
* uninstall from current JFormattedTextField.
*/
public void install(JFormattedTextField ftf) {
--- 873,942 ----
public abstract AbstractFormatter getFormatter(JFormattedTextField tf);
}
/**
! * Instances of {@code AbstractFormatter} are used by
! * {@code JFormattedTextField} to handle the conversion both
* from an Object to a String, and back from a String to an Object.
! * {@code AbstractFormatter}s can also enforce editing policies,
* or navigation policies, or manipulate the
! * {@code JFormattedTextField} in any way it sees fit to
* enforce the desired policy.
* <p>
! * An {@code AbstractFormatter} can only be active in
! * one {@code JFormattedTextField} at a time.
! * {@code JFormattedTextField} invokes
! * {@code install} when it is ready to use it followed
! * by {@code uninstall} when done. Subclasses
* that wish to install additional state should override
! * {@code install} and message super appropriately.
* <p>
* Subclasses must override the conversion methods
! * {@code stringToValue} and {@code valueToString}. Optionally
! * they can override {@code getActions},
! * {@code getNavigationFilter} and {@code getDocumentFilter}
! * to restrict the {@code JFormattedTextField} in a particular
* way.
* <p>
! * Subclasses that allow the {@code JFormattedTextField} to be in
! * a temporarily invalid state should invoke {@code setEditValid}
* at the appropriate times.
* @since 1.4
*/
public abstract static class AbstractFormatter implements Serializable {
private JFormattedTextField ftf;
/**
! * Installs the {@code AbstractFormatter} onto a particular
! * {@code JFormattedTextField}.
! * This will invoke {@code valueToString} to convert the
! * current value from the {@code JFormattedTextField} to
! * a String. This will then install the {@code Action}s from
! * {@code getActions}, the {@code DocumentFilter}
! * returned from {@code getDocumentFilter} and the
! * {@code NavigationFilter} returned from
! * {@code getNavigationFilter} onto the
! * {@code JFormattedTextField}.
* <p>
* Subclasses will typically only need to override this if they
* wish to install additional listeners on the
! * {@code JFormattedTextField}.
* <p>
! * If there is a {@code ParseException} in converting the
* current value to a String, this will set the text to an empty
! * String, and mark the {@code JFormattedTextField} as being
* in an invalid state.
* <p>
* While this is a public method, this is typically only useful
! * for subclassers of {@code JFormattedTextField}.
! * {@code JFormattedTextField} will invoke this method at
* the appropriate times when the value changes, or its internal
* state changes. You will only need to invoke this yourself if
! * you are subclassing {@code JFormattedTextField} and
! * installing/uninstalling {@code AbstractFormatter} at a
! * different time than {@code JFormattedTextField} does.
*
* @param ftf JFormattedTextField to format for, may be null indicating
* uninstall from current JFormattedTextField.
*/
public void install(JFormattedTextField ftf) {
*** 956,1003 ****
ftf.setFormatterActions(getActions());
}
}
/**
! * Uninstalls any state the <code>AbstractFormatter</code> may have
! * installed on the <code>JFormattedTextField</code>. This resets the
! * <code>DocumentFilter</code>, <code>NavigationFilter</code>
! * and additional <code>Action</code>s installed on the
! * <code>JFormattedTextField</code>.
*/
public void uninstall() {
if (this.ftf != null) {
installDocumentFilter(null);
this.ftf.setNavigationFilter(null);
this.ftf.setFormatterActions(null);
}
}
/**
! * Parses <code>text</code> returning an arbitrary Object. Some
* formatters may return null.
*
* @throws ParseException if there is an error in the conversion
* @param text String to convert
* @return Object representation of text
*/
public abstract Object stringToValue(String text) throws
ParseException;
/**
! * Returns the string value to display for <code>value</code>.
*
* @throws ParseException if there is an error in the conversion
* @param value Value to convert
* @return String representation of value
*/
public abstract String valueToString(Object value) throws
ParseException;
/**
! * Returns the current <code>JFormattedTextField</code> the
! * <code>AbstractFormatter</code> is installed on.
*
* @return JFormattedTextField formatting for.
*/
protected JFormattedTextField getFormattedTextField() {
return ftf;
--- 956,1003 ----
ftf.setFormatterActions(getActions());
}
}
/**
! * Uninstalls any state the {@code AbstractFormatter} may have
! * installed on the {@code JFormattedTextField}. This resets the
! * {@code DocumentFilter}, {@code NavigationFilter}
! * and additional {@code Action}s installed on the
! * {@code JFormattedTextField}.
*/
public void uninstall() {
if (this.ftf != null) {
installDocumentFilter(null);
this.ftf.setNavigationFilter(null);
this.ftf.setFormatterActions(null);
}
}
/**
! * Parses {@code text} returning an arbitrary Object. Some
* formatters may return null.
*
* @throws ParseException if there is an error in the conversion
* @param text String to convert
* @return Object representation of text
*/
public abstract Object stringToValue(String text) throws
ParseException;
/**
! * Returns the string value to display for {@code value}.
*
* @throws ParseException if there is an error in the conversion
* @param value Value to convert
* @return String representation of value
*/
public abstract String valueToString(Object value) throws
ParseException;
/**
! * Returns the current {@code JFormattedTextField} the
! * {@code AbstractFormatter} is installed on.
*
* @return JFormattedTextField formatting for.
*/
protected JFormattedTextField getFormattedTextField() {
return ftf;
*** 1014,1026 ****
ftf.invalidEdit();
}
}
/**
! * Invoke this to update the <code>editValid</code> property of the
! * <code>JFormattedTextField</code>. If you an enforce a policy
! * such that the <code>JFormattedTextField</code> is always in a
* valid state, you will never need to invoke this.
*
* @param valid Valid state of the JFormattedTextField
*/
protected void setEditValid(boolean valid) {
--- 1014,1026 ----
ftf.invalidEdit();
}
}
/**
! * Invoke this to update the {@code editValid} property of the
! * {@code JFormattedTextField}. If you an enforce a policy
! * such that the {@code JFormattedTextField} is always in a
* valid state, you will never need to invoke this.
*
* @param valid Valid state of the JFormattedTextField
*/
protected void setEditValid(boolean valid) {
*** 1031,1076 ****
}
}
/**
* Subclass and override if you wish to provide a custom set of
! * <code>Action</code>s. <code>install</code> will install these
! * on the <code>JFormattedTextField</code>'s <code>ActionMap</code>.
*
* @return Array of Actions to install on JFormattedTextField
*/
protected Action[] getActions() {
return null;
}
/**
* Subclass and override if you wish to provide a
! * <code>DocumentFilter</code> to restrict what can be input.
! * <code>install</code> will install the returned value onto
! * the <code>JFormattedTextField</code>.
*
* @return DocumentFilter to restrict edits
*/
protected DocumentFilter getDocumentFilter() {
return null;
}
/**
* Subclass and override if you wish to provide a filter to restrict
* where the user can navigate to.
! * <code>install</code> will install the returned value onto
! * the <code>JFormattedTextField</code>.
*
* @return NavigationFilter to restrict navigation
*/
protected NavigationFilter getNavigationFilter() {
return null;
}
/**
! * Clones the <code>AbstractFormatter</code>. The returned instance
! * is not associated with a <code>JFormattedTextField</code>.
*
* @return Copy of the AbstractFormatter
*/
protected Object clone() throws CloneNotSupportedException {
AbstractFormatter formatter = (AbstractFormatter)super.clone();
--- 1031,1076 ----
}
}
/**
* Subclass and override if you wish to provide a custom set of
! * {@code Action}s. {@code install} will install these
! * on the {@code JFormattedTextField}'s {@code ActionMap}.
*
* @return Array of Actions to install on JFormattedTextField
*/
protected Action[] getActions() {
return null;
}
/**
* Subclass and override if you wish to provide a
! * {@code DocumentFilter} to restrict what can be input.
! * {@code install} will install the returned value onto
! * the {@code JFormattedTextField}.
*
* @return DocumentFilter to restrict edits
*/
protected DocumentFilter getDocumentFilter() {
return null;
}
/**
* Subclass and override if you wish to provide a filter to restrict
* where the user can navigate to.
! * {@code install} will install the returned value onto
! * the {@code JFormattedTextField}.
*
* @return NavigationFilter to restrict navigation
*/
protected NavigationFilter getNavigationFilter() {
return null;
}
/**
! * Clones the {@code AbstractFormatter}. The returned instance
! * is not associated with a {@code JFormattedTextField}.
*
* @return Copy of the AbstractFormatter
*/
protected Object clone() throws CloneNotSupportedException {
AbstractFormatter formatter = (AbstractFormatter)super.clone();
*** 1078,1089 ****
formatter.ftf = null;
return formatter;
}
/**
! * Installs the <code>DocumentFilter</code> <code>filter</code>
! * onto the current <code>JFormattedTextField</code>.
*
* @param filter DocumentFilter to install on the Document.
*/
private void installDocumentFilter(DocumentFilter filter) {
JFormattedTextField ftf = getFormattedTextField();
--- 1078,1089 ----
formatter.ftf = null;
return formatter;
}
/**
! * Installs the {@code DocumentFilter filter}
! * onto the current {@code JFormattedTextField}.
*
* @param filter DocumentFilter to install on the Document.
*/
private void installDocumentFilter(DocumentFilter filter) {
JFormattedTextField ftf = getFormattedTextField();
*** 1100,1111 ****
}
/**
* Used to commit the edit. This extends JTextField.NotifyAction
! * so that <code>isEnabled</code> is true while a JFormattedTextField
! * has focus, and extends <code>actionPerformed</code> to invoke
* commitEdit.
*/
static class CommitAction extends JTextField.NotifyAction {
public void actionPerformed(ActionEvent e) {
JTextComponent target = getFocusedComponent();
--- 1100,1111 ----
}
/**
* Used to commit the edit. This extends JTextField.NotifyAction
! * so that {@code isEnabled} is true while a JFormattedTextField
! * has focus, and extends {@code actionPerformed} to invoke
* commitEdit.
*/
static class CommitAction extends JTextField.NotifyAction {
public void actionPerformed(ActionEvent e) {
JTextComponent target = getFocusedComponent();
*** 1138,1148 ****
}
/**
* CancelAction will reset the value in the JFormattedTextField when
! * <code>actionPerformed</code> is invoked. It will only be
* enabled if the focused component is an instance of
* JFormattedTextField.
*/
private static class CancelAction extends TextAction {
public CancelAction() {
--- 1138,1148 ----
}
/**
* CancelAction will reset the value in the JFormattedTextField when
! * {@code actionPerformed} is invoked. It will only be
* enabled if the focused component is an instance of
* JFormattedTextField.
*/
private static class CancelAction extends TextAction {
public CancelAction() {
< prev index next >