diff --git a/specs/WindowControlsOverlayConfiguration.md b/specs/WindowControlsOverlayConfiguration.md new file mode 100644 index 000000000..71864b52e --- /dev/null +++ b/specs/WindowControlsOverlayConfiguration.md @@ -0,0 +1,155 @@ +WebView2 Window Controls +=== + +# Background +This API allows you to enable and configure the Webview2 Window Controls Overlay. +The Overlay is a region on the top right/left of the webview window which contains +the caption buttons (minimize, maximize, restore, close). Enabling the Overlay allows +for custom app title bars rendered completely inside the webview window. + +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++ +```cpp +AppWindow::AppWindow() { + m_mainWindow = CreateWindowExW( + WS_EX_CONTROLPARENT, + GetWindowClass(), + L"" + WS_POPUPWINDOW, + 0,0, 800, 800, + nullptr, nullptr, + g_hInstance, nullptr); +} + +void AppWindow::OnCreateWebview2ControllerCompleted(HRESULT hr, ICoreWebview2Controller* controller) +{ + + wil::com_ptr coreWebView2; + CHECK_FAILURE(m_controller->get_CoreWebView2(&coreWebView2)); + + wil::com_ptr coreWebView2_28; + CHECK_FAILURE(coreWebView2->QueryInterface(&coreWebView2_28)); + + wil::com_ptr windowControlsOverlay; + CHECK_FAILURE(coreWebView2_28->get_WindowControlsOverlay(&windowControlsOverlay)); + + CHECK_FAILURE(windowControlsOverlay->put_IsVisible(true)); + COREWEBVIEW2_COLOR color {1, 0, 0, 225}; + CHECK_FAILURE(windowControlsOverlay->put_BackgroundColor(color)); +} +``` +## .NET C# +```c# +// WebView2 control is defined in the xaml +// +public MainWindow() +{ + InitializeComponent(); + m_AppWindow.TitleBar.ExtendsContentIntoTitleBar = true; + + CoreWebView2WindowControlsOverlay config = Webview2.CoreWebView2.WindowControlsOverlay; + config.IsVisible = true; + config.Color = Color.FromARGB(0, 0, 255); +} +``` + +# API Details +## Win32 C++ +```cpp +/// Controller API used to configure the window controls overlay. +/// To provide your app users with the best experience, it is important to handle webview +/// 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 ICoreWebView2_28 : IUnknown { + /// Gets the `WindowControlsOverlay` object. + [propget] HRESULT WindowControlsOverlay([out, retval] ICoreWebView2WindowControlsOverlay** value); +} + +/// This is the ICoreWebView2WindowControlsOverlay +[uuid(c9f7378b-8dbb-5445-bacb-08a3fdf032f0), object, pointer_default(unique)] +interface ICoreWebView2WindowControlsOverlay : IUnknown { + /// Gets the `Height` property. + [propget] HRESULT Height([out, retval] UINT32* value); + + + /// The `Height` property in raw screen pixels, allows you to set the height of the overlay and + /// 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 your minimum height. + /// + [propput] HRESULT Height([in] UINT32 value); + + + /// Gets the `IsVisible` property. + [propget] HRESULT IsVisible([out, retval] BOOL* value); + + + /// The `IsVisible` property allows you to opt in to using + /// the WebView2 window controls overlay. Defaults to `FALSE`. + /// + /// When this property is `TRUE`, WebView2 will draw its own minimize, maximize, + /// and close buttons on the top right corner of the Webview2. + /// + /// When using this you should configure your app window to not display its default + /// window control buttons. You are responsible for creating a title bar for your app + /// by using the available space to the left of the controls overlay. In doing so, + /// you can utilize the [IsNonClientRegionSupportEnabled](https://learn.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/icorewebview2settings9?view=webview2-1.0.2739.15) + /// API to enable draggable regions for your custom title bar. + /// + /// The Overlay buttons will cover 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 variables](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, titlebar-area-height defined to help you + /// get the dimensions of the available titlebar area to the left of the overlay. + /// Similarly the navigator object will 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 + /// to the size of that area. + /// + [propput] HRESULT IsVisible([in] BOOL value); + + /// Gets the `BackgroundColor` property. + [propget] HRESULT BackgroundColor([out, retval] COREWEBVIEW2_COLOR* value); + + /// The `BackgroundColor` 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. + /// Defaults to #f3f3f3. This API supports transparency. + [propput] HRESULT BackgroundColor([in] COREWEBVIEW2_COLOR value); +} +``` + +## .NET and WinRT +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2 + { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_28")] + { + CoreWebView2WindowControlsOverlay WindowControlsOverlay { get; }; + } + } + + runtimeclass CoreWebView2WindowControlsOverlay + { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2WindowControlsOverlay")] + { + Boolean IsVisible { get; set; }; + UInt32 Height { get; set; }; + Windows.UI.Color BackgroundColor { get; set; } + } + } +} +``` +