com.vaadin.ui
Class AbstractField<T>

java.lang.Object
  com.vaadin.terminal.AbstractClientConnector
      com.vaadin.ui.AbstractComponent
          com.vaadin.ui.AbstractField<T>

All Implemented Interfaces:

Buffered, BufferedValidatable, Property<T>, Property.Editor, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, Action.ShortcutNotifier, MethodEventSource, Connector, ClientConnector, RpcTarget, Sizeable, Component, Component.Focusable, Field<T>, Serializable

Direct Known Subclasses:

AbstractSelect, AbstractTextField, CheckBox, CustomField, DateField, Form, ProgressIndicator, RichTextArea, Slider

public abstract class AbstractField<T>
extends AbstractComponent
implements Field<T>, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Action.ShortcutNotifier

Abstract field component for implementing buffered property editors. The field may hold an internal value, or it may be connected to any data source that implements the Propertyinterface. AbstractField implements that interface itself, too, so accessing the Property value represented by it is straightforward.

AbstractField also provides the Buffered interface for buffering the data source value. By default the Field is in write through-mode and setWriteThrough(boolean)should be called to enable buffering.

The class also supports validators to make sure the value contained in the field is valid.

Since:

3.0

Version:

7.0.0.alpha3

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary

static class	AbstractField.FocusShortcut A ready-made ShortcutListener that focuses the given Focusable (usually a Field) when the keyboard shortcut is invoked.
static class	AbstractField.ReadOnlyStatusChangeEvent An Event object specifying the Property whose read-only status has changed.

Nested classes/interfaces inherited from class com.vaadin.ui.AbstractComponent

AbstractComponent.ComponentErrorEvent, AbstractComponent.ComponentErrorHandler

Nested classes/interfaces inherited from interface com.vaadin.ui.Field

Field.ValueChangeEvent

Nested classes/interfaces inherited from interface com.vaadin.data.Buffered

Buffered.SourceException

Nested classes/interfaces inherited from interface com.vaadin.data.Property

Property.Editor, Property.ReadOnlyException, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.Transactional<T>, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.terminal.Sizeable

Sizeable.Unit

Field Summary

Fields inherited from interface com.vaadin.terminal.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

AbstractField()

Method Summary

