View Binding

BindingEngine bridges the gap between C++ ViewModels and native platform views. It manages the lifecycle of every binding — VM→View and View→VM — and handles thread marshalling automatically.

Include: #include "aria/binding/binding_engine.hpp"

---

BindingEngine

Construction

#include "aria/binding/binding_engine.hpp"
 
// The engine always needs an adapter — it is the only way it can reach
// your UI toolkit. `adapter` here is a std::shared_ptr<IViewAdapter>,
// e.g. std::make_shared<aria::adapters::QtAdapter>().
 
// Simplest: direct dispatch (single-threaded, no marshal)
aria::binding::BindingEngine engine{adapter};
 
// Production: SmartMarshal — auto-posts from background threads
aria::binding::BindingEngine engine(adapter, dispatcher,
    aria::binding::BindingEngine::DispatchPolicy::SmartMarshal);

Dispatch Policies

Policy	VM→View Path	Use Case
Direct	Synchronous, same thread	Single-threaded apps, tests
SmartMarshal	Direct on UI thread, post from background	Production apps
AlwaysPost	Always post via dispatcher	Tests needing deterministic ordering

---

One-Way Bindings (VM → View)

bind_text_oneway

aria::Property<std::string> status{"Ready"};
 
engine.bind_text_oneway(status, label_view);
// label displays "Ready"; updates when status changes

bind_visible / bind_enabled

aria::Property<bool> has_items{true};
 
engine.bind_visible(has_items, list_container);
engine.bind_enabled(can_submit, submit_button);

bind_int_oneway / bind_double_oneway

aria::Property<int> count{0};
aria::Property<double> progress{0.75};
 
engine.bind_int_oneway(count, badge_view);
engine.bind_double_oneway(progress, progress_bar);

bind_text_projected

Render any Property<T> into a read-only text view through a T -> std::string projection. This is the lightweight one-way alternative to a full bidirectional Converter when the view never writes back (labels, status lines):

aria::Property<int> unread{3};
 
engine.bind_text_projected(unread, badge_label,
    [](int n) { return std::to_string(n) + " new"; });
// label shows "3 new"; re-renders whenever `unread` changes

bind_optional_text

Bind a Property<std::optional<T>> to a read-only text view. When the optional holds a value it is rendered through the projection; when it is std::nullopt the view shows empty_text (default: empty string):

aria::Property<std::optional<std::string>> user{std::nullopt};
 
engine.bind_optional_text(user, welcome_label,
    [](const std::string& name) { return "Welcome, " + name; },
    "(signed out)");
// nullopt → "(signed out)"; user = "Alice" → "Welcome, Alice"

Async-agnostic by design. Both helpers operate purely on Property<T>, so BindingEngine stays decoupled from aria-async at the API level (the engine never names an AsyncCommand type). They are the idiomatic way to render an AsyncCommand's observable properties — last_error_message (a Property<std::string>) with bind_text_projected, and last_result (a Property<std::optional<R>>) with bind_optional_text — without teaching BindingEngine about coroutines. See View-Destroy Cancellation.

---

Two-Way Bindings (VM ↔ View)

Two-way bindings synchronize in both directions: VM changes update the view, and user input in the view writes back to the VM.

bind_text

aria::Property<std::string> query{""};
 
engine.bind_text(query, search_input);
// Typing in search_input → query.set(text)
// query.set("hello") → search_input displays "hello"

bind_bool

aria::Property<bool> dark_mode{false};
 
engine.bind_bool(dark_mode, toggle_switch);

bind_int / bind_double

aria::Property<int> quantity{1};
aria::Property<double> price{9.99};
 
engine.bind_int(quantity, spin_box);
engine.bind_double(price, price_input);

---

Command Bindings

bind_command (Parameterless)

aria::Command<> save{[&] { do_save(); }};
 
engine.bind_command(save, save_button);
// Button click → save.execute()
// save.can_execute() drives button.enabled automatically

bind_command (Parameterized)

aria::Command<std::string> open{[&](const std::string& path) { /* ... */ }};
 
engine.bind_command(open, button, "documents/report.pdf");
// Button click → open.execute("documents/report.pdf")

---

Converters

When the VM type doesn't match the view type, you have two options.

One-way display: bind_text_projected

For a read-only label, pass a plain projection functor (T -> std::string). No parsing back, no Converter needed:

aria::Property<bool> is_admin{true};
 
// Bool → string for display
engine.bind_text_projected(is_admin, role_label,
    [](bool v) -> std::string { return v ? "Admin" : "Guest"; });

Two-way: bind_text_converted

When the view must also write back, supply a Converter<T, std::string>:

#include "aria/binding/converter.hpp"
 
aria::Property<int> quantity{1};
 
auto conv = aria::binding::converters::int_to_string();
engine.bind_text_converted(quantity, quantity_field, conv);

On the View → Model direction a built-in converter reports unparseable input through try_to_model (returning std::nullopt) or by throwing ConversionError; in both cases the engine skips the model write, so the previous value stays authoritative rather than being clobbered with a default-constructed one.

Built-In Converters

All live in aria::binding::converters and return a Converter<T, U>:

Factory	From	To
identity_string()	string	string
int_to_string()	int	string
double_to_string(int precision = 2)	double	string
bool_to_yes_no()	bool	string ("yes" / "no"; parses yes/true/1 and no/false/0)

For anything else, construct a Converter<T, U> directly (or use bind_text_projected when the binding is one-way).

