This week we will look at how we can create lists of items in Android, making use of RecyclerView.

RecyclerView

• The RecyclerView allows you to implement lists in a memory-efficient way.
• We insert the RecyclerView in an XML layout, wherever we want it to appear, in the normal way
• Example code for a recycler view, which can be placed in an XML layout (this example will occupy the whole of the parent):

  <androidx.recyclerview.widget.RecyclerView 
  android:layout_width="match_parent" 
  android:layout_height="0px" 
  app:layout_constraintBottom_toBottomOf="parent"
  app:layout_constraintTop_toTopOf="parent"
  android:id="@+id/moduleListView"/>

• When using a recycler view you have to specify its layout using a LayoutManager, e.g. LinearLayoutManager will specify that the items are arranged linearly (vertically):

  // This code is in the onCreate() of the Activity
  val moduleListView = findViewById<RecyclerView>(R.id.moduleListView)
  moduleListView.layoutManager = LinearLayoutManager(this)

• To use RecyclerView you must include it in your build.gradle dependencies, as it's a Jetpack library:

  implementation 'androidx.recyclerview:recyclerview:1.1.0'

Components of a RecyclerView

A RecyclerView contains:

• an adapter, which is used to control how the data being presented in the list is displayed.
• a series of ViewHolders. A ViewHolder is used to hold an individual View (list item) within the list being shown. It should extend from RecyclerView.ViewHolder.
• The idea is to preserve memory by only creating as many ViewHolders as are needed to contain visible list items
• So when we scroll the list up and down, resulting in some list items disappearing and new ones appearing, we can reallocate already-existing ViewHolders to the newly-visible items
• For example, if our list contains 100 items, but only 10 are visible at any one time, we need only create 10 ViewHolders, not 100, and then reuse these ViewHolders as the user scrolls the list up and down, so that they contain the 10 currently visible items

How to code a RecyclerView

• Create an Adapter class which should extend from RecyclerView.Adapter
• CWithin the Adapter, override the methods onCreateViewHolder(), onBindViewHolder(), and getItemCount(). What are these used for?
  • onCreateViewHolder() runs when we need to create a new view holder, e.g. when a list is first created, we create as many ViewHolders as we need to hold the visible items.
  • onBindViewHolder() runs when we need to bind an already-created holder with a particular item of data, e.g. if we scroll the screen and need to replace the contents of a view holder with a previously-hidden, newly-visible item.
  • getItemCount() should return the number of elements in our data set.
• Link the Adapter to your recycler view, e.g. if MyAdapter is your adapter class and moduleListView is a variable containing your RecyclerView, you could add code such as this to the onCreate() of your Activity to link the Adapter to the RecyclerView:

  moduleListView.adapter = MyAdapter(..)

Full example of adapter

import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.widget.TextView
import androidx.recyclerview.widget.RecyclerView

// The names and descriptions to be displayed are passed as parameters to
// our Adapter.
class MyAdapter(val titles: List<String>, 
                val descriptions: List<String>): 
    RecyclerView.Adapter<RecyclerView.ViewHolder>() {

    // A ViewHolder is associated with a particular adapter, so it makes
    // sense to create the holder as an inner class of the adapter.
    // The ViewHolder takes the associated View as a parameter

    inner class MyViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {

        // Inflate the child elements of the View and store them as properties,
        // so we have easy access to them later

        val tvName = itemView.findViewById(R.id.moduleName) as TextView
        val tvDescription = itemView.findViewById(R.id.moduleDescription) as TextView
    }

    // onCreateViewHolder() - called when a ViewHolder is first created.

    override fun onCreateViewHolder(parent: ViewGroup, viewType:Int) : RecyclerView.ViewHolder {
        // Inflate the XML layout and create a ViewHolder using it 

        val layoutInflater = LayoutInflater.from(parent.context)
        val inflatedLayout = layoutInflater.inflate(R.layout.list_item_layout, parent, false)
        return MyViewHolder(inflatedLayout)
    }

    // onBindViewHolder() - called when a ViewHolder is bound to a certain item of data.
    override fun onBindViewHolder(holder: RecyclerView.ViewHolder, index: Int) {
        // Cast to our specific ViewHolder class

        val myViewHolder = holder as MyViewHolder
    
        // Fill the name and description within the ViewHolder to the 
        // current elements within our two lists of data

        myViewHolder.tvName.text = titles[index]
        myViewHolder.tvDescription.text = descriptions[index]
    }

    override fun getItemCount(): Int {
        return titles.size
    }
}

Explanation of example: onCreateViewHolder()

In onCreateViewHolder(), we inflate a layout for an individual list item within the list.

• We write an XML layout file to define the layout of each individual list item. This might contain, for example, a TextView for a title and another for a description. An example is given below.
• We use a LayoutInflater to inflate this layout, which returns a View object containing the layout.
• We then create a ViewHolder to "hold" this view:
  • In the constructor of our ViewHolder (which takes the View as a parameter), we use View.findViewById() to obtain the child elements of the view (e.g. TextViews for title and description) using their ID. We then add these to the ViewHolder as properties, so that they can easily later be populated with data.
  • For programming convenience, the ViewHolder is often implemented as an inner class of the adapter (an inner class is a class within another class) as it means the ViewHolder can access all the adapter properties.
