docs: make android auto and carplay documentation part of the dart docs

Author: jokerttu

README.md

@@ -348,8 +348,8 @@ await mapViewController.setMapColorScheme(MapColorScheme.dark);
 ## Support for Android Auto and Apple CarPlay
 This plugin is compatible with both Android Auto and Apple CarPlay infotainment systems. For more details, please refer to the respective platform documentation:
 
-- [Android Auto documentation](./ANDROIDAUTO.md)
-- [CarPlay documentation](./CARPLAY.md)
+- [Android Auto documentation](./doc/android-auto.md)
+- [CarPlay documentation](./doc/carplay.md)
 
 ## Known issues
 

dartdoc_options.yaml

@@ -26,7 +26,20 @@ dartdoc:
     "Image Registry":
       markdown: doc/image-registry.md
       name: Image Registry
-  categoryOrder: ["Navigation", "Navigation View", "Map View", "Image Registry"]
+    "Android Auto":
+      markdown: doc/android-auto.md
+      name: Android Auto
+    "Carplay":
+      markdown: doc/carplay.md
+      name: Carplay
+  categoryOrder:
+    [
+      "Navigation",
+      "Navigation View",
+      "Map View",
+      "Image Registry",
+      "Android Auto",
+      "Carplay",
+    ]
   showUndocumentedCategories: true
-  nodoc: ['**/*.g.dart']
-
+  nodoc: ["**/*.g.dart"]

doc/android-auto.md

