OpenMapView

A modern, Kotlin-first MapView replacement for Android — powered by OpenStreetMap.

Installation

Add to your build.gradle.kts:

dependencies {
    implementation("de.afarber:openmapview:0.2.0")
}

The library is available on Maven Central. Alternative distribution via JitPack is also supported.

Features

• Drop-in compatible with Google MapView (non-deprecated methods only)
• Lightweight, pure Kotlin implementation
• OSM tiles via standard APIs
• Smooth camera animations with customizable durations
• Extensible marker, overlay, and gesture handling
• MIT licensed (use freely in commercial apps)

API Documentation

Full API reference documentation is available at afarber.github.io/OpenMapView.

The documentation is automatically generated from KDoc comments and updated with every commit to main.

Examples

Explore the example applications to see OpenMapView in action:

Example01Pan - Basic Map Panning

Demonstrates basic map tile rendering and touch pan gestures.

Example02Zoom - Zoom Controls and Gestures

Shows zoom functionality with FAB controls and pinch-to-zoom gestures.

Example03Markers - Marker Overlays

Demonstrates marker system with custom icons and click handling.

Example04Polylines - Polylines and Polygons

Shows how to draw vector shapes including polylines, filled polygons, and polygons with holes.

Example05Camera - Camera Animations

Demonstrates smooth camera animations with customizable durations and completion callbacks.

Documentation

• Contributing Guide - Code quality requirements, formatting, git hooks, and PR process
• Lifecycle Management - How OpenMapView handles Android lifecycle events
• Publishing Guide - Publishing to Maven Central and JitPack
• GitHub Workflows - CI/CD pipeline and workflow architecture
• Unit Testing - JVM unit tests with Robolectric for Android framework APIs
• Instrumented Testing - On-device (phone and auto) testing with Android emulator

Getting Started

With Jetpack Compose

@Composable
fun MapViewScreen() {
    val lifecycleOwner = androidx.lifecycle.compose.LocalLifecycleOwner.current

    AndroidView(
        factory = { context ->
            OpenMapView(context).apply {
                // Register lifecycle observer for proper cleanup
                lifecycleOwner.lifecycle.addObserver(this)

                setCenter(LatLng(51.4661, 7.2491))
                setZoom(14.0)

                // Add markers (optional)
                addMarker(Marker(
                    position = LatLng(51.4661, 7.2491),
                    title = "Bochum City Center"
                ))
            }
        },
        modifier = Modifier.fillMaxSize()
    )
}

With XML Layouts

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        val mapView = findViewById<OpenMapView>(R.id.mapView)
        mapView.setZoom(14.0)
        mapView.setCenter(LatLng(51.4661, 7.2491))
    }
}