refactor(demo): Modernize PolylineProgressDemoActivity

dkhawk · dkhawk · commit 38c49d947afd · 2025-09-05T14:02:19.000-06:00
This commit significantly refactors the `PolylineProgressDemoActivity` to align with modern Android development practices and better showcase the library's features.

Key changes include:
- **View Binding**: Replaced `findViewById` with View Binding for type-safe and more concise access to UI components. This required enabling `viewBinding` in the demo's `build.gradle.kts`.
- **Lifecycle-Aware Coroutines**: The animation now uses `lifecycleScope`, ensuring the coroutine is automatically canceled when the Activity is destroyed, preventing memory leaks.
- **State Management**: Replaced multiple `MutableLiveData` instances with a single `LiveData&lt;AnimationState&gt;` data class. This creates a single source of truth for the animation's state, leading to more predictable and maintainable UI updates.
- **Code Structure and Documentation**: The code has been reorganized into smaller, more focused functions. Extensive KDoc comments have been added to explain the implementation, highlight the use of `SphericalUtil`, and document the modern Android patterns being used.
diff --git a/demo/build.gradle.kts b/demo/build.gradle.kts
@@ -44,6 +44,10 @@ android {
         }
     }
 
+    buildFeatures {
+        viewBinding = true
+    }
+
     kotlinOptions {
         jvmTarget = "17"
     }
diff --git a/demo/src/main/java/com/google/maps/android/utils/demo/PolylineProgressDemoActivity.kt b/demo/src/main/java/com/google/maps/android/utils/demo/PolylineProgressDemoActivity.kt
@@ -2,146 +2,142 @@ package com.google.maps.android.utils.demo
 
 import android.graphics.Canvas
 import android.graphics.Color
-import android.os.Bundle
-import android.widget.Button
+import android.view.ViewGroup
 import android.widget.SeekBar
-import android.widget.TextView
-import androidx.appcompat.app.AppCompatActivity
 import androidx.core.content.ContextCompat
+import androidx.core.graphics.createBitmap
+import androidx.core.graphics.toColorInt
 import androidx.lifecycle.MutableLiveData
+import androidx.lifecycle.lifecycleScope
 import com.google.android.gms.maps.CameraUpdateFactory
-import com.google.android.gms.maps.GoogleMap
-import com.google.android.gms.maps.OnMapReadyCallback
-import com.google.android.gms.maps.SupportMapFragment
 import com.google.android.gms.maps.model.BitmapDescriptor
 import com.google.android.gms.maps.model.BitmapDescriptorFactory
 import com.google.android.gms.maps.model.LatLng
+import com.google.android.gms.maps.model.LatLngBounds
 import com.google.android.gms.maps.model.Marker
 import com.google.android.gms.maps.model.MarkerOptions
 import com.google.android.gms.maps.model.Polyline
 import com.google.android.gms.maps.model.PolylineOptions
 import com.google.maps.android.SphericalUtil
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Dispatchers
+import com.google.maps.android.utils.demo.databinding.ActivityPolylineProgressDemoBinding
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
-import androidx.core.graphics.createBitmap
-import androidx.core.graphics.toColorInt
 
-class PolylineProgressDemoActivity : AppCompatActivity(), OnMapReadyCallback, SeekBar.OnSeekBarChangeListener {
+/**
+ * This demo showcases how to animate a marker along a geodesic polyline, illustrating
+ * key features of the Android Maps Utils library and modern Android development practices.
+ */
+class PolylineProgressDemoActivity : BaseDemoActivity(), SeekBar.OnSeekBarChangeListener {
+
+    companion object {
+        private const val POLYLINE_WIDTH = 15f
+        private const val PROGRESS_POLYLINE_WIDTH = 7f
+        private const val ANIMATION_STEP_SIZE = 1
+        private const val ANIMATION_DELAY_MS = 75L
+    }
 
-    private var planeIcon: BitmapDescriptor? = null
-    private lateinit var map: GoogleMap
+    private lateinit var binding: ActivityPolylineProgressDemoBinding
     private lateinit var originalPolyline: Polyline
     private var progressPolyline: Polyline? = null
     private var progressMarker: Marker? = null
 
-    private lateinit var seekBar: SeekBar
-    private lateinit var percentageTextView: TextView
+    private val planeIcon: BitmapDescriptor by lazy {
+        bitmapDescriptorFromVector(R.drawable.baseline_airplanemode_active_24, "#FFD700".toColorInt())
+    }
 
-    private var isReady = false
-    private var animationJob: Job? = null
+    private data class AnimationState(val progress: Int, val direction: Int)
 
-    private val progress = MutableLiveData<Int>()
-    private val direction = MutableLiveData<Int>()
-    private val stepSize = 1
+    private val animationState = MutableLiveData<AnimationState>()
+    private var animationJob: Job? = null
 
     private val polylinePoints = listOf(
         LatLng(40.7128, -74.0060),   // New York
+        LatLng(47.6062, -122.3321),  // Seattle
+        LatLng(39.7392, -104.9903),  // Denver
+        LatLng(37.7749, -122.4194),  // San Francisco
         LatLng(34.0522, -118.2437),  // Los Angeles
         LatLng(41.8781, -87.6298),   // Chicago
         LatLng(29.7604, -95.3698),   // Houston
         LatLng(39.9526, -75.1652)    // Philadelphia
     )
 
-    override fun onCreate(savedInstanceState: Bundle?) {
-        super.onCreate(savedInstanceState)
-        isReady = false
-        setContentView(R.layout.activity_polyline_progress_demo)
+    override fun getLayoutId(): Int = R.layout.activity_polyline_progress_demo
 
-        val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as SupportMapFragment
-        mapFragment.getMapAsync(this)
+    /**
+     * This is where the demo begins. It is called from the base activity's `onMapReady` callback.
+     */
+    override fun startDemo(isRestore: Boolean) {
+        // The layout is already inflated by the base class. We can now bind to it.
+        val rootView = (findViewById<ViewGroup>(android.R.id.content)).getChildAt(0)
+        binding = ActivityPolylineProgressDemoBinding.bind(rootView)
 
-        progress.value = 0
-        direction.value = 1
+        setupMap()
+        setupUI()
+        // Set the initial state. The observer in setupUI will handle the first UI update.
+        animationState.value = AnimationState(progress = 0, direction = 1)
+        startAnimation()
     }
 
-    override fun onMapReady(googleMap: GoogleMap) {
-        map = googleMap
-        isReady = true
-
-        planeIcon = bitmapDescriptorFromVector(R.drawable.baseline_airplanemode_active_24, "#FFD700".toColorInt())
-
+    private fun setupMap() {
         originalPolyline = map.addPolyline(
             PolylineOptions()
                 .addAll(polylinePoints)
                 .color(Color.GRAY)
-                .width(15f) // Set the width of the base polyline
-                .geodesic(true) // Be sure to set the geodesic flag!
+                .width(POLYLINE_WIDTH)
+                .geodesic(true) // A geodesic polyline follows the curvature of the Earth.
         )
 
-        val bounds = with(com.google.android.gms.maps.model.LatLngBounds.Builder()) {
-            for (point in polylinePoints) {
-                include(point)
-            }
-            build()
-        }
-
+        val bounds = LatLngBounds.builder().apply {
+            polylinePoints.forEach { include(it) }
+        }.build()
         map.moveCamera(CameraUpdateFactory.newLatLngBounds(bounds, 100))
+    }
 
-        percentageTextView = findViewById(R.id.percentageTextView)
-        seekBar = findViewById<SeekBar>(R.id.seekBar).also {
-            it.setOnSeekBarChangeListener(this)
-            it.progress = 0
-        }
-
-        findViewById<Button>(R.id.resetButton).setOnClickListener {
-            if (animationJob != null) {
-                animationJob?.cancel()
-                animationJob = null
-            }
-            direction.value = 1
-            progress.value = 0
+    private fun setupUI() {
+        binding.seekBar.setOnSeekBarChangeListener(this)
+        binding.resetButton.setOnClickListener {
+            stopAnimation()
+            animationState.value = AnimationState(progress = 0, direction = 1)
             startAnimation()
         }
-
-        findViewById<Button>(R.id.pauseButton).setOnClickListener {
-            if (animationJob != null) {
-                animationJob?.cancel()
-                animationJob = null
+        binding.pauseButton.setOnClickListener {
+            if (animationJob?.isActive == true) {
+                stopAnimation()
             } else {
                 startAnimation()
             }
         }
 
-        progress.observe(this) {
-            seekBar.progress = it
-            percentageTextView.text = "$it%"
-            updateProgress(it / 100.0)
+        animationState.observe(this) { state ->
+            binding.seekBar.progress = state.progress
+            binding.percentageTextView.text = getString(R.string.percentage_format, state.progress)
+            updateProgressOnMap(state.progress / 100.0, state.direction)
         }
-
-        startAnimation()
     }
 
     private fun startAnimation() {
-        stopAnimation() // Stop any existing animation first
+        stopAnimation()
+        val currentState = animationState.value ?: return
 
-        // Start a coroutine to animate the polyline progress
-        animationJob = CoroutineScope(Dispatchers.Main).launch {
+        animationJob = lifecycleScope.launch {
+            var progress = currentState.progress
+            var direction = currentState.direction
             while (true) {
-                val currentProgress = progress.value ?: 0
-                val currentDirection = direction.value ?: 1
-                var nextProgress = currentProgress + currentDirection * stepSize
-                if (nextProgress >= 100) {
-                    nextProgress = 100
-                    direction.value = -1
-                } else if (nextProgress <= 0) {
-                    nextProgress = 0
-                    direction.value = 1
+                progress = when {
+                    progress > 100 -> {
+                        direction = -1
+                        100
+                    }
+                    progress < 0 -> {
+                        direction = 1
+                        0
+                    }
+                    else -> progress + direction * ANIMATION_STEP_SIZE
                 }
-                progress.value = nextProgress
-                delay(50)
+
+                animationState.postValue(AnimationState(progress, direction))
+                delay(ANIMATION_DELAY_MS)
             }
         }
     }
@@ -151,30 +147,18 @@ class PolylineProgressDemoActivity : AppCompatActivity(), OnMapReadyCallback, Se
         animationJob = null
     }
 
-    override fun onPause() {
-        super.onPause()
-        animationJob?.cancel()
-    }
-
-    override fun onResume() {
-        super.onResume()
-        startAnimation()
-    }
-
     override fun onProgressChanged(seekBar: SeekBar?, progress: Int, fromUser: Boolean) {
         if (fromUser) {
             stopAnimation()
-            this.progress.value = progress
+            animationState.value = AnimationState(progress, animationState.value?.direction ?: 1)
         }
     }
 
-    override fun onStartTrackingTouch(seekBar: SeekBar?) {}
+    override fun onStartTrackingTouch(seekBar: SeekBar?) { /* No-op */ }
 
-    override fun onStopTrackingTouch(seekBar: SeekBar?) {}
-
-    private fun updateProgress(percentage: Double) {
-        if (!isReady) return
+    override fun onStopTrackingTouch(seekBar: SeekBar?) { /* No-op */ }
 
+    private fun updateProgressOnMap(percentage: Double, direction: Int) {
         progressPolyline?.remove()
 
         val prefix = SphericalUtil.getPolylinePrefix(polylinePoints, percentage)
@@ -183,53 +167,49 @@ class PolylineProgressDemoActivity : AppCompatActivity(), OnMapReadyCallback, Se
                 PolylineOptions()
                     .addAll(prefix)
                     .color(Color.BLUE)
-                    .width(7f) // Set the width of the progress polyline
-                    .zIndex(1f) // Set the z-index to draw it on top
-                    .geodesic(true) // Be sure to set the geodesic flag!
+                    .width(PROGRESS_POLYLINE_WIDTH)
+                    .zIndex(1f)
+                    .geodesic(true)
             )
         }
 
-        val point = SphericalUtil.getPointOnPolyline(polylinePoints, percentage)
-        if (point != null) {
-            // Get the next point to calculate the heading
-            val nextPoint = SphericalUtil.getPointOnPolyline(polylinePoints, percentage + 0.0001)
-            var heading = nextPoint?.let { SphericalUtil.computeHeading(point, it) }
-            if (direction.value == -1) {
-                heading = heading?.plus(180)
-            }
+        SphericalUtil.getPointOnPolyline(polylinePoints, percentage)?.let { point ->
+            updateMarker(point, percentage, direction)
+        }
+    }
 
-            if (progressMarker == null) {
-                progressMarker = map.addMarker(
-                    MarkerOptions()
-                        .position(point)
-                        .flat(true)
-                        .draggable(false)
-                        .also {
-                            if (heading != null) {
-                                it.rotation(heading.toFloat())
-                            }
-                            if (planeIcon != null) {
-                                it.icon(planeIcon)
-                            }
-                        }
-                )
-            } else {
-                progressMarker?.position = point
-                if (heading != null) {
-                    progressMarker?.rotation = heading.toFloat()
-                }
+    private fun updateMarker(point: LatLng, percentage: Double, direction: Int) {
+        val heading = SphericalUtil.getPointOnPolyline(polylinePoints, percentage + 0.0001)
+            ?.let { SphericalUtil.computeHeading(point, it) }
+            ?.let { if (direction == -1) it + 180 else it } // Adjust for reverse direction.
+
+        if (progressMarker == null) {
+            progressMarker = map.addMarker(
+                MarkerOptions()
+                    .position(point)
+                    .flat(true)
+                    .draggable(false)
+                    .icon(planeIcon)
+                    .apply { heading?.let { rotation(it.toFloat()) } }
+            )
+        } else {
+            progressMarker?.also {
+                it.position = point
+                heading?.let { newHeading -> it.rotation = newHeading.toFloat() }
             }
         }
     }
 
-    private fun bitmapDescriptorFromVector(vectorResId: Int, color: Int): BitmapDescriptor? {
-        return ContextCompat.getDrawable(this, vectorResId)?.run {
-            setTint(color)
-            setBounds(0, 0, intrinsicWidth, intrinsicHeight)
-            val bitmap = createBitmap(intrinsicWidth, intrinsicHeight)
-            val canvas = Canvas(bitmap)
-            draw(canvas)
-            BitmapDescriptorFactory.fromBitmap(bitmap)
-        }
+    private fun bitmapDescriptorFromVector(vectorResId: Int, color: Int): BitmapDescriptor {
+        val vectorDrawable = ContextCompat.getDrawable(this, vectorResId)!!
+        vectorDrawable.setTint(color)
+        val bitmap = createBitmap(
+            vectorDrawable.intrinsicWidth,
+            vectorDrawable.intrinsicHeight
+        )
+        val canvas = Canvas(bitmap)
+        vectorDrawable.setBounds(0, 0, canvas.width, canvas.height)
+        vectorDrawable.draw(canvas)
+        return BitmapDescriptorFactory.fromBitmap(bitmap)
     }
 }
diff --git a/demo/src/main/res/values/strings.xml b/demo/src/main/res/values/strings.xml
@@ -34,4 +34,5 @@
     <string name="button_gradient">Gradient</string>
     <string name="button_opacity">Opacity</string>
     <string name="bad_maps_api_key">Invalid or missing Google Maps API key</string>
+    <string name="percentage_format">%1$d%%</string>
 </resources>

Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,10 @@ android {`
`44`	`44`	`}`
`45`	`45`	`}`
`46`	`46`
	`47`	`+ buildFeatures {`
	`48`	`+ viewBinding = true`
	`49`	`+ }`
	`50`	`+`
`47`	`51`	`kotlinOptions {`
`48`	`52`	`jvmTarget = "17"`
`49`	`53`	`}`