void	addListener(Property.ReadOnlyStatusChangeListener listener) Registers a new read-only status change listener for this Property.
void	addListener(Property.ValueChangeListener listener) Registers a new value change listener for this Property.
void	addValidator(Validator validator) Adds a new validator for the field's value.
void	attach() Notifies the component that it is connected to an application.
void	commit() Updates all changes since the previous commit to the data source.
void	detach() Notifies the component that it is detached from the application.
void	discard() Discards all changes since last commit.
protected void	fireReadOnlyStatusChange() Emits the read-only status change event.
protected void	fireValueChange(boolean repaintIsNotNeeded) Emits the value change event.
void	focus() Sets the focus for this component if the component is Focusable.
String	getConversionError() Gets the error that is shown if the field value cannot be converted to the data source type.
protected String	getConversionError(Class<?> dataSourceType) Returns the conversion error with {0} replaced by the data source type.
Object	getConvertedValue() Returns the current value (as returned by getValue()) converted to the data source type.
Converter<T,Object>	getConverter() Gets the converter used to convert the property data source value to the field value.
protected Buffered.SourceException	getCurrentBufferedSourceException() Gets the current buffered source exception.
ErrorMessage	getErrorMessage() Error messages shown by the fields are composites of the error message thrown by the superclasses (that is the component error message), validation errors and buffered source errors.
protected T	getInternalValue() Returns the internal field value, which might not match the data source value e.g.
Property	getPropertyDataSource() Gets the current data source of the field, if any.
String	getRequiredError() Gets the error message that is to be displayed if a required field is empty.
AbstractFieldState	getState() Returns the shared state bean with information to be sent from the server to the client.
int	getTabIndex() Gets the tabulator index of the Focusable component.
abstract Class<? extends T>	getType() Returns the type of the Field.
Collection<Validator>	getValidators() Gets the validators of the field.
T	getValue() Gets the current value of the field.
boolean	isBuffered() Checks the buffered mode of this Field.
protected boolean	isEmpty() Is the field empty? In general, "empty" state is same as null.
boolean	isInvalidAllowed() Fields allow invalid values by default.
boolean	isInvalidCommitted() Tests if the invalid data is committed to datasource.
boolean	isModified() Tests if the value stored in the object has been modified since it was last updated from the data source.
boolean	isReadOnly() The abstract field is read only also if the data source is in read only mode.
boolean	isReadThrough() Tests if the object is in read-through mode.
boolean	isRequired() Is this field required.
boolean	isValid() Tests the current value against registered validators if the field is not empty.
boolean	isValidationVisible() Is automatic, visible validation enabled? If automatic validation is enabled, any validators connected to this component are evaluated while painting the component and potential error messages are sent to client.
boolean	isWriteThrough() Tests if the object is in write-through mode.
void	readOnlyStatusChange(Property.ReadOnlyStatusChangeEvent event) React to read only status changes of the property by requesting a repaint.
void	removeAllValidators() Removes all validators from the field.
void	removeListener(Property.ReadOnlyStatusChangeListener listener) Removes a previously registered read-only status change listener.
void	removeListener(Property.ValueChangeListener listener) Removes a previously registered value change listener.
void	removeValidator(Validator validator) Removes the validator from the field.
void	setBuffered(boolean buffered) Sets the buffered mode of this Field.
void	setConversionError(String valueConversionError) Sets the error that is shown if the field value cannot be converted to the data source type.
void	setConvertedValue(Object value) Sets the value of the field using a value of the data source type.
void	setConverter(Class<?> datamodelType) Retrieves a converter for the field from the converter factory defined for the application.
void	setConverter(Converter<T,?> converter) Sets the converter used to convert the field value to property data source type.
void	setCurrentBufferedSourceException(Buffered.SourceException currentBufferedSourceException) Sets the current buffered source exception.
protected void	setInternalValue(T newValue) Sets the internal field value.
void	setInvalidAllowed(boolean invalidAllowed) Fields allow invalid values by default.
void	setInvalidCommitted(boolean isCommitted) Sets if the invalid data should be committed to datasource.
void	setPropertyDataSource(Property newDataSource) Sets the specified Property as the data source for the field.
void	setReadOnly(boolean readOnly) Changes the readonly state and throw read-only status change events.
void	setReadThrough(boolean readThrough) Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
void	setRequired(boolean required) Sets the field required.
void	setRequiredError(String requiredMessage) Set the error that is show if this field is required, but empty.
void	setTabIndex(int tabIndex) Sets the tabulator index of the Focusable component.
void	setValidationVisible(boolean validateAutomatically) Enable or disable automatic, visible validation.
void	setValue(Object newFieldValue) Sets the value of the field.
protected void	setValue(T newFieldValue, boolean repaintIsNotNeeded) Sets the value of the field.
void	setWriteThrough(boolean writeThrough) Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
protected boolean	shouldHideErrors() Returns true if the error indicator be hidden when painting the component even when there are errors.
String	toString() Deprecated. Instead use getValue() to get the value of the field, getConvertedValue() to get the field value converted to the data model type or getPropertyDataSource() .getValue() to get the value of the data source.
void	updateState() Called before the shared state is sent to the client.
void	validate() Checks the validity of the Field.
protected void	validate(T fieldValue) Validates that the given value pass the validators for the field.
void	valueChange(Property.ValueChangeEvent event) This method listens to data source value changes and passes the changes forwards.

Methods inherited from class com.vaadin.ui.AbstractComponent

