org.itsnat.comp.text
Interface ItsNatFormattedTextField

All Superinterfaces:

ItsNatComponent, ItsNatElementComponent, ItsNatTextComponent, ItsNatTextField, ItsNatUserData

All Known Subinterfaces:

ItsNatHTMLInputTextFormatted

public interface ItsNatFormattedTextField
extends ItsNatTextField

Is the base interface of text based components which text is rendered/edited as a single line and following a format.

This component type is inspired in javax.swing.JFormattedTextField. Some documentation is borrowed from Swing.

This component maintains two values, the value returned by ItsNatTextComponent.getText() is the value in the visual control rendering the component, and the value returned by getValue(). The last one is restricted to the scope defined by getItsNatFormatter().

When a new value on the visual control is set as the component value calling commitEdit() first is validated/converted calling ItsNatFormattedTextField.ItsNatFormatter.stringToValue(String,ItsNatFormattedTextField).

Any change to the internal value is notified with a "value" property change event and may be vetoed (see setValue(Object)).

Author:

Jose Maria Arranz Santamaria

Nested Class Summary

static interface	ItsNatFormattedTextField.ItsNatFormatter Defines an ItsNat formatter.
static interface	ItsNatFormattedTextField.ItsNatFormatterFactory Defines an ItsNat formatter factory.

Field Summary

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 component.

Method Summary

void	commitEdit() Forces the current value to be taken from the control and set as the current value converted first using the current ItsNatFormattedTextField.ItsNatFormatter.
ItsNatFormattedTextField.ItsNatFormatterFactory	createDefaultItsNatFormatterFactory() Creates a new default ItsNat formatter factory.
ItsNatFormattedTextField.ItsNatFormatter	createItsNatFormatter(java.text.Format format) Creates an ItsNat formatter wrapping the specified java.text.Format.
int	getFocusLostBehavior() Returns the behavior when focus is lost.
ItsNatFormattedTextField.ItsNatFormatter	getItsNatFormatter() This method is called when the component needs to convert an Object value from/to String.
ItsNatFormattedTextField.ItsNatFormatterFactory	getItsNatFormatterFactory() Returns the current ItsNat formatter factory.
java.lang.Object	getValue() Returns the last valid value.
boolean	hasFocus() Informs whether this component has the focus.
boolean	isEdited() Informs whether visual control content has changed and component value is still not modified.
boolean	isEditValid() Returns true if the current value being edited is valid.
void	setFocusLostBehavior(int behavior) Sets the behavior when focus is lost.
void	setFormat(java.text.Format format) Defines a default ItsNat formatter based on the specified java.text.Format.
void	setItsNatFormatter(ItsNatFormattedTextField.ItsNatFormatter formatter) Sets the default ItsNat formatter.
void	setItsNatFormatterFactory(ItsNatFormattedTextField.ItsNatFormatterFactory tf) Sets the current ItsNat formatter factory.
void	setValue(java.lang.Object value) Sets the value that will be formatted to the control by an ItsNatFormattedTextField.ItsNatFormatter obtained from the current ItsNatFormattedTextField.ItsNatFormatterFactory.

Methods inherited from interface org.itsnat.comp.text.ItsNatTextField

getItsNatTextFieldUI

Methods inherited from interface org.itsnat.comp.text.ItsNatTextComponent

appendString, createDefaultDocument, getDocument, getItsNatTextComponentUI, getText, getText, insertString, replaceString, setDocument, setText

Methods inherited from interface org.itsnat.comp.ItsNatElementComponent

getElement, getItsNatElementComponentUI

Methods inherited from interface org.itsnat.comp.ItsNatComponent

addEventListener, addEventListener, addEventListener, addEventListener, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, disableEventListener, disableEventListener, dispose, enableEventListener, enableEventListener, getArtifact, getArtifact, getItsNatComponentManager, getItsNatComponentUI, getItsNatDocument, getNode, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, isDisposed, isEnabled, registerArtifact, removeArtifact, removeEventListener, removeEventListener, removeEventListener, removeEventListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, setEnabled, setEventListenerParams, setEventListenerParams, setNode

Methods inherited from interface org.itsnat.core.ItsNatUserData

containsUserValueName, getUserValue, getUserValueNames, removeUserValue, setUserValue

Field Detail

COMMIT

static final int COMMIT

Constant identifying that when focus is lost, commitEdit should be invoked. If in committing the new value a ParseException or PropertyVetoException is thrown, the invalid value will remain.

See Also:

setFocusLostBehavior(int), Constant Field Values

COMMIT_OR_REVERT

static final int COMMIT_OR_REVERT

Constant identifying that when focus is lost, commitEdit should be invoked. If in commiting the new value a ParseException or PropertyVetoException is thrown, the value will be reverted.

See Also:

setFocusLostBehavior(int), Constant Field Values

REVERT

static final int REVERT

Constant identifying that when focus is lost, editing value should be reverted to current value set on the component.

See Also:

setFocusLostBehavior(int), Constant Field Values

PERSIST

static final int PERSIST

Constant identifying that when focus is lost, the edited value should be left.

See Also:

setFocusLostBehavior(int), Constant Field Values

Method Detail

getFocusLostBehavior

int getFocusLostBehavior()

