From 4341341282a463eaadeb3c60c9d2ce53e80e4e7c Mon Sep 17 00:00:00 2001 From: Filip Hracek Date: Mon, 24 Feb 2025 17:43:51 +0100 Subject: [PATCH] [google_maps_flutter] Improve README and API doc comments (#8560) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There are some inconsistencies and anachronisms in the various READMEs and in the API docs. This PR attempts to address them. - Makes sure to link to platform-specific READMEs from the main README file. - Makes the READMEs more consistent (e.g. only leaving the bare minimum quick start for the main README, and leaving all platform-specific notes to platform READMEs). - Using the more correct “Not supported on all platforms” instead of “Supported on Android only” for functionality that works on both Android and the Web. Intentionally staying vague in API docs in order to make later maintenance easier. (https://github.com/flutter/flutter/issues/161948#issuecomment-2605429688) - Remove a doc comment from before null safety about asserting non-null. - Format the platform sections in the main README so that they’re proper lists, and so that all of them end with a link to the appropriate platform-specific README. Issues: - Fixes flutter/flutter#161954 - Related: flutter/flutter#161950, flutter/flutter#161948 --- .../google_maps_flutter/CHANGELOG.md | 3 +- .../google_maps_flutter/README.md | 137 +++++++++--------- .../lib/src/google_map.dart | 11 +- .../google_maps_flutter/pubspec.yaml | 2 +- .../google_maps_flutter_android/CHANGELOG.md | 4 + .../google_maps_flutter_android/README.md | 6 +- .../google_maps_flutter_android/pubspec.yaml | 2 +- .../CHANGELOG.md | 5 + .../lib/src/types/polyline.dart | 6 +- .../pubspec.yaml | 2 +- .../google_maps_flutter_web/CHANGELOG.md | 3 +- .../google_maps_flutter_web/README.md | 1 + .../google_maps_flutter_web/pubspec.yaml | 2 +- 13 files changed, 100 insertions(+), 84 deletions(-) diff --git a/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md index ef5c348d68b7..9c0b9a460d42 100644 --- a/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md +++ b/packages/google_maps_flutter/google_maps_flutter/CHANGELOG.md @@ -1,5 +1,6 @@ -## NEXT +## 2.10.1 +* Updates READMEs and API docs. * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4. ## 2.10.0 diff --git a/packages/google_maps_flutter/google_maps_flutter/README.md b/packages/google_maps_flutter/google_maps_flutter/README.md index 1f1f68a73443..d80f9bbdd10b 100644 --- a/packages/google_maps_flutter/google_maps_flutter/README.md +++ b/packages/google_maps_flutter/google_maps_flutter/README.md @@ -12,6 +12,15 @@ A Flutter plugin that provides a [Google Maps](https://developers.google.com/map [web-support]: https://docs.flutter.dev/reference/supported-platforms +**Important:** Not all functionality is supported on all platforms. +To check details, please read the README files +of the endorsed platform packages: + +* [`google_maps_flutter_android` README](https://pub.dev/packages/google_maps_flutter_android) +* [`google_maps_flutter_ios` README](https://pub.dev/packages/google_maps_flutter_ios) +* [`google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web) + + ## Getting Started * Get an API key at . @@ -30,86 +39,72 @@ For more details, see [Getting started with Google Maps Platform](https://develo ### Android -1. Set the `minSdkVersion` in `android/app/build.gradle`: - -```groovy -android { - defaultConfig { - minSdkVersion 20 - } -} -``` - -This means that app will only be available for users that run Android SDK 20 or higher. - -2. Specify your API key in the application manifest `android/app/src/main/AndroidManifest.xml`: - -```xml - -``` - -#### Display Mode +1. Specify your API key in the application manifest `android/app/src/main/AndroidManifest.xml`: -The Android implementation supports multiple -[platform view display modes](https://docs.flutter.dev/platform-integration/android/platform-views). -For details, see [the Android README](https://pub.dev/packages/google_maps_flutter_android#display-mode). + ```xml + + ``` -#### Cloud-based map styling - -Cloud-based map styling works on Android only if `AndroidMapRenderer.latest` map renderer has been initialized. -For details, see [the Android README](https://pub.dev/packages/google_maps_flutter_android#map-renderer). +2. Read about Android-specific features and limitations in the + [`google_maps_flutter_android` README](https://pub.dev/packages/google_maps_flutter_android). ### iOS -To set up, specify your API key in the application delegate `ios/Runner/AppDelegate.m`: - -```objectivec -#include "AppDelegate.h" -#include "GeneratedPluginRegistrant.h" -#import "GoogleMaps/GoogleMaps.h" - -@implementation AppDelegate - -- (BOOL)application:(UIApplication *)application - didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { - [GMSServices provideAPIKey:@"YOUR KEY HERE"]; - [GeneratedPluginRegistrant registerWithRegistry:self]; - return [super application:application didFinishLaunchingWithOptions:launchOptions]; -} -@end -``` - -Or in your swift code, specify your API key in the application delegate `ios/Runner/AppDelegate.swift`: - -```swift -import UIKit -import Flutter -import GoogleMaps - -@UIApplicationMain -@objc class AppDelegate: FlutterAppDelegate { - override func application( - _ application: UIApplication, - didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? - ) -> Bool { - GMSServices.provideAPIKey("YOUR KEY HERE") - GeneratedPluginRegistrant.register(with: self) - return super.application(application, didFinishLaunchingWithOptions: launchOptions) - } -} -``` +1. Specify your API key in the application delegate `ios/Runner/AppDelegate.m`: + + ```objectivec + #include "AppDelegate.h" + #include "GeneratedPluginRegistrant.h" + #import "GoogleMaps/GoogleMaps.h" + + @implementation AppDelegate + + - (BOOL)application:(UIApplication *)application + didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { + [GMSServices provideAPIKey:@"YOUR KEY HERE"]; + [GeneratedPluginRegistrant registerWithRegistry:self]; + return [super application:application didFinishLaunchingWithOptions:launchOptions]; + } + @end + ``` + + Or in your Swift code, specify your API key + in the application delegate `ios/Runner/AppDelegate.swift`: + + ```swift + import UIKit + import Flutter + import GoogleMaps + + @UIApplicationMain + @objc class AppDelegate: FlutterAppDelegate { + override func application( + _ application: UIApplication, + didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? + ) -> Bool { + GMSServices.provideAPIKey("YOUR KEY HERE") + GeneratedPluginRegistrant.register(with: self) + return super.application(application, didFinishLaunchingWithOptions: launchOptions) + } + } + ``` + +2. Read about iOS-specific features and limitations in the + [`google_maps_flutter_ios` README](https://pub.dev/packages/google_maps_flutter_ios). ### Web -You'll need to modify the `web/index.html` file of your Flutter Web application -to include the Google Maps JS SDK. +1. Add the following to the `` section of `web/index.html`: + + ```html + + ``` -Check [the `google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web) -for the latest information on how to prepare your App to use Google Maps on the -web. +2. Read about iOS-specific features and limitations in the + [`google_maps_flutter_web` README](https://pub.dev/packages/google_maps_flutter_web). ### All diff --git a/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart b/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart index 888195ca36d2..9ef26405214c 100644 --- a/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart +++ b/packages/google_maps_flutter/google_maps_flutter/lib/src/google_map.dart @@ -87,7 +87,7 @@ class AndroidGoogleMapsFlutter { class GoogleMap extends StatefulWidget { /// Creates a widget displaying data from Google Maps services. /// - /// [AssertionError] will be thrown if [initialCameraPosition] is null; + /// The map's camera will start centered on [initialCameraPosition]. const GoogleMap({ super.key, required this.initialCameraPosition, @@ -110,8 +110,6 @@ class GoogleMap extends StatefulWidget { this.myLocationEnabled = false, this.myLocationButtonEnabled = true, this.layoutDirection, - - /// If no padding is specified default padding will be 0. this.padding = EdgeInsets.zero, this.indoorViewEnabled = false, this.trafficEnabled = false, @@ -202,6 +200,8 @@ class GoogleMap extends StatefulWidget { final bool fortyFiveDegreeImageryEnabled; /// Padding to be set on map. See https://developers.google.com/maps/documentation/android-sdk/map#map_padding for more details. + /// + /// If no padding is specified, the default padding is 0. final EdgeInsets padding; /// Markers to be placed on the map. @@ -223,6 +223,9 @@ class GoogleMap extends StatefulWidget { final Set tileOverlays; /// Cluster Managers to be initialized for the map. + /// + /// On the web, an extra step is required to enable clusters. + /// See https://pub.dev/packages/google_maps_flutter_web. final Set clusterManagers; /// Called when the camera starts moving. @@ -261,6 +264,8 @@ class GoogleMap extends StatefulWidget { /// * The My Location button animates to focus on the user's current location /// if the user's location is currently known. /// + /// This feature is not present in the Google Maps SDK for the web. + /// /// Enabling this feature requires adding location permissions to both native /// platforms of your app. /// * On Android add either diff --git a/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml index 6afe27288aaf..1c91065a66b5 100644 --- a/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml +++ b/packages/google_maps_flutter/google_maps_flutter/pubspec.yaml @@ -2,7 +2,7 @@ name: google_maps_flutter description: A Flutter plugin for integrating Google Maps in iOS and Android applications. repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22 -version: 2.10.0 +version: 2.10.1 environment: sdk: ^3.4.0 diff --git a/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md index e18bd40228cf..2c05bb8454dd 100644 --- a/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md +++ b/packages/google_maps_flutter/google_maps_flutter_android/CHANGELOG.md @@ -1,3 +1,7 @@ +## 2.14.13 + +* Updates READMEs and API docs. + ## 2.14.12 * Updates androidx.annotation:annotation to 1.9.1. diff --git a/packages/google_maps_flutter/google_maps_flutter_android/README.md b/packages/google_maps_flutter/google_maps_flutter_android/README.md index a4f0ff5a3486..450c6e5cfbf4 100644 --- a/packages/google_maps_flutter/google_maps_flutter_android/README.md +++ b/packages/google_maps_flutter/google_maps_flutter_android/README.md @@ -39,7 +39,7 @@ void main() { ### Texture Layer Hybrid Composition -This is the the current default mode and corresponds to `useAndroidViewSurface = false`. +This is the current default mode and corresponds to `useAndroidViewSurface = false`. This mode is more performant than Hybrid Composition and we recommend that you use this mode. ### Hybrid Composition @@ -78,6 +78,10 @@ Google Play the latest renderer will not be available and the legacy renderer wi WARNING: `AndroidMapRenderer.legacy` is known to crash apps and is no longer supported by the Google Maps team and therefore cannot be supported by the Flutter team. +### Cloud-based map styling + +Cloud-based map styling is not supported with the `AndroidMapRenderer.legacy` renderer. + ## Supported Heatmap Options | Field | Supported | diff --git a/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml index 19db56e19133..353f8e028583 100644 --- a/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml +++ b/packages/google_maps_flutter/google_maps_flutter_android/pubspec.yaml @@ -2,7 +2,7 @@ name: google_maps_flutter_android description: Android implementation of the google_maps_flutter plugin. repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter_android issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22 -version: 2.14.12 +version: 2.14.13 environment: sdk: ^3.5.0 diff --git a/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md index 34ff087b04ae..0f39df3a70d0 100644 --- a/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md +++ b/packages/google_maps_flutter/google_maps_flutter_platform_interface/CHANGELOG.md @@ -1,6 +1,11 @@ +## 2.11.1 + +* Updates READMEs and API docs. + ## 2.11.0 * Adds support for animating the camera with a duration. +* Updates READMEs and API docs. ## 2.10.0 diff --git a/packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart b/packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart index e590671419e6..75e900dec4fe 100644 --- a/packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart +++ b/packages/google_maps_flutter/google_maps_flutter_platform_interface/lib/src/types/polyline.dart @@ -66,7 +66,7 @@ class Polyline implements MapsObject { /// polyline except the start and end vertices. See [JointType] for supported joint types. The default value is /// mitered. /// - /// Supported on Android only. + /// Not supported on all platforms. final JointType jointType; /// The stroke pattern for the polyline. @@ -86,14 +86,14 @@ class Polyline implements MapsObject { /// /// The default start cap is ButtCap. /// - /// Supported on Android only. + /// Not supported on all platforms. final Cap startCap; /// The cap at the end vertex of the polyline. /// /// The default end cap is ButtCap. /// - /// Supported on Android only. + /// Not supported on all platforms. final Cap endCap; /// True if the polyline is visible. diff --git a/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml index 868cad297026..0c376f4400f9 100644 --- a/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml +++ b/packages/google_maps_flutter/google_maps_flutter_platform_interface/pubspec.yaml @@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/google_maps_f issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22 # NOTE: We strongly prefer non-breaking changes, even at the expense of a # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes -version: 2.11.0 +version: 2.11.1 environment: sdk: ^3.4.0 diff --git a/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md b/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md index b4239c12870e..645c2f9479c4 100644 --- a/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md +++ b/packages/google_maps_flutter/google_maps_flutter_web/CHANGELOG.md @@ -1,5 +1,6 @@ -## NEXT +## 0.5.10+1 +* Updates READMEs and API docs. * Updates minimum supported SDK version to Flutter 3.22/Dart 3.4. ## 0.5.10 diff --git a/packages/google_maps_flutter/google_maps_flutter_web/README.md b/packages/google_maps_flutter/google_maps_flutter_web/README.md index e53fe3506b07..9a92c70bad11 100644 --- a/packages/google_maps_flutter/google_maps_flutter_web/README.md +++ b/packages/google_maps_flutter/google_maps_flutter_web/README.md @@ -64,6 +64,7 @@ If you need marker clustering support, modify the tag to load the [js-mar ``` ## Heatmaps + To use heatmaps, add `&libraries=visualization` to the end of the URL. See [the documentation](https://developers.google.com/maps/documentation/javascript/libraries) for more information. ## Limitations of the web version diff --git a/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml b/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml index 7ed3d99fed5e..271a86d6fa95 100644 --- a/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml +++ b/packages/google_maps_flutter/google_maps_flutter_web/pubspec.yaml @@ -2,7 +2,7 @@ name: google_maps_flutter_web description: Web platform implementation of google_maps_flutter repository: https://github.com/flutter/packages/tree/main/packages/google_maps_flutter/google_maps_flutter_web issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+maps%22 -version: 0.5.10 +version: 0.5.10+1 environment: sdk: ^3.4.0