diff --git a/specs/IsWindowControlsOverlayEnabled.md b/specs/IsWindowControlsOverlayEnabled.md deleted file mode 100644 index 8b1378917..000000000 --- a/specs/IsWindowControlsOverlayEnabled.md +++ /dev/null @@ -1 +0,0 @@ - diff --git a/specs/WindowControlsOverlayConfiguration.md b/specs/WindowControlsOverlayConfiguration.md new file mode 100644 index 000000000..c76eb9844 --- /dev/null +++ b/specs/WindowControlsOverlayConfiguration.md @@ -0,0 +1,132 @@ +WebView2 Window Controls +=== + +# Background +This API allows devs 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). Enabing the Overlay allows +for custom app title bars rendered completly inside the webview window. + +The overlay configuration lives on the controller options object. The intent is to +configure it once, before creating the controller. The configuration cannot +be changed after the controller/webview has been created. + +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`. +# 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 controller5; + + if (controller->QueryInterface(&controller5) == S_OK) + { + wil::com_ptr wco_config; + CHECK_FAILURE(controller5->(&wco_config)); + + wco_config->put_IsEnabled(true); + COREWEBVIEW2_COLOR color {1, 0, 0, 225}; + wco_config->put_TitleBarColor(color); + } +} +``` +## .NET C# +```c# +// WebView2 control is defined in the xaml +// +public MainWindow() +{ + InitializeComponent(); + m_AppWindow.TitleBar.ExtendsContentIntoTitleBar = true; + + CoreWebView2WindowControlsOverlayConfiguration config = _coreWebView2Controller.WindowControlsOverlayConfiguration; + config.IsEnabled = true; + config.color = Color.FromARGB(0, 0, 255); +} +``` + +# API Details +## Win32 C++ +```cpp +/// Controller Options API used to configure the window controls overlay. +[uuid(101e36ca-7f75-5105-b9be-fea2ba61a2fd), object, pointer_default(unique)] +interface ICoreWebView2Controller5 : IUnknown { + /// Gets the `WindowControlsOverlayConfiguration` object. + [propget] HRESULT WindowControlsOverlayConfiguration([out, retval] ICoreWebView2WindowControlsOverlayConfiguration** value); +} + +/// This is the ICoreWebView2WindowControlsOverlayConfiguration +[uuid(c9f7378b-8dbb-5445-bacb-08a3fdf032f0), object, pointer_default(unique)] +interface ICoreWebView2WindowControlsOverlayConfiguration : IUnknown { + /// Gets the `Height` property. + [propget] HRESULT Height([out, retval] UINT32* value); + + /// The `Height` property in pixels, allows devs to set the height of the overlay and + /// title bar area. Defaults to 48px + /// + [propput] HRESULT Height([in] UINT32 value); + + /// Gets the `IsEnabled` property. + [propget] HRESULT IsEnabled([out, retval] BOOL* value); + + /// The `IsEnabled` 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 its own caption controls on the + /// top right corner of the window. + /// + [propput] HRESULT IsEnabled([in] BOOL value); + + /// Gets the `TitleBarColor` property. + [propget] HRESULT TitleBarColor([out, retval] COREWEBVIEW2_COLOR* value); + + /// The `TitleBarColor` property allows devs to set a background color + /// for the top of the webview window from (0,0, webview_ window_width, this Height property) + /// + [propput] HRESULT TitleBarColor([in] COREWEBVIEW2_COLOR value); +} +``` + +## .NET and WinRT +```c# +namespace Microsoft.Web.WebView2.Core +{ + runtimeclass CoreWebView2Controller + { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Controller")] + { + CoreWebView2WindowControlsOverlayConfiguration WindowControlsOverlayConfiguration { get; }; + } + } + + runtimeclass CoreWebView2WindowControlsOverlayConfiguration + { + [interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2WindowControlsOverlayConfiguration")] + { + Boolean IsEnabled { get; set; }; + UInt32 Height { get; set; }; + System.Drawing.Color TitleBarColor { get; set; } + } + } +} +``` + + + +# 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.