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. You would use this facility to ensure that if the builder is invoked before the first event arrives on the stream, the snapshot carries data of your choice rather than the default null value.

See also:

  • StreamBuilderBase, which supports widget building based on a computation that spans all interactions made with the stream.

Sample code

This sample shows a StreamBuilder configuring a text label to show the latest bid received for a lot in an auction. Assume the _lot field is set by a selector elsewhere in the UI.

new StreamBuilder<int>(
  stream: _lot?.bids, // a Stream<int> or null
  builder: (BuildContext context, AsyncSnapshot<int> snapshot) {
    if (snapshot.hasError)
      return new Text('Error: ${snapshot.error}');
    switch (snapshot.connectionState) {
      case ConnectionState.none: return new Text('Select lot');
      case ConnectionState.waiting: return new Text('Awaiting bids...');
      case ConnectionState.active: return new Text('\$${snapshot.data}');
      case ConnectionState.done: return new Text('\$${snapshot.data} (closed)');
    }
  },
)
Inheritance

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 by builder. The initialData is used to create the initial snapshot. It is null by default.
const

Properties

builder AsyncWidgetBuilder<T>
The build strategy currently used by this builder. Cannot be null.
final
initialData → T
The data that will be used to create the initial snapshot. Null by default.
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. [...]
afterData(AsyncSnapshot<T> current, T data) AsyncSnapshot<T>
Returns an updated version of the current summary following a data event. [...]
afterDisconnected(AsyncSnapshot<T> current) AsyncSnapshot<T>
Returns an updated version of the current summary reflecting that we are no longer connected to a stream. [...]
afterDone(AsyncSnapshot<T> current) AsyncSnapshot<T>
Returns an updated version of the current summary following stream termination. [...]
afterError(AsyncSnapshot<T> current, Object error) AsyncSnapshot<T>
Returns an updated version of the current summary following an error. [...]
build(BuildContext context, AsyncSnapshot<T> currentSummary) Widget
Returns a Widget based on the currentSummary.
initial() AsyncSnapshot<T>
Returns the initial summary of stream interaction, typically representing the fact that no interaction has happened at all. [...]
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