class EE::UI::UIBindingGroup

Overview

Owns heterogeneous bindings and exposes aggregate form state. More…

#include <uibindinggroup.hpp>

class UIBindingGroup {
public:
    // typedefs

    typedef SmallVector<Error, 4> Errors;
    typedef SmallVector<UIWidget*, 4> Widgets;
    typedef std::function<void()> Callback;

    // structs

    struct Entry;
    struct Error;

    template <typename T>
    struct ObservableEntry;

    template <typename T>
    struct PropertyEntry;

    template <typename T>
    struct RawEntry;

    // construction

    UIBindingGroup();
    UIBindingGroup(const UIBindingGroup&);
    UIBindingGroup(UIBindingGroup&&);
    ~UIBindingGroup();

    // methods

    UIBindingGroup& operator=(const UIBindingGroup&);
    UIBindingGroup& operator=(UIBindingGroup&&);

    template <typename T>
    UIBindingGroup& hold(UIValueBinding<T>&& binding);

    template <typename T>
    UIBindingGroup& operator+=(UIValueBinding<T>&& binding);

    template <typename T>
    UIBindingGroup& hold(std::unique_ptr<UIDataBind<T>> binding);

    template <typename T>
    UIBindingGroup& operator+=(std::unique_ptr<UIDataBind<T>> binding);

    template <typename T>
    UIBindingGroup& hold(UIProperty<T>& property);

    template <typename T>
    UIBindingGroup& operator+=(UIProperty<T>& property);

    bool isValid() const;
    bool isDirty() const;
    ObservableValue<bool>& validValue();
    ObservableValue<bool>& dirtyValue();
    Errors errors() const;
    Widgets widgets() const;
    UIWidget* firstInvalidWidget() const;
    void markClean();
    void reset();
    void clear();
    std::size_t size() const;
    void onChange(Callback callback);
};

Detailed Documentation

Owns heterogeneous bindings and exposes aggregate form state.

Dirty state compares live values with explicit per-binding baselines. The group owns bindings, but never owns their widgets or model values. Disabled widgets are excluded from aggregate validation. clear() and destruction disconnect all bindings.

UIBindingGroup form;
form += bindValue( name, nameInput, requiredName );
form += bindValue( port, portInput, validPort );
auto canSave = computedValue( form.validValue(), form.dirtyValue(),
                              []( bool valid, bool dirty ) { return valid && dirty; } );

Typedefs

typedef SmallVector<Error, 4> Errors

Inline-backed error collection sized for ordinary forms.

typedef SmallVector<UIWidget*, 4> Widgets

Inline-backed widget collection sized for ordinary forms.

Methods

template <typename T>
UIBindingGroup& hold(UIValueBinding<T>&& binding)

Adds and takes ownership of a typed binding.

Returns:

This group, allowing several bindings to be added in one expression.

template <typename T>
UIBindingGroup& hold(std::unique_ptr<UIDataBind<T>> binding)

Adds and takes ownership of a legacy UIDataBind.

template <typename T>
UIBindingGroup& hold(UIProperty<T>& property)

Tracks a UIProperty without taking ownership of it.

The entry expires safely if property is destroyed first. Its current value becomes the initial clean baseline.

template <typename T>
UIBindingGroup& operator+=(UIProperty<T>& property)

Convenience form of hold(UIProperty<T>&).

bool isValid() const

Disabled fields are intentionally ignored, which supports conditional form sections.

Returns:

true when every binding attached to an enabled widget is valid.

bool isDirty() const

Returns:

true when at least one value differs from its current clean baseline.

ObservableValue<bool>& validValue()

Returns:

Observable aggregate validity, suitable for computed values and commands.

ObservableValue<bool>& dirtyValue()

Returns:

Observable aggregate dirty state, suitable for computed values and commands.

Errors errors() const

Returns:

Invalid enabled bindings in insertion order.

Widgets widgets() const

The order within a legacy multi-widget UIDataBind or UIProperty is unspecified.

Returns:

Connected widgets grouped by binding insertion order.

UIWidget* firstInvalidWidget() const

Returns:

The first invalid enabled widget in insertion order, or nullptr.

void markClean()

Makes every binding’s current value its new clean/reset baseline.

void reset()

Restores every binding to the baseline recorded at insertion or markClean().

void clear()

Destroys all owned bindings and resets aggregate state.

std::size_t size() const

Returns:

The number of bindings owned by the group.

void onChange(Callback callback)

Replaces the callback invoked after a relevant group event.

A non-empty callback is invoked once immediately, then after value, validation, enabled-state, baseline, or membership changes. Use validValue() /dirtyValue() when only aggregate transitions matter, since those observables suppress equal values.