Retained Instance
A lightweight library built on top of Android Architecture Component ViewModel to simplify how UI Controllers (e.g., Activity, Fragment & NavBackStackEntry) retain instances on Android.
- Eliminate
ViewModelinheritance. - Eliminate
ViewModelProvider.Factoryneed. - Easy access to
ViewModelscoped properties:CoroutineScope(viewModelScope),SavedStateHandle, and many others. - Enable composition: callbacks can be listened with
OnClearedListener.
Motivation: Retained was originally created to share a ViewModel in Kotlin Multiplatform projects between Android & iOS with ease.
Download
dependencies {
// `Activity` support
implementation 'dev.marcellogalhardo:retained-activity:{Tag}'
// `Fragment` support, includes `Activity` support
implementation 'dev.marcellogalhardo:retained-fragment:{Tag}'
// Navigation support
implementation 'dev.marcellogalhardo:retained-navigation:{Tag}'
// Navigation with Fragment support, includes `Navigation` support
implementation 'dev.marcellogalhardo:retained-navigation-fragment:{Tag}'
}
(Please replace {Tag} with the latest version numbers)
Usage
The following sections demonstrate how to retain instances in activities and fragments. For simplicity, all examples will retain the following class:
class ViewModel(var counter: Int = 0)
Use Retained in Activities and Fragments
// retain an instance in an Activity:
class CounterActivity : AppCompatActivity() {
private val viewModel: ViewModel by retain { ViewModel() }
}
// retain an instance in a Fragment:
class CounterFragment : Fragment() {
private val viewModel: ViewModel by retain { ViewModel() }
}
// share an instance between Fragments scoped to the Activity
class CounterFragment : Fragment() {
private val sharedViewModel: ViewModel by retainInActivity { ViewModel() }
}
// share an instance between Fragments scoped to the NavGraph
class CounterFragment : Fragment() {
private val viewModel: ViewModel by retainInNavGraph(R.navigation.nav_graph) { ViewModel() }
}
Use Retained in Compose
@Composable
fun SampleView() {
// Using an Activity
val activity: ComponentActivity // find Activity
val viewModel by activity.retain { ViewModel() }
// Using a Fragment
val fragment: Fragment // find Fragment
val viewModel by fragment.retain { ViewModel() }
// Using NavBackStackEntry
val navBackStackEntry: NavBackStackEntry // find NavBackStackEntry
val viewModel by navBackStackEntry.retain { ViewModel() }
}
Advanced usage
Custom parameters from Jetpack's ViewModel
When retaining an instance, you have access to a RetainedEntry which contains all parameters you might need.
@Composable
fun SampleView() {
val viewModel = retain { entry: RetainedEntry ->
ViewModel()
}
// ...
}
The entry exposes a SavedStateHandle that can be used to work with the saved state, just like in a regular Android ViewModel.
class CounterFragment : Fragment() {
private val viewModel: ViewModel by retain { entry ->
ViewModel(counter = entry.savedStateHandle.get<Int>("count"))
}
// ...
}
It also exposes a CoroutineScope that works just like viewModelScope from the Android ViewModel.
class Presenter(scope: CoroutineScope) { /* ... */ }
fun SampleFragment() {
private val presenter: Presenter by retain { entry ->
Presenter(scope = entry.scope)
}
// ...
}
For more details, see RetainedEntry.
Listening onCleared calls
When retaining an instance, you can use the RetainedEntry to be notified when a retained instance is cleared (ViewModel.onCleared).
@Composable
fun SampleView() {
val viewModel by retain { entry ->
entry.onClearedListeners += {
println("Invoked when the host 'ViewModel.onCleared' is called")
}
}
// ...
}
As a convenience, if the retained instance implements the OnClearedListener interface, it will be automatically added to onClearedListeners and notified.
View support (Experimental)
Besides Activities and Fragments, it's also possible to retain instances in a view. There are a couple of extra modules for that:
dependencies {
implementation 'dev.marcellogalhardo:retained-view:{Tag}'
implementation 'dev.marcellogalhardo:retained-navigation-view:{Tag}'
}
The retained-view module exposes retainInActivity and retain, which will scope the instance to the parent being it an activity or a fragment. The retained-view-navigation module exposes retainInNavGraph to retain instances scoped to the NavGraph.
License
Copyright 2019 Marcello Galhardo
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
![[WIP] Add view module with view retained implementation](https://avatars.githubusercontent.com/u/750114?v=4)
31 Nov 18, 2022
429 Dec 15, 2022
10.3k Dec 31, 2022
924 Jan 5, 2023
2.9k Jan 9, 2023
362 Dec 29, 2022
41 Oct 17, 2022
22 Nov 19, 2022
25 Dec 27, 2022
28 Oct 3, 2022
121 Nov 29, 2022
514 Nov 29, 2022
2.7k Dec 28, 2022
13 Dec 16, 2022
18 Jul 17, 2022
5 Feb 15, 2022
101 Aug 14, 2022
66 Dec 28, 2022