com.vaadin.ui

Class AbstractField<T>

java.lang.Object

com.vaadin.server.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, ContextClickEvent.ContextClickNotifier, MethodEventSource, ClientConnector, Sizeable, Connector, Component, Component.Focusable, Field<T>, Serializable

Direct Known Subclasses:

AbstractSelect, AbstractTextField, CheckBox, CustomField, DateField, Form, ProgressBar, 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

Author:

Vaadin Ltd.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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 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.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

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

Sizeable.Unit

Field Summary

Fields inherited from class com.vaadin.ui.AbstractComponent

DESIGN_ATTR_PLAIN_TEXT

Fields inherited from interface com.vaadin.server.Sizeable

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

Constructor Summary

Constructors

Constructor and Description
AbstractField()

Method Summary

Modifier and Type	Method and Description
void	addListener(Property.ReadOnlyStatusChangeListener listener) Deprecated. As of 7.0, replaced by addReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener)
void	addListener(Property.ValueChangeListener listener) Deprecated. As of 7.0, replaced by addValueChangeListener(Property.ValueChangeListener)
void	addReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener listener) Registers a new read-only status change listener for this Property.
void	addValidator(Validator validator) Adds a new validator for the field's value.
void	addValueChangeListener(Property.ValueChangeListener listener) Registers a new value change listener for this Property.
void	attach() Notifies the component that it is connected to an application.
void	beforeClientResponse(boolean initial) Called before the shared state and RPC invocations are sent to the client.
void	clear() Clears the value of the field.
void	commit() Updates all changes since the previous commit to the data source.
void	detach() Notifies the connector that it is detached from its VaadinSession.
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, Converter.ConversionException e) Returns the conversion error with {0} replaced by the data source type and {1} replaced by the exception (localized) message.
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.
protected Collection<String>	getCustomAttributes() Returns a collection of attributes that should not be handled by the basic implementation of the readDesign and writeDesign methods.
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.
protected Class<?>	getModelType() Retrieves the type of the currently used data model.
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.
protected AbstractFieldState	getState() Returns the shared state bean with information to be sent from the server to the client.
protected AbstractFieldState	getState(boolean markAsDirty) Returns the shared state for this connector.
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.
boolean	isEmpty() Is the field empty? In general, "empty" state is same as null.
boolean	isImmediate() Returns the immediate mode of the component.
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	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.
void	readDesign(org.jsoup.nodes.Element design, DesignContext designContext) Reads the component state from the given design.
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) Deprecated. As of 7.0, replaced by removeReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener)
void	removeListener(Property.ValueChangeListener listener) Deprecated. As of 7.0, replaced by removeValueChangeListener(Property.ValueChangeListener)
void	removeReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener listener) Removes a previously registered read-only status change listener.
void	removeValidator(Validator validator) Removes the validator from the field.
void	removeValueChangeListener(Property.ValueChangeListener listener) Removes a previously registered value change listener.
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	setLocale(Locale locale) Sets the locale of this component.
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	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(T newFieldValue) Sets the value of the field.
protected void	setValue(T newFieldValue, boolean repaintIsNotNeeded) Sets the value of the field.
protected void	setValue(T newFieldValue, boolean repaintIsNotNeeded, boolean ignoreReadOnly) Sets the value of the field.
protected boolean	shouldHideErrors() Returns true if the error indicator be hidden when painting the component even when there are errors.
String	toString() Deprecated. As of 7.0. 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	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.
void	writeDesign(org.jsoup.nodes.Element design, DesignContext designContext) Writes the component state to the given design.

Methods inherited from class com.vaadin.ui.AbstractComponent

addContextClickListener, addListener, addShortcutListener, addStyleName, findAncestor, fireComponentErrorEvent, fireComponentEvent, getActionManager, getCaption, getComponentError, getData, getDebugId, getDescription, getExplicitImmediateValue, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isResponsive, isVisible, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setEnabled, setHeight, setHeight, setHeightUndefined, setIcon, setId, setImmediate, setParent, setPrimaryStyleName, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.vaadin.ui.Component

