Skip to content

Commit b8c84db

Browse files
bradp0721bradp0721
authored
Create RasterizationScale.md
1 parent f2abacd commit b8c84db

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

‎specs/RasterizationScale.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Background
2+
The WebView attempts to detects monitor scale changes and applies the monitor DPI scale to all UI produced by the WebView.
3+
When the host app has a DPI awareness of PerMonitorV2, then all child HWNDs receive WM_DPICHANGED.
4+
The WebView can check the current monitor DPI scale when it receives WM_DPICHANGED.
5+
But if the host app is just PerMonitor aware (not v2), then only the top level window receives WM_DPICHANGED.
6+
The WebView could try to use other metrics (like resize) to check the DPI, but resize is not guaranteed in that scenario.
7+
From [GitHub feedback](https://github.com/MicrosoftEdge/WebView2Feedback/issues/65),
8+
we also know that there are consumers of WebView that want to explicitly set a custom DPI scale for WebView.
9+
10+
In this document we describe the updated API. We'd appreciate your feedback.
11+
12+
13+
# Description
14+
To allow the app to control the DPI scale of WebView, we are adding a `RasterizationScale` property to the CoreWebView2Controller interface.
15+
The RasterizationScale property controls the DPI scaling for all UI in WebView.
16+
17+
In order to maintain compatibility with apps developed before this API existed,
18+
WebView2 continues to detect monitor scale changes be default and will update the RasterizationScale property.
19+
When the RasterizationScale property is updated, the `RasterizationScaleChanged` event is raised.
20+
The app can tell WebView2 to stop updating the RasterizationScale property by changing
21+
`ShouldDetectMonitorDpiScaleChanges` from the default value of true, to false.
22+
23+
# Examples
24+
The following code snippets show how to use the RasterizationScale and ShouldDetectMonitorScaleChanges properties,
25+
and now to listen to the RasterizationScaleChanged event.
26+
## Win32 C++
27+
```cpp
28+
void ViewComponent::SetRasterizationScale(float additionalScale)
29+
{
30+
CHECK_FAILURE(m_controller->put_ShouldDetectMonitorScaleChanges(FALSE));
31+
m_webviewAdditionalRasterizationScale = additionalScale;
32+
double rasterizationScale =
33+
additionalScale * m_appWindow->GetDpiScale() * m_appWindow->GetTextScale();
34+
CHECK_FAILURE(m_controller->put_RasterizationScale(rasterizationScale));
35+
}
36+
37+
Callback<ICoreWebView2RasterizationScaleChangedEventHandler>(
38+
[this](ICoreWebView2Controller* sender, IUnknown* args) -> HRESULT {
39+
double rasterizationScale;
40+
CHECK_FAILURE(m_controller->get_RasterizationScale(&rasterizationScale));
41+
42+
std::wstring message = L"WebView2APISample (RasterizationScale: " +
43+
std::to_wstring(int(rasterizationScale * 100)) + L"%)";
44+
SetWindowText(m_appWindow->GetMainWindow(), message.c_str());
45+
return S_OK;
46+
})
47+
.Get(), &m_rasterizationScaleChangedToken));
48+
```
49+
## .Net
50+
```c#
51+
public void SetRasterizationScale(double rasterizaitonScale)
52+
{
53+
CoreWebView2Controller.ShouldDetectMonitorScaleChanges = false;
54+
CoreWebView2Controller.RasterizationScale = rasterizationScale;
55+
}
56+
```
57+
58+
59+
# API Notes
60+
See [API Details](#api-details) section below for API reference.
61+
62+
# API Details
63+
## Win32 C++
64+
```c#
65+
interface ICoreWebView2Controller2 : ICoreWebView2Controller {
66+
/// The rasterization scale for the WebView. The rasterization scale is the
67+
/// combination of the monitor DPI scale and text scaling set by the user.
68+
/// This value should be updated when the DPI scale of the app's top level
69+
/// window changes (i.e. monitor DPI scale changes or window changes monitor)
70+
/// or when the text scale factor of the system changes.
71+
///
72+
/// \snippet AppWindow.cpp DPIChanged
73+
///
74+
/// \snippet AppWindow.cpp TextScaleChanged1
75+
///
76+
/// \snippet AppWindow.cpp TextScaleChanged2
77+
///
78+
/// Rasterization scale applies to the WebView content, as well as
79+
/// popups, context menus, scroll bars, etc. Normal app scaling scenarios
80+
/// should use the ZoomFactor property or SetBoundsAndZoomFactor API.
81+
///
82+
/// \snippet ViewComponent.cpp RasterizationScale
83+
[propget] HRESULT RasterizationScale([out, retval] double* scale);
84+
// Set the rasteriation scale property.
85+
[propput] HRESULT RasterizationScale([in] double scale);
86+
87+
/// ShouldDetectMonitorScaleChanges property determines whether the WebView
88+
/// attempts to track monitor DPI scale changes. When true, the WebView will
89+
/// track monitor DPI scale changes, update the RasterizationScale property,
90+
/// and raises RasterizationScaleChanged event. When false, the WebView will
91+
/// not track monitor DPI scale changes, and the app must update the
92+
/// RasterizationScale property itself. RasterizationScaleChanged event will
93+
/// never raise when ShouldDetectMonitorScaleChanges is false.
94+
[propget] HRESULT ShouldDetectMonitorScaleChanges([out, retval] BOOL* value);
95+
/// Set the ShouldDetectMonitorScaleChanges property.
96+
[propput] HRESULT ShouldDetectMonitorScaleChanges([in] BOOL value);
97+
98+
/// Add an event handler for the RasterizationScaleChanged event.
99+
/// The event is raised when the WebView detects that the monitor DPI scale
100+
/// has changed, ShouldDetectMonitorScaleChanges is true, and the WebView has
101+
/// changed the RasterizationScale property.
102+
///
103+
/// \snippet ViewComponent.cpp RasterizationScaleChanged
104+
HRESULT add_RasterizationScaleChanged(
105+
[in] ICoreWebView2RasterizationScaleChangedEventHandler*
106+
eventHandler,
107+
[out] EventRegistrationToken* token);
108+
/// Remove an event handler previously added with
109+
/// add_RasterizationScaleChanged.
110+
HRESULT remove_RasterizationScaleChanged(
111+
[in] EventRegistrationToken token);
112+
}
113+
interface ICoreWebView2RasterizationScaleChangedEventHandler : IUnknown {
114+
/// Called to provide the implementer with the event args for the
115+
/// corresponding event. There are no event args and the args
116+
/// parameter will be null.
117+
HRESULT Invoke(
118+
[in] ICoreWebView2Controller2* sender,
119+
[in] IUnknown* args);
120+
}
121+
```
122+
## .Net and WinRT
123+
```c#
124+
namespace Microsoft.Web.WebView2.Core
125+
{
126+
public partial class CoreWebView2Controller
127+
{
128+
/// <summary>
129+
/// Gets or sets the WebView rasterization scale.
130+
/// </summary>
131+
/// <remarks>
132+
/// The rasterization scale is the combination of the monitor DPI scale and text scaling set by the user. This value shoud be updated when the DPI scale of the app's top level window changes (i.e. monitor DPI scale changes or the window changes monitor) or when the text scale factor of the system changes.
133+
/// Rasterization scale applies to the WebView content, as well as popups, context menus, scroll bars, etc. Normal app scaling scenarios should use the <see cref="CoreWebView2.ZoomFactor"/> property or <see cref="CoreWebView2.SetBoundsAndZoomFactor"/> method.
134+
/// </remarks>
135+
public double RasterizationScale { get; set;};
136+
137+
/// <summary>
138+
/// Determines whether the WebView will detect monitor scale changes.
139+
/// </summary>
140+
/// <remarks>
141+
/// ShouldDetectMonitorScaleChanges property determines whether the WebView attempts to track monitor DPI scale schanges. When true, the WebView will track monitor DPI scale changes, update the <see cref="CoreWebView2.RasterizationScale"/> property, and fire <see cref="CoreWebView2.RasterizationScaleChanged"/> event. When false, the WebView will not track monitor DPI scale changes, and the app must update the <see cref="CoreWebView2.RasterizationScale"/> property itself. <see cref="CoreWebView2.RasterizationScaleChanged"/> event will never fire when ShouldDetectMonitorScaleChanges is false.
142+
/// </remarks>
143+
public int ShouldDetectMonitorScaleChanges {get; set;};
144+
145+
/// <summary>
146+
/// RasterizationScalechanged is raised when the <see cref="CoreWebView2Controller.RasterizationScale"/> property changes.
147+
/// </summary>
148+
/// <remarks>
149+
/// The event is raised when the Webview detects that the monitor DPI scale has changed, <see cref="CoreWebView2Controller.ShouldDetectMonitorScaleChanges"/> is true, and the Webview has changed the <see cref="CoreWebView2Controller.RasterizationScale"/> property.
150+
/// </remarks>
151+
/// <seealso cref="CoreWebView2Controller.RasterizationScale"/>
152+
public event EventHandler<object> RasterizationScaleChanged;
153+
}
154+
```

0 commit comments

Comments
 (0)