ViewModelStoreProvider
-
Cmn
class ViewModelStoreProvider
Manages a set of ViewModelStore instances scoped to a parent ViewModelStore.
This class allows the creation of "child" scopes that survive configuration changes (via the parent owner) but can be independently cleared when no longer needed.
Important: This class prevents a child ViewModel from being cleared while they are still in use (e.g., during exit animations). Consumers must call acquireToken to mark a child ViewModelStore as active and then call ReferenceToken.close to release the token when finished. Calling clearKey or clearAllKeys will only perform the actual cleanup once all of a store's tokens have been released.
Null owner: If store is EXPLICITLY null, this creates a root provider that runs independently. It manages its own state and will not be automatically cleared by configuration changes; you must manually call clearAllKeys to clean it up.
Summary
Nested types |
|---|
fun interface ViewModelStoreProvider.ReferenceToken : AutoCloseableRepresents an active hold on a specific |
Public constructors |
|
|---|---|
ViewModelStoreProvider(Constructs a |
Cmn
|
ViewModelStoreProvider( |
Cmn
|
Public functions |
||
|---|---|---|
ViewModelStoreProvider.ReferenceToken |
acquireToken(key: Any?)Increments the reference count for the |
Cmn
|
Unit |
Triggers a cleanup pass on all managed stores. |
Cmn
|
Unit |
Marks the |
Cmn
|
ViewModelStore |
getOrCreate(key: Any?)Retrieves or creates a |
Cmn
|
ViewModelStoreOwner |
getOrCreateOwner(Retrieves or creates a |
Cmn
|
Public constructors
ViewModelStoreProvider
ViewModelStoreProvider(
owner: ViewModelStoreOwner?,
defaultCreationExtras: CreationExtras = owner.defaultViewModelCreationExtras,
defaultFactory: ViewModelProvider.Factory = owner.defaultViewModelProviderFactory
)
Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.
| Parameters | |
|---|---|
owner: ViewModelStoreOwner? |
The parent |
defaultCreationExtras: CreationExtras = owner.defaultViewModelCreationExtras |
The default creation extras to use for child stores. Defaults to resolving from the |
defaultFactory: ViewModelProvider.Factory = owner.defaultViewModelProviderFactory |
The default factory to use for child stores. Defaults to resolving from the |
ViewModelStoreProvider
ViewModelStoreProvider(
store: ViewModelStore?,
defaultCreationExtras: CreationExtras = CreationExtras.Empty,
defaultFactory: ViewModelProvider.Factory = SavedStateViewModelFactory()
)
| Parameters | |
|---|---|
store: ViewModelStore? |
The parent |
defaultCreationExtras: CreationExtras = CreationExtras.Empty |
The default creation extras to use for child stores. |
defaultFactory: ViewModelProvider.Factory = SavedStateViewModelFactory() |
The default factory to use for child stores. |
Public functions
acquireToken
fun acquireToken(key: Any?): ViewModelStoreProvider.ReferenceToken
Increments the reference count for the ViewModelStore associated with the given key, ensuring it is not cleared until the returned [] is released.
| Parameters | |
|---|---|
key: Any? |
The unique identifier for the child scope. |
| Returns | |
|---|---|
ViewModelStoreProvider.ReferenceToken |
A token that must be released via |
clearAllKeys
fun clearAllKeys(): Unit
Triggers a cleanup pass on all managed stores.
Any ViewModelStore that has a reference count of zero will have its ViewModelStore.clear method called and will be removed from the internal map. Stores with active references are marked as removable and will be deferred until their count reaches zero.
clearKey
fun clearKey(key: Any?): Unit
Marks the ViewModelStore associated with the given key as removable.
If the store currently has a reference count of zero, it is cleared immediately. Otherwise, the actual cleanup is deferred until all acquired tokens are released.
| Parameters | |
|---|---|
key: Any? |
The unique identifier for the child scope. |
getOrCreate
fun getOrCreate(key: Any?): ViewModelStore
Retrieves or creates a ViewModelStore associated with the given key.
If a store with this key already exists, it is returned. If not, a new store is created. To protect this store from being prematurely cleared, you must call acquireToken.
| Parameters | |
|---|---|
key: Any? |
The unique identifier for the child scope. |
| Returns | |
|---|---|
ViewModelStore |
The |
getOrCreateOwner
fun getOrCreateOwner(
key: Any?,
savedStateRegistryOwner: SavedStateRegistryOwner? = null,
defaultCreationExtras: CreationExtras = this.defaultCreationExtras,
defaultFactory: ViewModelProvider.Factory = this.defaultFactory
): ViewModelStoreOwner
Retrieves or creates a ViewModelStoreOwner associated with the given key.
This method creates a new lightweight wrapper around the ViewModelStore.
Important: This does not automatically increment the reference count. If you are holding onto this owner asynchronously or across recompositions, you should call acquireToken to protect its lifecycle.
Saved State Support: If a savedStateRegistryOwner is provided, the returned ViewModelStoreOwner will also implement SavedStateRegistryOwner, delegating state resolution to the provided owner. This is required if ViewModels within this scope depend on androidx.lifecycle.SavedStateHandle. When saved state is enabled and defaultFactory is not explicitly overridden, it automatically upgrades to a SavedStateViewModelFactory.
| Parameters | |
|---|---|
key: Any? |
The unique identifier for the child scope. |
savedStateRegistryOwner: SavedStateRegistryOwner? = null |
An optional parent registry owner to delegate saved state operations to. If |
defaultCreationExtras: CreationExtras = this.defaultCreationExtras |
An optional override for the default |
defaultFactory: ViewModelProvider.Factory = this.defaultFactory |
An optional override for the default |
| Returns | |
|---|---|
ViewModelStoreOwner |
A scoped |
| Throws | |
|---|---|
IllegalArgumentException |
If |