registerFutureHandler<T extends Object, R> function

void registerFutureHandler<T extends Object, R>({
  1. Future<R> select(
    1. T
    )?,
  2. T? target,
  3. required void handler(
    1. BuildContext context,
    2. AsyncSnapshot<R?> newValue,
    3. void cancel()
    ),
  4. R? initialValue,
  5. String? instanceName,
  6. bool callHandlerOnlyOnce = false,
  7. bool allowFutureChange = false,
  8. GetIt? getIt,
})

registerFutureHandler registers a handler function for a Future exactly once on the first build and unregisters it when the widget is destroyed. This handler will only be called once when the Future completes. select allows you to register the handler to a member of the of the Object stored in GetIt. If you pass initialValue your passed handler will be executed immediately with that value. All handlers get passed in a cancel function that allows to kill the registration from inside the handler. If the Future has completed handler will be called every time until the handler calls cancel or the widget is destroyed

If you want to register a handler to a Future that is not registered in get_it you can pass it as target. if you pass null as select, T or target has to be a Future<R>. instanceName is the optional name of the instance if you registered it with a name in get_it. callHandlerOnlyOnce determines if the handler should be called only once when the future completes or every time the widget rebuilds after the completion

getIt is the optional instance of get_it to use if you don't want to use the default one. 99% of the time you won't need this.

Implementation

void registerFutureHandler<T extends Object, R>({
  Future<R> Function(T)? select,
  T? target,
  required void Function(BuildContext context, AsyncSnapshot<R?> newValue,
          void Function() cancel)
      handler,
  R? initialValue,
  String? instanceName,
  bool callHandlerOnlyOnce = false,
  bool allowFutureChange = false,
  GetIt? getIt,
}) {
  assert(_activeWatchItState != null,
      'registerFutureHandler can only be called inside a build function within a WatchingWidget or a widget using the WatchItMixin');

  final getItInstance = getIt ?? di;
  final parentObject = target ?? getItInstance<T>(instanceName: instanceName);

  // Validate target type when no select function is provided
  if (select == null && parentObject is! Future<R>) {
    throw ArgumentError(
        'When no select function is provided, target must be a Future<$R>. '
        'Got: ${parentObject.runtimeType}');
  }

  _activeWatchItState!.registerFutureHandler<T, R?>(
      parentOrFuture: parentObject,
      handler: handler,
      initialValueProvider: () => initialValue,
      instanceName: instanceName,
      allowMultipleSubscribers: true,
      callHandlerOnlyOnce: callHandlerOnlyOnce,
      selector: select,
      allowFutureChange: allowFutureChange);
}