CellNotifier<V> class
Adapts a ValueCell to Flutter's ValueNotifier contract as a read-only bridge.
CellNotifier is the binding's Listenable Adapter. It exposes a
ValueCell's value through the standard ValueNotifier<V?> interface so
that Flutter primitives built around Listenable — ValueListenableBuilder,
AnimatedBuilder, ListenableBuilder — can consume a cell without knowing
about the reactive graph. Reads are synchronous (the cell's storage is
read on .value); writes flow only from the cell's own observers, not
from outside.
Why it is used
- Flutter-native binding:
CellBuilderandCellSelectorboth build onCellNotifier. Any Flutter widget that takes a ValueListenable can take aCellNotifierdirectly. - Single observer per listener: the adapter owns exactly one
EgressHandleon the cell; several Flutter consumers of the same notifier share that one observation rather than each opening their own. - Synchronous read:
notifier.valuereturns the current value immediately — useful forselectprojections,initStateseeding, and testing.
How it works
- Subscribe: the constructor seeds the notifier with the cell's
current value and opens one
Cell.observelink on the cell. - Forward: each pulse assigns
pulse.payloadto the underlying ValueNotifier.value. Assigning on aValueNotifiernotifies its listeners, which Flutter widgets likeValueListenableBuilderreceive as a rebuild request. - Filter: error pulses (
pulse.type == 'error') are ignored — they are not values, and theValueNotifier<V?>contract has nowhere to put them. Display widgets that need to render errors subscribe to the cell directly (e.g. viaCellListenerorCellAsyncBuilder). - Dispose: the egress is stopped and the underlying notifier is disposed.
Design Note: CellNotifier is read-only by contract
CellNotifier extends ValueNotifier but overrides the value setter
to throw UnsupportedError. This is deliberate and load-bearing:
a writable ValueNotifier whose value diverges from its cell's value is
a silent bug — Flutter would rebuild on writes that the cell never
observed, and the two sources of truth would drift. Mutating the cell
instead (cell.value = ...) routes the change through the cell's
integrity gates and broadcasts it through the reactive graph, so every
dependent of the cell sees it — not just the widgets listening to this
one notifier.
Pulse semantics
- Data pulses assign to
super.valuesynchronously. See the Synchronous delivery note below for why this is intentional. - Error pulses are silently dropped. This is a display adapter, not an error surface.
- Type-mismatch pulses are not expected: the subscription is typed
Cell.observe<Pulse<V>>andPulse<V>.payloadis staticallyV?, so the payload type is consistent with the notifier's value type.
Synchronous delivery (read this)
super.value = pulse.payload is assigned synchronously in _onPulse.
If a pulse arrives while a sibling CellBuilder's subtree is mid-build,
this assignment marks the notifier's dependents dirty during the
build — which is exactly what we want: Flutter then raises its
"setState() or markNeedsBuild() called during build" framework error
instead of silently dropping the rebuild. The error is attributed to
the CellBuilder element, not to the widget that emitted the
pulse; the bug is the emission from inside build. Swallowing it would
hide the bug. Widgets that want the opposite — deferral to the end of
the frame — use CellValueBuilder, CellAsyncBuilder, or
CellListener, which manage a pending queue. The burden of correctness
falls on every cell that has a CellBuilder in the tree: never mutate
a cell from inside build.
Technical Details
- One egress per notifier: the adapter opens exactly one
Cell.observelink; disposing the notifier stops it. - Nullable
V?: the notifier exposesV?(notV), matching a not-yet-emitted cell.null is V-aware downstream widgets handle the nullable value. - Constructor-time validation: subscribing to an invalidated cell throws ArgumentError rather than producing a notifier that will never fire.
Example
final counter = Cell.state<int>(initial: 0);
final notifier = CellNotifier(counter.cell);
print(notifier.value); // 0
counter.update(5);
print(notifier.value); // 5
notifier.value = 42; // throws UnsupportedError
notifier.cell.value = 42; // correct: mutate the cell
notifier.dispose();
See Also:
- ValueNotifier — the Flutter primitive this extends.
CellBuilder— the widget that wrapsCellNotifierin aValueListenableBuilder.CellSelector— the widget that adds slice-based rebuild granularity on top ofCellNotifier.Cell.observe— the underlying observation primitive.
- Inheritance
-
- Object
- ChangeNotifier
- ValueNotifier<
V?> - CellNotifier
Constructors
-
CellNotifier(ValueCell<
V> cell) -
Subscribes to
celland seeds the notifier with its current value.
Properties
-
cell
→ ValueCell<
V> -
The cell being observed.
final
- hashCode → int
-
The hash code for this object.
no setterinherited
- hasListeners → bool
-
Whether any listeners are currently registered.
no setterinherited
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- value ↔ V?
-
The current value stored in this notifier.
getter/setter pairinherited-getteroverride-setter
Methods
-
addListener(
VoidCallback listener) → void -
Register a closure to be called when the object changes.
inherited
-
dispose(
) → void -
Stops observing cell and disposes the underlying ValueNotifier.
override
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
notifyListeners(
) → void -
Call all the registered listeners.
inherited
-
removeListener(
VoidCallback listener) → void -
Remove a previously registered closure from the list of closures that are
notified when the object changes.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited