### Install and Launch Example App via Command Line

Source: https://github.com/afarber/openmapview/blob/main/examples/Example09Overlays/README.md

Provides command-line instructions to build, install, and launch the `Example09Overlays` Android application. It utilizes Gradle wrapper for building and `adb` for installing and starting the activity.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example09Overlays:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example09overlays/.MainActivity
```

--------------------------------

### Install and Launch Example App from Command Line

Source: https://github.com/afarber/openmapview/blob/main/examples/Example07DraggableMarkers/README.md

Provides bash commands to build, install, and launch the specific example application module from the project root using Gradle and ADB. This is an alternative to running within an IDE.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example07DraggableMarkers:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example07draggablemarkers/.MainActivity
```

--------------------------------

### Build and Install Example App

Source: https://github.com/afarber/openmapview/blob/main/examples/Example10GroundOverlays/README.md

Provides command-line instructions to build the example application using Gradle and install it on an Android device or emulator using ADB. This is an alternative to running the app directly from Android Studio.

```bash
./gradlew :examples:Example10GroundOverlays:assembleDebug
adb install examples/Example10GroundOverlays/build/outputs/apk/debug/Example10GroundOverlays-debug.apk
adb shell am start -n de.afarber.openmapview.example10groundoverlays/.MainActivity
```

--------------------------------

### Build and Install OpenMapView Example (Bash)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example06Clicks/README.md

Provides command-line instructions to build, install, and launch the `Example06Clicks` application on an Android device or emulator. It utilizes Gradle for building and ADB for installation and launching.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example06Clicks:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example06clicks/.MainActivity
```

--------------------------------

### Build and Install Example App (Bash)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example04Polylines/README.md

Provides command-line instructions to build the `Example04Polylines` module, install the debug APK onto a connected device or emulator, and then launch the application.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example04Polylines:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example04polylines/.MainActivity
```

--------------------------------

### Build and Install OpenMapView Example (Bash)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example05Camera/README.md

Commands to build, install, and launch the Example05Camera application from the command line using Gradle. This is an alternative to running the app directly from Android Studio.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example05Camera:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example05camera/.MainActivity
```

--------------------------------

### Build and Install OpenMapView Example App (Bash)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example11MapTypes/README.md

Provides command-line instructions to build, install, and launch the Example11MapTypes app from the project root using Gradle. It requires Android SDK and Gradle to be set up.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example11MapTypes:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example11maptypes/.MainActivity
```

--------------------------------

### Build and Install Android App from Command Line

Source: https://github.com/afarber/openmapview/blob/main/examples/Example03Markers/README.md

Instructions for building and installing the Example03Markers app from the command line using Gradle wrapper. This is an alternative to running the app directly from Android Studio.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example03Markers:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example03markers/.MainActivity
```

--------------------------------

### Example JVM Unit Test with Robolectric

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Demonstrates a basic JVM unit test using Robolectric. This test verifies the `defaultMarker()` method from `BitmapDescriptorFactory`, asserting its non-nullability and dimensions.

```kotlin
@RunWith(RobolectricTestRunner::class)
class BitmapDescriptorFactoryTest {
    @Test
    fun testDefaultMarker_Red() {
        val bitmap = BitmapDescriptorFactory.defaultMarker()
        assertNotNull(bitmap)
        assertEquals(48, bitmap.width)
        assertEquals(72, bitmap.height)
    }
}
```

--------------------------------

### JitPack Development Snapshots in Kotlin

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

Examples demonstrating how to include development snapshots of OpenMapView from JitPack in a Kotlin project, using different references like the main branch, a specific commit, or a feature branch.

```kotlin
// Latest commit from main branch
implementation("com.github.afarber:OpenMapView:main-SNAPSHOT")

// Specific commit
implementation("com.github.afarber:OpenMapView:abc1234")

// Feature branch
implementation("com.github.afarber:OpenMapView:feature-branch-SNAPSHOT")
```

--------------------------------

### Build and Install Debug App via Gradle

Source: https://github.com/afarber/openmapview/blob/main/examples/Example01Pan/README.md

Builds, installs, and launches the debug version of the Example01Pan app using Gradle. Requires the Android SDK and Gradle to be set up.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example01Pan:installDebug

# Launch the app
# adb shell am start -n de.afarber.openmapview.example01pan/.MainActivity
```

--------------------------------

### Android App Build and Install for Example02Zoom

Source: https://github.com/afarber/openmapview/blob/main/examples/Example02Zoom/README.md

This snippet demonstrates how to build, install, and launch the Example02Zoom application from the command line using Gradle and ADB. It requires the project to be built from the root directory and assumes the necessary Android SDK and tools are configured.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example02Zoom:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example02zoom/.MainActivity
```

--------------------------------

### Build and Install Debug App (Bash)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example12Toolbar/README.md

Builds, installs, and launches the debug version of the `Example12Toolbar` application from the command line using Gradle. This is an alternative to running the app directly from Android Studio.

```bash
# From project root - build, install, and launch
./gradlew :examples:Example12Toolbar:installDebug

# Launch the app
adb shell am start -n de.afarber.openmapview.example12toolbar/.MainActivity
```

--------------------------------

### Build Debug Examples with Gradle

Source: https://github.com/afarber/openmapview/blob/main/docs/CONTRIBUTING.md

Builds all example applications with a debug configuration. This ensures that the library integrates correctly with sample applications.

```bash
# Build all examples
./gradlew assembleDebug
```

--------------------------------

### Standard Kotlin Unit Test Example

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

A basic example of a standard Kotlin unit test that does not rely on Android framework dependencies. It tests a utility function `MyUtil.calculate` and uses JUnit assertions to verify the expected output. This demonstrates a pure Kotlin test case.

```kotlin
import org.junit.Test
import org.junit.Assert.assertEquals

// Assuming MyUtil and calculate are defined elsewhere

class MyUtilTest {
    @Test
    fun testCalculation() {
        val result = MyUtil.calculate(5, 10)
        assertEquals(15, result)
    }
}
```

--------------------------------

### Setup Pre-commit Git Hooks

Source: https://github.com/afarber/openmapview/blob/main/docs/CONTRIBUTING.md

Installs Git hooks to automate code formatting and copyright header checks before each commit. This script helps prevent CI failures by ensuring code quality locally. The hooks check formatting and copyright compliance.

```bash
./scripts/setup-git-hooks.sh
```

--------------------------------

### Kotlin Copyright Header Example

Source: https://github.com/afarber/openmapview/blob/main/docs/CONTRIBUTING.md

Example of the required MIT license copyright header for all Kotlin source files. This header must be present at the top of every .kt file to ensure legal compliance and clarity. The spotlessApply command can automatically add this header.

```kotlin
/*
 * Copyright (c) 2025 Alexander Farber
 * SPDX-License-Identifier: MIT
 * 
 * This file is part of the OpenMapView project (https://github.com/afarber/OpenMapView)
 */
```

--------------------------------

### OpenMapView Initialization and Lifecycle Integration

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Demonstrates how to integrate OpenMapView into an Activity or Fragment using the DefaultLifecycleObserver pattern. This eliminates the need for manual lifecycle forwarding, simplifying setup.

```kotlin
lifecycle.addObserver(mapView)
```

--------------------------------

### Android Unit Test with Robolectric

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

An example of an Android unit test using Robolectric. The `@RunWith(RobolectricTestRunner::class)` annotation enables the use of Android framework classes within the test. This test specifically verifies the creation and properties of an Android `Bitmap` object.

```kotlin
import org.junit.Test
import org.junit.runner.RunWith
import org.robolectric.RobolectricTestRunner
import android.graphics.Bitmap
import org.junit.Assert.assertNotNull
import org.junit.Assert.assertEquals

@RunWith(RobolectricTestRunner::class)
class MyBitmapTest {
    @Test
    fun testBitmapCreation() {
        val bitmap = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888)
        assertNotNull(bitmap)
        assertEquals(100, bitmap.width)
    }
}
```

--------------------------------

### Complete Polyline Migration Example

Source: https://github.com/afarber/openmapview/blob/main/docs/REPLACING_GOOGLE_MAPS.md

This example provides a comprehensive migration of a polyline from Google Maps to OpenMapView, combining color, width, pattern, caps, joins, and clickability. It showcases the consolidated properties in OpenMapView.

```kotlin
import android.graphics.Color
import com.google.android.gms.maps.model.*

val polyline = googleMap.addPolyline(
    PolylineOptions()
        .add(LatLng(51.5, 0.0))
        .add(LatLng(51.6, 0.1))
        .color(Color.BLUE)
        .width(8f)
        .pattern(listOf(Dash(20f), Gap(10f)))
        .startCap(RoundCap())
        .endCap(RoundCap())
        .jointType(JointType.BEVEL)
        .clickable(true)
)
```

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.PathEffect
import androidx.compose.ui.graphics.StrokeCap
import androidx.compose.ui.graphics.StrokeJoin

val polyline = mapView.addPolyline(
    Polyline(
        points = listOf(LatLng(51.5, 0.0), LatLng(51.6, 0.1)),
        strokeColor = Color.Blue,
        strokeWidth = 8f,
        strokePattern = PathEffect.dashPathEffect(floatArrayOf(20f, 10f), 0f),
        strokeCap = StrokeCap.Round,
        strokeJoin = StrokeJoin.Bevel,
        clickable = true
    )
)
```

--------------------------------

### Apply Comprehensive Styling to OpenMapView Polyline

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Provides a complete example of styling a `Polyline` in OpenMapView, including custom stroke color, width, dashed pattern, rounded cap, and bevel join. This example showcases the flexibility of Compose's graphics primitives for map feature visualization.

```kotlin
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.PathEffect
import androidx.compose.ui.graphics.StrokeCap
import androidx.compose.ui.graphics.StrokeJoin

val styledPolyline = Polyline(
    points = listOf(LatLng(51.5, 0.0), LatLng(51.6, 0.1)),
    strokeColor = Color(0xFF0066CC),  // Custom blue
    strokeWidth = 12f,
    strokePattern = PathEffect.dashPathEffect(floatArrayOf(20f, 10f), 0f),
    strokeCap = StrokeCap.Round,
    strokeJoin = StrokeJoin.Bevel
)
```

--------------------------------

### Production-Ready OpenMapView Setup in Jetpack Compose

Source: https://context7.com/afarber/openmapview/llms.txt

This snippet demonstrates a complete, production-ready setup for OpenMapView within a Jetpack Compose UI. It includes lifecycle management, initial camera position, map type, zoom constraints, UI settings customization, map padding, camera region constraints, and event listeners for map clicks and idle states. It also covers accessibility descriptions.

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.platform.LocalLifecycleOwner
import androidx.compose.ui.unit.dp
import androidx.compose.ui.viewinterop.AndroidView
import androidx.lifecycle.LifecycleOwner
import androidx.lifecycle.lifecycleScope
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.LatLngBounds
import com.google.maps.android.clustering.ClusterManager
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import android.util.Log
import java.time.Duration

// Assuming OpenMapView, MapType, Marker, database, LatLng, LatLngBounds are defined elsewhere
// and lifecycleScope, withContext, Dispatchers are imported from coroutines

@Composable
fun ProductionMapView() {
    val lifecycleOwner = LocalLifecycleOwner.current
    val context = LocalContext.current
    var mapView: OpenMapView? by remember { mutableStateOf(null) }

    DisposableEffect(Unit) {
        onDispose {
            // Automatic cleanup via lifecycle observer
            // No manual cleanup needed
        }
    }

    AndroidView(
        factory = { ctx ->
            OpenMapView(ctx).apply {
                // Lifecycle management
                lifecycleOwner.lifecycle.addObserver(this)

                // Initial camera position
                setCenter(LatLng(51.4661, 7.2491))
                setZoom(14.0)

                // Map type
                setMapType(MapType.STANDARD)

                // Zoom constraints
                setMinZoomPreference(5.0f)
                setMaxZoomPreference(18.0f)

                // UI settings
                val uiSettings = getUiSettings()
                uiSettings.setZoomControlsEnabled(true)
                uiSettings.setZoomGesturesEnabled(true)
                uiSettings.setScrollGesturesEnabled(true)
                uiSettings.setScrollGesturesEnabledDuringRotateOrZoom(false)
                // uiSettings.infoWindowAutoDismiss = 8.seconds // Assuming 8.seconds is a valid Duration or similar

                // Map padding for UI elements
                setMapPadding(0, 200, 0, 100)  // Top toolbar, bottom nav

                // Constrain camera to region
                setLatLngBoundsForCameraTarget(
                    LatLngBounds(
                        southwest = LatLng(51.3, 7.0),
                        northeast = LatLng(51.6, 7.5)
                    )
                )

                // Event listeners
                setOnMapClickListener { latLng ->
                    Log.d("Map", "Map clicked: $latLng")
                }

                setOnCameraMoveStartedListener { reason ->
                    // Track camera movements for analytics
                }

                setOnCameraIdleListener {
                    // Load markers for visible region
                    loadMarkersForVisibleArea()
                }

                // Accessibility
                contentDescription = "Interactive map showing points of interest"

                mapView = this
            }
        },
        update = {
            // Update map when compose state changes
            // view.setCenter(...), view.addMarker(...), etc.
        },
        modifier = Modifier.fillMaxSize()
    )
}

```

--------------------------------

### Run Unit Tests for Specific Build Variant

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Allows running unit tests targeted at a particular build variant (e.g., 'debug' or 'release'). This is useful for testing code specific to certain build configurations.

```bash
./gradlew :openmapview:testDebugUnitTest
./gradlew :openmapview:testReleaseUnitTest
```

--------------------------------

### Tagging and Pushing a Version

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This command sequence is used to create a new version tag locally and push it to the remote repository, which triggers the automated publishing process for OpenMapView.

```bash
git tag v0.3.0
git push origin v0.3.0
```

--------------------------------

### Overlay Data Structure and Z-Index Examples in Kotlin

Source: https://github.com/afarber/openmapview/blob/main/examples/Example09Overlays/README.md

Defines the data structure for a TileOverlay, including properties like transparency, zIndex, and visibility. Provides examples of how to set the zIndex to control the drawing order of overlays relative to base map tiles.

```kotlin
data class TileOverlay(
    val tileProvider: TileProvider,     // Source for tile data
    val transparency: Float = 0f,       // 0.0 (opaque) to 1.0 (transparent)
    val zIndex: Float = 0f,             // Draw order (higher = on top)
    val visible: Boolean = true,        // Show/hide overlay
    val fadeIn: Boolean = false,        // Fade-in animation (future)
    val tag: Any? = null               // User data
)

// Below base tiles
TileOverlay(provider, zIndex = -1.0f)  // Custom base map

// Above base tiles (typical)
TileOverlay(provider, zIndex = 1.0f)   // OpenSeaMap
TileOverlay(provider, zIndex = 2.0f)   // OpenRailwayMap (on top)
```

--------------------------------

### Initialize OpenMapView with XML Layouts

Source: https://github.com/afarber/openmapview/blob/main/README.md

Shows how to load and interact with the OpenMapView component in an Android Activity using XML layouts. This example demonstrates finding the map view by its ID and setting its initial zoom level and center coordinates.

```kotlin
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.example.openmapview.OpenMapView
import com.google.android.gms.maps.model.LatLng

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))
    }
}
```

--------------------------------

### Run a Specific Unit Test Class

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Filters and runs unit tests belonging to a specific class, identified by a pattern. This is helpful for rapid testing of individual components or when debugging a particular test file.

```bash
./gradlew :openmapview:testDebugUnitTest --tests "*ProjectionTest*"
```

--------------------------------

### Robolectric: Testing Android Bitmap Creation

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Illustrates how Robolectric enables testing of Android framework classes like `Bitmap` within a standard JVM environment. Without Robolectric, `Bitmap.createBitmap` would return null.

```kotlin
@RunWith(RobolectricTestRunner::class)
class MyTest {
    @Test
    fun testBitmap() {
        val bitmap = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888)
        assertNotNull(bitmap)  // Works!
        assertEquals(100, bitmap.width)
    }
}
```

--------------------------------

### Configure JitPack Repository in settings.gradle.kts

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This snippet adds the JitPack repository to your project's `settings.gradle.kts` file, enabling it to fetch dependencies from JitPack. Ensure this is placed within the `dependencyResolutionManagement` block.

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}
```

--------------------------------

### Generate JaCoCo Test Coverage Report with Gradle

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Command to execute unit tests and generate a JaCoCo test coverage report for the OpenMapView Gradle module. This report is essential for analyzing code coverage metrics.

```bash
./gradlew :openmapview:testDebugUnitTest jacocoTestReport
```

--------------------------------

### Set Default Map Type in OpenMapView

Source: https://github.com/afarber/openmapview/blob/main/docs/MAP_TYPES.md

Demonstrates how to initialize OpenMapView and set the map to its default 'STANDARD' type. This is the basic setup for general-purpose mapping.

```kotlin
val mapView = OpenMapView(context)
mapView.setMapType(MapType.STANDARD)  // Default map
```

--------------------------------

### Run All Unit Tests with Detailed Output

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Executes all unit tests and continues running even if some tests fail, providing a comprehensive report. The `--continue` flag is useful for identifying all failing tests in a single run.

```bash
./gradlew :openmapview:test --continue
```

--------------------------------

### Install OpenMapView via Maven Central

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This code snippet shows how to include the OpenMapView library as a dependency in an Android project using Gradle. No special repository configuration is needed if using Maven Central, as it's a standard repository.

```kotlin
dependencies {
    implementation("de.afarber:openmapview:0.1.0")
}
```

--------------------------------

### Handle Marker Drag Events in Kotlin

Source: https://github.com/afarber/openmapview/blob/main/examples/Example07DraggableMarkers/README.md

Implements the OnMarkerDragListener interface to respond to marker drag events. Callbacks are provided for the start, continuous movement, and end of a drag operation, typically used for user feedback like Toasts.

```kotlin
mapView.setOnMarkerDragListener(object : OnMarkerDragListener {
    override fun onMarkerDragStart(marker: Marker) {
        Toast.makeText(context, "Started dragging: ${marker.title}", Toast.LENGTH_SHORT).show()
    }

    override fun onMarkerDrag(marker: Marker) {
        // Called continuously during drag - useful for real-time updates
    }

    override fun onMarkerDragEnd(marker: Marker) {
        val coordString = "%.4f, %.4f".format(
            marker.position.latitude,
            marker.position.longitude
        )
        Toast.makeText(context, "${marker.title} at: $coordString", Toast.LENGTH_SHORT).show()
    }
})
```

--------------------------------

### Test Bitmap Operations with Robolectric

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Tests the `TileCache` class's `put` and `get` methods using Robolectric for Android framework compatibility. This test creates a mock `Bitmap` and verifies that it can be stored and retrieved correctly from the cache. It ensures the cache mechanism works as expected with Android `Bitmap` objects.

```kotlin
import org.junit.Test
import org.junit.runner.RunWith
import org.robolectric.RobolectricTestRunner
import android.graphics.Bitmap
import org.junit.Assert.assertNotNull
import org.junit.Assert.assertEquals

// Assuming TileCache, TileCoordinate are defined elsewhere

@RunWith(RobolectricTestRunner::class)
class TileCacheTest {
    @Test
    fun testPutAndGet() {
        val cache = TileCache()
        val tile = TileCoordinate(1, 2, 3)
        val bitmap = Bitmap.createBitmap(256, 256, Bitmap.Config.ARGB_8888)

        cache.put(tile, bitmap)
        val result = cache.get(tile)

        assertNotNull(result)
        assertEquals(bitmap, result)
    }
}
```

--------------------------------

### Run Gradle Tasks for Release Checklist

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This snippet demonstrates common Gradle tasks used during the release process. These include running tests, formatting code, building the project, and publishing artifacts locally. Ensure these commands are executed successfully before proceeding with a release.

```bash
./gradlew test
./gradlew spotlessApply
./gradlew build
./gradlew publishToMavenLocal
```

--------------------------------

### Utilize Predefined Tile Providers

Source: https://github.com/afarber/openmapview/blob/main/examples/Example09Overlays/README.md

Illustrates the usage of the `PredefinedTileProviders` factory to easily access common OpenStreetMap-based tile services. Examples include OpenSeaMap for nautical charts, OpenRailwayMap for railway data, Waymarked Trails for hiking routes, and OpenSnowMap for ski pistes.

```kotlin
// OpenSeaMap (nautical charts)
PredefinedTileProviders.openSeaMap()

// OpenRailwayMap (railway infrastructure)
PredefinedTileProviders.openRailwayMap()

// Waymarked Trails (hiking routes)
PredefinedTileProviders.waymarkedTrailsHiking()

// OpenSnowMap (ski pistes)
PredefinedTileProviders.openSnowMap()
```

--------------------------------

### Mock HTTP Requests with Ktor MockEngine

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Shows how to use `ktor-client-mock`'s `MockEngine` to test network-related code. This allows simulating HTTP responses for specific requests, enabling testing of data fetching and network error handling without making actual network calls. It's useful for testing components that interact with APIs.

```kotlin
import io.ktor.client.HttpClient
import io.ktor.client.engine.mock.MockEngine
import io.ktor.client.engine.mock.respond
import io.ktor.http.HttpHeaders
import io.ktor.http.HttpStatusCode
import io.ktor.utils.io.core.ByteReadChannel
import kotlinx.coroutines.test.runTest
import org.junit.Test

// Assuming createMockPngBytes() is a helper function

@Test
fun testDownloadTile_Success() = runTest {
    val mockBitmapBytes = createMockPngBytes()
    val mockEngine = MockEngine { request ->
        respond(
            content = ByteReadChannel(mockBitmapBytes),
            status = HttpStatusCode.OK,
            headers = mapOf(HttpHeaders.ContentType to listOf("image/png"))
        )
    }

    val client = HttpClient(mockEngine)
    // Further testing with the mocked client would go here
}
```

--------------------------------

### CI Integration for Unit Tests with GitHub Actions

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Illustrates GitHub Actions configuration for running unit tests and uploading test results. The workflow executes Gradle tasks to run tests and uses `actions/upload-artifact` to store test results as artifacts for 30 days. This ensures continuous testing on every push.

```yaml
- name: Run unit tests
  run: ./gradlew :openmapview:test --continue

- name: Upload test results
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: '**/build/test-results/test*UnitTest/*.xml'
```

--------------------------------

### Check for Installed Map Apps (Kotlin)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example12Toolbar/README.md

Provides a Kotlin code snippet to check if any map applications are installed on the device that can handle the geo: URI scheme. This is crucial for implementing the browser fallback logic.

```kotlin
val intent = Intent(Intent.ACTION_VIEW, Uri.parse("geo:0,0"))
val activities = packageManager.queryIntentActivities(intent, 0)
if (activities.isEmpty()) {
    // No map apps installed, use browser fallback
}
```

--------------------------------

### Initialize OpenMapView with Jetpack Compose

Source: https://github.com/afarber/openmapview/blob/main/README.md

Demonstrates how to integrate and initialize the OpenMapView component within a Jetpack Compose UI. It shows how to set the center, zoom level, and add markers using both Kotlin-style direct instantiation and the Google Maps API style builder pattern. Proper lifecycle management is crucial for cleanup.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.ui.platform.LocalLifecycleOwner
import androidx.compose.ui.viewinterop.AndroidView
import com.example.openmapview.OpenMapView
import com.example.openmapview.Marker
import com.example.openmapview.MarkerOptions
import com.google.android.gms.maps.model.LatLng

@Composable
fun MapViewScreen() {
    val lifecycleOwner = 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 - Kotlin style (direct instantiation)
                addMarker(Marker(
                    position = LatLng(51.4661, 7.2491),
                    title = "Bochum City Center"
                ))

                // Or Google Maps API style (builder pattern)
                addMarker(
                    MarkerOptions()
                        .position(LatLng(51.4700, 7.2550))
                        .title("North Location")
                        .draggable(true)
                )
            }
        },
        modifier = Modifier.fillMaxSize()
    )
}
```

--------------------------------

### Unit Test with MockK for Data Repository

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Demonstrates testing a ViewModel (`MyViewModel`) that depends on a `DataRepository`. MockK is used to create a mock instance of the repository, and `every` is used to define its behavior (returning a specific list of strings). This allows testing the ViewModel's logic in isolation.

```kotlin
import io.mockk.mockk
import io.mockk.every
import io.mockk.verify
import org.junit.Test

// Assuming DataRepository, MyViewModel, and mockRepo/viewModel are defined elsewhere

class MyViewModelTest {
    @Test
    fun testLoadData() {
        val mockRepo = mockk<DataRepository>()
        every { mockRepo.getData() } returns listOf("a", "b", "c")

        val viewModel = MyViewModel(mockRepo)
        viewModel.loadData()

        verify(exactly = 1) { mockRepo.getData() }
    }
}
```

--------------------------------

### Apply and Check Spotless Formatting

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

These commands utilize the Spotless Gradle plugin for code formatting. `spotlessApply` automatically formats the code according to the defined rules, while `spotlessCheck` verifies if the code adheres to the formatting standards without making changes.

```bash
./gradlew spotlessApply
./gradlew spotlessCheck
```

--------------------------------

### Bitmap Descriptor: Default Marker

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Creates a default marker BitmapDescriptor. This is the simplest way to get a marker icon, using the BitmapDescriptorFactory.

```java
BitmapDescriptorFactory.defaultMarker()
```

--------------------------------

### Adding Tile Overlays using Builder or Direct Instantiation in Kotlin

Source: https://github.com/afarber/openmapview/blob/main/examples/Example09Overlays/README.md

Demonstrates two methods for adding tile overlays to the map: using a builder pattern with TileOverlayOptions, and direct instantiation of the TileOverlay class.

```kotlin
// Builder pattern
val overlay = mapView.addTileOverlay(TileOverlayOptions()...)

