Package com.vaadin.flow.component

Class AbstractCompositeField<C extends Component,S extends AbstractCompositeField<C,S,T>,T>

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.Composite<C>

com.vaadin.flow.component.AbstractCompositeField<C,S,T>

Type Parameters:

C - the type of the content component

S - the source type for value change events

T - the value type

All Implemented Interfaces:

AttachNotifier, DetachNotifier, HasElement, HasEnabled, HasValue<AbstractField.ComponentValueChangeEvent<S,T>,T>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<S,T>,T>, Serializable

public abstract class AbstractCompositeField<C extends Component,S extends AbstractCompositeField<C,S,T>,T>
extends Composite<C>
implements HasValueAndElement<AbstractField.ComponentValueChangeEvent<S,T>,T>, HasEnabled

An abstract field class that is backed by a composite component.

Note that composite fields do not automatically show client side validation error messages or required indicators.

See the detailed documentation for AbstractField and Composite for detailed information.

Since:

1.0

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>

Constructor Summary

Constructors

Constructor	Description
AbstractCompositeField(T defaultValue)	Creates a new field.

Method Summary

Modifier and Type	Method	Description
Registration	addValueChangeListener(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<S,T>> listener)	Adds a value change listener.
T	getEmptyValue()	Returns the value that represents an empty value.
T	getValue()	Returns the current value of this object.
boolean	isEmpty()	Returns whether this HasValue is considered to be empty.
protected void	setModelValue(T newModelValue, boolean fromClient)	Updates the model value if the value has actually changed.
protected abstract void	setPresentationValue(T newPresentationValue)	Updates the presentation of this field to display the provided value.
void	setValue(T value)	Sets the value of this object.
protected boolean	valueEquals(T value1, T value2)	Compares to value instances to each other to determine whether they are equal.

Methods inherited from class com.vaadin.flow.component.Composite

getChildren, getContent, getElement, initContent

Methods inherited from class com.vaadin.flow.component.Component

addListener, fireEvent, from, get, getEventBus, getId, getLocale, getParent, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasEnabled

isEnabled, setEnabled

Methods inherited from interface com.vaadin.flow.component.HasValue

clear, getOptionalValue

Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

isReadOnly, isRequiredIndicatorVisible, setReadOnly, setRequiredIndicatorVisible

Constructor Detail

AbstractCompositeField

public AbstractCompositeField(T defaultValue)

Creates a new field. The provided default value is used by getEmptyValue() and is also used as the initial value of this instance.

Parameters:

defaultValue - the default value

Method Detail

setValue

public void setValue(T value)

Description copied from interface: HasValue

Sets the value of this object. If the new value is not equal to getValue(), fires a value change event. May throw IllegalArgumentException if the value is not acceptable.

Implementation note: the implementing class should document whether null values are accepted or not, and override HasValue.getEmptyValue() if the empty value is not null.

Specified by:

setValue in interface HasValue<C extends Component,S extends AbstractCompositeField<C,S,T>>

Parameters:

value - the new value

getValue

public T getValue()

Description copied from interface: HasValue

Returns the current value of this object.

Implementation note: the implementing class should document whether null values may be returned or not, and override HasValue.getEmptyValue() if the empty value is not null.

Specified by:

getValue in interface HasValue<C extends Component,S extends AbstractCompositeField<C,S,T>>

Returns:

the current value

getEmptyValue

public T getEmptyValue()

Description copied from interface: HasValue

Returns the value that represents an empty value.

By default HasValue is expected to support null as empty values. Specific implementations might not support this.

Specified by:

getEmptyValue in interface HasValue<C extends Component,S extends AbstractCompositeField<C,S,T>>

Returns:

empty value

isEmpty

public boolean isEmpty()

Description copied from interface: HasValue

Returns whether this HasValue is considered to be empty.

By default this is an equality check between current value and empty value.

Specified by:

isEmpty in interface HasValue<C extends Component,S extends AbstractCompositeField<C,S,T>>

Returns:

true if considered empty; false if not

addValueChangeListener

public Registration addValueChangeListener(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<S,T>> listener)

Description copied from interface: HasValue

Adds a value change listener. The listener is called when the value of this HasValue is changed either by the user or programmatically.

Specified by:

addValueChangeListener in interface HasValue<C extends Component,S extends AbstractCompositeField<C,S,T>>

Parameters:

listener - the value change listener, not null

Returns:

a registration for the listener

setPresentationValue

protected abstract void setPresentationValue(T newPresentationValue)

Updates the presentation of this field to display the provided value. Subclasses should override this method to show the value to the user. This is typically done by setting an element property or by applying changes to child components.

If setModelValue(Object, boolean) is called from within this method, then value of the last invocation will be used as the model value instead of the value passed to this method. In this case setPresentationValue(Object) will not be called again. Changing the provided value might be useful if the provided value is sanitized.

See AbstractField for an overall description on the difference between model values and presentation values.

Parameters:

newPresentationValue - the new value to show

setModelValue

protected void setModelValue(T newModelValue,
                             boolean fromClient)

Updates the model value if the value has actually changed. Subclasses should call this method whenever the user has changed the value. A value change event is fired if the new value is different from the previous value according to valueEquals(Object, Object).

If the value is from the client-side and this field is in readonly mode, then the new model value will be ignored. setPresentationValue(Object) will be called with the previous model value so that the representation shown to the user can be reverted.

See AbstractField for an overall description on the difference between model values and presentation values.

Parameters:

newModelValue - the new internal value to use

fromClient - true if the new value originates from the client; otherwise false

valueEquals

protected boolean valueEquals(T value1,
                              T value2)

Compares to value instances to each other to determine whether they are equal. Equality is used to determine whether to update internal state and fire an event when setValue(Object) or setModelValue(Object, boolean) is called. Subclasses can override this method to define an alternative comparison method instead of Object.equals(Object).

Parameters:

value1 - the first instance

value2 - the second instance

Returns:

true if the instances are equal; otherwise false