addListener, addListener, addListener, addListener, addShortcutListener, addStyleName, findAncestor, fireComponentErrorEvent, fireComponentEvent, fireEvent, getActionManager, getApplication, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorHandler, getHeight, getHeightUnits, getIcon, getListeners, getLocale, getParent, getRoot, getStyle, getStyleName, getWidth, getWidthUnits, handleError, hasListeners, isConnectorEnabled, isEnabled, isImmediate, isVisible, removeListener, removeListener, removeListener, removeListener, removeListener, removeShortcutListener, removeStyleName, requestRepaint, setCaption, setComponentError, setData, setDebugId, setDescription, setEnabled, setErrorHandler, setHeight, setHeight, setIcon, setImmediate, setLocale, setParent, setSizeFull, setSizeUndefined, setStyle, setStyleName, setVisible, setWidth, setWidth

Methods inherited from class com.vaadin.terminal.AbstractClientConnector

addExtension, addMethodInvocationToQueue, createState, getAllChildrenIterable, getConnectorId, getExtensions, getRpcManager, getRpcProxy, getStateType, registerRpc, registerRpc, removeExtension, requestRepaintAll, retrievePendingRpcCalls

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.vaadin.ui.Component

addListener, addStyleName, getApplication, getCaption, getDebugId, getIcon, getLocale, getParent, getRoot, getStyleName, isEnabled, isVisible, removeListener, removeStyleName, setCaption, setDebugId, setEnabled, setIcon, setStyleName, setVisible

Methods inherited from interface com.vaadin.terminal.gwt.server.ClientConnector

getExtensions, getStateType, isConnectorEnabled, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setParent

Methods inherited from interface com.vaadin.terminal.gwt.client.Connector

getConnectorId

Methods inherited from interface com.vaadin.terminal.gwt.server.RpcTarget

getRpcManager

Methods inherited from interface com.vaadin.terminal.Sizeable

getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setSizeFull, setSizeUndefined, setWidth, setWidth

Methods inherited from interface com.vaadin.event.Action.ShortcutNotifier

addShortcutListener, removeShortcutListener

Constructor Detail

AbstractField

public AbstractField()

Method Detail

shouldHideErrors

protected boolean shouldHideErrors()

Returns true if the error indicator be hidden when painting the component even when there are errors. This is a mostly internal method, but can be overridden in subclasses e.g. if the error indicator should also be shown for empty fields in some cases.

Returns:

true to hide the error indicator, false to use the normal logic to show it when there are errors

getType

public abstract Class<? extends T> getType()

Returns the type of the Field. The methods getValue and setValue must be compatible with this type: one must be able to safely cast the value returned from getValue to the given type and pass any variable assignable to this type as an argument to setValue.

Specified by:

getType in interface Property<T>

Returns:

the type of the Field

isReadOnly

public boolean isReadOnly()

The abstract field is read only also if the data source is in read only mode.

Specified by:

isReadOnly in interface Property<T>

Specified by:

isReadOnly in interface Component

Overrides:

isReadOnly in class AbstractComponent

Returns:

true if the component or any of its parents is in read-only mode, false if not.

See Also:

Component.setReadOnly(boolean)

setReadOnly

public void setReadOnly(boolean readOnly)

Changes the readonly state and throw read-only status change events.

Specified by:

setReadOnly in interface Property<T>

Specified by:

setReadOnly in interface Component

Overrides:

setReadOnly in class AbstractComponent

Parameters:

readOnly - a boolean value specifying whether the component is put read-only mode or not

See Also:

Component.setReadOnly(boolean)

isInvalidCommitted

public boolean isInvalidCommitted()

Tests if the invalid data is committed to datasource.

Specified by:

isInvalidCommitted in interface BufferedValidatable

See Also:

BufferedValidatable.isInvalidCommitted()

setInvalidCommitted

public void setInvalidCommitted(boolean isCommitted)

Sets if the invalid data should be committed to datasource.

Specified by:

setInvalidCommitted in interface BufferedValidatable

See Also:

BufferedValidatable.setInvalidCommitted(boolean)

commit

public void commit()
            throws Buffered.SourceException,
                   Validator.InvalidValueException

Description copied from interface: Buffered