// Direct instantiation
val overlay = mapView.addTileOverlay(TileOverlay(...))
```

--------------------------------

### Configure Map Center and Zoom - OpenMapView

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Methods for setting and getting the map's center coordinates and zoom level. These are direct methods on the OpenMapView object.

```Java
OpenMapView.setCenter(new LatLng(latitude, longitude));
OpenMapView.setZoom(zoomLevel);
double currentZoom = OpenMapView.getZoom();
```

--------------------------------

### Add Ground Overlay (Google Maps Style)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example10GroundOverlays/README.md

Demonstrates adding a ground overlay using a Google Maps compatible API style. This includes setting the image, position, dimensions, bearing, transparency, clickability, and z-index. This approach leverages existing Google Maps SDK patterns.

```kotlin
val groundOverlay = mapView.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptor.BitmapMarker(bitmap))
        .position(LatLng(51.465, 7.255), 1500f)
        .bearing(45f)
        .transparency(0f)
        .clickable(true)
        .zIndex(3f)
)
```

--------------------------------

### Configure Map Type - OpenMapView

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Methods for setting and getting the current map type. Supports several predefined map types like NORMAL, TERRAIN, and CYCLE.

```Java
OpenMapView.setMapType(GoogleMap.MAP_TYPE_TERRAIN);
int currentMapType = OpenMapView.getMapType();
```

--------------------------------

### Update Gradle Dependencies

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This command forces Gradle to ignore cached dependencies and re-download them from the repositories. Use this when experiencing issues related to outdated or corrupted dependencies.

```bash
./gradlew --refresh-dependencies
```

--------------------------------

### Create Draggable Marker in Kotlin

Source: https://github.com/afarber/openmapview/blob/main/examples/Example07DraggableMarkers/README.md

Enables dragging for a specific marker by setting the 'draggable' property to true during marker creation. The marker is then added to the map view.

```kotlin
val marker = Marker(
    position = LatLng(51.4661, 7.2491),
    title = "Marker 1",
    snippet = "Drag me!",
    draggable = true  // Enable dragging
)
mapView.addMarker(marker)
```

--------------------------------

### Check Code Formatting with Gradle

Source: https://github.com/afarber/openmapview/blob/main/docs/CONTRIBUTING.md

Verifies that the project's code adheres to the defined Spotless formatting rules. This is a crucial step in the CI pipeline.

```bash
# Check formatting
./gradlew spotlessCheck
```

--------------------------------

### Browser Fallback URL (Text)

Source: https://github.com/afarber/openmapview/blob/main/examples/Example12Toolbar/README.md

Provides the URL format for the browser fallback to OpenStreetMap.org. This URL is used when no compatible map applications are installed on the device.

```text
https://www.openstreetmap.org/?mlat=51.4661&mlon=7.2491#map=14/51.4661/7.2491
```

--------------------------------

### Set Standard OpenStreetMap Map Type

Source: https://github.com/afarber/openmapview/blob/main/docs/MAP_TYPES.md

Configures OpenMapView to use the 'STANDARD' map type, which is the default OpenStreetMap rendering style suitable for general-purpose mapping and navigation.

```kotlin
mapView.setMapType(MapType.STANDARD)
```

--------------------------------

### Add OpenMapView Dependency in settings.gradle.kts

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLISHING.md

This snippet demonstrates how to add the OpenMapView library as a project dependency in your `settings.gradle.kts` file using the JitPack coordinates. Replace `0.1.0` with the desired version.

```kotlin
dependencies {
    implementation("com.github.afarber:OpenMapView:0.1.0")
}
```

--------------------------------

### Marker Drag Listener

Source: https://github.com/afarber/openmapview/blob/main/docs/PUBLIC_API.md

Implements a listener for marker drag events. This listener provides callbacks for when a marker drag starts, during the drag, and when the drag ends. It uses object syntax for defining the listener implementation.

```kotlin
mapView.setOnMarkerDragListener(object : OnMarkerDragListener {
    override fun onMarkerDragStart(marker: Marker) { }
    override fun onMarkerDrag(marker: Marker) { }
    override fun onMarkerDragEnd(marker: Marker) { }
})
```

--------------------------------

### Mock Canvas Drawing with MockK

Source: https://github.com/afarber/openmapview/blob/main/docs/TESTING_UNIT.md

Demonstrates using MockK to mock Android `Canvas` objects for testing drawing operations. This allows verification that specific drawing methods were called on the canvas without performing actual rendering. `relaxed = true` is used to avoid the need to define behavior for all methods.

```kotlin
import io.mockk.mockk
import io.mockk.verify
import android.graphics.Canvas
import org.junit.Test

// Assuming controller is an instance of a class that uses Canvas

@Test
fun testDraw_ValidViewport() {
    val canvas = mockk<Canvas>(relaxed = true)
    controller.draw(canvas)
    verify(atLeast = 1) { canvas.drawRect(any(), any(), any(), any(), any()) }
}
```

--------------------------------

### Set CARTO Light Theme Map Type

Source: https://github.com/afarber/openmapview/blob/main/docs/MAP_TYPES.md

Applies the CARTO_LIGHT map type, a minimalist light-themed basemap designed for data visualization and applications where overlays need to stand out.

```kotlin
mapView.setMapType(MapType.CARTO_LIGHT)
```