feat: Add a ScaleBar composable widget (#157)

* feat: Add a ScaleBar composable component

* chore: Fix typo in docs

* docs: Add documentation in README

* docs: Tweak docs

* docs: Tweak docs

* chore: Make DarkGray public for ScaleBar configuration

For example, if users want to specify it or different colors based on isSystemInDarkTheme()

* docs: Tweak docs

* chore: Allow setting width and height

* refactor: Rename duration variable and change to Int

This more closely matches other compose duration parameters

* refactor: Convert unit conversion functions to extension functions

* refactor: ScaleBar into maps-compose-widgets package

* chore: Switch to local module so artifact is always tied to same version as maps-compose

README.md

@@ -199,6 +199,38 @@ and don't use `Marker` composables (unless you don't care about `onClick`
 events). Clustering is the only use-case tested with `MapEffect`, there may be
 gotchas depending on what features you use in the utility library.
 
+## Widgets
+
+This library also provides optional composable widgets in the `maps-compose-widgets` library that you can use alongside the `GoogleMap` composable.
+
+### ScaleBar
+
+This widget shows the current scale of the map in feet and meters when zoomed into the map, changing to miles and kilometers, respectively, when zooming out. A `DisappearingScaleBar` is also included, which appears when the zoom level of the map changes, and then disappears after a configurable timeout period.
+
+The [ScaleBarActivity](app/src/main/java/com/google/maps/android/compose/ScaleBarActivity.kt) demonstrates both of these, with the `DisappearingScaleBar` in the upper left corner and the normal base `ScaleBar` in the upper right:
+
+![maps-compose-scale-bar-cropped](https://user-images.githubusercontent.com/928045/175665891-a0635004-2201-4392-83b3-0c6553b96926.gif)
+
+Both versions of this widget leverage the `CameraPositionState` in `maps-compose` and therefore are very simple to configure with their defaults:
+
+```kotlin
+ScaleBar(
+    modifier = Modifier
+            .padding(top = 5.dp, end = 15.dp)
+            .align(Alignment.TopEnd),
+    cameraPositionState = cameraPositionState
+)
+
+DisappearingScaleBar(
+    modifier = Modifier
+            .padding(top = 5.dp, end = 15.dp)
+            .align(Alignment.TopStart),
+    cameraPositionState = cameraPositionState
+)
+```
+
+The colors of the text, line, and shadow are also all configurable (e.g., based on `isSystemInDarkTheme()` on a dark map). Similarly, the `DisappearingScaleBar` animations can be configured.
+
 ## Sample App
 
 This repository includes a [sample app](app).
@@ -218,7 +250,10 @@ dependencies {
     implementation 'com.google.android.gms:play-services-maps:18.0.2'
     
     // Also include Compose version `1.2.0-alpha03` or higher - for example:
-    implementation "androidx.compose.foundation:foundation:2.4.0-alpha03"
+    implementation 'androidx.compose.foundation:foundation:2.4.0-alpha03'
+    
+    // Optionally, you can include the widgets library if you want to use ScaleBar, etc.
+    implementation 'com.google.maps.android:maps-compose-widgets:1.0.0'
 }
 ```
 

app/build.gradle

@@ -59,6 +59,8 @@ dependencies {
     // declaration if you want to test the sample app with a Maven Central release of the library.
     //implementation  "com.google.maps.android:maps-compose:2.2.1"
     implementation project(':maps-compose')
+    //implementation  "com.google.maps.android:maps-compose-widgets:1.0.0"
+    implementation project(':maps-compose-widgets')
     implementation 'com.google.android.gms:play-services-maps:18.0.2'
 }
 

app/src/main/AndroidManifest.xml

@@ -52,6 +52,9 @@
     <activity
         android:name=".LocationTrackingActivity"
         android:exported="false"/>
+    <activity
+        android:name=".ScaleBarActivity"
+        android:exported="false"/>
 
     <!-- Used by createComponentActivity() for unit testing -->
     <activity android:name="androidx.activity.ComponentActivity" />

app/src/main/java/com/google/maps/android/compose/MainActivity.kt

@@ -81,6 +81,13 @@ class MainActivity : ComponentActivity() {
                         }) {
                         Text(getString(R.string.location_tracking_activity))
                     }
+                    Spacer(modifier = Modifier.padding(5.dp))
+                    Button(
+                        onClick = {
+                            context.startActivity(Intent(context, ScaleBarActivity::class.java))
+                        }) {
+                        Text(getString(R.string.scale_bar_activity))
+                    }
                 }
             }
         }

app/src/main/java/com/google/maps/android/compose/ScaleBarActivity.kt

@@ -0,0 +1,99 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.maps.android.compose
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.EnterTransition
+import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.wrapContentSize
+import androidx.compose.material.CircularProgressIndicator
+import androidx.compose.material.MaterialTheme
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import com.google.android.gms.maps.model.CameraPosition
+import com.google.android.gms.maps.model.LatLng
+import com.google.maps.android.compose.widgets.DisappearingScaleBar
+import com.google.maps.android.compose.widgets.ScaleBar
+
+private const val TAG = "ScaleBarActivity"
+
+private const val zoom = 8f
+private val singapore = LatLng(1.35, 103.87)
+private val defaultCameraPosition = CameraPosition.fromLatLngZoom(singapore, zoom)
+
+class ScaleBarActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            var isMapLoaded by remember { mutableStateOf(false) }
+
+            // To control and observe the map camera
+            val cameraPositionState = rememberCameraPositionState {
+                position = defaultCameraPosition
+            }
+
+            Box(Modifier.fillMaxSize()) {
+                GoogleMap(
+                    modifier = Modifier.matchParentSize(),
+                    cameraPositionState = cameraPositionState,
+                    onMapLoaded = {
+                        isMapLoaded = true
+                    }
+                )
+                DisappearingScaleBar(
+                    modifier = Modifier
+                        .padding(top = 5.dp, end = 15.dp)
+                        .align(Alignment.TopStart),
+                    cameraPositionState = cameraPositionState
+                )
+                ScaleBar(
+                    modifier = Modifier
+                        .padding(top = 5.dp, end = 15.dp)
+                        .align(Alignment.TopEnd),
+                    cameraPositionState = cameraPositionState
+                )
+                if (!isMapLoaded) {
+                    AnimatedVisibility(
+                        modifier = Modifier
+                            .matchParentSize(),
+                        visible = !isMapLoaded,
+                        enter = EnterTransition.None,
+                        exit = fadeOut()
+                    ) {
+                        CircularProgressIndicator(
+                            modifier = Modifier
+                                .background(MaterialTheme.colors.background)
+                                .wrapContentSize()
+                        )
+                    }
+                }
+            }
+        }
+    }
+}

app/src/main/res/values/strings.xml

@@ -21,4 +21,5 @@
   <string name="map_in_column_activity">Map In Column</string>
   <string name="map_clustering_activity">Map Clustering</string>
   <string name="location_tracking_activity">Location Tracking</string>
+  <string name="scale_bar_activity">Scale Bar</string>
 </resources>

build.gradle

@@ -21,7 +21,7 @@ plugins {
 }
 
 ext.projectArtifactId = { project ->
-    if (project.name == 'maps-compose') {
+    if (project.name == 'maps-compose' || project.name == 'maps-compose-widgets') {
         return project.name
     } else {
         return null

maps-compose-widgets/.gitignore

@@ -0,0 +1 @@
+/build

maps-compose-widgets/build.gradle

@@ -0,0 +1,51 @@
+plugins {
+    id 'kotlin-android'
+    id 'kotlin-parcelize'
+}
+
+android {
+    compileSdk 31
+
+    defaultConfig {
+        minSdk 21
+        targetSdk 31
+        versionCode 1
+        versionName "1.0"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion "$compose_version"
+    }
+
+    buildFeatures {
+        buildConfig false
+        compose true
+    }
+
+    kotlinOptions {
+        jvmTarget = '1.8'
+        freeCompilerArgs += '-Xexplicit-api=strict'
+        freeCompilerArgs += '-Xopt-in=kotlin.RequiresOptIn'
+    }
+}
+
+dependencies {
+    implementation "androidx.compose.foundation:foundation:$compose_version"
+    implementation project(':maps-compose')
+    implementation 'androidx.compose.material:material:1.1.1'
+    implementation 'androidx.core:core-ktx:1.7.0'
+    implementation 'com.google.android.gms:play-services-maps:18.0.2'
+    implementation 'com.google.maps.android:maps-ktx:3.4.0'
+    implementation 'com.google.maps.android:maps-utils-ktx:3.3.0'
+
+    testImplementation 'junit:junit:4.13.2'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.3'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.4.0'
+    implementation "androidx.core:core-ktx:1.7.0"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:$kotlin_version"
+}

maps-compose-widgets/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

maps-compose-widgets/src/androidTest/java/com/google/maps/android/compose/widgets/ExampleInstrumentedTest.kt

@@ -0,0 +1,36 @@
+// Copyright 2021 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.maps.android.compose.widgets
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertEquals
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * See [testing documentation](http://d.android.com/tools/testing).
+ */
+@RunWith(AndroidJUnit4::class)
+internal class ExampleInstrumentedTest {
+    @Test
+    fun useAppContext() {
+        // Context of the app under test.
+        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
+        assertEquals("com.google.maps.android.compose.widgets.test", appContext.packageName)
+    }
+}

maps-compose-widgets/src/main/AndroidManifest.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ Copyright 2021 Google LLC
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manifest package="com.google.maps.android.compose.widgets">
+
+</manifest>