Add directional edge glow when panning hits camera bounds (#10)

Author: afarber

openmapview/src/main/kotlin/de/afarber/openmapview/Edge.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025 Alexander Farber
+ * SPDX-License-Identifier: MIT
+ *
+ * This file is part of the OpenMapView project (https://github.com/afarber/OpenMapView)
+ */
+
+package de.afarber.openmapview
+
+/**
+ * Represents an edge of the map view for edge effect triggering.
+ *
+ * Used with [OpenMapView.triggerEdgeEffect] to specify which edges should display
+ * a visual glow effect when the camera reaches its bounds.
+ */
+enum class Edge {
+    /** Top edge of the map view (north direction) */
+    TOP,
+
+    /** Bottom edge of the map view (south direction) */
+    BOTTOM,
+
+    /** Left edge of the map view (west direction) */
+    LEFT,
+
+    /** Right edge of the map view (east direction) */
+    RIGHT,
+}

openmapview/src/main/kotlin/de/afarber/openmapview/MapController.kt

@@ -99,13 +99,49 @@ class MapController(
      * @param latLng The coordinate to clamp
      * @return The clamped coordinate
      */
-    private fun clampToTargetBounds(latLng: LatLng): LatLng {
-        val bounds = cameraTargetBounds ?: return latLng
+    private fun clampToTargetBounds(latLng: LatLng): LatLng = clampToTargetBoundsWithEdges(latLng).first
 
-        val clampedLat = latLng.latitude.coerceIn(bounds.southwest.latitude, bounds.northeast.latitude)
-        val clampedLng = latLng.longitude.coerceIn(bounds.southwest.longitude, bounds.northeast.longitude)
+    /**
+     * Clamps a LatLng coordinate to remain within the camera target bounds,
+     * and returns which edges were hit during clamping.
+     *
+     * If no bounds are set, returns the input unchanged with an empty edge set.
+     *
+     * @param latLng The coordinate to clamp
+     * @return A pair of the clamped coordinate and the set of edges that were hit
+     */
+    private fun clampToTargetBoundsWithEdges(latLng: LatLng): Pair<LatLng, Set<Edge>> {
+        val bounds = cameraTargetBounds ?: return Pair(latLng, emptySet())
+
+        val hitEdges = mutableSetOf<Edge>()
+
+        val clampedLat =
+            when {
+                latLng.latitude < bounds.southwest.latitude -> {
+                    hitEdges.add(Edge.BOTTOM)
+                    bounds.southwest.latitude
+                }
+                latLng.latitude > bounds.northeast.latitude -> {
+                    hitEdges.add(Edge.TOP)
+                    bounds.northeast.latitude
+                }
+                else -> latLng.latitude
+            }
+
+        val clampedLng =
+            when {
+                latLng.longitude < bounds.southwest.longitude -> {
+                    hitEdges.add(Edge.LEFT)
+                    bounds.southwest.longitude
+                }
+                latLng.longitude > bounds.northeast.longitude -> {
+                    hitEdges.add(Edge.RIGHT)
+                    bounds.northeast.longitude
+                }
+                else -> latLng.longitude
+            }
 
-        return LatLng(clampedLat, clampedLng)
+        return Pair(LatLng(clampedLat, clampedLng), hitEdges)
     }
 
     private var viewWidth = 0
@@ -301,17 +337,38 @@ class MapController(
      * @param overzoomAmount The amount of overzoom attempted (positive for zoom in, negative for zoom out)
      */
     private fun triggerOverzoomEffect(overzoomAmount: Float) {
-        if (uiSettings?.isZoomEdgeEffectEnabled != true) return
+        if (uiSettings?.isEdgeEffectEnabled != true) return
         if (viewWidth == 0 || viewHeight == 0) return
 
         // Calculate glow strength based on overzoom magnitude
         val glowStrength = (kotlin.math.abs(overzoomAmount) * 2.0f).coerceIn(0.3f, 1.0f)
 
-        // Set glow on all edges
-        edgeGlowTop = glowStrength
-        edgeGlowBottom = glowStrength
-        edgeGlowLeft = glowStrength
-        edgeGlowRight = glowStrength
+        // Trigger edge effect on all edges
+        triggerEdgeEffect(setOf(Edge.TOP, Edge.BOTTOM, Edge.LEFT, Edge.RIGHT), glowStrength)
+    }
+
+    /**
+     * Triggers the edge glow effect on specified edges.
+     *
+     * This method can be called by app developers from button handlers or other UI controls
+     * to provide visual feedback when the camera cannot move further in a direction.
+     *
+     * @param edges The set of edges to trigger the effect on
+     * @param intensity The glow intensity from 0.0 (none) to 1.0 (full), default 0.8
+     */
+    fun triggerEdgeEffect(
+        edges: Set<Edge>,
+        intensity: Float = 0.8f,
+    ) {
+        if (uiSettings?.isEdgeEffectEnabled != true) return
+        if (viewWidth == 0 || viewHeight == 0) return
+
+        val clampedIntensity = intensity.coerceIn(0.0f, 1.0f)
+
+        if (Edge.TOP in edges) edgeGlowTop = clampedIntensity
+        if (Edge.BOTTOM in edges) edgeGlowBottom = clampedIntensity
+        if (Edge.LEFT in edges) edgeGlowLeft = clampedIntensity
+        if (Edge.RIGHT in edges) edgeGlowRight = clampedIntensity
     }
 
     /**
@@ -1052,6 +1109,8 @@ class MapController(
      * Updates the temporary pan offset during a drag gesture.
      *
      * The offset accumulates until committed via [commitPan].
+     * If camera target bounds are set and the pan would exceed them,
+     * triggers the edge effect on the appropriate edges.
      *
      * @param dx The horizontal movement in pixels
      * @param dy The vertical movement in pixels
@@ -1060,8 +1119,24 @@ class MapController(
         dx: Float,
         dy: Float,
     ) {
-        panOffsetX -= dx
-        panOffsetY -= dy
+        val newPanOffsetX = panOffsetX - dx
+        val newPanOffsetY = panOffsetY - dy
+
+        // Check if bounds are set and detect edge hits during panning
+        if (cameraTargetBounds != null) {
+            val (centerPixelX, centerPixelY) = ProjectionUtils.latLngToPixel(center, zoom.toInt())
+            val newCenterPixelX = (centerPixelX + newPanOffsetX).toInt()
+            val newCenterPixelY = (centerPixelY + newPanOffsetY).toInt()
+            val newCenter = ProjectionUtils.pixelToLatLng(newCenterPixelX, newCenterPixelY, zoom.toInt())
+
+            val (_, hitEdges) = clampToTargetBoundsWithEdges(newCenter)
+            if (hitEdges.isNotEmpty()) {
+                triggerEdgeEffect(hitEdges, 0.6f)
+            }
+        }
+
+        panOffsetX = newPanOffsetX
+        panOffsetY = newPanOffsetY
     }
 
     /**

openmapview/src/main/kotlin/de/afarber/openmapview/OpenMapView.kt

@@ -625,6 +625,34 @@ class OpenMapView
          */
         fun getUiSettings(): UiSettings = uiSettings
 
+        /**
+         * Triggers the edge glow effect on specified edges.
+         *
+         * Use this method to provide visual feedback when the camera cannot move further
+         * in a direction, such as when a button press would exceed the camera bounds.
+         *
+         * The edge effect respects the [UiSettings.isEdgeEffectEnabled] setting.
+         *
+         * Example:
+         * ```kotlin
+         * // Trigger effect on the right edge when a "move right" button is pressed at bounds
+         * mapView.triggerEdgeEffect(setOf(Edge.RIGHT))
+         *
+         * // Trigger effect on multiple edges with custom intensity
+         * mapView.triggerEdgeEffect(setOf(Edge.TOP, Edge.RIGHT), 0.5f)
+         * ```
+         *
+         * @param edges The set of edges to trigger the effect on
+         * @param intensity The glow intensity from 0.0 (none) to 1.0 (full), default 0.8
+         */
+        fun triggerEdgeEffect(
+            edges: Set<Edge>,
+            intensity: Float = 0.8f,
+        ) {
+            controller.triggerEdgeEffect(edges, intensity)
+            invalidate()
+        }
+
         /**
          * Sets padding on the map.
          *

openmapview/src/main/kotlin/de/afarber/openmapview/UiSettings.kt

@@ -32,12 +32,14 @@ class UiSettings {
     var isZoomControlsEnabled: Boolean = false
 
     /**
-     * Whether the zoom edge effect (visual glow when attempting to zoom beyond limits) is enabled.
-     * When enabled, a visual EdgeEffect glow appears on all four edges when pinch-zoom gestures
-     * attempt to exceed min/max zoom limits, similar to overscroll behavior.
+     * Whether the edge effect (visual glow at map boundaries) is enabled.
+     * When enabled, a visual EdgeEffect glow appears when:
+     * - Pinch-zoom gestures attempt to exceed min/max zoom limits (all edges glow)
+     * - Pan gestures attempt to exceed camera target bounds (directional glow on hit edges)
+     * Similar to Android's overscroll behavior.
      * Default is true.
      */
-    var isZoomEdgeEffectEnabled: Boolean = true
+    var isEdgeEffectEnabled: Boolean = true
 
     /**
      * Whether scroll gestures are enabled during rotate or zoom gestures.