If objects that are registered inside GetIt implements Disposable the
onDispose method will be called whenever that Object is unregistered,
resetted or its enclosing Scope is popped
Very simple and easy to use service locator
You register your object creation factory or an instance of an object with registerFactory,
registerSingleton or registerLazySingleton
And retrieve the desired object using get or call your locator as function as its a
callable class
Additionally GetIt offers asynchronous creation functions as well as functions to synchronize
the async initialization of multiple Singletons
If an object implements the ShadowChangeHandler if will get notified if
an Object with the same registration type and name is registered on a
higher scope which will shadow it.
It also will get notified if the shadowing object is removed from GetIt
If your singleton that you register wants to use the manually signalling
of its ready state, it can implement this interface class instead of using
the signalsReady parameter of the registration functions
(you don't really have to implement much ;-) )
WatchIt exports the default instance of get_it as a global variable which lets
you access it from anywhere in your app. To access any get_it registered
object you only have to type di<MyType>() instead of GetIt.I<MyType>().
if you don't want to use a different instance of get_it you can pass it to
the functions of this library as an optional parameter
returns true if all registered async or dependent objects are ready
and call onReady and onError handlers when the all-ready state is reached.
You can force a timeout Exception if allReady hasn't
returned true within timeout.
It will trigger a rebuild if this state changes
If no onError is passed in it will throw an exception if an error occurs
while waiting for the all-ready state.
callHandlerOnlyOnce determines if the onReady and onError handlers should
be called only once or on every rebuild after the all-ready state has been reached.
registers a handler that is called when the all-ready state is reached
it does not trigger a rebuild like allReady does.
You can force a timeout Exception if allReady has completed
within timeout which will call onError
if no onError is passed in it will throw an exception if an error occurs
while waiting for the all-ready state.
callHandlerOnlyOnce determines if the onReady and onError handlers should
be called only once or on every rebuild after the all-ready state has been reached.
If you want to execute a function only on the first built (even in in a StatelessWidget),
you can use the callOnce function anywhere in your build function. It has an optional dispose
handler which will be called when the widget is disposed.
returns true if the registered async or dependent object defined by T and
instanceName is ready
and calls onReadyonError handlers when the ready state is reached.
You can force a timeout Exception if isReady hasn't
returned true within timeout.
It will trigger a rebuild if this state changes.
if no onError is passed in it will throw an exception if an error occurs
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 of a StatelessWidget.
It ensures that it's only called once in the lifetime of a widget.
isFinal allows only objects in init to be registered so that other components
cannot accidentally register to this scope.
When the widget is destroyed the scope also gets destroyed after dispose
is executed. If you use this function and you have registered your objects with
an async disposal function, that function won't be awaited.
I would recommend doing pushing and popping from your business layer but sometimes
this might come in handy.
Will trigger a rebuild of the Widget if any new GetIt-Scope is pushed or popped.
This function will return true if the change was a push otherwise false.
If no change has happened then the return value will be null.
registerChangeNotifierHandler registers a handler function for a ChangeNotifier
exactly once on the first build
and unregisters it when the widget is destroyed.
If you set executeImmediately to true the handler will be called immediately
with the current value of the ChangeNotifier and not on the first change notification.
All handler functions get passed in a cancel function that allows to kill the registration
from inside the handler.
If you want to register a handler to a ChangeNotifier that is not registered in get_it you can
pass it as target.
instanceName is the optional name of the instance if you registered it
with a name in get_it.
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
registerHandler registers a handler function for a ValueListenable
exactly once on the first build
and unregister it when the widget is destroyed.
select allows you to register the handler to a member of the of the Object
stored in GetIt.
If you set executeImmediately to true the handler will be called immediately
with the current value of the ValueListenable and not on the first change notification.
All handler functions get passed in a cancel function that allows to kill the registration
from inside the handler.
If you want to register a handler to a Listenable 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 Listenable or ValueListenable.
instanceName is the optional name of the instance if you registered it
with a name in get_it.
registerStreamHandler registers a handler function for a Stream exactly
once on the first build
and unregisters it when the widget is destroyed.
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 handler functions get passed in a cancel function that allows to kill the registration
from inside the handler.
If you want to register a handler to a Stream 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 Stream
watchFuture observes the Future returned by select and triggers a rebuild as soon
as this 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 observe the Future a another time.
To be able to use watchFuture inside a build function
we have to pass initialValue so that it can return something before
the Future has completed
if select returns a different Future than on the last call, watchFuture
will ignore the completion of the previous Future and observe the completion
of the new Future.
preserveState determines then if the new initial value should be the last
value of the previous Future or again initialValue
If you want to observe 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
watchIt observes any Listenable registered in get_it and triggers a rebuild whenever
it notifies a change. Its basically a shortcut for watch(di<T>())instanceName is the optional name of the instance if you registered it
with a name in get_it.
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.
watchPropertyValue allows you to observe a property of a Listenable object and trigger a rebuild
whenever the Listenable notifies a change and the value of the property changes and
returns the current value of the property.
You can achieve a similar result with watchIt<UserManager>().userName but that
would trigger a rebuild whenever any property of the UserManager changes.
final userName = watchPropertyValue<UserManager, String>((user) => user.userName);
could be an example. Or even more expressive and concise:
final userName = watchPropertyValue((UserManager user) => user.userName);
which lets tha analyzer infer the type of T and R.
watchStream 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
if select returns a different Stream than on the last call, watchStream
will cancel the previous subscription and subscribe to the new stream.
preserveState determines then if the new initial value should be the last
value of the previous stream or again initialValue
If you want to observe a Stream 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 Stream
watchValue observes a ValueListenable property of an object registered in get_it
and triggers a rebuild whenever it notifies a change and returns its current
value. It's basically a shortcut for watchIt<T>().value
As this is a common scenario it allows us a type safe concise way to do this.
final userName = watchValue<UserManager, String>((user) => user.userName);
is an example of how to use it.
We can use the strength of generics to infer the type of the property and write
it even more expressively like this:
final userName = watchValue((UserManager user) => user.userName);
