Included a new API spec for Webview2 Window Controls Overlay

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<ICoreWebView2Controller5> controller5;
+
+    if (controller->QueryInterface(&controller5) == S_OK)
+    {
+        wil::com_ptr<ICoreWebView2WindowControlsOverlayConfiguration> 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
+// <wv2:WebView2 x:Name="webView" Source="https://www.microsoft.com/"/>
+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.