Need help with android-maps-ktx?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

googlemaps
149 Stars 19 Forks Apache License 2.0 147 Commits 7 Opened issues

Description

Kotlin extensions (KTX) for the Maps SDK and Utility Library for Android

Services available

!
?

Need anything else?

Contributors list

Tests Stable Discord Apache-2.0

Maps Android KTX

Description

This repository contains Kotlin extensions (KTX) for: 1. The Maps SDK for Android 1. The Maps SDK for Android Utility Library

It enables you to write more concise, idiomatic Kotlin. Each set of extensions can be used independently or together.

Requirements

  • Kotlin-enabled project
  • Kotlin coroutines
  • API level 15+

Installation

If you are using the Maps SDK through Google Play Services:

dependencies {

// KTX for the Maps SDK for Android library
implementation 'com.google.maps.android:maps-ktx:2.2.0'

// KTX for the Maps SDK for Android Utility Library
implementation 'com.google.maps.android:maps-utils-ktx:2.2.0'

// It is recommended to also include the latest Maps SDK and/or Utility Library versions
// as well to ensure that you have the latest features and bug fixes.
implementation 'com.google.android.gms:play-services-maps:17.0.0'
implementation 'com.google.maps.android:android-maps-utils:2.0.3'

}

Alternatively, if you are using the Maps SDK through the standalone V3 BETA distribution:

dependencies {

// KTX for the Maps SDK for Android V3 BETA Library
implementation 'com.google.maps.android:maps-v3-ktx:2.2.0'

// KTX for the Maps SDK for Android V3 BETA Utility Library
implementation 'com.google.maps.android:maps-utils-v3-ktx:2.2.0'

// It is recommended to also include the latest Maps SDK and/or Utility Library versions
// as well to ensure that you have the latest features and bug fixes.
implementation 'com.google.android.libraries.maps:maps:3.1.0-beta'
implementation 'com.google.maps.android:android-maps-utils-v3:2.0.3'

}

Example Usage

With this KTX library, you should be able to take advantage of several Kotlin language features such as extension functions, named parameters and default arguments, destructuring declarations, and coroutines.

Demo App

This repository includes a demo app that illustrates the use of this KTX library.

To run the demo app, you'll have to:

  1. Get a Maps API key
  2. Create a file in the root directory called
    secure.properties
    (this file should NOT be under version control to protect your API key)
  3. Add a single line to
    secure.properties
    that looks like
    MAPS_API_KEY=YOUR_API_KEY
    , where
    YOUR_API_KEY
    is the API key you obtained in the first step
  4. Build and run

Maps SDK KTX

Extension functions

Adding a

Marker
:

Before

java
GoogleMap googleMap = // ...
LatLng sydney = new LatLng(-33.852, 151.211);
MarkerOptions markerOptions = new MarkerOptions()
    .position(Sydney)
    .title("Marker in Sydney");
Marker marker = googleMap.addMarker(markerOptions);

After

kotlin
val googleMap = // ...
val sydney = LatLng(-33.852, 151.211)
val marker = googleMap.addMarker {
    position(sydney)
    title("Marker in Sydney")
}

Coroutines

Accessing a

GoogleMap
instance can be retrieved using coroutines vs. traditional the callback mechanism. The example here demonstrates how you can use this feature alongside with Lifecycle-aware coroutine scopes provided in Android’s Architecture Components. To use this, you'll need to add the following to your
build.gradle
dependencies:
implementation 'androidx.lifecycle:lifecycle-runtime-ktx:'

Before ```java @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); SupportMapFragment mapFragment = ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map));

mapFragment.getMapAsync(new OnMapReadyCallback {
    @Override
    public void onMapReady(GoogleMap googleMap) {
        // Access GoogleMap instance here
    }
});

} ```

After ```kotlin override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val mapFragment = supportFragmentManager.findFragmentById(R.id.map) as? SupportMapFragment

lifecycle.coroutineScope.launchWhenCreated {
    val googleMap = mapFragment?.awaitMap()
}

} ```

Flow

Note: The following feature utilizes an experimental coroutine API. To use this, you will have to add the

@OptIn(ExperimentalCoroutinesApi::class)
at the site of its usage as well as the compiler flag
-Xopt-in=kotlin.RequiresOptIn
.

Listing to camera events can be collected via Kotlin Flow.

Before

java
val googleMap = //...
googleMap.setOnCameraIdleListener = { //... }
googleMap.setOnCameraMoveCanceledListener { //... }
googleMap.setOnCameraMoveListener { //... }
googleMap.setOnCameraMoveStartedListener { //... }

After

kotlin
// To be invoked within a coroutine scope
googleMap.cameraEvents().collect { event ->
    when (event) {
        is CameraIdleEvent -> //...
        is CameraMoveCanceledEvent -> //...
        is CameraMoveEvent -> //...
        is CameraMoveStartedEvent -> //...
    }
}

Maps SDK for Android Utilities KTX

Extension functions

Checking if a

LatLng
is contained within a
Polygon
:

Before

java
Polygon polygon = // some polygon
LatLng latlng = // some latlng
boolean result = PolygonUtil.containsLocation(latlng, polygon.getPoints(), true);

After

kotlin
val polygon: Polygon = // some polygon
val latlng: LatLng = // some latlng
val result: Boolean = polygon.contains(latLng)

Named parameters and default arguments

Creating a

GeoJsonLayer
object:

Before

java
GeoJsonLayer layer = new GeoJsonLayer(
    map, 
    geoJsonFile, 
    null, 
    polygonManager, 
    null, 
    groundOverlayManager
);

After

kotlin
val layer = geoJsonLayer(
    map = map,
    geoJsonFile = geoJsonFile,
    polygonManager = polygonManager,
    groundOverlayManager = groundOverlayManager
)

Destructuring Declarations

Destructuring properties of a

Point
:

Before

java
Point point = new Point(1.0, 2.0);
double x = point.x;
double y = point.y;

After

kotlin
val point = Point(1.0, 2.0)
val (x, y) = point

Documentation

You can learn more about all the extensions provided by this library by reading the reference documents.

Support

Encounter an issue while using this library?

If you find a bug or have a feature request, please file an issue. Or, if you'd like to contribute, send us a pull request and refer to our code of conduct.

You can also reach us on our Discord channel.

For more information, check out the detailed guide on the Google Developers site.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.