[webview_flutter] Adds examples of accessing platform-specific features for each class (#7089)
* start
* more docs and version bump
* fix main
diff --git a/packages/webview_flutter/webview_flutter/CHANGELOG.md b/packages/webview_flutter/webview_flutter/CHANGELOG.md
index 6d2e860..84f8907 100644
--- a/packages/webview_flutter/webview_flutter/CHANGELOG.md
+++ b/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.
diff --git a/packages/webview_flutter/webview_flutter/README.md b/packages/webview_flutter/webview_flutter/README.md
index 98f7b66..b30b8bc 100644
--- a/packages/webview_flutter/webview_flutter/README.md
+++ b/packages/webview_flutter/webview_flutter/README.md
@@ -99,7 +99,7 @@
```
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 @@
* `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
\ No newline at end of file
diff --git a/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart b/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart
index 0651ad4..3237fa4 100644
--- a/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart
+++ b/packages/webview_flutter/webview_flutter/lib/src/navigation_delegate.dart
@@ -12,6 +12,28 @@
/// 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 @@
/// 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)?
diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart
index d632d1e..a112f15 100644
--- a/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart
+++ b/packages/webview_flutter/webview_flutter/lib/src/webview_controller.dart
@@ -10,12 +10,41 @@
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(),
@@ -23,6 +52,33 @@
/// 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));
diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart
index bffa1b5..353d755 100644
--- a/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart
+++ b/packages/webview_flutter/webview_flutter/lib/src/webview_cookie_manager.dart
@@ -5,8 +5,33 @@
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(),
@@ -14,6 +39,33 @@
/// 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));
diff --git a/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart b/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart
index b318011..440d0f6 100644
--- a/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart
+++ b/packages/webview_flutter/webview_flutter/lib/src/webview_widget.dart
@@ -10,8 +10,35 @@
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 @@
),
);
- /// 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,
diff --git a/packages/webview_flutter/webview_flutter/pubspec.yaml b/packages/webview_flutter/webview_flutter/pubspec.yaml
index a494f9e..5cef1a7 100644
--- a/packages/webview_flutter/webview_flutter/pubspec.yaml
+++ b/packages/webview_flutter/webview_flutter/pubspec.yaml
@@ -2,7 +2,7 @@
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"