---

Feedback-Loop Suppression

Two-way bindings create a potential loop: VM change → view update → view callback → VM set (same value). The engine suppresses this automatically:

1. When pushing a value VM→View, the engine marks the binding as "writing"
2. The incoming View→VM callback checks this flag and skips if set
3. Result: no infinite ping-pong

---

View Lifetime

Views can be destroyed before the engine. When a view is destroyed:

1. IView::on_destroy fires
2. The engine releases all bindings to that view
3. Subsequent property changes silently skip the dead view
4. Other bindings in the same engine remain active

// View destroyed (e.g. user closes panel)
panel->close();  // triggers on_destroy
 
// Property changes no longer attempt to update panel
status.set("Done");  // no crash, no dangling reference

---

Clear All Bindings

engine.clear();  // Releases every binding in one shot

Called automatically in the engine's destructor.

---

IViewAdapter / IView

Platform adapters implement IViewAdapter to teach the engine how to talk to native widgets:

• IView — represents a single native widget (text getter/setter, visibility, enabled, destroy callback)
• IViewAdapter — factory that creates IView wrappers for platform controls

See adapter guides for platform-specific implementations:

• Qt6 →
• AppKit →
• UIKit →
• JNI / Android →

---

Quick Reference

Every binding the engine ships, with its direction and the source types it accepts. Two rules explain the whole table:

• One-way (VM→View) bindings accept any read-only reactive source — Property<T> or Computed<T> (formally, anything satisfying aria::ReadOnlyReactive). A derived value needs no mirror property.
• Two-way bindings accept Property<T> only. A Computed has no write-back path, so passing one is a compile error rather than a silently dropped edit.

Scalar bindings

Method	Direction	Source	View channel
bind_text	Two-way	Property<string>	text input
bind_text_oneway	VM→View	Property<string> / Computed<string>	label text
bind_bool	Two-way	Property<bool>	checkbox / switch
bind_bool_oneway	VM→View	Property<bool> / Computed<bool>	checkbox / switch
bind_int	Two-way	Property<int>	spin box / slider
bind_int_oneway	VM→View	Property<int> / Computed<int>	spin box / progress bar
bind_int64	Two-way	Property<int64_t>	64-bit numeric input
bind_int64_oneway	VM→View	Property<int64_t> / Computed<int64_t>	64-bit numeric display
bind_uint64	Two-way	Property<uint64_t>	unsigned numeric input
bind_uint64_oneway	VM→View	Property<uint64_t> / Computed<uint64_t>	unsigned numeric display
bind_float	Two-way	Property<float>	slider / opacity
bind_float_oneway	VM→View	Property<float> / Computed<float>	slider / opacity
bind_double	Two-way	Property<double>	slider / double spin box
bind_double_oneway	VM→View	Property<double> / Computed<double>	numeric display

Text projection and conversion

Method	Direction	Source	Notes
bind_text_projected	VM→View	any ReadOnlyReactive of T	renders via T → string; the everyday "formatted label" binding
bind_optional_text	VM→View	any ReadOnlyReactive of optional<T>	renders *opt via T → string; nullopt shows empty_text
bind_text_converted	Two-way	Property<T>	full Converter<T, string>, parses text back into T
bind_text_converted_oneway	VM→View	any ReadOnlyReactive of T	uses only the converter's to_view

State, commands, lifetime

Method	Direction	Source	Notes
bind_visible	VM→View	Property<bool> / Computed<bool>	inherently one-way — the view never writes visibility back
bind_enabled	VM→View	Property<bool> / Computed<bool>	inherently one-way
bind_command	View→VM	Command<Args...>	click → execute(args...); also drives enabled from can_execute(args...)
bind_view_lifetime	—	std::function<void()>	fires once on view-destroy (or engine teardown); use to cancel in-flight async work
adopt	—	Subscription	hands an arbitrary subscription to the view's per-view bucket, released on view-destroy

When no binding fits, write the on_changed by hand and hand the resulting Subscription to adopt(view, std::move(sub)). That keeps the lifetime story identical to a real binding — released on view-destroy — and avoids the usual workaround of a long-lived subscription vector that never releases anything.

Composite labels are the common case: a binding has exactly one source, so a label reading two values either gets a Computed on the ViewModel that combines them (then it is a one-line bind_text_oneway), or stays a manual on_changed + adopt.

Binding a derived value

// ViewModel
Property<double> bill{20.0};
Property<int>    people{2};
Computed<double> per_person{[this] { return bill.get() / people.get(); }};
 
// View — Computed binds directly; no mirror Property, no manual on_changed.
engine.bind_text_projected(vm.per_person, label,
    [](double v) { return std::format("¥ {:.2f}", v); });
 
engine.bind_text(vm.per_person, input);   // ✗ compile error: not writable

---

See Also

• ViewModel → — the VM side of the binding
• Reactive Core → — Property and Command that bindings consume
• Lifecycle & Threading → — thread-affinity and dispatch policies

Adapter callbacks from worker threads

For HTTP input, construct the engine with the graph owner's dispatcher and BindingEngine::DispatchPolicy::SmartMarshal (or AlwaysPost). These policies apply to both binding directions, including converted text and commands. Direct requires callbacks to already run on the graph thread. Keep binding setup, teardown, Property and Command lifetimes on that thread. Posted input is discarded if its view binding is cleared or destroyed before delivery.