• The created ViewHolder is returned from onCreateViewHolder().

Explanation of example: onBindViewHolder()

In onBindViewHolder(), we bind the appropriate data to the current list item (e.g. the elements within our lists of data corresponding to the list item index)

• onBindViewHolder() has two parameters: the index of the list item we are processing, and its associated ViewHolder.
• We retrieve the corresponding item of data (e.g. from an array, list or database table holding the data)
• We then set the contents of the text views within this view holder to the details of the current item, so that the current item appears in the list

Layout for a list item

• As seen above, we have to define a layout for each list item in the RecyclerView
• Make it a LinearLayout and ensure that the height is set to wrap_content, not match_parent, otherwise each list item will occupy the whole screen
• e.g.

  <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  android:orientation="vertical"
  android:layout_width="match_parent"
  android:layout_height="wrap_content">
  
  <TextView android:layout_width="match_parent" 
  android:layout_height="wrap_content" android:id="@+id/moduleName" android:textSize="12pt" />
  
  <TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:id="@+id/moduleDescription" android:textSize="10pt" />
  
  </LinearLayout>

Handling events

• We may wish to handle events in our list, e.g. the user clicking on a list item.
• With ListActivity (the old way of implementing lists, before RecyclerView) this was done automatically by means of overriding the onListItemClick() event handler.
• With RecyclerView however we have to do it ourselves.
• ViewHolder has an "itemView" property representing the View associated with the ViewHolder.
• So, in onBindViewHolder() we can add an OnClickListener to the "itemView" of the ViewHolder, and call a callback function, passing the index to the callback.
• Kotlin makes this easy as we can pass in a callback to our Adapter and handle the click via a lambda which then calls our callback, passing in the index.
• e.g:

  import android.view.LayoutInflater
  import android.view.View
  import android.view.ViewGroup
  import android.widget.TextView
  import androidx.recyclerview.widget.RecyclerView
  
  class MyAdapter(val titles: List<String>, 
          val descriptions: List<String>,
          val callback: (Int) -> Unit): 
      RecyclerView.Adapter<RecyclerView.ViewHolder>() {
  
      inner class MyViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) {
          val tvName = itemView.findViewById(R.id.moduleName) as TextView
          val tvDescription = itemView.findViewById(R.id.moduleDescription) as TextView
      }
  
      override fun onCreateViewHolder(parent: ViewGroup, viewType:Int) : RecyclerView.ViewHolder {
          val layoutInflater = LayoutInflater.from(parent.context)
          return MyViewHolder(layoutInflater.inflate(R.layout.list_item_layout, parent, false))
      }
  
      override fun onBindViewHolder(holder: RecyclerView.ViewHolder, index: Int) {
          val myViewHolder = holder as MyViewHolder
          myViewHolder.tvName.text = titles[index]
          myViewHolder.tvDescription.text = descriptions[index]
          
          // Run our callback when the holder's itemView is clicked
          myViewHolder.itemView.setOnClickListener { callback(index) }
      }
  
      override fun getItemCount(): Int {
          return titles.size
      }
  }

Exercise

1. Turn the example above into a complete working application (at the moment, the RecyclerView part of the application has been coded, but not the main activity, so you need to implement an activity). Give the main activity an XML layout with a RecyclerView, as shown above. Fill the RecyclerView with the following titles and descriptions:
   • Title: Immersive Technologies, Description: Learn about developing augmented reality applications for the web, making use of three.js and A-Frame.
   • Title: Mobile Application Development, Description: Learn about Android development using Kotlin.
   • Title: Web Application Development, Description: Learn about web application development, including web APIs, JSON and AJAX.
2. More advanced: Modify your exercise from last year to search for all songs by a given artist by connecting to a web API, so that the search results appear in a RecyclerView. If you do not have it, please clone this repository containing a working solution:

   https://github.com/nwcourses/NetworkComm

   Each list item in the RecyclerView should contain:
   • The song title as the title;
   • The artist and year as the description.
   You will need to replace the TextView of your main activity layout with a RecyclerView, and you will need to pass two lists, one containing the titles, and one containing the descriptions, using the data obtained from the JSON.
   • Hint: you can use map() to do this: see the additional Week 1 notes from last year.
   • If you use my example code, or you used GSON, your life is easier because you have a Song class that you can use in your adapter. So your adapter should just contain a single list: a list of Song objects. You can obtain the title, artist and year from each Song in the list.
   Note that if you update your adapter with new data (i.e. new song details when doing a new search) you need to call the adapter's notifyDataSetChanged() method to inform the adapter that the data has changed and it needs to be redrawn. For example:

   myRecyclerView.adapter.notifyDataSetChanged()

   You will also need to download the Node.js based MAD song server from last year, and run it. Download from here.
3. Modify your answer to add a callback function when a list item is pressed. This callback can be passed in to to the adapter as a lambda function. The callback should simply display the details of the selected song as a Toast.