addListener, addStyleName, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isVisible, removeListener, removeStyleName, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setStyleName, setVisible

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Methods inherited from interface com.vaadin.server.Sizeable

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

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.

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.

Setting buffered mode from true to false will commit any pending changes.

Specified by:

setBuffered in interface Buffered

Parameters:

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

Since:

7.0.0

isBuffered

public boolean isBuffered()

Checks the buffered mode of this Field.

Specified by:

isBuffered in interface Buffered

Returns:

true if buffered mode is on, false otherwise

toString

@Deprecated
public String toString()

Deprecated. As of 7.0. 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 a string representation of this object. The returned string representation depends on if the legacy Property toString mode is enabled or disabled.

If legacy Property toString mode is enabled, returns the value of this Field converted to a String.

If legacy Property toString mode is disabled, the string representation has no special meaning

Overrides:

toString in class Object

Returns:

A string representation of the value value stored in the Property or a string representation of the Property object.

See Also:

LegacyPropertyHelper.isLegacyToStringEnabled()

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(T 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)

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

setValue

protected void setValue(T newFieldValue,
                        boolean repaintIsNotNeeded,
                        boolean ignoreReadOnly)
                 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.

ignoreReadOnly - True iff if the read-only check should be ignored

Throws:

Property.ReadOnlyException

Converter.ConversionException

Validator.InvalidValueException

Since:

7.5.7

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

getModelType

protected Class<?> getModelType()

Retrieves the type of the currently used data model. If the field has no data source then the model type of the converter is used.

Returns:

The type of the currently used data model or null if no data source or converter is set.

Since:

7.1

getConversionError

protected String getConversionError(Class<?> dataSourceType,
                                    Converter.ConversionException e)

Returns the conversion error with {0} replaced by the data source type and {1} replaced by the exception (localized) message.

Parameters:

dataSourceType - the type of the data source

e - a conversion exception which can provide additional information

Returns:

The value conversion error string with parameters replaced.

Since:

7.1

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:

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

Specified by:

removeAllValidators in interface Validatable

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()

addValueChangeListener

public void addValueChangeListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Registers a new value change listener for this Property.

Specified by:

addValueChangeListener in interface Property.ValueChangeNotifier

Parameters:

listener - the new Listener to be registered

addListener

@Deprecated
public void addListener(Property.ValueChangeListener listener)

Deprecated. As of 7.0, replaced by addValueChangeListener(Property.ValueChangeListener)

Specified by:

addListener in interface Property.ValueChangeNotifier

removeValueChangeListener

public void removeValueChangeListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Removes a previously registered value change listener.

Specified by:

removeValueChangeListener in interface Property.ValueChangeNotifier

Parameters:

listener - listener to be removed

removeListener

@Deprecated
public void removeListener(Property.ValueChangeListener listener)

Deprecated. As of 7.0, replaced by removeValueChangeListener(Property.ValueChangeListener)

Specified by:

removeListener in interface Property.ValueChangeNotifier

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

addReadOnlyStatusChangeListener

public void addReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

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

Specified by:

addReadOnlyStatusChangeListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - the new Listener to be registered

addListener

@Deprecated
public void addListener(Property.ReadOnlyStatusChangeListener listener)

Deprecated. As of 7.0, replaced by addReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener)

Specified by:

addListener in interface Property.ReadOnlyStatusChangeNotifier

removeReadOnlyStatusChangeListener

public void removeReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

Removes a previously registered read-only status change listener.

Specified by:

removeReadOnlyStatusChangeListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - listener to be removed

removeListener

@Deprecated
public void removeListener(Property.ReadOnlyStatusChangeListener listener)

Deprecated. As of 7.0, replaced by removeReadOnlyStatusChangeListener(Property.ReadOnlyStatusChangeListener)

Specified by:

removeListener in interface Property.ReadOnlyStatusChangeNotifier

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()

setLocale

public void setLocale(Locale locale)

Description copied from class: AbstractComponent

