template class EE::UI::UIDataBind

Overview

Synchronizes a value with one or more UIWidget properties. More…

#include <uidatabind.hpp>

template <typename T>
class UIDataBind {
public:
    // typedefs

    typedef UIValueConverter<T> Converter;

    // fields

    std::function<void(const T&newVal)> onValueChangeCb;

    // construction

    UIDataBind();
    UIDataBind(const UIDataBind&);
    UIDataBind(UIDataBind&&);
    UIDataBind(T* t, const UnorderedSet<UIWidget*>& widgets, const Converter& converter = Converter::converterDefault(), const std::string& valueKey = "value", const Event::EventType& eventType = Event::OnValueChange);
    UIDataBind(T* t, UIWidget* widget, const Converter& converter = Converter::converterDefault(), const std::string& valueKey = "value", const Event::EventType& eventType = Event::OnValueChange);
    ~UIDataBind();

    // methods

    static Converter converterDefault();
    static Converter converterString();
    static Converter converterBool();
    static std::unique_ptr<UIDataBind<T>> New(T* t, const UnorderedSet<UIWidget*>& widgets, const Converter& converter = Converter::converterDefault(), const std::string& valueKey = "value", const Event::EventType& eventType = Event::OnValueChange);
    static std::unique_ptr<UIDataBind<T>> New(T* t, UIWidget* widget, const Converter& converter = Converter::converterDefault(), const std::string& valueKey = "value", const Event::EventType& eventType = Event::OnValueChange);
    UIDataBind& operator=(const UIDataBind&);
    UIDataBind& operator=(UIDataBind&&);
    void init(T* t, const UnorderedSet<UIWidget*>& widgets, const Converter& converter = Converter::converterDefault(), const std::string& valueKey = "value", const Event::EventType& eventType = Event::OnValueChange);
    UIValueValidationResult set(const T& t);
    UIValueValidationResult set(T&& t);
    const T& get() const;
    bool isInitialized() const;
    void reset();
    void bind(UIWidget* widget);
    void unbind(UIWidget* widget);
    const PropertyDefinition* getPropertyDefinition() const;
    const UnorderedSet<UIWidget*>& getWidgets() const;
    UIValueValidationState& validationState();
    const UIValueValidationState& validationState() const;
    bool isValid() const;
};

Detailed Documentation

Synchronizes a value with one or more UIWidget properties.

UIDataBind observes each widget’s value event and writes converted values back to the external object supplied at construction. Calling set() updates that object and propagates the converted value to every bound widget.

The converter maps directly between T and the widget property string. Its toValue() callback decides whether widget input is acceptable. Values passed to set() are authoritative model state and are formatted through fromValue().

Warning

The external object is not owned. It must outlive the UIDataBind, or reset() must be called before that object is destroyed. UIProperty is the owning alternative when the value should have the same lifetime as its binding.

Widgets are also observed without ownership: EventConnection handles remove listeners when the binding dies, while the widget-level Event::OnClose notification removes widgets that die before the binding. All binding operations and widget events must run on the widgets’ owning UI thread. The class is non-copyable and non-movable because its listeners capture its address.

Use UIDataBind when adapting an existing externally owned value and its lifetime is already controlled by the caller. Prefer UIProperty for small UI-local state, or ObservableValue with UIValueBinding when the model must publish changes without depending on the UI.

bool showDetails = false;
auto binding = UIDataBind<bool>::New(
    &showDetails, checkbox, UIValueConverter<bool>::converterBool() );
// 'binding' must be destroyed or reset before 'showDetails'.

Methods

UIValueValidationResult set(const T& t)

Propagates the authoritative model value and reports formatting failures.

UIValueValidationResult set(T&& t)

Propagates the authoritative model value and reports formatting failures.

bool isInitialized() const

Returns:

True when the binding has a valid external value, property, and converter.

void reset()

Disconnects every widget and releases the reference to the external value.

After reset(), the binding must be initialized again before get() or set() is used.

void bind(UIWidget* widget)

Adds widget to the synchronized widget set. Duplicate binds are ignored.

void unbind(UIWidget* widget)

Disconnects and removes widget from the synchronized widget set.

UIValueValidationState& validationState()

Returns:

Observable converter error state for this binding.