From a6cc96939186bb7832439afbc7b9224b15f3976c Mon Sep 17 00:00:00 2001 From: Tochukwu Ibe-Ekeocha <114026179+tochukwuIbeEkeocha@users.noreply.github.com> Date: Fri, 1 Nov 2024 11:20:17 -0700 Subject: [PATCH] Update specs/WindowControlsOverlayConfiguration.md --- specs/WindowControlsOverlayConfiguration.md | 47 +++++++++++++-------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/specs/WindowControlsOverlayConfiguration.md b/specs/WindowControlsOverlayConfiguration.md index 19b018f8..40979e1b 100644 --- a/specs/WindowControlsOverlayConfiguration.md +++ b/specs/WindowControlsOverlayConfiguration.md @@ -10,6 +10,10 @@ The overlay Settings lives on the controller object. This API is designed to be used in addition with the other non-client region APIs and features. These include `app-region: drag`, and `IsNonClientRegionSupportEnabled`. + +# Conceptual pages (How To) +Here is a concept doc on the window controls overlay: https://wicg.github.io/window-controls-overlay/#concepts. This was written for the PWA counterpart for this feature. From the perspective of HTML & Javascript layers, everything there applies in Webview2 as well. + # Examples ## Win32 C++ @@ -27,15 +31,19 @@ AppWindow::AppWindow() { void AppWindow::OnCreateWebview2ControllerCompleted(HRESULT hr, ICoreWebview2Controller* controller) { - wil::com_ptr controller5; - CHECK_FAILURE(controller->QueryInterface(&controller5)); - wil::com_ptr wco_config; - CHECK_FAILURE(controller5->get_WindowControlsOverlaySettings(&wco_config)); + wil::com_ptr coreWebView2; + CHECK_FAILURE(m_controller->get_CoreWebView2(&coreWebView2)); + + wil::com_ptr coreWebView2_28; + CHECK_FAILURE(coreWebView2->QueryInterface(&coreWebView2_28)); - wco_config->put_IsEnabled(true); + wil::com_ptr windowControlsOverlaySettings; + CHECK_FAILURE(coreWebView2_28->get_WindowControlsOverlaySettings(&wco_config)); + + CHECK_FAILURE(wco_config->put_IsEnabled(true)); COREWEBVIEW2_COLOR color {1, 0, 0, 225}; - wco_config->put_TitleBarColor(color); + CHECK_FAILURE(wco_config->put_TitleBarBackgroundColor(color)); } ``` ## .NET C# @@ -47,7 +55,7 @@ public MainWindow() InitializeComponent(); m_AppWindow.TitleBar.ExtendsContentIntoTitleBar = true; - CoreWebView2WindowControlsOverlaySettings config = _coreWebView2Controller.WindowControlsOverlaySettings; + CoreWebView2WindowControlsOverlaySettings config = Webview2.CoreWebivew2.WindowControlsOverlaySettings; config.IsEnabled = true; config.color = Color.FromARGB(0, 0, 255); } @@ -61,7 +69,7 @@ public MainWindow() /// initialization errors appropriately. Provide your users with a way to close the window /// or restart the App. [uuid(101e36ca-7f75-5105-b9be-fea2ba61a2fd), object, pointer_default(unique)] -interface ICoreWebView2Controller5 : IUnknown { +interface ICoreWebView2_28 : IUnknown { /// Gets the `WindowControlsOverlaySettings` object. [propget] HRESULT WindowControlsOverlaySettings([out, retval] ICoreWebView2WindowControlsOverlaySettings** value); } @@ -74,7 +82,10 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown { /// The `Height` property in raw screen pixels, allows you to set the height of the overlay and - /// title bar area. Defaults to 48px. + /// title bar area. Defaults to 48px. There is no minimum height restriction for this API, + /// so it is up to the developer to make sure that the height of your window controls overlay + /// is enough that users can see and interact with it. We recommend using GetSystemMetrics(SM_CYCAPTION) + // as you minimum height. /// [propput] HRESULT Height([in] UINT32 value); @@ -97,7 +108,8 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown { /// /// The Overlay buttons will sit on top of the HTML content, and will prevent mouse interactions /// with any elements directly below it, so you should avoid placing content there. - /// To that end, there are four CSS environment vairables defined to help you + /// To that end, there are four [CSS environment vairables](https://developer.mozilla.org/en-US/docs/Web/API/Window_Controls_Overlay_API#css_environment_variables) + /// titlebar-area-x, titlebar-area-y, titlebar-area-width defined to help you /// get the dimensions of the available titlebar area to the left of the overlay. /// Similarly the navigator object wil contain a [WindowControlsOverlay property](https://developer.mozilla.org/en-US/docs/Web/API/WindowControlsOverlay) /// which can be used to get the titlebar area as a rect, and listen for changes @@ -105,14 +117,14 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown { /// [propput] HRESULT IsEnabled([in] BOOL value); - /// Gets the `TitleBarColor` property. - [propget] HRESULT TitleBarColor([out, retval] COREWEBVIEW2_COLOR* value); + /// Gets the `TitleBarBackgroundColor` property. + [propget] HRESULT TitleBarBackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); - /// The `TitleBarColor` property allows you to set a background color + /// The `TitleBarBackgroundColor` property allows you to set a background color /// for the overlay. Based on the background color you choose, Webview2 ///will automatically calculate a foreground and hover color that will /// provide you the best contrast while maintaining accessibility. - /// Defaults to #f3f3f3 + /// Defaults to #f3f3f3. This API supports transparency. [propput] HRESULT TitleBarBackgroundColor([in] COREWEBVIEW2_COLOR value); } ``` @@ -121,9 +133,9 @@ interface ICoreWebView2WindowControlsOverlaySettings : IUnknown { ```c# namespace Microsoft.Web.WebView2.Core { - runtimeclass CoreWebView2Controller + runtimeclass CoreWebView2 { - [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Controller")] + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_28")] { CoreWebView2WindowControlsOverlaySettings WindowControlsOverlaySettings { get; }; } @@ -135,8 +147,9 @@ namespace Microsoft.Web.WebView2.Core { Boolean IsEnabled { get; set; }; UInt32 Height { get; set; }; - Windows.UI.Color TitleBarColor { get; set; } + Windows.UI.Color TitleBarBackgroundColor { get; set; } } } } ``` +