[Android Auto] Working on android auto docs (#6569)

* Working on android auto docs

* simplify wording

* Update libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/MapboxScreen.kt

Co-authored-by: Abhishek Kejriwal <abhishek.kejriwal@mapbox.com>

Co-authored-by: Abhishek Kejriwal <abhishek.kejriwal@mapbox.com>

Author: kmadsen

libnavui-androidauto/api/current.txt

@@ -658,6 +658,7 @@ package com.mapbox.androidauto.screenmanager {
     field public static final String FREE_DRIVE = "MAPBOX_FREE_DRIVE";
     field public static final String FREE_DRIVE_FEEDBACK = "MAPBOX_FREE_DRIVE_FEEDBACK";
     field public static final String GEO_DEEPLINK = "MAPBOX_GEO_DEEPLINK";
+    field public static final String GEO_DEEPLINK_FEEDBACK = "MAPBOX_GEO_DEEPLINK_FEEDBACK";
     field public static final com.mapbox.androidauto.screenmanager.MapboxScreen INSTANCE;
     field public static final String NEEDS_LOCATION_PERMISSION = "MAPBOX_NEEDS_LOCATION_PERMISSION";
     field public static final String ROUTE_PREVIEW = "MAPBOX_ROUTE_PREVIEW";
@@ -667,7 +668,7 @@ package com.mapbox.androidauto.screenmanager {
     field public static final String SETTINGS = "MAPBOX_SETTINGS";
   }
 
-  @StringDef({com.mapbox.androidauto.screenmanager.MapboxScreen.NEEDS_LOCATION_PERMISSION, com.mapbox.androidauto.screenmanager.MapboxScreen.SETTINGS, com.mapbox.androidauto.screenmanager.MapboxScreen.FREE_DRIVE, com.mapbox.androidauto.screenmanager.MapboxScreen.SEARCH, com.mapbox.androidauto.screenmanager.MapboxScreen.SEARCH_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.FAVORITES, com.mapbox.androidauto.screenmanager.MapboxScreen.FAVORITES_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.GEO_DEEPLINK, com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW, com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.ACTIVE_GUIDANCE, com.mapbox.androidauto.screenmanager.MapboxScreen.ACTIVE_GUIDANCE_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.ARRIVAL}) @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention.BINARY) public static @interface MapboxScreen.Key {
+  @StringDef({com.mapbox.androidauto.screenmanager.MapboxScreen.NEEDS_LOCATION_PERMISSION, com.mapbox.androidauto.screenmanager.MapboxScreen.SETTINGS, com.mapbox.androidauto.screenmanager.MapboxScreen.FREE_DRIVE, com.mapbox.androidauto.screenmanager.MapboxScreen.SEARCH, com.mapbox.androidauto.screenmanager.MapboxScreen.SEARCH_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.FAVORITES, com.mapbox.androidauto.screenmanager.MapboxScreen.FAVORITES_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.GEO_DEEPLINK, com.mapbox.androidauto.screenmanager.MapboxScreen.GEO_DEEPLINK_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW, com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.ACTIVE_GUIDANCE, com.mapbox.androidauto.screenmanager.MapboxScreen.ACTIVE_GUIDANCE_FEEDBACK, com.mapbox.androidauto.screenmanager.MapboxScreen.ARRIVAL}) @kotlin.annotation.Retention(kotlin.annotation.AnnotationRetention.BINARY) public static @interface MapboxScreen.Key {
   }
 
   public final class MapboxScreenEvent {
@@ -766,6 +767,12 @@ package com.mapbox.androidauto.screenmanager.factories {
     method public androidx.car.app.Screen create(androidx.car.app.CarContext carContext);
   }
 
+  public final class GeoDeeplinkPlacesFeedbackScreenFactory extends com.mapbox.androidauto.feedback.core.CarFeedbackScreenFactory {
+    ctor public GeoDeeplinkPlacesFeedbackScreenFactory(com.mapbox.androidauto.MapboxCarContext mapboxCarContext);
+    method public com.mapbox.androidauto.feedback.ui.CarFeedbackPoll getCarFeedbackPoll(androidx.car.app.CarContext carContext);
+    method public String getSourceName();
+  }
+
   public final class NeedsLocationPermissionScreenFactory implements com.mapbox.androidauto.screenmanager.MapboxScreenFactory {
     ctor public NeedsLocationPermissionScreenFactory();
     method public androidx.car.app.Screen create(androidx.car.app.CarContext carContext);

libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/MapboxScreen.kt

@@ -60,6 +60,11 @@ object MapboxScreen {
      */
     const val GEO_DEEPLINK = "MAPBOX_GEO_DEEPLINK"
 
+    /**
+     * Gives the user an ability to search for a destination with their voice.
+     */
+    const val GEO_DEEPLINK_FEEDBACK = "MAPBOX_GEO_DEEPLINK_FEEDBACK"
+
     /**
      * Gives the user an ability to select a navigation route.
      */
@@ -98,6 +103,7 @@ object MapboxScreen {
         FAVORITES,
         FAVORITES_FEEDBACK,
         GEO_DEEPLINK,
+        GEO_DEEPLINK_FEEDBACK,
         ROUTE_PREVIEW,
         ROUTE_PREVIEW_FEEDBACK,
         ACTIVE_GUIDANCE,

libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/MapboxScreenGraph.kt

@@ -11,6 +11,7 @@ import com.mapbox.androidauto.screenmanager.MapboxScreen.FAVORITES_FEEDBACK
 import com.mapbox.androidauto.screenmanager.MapboxScreen.FREE_DRIVE
 import com.mapbox.androidauto.screenmanager.MapboxScreen.FREE_DRIVE_FEEDBACK
 import com.mapbox.androidauto.screenmanager.MapboxScreen.GEO_DEEPLINK
+import com.mapbox.androidauto.screenmanager.MapboxScreen.GEO_DEEPLINK_FEEDBACK
 import com.mapbox.androidauto.screenmanager.MapboxScreen.NEEDS_LOCATION_PERMISSION
 import com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW
 import com.mapbox.androidauto.screenmanager.MapboxScreen.ROUTE_PREVIEW_FEEDBACK
@@ -25,6 +26,7 @@ import com.mapbox.androidauto.screenmanager.factories.FavoritesScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.FreeDriveFeedbackScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.FreeDriveScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.GeoDeeplinkPlacesCarScreenFactory
+import com.mapbox.androidauto.screenmanager.factories.GeoDeeplinkPlacesFeedbackScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.NeedsLocationPermissionScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.RoutePreviewFeedbackScreenFactory
 import com.mapbox.androidauto.screenmanager.factories.RoutePreviewScreenFactory
@@ -58,6 +60,8 @@ fun MapboxCarContext.prepareScreens() = apply {
             to FavoritesFeedbackScreenFactory(mapboxCarContext),
         GEO_DEEPLINK
             to GeoDeeplinkPlacesCarScreenFactory(mapboxCarContext),
+        GEO_DEEPLINK_FEEDBACK
+            to GeoDeeplinkPlacesFeedbackScreenFactory(mapboxCarContext),
         ROUTE_PREVIEW
             to RoutePreviewScreenFactory(mapboxCarContext),
         ROUTE_PREVIEW_FEEDBACK

libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/MapboxScreenManager.kt

@@ -2,13 +2,15 @@ package com.mapbox.androidauto.screenmanager
 
 import androidx.annotation.UiThread
 import androidx.annotation.VisibleForTesting
+import androidx.car.app.CarContext
 import androidx.car.app.Screen
 import androidx.car.app.ScreenManager
 import androidx.car.app.Session
 import androidx.car.app.model.Template
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.lifecycleScope
+import com.mapbox.androidauto.MapboxCarContext
 import com.mapbox.androidauto.internal.context.MapboxCarContextOwner
 import com.mapbox.navigation.utils.internal.logI
 import kotlinx.coroutines.channels.BufferOverflow
@@ -21,8 +23,48 @@ import java.util.ArrayDeque
 import java.util.Deque
 
 /**
- * The Mapbox Navigation Android Auto SDK is prepared with a default experience. This object allows
- * you to customize the experience to meet your needs.
+ * [MapboxScreenManager] allows you to prepare an experience that includes many screens with a
+ * single function. Use the [MapboxCarContext.prepareScreens] to get started.
+ *
+ * ### How it works
+ * Using [String] to [MapboxScreenFactory] pairing, the [MapboxScreenManager] will create a screen
+ * based on a string provided. You can customize screens by setting the key value pair.
+ *
+ * [MapboxScreenManager] can be observed and controlled by the car or app. Observe the screen
+ * changes with [MapboxScreenManager.screenEvent], change the screen with operations like
+ * [MapboxScreenManager.replaceTop]. See the [MapboxScreenOperation] for all of the available
+ * operations, each operation is applied through [MapboxScreenManager] functions.
+ *
+ * ### Set up
+ * The [MapboxScreenManager] is provided to you through the [MapboxCarContext]. It is important
+ * to keep the screen manager lifecycle close to [CarContext] to avoid memory leaks.
+ * [MapboxScreenManager] does not work without the [ScreenManager] which is also bound to the
+ * [CarContext].
+ *
+ * Example
+ * ```
+ * class MySession : Session() {
+ *   private val mapboxCarContext = MapboxCarContext(lifecycle, MapboxCarMap())
+ *       .prepareScreens()
+ * --snip--
+ * }
+ * ```
+ *
+ * ### Customization
+ *
+ * At any point, you can change the mapping of the [MapboxScreenManager] with setters. The
+ * [MapboxScreenFactory] instances are expected to have a lifecycle as long as the [Session], so
+ * an instance of [MapboxScreenManager] is required. You can access this class through the
+ *
+ * [MapboxScreenFactory.create]
+ * Example
+ * ```
+ * mapboxCarContext.screenManager["MY_SCREEN"] = MyScreenFactory()
+ *
+ * // When your app is showing on the Android Auto head unit, the MyScreenFactory will be shown
+ * // on the top of the back stack.
+ * MapboxScreenManager.replaceTop("MY_SCREEN")
+ * ```
  */
 class MapboxScreenManager internal constructor(
     private val carContextOwner: MapboxCarContextOwner

libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/factories/GeoDeeplinkPlacesCarScreenFactory.kt

@@ -23,7 +23,7 @@ class GeoDeeplinkPlacesCarScreenFactory(
         return PlacesListOnMapScreen(
             SearchCarContext(mapboxCarContext),
             placesProvider,
-            listOf(CarFeedbackAction(MapboxScreen.FAVORITES_FEEDBACK))
+            listOf(CarFeedbackAction(MapboxScreen.GEO_DEEPLINK_FEEDBACK))
         )
     }
 }

libnavui-androidauto/src/main/java/com/mapbox/androidauto/screenmanager/factories/GeoDeeplinkPlacesFeedbackScreenFactory.kt

@@ -0,0 +1,21 @@
+package com.mapbox.androidauto.screenmanager.factories
+
+import androidx.car.app.CarContext
+import com.mapbox.androidauto.MapboxCarContext
+import com.mapbox.androidauto.feedback.core.CarFeedbackScreenFactory
+import com.mapbox.androidauto.feedback.ui.CarFeedbackPoll
+import com.mapbox.androidauto.screenmanager.MapboxScreen
+
+/**
+ * Default screen for [MapboxScreen.GEO_DEEPLINK_FEEDBACK].
+ */
+class GeoDeeplinkPlacesFeedbackScreenFactory(
+    private val mapboxCarContext: MapboxCarContext
+) : CarFeedbackScreenFactory(mapboxCarContext) {
+    override fun getSourceName(): String = MapboxScreen.GEO_DEEPLINK
+
+    override fun getCarFeedbackPoll(carContext: CarContext): CarFeedbackPoll {
+        return mapboxCarContext.options.feedbackPollProvider
+            .getSearchFeedbackPoll(carContext)
+    }
+}