BuildContext.watch

BuildContext.watch is a method similar to BuildContext.use , but with an added functionality. It not only retrieves the T dependency but also registers the current widget as a listener for any changes to the states set or otherwise any changes in the T dependency. Consequently, whenever changes, the widget using BuildContext.watch is automatically notified and rebuilt.

Tip

You can optionally use BuildContext.watch with an id, but when you need to listen changes in a dependency’s states using an id, it’s better to use BuildContext.watchId for improved readability and clarity.

context.watch<MyDependency>(null, 'myId');
// is equivalent to
context.watchId<MyDependency>('myId');

Caution

To render using a computed value based on multiple states, use BuildContext.select instead of BuildContext.watch or pre-compute the value using UseCompute to prevent unnecessary rebuilds.

Show me an example and explanation

[...]
build(BuildContext context) {
  final product = context.watch<Product>(
    (product) => [product.price, product.quantity],
  );
  final total = product.price.value + product.quantity.value;

  return Text("Total: $total");
}

// is equivalent to

[...]
build(BuildContext context) {
  final total = context.select<Product>(
    (product, $) {
      // The `$(...)` syntax is used to select a specific state to listen for changes.
      return $(product.price).value + $(product.quantity).value;
    },
  );

  return Text("Total: $total");
}

In the example above, we use context.watch and context.select to calculate the total price of a product based on its unit price and quantity. These methods update the UI when certain dependencies change, but they have different performance implications.

When using context.watch , the widget will rebuild whenever any of the dependencies change, even if the change in state does not affect the calculated value. This can lead to unnecessary rebuilds and reduced performance.

In contrast, context.select allows you to listen for specific state changes and only rebuilds when the calculated value (total) changes. This approach is more efficient as it avoids unnecessary rebuilds, leading to better performance.

Syntax & description

T context.watch<T>([
  List<RtState> listenStates?(T instance),
  String? id,
]);

• context: The BuildContext object, which provides information about the current widget in the tree.
• T : The type of the dependency you want to access. These are some points to consider:
  • If the type is nullable, the method will return null if the dependency is not found.
  • If the type is not nullable, the method will throw an exception if the dependency is not found.
• listenStates : An optional function that returns a list of state( RtState ) to listen for changes. If omitted, the method will listen for any changes in the T dependency.
• id: An optional identifier for the T dependency. If omitted, the dependency will be located by its type( T ).

Usage

This following example demonstrates how to use BuildContext.watch :

• counter.dart
• counter_view.dart
• counter_controller.dart
• main.dart

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';

class Counter extends StatelessWidget {
  const Counter({Key? key, this.id}) : super(key: key);

  final String? id;

  @override
  Widget build(BuildContext context) {
    // Locale the `CounterController` dependency
    final counterController = context.use<CounterController>(id);

    return Row(
      mainAxisSize: MainAxisSize.min,
      children: [
        ElevatedButton(
          onPressed: counterController.decrement,
          child: const Icon(Icons.remove),
        ),
        const SizedBox(width: 8),
        // Observe the `count` property of the `counterController`
        // and rebuild the widget tree when the `count` value changes
        Builder(
          builder: (context) {
            if (id != null) {
              context.watchId<CounterController>(id!, (inst) => [inst.count]);
            } else {
              context.watch<CounterController>((inst) => [inst.count]);
            }

            return Text("${counterController.count}");
          },
        ),
        const SizedBox(width: 8),
        ElevatedButton(
          onPressed: counterController.increment,
          child: const Icon(Icons.add),
        ),
      ],
    );
  }
}

import 'package:flutter/material.dart';
import 'counter.dart';

class CounterView extends StatelessWidget {
  const CounterView({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Counter"),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            const Counter(),
            const SizedBox(height: 8),
            FutureBuilder(
              future: Future.delayed(Duration(seconds: 1)),
              builder: (context, snapshot) {
                if (snapshot.connectionState != ConnectionState.done) {
                  return const CircularProgressIndicator();
                }

                return const Counter(id: "counterLazy");
              },
            ),
          ],
        ),
      ),
    );
  }
}

import 'package:reactter/reactter.dart';

class CounterController {
  // Create a reactive state using the `Signal` class
  final count = Signal(0);

  void increment() {
    count.value++;
  }

  void decrement() {
    count.value--;
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_reactter/flutter_reactter.dart';
import 'counter_controller.dart';
import 'counter_view.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: RtMultiProvider(
        [
          RtProvider(() => CounterController()),
          RtProvider.lazy(() => CounterController(), id: 'counterLazy'),
        ],
        child: CounterView(),
      ),
    );
  }
}

In this example, we use BuildContext.watch to get the instance of CounterController from the nearest ancestor provider(located in main.dart) and listen for changes in the count state.