[release/10.0.1xx-preview7] [HybridWebView] Add WebViewInitializing and WebViewInitialized Events

src/Controls/samples/Controls.Sample/Maui.Controls.Sample.csproj

@@ -78,7 +78,6 @@
   <ItemGroup>
     <EmbeddedResource Include="Resources\Embedded\*" />
     <MauiAsset Include="Resources\Raw\**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)" />
-    <MauiAsset Include="..\..\..\Core\src\Handlers\HybridWebView\HybridWebView.js" LogicalName="HybridSamplePage\scripts\HybridWebView.js" />
     <MauiImage Include="Resources\Images\*" />
     <MauiImage Update="Resources\Images\*.gif" Resize="false" />
     <MauiIcon Include="Resources\AppIcons\appicon.svg" ForegroundFile="Resources\AppIcons\appicon_foreground.svg" />

src/Controls/src/Core/HybridWebView/HybridWebView.cs

@@ -66,6 +66,32 @@ void IHybridWebView.RawMessageReceived(string rawMessage)
 		/// </summary>
 		public event EventHandler<HybridWebViewRawMessageReceivedEventArgs>? RawMessageReceived;
 
+		/// <inheritdoc/>
+		void IInitializationAwareWebView.WebViewInitializationStarted(WebViewInitializationStartedEventArgs args)
+		{
+			var platformArgs = new PlatformWebViewInitializingEventArgs(args);
+			var e = new WebViewInitializingEventArgs(platformArgs);
+			WebViewInitializing?.Invoke(this, e);
+		}
+
+		/// <summary>
+		/// Raised when the web view is initializing. This event allows the application to perform additional configuration.
+		/// </summary>
+		public event EventHandler<WebViewInitializingEventArgs>? WebViewInitializing;
+
+		/// <inheritdoc/>
+		void IInitializationAwareWebView.WebViewInitializationCompleted(WebViewInitializationCompletedEventArgs args)
+		{
+			var platformArgs = new PlatformWebViewInitializedEventArgs(args);
+			var e = new WebViewInitializedEventArgs(platformArgs);
+			WebViewInitialized?.Invoke(this, e);
+		}
+
+		/// <summary>
+		/// Raised when the web view has been initialized.
+		/// </summary>
+		public event EventHandler<WebViewInitializedEventArgs>? WebViewInitialized;
+
 		/// <inheritdoc/>
 		bool IWebRequestInterceptingWebView.WebResourceRequested(WebResourceRequestedEventArgs args)
 		{

src/Controls/src/Core/InitializationAwareWebView/PlatformWebViewInitializedEventArgs.cs

@@ -0,0 +1,119 @@
+#if WINDOWS
+using Microsoft.Web.WebView2.Core;
+#elif IOS || MACCATALYST
+using WebKit;
+#elif ANDROID
+using Android.Webkit;
+#endif
+
+namespace Microsoft.Maui.Controls;
+
+/// <summary>
+/// Provides platform-specific information about the <see cref="WebViewInitializedEventArgs"/> event.
+/// </summary>
+public class PlatformWebViewInitializedEventArgs
+{
+#if IOS || MACCATALYST
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="WebViewInitializationCompletedEventArgs"/> class.
+	/// </summary>
+	/// <param name="sender">The native view that is being initialized.</param>
+	/// <param name="configuration">The settings for the web view, which can be used to configure various aspects of the web view.</param>
+	internal PlatformWebViewInitializedEventArgs(WKWebView sender, WKWebViewConfiguration configuration)
+	{	
+		Sender = sender;
+		Configuration = configuration;
+	}
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="PlatformWebViewInitializedEventArgs"/> class.
+	/// </summary>
+	/// <param name="args">The event arguments containing the native view and configuration.</param>
+	internal PlatformWebViewInitializedEventArgs(WebViewInitializationCompletedEventArgs args)
+		: this(args.Sender, args.Configuration)
+	{
+	}
+
+	/// <summary>
+	/// Gets the native view attached to the event.
+	/// </summary>
+	public WKWebView Sender { get; }
+
+	/// <summary>
+	/// Gets or sets the settings attached to the web view.
+	/// </summary>
+	public WKWebViewConfiguration Configuration { get; }
+
+#elif ANDROID
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="WebViewInitializationCompletedEventArgs"/> class.
+	/// </summary>
+	/// <param name="sender">The native view that is being initialized.</param>
+	/// <param name="settings">The settings for the web view, which can be used to configure various aspects of the web view.</param>
+	internal PlatformWebViewInitializedEventArgs(global::Android.Webkit.WebView sender, WebSettings settings)
+	{
+		Sender = sender;
+		Settings = settings;
+	}
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="PlatformWebViewInitializedEventArgs"/> class.
+	/// </summary>
+	/// <param name="args">The event arguments containing the native view and configuration.</param>
+	internal PlatformWebViewInitializedEventArgs(WebViewInitializationCompletedEventArgs args)
+		: this(args.Sender, args.Settings)
+	{
+	}
+
+	/// <summary>
+	/// Gets the native view attached to the event.
+	/// </summary>
+	public global::Android.Webkit.WebView Sender { get; }
+
+	/// <summary>
+	/// Gets or sets the settings attached to the web view.
+	/// </summary>
+	public WebSettings Settings { get; }
+
+#elif WINDOWS
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="WebViewInitializationCompletedEventArgs"/> class.
+	/// </summary>
+	/// <param name="sender">The native view that is being initialized.</param>
+	/// <param name="settings">The settings for the web view, which can be used to configure various aspects of the web view.</param>
+	internal PlatformWebViewInitializedEventArgs(CoreWebView2 sender, CoreWebView2Settings settings)
+	{
+		Sender = sender;
+		Settings = settings;
+	}
+
+	/// <summary>
+	/// Initializes a new instance of the <see cref="PlatformWebViewInitializedEventArgs"/> class.
+	/// </summary>
+	/// <param name="args">The event arguments containing the native view and configuration.</param>
+	internal PlatformWebViewInitializedEventArgs(WebViewInitializationCompletedEventArgs args)
+		: this(args.Sender, args.Settings)
+	{
+	}
+
+	/// <summary>
+	/// Gets the native view attached to the event.
+	/// </summary>
+	public CoreWebView2 Sender { get; }
+
+	/// <summary>
+	/// Gets or sets the settings attached to the web view.
+	/// </summary>
+	public CoreWebView2Settings Settings { get; }
+
+#else
+
+	internal PlatformWebViewInitializedEventArgs(WebViewInitializationCompletedEventArgs args)
+	{
+	}
+
+#endif
+}

src/Controls/src/Core/InitializationAwareWebView/PlatformWebViewInitializingEventArgs.cs

@@ -0,0 +1,131 @@
+#if IOS || MACCATALYST
+using WebKit;
+#elif ANDROID
+using Android.Webkit;
+#elif WINDOWS
+using Microsoft.Web.WebView2.Core;
+#endif
+
+namespace Microsoft.Maui.Controls;
+
+/// <summary>
+/// Provides platform-specific information about the <see cref="WebViewInitializingEventArgs"/> event.
+/// </summary>
+public class PlatformWebViewInitializingEventArgs
+{
+	readonly WebViewInitializationStartedEventArgs _coreArgs;
+
+	internal PlatformWebViewInitializingEventArgs(WebViewInitializationStartedEventArgs args)
+	{
+		_coreArgs = args;
+	}
+
+#if WINDOWS
+
+	/// <summary>
+	/// Gets or sets the relative path to the folder that contains a custom
+	/// version of WebView2 Runtime.
+	/// </summary>
+	/// <remarks>
+	/// To use a fixed version of the WebView2 Runtime, set this property to 
+	/// the folder path that contains the fixed version of the WebView2 Runtime. 
+	/// </remarks>
+	public string? BrowserExecutableFolder
+	{
+		get => _coreArgs.BrowserExecutableFolder;
+		set => _coreArgs.BrowserExecutableFolder = value;
+	}
+
+	/// <summary>
+	/// Gets or sets the user data folder location for WebView2.
+	/// </summary>
+	/// <remarks>
+	/// The default user data folder {Executable File Name}.WebView2 is created
+	/// in the same directory next to the compiled code for the app.
+	/// WebView2 creation fails if the compiled code is running in a directory
+	/// in which the process does not have permission to create a new directory.
+	/// The app is responsible to clean up the associated user data folder
+	/// when it is done.
+	/// </remarks>
+	public string? UserDataFolder
+	{
+		get => _coreArgs.UserDataFolder;
+		set => _coreArgs.UserDataFolder = value;
+	}
+
+	/// <summary>
+	/// Gets or sets the options used to create WebView2 Environment.
+	/// </summary>
+	/// <remarks>
+	/// As a browser process may be shared among WebViews, WebView creation fails
+	/// if the specified options does not match the options of the WebViews
+	/// that are currently running in the shared browser process.
+	/// </remarks>
+	public CoreWebView2EnvironmentOptions? EnvironmentOptions
+	{
+		get => _coreArgs.EnvironmentOptions;
+		set => _coreArgs.EnvironmentOptions = value;
+	}
+
+	/// <summary>
+	/// Gets or sets whether the WebView2 controller is in private mode.
+	/// </summary>
+	public bool IsInPrivateModeEnabled
+	{
+		get => _coreArgs.IsInPrivateModeEnabled;
+		set => _coreArgs.IsInPrivateModeEnabled = value;
+	}
+
+	/// <summary>
+	/// Gets or sets the name of the controller profile.
+	/// </summary>
+	/// <remarks>
+	/// Profile names are only allowed to contain the following ASCII characters:
+	/// * alphabet characters: a-z and A-Z
+	/// * digit characters: 0-9
+	/// * and '#', '@', '$', '(', ')', '+', '-', '_', '~', '.', ' ' (space).
+	/// It has a maximum length of 64 characters excluding the null-terminator.
+	/// It is ASCII case insensitive.
+	/// </remarks>
+	public string? ProfileName
+	{
+		get => _coreArgs.ProfileName;
+		set => _coreArgs.ProfileName = value;
+	}
+
+	/// <summary>
+	/// Gets or sets the controller's default script locale.
+	/// </summary>
+	/// <remarks>
+	/// This property sets the default locale for all Intl JavaScript APIs and other JavaScript APIs that
+	/// depend on it, namely Intl.DateTimeFormat() which affects string formatting like in the time/date
+	/// formats. The intended locale value is in the format of BCP 47 Language Tags. 
+	/// More information can be found from https://www.ietf.org/rfc/bcp/bcp47.html. 
+	/// The default value for ScriptLocale will be depend on the WebView2 language and OS region.
+	/// If the language portions of the WebView2 language and OS region match, then it will use the OS region.
+	/// Otherwise, it will use the WebView2 language.
+	/// </remarks>
+	public string? ScriptLocale
+	{
+		get => _coreArgs.ScriptLocale;
+		set => _coreArgs.ScriptLocale = value;
+	}
+
+#elif IOS || MACCATALYST
+
+	/// <summary>
+	/// Gets or sets the configuration to be used in the construction of the WKWebView instance.
+	/// </summary>
+	public WKWebViewConfiguration Configuration => _coreArgs.Configuration;
+
+#elif ANDROID
+
+	/// <summary>
+	/// Gets the platform-specific settings for the WebView.
+	/// </summary>
+	public WebSettings Settings => _coreArgs.Settings;
+
+#else
+
+#endif
+}

src/Controls/src/Core/InitializationAwareWebView/WebViewInitializedEventArgs.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace Microsoft.Maui.Controls;
+
+/// <summary>
+/// Event arguments for the <see cref="HybridWebView.WebViewInitialized"/> event.
+/// </summary>
+public class WebViewInitializedEventArgs : EventArgs
+{
+	/// <summary>
+	/// Initializes a new instance of the <see cref="WebViewInitializedEventArgs"/> class
+	/// with the specified platform-specific arguments.
+	/// </summary>
+	/// <param name="platformArgs">The platform-specific event arguments.</param>
+	public WebViewInitializedEventArgs(PlatformWebViewInitializedEventArgs platformArgs)
+	{
+		PlatformArgs = platformArgs;
+	}
+
+	/// <summary>
+	/// Gets the platform-specific event arguments.
+	/// </summary>
+	public PlatformWebViewInitializedEventArgs? PlatformArgs { get; }
+}

src/Controls/src/Core/InitializationAwareWebView/WebViewInitializingEventArgs.cs

@@ -0,0 +1,24 @@
+using System;
+
+namespace Microsoft.Maui.Controls;
+
+/// <summary>
+/// Event arguments for the <see cref="HybridWebView.WebViewInitializing"/> event.
+/// </summary>
+public class WebViewInitializingEventArgs : EventArgs
+{
+	/// <summary>
+	/// Initializes a new instance of the <see cref="WebViewInitializingEventArgs"/> class
+	/// with the specified platform-specific arguments.
+	/// </summary>
+	/// <param name="platformArgs">The platform-specific event arguments.</param>
+	public WebViewInitializingEventArgs(PlatformWebViewInitializingEventArgs platformArgs)
+	{
+		PlatformArgs = platformArgs;
+	}
+
+	/// <summary>
+	/// Gets the platform-specific event arguments.
+	/// </summary>
+	public PlatformWebViewInitializingEventArgs? PlatformArgs { get; }
+}

src/Controls/src/Core/PublicAPI/net-android/PublicAPI.Unshipped.txt

@@ -76,6 +76,8 @@ Microsoft.Maui.Controls.Handlers.TabbedPageManager.NotifyDataSetChanged() -> voi
 ~Microsoft.Maui.Controls.Handlers.TabbedPageManager.previousPage -> Microsoft.Maui.Controls.Page
 Microsoft.Maui.Controls.HybridWebView.InvokeJavaScriptAsync(string! methodName, object?[]? paramValues = null, System.Text.Json.Serialization.Metadata.JsonTypeInfo?[]? paramJsonTypeInfos = null) -> System.Threading.Tasks.Task!
 Microsoft.Maui.Controls.HybridWebView.WebResourceRequested -> System.EventHandler<Microsoft.Maui.Controls.WebViewWebResourceRequestedEventArgs!>?
+Microsoft.Maui.Controls.HybridWebView.WebViewInitialized -> System.EventHandler<Microsoft.Maui.Controls.WebViewInitializedEventArgs!>?
+Microsoft.Maui.Controls.HybridWebView.WebViewInitializing -> System.EventHandler<Microsoft.Maui.Controls.WebViewInitializingEventArgs!>?
 Microsoft.Maui.Controls.ICornerElement
 Microsoft.Maui.Controls.ICornerElement.CornerRadius.get -> Microsoft.Maui.CornerRadius
 Microsoft.Maui.Controls.IExtendedTypeConverter.ConvertFromInvariantString(string! value, System.IServiceProvider! serviceProvider) -> object?
@@ -141,6 +143,11 @@ Microsoft.Maui.Controls.PickerClosedEventArgs.PickerClosedEventArgs() -> void
 Microsoft.Maui.Controls.PickerOpenedEventArgs
 Microsoft.Maui.Controls.PickerOpenedEventArgs.PickerOpenedEventArgs() -> void
 Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific.UIModalPresentationStyle.Popover = 5 -> Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific.UIModalPresentationStyle
+Microsoft.Maui.Controls.PlatformWebViewInitializedEventArgs
+Microsoft.Maui.Controls.PlatformWebViewInitializedEventArgs.Sender.get -> Android.Webkit.WebView!
+Microsoft.Maui.Controls.PlatformWebViewInitializedEventArgs.Settings.get -> Android.Webkit.WebSettings!
+Microsoft.Maui.Controls.PlatformWebViewInitializingEventArgs
+Microsoft.Maui.Controls.PlatformWebViewInitializingEventArgs.Settings.get -> Android.Webkit.WebSettings!
 Microsoft.Maui.Controls.PlatformWebViewWebResourceRequestedEventArgs
 Microsoft.Maui.Controls.PlatformWebViewWebResourceRequestedEventArgs.Request.get -> Android.Webkit.IWebResourceRequest!
 Microsoft.Maui.Controls.PlatformWebViewWebResourceRequestedEventArgs.Response.get -> Android.Webkit.WebResourceResponse?
@@ -194,6 +201,12 @@ Microsoft.Maui.Controls.TimePickerClosedEventArgs
 Microsoft.Maui.Controls.TimePickerClosedEventArgs.TimePickerClosedEventArgs() -> void
 Microsoft.Maui.Controls.TimePickerOpenedEventArgs
 Microsoft.Maui.Controls.TimePickerOpenedEventArgs.TimePickerOpenedEventArgs() -> void
+Microsoft.Maui.Controls.WebViewInitializedEventArgs
+Microsoft.Maui.Controls.WebViewInitializedEventArgs.PlatformArgs.get -> Microsoft.Maui.Controls.PlatformWebViewInitializedEventArgs?
+Microsoft.Maui.Controls.WebViewInitializedEventArgs.WebViewInitializedEventArgs(Microsoft.Maui.Controls.PlatformWebViewInitializedEventArgs! platformArgs) -> void
+Microsoft.Maui.Controls.WebViewInitializingEventArgs
+Microsoft.Maui.Controls.WebViewInitializingEventArgs.PlatformArgs.get -> Microsoft.Maui.Controls.PlatformWebViewInitializingEventArgs?
+Microsoft.Maui.Controls.WebViewInitializingEventArgs.WebViewInitializingEventArgs(Microsoft.Maui.Controls.PlatformWebViewInitializingEventArgs! platformArgs) -> void
 Microsoft.Maui.Controls.WebViewWebResourceRequestedEventArgs
 Microsoft.Maui.Controls.WebViewWebResourceRequestedEventArgs.Handled.get -> bool
 Microsoft.Maui.Controls.WebViewWebResourceRequestedEventArgs.Handled.set -> void