@@ -0,0 +1,81 @@
+# Navigation for Android Auto
+
+This guide explains how to enable and integrate Android Auto with the Flutter Navigation SDK.
+
+## Requirements
+
+- Android device
+- Android Auto test device or Android Automotive OS emulator
+
+## Setup
+
+Refer to the [Android for Cars developer documentation](https://developer.android.com/training/cars) to understand how the Android Auto works and to complete the initial setup. Key steps include:
+
+- Installing Android for Cars App Library.
+- Configuring your app's manifest file to include Android Auto.
+- Declaring a minimum car-app level in your manifest.
+- Creating 'CarAppService' and session
+
+For all the steps above, you can refer to the Android example application for guidance.
+
+### Screen for Android Auto
+
+Once your project is configured accordingly, and you are ready to build the screen for Android Auto, you can leverage the `AndroidAutoBaseScreen` provided by the SDK. This base class simplifies the setup by handling initialization, teardown, and rendering the map on the Android Auto display.
+
+Please refer to the `SampleAndroidAutoScreen.kt` file in the Android example app for guidance.
+
+To customize the Android Auto experience, override the `onGetTemplate` method in your custom AndroidAutoScreen class, providing your own `Template`:
+
+```kotlin
+override fun onGetTemplate(): Template {
+    /** ... */
+    @SuppressLint("MissingPermission")
+    val navigationTemplateBuilder =
+        NavigationTemplate.Builder()
+            .setActionStrip(
+                ActionStrip.Builder()
+                    .addAction(
+                        Action.Builder()
+                            .setTitle("Re-center")
+                            .setOnClickListener {
+                                if (mGoogleMap == null) return@setOnClickListener
+                                mGoogleMap!!.followMyLocation(GoogleMap.CameraPerspective.TILTED)
+                            }
+                            .build())
+                    .addAction(
+                        Action.Builder()
+                            .setTitle("Custom event")
+                            .setOnClickListener {
+                                sendCustomNavigationAutoEvent("CustomAndroidAutoEvent", mapOf("sampleDataKey" to "sampleDataContent"))
+                            }
+                            .build())
+                    .build())
+            .setMapActionStrip(ActionStrip.Builder().addAction(Action.PAN).build())
+    /** ... */
+}
+```
+
+For advanced customization, you can bypass the base class and implement your own screen by inheriting `Screen`. You can use the provided `AndroidAutoBaseScreen` base class as a reference on how to do that.
+
+### Flutter Setup
+
+On the Flutter side, you can use the `GoogleMapsAutoViewController` to interface with the CarPlay instance. The `GoogleMapsAutoViewController` allows you to call map functions on the CarPlay map view, and you can manage listeners using the provided functions.
+
+```dart
+final GoogleMapsAutoViewController _autoViewController =
+      GoogleMapsAutoViewController();
+
+_autoViewController.listenForCustomNavigationAutoEvents((event) {
+    showMessage("Received event: ${event.event}");
+});
+
+Future<void> _setMapTypeForAutoToSatellite() async {
+    await _autoViewController.setMapType(mapType: MapType.satellite);
+}
+```
+
+For a more detailed example, refer to the `lib/pages/navigation.dart` file in the Flutter example application.
+
+## Example Project
+
+For a fully functional Android Auto implementation, check out the [Android Studio example app](./example/android/).

doc/carplay.md

@@ -0,0 +1,63 @@
+# Navigation for Apple CarPlay
+
+This guide explains how to enable and integrate Apple CarPlay with the Flutter SDK.
+
+## Requirements
+
+- iOS device or iOS simulator
+- CarPlay Simulator
+- CarPlay entitlement for your application (provided by Apple)
+
+## Setup
+
+Refer to the [Apple CarPlay Developer Guide](https://developer.apple.com/carplay/) to understand how CarPlay works and to complete the initial setup. Key steps include:
+
+- Adding the CarPlay entitlement to your Xcode project.
+- Creating a separate scene for the CarPlay map and enabling support for multiple scenes.
+
+### SceneDelegate for CarPlay
+
+Once your project is configured to support multiple scenes, and you are setting up a dedicated scene for CarPlay, you can leverage the `BaseCarSceneDelegate` provided by the SDK. This base class simplifies the setup by handling initialization, teardown, and rendering the map on the CarPlay display.
+
+Please refer to the `CarSceneDelegate.swift` file in the iOS example app for guidance.
+
+To customize the CarPlay experience, override the `getTemplate` method in your custom `CarSceneDelegate` class, providing your own `CPMapTemplate`:
+
+```swift
+override func getTemplate() -> CPMapTemplate {
+    let template = CPMapTemplate()
+    template.showPanningInterface(animated: true)
+
+    let button = CPBarButton(title: "Custom Event") { [weak self] _ in
+      let data = ["sampleDataKey": "sampleDataContent"]
+      self?.sendCustomNavigationAutoEvent(event: "CustomCarPlayEvent", data: data)
+    }
+    template.leadingNavigationBarButtons = [button]
+    return template
+  }
+```
+
+For advanced customization, you can bypass the base class and implement your own delegate inheriting `CPTemplateApplicationSceneDelegate`. You can use the provided `BaseCarSceneDelegate` base class as a reference on how to do that.
+
+### Flutter Setup
+
+On the Flutter side, you can use the `GoogleMapsAutoViewController` to interface with the CarPlay instance. The `GoogleMapsAutoViewController` allows you to call map functions on the CarPlay map view, and you can manage listeners using the provided functions.
+
+```dart
+final GoogleMapsAutoViewController _autoViewController =
+      GoogleMapsAutoViewController();
+
+_autoViewController.listenForCustomNavigationAutoEvents((event) {
+    showMessage("Received event: ${event.event}");
+});
+
+Future<void> _setMapTypeForAutoToSatellite() async {
+    await _autoViewController.setMapType(mapType: MapType.satellite);
+}
+```
+
+For a more detailed example, refer to the `lib/pages/navigation.dart` file in the Flutter example application.
+
+## Example Project
+
+For a fully functional CarPlay implementation, check out the [Runner](./example/ios/) Xcode project, which includes the `RunnerCarPlay` build target. The sample already contains test entitlement so you don't need to request one from Apple to run it.

lib/src/google_maps_auto_view_controller.dart

@@ -17,6 +17,8 @@ import 'package:flutter/widgets.dart';
 import '../google_navigation_flutter.dart';
 import 'google_navigation_flutter_platform_interface.dart';
 
+/// {@category Android Auto}
+/// {@category Carplay}
 class GoogleMapsAutoViewController {
   GoogleMapsAutoViewController() {
     GoogleMapsNavigationPlatform.instance.autoAPI.ensureAutoViewApiSetUp();

lib/src/types/circles.dart

@@ -21,6 +21,8 @@ import '../utils/color.dart';
 /// Circle that has beed added to map.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 @immutable
 class Circle {
   /// Construct [Circle].

lib/src/types/lat_lng.dart

@@ -18,6 +18,8 @@ import 'package:flutter/foundation.dart';
 /// {@category Navigation}
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 @immutable
 class LatLng {
   /// Initializes a [LatLng] with the provided latitude and longitude values.

lib/src/types/lat_lng_bounds.dart

@@ -19,6 +19,8 @@ import '../../google_navigation_flutter.dart';
 /// LatLngBounds bounds object.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 @immutable
 class LatLngBounds {
   /// Initialize LatLngBounds with the given southwest and northeast points.

lib/src/types/markers.dart

@@ -19,6 +19,8 @@ import '../../google_navigation_flutter.dart';
 /// Marker that has beed added to the map.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 @immutable
 class Marker {
   /// Construct [Marker]

lib/src/types/navigation_view_types.dart

@@ -23,6 +23,8 @@ class NavigationViewRecenterButtonClickedEvent {}
 /// Map type.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 enum MapType {
   /// No type set.
   none,
@@ -76,6 +78,8 @@ enum NavigationForceNightMode {
 /// Represents the camera position in a Google Maps view.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 class CameraPosition {
   /// Creates a [CameraPosition] object with map centered
   /// to the [target] with the given [bearing], [tilt] and [zoom] level.
@@ -123,6 +127,8 @@ class CameraPosition {
 /// to specify the orientation of the camera.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 enum CameraPerspective {
   /// A tilted perspective facing in the same direction as the user.
   tilted,
@@ -134,6 +140,9 @@ enum CameraPerspective {
   topDownNorthUp,
 }
 
+/// {@category Navigation}
+/// {@category Android Auto}
+/// {@category Carplay}
 class CustomNavigationAutoEvent {
   final String? event;
   final Object? data;
@@ -144,6 +153,9 @@ class CustomNavigationAutoEvent {
   String toString() => 'CustomNavigationAutoEvent(event: $event, data: $data)';
 }
 
+/// {@category Navigation}
+/// {@category Android Auto}
+/// {@category Carplay}
 class AutoScreenAvailabilityChangedEvent {
   final bool isAvailable;
 
@@ -347,6 +359,8 @@ enum CameraUpdateType {
 /// the current position.
 /// {@category Navigation View}
 /// {@category Map View}
+/// {@category Android Auto}
+/// {@category Carplay}
 class CameraUpdate {
   CameraUpdate._(this.type);