Updates all changes since the previous commit to the data source. The value stored in the object will always be updated into the data source when commit is called.

Specified by:

commit in interface Buffered

Throws:

Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

Validator.InvalidValueException - if the operation fails because validation is enabled and the values do not validate

discard

public void discard()
             throws Buffered.SourceException

Description copied from interface: Buffered

Discards all changes since last commit. The object updates its value from the data source.

Specified by:

discard in interface Buffered

Throws:

Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

isModified

public boolean isModified()

Description copied from interface: Buffered

Tests if the value stored in the object has been modified since it was last updated from the data source.

Specified by:

isModified in interface Buffered

Returns:

true if the value in the object has been modified since the last data source update, false if not.

isWriteThrough

public boolean isWriteThrough()

Description copied from interface: Buffered

Tests if the object is in write-through mode. If the object is in write-through mode, all modifications to it will result in commit being called after the modification.

Specified by:

isWriteThrough in interface Buffered

Returns:

true if the object is in write-through mode, false if it's not.

setWriteThrough

@Deprecated
public void setWriteThrough(boolean writeThrough)
                     throws Buffered.SourceException,
                            Validator.InvalidValueException

Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Sets the field's write-through mode to the specified status. When switching the write-through mode on, a commit() will be performed.

Specified by:

setWriteThrough in interface Buffered

Parameters:

writeThrough - Boolean value to indicate if the object should be in write-through mode after the call.

Throws:

SourceException - If the operation fails because of an exception is thrown by the data source.

Validator.InvalidValueException - If the implicit commit operation fails because of a validation error.

Buffered.SourceException

See Also:

for an easier way to control read through and write through modes

isReadThrough

public boolean isReadThrough()

Description copied from interface: Buffered

Tests if the object is in read-through mode. If the object is in read-through mode, retrieving its value will result in the value being first updated from the data source to the object.

The only exception to this rule is that when the object is not in write-through mode and it's buffer contains a modified value, the value retrieved from the object will be the locally modified value in the buffer which may differ from the value in the data source.

Specified by:

isReadThrough in interface Buffered

Returns:

true if the object is in read-through mode, false if it's not.

setReadThrough

@Deprecated
public void setReadThrough(boolean readThrough)
                    throws Buffered.SourceException

Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Sets the field's read-through mode to the specified status. When switching read-through mode on, the object's value is updated from the data source.

Specified by:

setReadThrough in interface Buffered

Parameters:

readThrough - Boolean value to indicate if the object should be in read-through mode after the call.

Throws:

SourceException - If the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

Buffered.SourceException

See Also:

for an easier way to control read through and write through modes

setBuffered

public void setBuffered(boolean buffered)

Sets the buffered mode of this Field.

When the field is in buffered mode, changes will not be committed to the property data source until commit() is called.

Changing buffered mode will change the read through and write through state for the field.

Mixing calls to setBuffered(boolean) and setReadThrough(boolean) or setWriteThrough(boolean) is generally a bad idea.

Specified by:

setBuffered in interface Buffered

Parameters:

buffered - true if buffered mode should be turned on, false otherwise

isBuffered

public boolean isBuffered()

Checks the buffered mode of this Field.

This method only returns true if both read and write buffering is used.

Specified by:

isBuffered in interface Buffered

Returns:

true if buffered mode is on, false otherwise

toString

@Deprecated
public String toString()

Deprecated. Instead use getValue() to get the value of the field, getConvertedValue() to get the field value converted to the data model type or getPropertyDataSource() .getValue() to get the value of the data source.

Returns the (field) value converted to a String using toString().

Overrides:

toString in class Object

See Also:

Object.toString()

getValue

public T getValue()

Gets the current value of the field.

This is the visible, modified and possible invalid value the user have entered to the field.

Note that the object returned is compatible with getType(). For example, if the type is String, this returns Strings even when the underlying datasource is of some other type. In order to access the converted value, use getConvertedValue() and to access the value of the property data source, use Property.getValue() for the property data source.

