Package com.vaadin.flow.component

Interface HasValue<E extends HasValue.ValueChangeEvent<V>,V>

Type Parameters:
E - the type of the value change event fired by this instance
V - the value type
All Superinterfaces:
Serializable
All Known Subinterfaces:
HasValueAndElement<E,V>, InputField<E,V>, MultiSelect<C,T>, SingleSelect<C,T>
All Known Implementing Classes:
AbstractCompositeField, AbstractField, AbstractNumberField, AbstractSinglePropertyField, BigDecimalField, Checkbox, CheckboxGroup, ComboBox, ComboBoxBase, CustomField, DatePicker, DateTimePicker, EmailField, Input, IntegerField, ListBox, ListBoxBase, MultiSelectComboBox, MultiSelectListBox, NumberField, PasswordField, RadioButtonGroup, RangeInput, RangeSlider, ReadOnlyHasValue, RichTextEditor, Select, Slider, TextArea, TextField, TextFieldBase, TimePicker
public interface HasValue<E extends HasValue.ValueChangeEvent<V>,V> extends Serializable
A generic interface for field components and other user interface objects that have a user-editable value. Emits change events whenever the value is changed, either by the user or programmatically.
Since:
1.0.
Author:
Vaadin Ltd

  • Method Details

    • setValue

      void setValue(V value)
      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 getEmptyValue() if the empty value is not null.

      Parameters:
      value - the new value
      Throws:
      IllegalArgumentException - if the value is invalid

    • getValue

      V getValue()
      Returns the current value of this object.

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

      Returns:
      the current value

    • addValueChangeListener

      Registration addValueChangeListener(HasValue.ValueChangeListener<? super E> listener)
      Adds a value change listener. The listener is called when the value of this HasValue is changed either by the user or programmatically.
      Parameters:
      listener - the value change listener, not null
      Returns:
      a registration for the listener

    • getEmptyValue

      default V getEmptyValue()
      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.

      Returns:
      empty value

    • getOptionalValue

      default Optional<V> getOptionalValue()
      Returns the current value of this object, wrapped in an Optional.

      The Optional will be empty if the value is null or isEmpty() returns true.

      Returns:
      the current value, wrapped in an Optional

    • isEmpty

      default boolean isEmpty()
      Returns whether this HasValue is considered to be empty.

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

      Returns:
      true if considered empty; false if not

    • clear

      default void clear()
      Resets the value to the empty one.

      This is just a shorthand for resetting the value, see the methods setValue(Object) and getEmptyValue().

      See Also:

    • setReadOnly

      void setReadOnly(boolean readOnly)
      Sets the read-only mode of this HasValue to given mode. The user can't change the value when in read-only mode.

      A HasValue with a visual component in read-only mode typically looks visually different to signal to the user that the value cannot be edited.

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

    • isReadOnly

      boolean isReadOnly()
      Returns whether this HasValue is in read-only mode or not.
      Returns:
      false if the user can modify the value, true if not.

    • setRequiredIndicatorVisible

      void setRequiredIndicatorVisible(boolean requiredIndicatorVisible)
      Sets the required indicator visible or not.

      If set visible, it is visually indicated in the user interface.

      The method is intended to be used with Binder which does server-side validation. In case HTML element has its own (client-side) validation it should be disabled when setRequiredIndicatorVisible(true) is called and re-enabled back on setRequiredIndicatorVisible(false). It's responsibility of each component implementation to follow the contract so that the method call doesn't do anything else than show/hide the "required" indication. Usually components provide their own setRequired method which should be called in case the client-side validation is required.

      Parameters:
      requiredIndicatorVisible - true to make the required indicator visible, false if not

    • isRequiredIndicatorVisible

      boolean isRequiredIndicatorVisible()
      Checks whether the required indicator is visible.
      Returns:
      true if visible, false if not

    • bindValue

      default void bindValue(Signal<V> valueSignal, SerializableConsumer<V> writeCallback)
      Binds a Signal's value to the value state of this component and keeps the state synchronized with the signal value while the element is in attached state. When the element is in detached state, signal value changes have no effect.

      While a Signal is bound to a value state, any attempt to bind a new Signal while one is already bound throws BindingActiveException.

      While a Signal is bound to a value state and the element is in attached state, setting the value with setValue(Object) or when a change originates from the client will invoke the write callback to propagate the value back. After the callback, the signal is re-consulted via Signal.peek() and if its value differs from what was being set, the new value is ignored and the signal's updated value is used instead, i.e. in cases where write callback has `signal.set("different")`, whereas a value being set is "a new value", the "different" value wins.

      If the write callback is null, the binding is read-only and any attempt to set the value while the element is attached will throw an IllegalStateException.

      Example of usage: 

       ValueSignal<String> signal = new ValueSignal<>("");
 Input component = new Input();
 add(component);
 component.bindValue(signal, signal::set);
 signal.set("Hello"); // The input's value changes
      Parameters:
      valueSignal - the signal to bind, not null
      writeCallback - the callback to propagate value changes back, or null for a read-only binding
      Throws:
      BindingActiveException - thrown when there is already an existing binding
      See Also:

    • bindReadOnly

      default void bindReadOnly(Signal<Boolean> readOnlySignal)
      Binds a Signal's value to the read-only state of this component and keeps the state synchronized with the signal value while the component is in attached state. When the component is in detached state, signal value changes have no effect.

      While a Signal is bound to the read-only state, any attempt to set the read-only state manually with setReadOnly(boolean) throws BindingActiveException. Same happens when trying to bind a new Signal while one is already bound.

      Example of usage: 

       ValueSignal<Boolean> signal = new ValueSignal<>(false);
 Input component = new Input();
 add(component);
 component.bindReadOnly(signal);
 signal.set(true); // The input becomes read-only
      Parameters:
      readOnlySignal - the signal to bind, not null
      Throws:
      BindingActiveException - thrown when there is already an existing binding
      See Also: