[webview_flutter] Adds examples of accessing platform-specific features for each class (#7089)

* start

* more docs and version bump

* fix main

Author: bparrishMines

packages/webview_flutter/webview_flutter/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 4.0.4
+
+* Adds examples of accessing platform-specific features for each class.
+
 ## 4.0.3
 
 * Updates example code for `use_build_context_synchronously` lint.

packages/webview_flutter/webview_flutter/README.md

@@ -99,7 +99,7 @@ import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
 ```
 
 Now, additional features can be accessed through the platform implementations. Classes
-`WebViewController`, `WebViewWidget`, `NavigationDelegate`, and `WebViewCookieManager` pass their
+[WebViewController], [WebViewWidget], [NavigationDelegate], and [WebViewCookieManager] pass their
 functionality to a class provided by the current platform. Below are a couple of ways to access
 additional functionality provided by the platform and is followed by an example.
 
@@ -212,11 +212,17 @@ Below is a non-exhaustive list of changes to the API:
   * `WebView.userAgent` -> `WebViewController.setUserAgent`
   * `WebView.backgroundColor` -> `WebViewController.setBackgroundColor`
 * The following features have been moved to an Android implementation class. See section
-  `Platform-Specific Features` for details on accessing Android platform specific features.
+  `Platform-Specific Features` for details on accessing Android platform-specific features.
   * `WebView.debuggingEnabled` -> `static AndroidWebViewController.enableDebugging`
   * `WebView.initialMediaPlaybackPolicy` -> `AndroidWebViewController.setMediaPlaybackRequiresUserGesture`
 * The following features have been moved to an iOS implementation class. See section
-  `Platform-Specific Features` for details on accessing iOS platform specific features.
+  `Platform-Specific Features` for details on accessing iOS platform-specific features.
   * `WebView.gestureNavigationEnabled` -> `WebKitWebViewController.setAllowsBackForwardNavigationGestures`
   * `WebView.initialMediaPlaybackPolicy` -> `WebKitWebViewControllerCreationParams.mediaTypesRequiringUserAction`
   * `WebView.allowsInlineMediaPlayback` -> `WebKitWebViewControllerCreationParams.allowsInlineMediaPlayback`
+
+<!-- Links -->
+[WebViewController]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewController-class.html
+[WebViewWidget]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewWidget-class.html
+[NavigationDelegate]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/NavigationDelegate-class.html
+[WebViewCookieManager]: https://pub.dev/documentation/webview_flutter/latest/webview_flutter/WebViewCookieManager-class.html

packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart

@@ -12,6 +12,28 @@ import 'webview_controller.dart';
 /// the progress of navigation requests.
 ///
 /// See [WebViewController.setNavigationDelegate].
+///
+/// ## Platform-Specific Features
+/// This class contains an underlying implementation provided by the current
+/// platform. Once a platform implementation is imported, the examples below
+/// can be followed to use features provided by a platform's implementation.
+///
+/// {@macro webview_flutter.NavigationDelegate.fromPlatformCreationParams}
+///
+/// Below is an example of accessing the platform-specific implementation for
+/// iOS and Android:
+///
+/// ```dart
+/// final NavigationDelegate navigationDelegate = NavigationDelegate();
+///
+/// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+///   final WebKitNavigationDelegate webKitDelegate =
+///       navigationDelegate.platform as WebKitNavigationDelegate;
+/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+///   final AndroidNavigationDelegate androidDelegate =
+///       navigationDelegate.platform as AndroidNavigationDelegate;
+/// }
+/// ```
 class NavigationDelegate {
   /// Constructs a [NavigationDelegate].
   NavigationDelegate({
@@ -32,6 +54,33 @@ class NavigationDelegate {
 
   /// Constructs a [NavigationDelegate] from creation params for a specific
   /// platform.
+  ///
+  /// {@template webview_flutter.NavigationDelegate.fromPlatformCreationParams}
+  /// Below is an example of setting platform-specific creation parameters for
+  /// iOS and Android:
+  ///
+  /// ```dart
+  /// PlatformNavigationDelegateCreationParams params =
+  ///     const PlatformNavigationDelegateCreationParams();
+  ///
+  /// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+  ///   params = WebKitNavigationDelegateCreationParams
+  ///       .fromPlatformNavigationDelegateCreationParams(
+  ///     params,
+  ///   );
+  /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+  ///   params = AndroidNavigationDelegateCreationParams
+  ///       .fromPlatformNavigationDelegateCreationParams(
+  ///     params,
+  ///   );
+  /// }
+  ///
+  /// final NavigationDelegate navigationDelegate =
+  ///     NavigationDelegate.fromPlatformCreationParams(
+  ///   params,
+  /// );
+  /// ```
+  /// {@endtemplate}
   NavigationDelegate.fromPlatformCreationParams(
     PlatformNavigationDelegateCreationParams params, {
     FutureOr<NavigationDecision> Function(NavigationRequest request)?

packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart

@@ -10,19 +10,75 @@ import 'package:flutter/material.dart';
 import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
 
 import 'navigation_delegate.dart';
+import 'webview_widget.dart';
 
 /// Controls a WebView provided by the host platform.
 ///
 /// Pass this to a [WebViewWidget] to display the WebView.
+///
+/// A [WebViewController] can only be used by a single [WebViewWidget] at a
+/// time.
+///
+/// ## Platform-Specific Features
+/// This class contains an underlying implementation provided by the current
+/// platform. Once a platform implementation is imported, the examples below
+/// can be followed to use features provided by a platform's implementation.
+///
+/// {@macro webview_flutter.WebViewController.fromPlatformCreationParams}
+///
+/// Below is an example of accessing the platform-specific implementation for
+/// iOS and Android:
+///
+/// ```dart
+/// final WebViewController webViewController = WebViewController();
+///
+/// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+///   final WebKitWebViewController webKitController =
+///       webViewController.platform as WebKitWebViewController;
+/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+///   final AndroidWebViewController androidController =
+///       webViewController.platform as AndroidWebViewController;
+/// }
+/// ```
 class WebViewController {
   /// Constructs a [WebViewController].
+  ///
+  /// See [WebViewController.fromPlatformCreationParams] for setting parameters
+  /// for a specific platform.
   WebViewController()
       : this.fromPlatformCreationParams(
           const PlatformWebViewControllerCreationParams(),
         );
 
   /// Constructs a [WebViewController] from creation params for a specific
   /// platform.
+  ///
+  /// {@template webview_flutter.WebViewCookieManager.fromPlatformCreationParams}
+  /// Below is an example of setting platform-specific creation parameters for
+  /// iOS and Android:
+  ///
+  /// ```dart
+  /// PlatformWebViewControllerCreationParams params =
+  ///     const PlatformWebViewControllerCreationParams();
+  ///
+  /// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+  ///   params = WebKitWebViewControllerCreationParams
+  ///       .fromPlatformWebViewControllerCreationParams(
+  ///     params,
+  ///   );
+  /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+  ///   params = AndroidWebViewControllerCreationParams
+  ///       .fromPlatformWebViewControllerCreationParams(
+  ///     params,
+  ///   );
+  /// }
+  ///
+  /// final WebViewController webViewController =
+  ///     WebViewController.fromPlatformCreationParams(
+  ///   params,
+  /// );
+  /// ```
+  /// {@endtemplate}
   WebViewController.fromPlatformCreationParams(
     PlatformWebViewControllerCreationParams params,
   ) : this.fromPlatform(PlatformWebViewController(params));

packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart

@@ -5,15 +5,67 @@
 import 'package:webview_flutter_platform_interface/webview_flutter_platform_interface.dart';
 
 /// Manages cookies pertaining to all WebViews.
+///
+/// ## Platform-Specific Features
+/// This class contains an underlying implementation provided by the current
+/// platform. Once a platform implementation is imported, the examples below
+/// can be followed to use features provided by a platform's implementation.
+///
+/// {@macro webview_flutter.WebViewCookieManager.fromPlatformCreationParams}
+///
+/// Below is an example of accessing the platform-specific implementation for
+/// iOS and Android:
+///
+/// ```dart
+/// final WebViewCookieManager cookieManager = WebViewCookieManager();
+///
+/// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+///   final WebKitWebViewCookieManager webKitManager =
+///       cookieManager.platform as WebKitWebViewCookieManager;
+/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+///   final AndroidWebViewCookieManager androidManager =
+///       cookieManager.platform as AndroidWebViewCookieManager;
+/// }
+/// ```
 class WebViewCookieManager {
   /// Constructs a [WebViewCookieManager].
+  ///
+  /// See [WebViewCookieManager.fromPlatformCreationParams] for setting
+  /// parameters for a specific platform.
   WebViewCookieManager()
       : this.fromPlatformCreationParams(
           const PlatformWebViewCookieManagerCreationParams(),
         );
 
   /// Constructs a [WebViewCookieManager] from creation params for a specific
   /// platform.
+  ///
+  /// {@template webview_flutter.WebViewCookieManager.fromPlatformCreationParams}
+  /// Below is an example of setting platform-specific creation parameters for
+  /// iOS and Android:
+  ///
+  /// ```dart
+  /// PlatformWebViewCookieManagerCreationParams params =
+  ///     const PlatformWebViewCookieManagerCreationParams();
+  ///
+  /// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+  ///   params = WebKitWebViewCookieManagerCreationParams
+  ///       .fromPlatformWebViewCookieManagerCreationParams(
+  ///     params,
+  ///   );
+  /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+  ///   params = AndroidWebViewCookieManagerCreationParams
+  ///       .fromPlatformWebViewCookieManagerCreationParams(
+  ///     params,
+  ///   );
+  /// }
+  ///
+  /// final WebViewCookieManager webViewCookieManager =
+  ///     WebViewCookieManager.fromPlatformCreationParams(
+  ///   params,
+  /// );
+  /// ```
+  /// {@endtemplate}
   WebViewCookieManager.fromPlatformCreationParams(
     PlatformWebViewCookieManagerCreationParams params,
   ) : this.fromPlatform(PlatformWebViewCookieManager(params));

packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart

@@ -10,8 +10,35 @@ import 'package:webview_flutter_platform_interface/webview_flutter_platform_inte
 import 'webview_controller.dart';
 
 /// Displays a native WebView as a Widget.
+///
+/// ## Platform-Specific Features
+/// This class contains an underlying implementation provided by the current
+/// platform. Once a platform implementation is imported, the examples below
+/// can be followed to use features provided by a platform's implementation.
+///
+/// {@macro webview_flutter.WebViewWidget.fromPlatformCreationParams}
+///
+/// Below is an example of accessing the platform-specific implementation for
+/// iOS and Android:
+///
+/// ```dart
+/// final WebViewController controller = WebViewController();
+///
+/// final WebViewWidget webViewWidget = WebViewWidget(controller: controller);
+///
+/// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+///   final WebKitWebViewWidget webKitWidget =
+///       webViewWidget.platform as WebKitWebViewWidget;
+/// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+///   final AndroidWebViewWidget androidWidget =
+///       webViewWidget.platform as AndroidWebViewWidget;
+/// }
+/// ```
 class WebViewWidget extends StatelessWidget {
   /// Constructs a [WebViewWidget].
+  ///
+  /// See [WebViewWidget.fromPlatformCreationParams] for setting parameters for
+  /// a specific platform.
   WebViewWidget({
     Key? key,
     required WebViewController controller,
@@ -27,8 +54,40 @@ class WebViewWidget extends StatelessWidget {
           ),
         );
 
-  /// Constructs a [WebViewWidget] from creation params for a specific
-  /// platform.
+  /// Constructs a [WebViewWidget] from creation params for a specific platform.
+  ///
+  /// {@template webview_flutter.WebViewWidget.fromPlatformCreationParams}
+  /// Below is an example of setting platform-specific creation parameters for
+  /// iOS and Android:
+  ///
+  /// ```dart
+  /// final WebViewController controller = WebViewController();
+  ///
+  /// PlatformWebViewWidgetCreationParams params =
+  ///     PlatformWebViewWidgetCreationParams(
+  ///   controller: controller.platform,
+  ///   layoutDirection: TextDirection.ltr,
+  ///   gestureRecognizers: const <Factory<OneSequenceGestureRecognizer>>{},
+  /// );
+  ///
+  /// if (WebViewPlatform.instance is WebKitWebViewPlatform) {
+  ///   params = WebKitWebViewWidgetCreationParams
+  ///       .fromPlatformWebViewWidgetCreationParams(
+  ///     params,
+  ///   );
+  /// } else if (WebViewPlatform.instance is AndroidWebViewPlatform) {
+  ///   params = AndroidWebViewWidgetCreationParams
+  ///       .fromPlatformWebViewWidgetCreationParams(
+  ///     params,
+  ///   );
+  /// }
+  ///
+  /// final WebViewWidget webViewWidget =
+  ///     WebViewWidget.fromPlatformCreationParams(
+  ///   params: params,
+  /// );
+  /// ```
+  /// {@endtemplate}
   WebViewWidget.fromPlatformCreationParams({
     Key? key,
     required PlatformWebViewWidgetCreationParams params,

packages/webview_flutter/webview_flutter/pubspec.yaml

@@ -2,7 +2,7 @@ name: webview_flutter
 description: A Flutter plugin that provides a WebView widget on Android and iOS.
 repository: https://github.com/flutter/plugins/tree/main/packages/webview_flutter/webview_flutter
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+webview%22
-version: 4.0.3
+version: 4.0.4
 
 environment:
   sdk: ">=2.17.0 <3.0.0"