KatMaps is a declarative API wrapper that simplifies the usage of the Android Google Maps SDK. It is written in Kotlin and provides a Kotlin first API.

List of all Google Maps SDK features currently supported by KatMaps

1. Map markers (No z-index property yet)
2. Marker click listener
3. Map click listener
4. Map move listener
5. Map Positioning
6. Google Map Themes

These are features added on top of the Google Maps SDK.

• Self explanatory - invokes a callback when a marker is deselected.

• Selected/Deselected marker animations

• Modifies Google map's marker click listener to respond instaneously to marker clicks

• Improved capability of being able to differentiate markers packed close together on a map. Toggles between a group of markers close to where the user clicks on the map, starting with the marker closest to the user's tap.

• Map marker labels are implemented as part of the KatMaps library. It handles hiding labels that overlap other labels by default.

• Set it and forget it. No more waiting and checking for Google Maps to be initialized.
• Enhanced readability
  • Map properties are defined by simple data classes rather than complex builders
• Separation of concerns
  • Developer doesn't have to take into account Google Map's life cycle events

• Control map with center and radius instead of arbitrary zoom level
• Use padding to account for views obstructing the map's visibility

1. Import the katmaps-library Gradle module into your Android project.

2. Add the KatMaps library as a dependency to your app in build.gradle

   implementation project(":katmaps-library")

3. Add your Google Maps API key to AndroidManifest.xml

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="YOUR_GOOGLE_MAPS_API_KEY_HERE"/>

4. Create a layout with FrameLayout as the placeholder for the MapFragment that we'll be adding later

   <FrameLayout
   	android:id="@+id/mapPlaceholder"
   	android:layout_width="match_parent"
   	android:layout_height="match_parent" />

5. Create instance of MapFragment in your activity

   private val map = MapFragment()

6. Add fragment to mapPlaceholder in your layout with the MapFragment object we just created

   supportFragmentManager.beginTransaction().add(R.id.katmaps, mapPlaceholder).commit()

7. You are now ready to use KatMaps

• Avoid using the onMapReady listener! Being a declarataive API, KatMaps is ready to be used once the object is created.

Once you have KatMaps set up, you can begin manipulating the map. Here are some examples of what you can do.

val pinIcon = MapIcon.Image(someBitmap)
val sevenWonders = listOf(
	MapMarker(
		tag = "Great Wall",
		position = GeoCoordinate(1.0, 1.0),
		icon = pinIcon,
		title = "The Great Wall of China"
	)
)

map.markers = sevenWonders

map.markers = emptyList()

map.onMarkerClickListener = { marker ->
    Log.i("Demo", "Clicked: ${marker.labelTitle} - ${marker.labelDescription}")
}

map.onMarkerDeselectedListener = { marker ->
    Log.i("Demo", "Deselected: ${marker.labelTitle} - ${marker.labelDescription}")
}

map.cameraPosition = MapBounds.fromCenter(
    center = GeoCoordinate(41.9019876, -87.6561932),
    radius = 2.miles
)

Note: You must check for permissions or this won't work

map.showCurrentLocation = true

val previousCameraPosition: MapBound = map.cameraPosition

map.cameraPosition = MapBounds.fromCenter(
    center = previousCameraPosition.center,
    radius = 2.miles,
    tilt = 30f
)

map.moveCamera(
    mapBounds = MapBounds.fromCenter(
        center = GeoCoordinate(41.9019876, -87.6561932),
        radius = 2.miles
    ),
    animated = true
)

map.cameraPosition = MapBounds.fromCenter(
    center = GeoCoordinate(41.9019876, -87.6561932),
    radius = 2.miles,
    padding = MapBounds.Padding(0.1f, 0.1f, 0.1f, 0.1f)
)

map.cameraPosition = MapBounds.fromCenter(
    center = GeoCoordinate(41.9019876, -87.6561932),
    radius = 2.miles,
    padding = MapBounds.Padding(0f, 0.2f, 0f, 0f)
)

1. Add your Google Maps API Key (pick one):

   • In the Android Manifest of the demo-app module:

      <meta-data
      	android:name="com.google.android.geo.API_KEY"
      	android:value="PUT_YOUR_KEY_HERE"/>

   • Add to your environment variable:

     export KATMAPS_DEMO_GOOGLE_KEY="PUT_YOUR_KEY_HERE"

2. Import into Android Studio

3. Run demo-app

1. Support multiple map providers through a common API
2. Multi-platform support via Kotlin Multiplatform
3. Map Circles/Polylines/Polygons
4. Info windows
5. Efficiently handle diffing changes to marker sets when setting markers rather than removing all markers and creating new ones
6. Allow for multiple markers to be selected/upper bound for markers selected
7. Anything else that's in Google Maps SDK that isn't in KatMaps
8. Animated drawables support for marker animation
9. Thoroughly test MapBounds.ScaleStrategy