Skip to content

Commit 184b0ee

Browse files
tochukwuIbeEkeochatochukwuIbeEkeocha
authored
Merge pull request #3502 from MicrosoftEdge/api-IsNonClientRegionSupportEnabled-draft
Add spec for IsNonClientRegionSupportEnabled.md
2 parents d156ec4 + 265a204 commit 184b0ee

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎specs/IsNonClientRegionSupportEnabled.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Background
2+
3+
To improve the developer experience for customizing non-client regions, WebView2 is
4+
working to support using DOM elements as non-client regions. We currently have limited
5+
support for custom title bars aka draggable regions and are working on building out support
6+
for caption controls and resize regions.
7+
8+
For security and flexibility, we want developers to be able to enable or disable all
9+
custom non-client functionality per WebView. Non-client functionality will affect that
10+
app window’s size and position so it’s important that developers can definitively
11+
toggle access. This can be achieved in a limited way using a feature flag, but feature
12+
flags are applied per WebView2 environment, thus, an API on the WebView2 to enable/disable
13+
non-client support via a setting is the better solution.
14+
15+
# Description
16+
`IsNonClientRegionSupportEnabled` defaults to `FALSE`. Disabling/Enabling
17+
`IsNonClientRegionSupportEnabled` takes effect after the next navigation. Currently, draggable
18+
regions is the only non-client experience we have implemented. Eventually, this setting will
19+
expand to enable other non-client functionality, such as resize and caption controls.
20+
21+
When the setting is set to `TRUE`, then the following non-client region support for only the top
22+
level document will be enabled:
23+
* Web pages will be able to use the `app-region` CSS style.
24+
* Draggable Regions declared with the CSS style `app-region: drag` will support title bar
25+
functionality, for example, the dragging of the app window, the title bar context menu upon
26+
right click, and the maximizing/restoring of the window size upon double click of the html
27+
element.
28+
29+
When set to `FALSE`, then all non-client region support will be disabled.
30+
* Web pages will not be able to use the `app-region` CSS style.
31+
32+
# Examples
33+
This example enables non-client region support for all pages on www.microsoft.com.
34+
Pages on other origins will not have non-client region support enabled.
35+
36+
## Win32 C++
37+
```cpp
38+
ScenarioNonClientRegionSupport::ScenarioNonClientRegionSupport(AppWindow* appWindow)
39+
: m_appWindow(appWindow), m_webView(appWindow->GetWebView())
40+
{
41+
42+
CHECK_FAILURE(m_webView->add_NavigationStarting(
43+
Callback<ICoreWebView2NavigationStartingEventHandler>(
44+
[this](
45+
ICoreWebView2* sender,
46+
ICoreWebView2NavigationStartingEventArgs* args) -> HRESULT
47+
{
48+
static const PCWSTR allowedHostName = L"www.microsoft.com";
49+
wil::unique_cotaskmem_string uri;
50+
CHECK_FAILURE(args->get_Uri(&uri));
51+
wil::unique_bstr domain = GetDomainOfUri(uri.get());
52+
53+
wil::com_ptr<ICoreWebView2Settings> m_settings;
54+
CHECK_FAILURE(m_webView->get_Settings(&m_settings));
55+
wil::com_ptr<ICoreWebView2Settings12> coreWebView2Settings12;
56+
coreWebView2Settings12 = m_settings.try_query<ICoreWebView2Settings12>();
57+
CHECK_FEATURE_RETURN(coreWebView2Settings12);
58+
59+
bool trusted = _wcsicmp(domain.get(), allowedHostName) == 0;
60+
// This change will take affect after this navitation event completes
61+
CHECK_FAILURE(coreWebView2Settings12->put_IsNonClientRegionSupportEnabled(trusted));
62+
63+
return S_OK;
64+
})
65+
.Get(),
66+
&m_navigationStartingToken));
67+
}
68+
```
69+
## .NET C#
70+
```c#
71+
// WebView2 control is defined in the xaml
72+
// <wv2:WebView2 x:Name="webView" Source="https://www.microsoft.com/"/>
73+
public MainWindow()
74+
{
75+
InitializeComponent();
76+
webView.NavigationStarting += SetNonClientRegionSupport;
77+
}
78+
79+
private void SetNonClientRegionSupport(CoreWebView2 sender, CoreWebView2NavigationStartingEventArgs args)
80+
{
81+
var coreWebView2Settings = webView.CoreWebView2.Settings;
82+
var urlCompareExample = "www.microsoft.com";
83+
var uri = new Uri(args.Uri);
84+
85+
bool trusted = String.Equals(uri.Host, urlCompareExample, StringComparison.OrdinalIgnoreCase);
86+
coreWebView2Settings.IsNonClientRegionSupportEnabled = trusted
87+
}
88+
```
89+
90+
## Declaring Non-client App Regions
91+
The value of the app-region CSS property can be used to indicate which HTML elements are treated as non-client regions.
92+
* Draggable regions can be controlled through the values `drag` or `no-drag`.
93+
* `app-region: drag` will support [draggable region functionality](#description) for the html element.
94+
* `app-region: no-drag` will unmark the html element as a drag region, reverting it to all it's default behaviors.
95+
The app-region CSS property inherits. The initial value is no-drag
96+
```html
97+
<!DOCTYPE html>
98+
<body>
99+
<div style="app-region:drag">
100+
Drag Region
101+
<div style="app-region:no-drag">No-drag Region</div>
102+
</div>
103+
</body>
104+
<html>
105+
```
106+
107+
# Remarks
108+
If the feature flag (`msWebView2EnableDraggableRegions`) is used to enable the CSS style `app-region`'s
109+
values `drag` and `no-drag`, draggable region support will remain enabled
110+
even if the `IsNonClientRegionSupportEnabled` setting is `FALSE`.
111+
* Note: The feature flag is experimental and should not be used in production.
112+
113+
# API Notes
114+
See [API Details](#api-details) section below for API reference.
115+
116+
# API Details
117+
## Win32 C++
118+
```cpp
119+
120+
[uuid(436CA5E2-2D50-43C7-9735-E760F299439E), object, pointer_default(unique)]
121+
interface ICoreWebView2Settings12 : ICoreWebView2Settings11 {
122+
/// The `IsNonClientRegionSupportEnabled` property enables web pages to use the
123+
/// `app-region` CSS style. Changing the `IsNonClientRegionSupportEnabled` property
124+
/// take effect at the completion of the NavigationStarting event for the next
125+
/// top-level navigation. Defaults to `FALSE`.
126+
///
127+
/// When this property is `TRUE`, then all the following non-client region support
128+
/// will be enabled:
129+
/// 1. Draggable Regions will be enabled and treated as a window's title bar.
130+
/// Draggable Regions are regions on a webpage that are exposed through the css
131+
/// attribute `app-region` with the value `drag`. When set to
132+
/// `drag`, these regions will be treated like the window's title bar, supporting
133+
/// dragging of the entire WebView and its host app window, the title bar context menu
134+
/// upon right click, and the maximizing to fill the window and restoring the window size
135+
/// upon double click of the html element.
136+
///
137+
/// When set to `FALSE`, values of the `app-region` CSS style will be ignored. The only
138+
/// exception is `app-region: drag` when the feature flag (msWebView2EnableDraggableRegions)
139+
/// is enabled.
140+
[propget] HRESULT IsNonClientRegionSupportEnabled([out, retval] BOOL* value);
141+
/// Set the IsNonClientRegionSupportEnabled property
142+
[propput] HRESULT IsNonClientRegionSupportEnabled([in] BOOL value);
143+
}
144+
```
145+
146+
## .NET and WinRT
147+
```c#
148+
namespace Microsoft.Web.WebView2.Core
149+
{
150+
runtimeclass CoreWebView2Settings
151+
{
152+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Settings12")]
153+
{
154+
Boolean IsNonClientRegionSupportEnabled { get; set; };
155+
}
156+
}
157+
}
158+
```
159+
160+
# Appendix
161+
We considered implementing the APIs in the ControllerOptions class, which would establish
162+
whether non-client regions would be supported for the life of the webview at creation. To
163+
provide greater flexibility of use, we decided to implement it as a setting.

0 commit comments

Comments
 (0)