Better function definition

Author: kmadsen

Diff for: extension-androidauto/CHANGELOG.md

@@ -8,7 +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`.
+* Add support for intercepting the `SurfaceCallback#onClick` when using `MapboxCarMap.prepareSurfaceCallback`. ([#1683](https://github.com/mapbox/mapbox-maps-android/pull/1683)])
 
 ## Bug fixes 🐞
 

Diff for: extension-androidauto/api/extension-androidauto.api

@@ -1,16 +1,3 @@
-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
@@ -26,10 +13,10 @@ public final class com/mapbox/maps/extension/androidauto/MapboxCarMap {
 	public final fun getEdgeInsets ()Lcom/mapbox/maps/EdgeInsets;
 	public final fun getMapInitOptions ()Lcom/mapbox/maps/MapInitOptions;
 	public final fun getVisibleArea ()Landroid/graphics/Rect;
+	public final fun prepareSurfaceCallback (Landroidx/car/app/CarContext;Lcom/mapbox/maps/MapInitOptions;)Landroidx/car/app/SurfaceCallback;
 	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
 }
 

Diff for: extension-androidauto/api/metalava.txt

@@ -1,10 +1,6 @@
 // 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();
   }
@@ -17,10 +13,10 @@ package com.mapbox.maps.extension.androidauto {
     method public com.mapbox.maps.EdgeInsets? getEdgeInsets();
     method public com.mapbox.maps.MapInitOptions getMapInitOptions();
     method public android.graphics.Rect? getVisibleArea();
+    method @com.mapbox.maps.MapboxExperimental public androidx.car.app.SurfaceCallback prepareSurfaceCallback(androidx.car.app.CarContext carContext, com.mapbox.maps.MapInitOptions mapInitOptions);
     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;

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

@@ -18,7 +18,7 @@ import java.util.concurrent.CopyOnWriteArraySet
  * Maintains the surface state for [MapboxCarMap].
  */
 @MapboxExperimental
-class CarMapSurfaceOwner @JvmOverloads constructor(
+internal class CarMapSurfaceOwner @JvmOverloads constructor(
   internal var gestureHandler: MapboxCarMapGestureHandler? = DefaultMapboxCarMapGestureHandler()
 ) : SurfaceCallback {
 

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

@@ -72,27 +72,24 @@ class MapboxCarMap {
     carContext: CarContext,
     mapInitOptions: MapInitOptions,
   ) = apply {
-    check(mapInitOptions.context is CarContext) {
-      "You must set up the MapboxCarMap MapInitOptions with a CarContext"
-    }
-    carMapSurfaceOwner.setup(carContext, mapInitOptions)
-    carContext.getCarService(AppManager::class.java).setSurfaceCallback(carMapSurfaceOwner)
+    val surfaceCallback = prepareSurfaceCallback(carContext, mapInitOptions)
+    carContext.getCarService(AppManager::class.java).setSurfaceCallback(surfaceCallback)
   }
 
   /**
    * 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.
+   * forward the calls to the returned [SurfaceCallback]. This makes it possible for you to adopt
+   * new api versions or intercept the calls and continue to use the [MapboxCarMap] as designed.
    *
-   * This is a temporary solution, while androidx.car.app:app:1.3.0 is rolling out
+   * This may be 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(
+  fun prepareSurfaceCallback(
     carContext: CarContext,
     mapInitOptions: MapInitOptions
-  ): CarMapSurfaceOwner {
+  ): SurfaceCallback {
     check(mapInitOptions.context is CarContext) {
       "You must set up the MapboxCarMap MapInitOptions with a CarContext"
     }

Diff for: extension-androidauto/src/test/java/com/mapbox/maps/extension/androidauto/MapboxCarMapTest.kt

@@ -76,6 +76,26 @@ class MapboxCarMapTest {
     assertTrue(surfaceCallbackSlot.isCaptured)
   }
 
+  @Test
+  fun `setup will call setSurfaceCallback`() {
+    MapboxCarMap().setup(carContext, mapInitOptions)
+
+    val appManager = carContext.getCarService(AppManager::class.java)
+    verify(exactly = 1) {
+      appManager.setSurfaceCallback(any())
+    }
+  }
+
+  @Test
+  fun `prepareSurfaceCallback does not call setSurfaceCallback`() {
+    MapboxCarMap().prepareSurfaceCallback(carContext, mapInitOptions)
+
+    val appManager = carContext.getCarService(AppManager::class.java)
+    verify(exactly = 0) {
+      appManager.setSurfaceCallback(any())
+    }
+  }
+
   @Test
   fun `carMapSurface is valid after onSurfaceAvailable`() {
     val mapboxCarMap = MapboxCarMap().setup(carContext, mapInitOptions)