Skip to content

Commit 5a18d07

Browse files
abbychoiiabbychoii
committed
Update IsNonClientRegionSupportEnabled.md
1 parent 4c22d04 commit 5a18d07

1 file changed

Lines changed: 70 additions & 31 deletions

File tree

‎specs/IsNonClientRegionSupportEnabled.md‎

Lines changed: 70 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
# Background
22

3-
To improve the developer experience for customizing non-client regions, WebView2 is working to support using DOM elements as non-client regions. We currently have limited support for title bar aka
4-
draggable regions and are working on building out support for caption controls and resize regions.
3+
To improve the developer experience for customizing non-client regions, WebView2 is working to support using DOM elements as non-client regions. We currently have
4+
limited support for title bar aka draggable regions and are working on building out support for caption controls and resize regions.
55

6-
For security and flexibility, we want developers to be able to enable or disable all custom non-client functionality per WebView. Non-client functionality will affect that app window’s size and position so
7-
it’s important that developers can definitively toggle access. This can be achieved in a limited way using a feature flag, but feature flags are applied per WebView2 environment, thus, an API on the
8-
WebView2 to enable/disable non-client support via a setting is the better solution.
6+
For security and flexibility, we want developers to be able to enable or disable all custom non-client functionality per WebView. Non-client functionality will affect
7+
that app window’s size and position so it’s important that developers can definitively toggle access. This can be achieved in a limited way using a feature flag, but
8+
feature flags are applied per WebView2 environment, thus, an API on the WebView2 to enable/disable non-client support via a setting is the better solution.
99

1010
# Description
11-
`IsNonClientRegionSupportEnabled` defaults to `FALSE`. Disabling/Enabling `IsNonClientRegionSupportEnabled` takes effect after the next navigation. Currently, draggable regions is the only non-client
12-
experience we have implemented. Eventually, this setting will expand to enable other non-client functionality, such as resize and caption controls.
11+
`IsNonClientRegionSupportEnabled` defaults to `FALSE`. Disabling/Enabling `IsNonClientRegionSupportEnabled` takes effect after the next navigation. Currently,
12+
draggable regions is the only non-client experience we have implemented. Eventually, this setting will expand to enable other non-client functionality, such as resize
13+
and caption controls.
1314

1415
When the setting is set to `TRUE`, then the following non-client region support for the top level document will be enabled:
1516

@@ -22,35 +23,75 @@ When set to `FALSE`, then all non-client region support will be disabled.
2223
* Web pages will not be able to use the `app-region` CSS style.
2324

