Adding to the standard AndroidManifest.xml

Many of the apps in this book have an AndroidManifest.xml file that borders on simple, but that's not the case with this app. In addition to the usual MainActivity, you also have a DetailsActivity, PlaybackActivity, and BrowseErrorActivity. Each of these activities has its own .kt file, as shown previously in Figure 3-1. They also appear as activities in the <application> element.

However, these activities aren't the main event. What you really find interesting are the <uses-feature> entries shown here:

<uses-feature
android:name="android.hardware.touchscreen"
android:required="false"/>
<uses-feature
android:name="android.software.leanback"
android:required="true"/>

The first entry, android.hardware.touchscreen, lets you click the screen and have something happen. If you load this app on a regular TV, it may not have a touchscreen, so working with the app will be harder. Some TVs also ship with what is called a multitouch display that uses multiple touch gestures. In other words, the display can detect more than one touch at a time. To get this functionality, you change android.hardware.touchscreen to something like android.hardware.touchscreen.multitouch.distinct.

The second entry merely tells the compiler that this software runs on an Android TV and not another device. It replaces the android.hardware.type.television entry that you may find in older examples. Along with the addition of the android.software.leanback feature, you also find that the <intent-filter> element and <category> entry also reflect the TV nature of the app by using <category android:name="android.intent.category.LEANBACK_LAUNCHER" />.

Looking into build.gradle (Module: app)

Even build.gradle reflects the change in app venue. Most of the entries are similar to those that you use to build other app types, but note the leanback addition shown in bold in the following code:

dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])
implementation
"org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
implementation 'androidx.leanback:leanback:1.0.0'
implementation 'androidx.appcompat:appcompat:1.0.2'
implementation 'com.github.bumptech.glide:glide:3.8.0'
}

Defining a layout

What will underwhelm you the most about this app is the lack of layout. You find some interesting generic graphics in the drawable folder and two activity layouts in the layout folder. However, both layouts are incredibly simple because you perform most of the display work within the code. For example, here's the activity_main.xml file, which is a far cry from most of the examples in the book:

<?xml version="1.0" encoding="utf-8"?>
<fragment xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:id="@+id/main_browse_fragment"
android:name="com.allmycode.p05_03_01.MainFragment"
android:layout_width="match_parent"
android:layout_height="match_parent"
tools:context=".MainActivity"
tools:deviceIds="tv"
tools:ignore="MergeRootFrame"/>

Oddly enough, MainActivity.kt is similarly devoid of content. All you really have in that file is the override for onCreate(). The overview of the work to do to present a list of movies appears in MainFragment.kt, where you find a list of tasks to perform in onActivityCreated():

override fun onActivityCreated(savedInstanceState: Bundle?) {
Log.i(TAG, "onCreate")
super.onActivityCreated(savedInstanceState)

prepareBackgroundManager()

setupUIElements()

loadRows()

setupEventListeners()
}

The first two items on the list, prepareBackgroundManager() and setupUIElements(), are what you expect for creating a display. The last step, setupEventListeners(), makes the app interactive so that something happens as the result of a click. However, when you get to loadRows(), things get interesting because now you're dealing with data. The loadRows() function creates an adapter — a data source — as shown in Listing 3-1. The sections that follow discuss this part of the app in more detail.

LISTING 3-1: Providing a Data Source

private fun loadRows() {
val list = MovieList.list

val rowsAdapter = ArrayObjectAdapter(ListRowPresenter())
val cardPresenter = CardPresenter()

for (i in 0 until NUM_ROWS) {
if (i != 0) {
Collections.shuffle(list)
}
val listRowAdapter = ArrayObjectAdapter(cardPresenter)
for (j in 0 until NUM_COLS) {
listRowAdapter.add(list[j % 5])
}
val header = HeaderItem(i.toLong(),
MovieList.MOVIE_CATEGORY[i])
rowsAdapter.add(ListRow(header, listRowAdapter))
}

val gridHeader = HeaderItem(NUM_ROWS.toLong(), "PREFERENCES")

val mGridPresenter = GridItemPresenter()
val gridRowAdapter =
ArrayObjectAdapter(mGridPresenter)
gridRowAdapter.add(resources.getString(R.string.grid_view))
gridRowAdapter.add(getString(R.string.error_fragment))
gridRowAdapter.add(
resources.getString(R.string.personal_settings))
rowsAdapter.add(ListRow(gridHeader, gridRowAdapter))

adapter = rowsAdapter
}

The adapter and the presenter

Central to the mission of the code in Listing 3-1 are the notions of an adapter (MovieList.list), found in MovieList.kt, and a presenter (CardPresenter), found in CardPresenter.kt. An adapter stores data, and a presenter displays the data that an adapter stores. That's the way Android's TV classes separate data from presentation. The loadRows() function provides the functionality needed to move the data from MovieList.list to cardPresenter using the ArrayObjectAdapter.

It's a classic principle of app development:

Data and presentation don't belong in the same parts of your code.

If you interleave your data code with your presentation code, modifying the presentation is difficult to do without messing up the data. Data is data, whether it's displayed on a 70-inch TV or a 1-inch watch screen.

Imagine dealing with data about a movie, as described earlier. In a more realistic app, the data might include the title, the release date, a synopsis, the actors' names, a link to a trailer, and other information. A user might view the data on an Android TV. But in another setting, the same user might view the same data on a computer, a smartphone, or whatever other device is available. With the presentation code separated from the data code, you can provide several alternatives for displaying the same data. With one class to store the data, you can plug in a big TV display one time, a smartphone display another time, and a ten-inch laptop display the next time. You can offer the user a choice of interfaces — one for daytime browsing and another for nighttime perusal. You're ready for any kind of display because the code to control the data doesn't care what display logic is behind it.

