This chapter is from the book
This chapter is from the book
This chapter is from the book
Adding a ViewModel
Now, back to ViewModel. A ViewModel is related to one particular screen and is a great place to put logic involved in formatting the data to display on that screen. A ViewModel holds on to a model object and “decorates” the model – adding functionality to display onscreen that you might not want in the model itself. Using a ViewModel aggregates all the data the screen needs in one place, formats the data, and makes it easy to access the end result.
ViewModel is part of the androidx.lifecycle package, which contains lifecycle-related APIs including lifecycle-aware components. Lifecycle-aware components observe the lifecycle of some other component, such as an activity, and take the state of that lifecycle into account.
Google created the androidx.lifecycle package and its contents to make dealing with the activity lifecycle (and other lifecycles, which you will learn about later in this book) a little less painful. You will learn about LiveData, another lifecycle-aware component, in Chapter 11. And you will learn how to create your own lifecycle-aware components in Chapter 25.
Now you are ready to create your ViewModel subclass, QuizViewModel. In the project tool window, right-click the com.bignerdranch.android.geoquiz package and select New → Kotlin File/Class. Enter QuizViewModel for the name and select Class from the Kind dropdown.
In QuizViewModel.kt, add an init block and override onCleared(). Log the creation and destruction of the QuizViewModel instance, as shown in Listing 4.3.
Listing 4.3 Creating a ViewModel class (QuizViewModel.kt)
private const val TAG = "QuizViewModel"
class QuizViewModel : ViewModel() {
init {
Log.d(TAG, "ViewModel instance created")
}
override fun onCleared() {
super.onCleared()
Log.d(TAG, "ViewModel instance about to be destroyed")
}
}
The onCleared() function is called just before a ViewModel is destroyed. This is a useful place to perform any cleanup, such as un-observing a data source. For now, you simply log the fact that the ViewModel is about to be destroyed so that you can explore its lifecycle (the same way you explored the lifecycle of MainActivity in Chapter 3).
Now, open MainActivity.kt and, in onCreate(…), associate the activity with an instance of QuizViewModel.
Listing 4.4 Accessing the ViewModel (MainActivity.kt)
class MainActivity : AppCompatActivity() {
...
override fun onCreate(savedInstanceState: Bundle?) {
...
setContentView(R.layout.activity_main)
val provider: ViewModelProvider = ViewModelProviders.of(this)
val quizViewModel = provider.get(QuizViewModel::class.java)
Log.d(TAG, "Got a QuizViewModel: $quizViewModel")
trueButton = findViewById(R.id.true_button)
...
}
...
}
The ViewModelProviders class (note the plural “Providers”) provides instances of the ViewModelProvider class. Your call to ViewModelProviders.of(this) creates and returns a ViewModelProvider associated with the activity.
ViewModelProvider (no plural), on the other hand, provides instances of ViewModel to the activity. Calling provider.get(QuizViewModel::class.java) returns an instance of QuizViewModel. You will most often see these functions chained together, like so:
ViewModelProviders.of(this).get(QuizViewModel::class.java)
The ViewModelProvider acts like a registry of ViewModels. When the activity queries for a QuizViewModel for the first time, ViewModelProvider creates and returns a new QuizViewModel instance. When the activity queries for the QuizViewModel after a configuration change, the instance that was first created is returned. When the activity is finished (such as when the user presses the Back button), the ViewModel-Activity pair is removed from memory.
ViewModel lifecycle and ViewModelProvider
You learned in Chapter 3 that activities transition between four states: resumed, paused, stopped, and nonexistent. You also learned about different ways an activity can be destroyed: either by the user finishing the activity or by the system destroying it as a result of a configuration change.
When the user finishes an activity, they expect their UI state to be reset. When the user rotates an activity, they expect their UI state to be the same before and after rotation.
You can determine which of these two scenarios is happening by checking the activity’s isFinishing property. If isFinishing is true, the activity is being destroyed because the user finished the activity (such as by pressing the Back button or by clearing the app’s card from the overview screen). If isFinishing is false, the activity is being destroyed by the system because of a configuration change.
But you do not need to track isFinishing and preserve UI state manually when it is false just to meet your user’s expectations. Instead, you can use a ViewModel to keep an activity’s UI state data in memory across configuration changes. A ViewModel’s lifecycle more closely mirrors the user’s expectations: It survives configuration changes and is destroyed only when its associated activity is finished.
You associate a ViewModel instance with an activity’s lifecycle, as you did in Listing 4.4. The ViewModel is then said to be scoped to that activity’s lifecycle. This means the ViewModel will remain in memory, regardless of the activity’s state, until the activity is finished. Once the activity is finished (such as by the user pressing the Back button), the ViewModel instance is destroyed (Figure 4.2).
)
FIGURE 4.2 QuizViewModel scoped to MainActivity
This means that the ViewModel stays in memory during a configuration change, such as rotation. During the configuration change, the activity instance is destroyed and re-created, but the ViewModels scoped to the activity stay in memory. This is depicted in Figure 4.3, using MainActivity and QuizViewModel.
)
FIGURE 4.3 MainActivity and QuizViewModel across rotation
To see this in action, run GeoQuiz. In Logcat, select Edit Filter Configuration in the dropdown to create a new filter. In the Log Tag box, enter QuizViewModel|MainActivity (that is, the two class names with the pipe character | between them) to show only logs tagged with either class name. Name the filter ViewModelAndActivity (or another name that makes sense to you) and click OK (Figure 4.4).
)
FIGURE 4.4 Filtering QuizViewModel and MainActivity logs
Now look at the logs. When MainActivity first launches and queries for the ViewModel in onCreate(…), a new QuizViewModel instance is created. This is reflected in the logs (Figure 4.5).
)
FIGURE 4.5 QuizViewModel instance created
Rotate the device. The logs show the activity is destroyed (Figure 4.6). The QuizViewModel is not. When the new instance of MainActivity is created after rotation, it requests a QuizViewModel. Since the original QuizViewModel is still in memory, the ViewModelProvider returns that instance rather than creating a new one.
)
FIGURE 4.6 MainActivity is destroyed and re-created; QuizViewModel persists
Finally, press the Back button. QuizViewModel.onCleared() is called, indicating that the QuizViewModel instance is about to be destroyed, as the logs show (Figure 4.7). The QuizViewModel is destroyed, along with the MainActivity instance.
)
FIGURE 4.7 MainActivity and QuizViewModel destroyed
The relationship between MainActivity and QuizViewModel is unidirectional. The activity references the ViewModel, but the ViewModel does not access the activity. Your ViewModel should never hold a reference to an activity or a view, otherwise you will introduce a memory leak.
A memory leak occurs when one object holds a strong reference to another object that should be destroyed. Holding the strong reference prevents the garbage collector from clearing the object from memory. Memory leaks due to a configuration change are common bugs. The details of strong reference and garbage collection are outside the scope of this book. If you are not sure about these concepts, we recommend reading up on them in a Kotlin or Java reference.
Your ViewModel instance stays in memory across rotation, while your original activity instance gets destroyed. If the ViewModel held a strong reference to the original activity instance, two problems would occur: First, the original activity instance would not be removed from memory, and thus the activity would be leaked. Second, the ViewModel would hold a reference to a stale activity. If the ViewModel tried to update the view of the stale activity, it would trigger an IllegalStateException.
Add data to your ViewModel
Now it is finally time to fix GeoQuiz’s rotation bug. QuizViewModel is not destroyed on rotation the way MainActivity is, so you can stash the activity’s UI state data in the QuizViewModel instance and it, too, will survive rotation.
You are going to copy the question and current index data from your activity to your ViewModel, along with all the logic related to them. Begin by cutting the currentIndex and questionBank properties from MainActivity (Listing 4.5).
Listing 4.5 Cutting model data from activity (MainActivity.kt)
class MainActivity : AppCompatActivity() {
...
private val questionBank = listOf(
Question(R.string.question_australia, true),
Question(R.string.question_oceans, true),
Question(R.string.question_mideast, false),
Question(R.string.question_africa, false),
Question(R.string.question_americas, true),
Question(R.string.question_asia, true)
)
private var currentIndex = 0
...
}
Now, paste the currentIndex and questionBank properties into QuizViewModel, as shown in Listing 4.6.
Remove the private access modifier from currentIndex so the property value can be accessed by external classes, such as MainActivity. Leave the private access modifier on questionBank – MainActivity will not interact with the questionBank directly. Instead, it will call functions and computed properties you will add to QuizViewModel. While you are editing QuizViewModel, delete the init and onCleared() logging, as you will not use them again.
Listing 4.6 Pasting model data into QuizViewModel (QuizViewModel.kt)
class QuizViewModel : ViewModel() {
init {
Log.d(TAG, "ViewModel instance created")
}
override fun onCleared() {
super.onCleared()
Log.d(TAG, "ViewModel instance about to be destroyed")
}
private var currentIndex = 0
private val questionBank = listOf(
Question(R.string.question_australia, true),
Question(R.string.question_oceans, true),
Question(R.string.question_mideast, false),
Question(R.string.question_africa, false),
Question(R.string.question_americas, true),
Question(R.string.question_asia, true)
)
}
Next, add a function to QuizViewModel to advance to the next question. Also, add computed properties to return the text and answer for the current question.
Listing 4.7 Adding business logic to QuizViewModel (QuizViewModel.kt)
class QuizViewModel : ViewModel() {
var currentIndex = 0
private val questionBank = listOf(
...
)
val currentQuestionAnswer: Boolean
get() = questionBank[currentIndex].answer
val currentQuestionText: Int
get() = questionBank[currentIndex].textResId
fun moveToNext() {
currentIndex = (currentIndex + 1) % questionBank.size
}
}
Earlier, we said that a ViewModel stores all the data that its associated screen needs, formats it, and makes it easy to access. This allows you to remove presentation logic code from the activity, which in turn keeps your activity simpler. And keeping activities as simple as possible is a good thing: Any logic you put in your activity might be unintentionally affected by the activity’s lifecycle. Also, it allows the activity to be responsible for handling only what appears on the screen, not the logic behind determining the data to display.
However, you are going to leave the updateQuestion() and checkAnswer(Boolean) functions in MainActivity. You will update these functions shortly to call through to the new QuizViewModel computed properties you added. But you will keep them in MainActivity to help keep your activity code organized.
Next, add a lazily initialized property to stash the QuizViewModel instance associated with the activity.
Listing 4.8 Lazily initializing QuizViewModel (MainActivity.kt)
class MainActivity : AppCompatActivity() {
...
private val quizViewModel: QuizViewModel by lazy {
ViewModelProviders.of(this).get(QuizViewModel::class.java)
}
override fun onCreate(savedInstanceState: Bundle?) {
...
val provider: ViewModelProvider = ViewModelProviders.of(this)
val quizViewModel = provider.get(QuizViewModel::class.java)
Log.d(TAG, "Got a QuizViewModel: $quizViewModel")
...
}
...
}
Using by lazy allows you to make the quizViewModel property a val instead of a var. This is great, because you only need (and want) to grab and store the QuizViewModel when the activity instance is created – so quizViewModel should only be assigned a value one time.
More importantly, using by lazy means the quizViewModel calculation and assignment will not happen until the first time you access quizViewModel. This is good because you cannot safely access a ViewModel until Activity.onCreate(…). If you try to call ViewModelProviders.of(this).get(QuizViewModel::class.java) before Activity.onCreate(…), your app will crash with an IllegalStateException.
Finally, update MainActivity to display content from and interact with your newly updated QuizViewModel.
Listing 4.9 Updating question through QuizViewModel (MainActivity.kt)
class MainActivity : AppCompatActivity() {
...
override fun onCreate(savedInstanceState: Bundle?) {
...
nextButton.setOnClickListener {
currentIndex = (currentIndex + 1) % questionBank.size
quizViewModel.moveToNext()
updateQuestion()
}
...
}
...
private fun updateQuestion() {
val questionTextResId = questionBank[currentIndex].textResId
val questionTextResId = quizViewModel.currentQuestionText
questionTextView.setText(questionTextResId)
}
private fun checkAnswer(userAnswer: Boolean) {
val correctAnswer = questionBank[currentIndex].answer
val correctAnswer = quizViewModel.currentQuestionAnswer
...
}
Run GeoQuiz, press NEXT, and rotate the device or emulator. No matter how many times you rotate, the newly minted MainActivity will “remember” what question you were on. Do a happy dance to celebrate solving the UI state loss on rotation bug.
But do not dance too long. There is another, less-easily-discoverable bug to squash.