2425
# Examples
25-
```cpp
26-
wil::com_ptr<ICoreWebView2> webView;
27-
void SettingsComponent::ToggleNonClientRegionSupportEnabled()
26+
```cpp
27+
ScenarioNonClientRegionSupport::ScenarioNonClientRegionSupport(AppWindow* appWindow)
28+
: m_appWindow(appWindow), m_webView(appWindow->GetWebView())
2829
{
29-
// Get webView's current settings
30-
wil::com_ptr<ICoreWebView2Settings> coreWebView2Settings;
31-
CHECK_FAILURE(webView->get_Settings(&coreWebView2Settings));
32-
wil::com_ptr<ICoreWebView2Settings9> coreWebView2Settings9;
33-
coreWebView2Settings9 = coreWebView2Settings.try_query<ICoreWebView2Settings9>();
34-
if (coreWebView2Settings9)
35-
{
36-
BOOL enabled;
37-
CHECK_FAILURE(coreWebView2Settings9->get_IsNonClientRegionSupportEnabled(&enabled));
38-
CHECK_FAILURE(coreWebView2Settings9->put_IsNonClientRegionSupportEnabled(!enabled));
39-
}
30+
31+
CHECK_FAILURE(m_webView->add_NavigationStarting(
32+
Callback<ICoreWebView2NavigationStartingEventHandler>(
33+
[this](
34+
ICoreWebView2* sender,
35+
ICoreWebView2NavigationStartingEventArgs* args) -> HRESULT
36+
{
37+
static const PCWSTR url_compare_example = L"www.microsoft.com";
38+
wil::unique_cotaskmem_string uri;
39+
CHECK_FAILURE(args->get_Uri(&uri));
40+
wil::unique_bstr domain = GetDomainOfUri(uri.get());
41+
42+
wil::com_ptr<ICoreWebView2Settings> m_settings;
43+
CHECK_FAILURE(m_webView->get_Settings(&m_settings));
44+
wil::com_ptr<ICoreWebView2Settings12> coreWebView2Settings12;
45+
coreWebView2Settings12 = m_settings.try_query<ICoreWebView2Settings12();
46+
CHECK_FEATURE_RETURN(coreWebView2Settings12);
47+
48+
BOOL enabled;
49+
CHECK_FAILURE(coreWebView2Settings12->get_IsNonClientRegionSupportEnabled(&enabled));
50+
51+
if (wcscmp(domain.get(), url_compare_example) == 0 && !enabled)
52+
{
53+
CHECK_FAILURE(
54+
coreWebView2Settings12->put_IsNonClientRegionSupportEnabled(TRUE));
55+
}
56+
else if (wcscmp(domain.get(), url_compare_example) != 0 && enabled)
57+
{
58+
CHECK_FAILURE(
59+
coreWebView2Settings12->put_IsNonClientRegionSupportEnabled(FALSE));
60+
}
61+
return S_OK;
62+
})
63+
.Get(),
64+
&m_navigationStartingToken));
4065
}
4166
```
67+
4268
```c#
43-
private WebView2 _webView;
44-
void ToggleNonClientRegionSupportEnabled()
69+
private WebView2 webView;
70+
webView.CoreWebView2.NavigationStarting += SetNonClientRegionSupport;
71+
72+
private void SetNonClientRegionSupport(CoreWebView2 sender, CoreWebView2NavigationStartingEventArgs args)
4573
{
46-
var coreWebView2Settings = _webView.CoreWebView2.Settings;
47-
coreWebView2Settings.IsNonClientRegionSupportEnabled = !coreWebView2Settings.IsNonClientRegionSupportEnabled;
74+
var coreWebView2Settings = webView.CoreWebView2.Settings;
75+
var urlCompareExample = "www.microsoft.com";
76+
var uri = new Uri(args.Uri);
77+
78+
if (String.Equals(uri.Host, urlCompareExample, StringComparison.OrdinalIgnoreCase) &&
79+
!coreWebView2Settings.IsNonClientRegionSupportEnabled)
80+
{
81+
coreWebView2Settings.IsNonClientRegionSupportEnabled = true;
82+
}
83+
else if (!String.Equals(uri.Host, urlCompareExample, StringComparison.OrdinalIgnoreCase) &&
84+
coreWebView2Settings.IsNonClientRegionSupportEnabled)
85+
{
86+
coreWebView2Settings.IsNonClientRegionSupportEnabled = false;
87+
}
4888
}
4989
```
5090

5191
# Remarks
52-
If the feature flag for enabling the app-region CSS style is used to enable draggable regions in additional browser arguments, draggable region support will remain enabled even if the
53-
`IsNonClientRegionSupportEnabled` setting is `FALSE`.
92+
If the feature flag is used to enable draggable regions in additional browser arguments, draggable
93+
region support will remain enabled even if the `IsNonClientRegionSupportEnabled` setting is `FALSE`.
94+
* Note: The feature flag is experimental and should not be used in production.
5495

5596
# API Notes
5697
See [API Details](#api-details) section below for API reference.
@@ -77,8 +118,6 @@ interface ICoreWebView2Settings9 : ICoreWebView2Settings8 {
77118
/// dragging of the entire WebView and its host app window, the title bar context menu
78119
/// upon right click, and the maximizing to fill the window and restoring the window size
79120
/// upon double click of the html element.
80-
/// Draggable region support will be enabled if either the `IsNonClientRegionSupportEnabled`
81-
/// property or the flag is used in additional browser arguments (See put_AdditionalBrowserArguments).
82121
///
83122
/// When set to `FALSE`, then all non-client region support will be disabled. Web
84123
/// pages will not be able to use the `app-region` CSS style.
@@ -89,5 +128,5 @@ interface ICoreWebView2Settings9 : ICoreWebView2Settings8 {
89128
```
90129

91130
# Appendix
92-
We considered implementing the APIs in the ControllerOptions class, which would establish whether non-client regions would be supported for the life of the webview at creation. To provide greater
93-
flexibility of use, we decided to implement it as a setting.
131+
We considered implementing the APIs in the ControllerOptions class, which would establish whether non-client regions would be supported for the life of the webview at
132+
creation. To provide greater flexibility of use, we decided to implement it as a setting.

0 commit comments

Comments
 (0)