Returns the behavior when focus is lost. This will be one of COMMIT_OR_REVERT, COMMIT, REVERT or PERSIST Note that some ItsNatFormattedTextField.ItsNatFormatters may push changes to the control value.

Returns:

returns behavior when focus is lost. COMMIT_OR_REVERT by default

See Also:

setFocusLostBehavior(int)

setFocusLostBehavior

void setFocusLostBehavior(int behavior)

Sets the behavior when focus is lost. This will be one of COMMIT_OR_REVERT, COMMIT, REVERT or PERSIST

Parameters:

behavior - identifies behavior when focus is lost

See Also:

getFocusLostBehavior()

getValue

java.lang.Object getValue()

Returns the last valid value. Based on the editing policy of the ItsNatFormattedTextField.ItsNatFormatter this may not return the current edited value. The currently edited value can be obtained by invoking commitEdit() followed by getValue().

Returns:

last valid value. The default value is null.

setValue

void setValue(java.lang.Object value)
              throws java.beans.PropertyVetoException

Sets the value that will be formatted to the control by an ItsNatFormattedTextField.ItsNatFormatter obtained from the current ItsNatFormattedTextField.ItsNatFormatterFactory. If no ItsNatFormattedTextField.ItsNatFormatterFactory has been specified, this will attempt to create one based on the type of value.

This new value is "voted" before is set firing a java.beans.PropertyChangeEvent event, with name "value", sent to the listeners registered with ItsNatComponent.addVetoableChangeListener(VetoableChangeListener) if some listener does a "veto" (throws a java.beans.PropertyVetoException) the new value is not set. If finally set the PropertyChangeEvent event is sent to the listeners registered with ItsNatComponent.addPropertyChangeListener(java.beans.PropertyChangeListener) or ItsNatComponent.addPropertyChangeListener(String,java.beans.PropertyChangeListener) with property name "value".

Parameters:

value - value to display (and may be edit).

Throws:

java.beans.PropertyVetoException - if the new value was vetoed.

commitEdit

void commitEdit()
                throws java.text.ParseException,
                       java.beans.PropertyVetoException

Forces the current value to be taken from the control and set as the current value converted first using the current ItsNatFormattedTextField.ItsNatFormatter.

Throws:

java.text.ParseException - if the ItsNatFormattedTextField.ItsNatFormatter is not able to format the current control value

java.beans.PropertyVetoException - if the new value was vetoed.

isEdited

boolean isEdited()

Informs whether visual control content has changed and component value is still not modified.

Returns:

if visual value has changed and component value not.

isEditValid

boolean isEditValid()

Returns true if the current value being edited is valid.

Returns:

true if the current value being edited is valid.

hasFocus

boolean hasFocus()

Informs whether this component has the focus.

Returned value is only valid if this component processes "focus" and "blur" events.

Returns:

true if this component has the focus.

createDefaultItsNatFormatterFactory

ItsNatFormattedTextField.ItsNatFormatterFactory createDefaultItsNatFormatterFactory()

Creates a new default ItsNat formatter factory.

Current implementation is an ItsNatFormatterFactoryDefault.

Returns:

a default formatter factory instance.

getItsNatFormatterFactory

ItsNatFormattedTextField.ItsNatFormatterFactory getItsNatFormatterFactory()

Returns the current ItsNat formatter factory.

By default ItsNat provides a default factory created with createDefaultItsNatFormatterFactory().

Returns:

the current factory. May be null.

See Also:

setItsNatFormatterFactory(ItsNatFormatterFactory)

setItsNatFormatterFactory

void setItsNatFormatterFactory(ItsNatFormattedTextField.ItsNatFormatterFactory tf)

Sets the current ItsNat formatter factory.

Parameters:

tf - the new formatter factory. May be null.

getItsNatFormatter

ItsNatFormattedTextField.ItsNatFormatter getItsNatFormatter()

This method is called when the component needs to convert an Object value from/to String.

If a formatter was defined explicitly with a call to setItsNatFormatter(ItsNatFormatter) this method returns this formatter, else returns the formatter of the default formatter factory (getItsNatFormatterFactory() calling ItsNatFormattedTextField.ItsNatFormatterFactory.getItsNatFormatter(ItsNatFormattedTextField), if no factory is defined or the factory has not an appropriated formatter, then the component tries to build an appropriated formatter to the current value (getValue()).

Returns:

the selected formatter.

setItsNatFormatter

void setItsNatFormatter(ItsNatFormattedTextField.ItsNatFormatter formatter)

Sets the default ItsNat formatter.

Parameters:

formatter - the default formatter. May be null (the factory will be used).

setFormat

void setFormat(java.text.Format format)

Defines a default ItsNat formatter based on the specified java.text.Format.

The method createItsNatFormatter(java.text.Format) is called to create an ItsNat formatter wrapping this format. The new ItsNat formatter is set calling setItsNatFormatter(ItsNatFormatter).

Parameters:

format - the java.text.Format object to set as the default formatter.

createItsNatFormatter

ItsNatFormattedTextField.ItsNatFormatter createItsNatFormatter(java.text.Format format)

Creates an ItsNat formatter wrapping the specified java.text.Format.

Current implementation uses Format.parseObject(String) and Format.format(Object) to convert string and values.

Parameters:

format - the java.text.Format to wrap.

Returns:

a new ItsNat formatter wrapping the specified format.