Imagine changing the way you store each movie's release date. Instead of storing an ordinary Gregorian calendar date, you decide to store each movie's Star Trek star date. (According to one online calculator, the first Matrix movie was released in the United States on star date –323754.8.) With the data decoupled from the display, you don't have to inform your display code about this data storage change. The data code already has a function named getReleaseDate(), and the presentation code calls this method during the app's run. While you're setting up the data code to handle star dates, you modify the getReleaseDate() method to convert between star dates and Gregorian dates. The display code doesn't know about this change, and what the display code doesn't know won't hurt it.

Using the Adapter class

Figure 3-7 illustrates the relationships among classes used in Listing 3-1.

For an adapter, TV apps normally use the ArrayObjectAdapter class (a member of the 'androidx.leanback:leanback:1.0.0' package). When you construct a new ArrayObjectAdapter, you supply a Presenter in the constructor call, such as the following:

• val rowsAdapter = ArrayObjectAdapter(ListRowPresenter()): Applies a dimming effect to each of the rows, as described at https://developer.android.com/reference/android/support/v17/leanback/widget/ListRowPresenter

  

• val listRowAdapter = ArrayObjectAdapter(cardPresenter): Determines how to display the individual movies you want to display
• val gridRowAdapter = ArrayObjectAdapter(mGridPresenter): Creates a grid in which to place each of the movies contained within cardPresenter

Thus, each ArrayObjectAdapter has its own presenter.

Each presenter constructs its own ViewHolder. (The ViewHolder class is an inner class of the Presenter class. Each presenter actually constructs its own Presenter.ViewHolder.) The next section tells you how this process works within the presenter.

A ViewHolder holds a view. (Don't look so surprised!) An instance of the ViewHolder class has no methods of its own and has only one public field. The public field is the view field. A ViewHolder instance's view field refers to whatever view the ViewHolder is holding. A presenter displays views, and a presenter gets its views from the ViewHolder. You can think of the ViewHolder as a cache for views.

In Listing 3-1, a call to an adapter's add() function adds an object to the adapter. This adding process happens in a number of ways:

• Adding a list of movies to a row (listRowAdapter)
• Adding rows of movies to a movie collection (rowsAdapter)
• Adding the rows of movies and other display details to a grid (gridRowAdapter)

Using the Presenter class

When you construct a new ArrayObjectAdapter, you supply a presenter in the constructor call. Thus, an ArrayObjectAdapter has its own presenter. Keep that idea in mind while you read the following facts:

• The presenter belonging to a row of items handles the presenting of an individual item (CardPresenter, which appears in CardPresenter.kt).

  A card is a rectangular area in which an object's data are displayed. In Figure 3-5, shown previously, the highlighted card's title is Zeitgeist 2010_ Year in Review.

• The presenter belonging to the entire list of items (think of a table with rows and columns) handles the presentation of those rows (ListRowPresenter, which is provided for you by Android).
• The presenter belonging to an entire grid handles the presenting of grid elements (GridItemPresenter, which appears in the MainFragment.kt file as an inner class).

The CardPresenter class offers a good example of how a presenter is constructed. Listing 3-2 shows the essential code given with the example app. (It has other elements as well, but these are the functions you should focus on.)

LISTING 3-2: The Presenter

override fun onCreateViewHolder(parent: ViewGroup):
Presenter.ViewHolder {

Log.d(TAG, "onCreateViewHolder")

sDefaultBackgroundColor = ContextCompat.getColor(parent.context,
R.color.default_background)
sSelectedBackgroundColor =
ContextCompat.getColor(parent.context,
R.color.selected_background)
mDefaultCardImage = ContextCompat.getDrawable(parent.context,
R.drawable.movie)

val cardView = object : ImageCardView(parent.context) {
override fun setSelected(selected: Boolean) {
updateCardBackgroundColor(this, selected)
super.setSelected(selected)
}
}

cardView.isFocusable = true
cardView.isFocusableInTouchMode = true
updateCardBackgroundColor(cardView, false)
return Presenter.ViewHolder(cardView)
}

override fun onBindViewHolder(viewHolder: Presenter.ViewHolder,
item: Any) {
val movie = item as Movie
val cardView = viewHolder.view as ImageCardView

Log.d(TAG, "onBindViewHolder")
if (movie.cardImageUrl != null) {
cardView.titleText = movie.title
cardView.contentText = movie.studio
cardView.setMainImageDimensions(CARD_WIDTH, CARD_HEIGHT)
Glide.with(viewHolder.view.context)
.load(movie.cardImageUrl)
.centerCrop()
.error(mDefaultCardImage)
.into(cardView.mainImageView)
}
}

override fun onUnbindViewHolder(viewHolder: Presenter.ViewHolder) {
Log.d(TAG, "onUnbindViewHolder")
val cardView = viewHolder.view as ImageCardView
// Remove references to images so that the garbage collector can
// free up memory
cardView.badgeImage = null
cardView.mainImage = null
}

The presenter in Listing 3-2 has three required methods:

• The onCreateViewHolder method does what its name suggests. It creates a ViewHolder instance.

  The ViewHolder instance has a view. How nice!

• The onBindViewHolder method binds data to a ViewHolder instance.

  In Listing 3-2, the view in the ViewHolder gets the properties needed to interact with the movie data. In particular, the card's title, cardView.titleText, becomes the content of movie.title.

• The onUnbindViewHolder method can do some cleanup when the data in a view becomes obsolete.

  In Listing 3-2, the onUnbindViewHolder method removes the references to the images so that the garbage collector can free the memory they use.