Since Vaadin 7.0, no implicit conversions between other data types and String are performed, but a converter is used if set.

Specified by:

getValue in interface Property<T>

Returns:

the current value of the field.

setValue

public void setValue(Object newFieldValue)
              throws Property.ReadOnlyException,
                     Converter.ConversionException

Sets the value of the field.

Specified by:

setValue in interface Property<T>

Parameters:

newFieldValue - the New value of the field.

Throws:

Property.ReadOnlyException

Converter.ConversionException

setValue

protected void setValue(T newFieldValue,
                        boolean repaintIsNotNeeded)
                 throws Property.ReadOnlyException,
                        Converter.ConversionException,
                        Validator.InvalidValueException

Sets the value of the field.

Parameters:

newFieldValue - the New value of the field.

repaintIsNotNeeded - True iff caller is sure that repaint is not needed.

Throws:

Property.ReadOnlyException

Converter.ConversionException

Validator.InvalidValueException

getPropertyDataSource

public Property getPropertyDataSource()

Gets the current data source of the field, if any.

Specified by:

getPropertyDataSource in interface Property.Viewer

Returns:

the current data source as a Property, or null if none defined.

setPropertyDataSource

public void setPropertyDataSource(Property newDataSource)

Sets the specified Property as the data source for the field. All uncommitted changes are replaced with a value from the new data source.

If the datasource has any validators, the same validators are added to the field. Because the default behavior of the field is to allow invalid values, but not to allow committing them, this only adds visual error messages to fields and do not allow committing them as long as the value is invalid. After the value is valid, the error message is not shown and the commit can be done normally.

If the data source implements Property.ValueChangeNotifier and/or Property.ReadOnlyStatusChangeNotifier, the field registers itself as a listener and updates itself according to the events it receives. To avoid memory leaks caused by references to a field no longer in use, the listener registrations are removed on detach and re-added on attach.

Note: before 6.5 we actually called discard() method in the beginning of the method. This was removed to simplify implementation, avoid excess calls to backing property and to avoid odd value change events that were previously fired (developer expects 0-1 value change events if this method is called). Some complex field implementations might now need to override this method to do housekeeping similar to discard().

Specified by:

setPropertyDataSource in interface Property.Viewer

Parameters:

newDataSource - the new data source Property.

setConverter

public void setConverter(Class<?> datamodelType)

Retrieves a converter for the field from the converter factory defined for the application. Clears the converter if no application reference is available or if the factory returns null.

Parameters:

datamodelType - The type of the data model that we want to be able to convert from

getConversionError

protected String getConversionError(Class<?> dataSourceType)

Returns the conversion error with {0} replaced by the data source type.

Parameters:

dataSourceType - The type of the data source

Returns:

The value conversion error string with parameters replaced.

getConvertedValue

public Object getConvertedValue()

Returns the current value (as returned by getValue()) converted to the data source type.

This returns the same as getValue() if no converter has been set. The value is not necessarily the same as the data source value e.g. if the field is in buffered mode and has been modified.

Returns:

The converted value that is compatible with the data source type

setConvertedValue

public void setConvertedValue(Object value)

Sets the value of the field using a value of the data source type. The value given is converted to the field type and then assigned to the field. This will update the property data source in the same way as when setValue(Object) is called.

Parameters:

value - The value to set. Must be the same type as the data source.

addValidator

public void addValidator(Validator validator)

Adds a new validator for the field's value. All validators added to a field are checked each time the its value changes.

Specified by:

addValidator in interface Validatable

Parameters:

validator - the new validator to be added.

getValidators

public Collection<Validator> getValidators()

Gets the validators of the field.

Specified by:

getValidators in interface Validatable

Returns:

the Unmodifiable collection that holds all validators for the field.

removeValidator

public void removeValidator(Validator validator)

Removes the validator from the field.

Specified by:

removeValidator in interface Validatable

Parameters:

validator - the validator to remove.

removeAllValidators

public void removeAllValidators()

Removes all validators from the field.

isValid

