BuildContext Extensions

The BuildContext class in Flutter provides information about the current widget in the tree. Reactter extends the BuildContext class with additional methods to make it easier to work with dependencies.

Reactter provides the following extensions for the BuildContext class:

• BuildContext.use
• BuildContext.watch
• BuildContext.watchId
• BuildContext.select

BuildContext.use

BuildContext.use is a method that gets an instance of T dependency from the nearest ancestor provider ( RtProvider or RtComponent ) of type T .

Syntax

T context.use<T>([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.
• 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.use :

• 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, the Counter widget uses BuildContext.use to get the instance of CounterController from the nearest ancestor provider (located in main.dart).

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

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.

BuildContext.watchId

BuildContext.watchId is a method similar to BuildContext.watch , but use id as first argument to locate the dependency.

Tip

This approach is useful when you have multiple dependencies of the same type and you want to access a specific one.

While you can use BuildContext.watch with id, BuildContext.watchId is more readable and clear when an id is required.

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

Syntax

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

• 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.
• id: An identifier for the T dependency. The dependency will be located by its type ( T ) and the id.
• 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.

Usage

This following example demonstrates how to use BuildContext.watchId :

• 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, the Counter widget uses BuildContext.watchId to get the instance of CounterController by its id from the nearest ancestor provider (located in main.dart) and listen for changes in the count state.

BuildContext.select

BuildContext.select is a method that computes a value whenever the selected states change and registers the current widget as a listener for these changes. Consequently, each time the selected states change, the value is recalculated and if it is different from the previous one, the widget is automatically notified and rebuilt.

Tip

BuildContext.select is useful when you need to render using a computed value based on multiple states. This aproach is more efficient than using BuildContext.watch because it avoids 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

V context.select<T, V>(
  V computeValue(T instance, RtState select(RtState state)),
  [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 select. It is used to locate the dependency from the nearest ancestor provider.
• V : The type of the value you want to compute. It is the return type of the computeValue function.
• computeValue : A function that computes the value based on the selected states. It takes two parameters:
  • instance: The instance of the dependency of type T .
  • select : A function that allows you to wrap the state ( RtState ) to be listened for changes and returns it.
• id: An optional identifier for the T dependency. If omitted, the dependency will be located by its type ( T ).

Tip

It’s a good idea to name the select parameter to something more simple and shorter like $ to make it easier to read and understand the selector function when you have multiple states to select.

RtSelector<UserController, String>(
  selector: (inst, $) => $(inst.firstName).value + ' ' + $(inst.lastName).value,
  builder: (context, inst, fullName, child) {
    return Text("Full name: $fullName");
  },
)

Usage

This following example demonstrates how to use BuildContext.select :

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

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

class CounterDivisible extends StatelessWidget {
  final int byNum;

  const CounterDivisible({Key? key, required this.byNum}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Select the `count` state from the `CounterController`,
    // calculate if the `count` is divisible by num(`byNum`)
    // and rebuild the widget tree when the value(`isDivisibleByNum`) changes
    final isDivisibleByNum = context.select<CounterController, bool>(
      (counterController, $) => $(counterController.count).value % byNum == 0,
    );

    return Text(
      isDivisibleByNum ? "Divisible by $byNum" : "Not divisible by $byNum",
    );
  }
}

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: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 '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(),
      ),
    );
  }
}

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--;
  }
}

In this example, checks if the count state from CounterController is divisible by a specified number (byNum). The BuildContext.select method is used to perform this check and rebuild the widget tree whenever the divisibility status changes.