From b48317c0c00ee5106c7b7f741d22c044a0b2f031 Mon Sep 17 00:00:00 2001 From: Danila Fedorin Date: Wed, 13 May 2020 15:57:49 -0700 Subject: [PATCH] Document UI components that are not activities or fragments. --- .../fencelessgrazing/CollarClickListener.kt | 10 ++++++++++ .../fencelessgrazing/CollarSummaryAdapter.kt | 13 ++++++++++++- .../fencelessgrazing/CollarViewHolder.kt | 19 ++++++++++++++++++- .../StatisticsGraphAdapter.kt | 3 +++ .../requests/AuthenticatedRequest.kt | 2 +- 5 files changed, 44 insertions(+), 3 deletions(-) diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/CollarClickListener.kt b/app/src/main/java/com/danilafe/fencelessgrazing/CollarClickListener.kt index 0b1e8b6..fae185e 100644 --- a/app/src/main/java/com/danilafe/fencelessgrazing/CollarClickListener.kt +++ b/app/src/main/java/com/danilafe/fencelessgrazing/CollarClickListener.kt @@ -2,6 +2,16 @@ package com.danilafe.fencelessgrazing import com.danilafe.fencelessgrazing.model.CollarSummary +/** + * Simple interface used for the [CollarSummaryAdapter] to + * allow items in the collar list to respond to click events. + */ interface CollarClickListener { + + /** + * Method called when a collar is clicked in the [CollarSummaryAdapter]. + * + * @param collar the collar that was clicked. + */ fun onCollarClick(collar: CollarSummary?) } \ No newline at end of file diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/CollarSummaryAdapter.kt b/app/src/main/java/com/danilafe/fencelessgrazing/CollarSummaryAdapter.kt index ccc82a6..24c6fb5 100644 --- a/app/src/main/java/com/danilafe/fencelessgrazing/CollarSummaryAdapter.kt +++ b/app/src/main/java/com/danilafe/fencelessgrazing/CollarSummaryAdapter.kt @@ -11,12 +11,23 @@ import com.android.volley.toolbox.Volley import com.danilafe.fencelessgrazing.model.CollarSummary import com.danilafe.fencelessgrazing.requests.CollarRequest +/** + * A [ListAdapter] subclass to display and manage a list of [CollarSummary] items + * collected from a [CollarRequest]. + * + * @param items the list of items that are contained in this adapter. + * @param collarClickListener the action to be executed when an item in the list is clicked. + */ class CollarSummaryAdapter( private val items: List, private val collarClickListener: CollarClickListener ) : ListAdapter(DiffCallback()) { - class DiffCallback : DiffUtil.ItemCallback() { + /** + * [DiffUtil.ItemCallback] used for the [ListAdapter]. Compares items using + * the standard equality method generated for data classes. + */ + internal class DiffCallback : DiffUtil.ItemCallback() { override fun areItemsTheSame(oldItem: CollarSummary, newItem: CollarSummary): Boolean = oldItem.id == newItem.id diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/CollarViewHolder.kt b/app/src/main/java/com/danilafe/fencelessgrazing/CollarViewHolder.kt index a1bf77d..75a5bec 100644 --- a/app/src/main/java/com/danilafe/fencelessgrazing/CollarViewHolder.kt +++ b/app/src/main/java/com/danilafe/fencelessgrazing/CollarViewHolder.kt @@ -5,13 +5,30 @@ import android.widget.TextView import androidx.recyclerview.widget.RecyclerView import com.danilafe.fencelessgrazing.model.CollarSummary +/** + * A [RecyclerView.ViewHolder] used to render [CollarSummary] item entries. + */ class CollarViewHolder(itemView: View) : RecyclerView.ViewHolder(itemView) { + /** + * The [TextView] that holds the name of a collar. + */ private val nameView: TextView = itemView.findViewById(R.id.collarSummaryName) + + /** + * The [TextView] that holds the position of the collar. + */ private val positionView: TextView = itemView.findViewById(R.id.collarSummaryPos) + /** + * Called by the [CollarSummaryAdapter] to update the contents of the view this + * class holds. + * + * @param summary the collar summary whose data should be extracted and placed into the views. + * @param collarClickListener the action that should be called when a summary is clicked. + */ fun bindData(summary: CollarSummary, collarClickListener: CollarClickListener) { nameView.text = summary.name - positionView.text = nameView.resources.getString(R.string.collarSummaryLocation, + positionView.text = itemView.resources.getString(R.string.collarSummaryLocation, summary.pos.longitude.toDouble(), summary.pos.latitude.toDouble()) itemView.setOnClickListener { collarClickListener.onCollarClick(summary) diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/StatisticsGraphAdapter.kt b/app/src/main/java/com/danilafe/fencelessgrazing/StatisticsGraphAdapter.kt index 67b016f..d9dfeff 100644 --- a/app/src/main/java/com/danilafe/fencelessgrazing/StatisticsGraphAdapter.kt +++ b/app/src/main/java/com/danilafe/fencelessgrazing/StatisticsGraphAdapter.kt @@ -4,6 +4,9 @@ import androidx.fragment.app.Fragment import androidx.fragment.app.FragmentActivity import androidx.viewpager2.adapter.FragmentStateAdapter +/** + * Adapter for the [ViewPager2][androidx.viewpager2.widget.ViewPager2] class. + */ class StatisticsGraphAdapter(activity : FragmentActivity) : FragmentStateAdapter(activity) { override fun getItemCount(): Int = 1 override fun createFragment(position: Int): Fragment = DistanceTraveledGraph() diff --git a/app/src/main/java/com/danilafe/fencelessgrazing/requests/AuthenticatedRequest.kt b/app/src/main/java/com/danilafe/fencelessgrazing/requests/AuthenticatedRequest.kt index 02b1b09..6da2c81 100644 --- a/app/src/main/java/com/danilafe/fencelessgrazing/requests/AuthenticatedRequest.kt +++ b/app/src/main/java/com/danilafe/fencelessgrazing/requests/AuthenticatedRequest.kt @@ -4,7 +4,7 @@ import com.android.volley.Response import com.android.volley.toolbox.StringRequest /** - * General request aimed at a protected endpoint of the API. The [token] can be retrieved + * General request aimed at a protected endpoint of the API. The token can be retrieved * via a [LoginRequest], or, if you've made it past the login screen, via Shared Preferences. * * The [AuthenticatedRequest] expects to receive a string from the API endpoint; how this string