From bad09b9183e0f80b34f473f6cb8d29e0ff07ca20 Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Wed, 30 Oct 2024 13:51:55 -0700 Subject: [PATCH 1/6] Create CoreWebView2ControllerOptions.DefaultBackgroundColor.md Update to address feedback from review comments --- ...ontrollerOptions.DefaultBackgroundColor.md | 124 ++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md new file mode 100644 index 00000000..00fa26d5 --- /dev/null +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -0,0 +1,124 @@ +CoreWebView2ControllerOptions.DefaultBackgroundColor +=== +# Background + +Previously, there was a fix to address an issue where the background color controller property +was applied too late, causing a disruptive white flash during the WebView2 loading process. + +This fix required using an environment variable. However, this workaround was not meant to be +a long-term solution. Therefore, we need to add this setting to `ICoreWebView2ControllerOptions` +to apply the color early in the loading process. + +# Description + +This interface extends the `ICoreWebView2ControllerOptions` to expose the `DefaultBackgroundColor` +property as an option. +The `CoreWebView2ControllerOptions.DefaultBackgroundColor` API allows users to set the +`DefaultBackgroundColor` property at initialization. + +This is useful when setting it using the existing [`CoreWebView2Controller.DefaultBackgroundColor API`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.web.webview2.core.corewebview2controller.defaultbackgroundcolor?view=webview2-dotnet-1.0.2792.45) +applies the color too late. + + + +# Examples + +## Win32 C++ +```cpp + HRESULT AppWindow::CreateControllerWithOptions() +{ + wil::com_ptr options; + HRESULT hr = m_environment->CreateCoreWebView2ControllerOptions(&options); + + wil::com_ptr stagingOptions; + auto result = options->QueryInterface(IID_PPV_ARGS(&stagingOptions)); + + if (SUCCEEDED(result)) + { + COREWEBVIEW2_COLOR wvColor{255, 223, 225, 225}; + stagingOptions->put_DefaultBackgroundColor(wvColor); + + m_environment->CreateCoreWebView2Controller( + m_mainWindow, options.Get(), + Callback( + this, &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()); + } + +} +``` + + + +## C# +```c# +public MainWindow() +{ +InitializeComponent(); +SetDefaultBackgroundColor(); +} + +private void SetDefaultBackgroundColor() +{ + CoreWebView2ControllerOptions options = WebView2.CoreWebView2.Environment.CreateCoreWebView2ControllerOptions(); + options.DefaultBackgroundColor = Color.FromArgb(0, 0, 255); + WebView2.CoreWebView2.Environment.CreateCoreWebView2ControllerAsync(parentHwnd, options); +} + +``` + + + +# API Details + +## Win32 C++ + ```cpp +/// This interface extends the ICoreWebView2ControllerOptions interface to expose the DefaultBackgroundColor property. +/// It is encouraged to transition away from the environment variable and use this API solution to apply the property. + +[uuid(df9cb70b-8d87-5bca-ae4b-6f23285e8d94), object, pointer_default(unique)] +interface ICoreWebView2ControllerOptions4 : IUnknown { + + /// This API allows users to initialize the `DefaultBackgroundColor` early, + /// preventing a white flash that can happen while WebView2 is loading when + /// the background color is set to something other than white. With early + /// initialization, the color remains consistent from the start. After + /// initialization, `ICoreWebView2Controller2::get_DefaultBackgroundColor` + /// will return the value set using this API. + /// + /// The `DefaultBackgroundColor` is the color that renders underneath all web + /// content. This means WebView renders this color when there is no web + /// content loaded. It is important to note that the default color is white. + /// Currently this API only supports opaque colors and transparency. It will + /// fail for colors with alpha values that don't equal 0 or 255 ie. translucent + /// colors are not supported. It also does not support transparency on Windows 7. + /// On Windows 7, setting DefaultBackgroundColor to a Color with an Alpha value + /// other than 255 will result in failure. On any OS above Win7, choosing a + /// transparent color will result in showing hosting app content. This means + /// webpages without explicit background properties defined will render web + /// content over hosting app content. + + [propget] HRESULT DefaultBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); + [propput] HRESULT DefaultBackgroundColor([in] COREWEBVIEW2_COLOR value); + +} +``` + + + +## .NET WinRT + +```cpp +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2ControllerOptions + { + // ... + [interface_name("ICoreWebView2ControllerOptions4")] + { + Windows.UI.Color DefaultBackgroundColor { get; set; }; + } + } + } +} + +``` From 614e9de8d88ed051d700e5e16602bcbefec2a87d Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Tue, 5 Nov 2024 21:54:04 +0000 Subject: [PATCH 2/6] Update to adress latest comments --- ...ontrollerOptions.DefaultBackgroundColor.md | 44 +++++++++++-------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md index 00fa26d5..4a5ef4b7 100644 --- a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -27,23 +27,31 @@ applies the color too late. ```cpp  HRESULT AppWindow::CreateControllerWithOptions() { - wil::com_ptr options; + wil::com_ptr options4; HRESULT hr = m_environment->CreateCoreWebView2ControllerOptions(&options); - wil::com_ptr stagingOptions; + if (hr == E_INVALIDARG) + { + return S_OK; + } + + wil::com_ptr options4; auto result = options->QueryInterface(IID_PPV_ARGS(&stagingOptions)); if (SUCCEEDED(result)) { COREWEBVIEW2_COLOR wvColor{255, 223, 225, 225}; stagingOptions->put_DefaultBackgroundColor(wvColor); - - m_environment->CreateCoreWebView2Controller( - m_mainWindow, options.Get(), - Callback( - this, &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()); } + m_environment->CreateCoreWebView2Controller( + m_mainWindow, + SUCCEEDED(result) ? stagingOptions.Get() : options.Get(), + Callback( + this, &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()); + + return S_OK; + } ``` @@ -53,15 +61,16 @@ applies the color too late. ```c# public MainWindow() { -InitializeComponent(); -SetDefaultBackgroundColor(); + InitializeComponent(); + SetDefaultBackgroundColor(); } private void SetDefaultBackgroundColor() { - CoreWebView2ControllerOptions options = WebView2.CoreWebView2.Environment.CreateCoreWebView2ControllerOptions(); + CoreWebView2Environment environment = CoreWebView2Environment.CreateAsync(); + CoreWebView2ControllerOptions options = environment.CreateCoreWebView2ControllerOptions(); options.DefaultBackgroundColor = Color.FromArgb(0, 0, 255); - WebView2.CoreWebView2.Environment.CreateCoreWebView2ControllerAsync(parentHwnd, options); + WebView2.EnsureCoreWebView2Async(environment, options); } ``` @@ -87,15 +96,14 @@ interface ICoreWebView2ControllerOptions4 : IUnknown { /// /// The `DefaultBackgroundColor` is the color that renders underneath all web /// content. This means WebView renders this color when there is no web - /// content loaded. It is important to note that the default color is white. + /// content loaded. When no background color is defined in WebView2, it uses + /// the `DefaultBackgroundColor` property to render the background. + /// By default, this color is set to white. + /// /// Currently this API only supports opaque colors and transparency. It will /// fail for colors with alpha values that don't equal 0 or 255 ie. translucent - /// colors are not supported. It also does not support transparency on Windows 7. - /// On Windows 7, setting DefaultBackgroundColor to a Color with an Alpha value - /// other than 255 will result in failure. On any OS above Win7, choosing a - /// transparent color will result in showing hosting app content. This means - /// webpages without explicit background properties defined will render web - /// content over hosting app content. + /// colors are not supported. When WebView2 is set to have a transparent background, + /// it renders the content of the parent window behind it. [propget] HRESULT DefaultBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); [propput] HRESULT DefaultBackgroundColor([in] COREWEBVIEW2_COLOR value); From 462d39d6954234c91d75de82202334e8f107b10b Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Tue, 5 Nov 2024 21:54:04 +0000 Subject: [PATCH 3/6] Update to adress latest comments --- ...View2ControllerOptions.DefaultBackgroundColor.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md index 4a5ef4b7..a37837e5 100644 --- a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -27,26 +27,27 @@ applies the color too late. ```cpp  HRESULT AppWindow::CreateControllerWithOptions() { - wil::com_ptr options4; + wil::com_ptr options; HRESULT hr = m_environment->CreateCoreWebView2ControllerOptions(&options); if (hr == E_INVALIDARG) { + ShowFailure(hr, L"Invalid profile name."); return S_OK; } wil::com_ptr options4; - auto result = options->QueryInterface(IID_PPV_ARGS(&stagingOptions)); + auto result = options->QueryInterface(IID_PPV_ARGS(&options4)); if (SUCCEEDED(result)) { - COREWEBVIEW2_COLOR wvColor{255, 223, 225, 225}; - stagingOptions->put_DefaultBackgroundColor(wvColor); + COREWEBVIEW2_COLOR wvColor{255, 85, 0, 225}; + options4->put_DefaultBackgroundColor(wvColor); } m_environment->CreateCoreWebView2Controller( m_mainWindow, - SUCCEEDED(result) ? stagingOptions.Get() : options.Get(), + SUCCEEDED(result) ? options4.Get() : options.Get(), Callback( this, &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()); @@ -69,7 +70,7 @@ private void SetDefaultBackgroundColor() { CoreWebView2Environment environment = CoreWebView2Environment.CreateAsync(); CoreWebView2ControllerOptions options = environment.CreateCoreWebView2ControllerOptions(); - options.DefaultBackgroundColor = Color.FromArgb(0, 0, 255); + options.DefaultBackgroundColor = Color.FromArgb(255, 85, 0, 255); WebView2.EnsureCoreWebView2Async(environment, options); } From c9b0f68f9e8264ffc693df4d4c395504d9327bfe Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Thu, 12 Dec 2024 13:28:24 -0800 Subject: [PATCH 4/6] Update specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md Co-authored-by: Raymond Chen --- specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md index a37837e5..75cf6387 100644 --- a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -86,7 +86,7 @@ private void SetDefaultBackgroundColor() /// It is encouraged to transition away from the environment variable and use this API solution to apply the property. [uuid(df9cb70b-8d87-5bca-ae4b-6f23285e8d94), object, pointer_default(unique)] -interface ICoreWebView2ControllerOptions4 : IUnknown { +interface ICoreWebView2ControllerOptions4 : ICoreWebView2ControllerOptions3 { /// This API allows users to initialize the `DefaultBackgroundColor` early, /// preventing a white flash that can happen while WebView2 is loading when From 9e780e0bea6107fee70a166abe40f8b3b6a5c817 Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Thu, 12 Dec 2024 13:31:00 -0800 Subject: [PATCH 5/6] Update specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md Co-authored-by: Raymond Chen --- specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md index 75cf6387..29e541f4 100644 --- a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -45,7 +45,7 @@ applies the color too late. options4->put_DefaultBackgroundColor(wvColor); } - m_environment->CreateCoreWebView2Controller( + m_environment->CreateCoreWebView2ControllerWithOptions( m_mainWindow, SUCCEEDED(result) ? options4.Get() : options.Get(), Callback( From 0105051c7c650ab16b5e637073de60bc480a8408 Mon Sep 17 00:00:00 2001 From: Citlalli Zarate Date: Tue, 17 Dec 2024 17:44:46 +0000 Subject: [PATCH 6/6] Update to reflect feedback specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md --- ...ontrollerOptions.DefaultBackgroundColor.md | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md index 29e541f4..b8554a45 100644 --- a/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md +++ b/specs/CoreWebView2ControllerOptions.DefaultBackgroundColor.md @@ -47,7 +47,7 @@ applies the color too late. m_environment->CreateCoreWebView2ControllerWithOptions( m_mainWindow, - SUCCEEDED(result) ? options4.Get() : options.Get(), + options.Get(), Callback( this, &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()); @@ -66,12 +66,14 @@ public MainWindow() SetDefaultBackgroundColor(); } -private void SetDefaultBackgroundColor() +private async Task +SetDefaultBackgroundColor() { - CoreWebView2Environment environment = CoreWebView2Environment.CreateAsync(); + CoreWebView2Environment environment = await + CoreWebView2Environment.CreateAsync(); CoreWebView2ControllerOptions options = environment.CreateCoreWebView2ControllerOptions(); options.DefaultBackgroundColor = Color.FromArgb(255, 85, 0, 255); - WebView2.EnsureCoreWebView2Async(environment, options); + await WebView2.EnsureCoreWebView2Async(environment, options); } ``` @@ -82,18 +84,19 @@ private void SetDefaultBackgroundColor() ## Win32 C++ ```cpp -/// This interface extends the ICoreWebView2ControllerOptions interface to expose the DefaultBackgroundColor property. -/// It is encouraged to transition away from the environment variable and use this API solution to apply the property. +/// This interface extends the ICoreWebView2ControllerOptions interface to expose +/// DefaultBackgroundColor property. It is encouraged to transition away from the +/// environment variable and use this API solution to apply the property. [uuid(df9cb70b-8d87-5bca-ae4b-6f23285e8d94), object, pointer_default(unique)] interface ICoreWebView2ControllerOptions4 : ICoreWebView2ControllerOptions3 { /// This API allows users to initialize the `DefaultBackgroundColor` early, - /// preventing a white flash that can happen while WebView2 is loading when + /// preventing a white flash that can occur while WebView2 is loading when /// the background color is set to something other than white. With early /// initialization, the color remains consistent from the start. After /// initialization, `ICoreWebView2Controller2::get_DefaultBackgroundColor` - /// will return the value set using this API. + /// will return the value set using this API. /// /// The `DefaultBackgroundColor` is the color that renders underneath all web /// content. This means WebView renders this color when there is no web @@ -101,10 +104,10 @@ interface ICoreWebView2ControllerOptions4 : ICoreWebView2ControllerOptions3 { /// the `DefaultBackgroundColor` property to render the background. /// By default, this color is set to white. /// - /// Currently this API only supports opaque colors and transparency. It will - /// fail for colors with alpha values that don't equal 0 or 255 ie. translucent - /// colors are not supported. When WebView2 is set to have a transparent background, - /// it renders the content of the parent window behind it. + /// Currently, this API only supports opaque colors and full transparency. It will + /// fail for colors with alpha values that don't equal 0 or 255. + /// When WebView2 is set to be fully transparent, it does not render a background, + /// allowing the content from windows behind it to be visible. [propget] HRESULT DefaultBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); [propput] HRESULT DefaultBackgroundColor([in] COREWEBVIEW2_COLOR value);