Class AbstractField<C extends AbstractField<C,T>,T>
- Type Parameters:
C
- the source type for value change eventsT
- the value type
- All Implemented Interfaces:
AttachNotifier
,DetachNotifier
,HasElement
,HasEnabled
,HasStyle
,HasValue<AbstractField.ComponentValueChangeEvent<C,
,T>, T> HasValueAndElement<AbstractField.ComponentValueChangeEvent<C,
,T>, T> Serializable
- Direct Known Subclasses:
AbstractSinglePropertyField
,CustomField
Component
allowing user
input. Implements HasValue
to represent the input value. Examples of
typical field components include text fields, date pickers, and check boxes.
The field value is represented in two separate ways:
- A presentation value that is shown to the user. This is typically represented in the component's server-side DOM element or through child components.
- A model value that is available for programmatic use through the
HasValue
interface. This representation is handled by this class and should not be directly accessed by subclasses.
In order to keep the two value representations in sync with each other, subclasses must take care of the two following things:
- Listen to changes from the user, and call
setModelValue(Object, boolean)
with an updated value. - Implement
setPresentationValue(Object)
to update the presentation value of the component so that the new value is shown to the user.
This class extends Component
, which means that it cannot be used for
adding field functionality to an existing component without changing the
superclass of that component. As an alternative, you can use
AbstractCompositeField
to instead wrap an instance of the existing
component.
- Since:
- 1.0
- Author:
- Vaadin Ltd
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
Value change event fired by components.Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue
HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>
-
Constructor Summary
ConstructorDescriptionAbstractField
(Element element, T defaultValue) Creates a new field with the given element instance.AbstractField
(T defaultValue) Creates a new field with an element created based on theTag
annotation of the sub class. -
Method Summary
Modifier and TypeMethodDescriptionaddValueChangeListener
(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<C, T>> listener) Adds a value change listener.Returns the value that represents an empty value.getValue()
Returns the current value of this object.boolean
isEmpty()
Returns whether thisHasValue
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
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.Component
addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, 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.HasStyle
addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName
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 Details
-
AbstractField
Creates a new field with an element created based on theTag
annotation of the sub class. The provided default value is used bygetEmptyValue()
and as the initial model value of this instance.- Parameters:
defaultValue
- the default value for fields of this type
-
AbstractField
Creates a new field with the given element instance. he provided default value is used bygetEmptyValue()
and as the initial model value of this instance.- Parameters:
element
- the root element for the componentdefaultValue
- the default value for fields of this type
-
-
Method Details
-
addValueChangeListener
public Registration addValueChangeListener(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<C, T>> listener) Description copied from interface:HasValue
Adds a value change listener. The listener is called when the value of thisHasValue
is changed either by the user or programmatically.- Specified by:
addValueChangeListener
in interfaceHasValue<C extends AbstractField<C,
T>, T> - Parameters:
listener
- the value change listener, not null- Returns:
- a registration for the listener
-
setValue
Description copied from interface:HasValue
Sets the value of this object. If the new value is not equal togetValue()
, fires a value change event. May throwIllegalArgumentException
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 notnull
. -
setPresentationValue
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, the value of the last invocation will be used as the model value instead of the value passed to this method. In this casesetPresentationValue(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
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 tovalueEquals(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 usefromClient
-true
if the new value originates from the client; otherwisefalse
-
valueEquals
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 whensetValue(Object)
orsetModelValue(Object, boolean)
is called. Subclasses can override this method to define an alternative comparison method instead ofObject.equals(Object)
.- Parameters:
value1
- the first instancevalue2
- the second instance- Returns:
true
if the instances are equal; otherwisefalse
-
isEmpty
public boolean isEmpty()Description copied from interface:HasValue
Returns whether thisHasValue
is considered to be empty.By default this is an equality check between current value and empty value.
-
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 notnull
. -
getEmptyValue
Description copied from interface:HasValue
Returns the value that represents an empty value.By default
HasValue
is expected to supportnull
as empty values. Specific implementations might not support this.- Specified by:
getEmptyValue
in interfaceHasValue<C extends AbstractField<C,
T>, T> - Returns:
- empty value
-