Allow for downstream upgrades

Author: kmadsen

android-auto-app/src/main/java/com/mapbox/maps/testapp/auto/testing/CarJavaInterfaceChecker.java

@@ -14,6 +14,7 @@
 import com.mapbox.maps.MapboxExperimental;
 import com.mapbox.maps.ResourceOptions;
 import com.mapbox.maps.ScreenCoordinate;
+import com.mapbox.maps.extension.androidauto.CarMapSurfaceOwner;
 import com.mapbox.maps.extension.androidauto.MapboxCarMap;
 import com.mapbox.maps.extension.androidauto.DefaultMapboxCarMapGestureHandler;
 import com.mapbox.maps.extension.androidauto.MapboxCarMapEx;
@@ -24,8 +25,13 @@
 @MapboxExperimental
 class CarJavaInterfaceChecker {
 
-  void constructors(MapInitOptions mapInitOptions) {
-    MapboxCarMap mapboxCarMap = new MapboxCarMap();
+  void constructorMapboxCarMap(MapInitOptions mapInitOptions) {
+    new MapboxCarMap();
+  }
+
+  void constructorsCarMapSurfaceOwner(MapboxCarMapGestureHandler gestures) {
+    new CarMapSurfaceOwner();
+    new CarMapSurfaceOwner(gestures);
   }
 
   void getters(MapboxCarMap mapboxCarMap) {

extension-androidauto/CHANGELOG.md

@@ -8,6 +8,7 @@ Mapbox welcomes participation and contributions from everyone.
 * Add `MapboxCarMapSessionInstaller` and `MapboxCarMapScreenInstaller` for simpler setup. ([#1603](https://github.com/mapbox/mapbox-maps-android/pull/1603))
 * Add `Session.mapboxMapInstaller` and `Screen.mapboxMapInstaller` extension functions to create the installers. ([#1603](https://github.com/mapbox/mapbox-maps-android/pull/1603))
 * Change `MapboxCarMapGestureHandler` to an java interface so default methods can be added without breaking java backwards compatibility. ([#1670](https://github.com/mapbox/mapbox-maps-android/pull/1670))
+* Add support for intercepting the `SurfaceCallback#onClick` with an experimental method `MapboxCarMap.setupWithCustomCallback`.
 
 ## Bug fixes 🐞
 

extension-androidauto/api/extension-androidauto.api

@@ -1,3 +1,16 @@
+public final class com/mapbox/maps/extension/androidauto/CarMapSurfaceOwner : androidx/car/app/SurfaceCallback {
+	public fun <init> ()V
+	public fun <init> (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler;)V
+	public synthetic fun <init> (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun onFling (FF)V
+	public fun onScale (FFF)V
+	public fun onScroll (FF)V
+	public fun onStableAreaChanged (Landroid/graphics/Rect;)V
+	public fun onSurfaceAvailable (Landroidx/car/app/SurfaceContainer;)V
+	public fun onSurfaceDestroyed (Landroidx/car/app/SurfaceContainer;)V
+	public fun onVisibleAreaChanged (Landroid/graphics/Rect;)V
+}
+
 public class com/mapbox/maps/extension/androidauto/DefaultMapboxCarMapGestureHandler : com/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler {
 	public fun <init> ()V
 	public fun onFling (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;FF)V
@@ -16,6 +29,7 @@ public final class com/mapbox/maps/extension/androidauto/MapboxCarMap {
 	public final fun registerObserver (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;)Lcom/mapbox/maps/extension/androidauto/MapboxCarMap;
 	public final fun setGestureHandler (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler;)V
 	public final fun setup (Landroidx/car/app/CarContext;Lcom/mapbox/maps/MapInitOptions;)Lcom/mapbox/maps/extension/androidauto/MapboxCarMap;
+	public final fun setupWithCustomCallback (Landroidx/car/app/CarContext;Lcom/mapbox/maps/MapInitOptions;)Lcom/mapbox/maps/extension/androidauto/CarMapSurfaceOwner;
 	public final fun unregisterObserver (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;)V
 }
 

extension-androidauto/api/metalava.txt

@@ -1,6 +1,10 @@
 // Signature format: 3.0
 package com.mapbox.maps.extension.androidauto {
 
+  @com.mapbox.maps.MapboxExperimental public final class CarMapSurfaceOwner implements androidx.car.app.SurfaceCallback {
+    ctor public CarMapSurfaceOwner(com.mapbox.maps.extension.androidauto.MapboxCarMapGestureHandler? gestureHandler = com.mapbox.maps.extension.androidauto.DefaultMapboxCarMapGestureHandler());
+  }
+
   @com.mapbox.maps.MapboxExperimental public class DefaultMapboxCarMapGestureHandler implements com.mapbox.maps.extension.androidauto.MapboxCarMapGestureHandler {
     ctor public DefaultMapboxCarMapGestureHandler();
   }
@@ -16,6 +20,7 @@ package com.mapbox.maps.extension.androidauto {
     method public com.mapbox.maps.extension.androidauto.MapboxCarMap registerObserver(com.mapbox.maps.extension.androidauto.MapboxCarMapObserver mapboxCarMapObserver);
     method public void setGestureHandler(com.mapbox.maps.extension.androidauto.MapboxCarMapGestureHandler? gestureHandler);
     method public com.mapbox.maps.extension.androidauto.MapboxCarMap setup(androidx.car.app.CarContext carContext, com.mapbox.maps.MapInitOptions mapInitOptions);
+    method @com.mapbox.maps.MapboxExperimental public com.mapbox.maps.extension.androidauto.CarMapSurfaceOwner setupWithCustomCallback(androidx.car.app.CarContext carContext, com.mapbox.maps.MapInitOptions mapInitOptions);
     method public void unregisterObserver(com.mapbox.maps.extension.androidauto.MapboxCarMapObserver mapboxCarMapObserver);
     property public final androidx.car.app.CarContext carContext;
     property public final com.mapbox.maps.extension.androidauto.MapboxCarMapSurface? carMapSurface;

extension-androidauto/src/main/java/com/mapbox/maps/extension/androidauto/CarMapSurfaceOwner.kt

@@ -6,6 +6,7 @@ import androidx.car.app.SurfaceCallback
 import androidx.car.app.SurfaceContainer
 import com.mapbox.maps.EdgeInsets
 import com.mapbox.maps.MapInitOptions
+import com.mapbox.maps.MapSurface
 import com.mapbox.maps.MapboxExperimental
 import com.mapbox.maps.ScreenCoordinate
 import com.mapbox.maps.logI
@@ -17,8 +18,8 @@ import java.util.concurrent.CopyOnWriteArraySet
  * Maintains the surface state for [MapboxCarMap].
  */
 @MapboxExperimental
-internal class CarMapSurfaceOwner(
-  var gestureHandler: MapboxCarMapGestureHandler? = DefaultMapboxCarMapGestureHandler()
+class CarMapSurfaceOwner @JvmOverloads constructor(
+  internal var gestureHandler: MapboxCarMapGestureHandler? = DefaultMapboxCarMapGestureHandler()
 ) : SurfaceCallback {
 
   internal var mapboxCarMapSurface: MapboxCarMapSurface? = null
@@ -35,14 +36,14 @@ internal class CarMapSurfaceOwner(
 
   private val carMapObservers = CopyOnWriteArraySet<MapboxCarMapObserver>()
 
-  fun setup(carContext: CarContext, mapInitOptions: MapInitOptions) = apply {
+  internal fun setup(carContext: CarContext, mapInitOptions: MapInitOptions) = apply {
     this.carContext = carContext
     this.mapInitOptions = mapInitOptions
   }
 
-  fun isSetup(): Boolean = this::carContext.isInitialized && this::mapInitOptions.isInitialized
+  internal fun isSetup(): Boolean = this::carContext.isInitialized && this::mapInitOptions.isInitialized
 
-  fun registerObserver(mapboxCarMapObserver: MapboxCarMapObserver) {
+  internal fun registerObserver(mapboxCarMapObserver: MapboxCarMapObserver) {
     carMapObservers.add(mapboxCarMapObserver)
     logI(TAG, "registerObserver + 1 = ${carMapObservers.size}")
 
@@ -55,17 +56,23 @@ internal class CarMapSurfaceOwner(
     }
   }
 
-  fun unregisterObserver(mapboxCarMapObserver: MapboxCarMapObserver) {
+  internal fun unregisterObserver(mapboxCarMapObserver: MapboxCarMapObserver) {
     carMapObservers.remove(mapboxCarMapObserver)
     mapboxCarMapSurface?.let { mapboxCarMapObserver.onDetached(it) }
     logI(TAG, "unregisterObserver - 1 = ${carMapObservers.size}")
   }
 
-  fun clearObservers() {
+  internal fun clearObservers() {
     this.mapboxCarMapSurface?.let { surface -> carMapObservers.forEach { it.onDetached(surface) } }
     carMapObservers.clear()
   }
 
+  /**
+   * Prepares the [MapSurface] and notifies any registered observers that the map has been attached
+   * with [MapboxCarMapObserver.onAttached].
+   *
+   * @see SurfaceCallback.onSurfaceAvailable
+   */
   override fun onSurfaceAvailable(surfaceContainer: SurfaceContainer) {
     logI(TAG, "onSurfaceAvailable $surfaceContainer")
     surfaceContainer.surface?.let { surface ->
@@ -94,6 +101,12 @@ internal class CarMapSurfaceOwner(
     }
   }
 
+  /**
+   * Destroys the resources used by [MapSurface] and notifies any registered observers that the map
+   * has been detached with [MapboxCarMapObserver.onDetached].
+   *
+   * @see SurfaceCallback.onSurfaceDestroyed
+   */
   override fun onSurfaceDestroyed(surfaceContainer: SurfaceContainer) {
     logI(TAG, "onSurfaceDestroyed")
     val detachSurface = this.mapboxCarMapSurface
@@ -104,6 +117,12 @@ internal class CarMapSurfaceOwner(
     detachSurface?.let { carMapObservers.forEach { it.onDetached(detachSurface) } }
   }
 
+  /**
+   * Notifies any registered observers that the visible area has changed with
+   * [MapboxCarMapObserver.onVisibleAreaChanged].
+   *
+   * @see SurfaceCallback.onVisibleAreaChanged
+   */
   override fun onVisibleAreaChanged(visibleArea: Rect) {
     logI(TAG, "onVisibleAreaChanged visibleArea:$visibleArea")
     this.visibleArea = visibleArea
@@ -121,22 +140,40 @@ internal class CarMapSurfaceOwner(
     }
   }
 
+  /**
+   * @see SurfaceCallback.onStableAreaChanged
+   */
   override fun onStableAreaChanged(stableArea: Rect) {
     // Have not found a need for this.
   }
 
+  /**
+   * Forwards the gesture to the [MapboxCarMapGestureHandler.onScroll].
+   *
+   * @see SurfaceCallback.onScroll
+   */
   override fun onScroll(distanceX: Float, distanceY: Float) {
     logI(TAG, "onScroll $distanceX, $distanceY")
     val carMapSurface = mapboxCarMapSurface ?: return
     gestureHandler?.onScroll(carMapSurface, visibleCenter, distanceX, distanceY)
   }
 
+  /**
+   * Forwards the gesture to the [MapboxCarMapGestureHandler.onFling].
+   *
+   * @see SurfaceCallback.onFling
+   */
   override fun onFling(velocityX: Float, velocityY: Float) {
     logI(TAG, "onFling $velocityX, $velocityY")
     val carMapSurface = mapboxCarMapSurface ?: return
     gestureHandler?.onFling(carMapSurface, velocityX, velocityY)
   }
 
+  /**
+   * Forwards the gesture to the [MapboxCarMapGestureHandler.onScale].
+   *
+   * @see SurfaceCallback.onScale
+   */
   override fun onScale(focusX: Float, focusY: Float, scaleFactor: Float) {
     logI(TAG, "onScroll $focusX, $focusY, $scaleFactor")
     val carMapSurface = mapboxCarMapSurface ?: return

extension-androidauto/src/main/java/com/mapbox/maps/extension/androidauto/MapboxCarMap.kt

@@ -4,6 +4,7 @@ import android.graphics.Rect
 import androidx.car.app.AppManager
 import androidx.car.app.CarContext
 import androidx.car.app.Session
+import androidx.car.app.SurfaceCallback
 import androidx.lifecycle.Lifecycle
 import com.mapbox.maps.EdgeInsets
 import com.mapbox.maps.MapInitOptions
@@ -72,12 +73,33 @@ class MapboxCarMap {
     mapInitOptions: MapInitOptions,
   ) = apply {
     check(mapInitOptions.context is CarContext) {
-      "You must setup the MapboxCarMap MapInitOptions with a CarContext"
+      "You must set up the MapboxCarMap MapInitOptions with a CarContext"
     }
     carMapSurfaceOwner.setup(carContext, mapInitOptions)
     carContext.getCarService(AppManager::class.java).setSurfaceCallback(carMapSurfaceOwner)
   }
 
+  /**
+   * Instead of using [setup], this function allows you to create your own [SurfaceCallback] and
+   * forward the calls to the [CarMapSurfaceOwner]. This makes it possible for you to adopt new
+   * api versions and continue to use the [MapboxCarMap] as designed.
+   *
+   * This is a temporary solution, while androidx.car.app:app:1.3.0 is rolling out
+   * [SurfaceCallback.onClick]. If there is no use for this function in the future, it will be
+   * removed.
+   */
+  @MapboxExperimental
+  fun setupWithCustomCallback(
+    carContext: CarContext,
+    mapInitOptions: MapInitOptions
+  ): CarMapSurfaceOwner {
+    check(mapInitOptions.context is CarContext) {
+      "You must set up the MapboxCarMap MapInitOptions with a CarContext"
+    }
+    carMapSurfaceOwner.setup(carContext, mapInitOptions)
+    return carMapSurfaceOwner
+  }
+
   /**
    * Returns the current [MapboxCarMapSurface]. It is recommended to use [registerObserver] and
    * [MapboxCarMapObserver] to attach and detach your customizations.