Sets the locale of this component.

 // Component for which the locale is meaningful
 InlineDateField date = new InlineDateField("Datum");

 // German language specified with ISO 639-1 language
 // code and ISO 3166-1 alpha-2 country code.
 date.setLocale(new Locale("de", "DE"));

 date.setResolution(DateField.RESOLUTION_DAY);
 layout.addComponent(date);
 

Overrides:

setLocale in class AbstractComponent

Parameters:

locale - the locale to become this component's locale.

detach

public void detach()

Description copied from class: AbstractClientConnector

Notifies the connector that it is detached from its VaadinSession.

The caller of this method is #setParent(ClientConnector) if the parent is in the session. When the parent is detached from the session it is its responsibility to call ClientConnector.detach() for each of its children.

The AbstractClientConnector.getSession() and AbstractClientConnector.getUI() 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. If {1} is present in the message, it will be replaced by the ConversionException message.

Parameters:

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

isEmpty

public boolean isEmpty()

Description copied from interface: Field

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

Specified by:

isEmpty in interface Field<T>

Returns:

true if the field is empty, false otherwise

clear

public void clear()

Description copied from interface: Field

Clears the value of the field.

The field value is typically reset to the initial value of the field. Calling Field.isEmpty() on a cleared field must always returns true.

Specified by:

clear in interface Field<T>

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

protected 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().

Overrides:

getState in class AbstractComponent

Returns:

updated component shared state

getState

protected AbstractFieldState getState(boolean markAsDirty)

Description copied from class: AbstractClientConnector

Returns the shared state for this connector.

Overrides:

getState in class AbstractComponent

Parameters:

markAsDirty - true if the connector should automatically be marked dirty, false otherwise

Returns:

The shared state for this connector. Never null.

See Also:

AbstractClientConnector.getState()

beforeClientResponse

public void beforeClientResponse(boolean initial)

Description copied from interface: ClientConnector

Called before the shared state and RPC invocations are sent to the client. Gives the connector an opportunity to set computed/dynamic state values or to invoke last minute RPC methods depending on other component features.

Specified by:

beforeClientResponse in interface ClientConnector

Overrides:

beforeClientResponse in class AbstractComponent

Parameters:

initial - true if the client-side connector will be created and initialized after this method has been invoked. false if there is already an initialized client-side connector.

isImmediate

public boolean isImmediate()

Returns the immediate mode of the component.

Certain operations such as adding a value change listener will set the component into immediate mode if AbstractComponent.setImmediate(boolean) has not been explicitly called with false.

Fields are automatically set to immediate if validators have been added.

Overrides:

isImmediate in class AbstractComponent

Returns:

true if the component is in immediate mode (explicitly or implicitly set), false if the component if not in immediate mode

readDesign

public void readDesign(org.jsoup.nodes.Element design,
                       DesignContext designContext)

Description copied from interface: Component

Reads the component state from the given design.

The component is responsible not only for updating its own state but also for ensuring that its children update their state based on the design.

It is assumed that the component is in its default state when this method is called. Reading should only take into consideration attributes specified in the design and not reset any unspecified attributes to their defaults.

This method must not modify the design.

Specified by:

readDesign in interface Component

Overrides:

readDesign in class AbstractComponent

Parameters:

design - The element to obtain the state from

designContext - The DesignContext instance used for parsing the design

getCustomAttributes

protected Collection<String> getCustomAttributes()

Description copied from class: AbstractComponent

Returns a collection of attributes that should not be handled by the basic implementation of the readDesign and writeDesign methods. Typically these are handled in a custom way in the overridden versions of the above methods

Overrides:

getCustomAttributes in class AbstractComponent

Returns:

the collection of attributes that are not handled by the basic implementation

writeDesign

public void writeDesign(org.jsoup.nodes.Element design,
                        DesignContext designContext)

Description copied from interface: Component

Writes the component state to the given design.

The component is responsible not only for writing its own state but also for ensuring that its children write their state to the design.

This method must not modify the component state.

Specified by:

writeDesign in interface Component

Overrides:

writeDesign in class AbstractComponent

Parameters:

design - The element to write the component state to. Any previous attributes or child nodes are not cleared.

designContext - The DesignContext instance used for writing the design