Proposal for the coming get_it mixin for Widgets as I was asked by users to help binding the UI to the objects in GetIt. Highly inspired by @remi_rousselet 's Hooks and provider in this aspect. For people using Hooks I plan a similar GetItHook. Please tell me what you think
/// all the following functions can be called inside the build function but also
/// in e.g. in `initState` of a `StatefulWidget`.
/// The mixin takes care that everything is correctly disposed.
/// retrieves or creates an instance of a registered type [T] depending on the registration
/// function used for this type or based on a name.
/// for factories you can pass up to 2 parameters [param1,param2] they have to match the types
/// given at registration with [registerFactoryParam()]
T get<T>({String instanceName, dynamic param1, dynamic param2});
/// like [get] but for async registrations
Future<T> getAsync<T>({String instanceName, dynamic param1, dynamic param2});
/// like [get] but with an additional [select] function to return a member of [T]
R getX<T, R>(R Function(T) accessor, {String instanceName});
/// like [get] but it also registers a listener to [T] and
/// triggers a rebuild everytime [T] signals a change
T watch<T extends Listenable>({String instanceName});
/// like [get] but it also registers a listener to the result of [select] and
/// triggers a rebuild everytime signals [R] a change
/// useful if the `Listenable` [R] is a member of your business object [T]
R watchX<T, R extends Listenable>(
R Function(T) select, {
String instanceName,
});
/// like watch but it only triggers a rebuild when the value that the function
/// [only] returns changes. With that you can react to changes of single members
/// of [T]
T watchOnly<T extends Listenable>(
Object Function(T) only, {
String instanceName,
});
/// a combination of [watchX] and [watchOnly]
R watchXOnly<T, Q extends Listenable, R>(
Q Function(T) select,
Object Function(R) only, {
String instanceName,
});
/// subscribes to the `Stream` returned by [select] and returns
/// an `AsyncSnapshot` with the latest received data from the `Stream`
/// Whenever new data is received it triggers a rebuild.
/// When you call [watchStream] a second time on the same `Stream` it will
/// return the last received data but not subscribe another time.
/// To be able to use [watchStream] inside a `build` function we have to pass
/// [initialValue] so that it can return something before it has received the first data
AsyncSnapshot<R> watchStream<T, R>(
Stream<R> Function(T) select,
R initialValue, {
String instanceName,
});
/// awaits the ` Future` returned by [select] and triggers a rebuild as soon
/// as the `Future` completes. After that it returns
/// an `AsyncSnapshot` with the received data from the `Future`
/// When you call [watchFuture] a second time on the same `Future` it will
/// return the last received data but not await another time.
/// To be able to use [watchStream] inside a `build` function
/// we have to pass [initialValue] so that it can return something before
/// the `Future` has completed
AsyncSnapshot<R> watchFuture<T, R>(
Stream<R> Function(T) select,
R initialValue, {
String instanceName,
});
/// Pushes a new GetIt-Scope. After pushing it executes [init] where you can register
/// objects that should only exist as long as this scope exists.
/// Can be called inside the `build` method method of a `StatelessWidget`.
/// It ensures that it's only called once in the lifetime of a widget.
/// When the widget is destroyed the scope too gets destroyed after [dispose]
/// is executed. If you use this function and you have registered your objects with
/// an async disposal function, that functions won't be awaited.
/// I would recommend doing pushing and popping from your business layer but sometimes
/// this might come in handy
void pushScope({void Function(GetIt getIt) init, void Function() dispose});