public boolean isValid()

Tests the current value against registered validators if the field is not empty. If the field is empty it is considered valid if it is not required and invalid otherwise. Validators are never checked for empty fields. In most cases, validate() should be used instead of isValid() to also get the error message.

Specified by:

isValid in interface Validatable

Returns:

true if all registered validators claim that the current value is valid or if the field is empty and not required, false otherwise.

validate

public void validate()
              throws Validator.InvalidValueException

Checks the validity of the Field. A field is invalid if it is set as required (using setRequired(boolean) and is empty, if one or several of the validators added to the field indicate it is invalid or if the value cannot be converted provided a converter has been set. The "required" validation is a built-in validation feature. If the field is required and empty this method throws an EmptyValueException with the error message set using setRequiredError(String).

Specified by:

validate in interface Validatable

Throws:

Validator.InvalidValueException - if the value is not valid

See Also:

Validatable.validate()

validate

protected void validate(T fieldValue)
                 throws Validator.InvalidValueException

Validates that the given value pass the validators for the field.

This method does not check the requiredness of the field.

Parameters:

fieldValue - The value to check

Throws:

Validator.InvalidValueException - if one or several validators fail

isInvalidAllowed

public boolean isInvalidAllowed()

Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately.

Specified by:

isInvalidAllowed in interface Validatable

Returns:

true iff the invalid values are allowed.

See Also:

Validatable.isInvalidAllowed()

setInvalidAllowed

public void setInvalidAllowed(boolean invalidAllowed)
                       throws UnsupportedOperationException

Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately.

In common setting where the user wants to assure the correctness of the datasource, but allow temporarily invalid contents in the field, the user should add the validators to datasource, that should not allow invalid values. The validators are automatically copied to the field when the datasource is set.

Specified by:

setInvalidAllowed in interface Validatable

Throws:

UnsupportedOperationException - if the setInvalidAllowed is not supported.

See Also:

Validatable.setInvalidAllowed(boolean)

getErrorMessage

public ErrorMessage getErrorMessage()

Error messages shown by the fields are composites of the error message thrown by the superclasses (that is the component error message), validation errors and buffered source errors.

Overrides:

getErrorMessage in class AbstractComponent

Returns:

ErrorMessage containing the description of the error state of the component or null, if the component contains no errors. Extending classes should override this method if they support other error message types such as validation errors or buffering errors. The returned error message contains information about all the errors.

See Also:

AbstractComponent.getErrorMessage()

addListener

public void addListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Registers a new value change listener for this Property.

Specified by:

addListener in interface Property.ValueChangeNotifier

Parameters:

listener - the new Listener to be registered

removeListener

public void removeListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Removes a previously registered value change listener.

Specified by:

removeListener in interface Property.ValueChangeNotifier

Parameters:

listener - listener to be removed

fireValueChange

protected void fireValueChange(boolean repaintIsNotNeeded)

Emits the value change event. The value contained in the field is validated before the event is created.

readOnlyStatusChange

public void readOnlyStatusChange(Property.ReadOnlyStatusChangeEvent event)

React to read only status changes of the property by requesting a repaint.

Specified by:

readOnlyStatusChange in interface Property.ReadOnlyStatusChangeListener

Parameters:

event - Read-only status change event object

See Also:

Property.ReadOnlyStatusChangeListener

addListener

public void addListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

Registers a new read-only status change listener for this Property.

Specified by:

addListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - the new Listener to be registered

removeListener

public void removeListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

Removes a previously registered read-only status change listener.

Specified by:

removeListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - listener to be removed

fireReadOnlyStatusChange

protected void fireReadOnlyStatusChange()

Emits the read-only status change event. The value contained in the field is validated before the event is created.

valueChange

public void valueChange(Property.ValueChangeEvent event)

This method listens to data source value changes and passes the changes forwards. Changes are not forwarded to the listeners of the field during internal operations of the field to avoid duplicate notifications.

Specified by:

valueChange in interface Property.ValueChangeListener

Parameters:

event - the value change event telling the data source contents have changed.

focus

public void focus()

Sets the focus for this component if the component is Focusable.

Specified by:

focus in interface Component.Focusable

Overrides:

focus in class AbstractComponent

See Also:

FieldEvents, FieldEvents.FocusEvent, FieldEvents.FocusListener, FieldEvents.BlurEvent, FieldEvents.BlurListener

getTabIndex

public int getTabIndex()

Description copied from interface: Component.Focusable

Gets the tabulator index of the Focusable component.

Specified by:

getTabIndex in interface Component.Focusable

Returns:

tab index set for the Focusable component

See Also:

Component.Focusable.setTabIndex(int)

setTabIndex

public void setTabIndex(int tabIndex)

Description copied from interface: Component.Focusable

Sets the tabulator index of the Focusable component. The tab index property is used to specify the order in which the fields are focused when the user presses the Tab key. Components with a defined tab index are focused sequentially first, and then the components with no tab index.

 Form loginBox = new Form();
 loginBox.setCaption("Login");
 layout.addComponent(loginBox);
 
 // Create the first field which will be focused
 TextField username = new TextField("User name");
 loginBox.addField("username", username);
 
 // Set focus to the user name
 username.focus();
 
 TextField password = new TextField("Password");
 loginBox.addField("password", password);
 
 Button login = new Button("Login");
 loginBox.getFooter().addComponent(login);
 
 // An additional component which natural focus order would
 // be after the button.
 CheckBox remember = new CheckBox("Remember me");
 loginBox.getFooter().addComponent(remember);
 
 username.setTabIndex(1);
 password.setTabIndex(2);
 remember.setTabIndex(3); // Different than natural place
 login.setTabIndex(4);
 

After all focusable user interface components are done, the browser can begin again from the component with the smallest tab index, or it can take the focus out of the page, for example, to the location bar.

If the tab index is not set (is set to zero), the default tab order is used. The order is somewhat browser-dependent, but generally follows the HTML structure of the page.

A negative value means that the component is completely removed from the tabulation order and can not be reached by pressing the Tab key at all.

Specified by:

setTabIndex in interface Component.Focusable

Parameters:

tabIndex - the tab order of this component. Indexes usually start from 1. Zero means that default tab order should be used. A negative value means that the field should not be included in the tabbing sequence.

See Also:

Component.Focusable.getTabIndex()

getInternalValue

protected T getInternalValue()

Returns the internal field value, which might not match the data source value e.g. if the field has been modified and is not in write-through mode. This method can be overridden by subclasses together with setInternalValue(Object) to compute internal field value at runtime. When doing so, typically also isModified() needs to be overridden and care should be taken in the management of the empty state and buffering support.

Returns:

internal field value

setInternalValue

protected void setInternalValue(T newValue)

Sets the internal field value. This is purely used by AbstractField to change the internal Field value. It does not trigger valuechange events. It can be overridden by the inheriting classes to update all dependent variables. Subclasses can also override getInternalValue() if necessary.

Parameters:

newValue - the new value to be set.

attach

public void attach()

Notifies the component that it is connected to an application.

Specified by:

attach in interface ClientConnector

Specified by:

attach in interface Component

Overrides:

attach in class AbstractComponent

See Also:

Component.attach()

detach

public void detach()

Description copied from class: AbstractClientConnector

Notifies the component that it is detached from the application.

The caller of this method is ClientConnector.setParent(ClientConnector) if the parent is in the application. When the parent is detached from the application it is its response to call ClientConnector.detach() for all the children and to detach itself from the terminal.

The AbstractClientConnector.getApplication() and AbstractClientConnector.getRoot() methods might return null after this method is called.

Specified by:

detach in interface ClientConnector

Overrides:

detach in class AbstractComponent

isRequired

public boolean isRequired()

Is this field required. Required fields must filled by the user. If the field is required, it is visually indicated in the user interface. Furthermore, setting field to be required implicitly adds "non-empty" validator and thus isValid() == false or any isEmpty() fields. In those cases validation errors are not painted as it is obvious that the user must fill in the required fields. On the other hand, for the non-required fields isValid() == true if the field isEmpty() regardless of any attached validators.

Specified by:

isRequired in interface Field<T>

Returns:

true if the field is required, otherwise false.

setRequired

public void setRequired(boolean required)

Sets the field required. Required fields must filled by the user. If the field is required, it is visually indicated in the user interface. Furthermore, setting field to be required implicitly adds "non-empty" validator and thus isValid() == false or any isEmpty() fields. In those cases validation errors are not painted as it is obvious that the user must fill in the required fields. On the other hand, for the non-required fields isValid() == true if the field isEmpty() regardless of any attached validators.

Specified by:

setRequired in interface Field<T>

Parameters:

required - Is the field required.

setRequiredError

public void setRequiredError(String requiredMessage)

Set the error that is show if this field is required, but empty. When setting requiredMessage to be "" or null, no error pop-up or exclamation mark is shown for a empty required field. This faults to "". Even in those cases isValid() returns false for empty required fields.

Specified by:

setRequiredError in interface Field<T>

Parameters:

requiredMessage - Message to be shown when this field is required, but empty.

getRequiredError

public String getRequiredError()

Description copied from interface: Field

Gets the error message that is to be displayed if a required field is empty.

Specified by:

getRequiredError in interface Field<T>

Returns:

Error message.

getConversionError

public String getConversionError()

Gets the error that is shown if the field value cannot be converted to the data source type.

Returns:

The error that is shown if conversion of the field value fails

setConversionError

public void setConversionError(String valueConversionError)

Sets the error that is shown if the field value cannot be converted to the data source type. If {0} is present in the message, it will be replaced by the simple name of the data source type.

Parameters:

valueConversionError - Message to be shown when conversion of the value fails

isEmpty

protected boolean isEmpty()

Is the field empty? In general, "empty" state is same as null. As an exception, TextField also treats empty string as "empty".

isValidationVisible

public boolean isValidationVisible()

Is automatic, visible validation enabled? If automatic validation is enabled, any validators connected to this component are evaluated while painting the component and potential error messages are sent to client. If the automatic validation is turned off, isValid() and validate() methods still work, but one must show the validation in their own code.

Returns:

True, if automatic validation is enabled.

setValidationVisible

public void setValidationVisible(boolean validateAutomatically)

Enable or disable automatic, visible validation. If automatic validation is enabled, any validators connected to this component are evaluated while painting the component and potential error messages are sent to client. If the automatic validation is turned off, isValid() and validate() methods still work, but one must show the validation in their own code.

Parameters:

validateAutomatically - True, if automatic validation is enabled.

setCurrentBufferedSourceException

public void setCurrentBufferedSourceException(Buffered.SourceException currentBufferedSourceException)

Sets the current buffered source exception.

Parameters:

currentBufferedSourceException -

getCurrentBufferedSourceException

protected Buffered.SourceException getCurrentBufferedSourceException()

Gets the current buffered source exception.

Returns:

The current source exception

getConverter

public Converter<T,Object> getConverter()

Gets the converter used to convert the property data source value to the field value.

Returns:

The converter or null if none is set.

setConverter

public void setConverter(Converter<T,?> converter)

Sets the converter used to convert the field value to property data source type. The converter must have a presentation type that matches the field type.

Parameters:

converter - The new converter to use.

getState

public AbstractFieldState getState()

Description copied from class: AbstractComponent

Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().

Specified by:

getState in interface Connector

Specified by:

getState in interface Component

Overrides:

getState in class AbstractComponent

Returns:

updated component shared state

updateState

public void updateState()

Description copied from interface: Component

Called before the shared state is sent to the client. Gives the component an opportunity to set computed/dynamic state values e.g. state values that depend on other component features.

This method must not alter the component hierarchy in any way.

Specified by:

updateState in interface Component

Overrides:

updateState in class AbstractComponent