From d3957302376a42927a98c6ba040e81eb580f0a66 Mon Sep 17 00:00:00 2001 From: Tochukwu Ibe-Ekeocha Date: Tue, 4 Jun 2024 14:34:51 -0700 Subject: [PATCH] Included a new API spec for Webview2 Window Controls Overlay --- specs/IsWindowControlsOverlayEnabled.md | 155 ++++++++++++++++++++++++ 1 file changed, 155 insertions(+) diff --git a/specs/IsWindowControlsOverlayEnabled.md b/specs/IsWindowControlsOverlayEnabled.md index 8b1378917..eb1eff6fb 100644 --- a/specs/IsWindowControlsOverlayEnabled.md +++ b/specs/IsWindowControlsOverlayEnabled.md @@ -1 +1,156 @@ +WebView2 Window Controls +=== +# Background +The goal of this API is to provide devs with a cleaner way to build apps where +the entire Window UI is rendered by WebView2. Till now, it hasn't been possible +for the window/caption control buttons (minimize, maximize, restore, close) to +be rendered and controlled by the browser process. This API allows devs to tell +WebView2 that it should render its own window control buttons. + +# Description +`IsWindowControlsOverlayEnabled` defaults to `FALSE`. Disabling/Enabling +`IsWindowControlsOverlayEnabled` takes effect after the next navigation. + +# Examples + +## Win32 C++ +```cpp +void AppWindow::InitializeWebView() +{ + +CreateCoreWebView2EnvironmentWithOptions( + browserExecutableFolder, + userDataFolder, + corewebview2environmentoptions, + Callback( + this, + [this](HRESULT result, ICoreWebView2Environment* environment) -> { + CHECK_FAILURE(hr); + + CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller( + mainwindowhwnd, + Callback( + this, + &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get())); + }).Get()); +} + +HRESULT AppWindow::OnCreateCoreWebView2ControllerCompleted( + HRESULT result, ICoreWebView2Controller* controller) +{ + CHECK_FAILURE(hr); + + wil::com_ptr coreWebView2; + CHECK_FAILURE(controller->get_CoreWebView2(&coreWebView2)); + + wil::com_ptr m_settings; + CHECK_FAILURE(coreWebView2->get_Settings(&m_settings)); + + wil::com_ptr coreWebView2Settings12; + coreWebView2Settings12 = m_settings.try_query(); + CHECK_FEATURE_RETURN(coreWebView2Settings12); + CHECK_FAILURE(coreWebView2Settings12->IsWindowControlsOverlayEnabled(true)); + + CHECK_FAILURE(coreWebView2->add_NavigationCompleted( + Callback( + [this, webviewEventView](ICoreWebView2* sender, ICoreWebView2NavigationCompletedEventArgs* args) + -> HRESULT { + + RECT bounds; + controller->QueryWindowControlsOverlayBounds(&bounds); + return S_OK; + }) + .Get(), + &m_navigationCompletedToken)); + + CHECK_FAILURE(m_webView->Navigate(L"www.bing.com")); +} +``` +## .NET C# +```c# +// WebView2 control is defined in the xaml +// +public MainWindow() +{ + InitializeComponent(); + this.webView2Control.CoreWebView2InitializationCompleted + += WebView2InitializationCompleted; + this.webView2Control.NavigationCompleted + += NavigationCompleted ; +} + +private void WebView2InitializationCompleted( + object sender, + CoreWebView2InitializationCompletedEventArgs e) +{ + if (!e.IsSuccess) + { + MessageBox.Show($"WebView2 creation failed with exception = {e.InitializationException}"); + + return; + } + + SetWindowControlsOverlaySupport(true); +} + +private void NavigationCompleted( + object sender, + CoreWebView2NavigationCompletedEventArgs e) +{ + Windows.Foundation.Rect bounds = CoreWebView2Controller.QueryWindowControlsOverlayBounds(); +} + +private void SetWindowControlsOverlaySupport(bool enabled) +{ + var coreWebView2Settings = this.webView2Control.CoreWebView2.Settings; + coreWebView2Settings.IsWindowControlsOverlayEnabled = enabled; +} +``` + +# API Details +## Win32 C++ +```cpp +[uuid(436CA5E2-2D50-43C7-9735-E760F299439E), object, pointer_default(unique)] +interface ICoreWebView2Settings12 : ICoreWebView2Settings11 { + /// Gets the `IsWindowControlsOverlayEnabled` property. + [propget] HRESULT IsWindowControlsOverlayEnabled([out, retval] BOOL* value); + + + /// The `IsWindowControlsOverlayEnabled` property allows devs to opt in/out of using + /// the WV2 custom caption controls. Defaults to `FALSE`. + /// + /// When this property is `TRUE`, WV2 will draw it's own caption controls on the + /// top right corner of the window. + /// + [propput] HRESULT IsWindowControlsOverlayEnabled([in] BOOL value); +} +``` + +## .NET and WinRT +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2Settings + { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings11")] + { + Boolean IsWindowControlsOverlayEnabled { get; set; }; + } + } + + unsealed runtimeclass CoreWebView2Controller { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Controller5")] + { + Windows.Foundation.Rect QueryWindowControlsOverlayBounds(); + } + } +} +``` + + + +# Appendix +To provide your app users with the best experience, it is important to handle webview +initialization errors appropriatly. Provide your users with a way to close the window +or restart the App.