StreamBuilder< T> class
Widget that builds itself based on the latest snapshot of interaction with a Stream.
Widget rebuilding is scheduled by each interaction, using State.setState, but is otherwise decoupled from the timing of the stream. The builder is called at the discretion of the Flutter pipeline, and will thus receive a timing-dependent sub-sequence of the snapshots that represent the interaction with the stream.
As an example, when interacting with a stream producing the integers 0 through 9, the builder may be called with any ordered sub-sequence of the following snapshots that includes the last one (the one with ConnectionState.done):
new AsyncSnapshot<int>.withData(ConnectionState.waiting, null)
new AsyncSnapshot<int>.withData(ConnectionState.active, 0)
new AsyncSnapshot<int>.withData(ConnectionState.active, 1)
- ...
new AsyncSnapshot<int>.withData(ConnectionState.active, 9)
new AsyncSnapshot<int>.withData(ConnectionState.done, 9)
The actual sequence of invocations of the builder depends on the relative timing of events produced by the stream and the build rate of the Flutter pipeline.
Changing the StreamBuilder configuration to another stream during event generation introduces snapshot pairs of the form:
new AsyncSnapshot<int>.withData(ConnectionState.none, 5)
new AsyncSnapshot<int>.withData(ConnectionState.waiting, 5)
The latter will be produced only when the new stream is non-null, and the former only when the old stream is non-null.
The stream may produce errors, resulting in snapshots of the form:
new AsyncSnapshot<int>.withError(ConnectionState.active, 'some error')
The data and error fields of snapshots produced are only changed when the
state is ConnectionState.active
.
The initial snapshot data can be controlled by specifying initialData. This should be used to ensure that the first frame has the expected value, as the builder will always be called before the stream listener has a chance to be processed.
_lot
field is
set by a selector elsewhere in the UI.
StreamBuilder<int>(
stream: _lot?.bids, // a Stream<int> or null
builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
if (snapshot.hasError)
return Text('Error: ${snapshot.error}');
switch (snapshot.connectionState) {
case ConnectionState.none: return Text('Select lot');
case ConnectionState.waiting: return Text('Awaiting bids...');
case ConnectionState.active: return Text('\$${snapshot.data}');
case ConnectionState.done: return Text('\$${snapshot.data} (closed)');
}
return null; // unreachable
},
)
See also:
- ValueListenableBuilder, which wraps a ValueListenable instead of a Stream.
- StreamBuilderBase, which supports widget building based on a computation that spans all interactions made with the stream.
- Inheritance
- Object
- Diagnosticable
- DiagnosticableTree
- Widget
- StatefulWidget
- StreamBuilderBase<
T, AsyncSnapshot< T>> - StreamBuilder
Constructors
-
StreamBuilder({Key key, T initialData, Stream<
T> stream, @required AsyncWidgetBuilder< T> builder }) -
Creates a new StreamBuilder that builds itself based on the latest
snapshot of interaction with the specified
stream
and whose build strategy is given bybuilder
. [...]const
Properties
-
builder
→ AsyncWidgetBuilder<
T> -
The build strategy currently used by this builder.
final
- initialData → T
-
The data that will be used to create the initial snapshot. [...]
final
- hashCode → int
-
The hash code for this object. [...]
read-only, inherited
- key → Key
-
Controls how one widget replaces another widget in the tree. [...]
final, inherited
- runtimeType → Type
-
A representation of the runtime type of the object.
read-only, inherited
-
stream
→ Stream<
T> -
The asynchronous computation to which this builder is currently connected,
possibly null. When changed, the current summary is updated using
afterDisconnected, if the previous stream was not null, followed by
afterConnected, if the new stream is not null.
final, inherited
Methods
-
afterConnected(
AsyncSnapshot< T> current) → AsyncSnapshot< T> -
Returns an updated version of the
current
summary reflecting that we are now connected to a stream. [...]override -
afterData(
AsyncSnapshot< T> current, T data) → AsyncSnapshot< T> -
Returns an updated version of the
current
summary following a data event. [...]override -
afterDisconnected(
AsyncSnapshot< T> current) → AsyncSnapshot< T> -
Returns an updated version of the
current
summary reflecting that we are no longer connected to a stream. [...]override -
afterDone(
AsyncSnapshot< T> current) → AsyncSnapshot< T> -
Returns an updated version of the
current
summary following stream termination. [...]override -
afterError(
AsyncSnapshot< T> current, Object error) → AsyncSnapshot< T> -
Returns an updated version of the
current
summary following an error. [...]override -
build(
BuildContext context, AsyncSnapshot< T> currentSummary) → Widget -
Returns a Widget based on the
currentSummary
.override -
initial(
) → AsyncSnapshot< T> -
Returns the initial summary of stream interaction, typically representing
the fact that no interaction has happened at all. [...]
override
-
createElement(
) → StatefulElement -
Creates a StatefulElement to manage this widget's location in the tree. [...]
inherited
-
createState(
) → State< StreamBuilderBase< T, AsyncSnapshot< T>>> -
Creates the mutable state for this widget at a given location in the tree. [...]
inherited
-
debugDescribeChildren(
) → List< DiagnosticsNode> -
Returns a list of DiagnosticsNode objects describing this node's
children. [...]
@protected, inherited
-
debugFillProperties(
DiagnosticPropertiesBuilder properties) → void -
Add additional properties associated with the node. [...]
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a non-existent method or property is accessed. [...]
inherited
-
toDiagnosticsNode(
{String name, DiagnosticsTreeStyle style }) → DiagnosticsNode -
Returns a debug representation of the object that is used by debugging
tools and by toStringDeep. [...]
inherited
-
toString(
{DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String -
Returns a string representation of this object.
inherited
-
toStringDeep(
{String prefixLineOne: '', String prefixOtherLines, DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String -
Returns a string representation of this node and its descendants. [...]
inherited
-
toStringShallow(
{String joiner: ', ', DiagnosticLevel minLevel: DiagnosticLevel.debug }) → String -
Returns a one-line detailed description of the object. [...]
inherited
-
toStringShort(
) → String -
A short, textual description of this widget.
inherited
Operators
-
operator ==(
dynamic other) → bool -
The equality operator. [...]
inherited