/
Android Studio Sign in

ViewModelStoreProvider

Manages a set of child ViewModelStore instances scoped to a parent ViewModelStore.

This class allows the creation of child ViewModelStore instances that survive configuration changes (retained via the parent ViewModelStore) 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 parentStore: If parentStore 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

A special marker key that can be used with acquireToken to manage the lifecycle of the shared state associated with a particular parentKey.

Represents an active hold on a specific ViewModelStore.

Public constructors
ViewModelStoreProvider(
    parentOwner: ViewModelStoreOwner?,
    parentKey: Any?,
    defaultArgs: SavedState,
    defaultCreationExtras: CreationExtras,
    defaultFactory: ViewModelProvider.Factory
)

Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.
Cmn
ViewModelStoreProvider(
    parentStore: ViewModelStore?,
    parentKey: Any?,
    defaultArgs: SavedState,
    defaultCreationExtras: CreationExtras,
    defaultFactory: ViewModelProvider.Factory
)
Cmn

Public functions
ViewModelStoreProvider.ReferenceToken

Increments the reference count for the ViewModelStore associated with the given key, ensuring it is not cleared until the returned ReferenceToken is released.
Cmn
Unit

Triggers a cleanup pass on all managed stores.
Cmn
Unit
clearKey(key: Any?)

Marks the ViewModelStore associated with the given key as removable.
Cmn
ViewModelStore

Retrieves or creates a ViewModelStore associated with the given key.
Cmn
ViewModelStoreOwner
getOrCreateOwner(
    key: Any?,
    savedStateRegistryOwner: SavedStateRegistryOwner?,
    defaultArgs: SavedState,
    defaultCreationExtras: CreationExtras,
    defaultFactory: ViewModelProvider.Factory
)

Retrieves or creates a ViewModelStoreOwner associated with the given key.
Cmn

Public constructors

ViewModelStoreProvider

Cmn 
ViewModelStoreProvider(
    parentOwner: ViewModelStoreOwner?,
    parentKey: Any? = null,
    defaultArgs: SavedState = savedState(),
    defaultCreationExtras: CreationExtras = parentOwner.defaultViewModelCreationExtras,
    defaultFactory: ViewModelProvider.Factory = parentOwner.defaultViewModelProviderFactory
)

Constructs a ViewModelStoreProvider bound to a parent ViewModelStoreOwner.

Parameters
parentOwner: ViewModelStoreOwner?

The parent ViewModelStoreOwner whose ViewModelStore is used to retain child ViewModelStore instances across configuration changes, or null for an independent root provider.
parentKey: Any? = null

A unique identifier used to scope this provider and its underlying state within the parentOwner. Providers sharing the same key will share the same internal state. A null key is valid and acts as its own distinct shared scope. Defaults to null.
defaultArgs: SavedState = savedState()

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
defaultCreationExtras: CreationExtras = parentOwner.defaultViewModelCreationExtras

The default creation extras to use for child stores. Defaults to resolving from the parentOwner.
defaultFactory: ViewModelProvider.Factory = parentOwner.defaultViewModelProviderFactory

The default factory to use for child stores. Defaults to resolving from the parentOwner.

ViewModelStoreProvider

Cmn 
ViewModelStoreProvider(
    parentStore: ViewModelStore?,
    parentKey: Any? = null,
    defaultArgs: SavedState = savedState(),
    defaultCreationExtras: CreationExtras = CreationExtras.Empty,
    defaultFactory: ViewModelProvider.Factory = SavedStateViewModelFactory()
)
Parameters
parentStore: ViewModelStore?

The parent ViewModelStore used to retain child ViewModelStore instances across configuration changes, or null for an independent root provider.
parentKey: Any? = null

A unique identifier used to scope this provider and its underlying state within the parentStore. Providers sharing the same key will share the same internal state. A null key is valid and acts as its own distinct shared scope. Defaults to null.
defaultArgs: SavedState = savedState()

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
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

Cmn
Added in 2.11.0
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 ReferenceToken is released.

Parameters
key: Any?

The unique identifier for the child scope. A null key is valid and is treated as a distinct scope.
Returns
ViewModelStoreProvider.ReferenceToken

A token that must be released via ReferenceToken.close when the caller no longer requires the store.

clearAllKeys

Cmn
Added in 2.11.0
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

Cmn
Added in 2.11.0
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. Passing null will target the specific scope associated with the null key.

getOrCreate

Cmn
Added in 2.11.0
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. A null key is valid and is treated as a distinct scope.
Returns
ViewModelStore

The ViewModelStore tied to the provided key.

getOrCreateOwner

Cmn 
fun getOrCreateOwner(
    key: Any?,
    savedStateRegistryOwner: SavedStateRegistryOwner? = null,
    defaultArgs: SavedState = this.defaultArgs,
    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 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. A null key is valid and is treated as a distinct scope.
savedStateRegistryOwner: SavedStateRegistryOwner? = null

An optional parent registry owner to delegate saved state operations to. If null, the returned owner will not support SavedStateHandle.
defaultArgs: SavedState = this.defaultArgs

The default SavedState arguments to use for child stores. These arguments are merged with any default arguments in defaultCreationExtras. If the same key exists in both, the value from defaultArgs takes precedence.
defaultCreationExtras: CreationExtras = this.defaultCreationExtras

An optional override for the default CreationExtras.
defaultFactory: ViewModelProvider.Factory = this.defaultFactory

An optional override for the default ViewModelProvider.Factory.
Returns
ViewModelStoreOwner

A scoped ViewModelStoreOwner, which optionally supports saved state.
Throws
IllegalArgumentException

If savedStateRegistryOwner is provided but its lifecycle is past the INITIALIZED or CREATED state.
Morty Proxy This is a proxified and sanitized view of the page, visit original site.