From 2038eac3f48090d581cea25f38e5509c90fc37d9 Mon Sep 17 00:00:00 2001
From: Tochukwu Ibe-Ekeocha <tibeekeocha@microsoft.com>
Date: Tue, 4 Jun 2024 14:34:51 -0700
Subject: [PATCH] Included a new API spec for Webview2 Window Controls Overlay

---
 specs/IsWindowControlsOverlayEnabled.md | 125 ++++++++++++++++++++++++
 1 file changed, 125 insertions(+)

diff --git a/specs/IsWindowControlsOverlayEnabled.md b/specs/IsWindowControlsOverlayEnabled.md
index 8b1378917..a25d6605d 100644
--- a/specs/IsWindowControlsOverlayEnabled.md
+++ b/specs/IsWindowControlsOverlayEnabled.md
@@ -1 +1,126 @@
+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 proccess. This API allows devs to tell
+WebView2 that it should render it's 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<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
+        this, 
+        [this](HRESULT result, ICoreWebView2Environment* environment) -> {
+            CHECK_FAILURE(hr);
+
+            CHECK_FAILURE(m_webViewEnvironment->CreateCoreWebView2Controller(
+            mainwindowhwnd, 
+            Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(
+                        this, 
+                        &AppWindow::OnCreateCoreWebView2ControllerCompleted).Get()));
+        }).Get());
+}
+
+HRESULT AppWindow::OnCreateCoreWebView2ControllerCompleted(
+    HRESULT result, ICoreWebView2Controller* controller)
+{
+    CHECK_FAILURE(hr);
+
+    wil::com_ptr<ICoreWebView2> coreWebView2;
+    CHECK_FAILURE(controller->get_CoreWebView2(&coreWebView2));
+
+    wil::com_ptr<ICoreWebView2Settings> m_settings;
+    CHECK_FAILURE(coreWebView2->get_Settings(&m_settings));
+
+    wil::com_ptr<ICoreWebView2Settings12> coreWebView2Settings12;
+    coreWebView2Settings12 = m_settings.try_query<ICoreWebView2Settings12>();
+    CHECK_FEATURE_RETURN(coreWebView2Settings12);
+    CHECK_FAILURE(coreWebView2Settings12->IsWindowControlsOverlayEnabled(true));
+}
+```
+## .NET C#
+```c#
+// WebView2 control is defined in the xaml
+// <wv2:WebView2 x:Name="webView" Source="https://www.microsoft.com/"/>
+public MainWindow() 
+{
+    InitializeComponent();
+    this.webView2Control.CoreWebView2InitializationCompleted 
+    += WebView2InitializationCompleted;
+}
+
+private void WebView2InitializationCompleted(
+    object sender, 
+    CoreWebView2InitializationCompletedEventArgs e)
+{
+    if (!e.IsSuccess)
+    {
+    MessageBox.Show($"WebView2 creation failed with exception = {e.InitializationException}");
+
+    return;
+    }
+
+    SetWindowControlsOverlaySupport(true);
+}
+
+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.ICoreWebView2Settings12")]
+        {
+            Boolean IsWindowControlsOverlayEnabled { 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.