feat: Add a ScaleBar composable widget

[barbeau]

This PR refactors the work done in PR googlemaps/android-maps-ktx#175 to use android-maps-compose instead of relying on the GoogleMap object.

It creates a ScaleBar composable that 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 implemented, which imitates the scale bar behavior in the Google Maps app that appears when the zoom level of the map changes, and then disappears after a configurable timeout period.

A new ScaleBarActivity demonstrates both of these, with the DisappearingScaleBar in the upper left corner and the normal ScaleBar in the upper right (wait for the pause to see the left bar disappear):

Usage

Both components leverage the CameraPositionState in maps-compose and therefore are very simple to configure with their defaults:

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
)

Other configuration options

The colors of the text, line, and shadow are also all configurable (e.g., based on isSystemInDarkTheme() on a dark map) - here's the composable signature:

public fun ScaleBar(
    modifier: Modifier = Modifier,
    cameraPositionState: CameraPositionState,
    textColor: Color = DarkGray,
    lineColor: Color = DarkGray,
    shadowColor: Color = Color.White,
) {

Similarly, the DisappearingScaleBar animations can be configured:

public fun DisappearingScaleBar(
    modifier: Modifier = Modifier,
    cameraPositionState: CameraPositionState,
    textColor: Color = DarkGray,
    lineColor: Color = DarkGray,
    shadowColor: Color = Color.White,
    visibilityTimeoutMs: Long = 3_000,
    enterTransition: EnterTransition = fadeIn(),
    exitTransition: ExitTransition = fadeOut(),
) {

EDIT - This widget is going to be added in a new package maps-compose-widgets, and therefore needs another dependency as well:

    implementation 'com.google.maps.android:maps-compose-widgets:1.0.0'

---

Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Make sure to open a GitHub issue as a bug/feature request before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

Fixes googlemaps/android-maps-utils#701 🦕

[arriolac]

I had some minor comments in the PR and one comment around introducing a new package for this and potentially future components/widgets in the future. I strongly recommend that we go this route to keep maps-compose purely for core features which keeps the dependencies used at a minimal.

I was initially going to suggest to add a new composable lambda in the GoogleMap composable for widgets like this since the ScaleBar doesn't really make sense outside of the context of a GoogleMap. Something like:

GoogleMap(
  top = {
    ScaleBar(/* ... */)  
  }
)

But, I think if we introduce a separate package for this widget then we should go with the current approach you have.

[arriolac]

I'm a bit wary to add a new dependency like the utility library to maps-compose as it should be kept as lightweight as possible (ideally it should only contain Compose dependencies + the Maps SDK). How about creating a separate package for it? Something like maps-compose-widgets?

[barbeau]

Yeah, that makes a lot of sense to me. I like "widgets" as well, so maps-compose-widgets sounds good to me!

[barbeau]

@arriolac For configuring and publishing the artifact, can I duplicate most of what's in the maps-compose build.gradle (changing package names as appropriate)? Does other configuration need to happen to make this work?

[arriolac]

Yep, you can duplicate what's in there. Publishing code is on the project-level build.gradle file. You will have to make a new entry for artifactId so that it's applied to the new module. See: https://github.com/googlemaps/android-maps-compose/blob/main/build.gradle#L24

[barbeau]

Thanks! Done in 32e5a4e. Eyes on this are welcome to make sure I didn't miss anything.

[arriolac]

Just one more comment to address and one suggestion (can be addressed in the same PR or separately).

[arriolac]

This should reference the local module so the artifact is always tied to the same version as maps-compose.

implementation project(':maps-compose')

[barbeau]

Done in 33990bb

[arriolac]

suggestion: dependencies shared across modules should be defined in a separate gradle file so there is one version used by both artifacts. doesn't have to be addressed now but something for future reference.

[barbeau]

Sounds good. I opened #160 for this.

[googlemaps-bot]

🎉 This PR is included in version 2.5.0 🎉

The release is available on:

• v2.5.0
• GitHub release

Your semantic-release bot 📦🚀