Skip to content

Commit 8d9aace

Browse files
kmadsenkmadsen
authored
[Android Auto] Add stable area changed callback (#1648)
* Add stable area changed callback * Update javadocs * Update tests and fix an issue * Update api * java example
1 parent 4932cc5 commit 8d9aace

File tree

10 files changed

+203
-86
lines changed

10 files changed

+203
-86
lines changed

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

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,9 @@ void constructors(MapInitOptions mapInitOptions) {
3131
void getters(MapboxCarMap mapboxCarMap) {
3232
CarContext carContext = mapboxCarMap.getCarContext();
3333
Rect visibleArea = mapboxCarMap.getVisibleArea();
34-
EdgeInsets edgeInsets = mapboxCarMap.getEdgeInsets();
34+
EdgeInsets edgeInsets = mapboxCarMap.getVisibleEdgeInsets();
35+
Rect stableArea = mapboxCarMap.getStableArea();
36+
EdgeInsets stableEdgeInsets = mapboxCarMap.getStableEdgeInsets();
3537
MapboxCarMapSurface mapboxCarMapSurface = mapboxCarMap.getCarMapSurface();
3638
}
3739

@@ -49,6 +51,11 @@ public void onVisibleAreaChanged(@NonNull Rect visibleArea, @NonNull EdgeInsets
4951

5052
}
5153

54+
@Override
55+
public void onStableAreaChanged(@NonNull Rect stableArea, @NonNull EdgeInsets edgeInsets) {
56+
57+
}
58+
5259
@Override
5360
public void onDetached(@NonNull MapboxCarMapSurface mapboxCarMapSurface) {
5461

@@ -62,9 +69,12 @@ public void onAttached(@NonNull MapboxCarMapSurface mapboxCarMapSurface) {
6269
}
6370

6471
private void observers(MapboxCarMap mapboxCarMap) {
72+
MapboxCarMapObserver emptyObserver = new MapboxCarMapObserver() { };
6573
MapboxCarMapObserver observer = createObserver();
74+
mapboxCarMap.registerObserver(emptyObserver);
6675
mapboxCarMap.registerObserver(observer);
6776
mapboxCarMap.unregisterObserver(observer);
77+
mapboxCarMap.unregisterObserver(emptyObserver);
6878
mapboxCarMap.clearObservers();
6979
}
7080

‎extension-androidauto/CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@ Mapbox welcomes participation and contributions from everyone.
88
* Add `MapboxCarMapSessionInstaller` and `MapboxCarMapScreenInstaller` for simpler setup. ([#1603](https://github.com/mapbox/mapbox-maps-android/pull/1603))
99
* Add `Session.mapboxMapInstaller` and `Screen.mapboxMapInstaller` extension functions to create the installers. ([#1603](https://github.com/mapbox/mapbox-maps-android/pull/1603))
1010
* 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))
11+
* Change `MapboxCarMapObserver` to an java interface so default methods can be added without breaking java backwards compatibility. ([#1670](https://github.com/mapbox/mapbox-maps-android/pull/1648))
12+
* Change `MapboxCarMap#getEdgeInsets()` to `mapboxCarMap.getVisibleEdgeInsets()` with the addition of `mapboxCarMap.getStableEdgeInsets()`. ([#1670](https://github.com/mapbox/mapbox-maps-android/pull/1648))
13+
* Add `MapboxCarMapObserver#onStableAreaChanged` to support all the available functions from the SurfaceCallback. ([#1670](https://github.com/mapbox/mapbox-maps-android/pull/1648))
1114

1215
## Bug fixes 🐞
1316

‎extension-androidauto/api/extension-androidauto.api

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,11 @@ public final class com/mapbox/maps/extension/androidauto/MapboxCarMap {
1010
public final fun clearObservers ()V
1111
public final fun getCarContext ()Landroidx/car/app/CarContext;
1212
public final fun getCarMapSurface ()Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;
13-
public final fun getEdgeInsets ()Lcom/mapbox/maps/EdgeInsets;
1413
public final fun getMapInitOptions ()Lcom/mapbox/maps/MapInitOptions;
14+
public final fun getStableArea ()Landroid/graphics/Rect;
15+
public final fun getStableEdgeInsets ()Lcom/mapbox/maps/EdgeInsets;
1516
public final fun getVisibleArea ()Landroid/graphics/Rect;
17+
public final fun getVisibleEdgeInsets ()Lcom/mapbox/maps/EdgeInsets;
1618
public final fun registerObserver (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;)Lcom/mapbox/maps/extension/androidauto/MapboxCarMap;
1719
public final fun setGestureHandler (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler;)V
1820
public final fun setup (Landroidx/car/app/CarContext;Lcom/mapbox/maps/MapInitOptions;)Lcom/mapbox/maps/extension/androidauto/MapboxCarMap;
@@ -35,15 +37,10 @@ public abstract interface class com/mapbox/maps/extension/androidauto/MapboxCarM
3537
}
3638

3739
public abstract interface class com/mapbox/maps/extension/androidauto/MapboxCarMapObserver {
38-
public abstract fun onAttached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
39-
public abstract fun onDetached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
40-
public abstract fun onVisibleAreaChanged (Landroid/graphics/Rect;Lcom/mapbox/maps/EdgeInsets;)V
41-
}
42-
43-
public final class com/mapbox/maps/extension/androidauto/MapboxCarMapObserver$DefaultImpls {
44-
public static fun onAttached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
45-
public static fun onDetached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
46-
public static fun onVisibleAreaChanged (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapObserver;Landroid/graphics/Rect;Lcom/mapbox/maps/EdgeInsets;)V
40+
public fun onAttached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
41+
public fun onDetached (Lcom/mapbox/maps/extension/androidauto/MapboxCarMapSurface;)V
42+
public fun onStableAreaChanged (Landroid/graphics/Rect;Lcom/mapbox/maps/EdgeInsets;)V
43+
public fun onVisibleAreaChanged (Landroid/graphics/Rect;Lcom/mapbox/maps/EdgeInsets;)V
4744
}
4845

4946
public final class com/mapbox/maps/extension/androidauto/MapboxCarMapScreenInstaller {

‎extension-androidauto/api/metalava.txt

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,22 @@ package com.mapbox.maps.extension.androidauto {
1010
method public void clearObservers();
1111
method public androidx.car.app.CarContext getCarContext();
1212
method public com.mapbox.maps.extension.androidauto.MapboxCarMapSurface? getCarMapSurface();
13-
method public com.mapbox.maps.EdgeInsets? getEdgeInsets();
1413
method public com.mapbox.maps.MapInitOptions getMapInitOptions();
14+
method public android.graphics.Rect? getStableArea();
15+
method public com.mapbox.maps.EdgeInsets? getStableEdgeInsets();
1516
method public android.graphics.Rect? getVisibleArea();
17+
method public com.mapbox.maps.EdgeInsets? getVisibleEdgeInsets();
1618
method public com.mapbox.maps.extension.androidauto.MapboxCarMap registerObserver(com.mapbox.maps.extension.androidauto.MapboxCarMapObserver mapboxCarMapObserver);
1719
method public void setGestureHandler(com.mapbox.maps.extension.androidauto.MapboxCarMapGestureHandler? gestureHandler);
1820
method public com.mapbox.maps.extension.androidauto.MapboxCarMap setup(androidx.car.app.CarContext carContext, com.mapbox.maps.MapInitOptions mapInitOptions);
1921
method public void unregisterObserver(com.mapbox.maps.extension.androidauto.MapboxCarMapObserver mapboxCarMapObserver);
2022
property public final androidx.car.app.CarContext carContext;
2123
property public final com.mapbox.maps.extension.androidauto.MapboxCarMapSurface? carMapSurface;
22-
property public final com.mapbox.maps.EdgeInsets? edgeInsets;
2324
property public final com.mapbox.maps.MapInitOptions mapInitOptions;
25+
property public final android.graphics.Rect? stableArea;
26+
property public final com.mapbox.maps.EdgeInsets? stableEdgeInsets;
2427
property public final android.graphics.Rect? visibleArea;
28+
property public final com.mapbox.maps.EdgeInsets? visibleEdgeInsets;
2529
}
2630

2731
public final class MapboxCarMapEx {
@@ -40,9 +44,10 @@ package com.mapbox.maps.extension.androidauto {
4044
}
4145

4246
@com.mapbox.maps.MapboxExperimental public interface MapboxCarMapObserver {
43-
method public default void onAttached(com.mapbox.maps.extension.androidauto.MapboxCarMapSurface mapboxCarMapSurface);
44-
method public default void onDetached(com.mapbox.maps.extension.androidauto.MapboxCarMapSurface mapboxCarMapSurface);
45-
method public default void onVisibleAreaChanged(android.graphics.Rect visibleArea, com.mapbox.maps.EdgeInsets edgeInsets);
47+
method public default void onAttached(com.mapbox.maps.extension.androidauto.MapboxCarMapSurface);
48+
method public default void onDetached(com.mapbox.maps.extension.androidauto.MapboxCarMapSurface);
49+
method public default void onStableAreaChanged(android.graphics.Rect, com.mapbox.maps.EdgeInsets);
50+
method public default void onVisibleAreaChanged(android.graphics.Rect, com.mapbox.maps.EdgeInsets);
4651
}
4752

4853
@com.mapbox.maps.MapboxExperimental public final class MapboxCarMapScreenInstaller {

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

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,13 @@ internal class CarMapSurfaceOwner(
2525
private set
2626
internal var visibleArea: Rect? = null
2727
private set
28-
internal var edgeInsets: EdgeInsets? = null
28+
internal var visibleEdgeInsets: EdgeInsets? = null
2929
private set
3030
internal var visibleCenter: ScreenCoordinate = visibleCenter()
3131
private set
32+
internal var stableArea: Rect? = null
33+
private set
34+
internal var stableEdgeInsets: EdgeInsets? = null
3235

3336
internal lateinit var carContext: CarContext
3437
internal lateinit var mapInitOptions: MapInitOptions
@@ -49,10 +52,14 @@ internal class CarMapSurfaceOwner(
4952
mapboxCarMapSurface?.let { carMapSurface ->
5053
mapboxCarMapObserver.onAttached(carMapSurface)
5154
}
52-
ifNonNull(mapboxCarMapSurface, visibleArea, edgeInsets) { _, area, edge ->
55+
ifNonNull(mapboxCarMapSurface, visibleArea, visibleEdgeInsets) { _, area, edge ->
5356
logI(TAG, "registerObserver visibleAreaChanged")
5457
mapboxCarMapObserver.onVisibleAreaChanged(area, edge)
5558
}
59+
ifNonNull(mapboxCarMapSurface, stableArea, stableEdgeInsets) { _, area, edge ->
60+
logI(TAG, "registerObserver stableAreaChanged")
61+
mapboxCarMapObserver.onStableAreaChanged(area, edge)
62+
}
5663
}
5764

5865
fun unregisterObserver(mapboxCarMapObserver: MapboxCarMapObserver) {
@@ -111,9 +118,9 @@ internal class CarMapSurfaceOwner(
111118
}
112119

113120
private fun notifyVisibleAreaChanged() {
114-
this.edgeInsets = visibleArea?.edgeInsets()
121+
this.visibleEdgeInsets = visibleArea?.edgeInsets()
115122
this.visibleCenter = visibleCenter()
116-
ifNonNull(mapboxCarMapSurface, visibleArea, edgeInsets) { _, area, edge ->
123+
ifNonNull(mapboxCarMapSurface, visibleArea, visibleEdgeInsets) { _, area, edge ->
117124
logI(TAG, "notifyVisibleAreaChanged $area $edge")
118125
carMapObservers.forEach {
119126
it.onVisibleAreaChanged(area, edge)
@@ -122,7 +129,15 @@ internal class CarMapSurfaceOwner(
122129
}
123130

124131
override fun onStableAreaChanged(stableArea: Rect) {
125-
// Have not found a need for this.
132+
logI(TAG, "onStableAreaChanged stableArea:$stableArea")
133+
this.stableEdgeInsets = stableArea.edgeInsets()
134+
this.stableArea = stableArea
135+
ifNonNull(mapboxCarMapSurface, stableArea, stableEdgeInsets) { _, area, edge ->
136+
logI(TAG, "notifyStableAreaChanged $area $edge")
137+
carMapObservers.forEach {
138+
it.onStableAreaChanged(area, edge)
139+
}
140+
}
126141
}
127142

128143
override fun onScroll(distanceX: Float, distanceY: Float) {

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

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,22 @@ class MapboxCarMap {
9696
* Accessor to the edgeInsets calculated by the car library. It is recommended to
9797
* use the values returned by [MapboxCarMapObserver.onVisibleAreaChanged].
9898
*/
99-
val edgeInsets: EdgeInsets?
100-
get() { return carMapSurfaceOwner.edgeInsets }
99+
val visibleEdgeInsets: EdgeInsets?
100+
get() { return carMapSurfaceOwner.visibleEdgeInsets }
101+
102+
/**
103+
* Accessor to the stable area calculated by the car library. It is recommended to
104+
* use the values returned by [MapboxCarMapObserver.onStableAreaChanged].
105+
*/
106+
val stableArea: Rect?
107+
get() { return carMapSurfaceOwner.stableArea }
108+
109+
/**
110+
* Accessor to the stableEdgeInsets calculated by the car library. It is recommended to
111+
* use the values returned by [MapboxCarMapObserver.onStableAreaChanged].
112+
*/
113+
val stableEdgeInsets: EdgeInsets?
114+
get() { return carMapSurfaceOwner.stableEdgeInsets }
101115

102116
/**
103117
* @param mapboxCarMapObserver implements the desired mapbox car experiences

‎extension-androidauto/src/main/java/com/mapbox/maps/extension/androidauto/MapboxCarMapGestureHandler.java

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
package com.mapbox.maps.extension.androidauto;
22

33
import androidx.annotation.NonNull;
4+
import androidx.car.app.SurfaceCallback;
45

56
import com.mapbox.maps.MapboxExperimental;
67
import com.mapbox.maps.ScreenCoordinate;
78

89
/**
9-
* This interface captures gesture events from Android Auto's SurfaceCallback. If you would like
10-
* to customize observe the map gestures provided, you can set your own gestures
11-
* with [MapboxCarMap.setGestureHandler].
10+
* This interface captures gesture events from Android Auto's {@link SurfaceCallback}. In order to
11+
* customize the map gestures provided, you can set your own gestures
12+
* with {@link MapboxCarMap#setGestureHandler}.
1213
*/
1314
@MapboxExperimental
1415
public interface MapboxCarMapGestureHandler {
@@ -17,7 +18,7 @@ public interface MapboxCarMapGestureHandler {
1718
* Allows you to implement or observe the map scroll gesture handler. The surface is
1819
* [MapboxCarMapObserver.onAttached] before this can be triggered.
1920
*
20-
* @see [SurfaceCallback.onScroll] for instructions to enable.
21+
* @see SurfaceCallback#onScroll for instructions to enable.
2122
*
2223
* @param mapboxCarMapSurface loaded and ready car map surface
2324
* @param distanceX the distance in pixels along the X axis
@@ -34,9 +35,9 @@ default void onScroll(
3435

3536
/**
3637
* Allows you to implement or observe the map fling gesture handler. The surface is
37-
* [MapboxCarMapObserver.onAttached] before this can be triggered.
38+
* {@link MapboxCarMapObserver#onAttached} before this can be triggered.
3839
*
39-
* @see [SurfaceCallback.onFling] for instructions to enable.
40+
* @see SurfaceCallback#onFling for instructions to enable.
4041
*
4142
* @param mapboxCarMapSurface loaded and ready car map surface
4243
* @param velocityX the velocity of this fling measured in pixels per second along the x axis
@@ -52,9 +53,9 @@ default void onFling(
5253

5354
/**
5455
* Allows you to implement or observe the map scale gesture handler. The surface is
55-
* [MapboxCarMapObserver.onAttached] before this can be triggered.
56+
* {@link MapboxCarMapObserver#onAttached} before this can be triggered.
5657
*
57-
* @see [SurfaceCallback.onScale] for instructions to enable.
58+
* @see SurfaceCallback#onScale for instructions to enable.
5859
*
5960
* @param mapboxCarMapSurface loaded and ready car map surface
6061
* @param focusX x coordinate of the focal point in pixels. A negative value indicates that the focal point is unavailable.

‎extension-androidauto/src/main/java/com/mapbox/maps/extension/androidauto/MapboxCarMapObserver.java

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
package com.mapbox.maps.extension.androidauto;
2+
3+
import android.graphics.Rect;
4+
5+
import androidx.annotation.NonNull;
6+
import androidx.car.app.SurfaceCallback;
7+
8+
import com.mapbox.maps.EdgeInsets;
9+
import com.mapbox.maps.MapboxExperimental;
10+
11+
/**
12+
* Many downstream services will not work until the surface has been created and the map has
13+
* loaded. This interface allows you to create custom Mapbox experiences for the car.
14+
*/
15+
@MapboxExperimental
16+
public interface MapboxCarMapObserver {
17+
18+
/**
19+
* Called when a {@link MapboxCarMapSurface} has been loaded.
20+
* You can assume there will only be a single surface at a time.
21+
*
22+
* @see MapboxCarMap#registerObserver
23+
*
24+
* @param mapboxCarMapSurface loaded and ready to use car map surface
25+
*/
26+
default void onAttached(@NonNull MapboxCarMapSurface mapboxCarMapSurface) {
27+
// No op by default
28+
}
29+
30+
/**
31+
* Called when a {@link MapboxCarMapSurface} has been detached from this observer. Some examples that
32+
* can cause this to detach are:
33+
* - {@link MapboxCarMap} lifecycle is destroyed
34+
* - This observer has been unregistered with {@link MapboxCarMap#unregisterObserver}
35+
*
36+
* You can assume that there was a corresponding call to {@link #onAttached} with the same
37+
* [MapboxCarMapObserver] instance.
38+
*
39+
* @param mapboxCarMapSurface loaded and ready car map surface
40+
*/
41+
default void onDetached(@NonNull MapboxCarMapSurface mapboxCarMapSurface) {
42+
// No op by default
43+
}
44+
45+
/**
46+
* Called when the car library updates the visible regions for the surface. For example, this
47+
* is triggered when the action buttons come in and out of visibility.
48+
* You can assume this will be called after {@link #onAttached}.
49+
*
50+
* @see SurfaceCallback#onVisibleAreaChanged(Rect) for more details.
51+
*
52+
* @param visibleArea the visible area provided by the host
53+
* @param edgeInsets distance from each side of the screen that creates the visibleArea
54+
*/
55+
default void onVisibleAreaChanged(@NonNull Rect visibleArea, @NonNull EdgeInsets edgeInsets) {
56+
// No op by default
57+
}
58+
59+
/**
60+
* Called when the car library updates the stable region for the surface. This area will remain
61+
* constant while the visible area changes when views come in and out of view.
62+
*
63+
* @see SurfaceCallback#onStableAreaChanged(Rect) for more details.
64+
*
65+
* @param stableArea the stable area provided by the host
66+
* @param edgeInsets distance from each side of the screen that creates the stableArea
67+
*/
68+
default void onStableAreaChanged(@NonNull Rect stableArea, @NonNull EdgeInsets edgeInsets) {
69+
// No op by default
70+
}
71+
}

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

Lines changed: 0 additions & 52 deletions
This file was deleted.

0 commit comments

Comments
 (0)