From 4c7f8b1dfa5b46fcd3e0682d95527850522ad5cb Mon Sep 17 00:00:00 2001 From: John An Date: Mon, 16 Sep 2024 12:20:01 -0700 Subject: [PATCH 01/37] Adding documentation for Window to Visual hosting mode --- .../concepts/windowed-vs-visual-hosting.md | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index f6a006a3b0..10692328bd 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -10,13 +10,14 @@ ms.date: 10/24/2022 --- # Windowed vs. visual hosting of WebView2 -There are two options for hosting the Microsoft Edge WebView2 control in your app: windowed hosting and visual hosting. +There are three options for hosting the Microsoft Edge WebView2 control in your app: windowed hosting, window to visual hosting, and visual hosting. -If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. If you want to provide a more custom user experience (UX), and want to use visual hosting, read this article. +If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. If you want to provide a more custom user experience (UX) and want to use visual hosting, or if you are using windowed mode in specific scenarios and are experiencing persistent issues with DPI and scaling, read this article. | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | +| Window to Visual hosting | A combination of windowed and visual modes. This mode provides a developer experience basically identical to windowed mode. The only developer from the app developer perspective is the need to set the `COREWEBVIEW2_FORCED_HOSTING_MODE` environment variable to `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. Like windowed mode, the OS sends input to the WebView2 and there is no need to use the visual hosting input APIs. But unlike windowed mode, the WebView2 output is displayed using a visual instead of a window as it is in visual hosting. This implementation detail allows us to prevent a number of DPI related bugs that pure windowed mode apps can run into. It is important to note that this hosting mode comes at the cost of losing pen input and handwriting support. | A developer experience nearly identical to windowed mode but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and visual hosting has additional requirements for it to render properly. The API calls are listed in [Windowed hosting](#windowed-hosting) and [Visual hosting](#visual-hosting), below. @@ -34,6 +35,9 @@ Both approaches for hosting the WebView2 control in your app are similar in func There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. +#### Window to Visual hosting: For a similar experience to Windowed hosting with some added benefits and tradeoff + +Window-to-Visual hosting is meant to be as easy to adopt as windowed hosting. It only requires setting an environment variable to enable. It does not require use of the visual hosting APIs. It resolves certain DPI issues that can result when sharing a WebView2 user data folder across applications. It does not support pen input and handwriting. To enable it, users must set this environment variable: `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value: `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. #### Visual hosting: For more granular control over layout @@ -51,7 +55,7 @@ Key compatibility limitations include the operating system and rendering in fram #### Operating systems -Windows 7 and Windows 8 can only do windowed hosting, not visual hosting. +All hosting modes are supported wherever WebView2 is supported ie. Windows 10 and up and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported. For those still on those platforms Windows 7 and Windows 8 can only do windowed hosting, not visual hosting. See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. @@ -87,9 +91,9 @@ The `CoreWebView2Controller` properties and methods: -## Windowed hosting +## Windowed and Window to Visual hosting -Windowed hosting can be described as an HWND that stores information. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. Some of the Output/Input commands are handled for you by the framework you choose; however, you will still need to handle window management. +In this hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is taht some of the Input/Output commands are handled for you by the OS or the framework. However, you will still need to handle some window management functionalities. Unless specified, all of the information in this section is also true for Window to Visual hosting mode. Benefits for Windowed hosting include: @@ -99,13 +103,23 @@ Benefits for Windowed hosting include: * You don't have to manage the various composition-based rendering (for example, Inputs, Outputs, and Accessibility controls) if you don't want to. +Benefits for Window to Visual hosting include: + +* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application + +* Different apps that share a WebView2 user data folder can have different DPI awarenesses + +* Different apps that share a WebView2 user data folder can have different integrity levels + +* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang + For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). #### Window management -The following aspects of window management are handled in a windowed hosting environment. +The following aspects of window management need to be handled in a windowed hosting environment. @@ -283,7 +297,7 @@ When WebView2 has focus, it receives input directly from the user. An app may wa ###### Default background color -WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set its own background color. +WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set a background color or sets a transparent background color. ##### [.NET/C#](#tab/dotnetcsharp) From 9b3a6151e5ee2dfc020eec025151e07f2a1d5bbc Mon Sep 17 00:00:00 2001 From: John An Date: Wed, 18 Sep 2024 15:51:31 -0700 Subject: [PATCH 02/37] Applying suggested edits. Shortening content in table and consolidating info in later sections. --- .../concepts/windowed-vs-visual-hosting.md | 27 +++++++++++-------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 10692328bd..a182753953 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -10,14 +10,17 @@ ms.date: 10/24/2022 --- # Windowed vs. visual hosting of WebView2 -There are three options for hosting the Microsoft Edge WebView2 control in your app: windowed hosting, window to visual hosting, and visual hosting. +There are three options for hosting the Microsoft Edge WebView2 control in your app: +* Windowed Hosting +* Window to Visual Hosting +* Visual Hosting If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. If you want to provide a more custom user experience (UX) and want to use visual hosting, or if you are using windowed mode in specific scenarios and are experiencing persistent issues with DPI and scaling, read this article. | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of windowed and visual modes. This mode provides a developer experience basically identical to windowed mode. The only developer from the app developer perspective is the need to set the `COREWEBVIEW2_FORCED_HOSTING_MODE` environment variable to `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. Like windowed mode, the OS sends input to the WebView2 and there is no need to use the visual hosting input APIs. But unlike windowed mode, the WebView2 output is displayed using a visual instead of a window as it is in visual hosting. This implementation detail allows us to prevent a number of DPI related bugs that pure windowed mode apps can run into. It is important to note that this hosting mode comes at the cost of losing pen input and handwriting support. | A developer experience nearly identical to windowed mode but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| Window to Visual hosting | A combination of windowed and visual modes. Similar to windowed mode except that it outputs content to a visual that is hosted in a window rather than hosting content in a window directly. | A developer experience nearly identical to windowed mode but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and visual hosting has additional requirements for it to render properly. The API calls are listed in [Windowed hosting](#windowed-hosting) and [Visual hosting](#visual-hosting), below. @@ -33,11 +36,13 @@ Both approaches for hosting the WebView2 control in your app are similar in func "Windowed" means that in your app, an HWND inherits many default properties from the operating system. -There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. +There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. However this hosting mode can run into DPI issues in specific scenarios such as sharing a user data folder across different applications. -#### Window to Visual hosting: For a similar experience to Windowed hosting with some added benefits and tradeoff +#### Window to Visual hosting: For a similar experience to Windowed hosting with some added benefits and a tradeoff -Window-to-Visual hosting is meant to be as easy to adopt as windowed hosting. It only requires setting an environment variable to enable. It does not require use of the visual hosting APIs. It resolves certain DPI issues that can result when sharing a WebView2 user data folder across applications. It does not support pen input and handwriting. To enable it, users must set this environment variable: `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value: `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. +Window-to-Visual hosting means the WebView2 content is displayed using a visual that is hosted in an HWND. As opposed to hosting the content in a window directly or in a visual directly. + +By hosting content in an HWND, this hosting mode enjoys the same ease of adoption benefits as Windowed mode. But by displaying that content using a visual, this hosting mode avoids some specific DPI issues that can result when using Windowed mode. To enable it, users must set this environment variable: `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value: `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. It does not require use of the visual hosting APIs. Enabling this hosting mode removes support for pen input and handwriting. #### Visual hosting: For more granular control over layout @@ -93,7 +98,7 @@ The `CoreWebView2Controller` properties and methods: ## Windowed and Window to Visual hosting -In this hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is taht some of the Input/Output commands are handled for you by the OS or the framework. However, you will still need to handle some window management functionalities. Unless specified, all of the information in this section is also true for Window to Visual hosting mode. +In the Windowed hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. In the Window to Visual mode, content is hosted slightly differently, but has the same benefits and window management requirements as Windowed. Benefits for Windowed hosting include: @@ -105,13 +110,13 @@ Benefits for Windowed hosting include: Benefits for Window to Visual hosting include: -* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application +* Different apps that share a WebView2 user data folder can have different DPI awarenesses. -* Different apps that share a WebView2 user data folder can have different DPI awarenesses +* Different apps that share a WebView2 user data folder can have different integrity levels. -* Different apps that share a WebView2 user data folder can have different integrity levels +* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. -* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang +* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application. For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). @@ -297,7 +302,7 @@ When WebView2 has focus, it receives input directly from the user. An app may wa ###### Default background color -WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set a background color or sets a transparent background color. +WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set a background color, or sets a transparent background color. ##### [.NET/C#](#tab/dotnetcsharp) From c2159528b35e10e422fd653e98ee865411869c65 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 18:25:35 -0700 Subject: [PATCH 03/37] Writer/Editor pass, incorp cmts --- .../concepts/windowed-vs-visual-hosting.md | 136 +++++++++++++++--- 1 file changed, 115 insertions(+), 21 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index a182753953..3d85775baf 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -6,21 +6,65 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: webview -ms.date: 10/24/2022 +ms.date: 09/18/2024 --- # Windowed vs. visual hosting of WebView2 + + + There are three options for hosting the Microsoft Edge WebView2 control in your app: -* Windowed Hosting -* Window to Visual Hosting -* Visual Hosting +* Windowed hosting. +* Window to Visual hosting. +* Visual hosting. -If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. If you want to provide a more custom user experience (UX) and want to use visual hosting, or if you are using windowed mode in specific scenarios and are experiencing persistent issues with DPI and scaling, read this article. +If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use visual hosting, or if you are using windowed mode (Windowed hosting) in specific scenarios and are experiencing persistent issues with DPI and scaling. | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of windowed and visual modes. Similar to windowed mode except that it outputs content to a visual that is hosted in a window rather than hosting content in a window directly. | A developer experience nearly identical to windowed mode but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| Window to Visual hosting | A combination of windowed mode (Windowed hosting) and visual mode (Visual hosting). Similar to windowed mode except that it outputs content to a visual that is hosted in a window rather than hosting content in a window directly. | A developer experience nearly identical to windowed mode, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and visual hosting has additional requirements for it to render properly. The API calls are listed in [Windowed hosting](#windowed-hosting) and [Visual hosting](#visual-hosting), below. @@ -32,20 +76,54 @@ These approaches have different requirements, constraints, and benefits. Window Both approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements. + #### Windowed hosting: For displaying content quickly and easily -"Windowed" means that in your app, an HWND inherits many default properties from the operating system. +_Windowed hosting_ means that in your app, an HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. + + +###### Advantages + +There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. + + +###### Disadvantages + +Windowed hosting mode can run into DPI issues in some scenarios, such as sharing a user data folder across different applications. + -There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. However this hosting mode can run into DPI issues in specific scenarios such as sharing a user data folder across different applications. + +#### Window to Visual hosting: Similar experience as Windowed hosting with added benefits and tradeoff + +_Window-to-Visual hosting_ means that the WebView2 content is displayed by using a visual that is hosted in an HWND (window), rather than hosting the content in a window directly or in a visual directly. + +Window-to-Visual hosting is a combination of windowed and visual modes. + +A _visual_ is a basic graphical unit that can be used with other visuals to compose graphical experiences on Windows. There are a couple of Windows graphics APIs that expose this functionality: `dcomp` and `Windows::UI::Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows::UI::Composition::Visual`, which are visuals that are exposed through the aforementioned APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. + + +###### Advantages -#### Window to Visual hosting: For a similar experience to Windowed hosting with some added benefits and a tradeoff +By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but avoids some DPI issues that can result when using Windowed mode, because Window to Visual hosting mode displays content by using a visual. -Window-to-Visual hosting means the WebView2 content is displayed using a visual that is hosted in an HWND. As opposed to hosting the content in a window directly or in a visual directly. +To enable Window to Visual hosting, your app sets the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. -By hosting content in an HWND, this hosting mode enjoys the same ease of adoption benefits as Windowed mode. But by displaying that content using a visual, this hosting mode avoids some specific DPI issues that can result when using Windowed mode. To enable it, users must set this environment variable: `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value: `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. It does not require use of the visual hosting APIs. Enabling this hosting mode removes support for pen input and handwriting. +Window to Visual hosting does not require use of the visual hosting APIs. + +###### Disadvantages + +Enabling Window to Visual hosting mode removes support for pen input and handwriting. + + + #### Visual hosting: For more granular control over layout +When using _Visual hosting_, your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. + + +###### Advantages and disadvantages + Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. With visual hosting, for example you must choose how when the user resizes the window, how the webview scales in relation to the whole page - for example, if you want the webview to scale twice as much as the app. @@ -68,6 +146,8 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft #### Rendering WebView2 in framework and non-framework apps + + If you're using a UI framework for your app, you should use the corresponding WebView2 element for that UI framework. If you aren't using a UI framework for your app (such as Win32 or React Native) or your UI framework doesn't have a WebView2 element, you'll need to create `CoreWebView2Controller` and render it into the desired app. **Note:** If your app's UI is built using `DirectComposition` or `Windows.UI.Composition`, then you should use `CoreWebView2CompositionController`, otherwise you should use `CoreWebView2Controller`. @@ -96,11 +176,15 @@ The `CoreWebView2Controller` properties and methods: -## Windowed and Window to Visual hosting +## Windowed hosting and Window to Visual hosting -In the Windowed hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. In the Window to Visual mode, content is hosted slightly differently, but has the same benefits and window management requirements as Windowed. +In the Windowed hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. -Benefits for Windowed hosting include: +In the Window to Visual hosting mode, content is hosted slightly differently, but has the same benefits and window-management requirements as Windowed hosting. + + + +#### Benefits of Windowed hosting * Zooming and rasterization scales (for example, menus, context menus, and so on) will also automatically scale to the app's parent `HWND`. It also handles how the WebView manages being focused and tabbing in/out of itself when it reaches the final element. @@ -108,7 +192,9 @@ Benefits for Windowed hosting include: * You don't have to manage the various composition-based rendering (for example, Inputs, Outputs, and Accessibility controls) if you don't want to. -Benefits for Window to Visual hosting include: + + +#### Benefits of Window to Visual hosting * Different apps that share a WebView2 user data folder can have different DPI awarenesses. @@ -124,12 +210,16 @@ For general information regarding Window management and `HWND` functionality, se #### Window management -The following aspects of window management need to be handled in a windowed hosting environment. +In a windowed hosting environment, the following aspects of window management need to be handled. +* Sizing, positioning, and visibility. +* Zooming. ###### Sizing, positioning, and visibility + + `CoreWebView2Controller` takes a parent `HWND`. The `Bounds` property sizes and positions the WebView2 relative to the parent `HWND`. The visibility of WebView2 can be toggled by using `IsVisible`. ##### [.NET/C#](#tab/dotnetcsharp) @@ -337,6 +427,8 @@ The following APIs can be used when configuring WebView2 in a visual hosting env #### Composition-based rendering + + For composition-based WebView2 rendering, use the `CoreWebView2Environment` to create a `CoreWebView2CompositionController`. The `CoreWebView2CompositionController` implements all the APIs as `CoreWebView2Controller`, but includes additional APIs specific to composition-based rendering. ##### [.NET/C#](#tab/dotnetcsharp) @@ -407,7 +499,7 @@ Spatial input such as mouse, touch, or pen is received by the app and must be se * [CoreWebView2Environment.CreateCoreWebView2PointerInfo Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment#createcorewebview2pointerinfo) * [CoreWebView2PointerInfo Class](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2pointerinfo) - ##### [Win32/C++](#tab/win32cpp) @@ -448,8 +540,10 @@ Not applicable. - +## See also + - +* [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. +* [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). +* [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. From 75cbfa274c179bd8ca230ea2be76332d4ebf3fe6 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 18:54:32 -0700 Subject: [PATCH 04/37] linkfix etc --- .../concepts/windowed-vs-visual-hosting.md | 53 +++++++++++++------ 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 3d85775baf..51130e8e27 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -1,6 +1,6 @@ --- -title: Windowed vs. visual hosting of WebView2 -description: Deciding whether to have your app use windowed hosting vs. visual hosting of the WebView2 control. Hosting WebView2 in windowed or visual environments. +title: Windowed vs. Visual hosting of WebView2 +description: Deciding whether to have your app use Windowed hosting vs. Visual hosting of the WebView2 control. Hosting WebView2 in windowed or visual environments. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: conceptual @@ -8,7 +8,7 @@ ms.service: microsoft-edge ms.subservice: webview ms.date: 09/18/2024 --- -# Windowed vs. visual hosting of WebView2 +# Windowed vs. Visual hosting of WebView2 +Overview of APIs: https://learn.microsoft.com/microsoft-edge/webview2/concepts/overview-features-apis +--> There are three options for hosting the Microsoft Edge WebView2 control in your app: * Windowed hosting. * Window to Visual hosting. * Visual hosting. -If you use windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use visual hosting, or if you are using windowed mode (Windowed hosting) in specific scenarios and are experiencing persistent issues with DPI and scaling. +If you use Windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use Visual hosting, or if you are using windowed mode (Windowed hosting) in specific scenarios and are experiencing persistent issues with DPI and scaling. | Approach | Description | Optimized for | |---|---|---| @@ -67,7 +70,9 @@ If you use windowed hosting, which is a good starting point for most apps, you d | Window to Visual hosting | A combination of windowed mode (Windowed hosting) and visual mode (Visual hosting). Similar to windowed mode except that it outputs content to a visual that is hosted in a window rather than hosting content in a window directly. | A developer experience nearly identical to windowed mode, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | -These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and visual hosting has additional requirements for it to render properly. The API calls are listed in [Windowed hosting](#windowed-hosting) and [Visual hosting](#visual-hosting), below. +These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than Visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and Visual hosting has additional requirements for it to render properly. The API calls are listed in the following sections below: +* [Windowed hosting and Window to Visual hosting](#windowed-hosting-and-window-to-visual-hosting) +* [Visual hosting](#visual-hosting) @@ -108,7 +113,7 @@ By hosting content in an HWND, Window to Visual hosting mode enjoys the same eas To enable Window to Visual hosting, your app sets the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. -Window to Visual hosting does not require use of the visual hosting APIs. +Window to Visual hosting does not require use of the Visual hosting APIs. ###### Disadvantages @@ -126,7 +131,7 @@ When using _Visual hosting_, your host app takes spatial input (such as mouse or Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. -With visual hosting, for example you must choose how when the user resizes the window, how the webview scales in relation to the whole page - for example, if you want the webview to scale twice as much as the app. +With Visual hosting, for example you must choose how when the user resizes the window, how the webview scales in relation to the whole page - for example, if you want the webview to scale twice as much as the app. @@ -138,7 +143,7 @@ Key compatibility limitations include the operating system and rendering in fram #### Operating systems -All hosting modes are supported wherever WebView2 is supported ie. Windows 10 and up and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported. For those still on those platforms Windows 7 and Windows 8 can only do windowed hosting, not visual hosting. +All hosting modes are supported wherever WebView2 is supported ie. Windows 10 and up and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported. For those still on those platforms Windows 7 and Windows 8 can only do Windowed hosting, not Visual hosting. See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. @@ -207,10 +212,16 @@ In the Window to Visual hosting mode, content is hosted slightly differently, bu For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). + +#### APIs for Windowed hosting and Window to Visual hosting + +The following APIs can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting. + + #### Window management -In a windowed hosting environment, the following aspects of window management need to be handled. +In a Windowed hosting environment, the following aspects of window management need to be handled. * Sizing, positioning, and visibility. * Zooming. @@ -268,6 +279,9 @@ WebView2 `ZoomFactor` is used to scale just the web content. This is also updat #### Rasterization scale + The `RasterizationScale` API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the `RasterizationScale`. `BoundsMode` is used to configure whether the `Bounds` property is interpreted as raw pixels, or DIPs (which need to be scaled by `RasterizationScale`). @@ -415,13 +429,17 @@ WebView2 can specify a default background color. This can be any opaque color or ## Visual hosting -In visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for windowed hosting, visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). +In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). -If your WebView2 app uses visual hosting: +If your WebView2 app uses Visual hosting: * Inputs are routed to the app's `HWND` and must be configured to send the spatial input (for example, mouse, touch, and pen) based on positions, _not_ what currently has focus, such as a keyboard. -The following APIs can be used when configuring WebView2 in a visual hosting environment: + + +#### APIs for Visual hosting + +The following APIs can be used when configuring WebView2 in a Visual hosting environment: @@ -541,9 +559,12 @@ Not applicable. ## See also - + +* [Overview of WebView2 features and APIs](./overview-features-apis.md) * [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. + +Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. From bb6950571230f5b78dbe454263ba585025a455f2 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 18:58:46 -0700 Subject: [PATCH 05/37] move todo cmts --- .../webview2/concepts/windowed-vs-visual-hosting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 51130e8e27..aff1735da4 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -216,6 +216,7 @@ For general information regarding Window management and `HWND` functionality, se #### APIs for Windowed hosting and Window to Visual hosting The following APIs can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting. + @@ -229,7 +230,6 @@ In a Windowed hosting environment, the following aspects of window management ne ###### Sizing, positioning, and visibility - `CoreWebView2Controller` takes a parent `HWND`. The `Bounds` property sizes and positions the WebView2 relative to the parent `HWND`. The visibility of WebView2 can be toggled by using `IsVisible`. @@ -440,13 +440,12 @@ If your WebView2 app uses Visual hosting: #### APIs for Visual hosting The following APIs can be used when configuring WebView2 in a Visual hosting environment: + #### Composition-based rendering - - For composition-based WebView2 rendering, use the `CoreWebView2Environment` to create a `CoreWebView2CompositionController`. The `CoreWebView2CompositionController` implements all the APIs as `CoreWebView2Controller`, but includes additional APIs specific to composition-based rendering. ##### [.NET/C#](#tab/dotnetcsharp) From 88a42e1e5079f0a7cacf691612891c29585fb685 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 19:33:49 -0700 Subject: [PATCH 06/37] adjust api section levels --- microsoft-edge/toc.yml | 2 +- .../concepts/windowed-vs-visual-hosting.md | 61 ++++++++++++------- 2 files changed, 41 insertions(+), 22 deletions(-) diff --git a/microsoft-edge/toc.yml b/microsoft-edge/toc.yml index 12160c232d..812ce1ce83 100644 --- a/microsoft-edge/toc.yml +++ b/microsoft-edge/toc.yml @@ -1366,7 +1366,7 @@ href: webview2/concepts/basic-authentication.md displayName: auth, Basic authentication for WebView2 apps # top-of-page title - - name: Windowed vs. visual hosting of WebView2 + - name: Windowed vs. Visual hosting of WebView2 href: webview2/concepts/windowed-vs-visual-hosting.md - name: Custom management of network requests diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index aff1735da4..c29b89bbb0 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -34,10 +34,10 @@ ms.date: 09/18/2024 #### Benefits of Windowed hosting #### Benefits of Window to Visual hosting #### APIs for Windowed hosting and Window to Visual hosting -#### Window management [APIs tabset] -###### Sizing, positioning, and visibility [APIs tabset] -###### Zooming [APIs tabset] -#### Rasterization scale [APIs tabset] err? same level as surrounding headings, in "Overview of APIs" +###### Window management [APIs tabset] +###### Sizing, positioning, and visibility [APIs tabset] child +###### Zooming [APIs tabset] child +###### Rasterization scale [APIs tabset] ###### Focus and tabbing [APIs tabset] ###### Parent window [APIs tabset] ###### Keyboard accelerators [APIs tabset] @@ -46,10 +46,10 @@ ms.date: 09/18/2024 ======================================= ## Visual hosting #### APIs for Visual hosting -#### Composition-based rendering [APIs tabset] -#### Output [APIs tabset] -#### Input [APIs tabset] -#### Accessibility [APIs tabset] +###### Composition-based rendering [APIs tabset] +###### Output [APIs tabset] +###### Input [APIs tabset] +###### Accessibility [APIs tabset] ======================================= ## See also @@ -151,7 +151,10 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft #### Rendering WebView2 in framework and non-framework apps - + If you're using a UI framework for your app, you should use the corresponding WebView2 element for that UI framework. If you aren't using a UI framework for your app (such as Win32 or React Native) or your UI framework doesn't have a WebView2 element, you'll need to create `CoreWebView2Controller` and render it into the desired app. @@ -216,13 +219,23 @@ For general information regarding Window management and `HWND` functionality, se #### APIs for Windowed hosting and Window to Visual hosting The following APIs can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting. - + -#### Window management +###### Window management -In a Windowed hosting environment, the following aspects of window management need to be handled. +In a Windowed hosting environment, the following aspects of window management need to be handled: * Sizing, positioning, and visibility. * Zooming. @@ -230,6 +243,7 @@ In a Windowed hosting environment, the following aspects of window management ne ###### Sizing, positioning, and visibility +This section is part of Window management. `CoreWebView2Controller` takes a parent `HWND`. The `Bounds` property sizes and positions the WebView2 relative to the parent `HWND`. The visibility of WebView2 can be toggled by using `IsVisible`. @@ -254,6 +268,8 @@ In a Windowed hosting environment, the following aspects of window management ne ###### Zooming +This section is part of Window management. + WebView2 `ZoomFactor` is used to scale just the web content. This is also updated when the user zooms the content through **Ctrl**+Mouse Wheel. ##### [.NET/C#](#tab/dotnetcsharp) @@ -278,10 +294,7 @@ WebView2 `ZoomFactor` is used to scale just the web content. This is also updat -#### Rasterization scale - +###### Rasterization scale The `RasterizationScale` API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the `RasterizationScale`. `BoundsMode` is used to configure whether the `Bounds` property is interpreted as raw pixels, or DIPs (which need to be scaled by `RasterizationScale`). @@ -440,11 +453,17 @@ If your WebView2 app uses Visual hosting: #### APIs for Visual hosting The following APIs can be used when configuring WebView2 in a Visual hosting environment: - + -#### Composition-based rendering +###### Composition-based rendering For composition-based WebView2 rendering, use the `CoreWebView2Environment` to create a `CoreWebView2CompositionController`. The `CoreWebView2CompositionController` implements all the APIs as `CoreWebView2Controller`, but includes additional APIs specific to composition-based rendering. @@ -467,7 +486,7 @@ For composition-based WebView2 rendering, use the `CoreWebView2Environment` to c -#### Output +###### Output WebView2 can connect its composition tree to `IDCompositionVisual`, `IDCompositionTarget`, or `Windows::UI::Composition::ContainerVisual`. @@ -487,7 +506,7 @@ WebView2 can connect its composition tree to `IDCompositionVisual`, `IDCompositi -#### Input +###### Input Spatial input such as mouse, touch, or pen is received by the app and must be sent to WebView2. WebView2 notifies the app when the cursor should be updated based on the input device's position. @@ -536,7 +555,7 @@ Spatial input such as mouse, touch, or pen is received by the app and must be se -#### Accessibility +###### Accessibility By default, WebView2 will show up in the accessibility tree as a child of the parent `HWND`. WebView2 provides an API to better position the WebView2 content relative to other elements in the app. From f9add9b9d0c77aee7e33eea902f2a3772bfe8272 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 19:38:09 -0700 Subject: [PATCH 07/37] include "mode" in term introduction --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index c29b89bbb0..d6ad8d99bf 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -58,9 +58,9 @@ Overview of APIs: https://learn.microsoft.com/microsoft-edge/webview2/concepts/o --> There are three options for hosting the Microsoft Edge WebView2 control in your app: -* Windowed hosting. -* Window to Visual hosting. -* Visual hosting. +* The Windowed hosting mode. +* The Window to Visual hosting mode. +* The Visual hosting mode. If you use Windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use Visual hosting, or if you are using windowed mode (Windowed hosting) in specific scenarios and are experiencing persistent issues with DPI and scaling. From 9475616a3bfc2ed2c4cd67147de8d7a22d8bdf1d Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 18 Sep 2024 19:49:38 -0700 Subject: [PATCH 08/37] remove Overview link from outline cmt --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index d6ad8d99bf..8b4b2659dd 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -53,8 +53,6 @@ ms.date: 09/18/2024 ======================================= ## See also - -Overview of APIs: https://learn.microsoft.com/microsoft-edge/webview2/concepts/overview-features-apis --> There are three options for hosting the Microsoft Edge WebView2 control in your app: From e3ae82b32025083d89b59218fe11cc81b5d8e965 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Thu, 19 Sep 2024 00:27:15 -0700 Subject: [PATCH 09/37] link to equiv section in Overview APIs --- .../concepts/windowed-vs-visual-hosting.md | 94 +++++-------------- 1 file changed, 25 insertions(+), 69 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 8b4b2659dd..9b11015212 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -10,51 +10,6 @@ ms.date: 09/18/2024 --- # Windowed vs. Visual hosting of WebView2 - - There are three options for hosting the Microsoft Edge WebView2 control in your app: * The Windowed hosting mode. * The Window to Visual hosting mode. @@ -149,10 +104,10 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft #### Rendering WebView2 in framework and non-framework apps - + + + +This list is similar to [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. If you're using a UI framework for your app, you should use the corresponding WebView2 element for that UI framework. If you aren't using a UI framework for your app (such as Win32 or React Native) or your UI framework doesn't have a WebView2 element, you'll need to create `CoreWebView2Controller` and render it into the desired app. @@ -217,17 +172,7 @@ For general information regarding Window management and `HWND` functionality, se #### APIs for Windowed hosting and Window to Visual hosting The following APIs can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting. - + @@ -241,7 +186,7 @@ In a Windowed hosting environment, the following aspects of window management ne ###### Sizing, positioning, and visibility -This section is part of Window management. +This section is part of Window management. This list is similar to [Sizing, positioning, and visibility](./overview-features-apis.md#sizing-positioning-and-visibility) in _Overview of WebView2 features and APIs_. `CoreWebView2Controller` takes a parent `HWND`. The `Bounds` property sizes and positions the WebView2 relative to the parent `HWND`. The visibility of WebView2 can be toggled by using `IsVisible`. @@ -266,7 +211,7 @@ This section is part of Window management. ###### Zooming -This section is part of Window management. +This section is part of Window management. This list is similar to [Zooming](./overview-features-apis.md#zooming) in _Overview of WebView2 features and APIs_. WebView2 `ZoomFactor` is used to scale just the web content. This is also updated when the user zooms the content through **Ctrl**+Mouse Wheel. @@ -296,6 +241,8 @@ WebView2 `ZoomFactor` is used to scale just the web content. This is also updat The `RasterizationScale` API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the `RasterizationScale`. `BoundsMode` is used to configure whether the `Bounds` property is interpreted as raw pixels, or DIPs (which need to be scaled by `RasterizationScale`). +This list is similar to [Rasterization scale](./overview-features-apis.md#rasterization-scale) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2Controller.BoundsMode Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.boundsmode#microsoft-web-webview2-core-corewebview2controller-boundsmode) @@ -328,6 +275,8 @@ The `RasterizationScale` API scales all WebView2 UI including context menus, too WebView2 raises events to let the app know when it gains or loses focus. For tabbing, there's an API to move focus into WebView2, and an event for WebView2 to request the app to take focus back. +This list is similar to [Focus and tabbing](./overview-features-apis.md#focus-and-tabbing) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2Controller.MoveFocus Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.movefocus) @@ -363,6 +312,7 @@ WebView2 raises events to let the app know when it gains or loses focus. For ta WebView2 can be re-parented to a different parent `HWND`. WebView2 also needs to be notified when the app's position on the screen changes. +This list is similar to [Parent window](./overview-features-apis.md#parent-window) in _Overview of WebView2 features and APIs_. ##### [.NET/C#](#tab/dotnetcsharp) @@ -387,6 +337,8 @@ WebView2 can be re-parented to a different parent `HWND`. WebView2 also needs to When WebView2 has focus, it receives input directly from the user. An app may want to intercept and handle certain accelerator key combinations or disable the normal browser accelerator key behaviors. +This list is similar to [Keyboard accelerators](./overview-features-apis.md#keyboard-accelerators) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled Property](/dotnet/api/microsoft.web.webview2.core.corewebview2settings.arebrowseracceleratorkeysenabled) @@ -419,6 +371,8 @@ When WebView2 has focus, it receives input directly from the user. An app may wa WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set a background color, or sets a transparent background color. +This list is similar to [Default background color](./overview-features-apis.md#default-background-color) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2Controller.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.defaultbackgroundcolor) @@ -451,13 +405,7 @@ If your WebView2 app uses Visual hosting: #### APIs for Visual hosting The following APIs can be used when configuring WebView2 in a Visual hosting environment: - + @@ -465,6 +413,8 @@ Accessibility = [Accessibility](./overview-features-apis.md#accessibility) For composition-based WebView2 rendering, use the `CoreWebView2Environment` to create a `CoreWebView2CompositionController`. The `CoreWebView2CompositionController` implements all the APIs as `CoreWebView2Controller`, but includes additional APIs specific to composition-based rendering. +This list is similar to [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2CompositionController Class](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller) @@ -488,6 +438,8 @@ For composition-based WebView2 rendering, use the `CoreWebView2Environment` to c WebView2 can connect its composition tree to `IDCompositionVisual`, `IDCompositionTarget`, or `Windows::UI::Composition::ContainerVisual`. +This list is similar to [Connecting to the visual tree](./overview-features-apis.md#connecting-to-the-visual-tree) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2CompositionController.RootVisualTarget Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.rootvisualtarget) @@ -508,6 +460,8 @@ WebView2 can connect its composition tree to `IDCompositionVisual`, `IDCompositi Spatial input such as mouse, touch, or pen is received by the app and must be sent to WebView2. WebView2 notifies the app when the cursor should be updated based on the input device's position. +This list is similar to [Forwarding input](./overview-features-apis.md#forwarding-input) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) * [CoreWebView2CompositionController.Cursor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.cursor) @@ -557,6 +511,8 @@ Spatial input such as mouse, touch, or pen is received by the app and must be se By default, WebView2 will show up in the accessibility tree as a child of the parent `HWND`. WebView2 provides an API to better position the WebView2 content relative to other elements in the app. +This list is similar to [Accessibility](./overview-features-apis.md#accessibility) in _Overview of WebView2 features and APIs_. + ##### [.NET/C#](#tab/dotnetcsharp) Not applicable. From b7d1c28103e4db84d3fa699f7289ed8d33b2b3da Mon Sep 17 00:00:00 2001 From: "John An (from Dev Box)" Date: Mon, 23 Sep 2024 17:01:12 -0700 Subject: [PATCH 10/37] Remove api tabset in windowed-vs-visual-hosting.md that is duplicated in overview-features-apis.md. Then consolidate information that was embedded throughout the api tabset section into previous info sections --- .../concepts/windowed-vs-visual-hosting.md | 482 ++---------------- 1 file changed, 38 insertions(+), 444 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 9b11015212..0956ee3099 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -1,6 +1,6 @@ --- title: Windowed vs. Visual hosting of WebView2 -description: Deciding whether to have your app use Windowed hosting vs. Visual hosting of the WebView2 control. Hosting WebView2 in windowed or visual environments. +description: Deciding whether to have your app use Windowed, Window to Visual, or Visual hosting of the WebView2 control. Hosting WebView2 in windowed or visual environments. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: conceptual @@ -15,12 +15,12 @@ There are three options for hosting the Microsoft Edge WebView2 control in your * The Window to Visual hosting mode. * The Visual hosting mode. -If you use Windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use Visual hosting, or if you are using windowed mode (Windowed hosting) in specific scenarios and are experiencing persistent issues with DPI and scaling. +If you use Windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use Visual hosting, or if you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of windowed mode (Windowed hosting) and visual mode (Visual hosting). Similar to windowed mode except that it outputs content to a visual that is hosted in a window rather than hosting content in a window directly. | A developer experience nearly identical to windowed mode, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than Visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and Visual hosting has additional requirements for it to render properly. The API calls are listed in the following sections below: @@ -31,54 +31,73 @@ These approaches have different requirements, constraints, and benefits. Window ## Scenarios for selecting the hosting approach -Both approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements. +The different approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements. #### Windowed hosting: For displaying content quickly and easily -_Windowed hosting_ means that in your app, an HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. +_Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window ie. an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. + +For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). ###### Advantages -There are instances where you might want to focus on displaying web content as quickly and easily as possible in your app. Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. +* Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. + +* Zooming and rasterization scales (for example, menus, context menus, and so on) will automatically scale to the app's parent `HWND`. It also handles how the WebView manages being focused and tabbing in/out of itself when it reaches the final element. + +* The app handles keyboard accelerators and keyboard shortcuts when in the WebView. For example, **Ctrl+C** in a WebView will know that you are trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. + +* You don't have to manage the various composition-based rendering (for example, Inputs, Outputs, and Accessibility controls) if you don't want to. ###### Disadvantages Windowed hosting mode can run into DPI issues in some scenarios, such as sharing a user data folder across different applications. - -#### Window to Visual hosting: Similar experience as Windowed hosting with added benefits and tradeoff +#### Window to Visual hosting: For a similar experience as Windowed hosting with added benefits and tradeoff + +_Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI issues that can result when using Windowed mode. -_Window-to-Visual hosting_ means that the WebView2 content is displayed by using a visual that is hosted in an HWND (window), rather than hosting the content in a window directly or in a visual directly. +Window to Visual hosting does not require use of the Visual hosting APIs. -Window-to-Visual hosting is a combination of windowed and visual modes. +To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. -A _visual_ is a basic graphical unit that can be used with other visuals to compose graphical experiences on Windows. There are a couple of Windows graphics APIs that expose this functionality: `dcomp` and `Windows::UI::Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows::UI::Composition::Visual`, which are visuals that are exposed through the aforementioned APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. +In both Window-to-Visual and Visual hosting, a _visual_ is defined as a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are: `DirectComposition` and `Windows.UI.Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are visuals that are exposed through the aforementioned APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) For more information see [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs and [Composition visual](/windows/uwp/composition/composition-visual-tree) Windows App Development > UWP docs. ###### Advantages -By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but avoids some DPI issues that can result when using Windowed mode, because Window to Visual hosting mode displays content by using a visual. +* Different apps that share a WebView2 user data folder can have different DPI awarenesses. -To enable Window to Visual hosting, your app sets the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. +* Different apps that share a WebView2 user data folder can have different integrity levels. -Window to Visual hosting does not require use of the Visual hosting APIs. +* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. + +* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application. ###### Disadvantages Enabling Window to Visual hosting mode removes support for pen input and handwriting. + +###### APIs for Windowed hosting and Window to Visual hosting + +For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps). #### Visual hosting: For more granular control over layout When using _Visual hosting_, your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. +In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). + +If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (for example, mouse, touch, and pen) based on positions, _not_ what currently has focus, such as a keyboard. + ###### Advantages and disadvantages @@ -86,13 +105,16 @@ Visual hosting allows for (and requires) more granular control of layout. When With Visual hosting, for example you must choose how when the user resizes the window, how the webview scales in relation to the whole page - for example, if you want the webview to scale twice as much as the app. + +###### APIs for Visual hosting + +For a list of APIs that can be used when configuring WebView2 in a visual hosting environment, see [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition). ## Compatibility and constraints Key compatibility limitations include the operating system and rendering in framework and non-framework apps. - #### Operating systems @@ -100,435 +122,6 @@ All hosting modes are supported wherever WebView2 is supported ie. Windows 10 an See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. - - -#### Rendering WebView2 in framework and non-framework apps - - - - -This list is similar to [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. - -If you're using a UI framework for your app, you should use the corresponding WebView2 element for that UI framework. If you aren't using a UI framework for your app (such as Win32 or React Native) or your UI framework doesn't have a WebView2 element, you'll need to create `CoreWebView2Controller` and render it into the desired app. - -**Note:** If your app's UI is built using `DirectComposition` or `Windows.UI.Composition`, then you should use `CoreWebView2CompositionController`, otherwise you should use `CoreWebView2Controller`. - -The `CoreWebView2Controller` properties and methods: - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.CoreWebView2 Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.corewebview2) -* [CoreWebView2Controller.Close Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.close) -* [CoreWebView2Environment.CreateCoreWebView2ControllerAsync Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createcorewebview2controllerasync) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.CoreWebView2 Property](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_corewebview2) -* [CoreWebView2Controller.Close Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#close) -* [CoreWebView2Environment.CreateCoreWebView2ControllerAsync Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment#createcorewebview2controllerasync) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::CoreWebView2 property](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_corewebview2) -* [ICoreWebView2Controller::Close method](/microsoft-edge/webview2/reference/win32/icorewebview2controller#close) -* [ICoreWebView2Environment::CreateCoreWebView2Controller method](/microsoft-edge/webview2/reference/win32/icorewebview2environment#createcorewebview2controller) - ---- - - - -## Windowed hosting and Window to Visual hosting - -In the Windowed hosting mode, WebView2 content is hosted directly in a window. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. - -In the Window to Visual hosting mode, content is hosted slightly differently, but has the same benefits and window-management requirements as Windowed hosting. - - - -#### Benefits of Windowed hosting - -* Zooming and rasterization scales (for example, menus, context menus, and so on) will also automatically scale to the app's parent `HWND`. It also handles how the WebView manages being focused and tabbing in/out of itself when it reaches the final element. - -* The app handles keyboard accelerators and keyboard shortcuts when in the WebView. For example, **Ctrl+C** in a WebView will know that you are trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. - -* You don't have to manage the various composition-based rendering (for example, Inputs, Outputs, and Accessibility controls) if you don't want to. - - - -#### Benefits of Window to Visual hosting - -* Different apps that share a WebView2 user data folder can have different DPI awarenesses. - -* Different apps that share a WebView2 user data folder can have different integrity levels. - -* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. - -* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application. - -For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). - - - -#### APIs for Windowed hosting and Window to Visual hosting - -The following APIs can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting. - - - - -###### Window management - -In a Windowed hosting environment, the following aspects of window management need to be handled: -* Sizing, positioning, and visibility. -* Zooming. - - - -###### Sizing, positioning, and visibility - -This section is part of Window management. This list is similar to [Sizing, positioning, and visibility](./overview-features-apis.md#sizing-positioning-and-visibility) in _Overview of WebView2 features and APIs_. - -`CoreWebView2Controller` takes a parent `HWND`. The `Bounds` property sizes and positions the WebView2 relative to the parent `HWND`. The visibility of WebView2 can be toggled by using `IsVisible`. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.Bounds Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.bounds#microsoft-web-webview2-core-corewebview2controller-bounds) -* [CoreWebView2Controller.IsVisible Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.isvisible) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.Bounds Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#bounds) -* [CoreWebView2Controller.IsVisible Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#isvisible) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::Bounds property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_bounds), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#put_bounds) -* [ICoreWebView2Controller::IsVisible property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_isvisible), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#put_isvisible) - ---- - - - -###### Zooming - -This section is part of Window management. This list is similar to [Zooming](./overview-features-apis.md#zooming) in _Overview of WebView2 features and APIs_. - -WebView2 `ZoomFactor` is used to scale just the web content. This is also updated when the user zooms the content through **Ctrl**+Mouse Wheel. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.ZoomFactor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.zoomfactor#microsoft-web-webview2-core-corewebview2controller-zoomfactor) -* [CoreWebView2Controller.ZoomFactorChanged Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.zoomfactorchanged) -* [CoreWebView2Controller.SetBoundsAndZoomFactor Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.setboundsandzoomfactor) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.ZoomFactor Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#zoomfactor) -* [CoreWebView2Controller.ZoomFactorChanged Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#zoomfactorchanged) -* [CoreWebView2Controller.SetBoundsAndZoomFactor Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#setboundsandzoomfactor) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::ZoomFactor property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_zoomfactor), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#put_zoomfactor) -* [ICoreWebView2Controller::ZoomFactorChanged event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller#add_zoomfactorchanged), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#remove_zoomfactorchanged) -* [ICoreWebView2Controller::SetBoundsAndZoomFactor method](/microsoft-edge/webview2/reference/win32/icorewebview2controller#setboundsandzoomfactor) - ---- - - - -###### Rasterization scale - -The `RasterizationScale` API scales all WebView2 UI including context menus, tooltip, and popups. The app can set whether the WebView2 should detect monitor scale changes and automatically update the `RasterizationScale`. `BoundsMode` is used to configure whether the `Bounds` property is interpreted as raw pixels, or DIPs (which need to be scaled by `RasterizationScale`). - -This list is similar to [Rasterization scale](./overview-features-apis.md#rasterization-scale) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.BoundsMode Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.boundsmode#microsoft-web-webview2-core-corewebview2controller-boundsmode) - * [CoreWebView2BoundsMode Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2boundsmode) -* [CoreWebView2Controller.RasterizationScale Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.rasterizationscale) -* [CoreWebView2Controller.RasterizationScaleChanged Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.rasterizationscalechanged) -* [CoreWebView2Controller.ShouldDetectMonitorScaleChanges Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.shoulddetectmonitorscalechanges) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.BoundsMode Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#boundsmode) - * [CoreWebView2BoundsMode Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2boundsmode) -* [CoreWebView2Controller.RasterizationScale Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#rasterizationscale) -* [CoreWebView2Controller.RasterizationScaleChanged Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#rasterizationscalechanged) -* [CoreWebView2Controller.ShouldDetectMonitorScaleChanges Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#shoulddetectmonitorscalechanges) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::BoundsMode property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller#get_bounds), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#put_bounds) - * [COREWEBVIEW2_BOUNDS_MODE enum](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_bounds_mode) -* [ICoreWebView2Controller::RasterizationScale property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#get_rasterizationscale), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#put_rasterizationscale) -* [ICoreWebView2Controller::RasterizationScaleChanged event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#add_rasterizationscalechanged), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#remove_rasterizationscalechanged) -* [ICoreWebView2Controller::ShouldDetectMonitorScaleChanges property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#get_shoulddetectmonitorscalechanges), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller3#put_rasterizationscale) - ---- - - - -###### Focus and tabbing - -WebView2 raises events to let the app know when it gains or loses focus. For tabbing, there's an API to move focus into WebView2, and an event for WebView2 to request the app to take focus back. - -This list is similar to [Focus and tabbing](./overview-features-apis.md#focus-and-tabbing) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.MoveFocus Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.movefocus) - * [CoreWebView2MoveFocusReason Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2movefocusreason) -* [CoreWebView2Controller.MoveFocusRequested Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.movefocusrequested) - * [CoreWebView2MoveFocusRequestedEventArgs Class](/dotnet/api/microsoft.web.webview2.core.corewebview2movefocusrequestedeventargs) -* [CoreWebView2Controller.GotFocus Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.gotfocus) -* [CoreWebView2Controller.LostFocus Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.lostfocus) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.MoveFocus Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#movefocus) - * [CoreWebView2MoveFocusReason Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2movefocusreason) -* [CoreWebView2Controller.MoveFocusRequested Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#movefocusrequested) - * [CoreWebView2MoveFocusRequestedEventArgs Class](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2movefocusrequestedeventargs) -* [CoreWebView2Controller.GotFocus Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#gotfocus) -* [CoreWebView2Controller.LostFocus Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#lostfocus) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::MoveFocus method](/microsoft-edge/webview2/reference/win32/icorewebview2controller#movefocus) - * [COREWEBVIEW2_MOVE_FOCUS_REASON enum](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_move_focus_reason) -* [ICoreWebView2Controller::MoveFocusRequested event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller#add_movefocusrequested), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#remove_movefocusrequested) - * [ICoreWebView2MoveFocusRequestedEventArgs interface](/microsoft-edge/webview2/reference/win32/icorewebview2movefocusrequestedeventargs) -* [ICoreWebView2Controller::GotFocus event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller#add_gotfocus), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#remove_gotfocus) -* [ICoreWebView2Controller::LostFocus event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller#add_lostfocus), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#remove_lostfocus) - ---- - - - -###### Parent window - -WebView2 can be re-parented to a different parent `HWND`. WebView2 also needs to be notified when the app's position on the screen changes. - -This list is similar to [Parent window](./overview-features-apis.md#parent-window) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.NotifyParentWindowPositionChanged Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.notifyparentwindowpositionchanged) -* [CoreWebView2Controller.ParentWindow Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.notifyparentwindowpositionchanged) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.NotifyParentWindowPositionChanged Method](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.notifyparentwindowpositionchanged) -* [CoreWebView2Controller.ParentWindow Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.parentwindow) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::NotifyParentWindowPositionChanged method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#notifyparentwindowpositionchanged) -* [ICoreWebView2Controller::ParentWindow property (get)](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2controller#parentwindow) - ---- - - - -###### Keyboard accelerators - -When WebView2 has focus, it receives input directly from the user. An app may want to intercept and handle certain accelerator key combinations or disable the normal browser accelerator key behaviors. - -This list is similar to [Keyboard accelerators](./overview-features-apis.md#keyboard-accelerators) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled Property](/dotnet/api/microsoft.web.webview2.core.corewebview2settings.arebrowseracceleratorkeysenabled) -* [CoreWebView2Controller.AcceleratorKeyPressed Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed) - * [CoreWebView2AcceleratorKeyPressedEventArgs Class](/dotnet/api/microsoft.web.webview2.core.corewebview2acceleratorkeypressedeventargs) - * [CoreWebView2KeyEventKind Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2keyeventkind) - * [CoreWebView2PhysicalKeyStatus Struct](/dotnet/api/microsoft.web.webview2.core.corewebview2physicalkeystatus) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Settings.AreBrowserAcceleratorKeysEnabled Property](/dotnet/api/microsoft.web.webview2.core.corewebview2settings.arebrowseracceleratorkeysenabled) -* [CoreWebView2Controller.AcceleratorKeyPressed Event](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.acceleratorkeypressed) - * [CoreWebView2AcceleratorKeyPressedEventArgs Class](/dotnet/api/microsoft.web.webview2.core.corewebview2acceleratorkeypressedeventargs) - * [CoreWebView2KeyEventKind Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2keyeventkind) - * [CoreWebView2PhysicalKeyStatus Struct](/dotnet/api/microsoft.web.webview2.core.corewebview2physicalkeystatus) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Settings::AreBrowserAcceleratorKeysEnabled property (get](/microsoft-edge/webview2/reference/win32/icorewebview2settings3#get_arebrowseracceleratorkeysenabled), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2settings3#put_arebrowseracceleratorkeysenabled) -* [ICoreWebView2Controller::AcceleratorKeyPressed event (add](/microsoft-edge/webview2/reference/win32/icorewebview2controller#add_acceleratorkeypressed), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2controller#remove_acceleratorkeypressed) - * [ICoreWebView2AcceleratorKeyPressedEventArgs class](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2acceleratorkeypressedeventargs) - * [ICoreWebView2KeyEventKind enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2keyeventkind) - * [ICoreWebView2PhysicalKeyStatus struct](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2physicalkeystatus) - ---- - - - -###### Default background color - -WebView2 can specify a default background color. This can be any opaque color or transparent color. This color will be used if the webpage doesn't set a background color, or sets a transparent background color. - -This list is similar to [Default background color](./overview-features-apis.md#default-background-color) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2Controller.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.defaultbackgroundcolor) - * [CoreWebView2Color Struct](/dotnet/api/microsoft.web.webview2.core.corewebview2color) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2Controller.DefaultBackgroundColor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2controller.defaultbackgroundcolor#microsoft-web-webview2-core-corewebview2controller-defaultbackgroundcolor) - * [CoreWebView2Color Struct](/dotnet/api/microsoft.web.webview2.core.corewebview2color) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2Controller::DefaultBackgroundColor property (get](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#get_defaultbackgroundcolor), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2controller2#put_defaultbackgroundcolor) - * [COREWEBVIEW2_COLOR struct](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_color) - ---- - - - -## Visual hosting - -In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). - -If your WebView2 app uses Visual hosting: - -* Inputs are routed to the app's `HWND` and must be configured to send the spatial input (for example, mouse, touch, and pen) based on positions, _not_ what currently has focus, such as a keyboard. - - - -#### APIs for Visual hosting - -The following APIs can be used when configuring WebView2 in a Visual hosting environment: - - - - -###### Composition-based rendering - -For composition-based WebView2 rendering, use the `CoreWebView2Environment` to create a `CoreWebView2CompositionController`. The `CoreWebView2CompositionController` implements all the APIs as `CoreWebView2Controller`, but includes additional APIs specific to composition-based rendering. - -This list is similar to [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2CompositionController Class](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller) -* [CoreWebView2Environment.CreateCoreWebView2CompositionControllerAsync Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createcorewebview2compositioncontrollerasync) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2CompositionController Class](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller) -* [CoreWebView2Environment.CreateCoreWebView2CompositionControllerAsync Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createcorewebview2compositioncontrollerasync) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2CompositionController interface](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller) -* [ICoreWebView2Environment::CreateCoreWebView2CompositionController method](/microsoft-edge/webview2/reference/win32/icorewebview2environment3#createcorewebview2compositioncontroller) - ---- - - - -###### Output - -WebView2 can connect its composition tree to `IDCompositionVisual`, `IDCompositionTarget`, or `Windows::UI::Composition::ContainerVisual`. - -This list is similar to [Connecting to the visual tree](./overview-features-apis.md#connecting-to-the-visual-tree) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2CompositionController.RootVisualTarget Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.rootvisualtarget) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2CompositionController.RootVisualTarget Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.rootvisualtarget) - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2CompositionController::RootVisualTarget property (get](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#get_rootvisualtarget), [put)](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#put_rootvisualtarget) - ---- - - - -###### Input - -Spatial input such as mouse, touch, or pen is received by the app and must be sent to WebView2. WebView2 notifies the app when the cursor should be updated based on the input device's position. - -This list is similar to [Forwarding input](./overview-features-apis.md#forwarding-input) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -* [CoreWebView2CompositionController.Cursor Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.cursor) -* [CoreWebView2CompositionController.CursorChanged Event](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.cursorchanged) -* [CoreWebView2CompositionController.SystemCursorId Property](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.systemcursorid) -* [CoreWebView2CompositionController.SendMouseInput Method](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.sendmouseinput) - * [CoreWebView2MouseEventKind Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2mouseeventkind) - * [CoreWebView2MouseEventVirtualKeys Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2mouseeventvirtualkeys) -* [CoreWebView2CompositionController.SendPointerInput Method](/dotnet/api/microsoft.web.webview2.core.corewebview2compositioncontroller.sendpointerinput) - * [CoreWebView2PointerEventKind Enum](/dotnet/api/microsoft.web.webview2.core.corewebview2pointereventkind) -* [CoreWebView2Environment.CreateCoreWebView2PointerInfo Method](/dotnet/api/microsoft.web.webview2.core.corewebview2environment.createcorewebview2pointerinfo) - * [CoreWebView2PointerInfo Class](/dotnet/api/microsoft.web.webview2.core.corewebview2pointerinfo) - -##### [WinRT/C#](#tab/winrtcsharp) - -* [CoreWebView2CompositionController.Cursor Property](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2compositioncontroller#cursor) -* [CoreWebView2CompositionController.CursorChanged Event](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2compositioncontroller#cursorchanged) -* [CoreWebView2CompositionController.SendMouseInput Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2compositioncontroller#sendmouseinput) - * [CoreWebView2MouseEventKind Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2mouseeventkind) - * [CoreWebView2MouseEventVirtualKeys Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2mouseeventvirtualkeys) -* [CoreWebView2CompositionController.SendPointerInput Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2compositioncontroller#sendpointerinput) - * [CoreWebView2PointerEventKind Enum](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2mouseeventkind) -* [CoreWebView2Environment.CreateCoreWebView2PointerInfo Method](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environment#createcorewebview2pointerinfo) - * [CoreWebView2PointerInfo Class](/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2pointerinfo) - - - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2CompositionController::Cursor property (get)](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#get_cursor) -* [ICoreWebView2CompositionController::CursorChanged event (add](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#add_cursorchanged), [remove)](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#remove_cursorchanged) -* [ICoreWebView2CompositionController::SystemCursorId property (get)](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#get_systemcursorid) -* [ICoreWebView2CompositionController::SendMouseInput method](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#sendmouseinput) - * [COREWEBVIEW2_MOUSE_EVENT_KIND enum](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_mouse_event_kind) - * [COREWEBVIEW2_MOUSE_EVENT_VIRTUAL_KEYS enum](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_mouse_event_virtual_keys) -* [ICoreWebView2CompositionController::SendPointerInput method](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller#sendpointerinput) - * [COREWEBVIEW2_POINTER_EVENT_KIND enum](/microsoft-edge/webview2/reference/win32/icorewebview2#corewebview2_pointer_event_kind) -* [ICoreWebView2Environment::CreateCoreWebView2PointerInfo method](/microsoft-edge/webview2/reference/win32/icorewebview2environment3#createcorewebview2pointerinfo) - * [ICoreWebView2PointerInfo interface](/microsoft-edge/webview2/reference/win32/icorewebview2pointerinfo) - ---- - - - -###### Accessibility - -By default, WebView2 will show up in the accessibility tree as a child of the parent `HWND`. WebView2 provides an API to better position the WebView2 content relative to other elements in the app. - -This list is similar to [Accessibility](./overview-features-apis.md#accessibility) in _Overview of WebView2 features and APIs_. - -##### [.NET/C#](#tab/dotnetcsharp) - -Not applicable. - -##### [WinRT/C#](#tab/winrtcsharp) - -Not applicable. - -##### [Win32/C++](#tab/win32cpp) - -* [ICoreWebView2CompositionController::AutomationProvider property (get)](/microsoft-edge/webview2/reference/win32/icorewebview2compositioncontroller2#get_automationprovider) -* [ICoreWebView2Environment::GetAutomationProviderForWindow method](/microsoft-edge/webview2/reference/win32/icorewebview2environment4#getautomationproviderforwindow) - ---- - - ## See also @@ -540,3 +133,4 @@ Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. +* [Composition visual](/windows/uwp/composition/composition-visual-tree) in Windows App Development > UWP docs. From f09366c693cd65cc31ed2992c66010b49e6e6bbd Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 18:29:10 -0700 Subject: [PATCH 11/37] edit pass after API tabsets removed --- .../concepts/windowed-vs-visual-hosting.md | 73 +++++++++++++------ 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 0956ee3099..3d3a0d4f48 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -6,7 +6,7 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: webview -ms.date: 09/18/2024 +ms.date: 09/23/2024 --- # Windowed vs. Visual hosting of WebView2 @@ -15,7 +15,9 @@ There are three options for hosting the Microsoft Edge WebView2 control in your * The Window to Visual hosting mode. * The Visual hosting mode. -If you use Windowed hosting, which is a good starting point for most apps, you don't need to read this article. Read this article if you want to provide a more custom user experience (UX) and want to use Visual hosting, or if you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. +You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: +* If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. +* If you want to provide a more custom user experience (UX) and want to use Visual hosting. | Approach | Description | Optimized for | |---|---|---| @@ -23,9 +25,10 @@ If you use Windowed hosting, which is a good starting point for most apps, you d | Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | -These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than Visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and Visual hosting has additional requirements for it to render properly. The API calls are listed in the following sections below: -* [Windowed hosting and Window to Visual hosting](#windowed-hosting-and-window-to-visual-hosting) -* [Visual hosting](#visual-hosting) +These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than Visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and Visual hosting has additional requirements for it to render properly. The API lists are linked to in the sections below: +* [APIs for Windowed hosting](#apis-for-windowed-hosting) +* [APIs for Window to Visual hosting](#apis-for-window-to-visual-hosting) +* [APIs for Visual hosting](#apis-for-visual-hosting) @@ -37,28 +40,39 @@ The different approaches for hosting the WebView2 control in your app are simila #### Windowed hosting: For displaying content quickly and easily -_Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window ie. an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. +_Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window; that is, an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. + +The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. + +For general information about Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). -For general information regarding Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). ###### Advantages * Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. -* Zooming and rasterization scales (for example, menus, context menus, and so on) will automatically scale to the app's parent `HWND`. It also handles how the WebView manages being focused and tabbing in/out of itself when it reaches the final element. +* Zooming and rasterization scales (such as menus and context menus) automatically scale to the app's parent `HWND`. Windowed hosting also handles how the WebView control manages being focused and tabbing in/out of itself when it reaches the final element. + +* The app handles keyboard accelerators and keyboard shortcuts when focus is the WebView. For example, pressing **Ctrl+C** in a WebView will be interpreted as trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. -* The app handles keyboard accelerators and keyboard shortcuts when in the WebView. For example, **Ctrl+C** in a WebView will know that you are trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. +* You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. -* You don't have to manage the various composition-based rendering (for example, Inputs, Outputs, and Accessibility controls) if you don't want to. ###### Disadvantages Windowed hosting mode can run into DPI issues in some scenarios, such as sharing a user data folder across different applications. + + +###### APIs for Windowed hosting + +For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. + + -#### Window to Visual hosting: For a similar experience as Windowed hosting with added benefits and tradeoff +#### Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff _Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI issues that can result when using Windowed mode. @@ -66,28 +80,34 @@ Window to Visual hosting does not require use of the Visual hosting APIs. To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. -In both Window-to-Visual and Visual hosting, a _visual_ is defined as a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are: `DirectComposition` and `Windows.UI.Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are visuals that are exposed through the aforementioned APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) For more information see [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs and [Composition visual](/windows/uwp/composition/composition-visual-tree) Windows App Development > UWP docs. +In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are `DirectComposition` and `Windows.UI.Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are visuals that are exposed through the `DirectComposition` and `Windows.UI.Composition` APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See: +* [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. +* [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. + ###### Advantages -* Different apps that share a WebView2 user data folder can have different DPI awarenesses. +* Different apps that share a WebView2 user data folder can have different DPI awareness. * Different apps that share a WebView2 user data folder can have different integrity levels. * Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. -* Changing monitor scale when hosting a WebView2 in a VSTO add-in no longer sporadically hang the application. +* Changing monitor scale when hosting a WebView2 in a VSTO Add-in no longer sporadically hang the application. See [VSTO Add-ins](https://learn.microsoft.com/en-us/visualstudio/vsto/office-solutions-development-overview-vsto?view=vs-2022#vsto-add-ins) in _Office solutions development overview (VSTO)_. + ###### Disadvantages Enabling Window to Visual hosting mode removes support for pen input and handwriting. - -###### APIs for Windowed hosting and Window to Visual hosting -For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps). + +###### APIs for Window to Visual hosting + +For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. + #### Visual hosting: For more granular control over layout @@ -96,32 +116,37 @@ When using _Visual hosting_, your host app takes spatial input (such as mouse or In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). -If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (for example, mouse, touch, and pen) based on positions, _not_ what currently has focus, such as a keyboard. +If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ what currently has focus, such as a keyboard. + ###### Advantages and disadvantages Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. -With Visual hosting, for example you must choose how when the user resizes the window, how the webview scales in relation to the whole page - for example, if you want the webview to scale twice as much as the app. +For example, with Visual hosting, when the user resizes the window, you must define how the WebView control scales in relation to the whole webpage, such as making the WebView scale twice as much as the app. - + + ###### APIs for Visual hosting -For a list of APIs that can be used when configuring WebView2 in a visual hosting environment, see [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition). +For a list of APIs that can be used when configuring WebView2 in a Visual hosting environment, see [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition) in _Overview of WebView2 features and APIs_. + ## Compatibility and constraints Key compatibility limitations include the operating system and rendering in framework and non-framework apps. + #### Operating systems -All hosting modes are supported wherever WebView2 is supported ie. Windows 10 and up and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported. For those still on those platforms Windows 7 and Windows 8 can only do Windowed hosting, not Visual hosting. +All hosting modes are supported wherever WebView2 is supported; that is, Windows 10 and up, and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported; Windows 7 and Windows 8 only support Windowed hosting, not Visual hosting. See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. + ## See also @@ -131,6 +156,6 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. -* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. -* [Composition visual](/windows/uwp/composition/composition-visual-tree) in Windows App Development > UWP docs. +* [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. From 64a7252daa13d3ea4a46d7f629600f953d55b272 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 18:37:56 -0700 Subject: [PATCH 12/37] missing: focus is *on* the WebView --- .../webview2/concepts/windowed-vs-visual-hosting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 3d3a0d4f48..fe9926564a 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -54,7 +54,7 @@ For general information about Window management and `HWND` functionality, see [A * Zooming and rasterization scales (such as menus and context menus) automatically scale to the app's parent `HWND`. Windowed hosting also handles how the WebView control manages being focused and tabbing in/out of itself when it reaches the final element. -* The app handles keyboard accelerators and keyboard shortcuts when focus is the WebView. For example, pressing **Ctrl+C** in a WebView will be interpreted as trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. +* The app handles keyboard accelerators and keyboard shortcuts when focus is on the WebView. For example, pressing **Ctrl+C** in a WebView will be interpreted as trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. * You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. @@ -68,7 +68,7 @@ Windowed hosting mode can run into DPI issues in some scenarios, such as sharing ###### APIs for Windowed hosting -For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. +For a list of APIs that can be used when configuring WebView2 for Windowed hosting (or for Window to Visual hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. @@ -106,7 +106,7 @@ Enabling Window to Visual hosting mode removes support for pen input and handwri ###### APIs for Window to Visual hosting -For a list of APIs that can be used when configuring WebView2 for Windowed hosting or Window to Visual hosting, see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. +For a list of APIs that can be used when configuring WebView2 Window to Visual hosting (or for Windowed hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. @@ -116,7 +116,7 @@ When using _Visual hosting_, your host app takes spatial input (such as mouse or In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). -If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ what currently has focus, such as a keyboard. +If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ based on what currently has focus, such as a keyboard. @@ -142,7 +142,7 @@ Key compatibility limitations include the operating system and rendering in fram #### Operating systems -All hosting modes are supported wherever WebView2 is supported; that is, Windows 10 and up, and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported; Windows 7 and Windows 8 only support Windowed hosting, not Visual hosting. +All hosting modes are supported wherever WebView2 is supported; that is, Windows 10 and later, and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported; Windows 7 and Windows 8 only support Windowed hosting, not Visual hosting. See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. From 98ff9a8f87e4988ec0b89e2687b3530a9f43af24 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 18:43:29 -0700 Subject: [PATCH 13/37] ## linkfix --- .../webview2/concepts/windowed-vs-visual-hosting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index fe9926564a..86c2b8f4b1 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -94,7 +94,7 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical * Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. -* Changing monitor scale when hosting a WebView2 in a VSTO Add-in no longer sporadically hang the application. See [VSTO Add-ins](https://learn.microsoft.com/en-us/visualstudio/vsto/office-solutions-development-overview-vsto?view=vs-2022#vsto-add-ins) in _Office solutions development overview (VSTO)_. +* Changing monitor scale when hosting a WebView2 in a VSTO Add-in no longer sporadically hang the application. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. @@ -106,7 +106,7 @@ Enabling Window to Visual hosting mode removes support for pen input and handwri ###### APIs for Window to Visual hosting -For a list of APIs that can be used when configuring WebView2 Window to Visual hosting (or for Windowed hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md##rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. +For a list of APIs that can be used when configuring WebView2 Window to Visual hosting (or for Windowed hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. From 3ce0797cff23061795d26f2acebebe72283cd57d Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 18:56:16 -0700 Subject: [PATCH 14/37] promoted to h2s, linked from table --- .../concepts/windowed-vs-visual-hosting.md | 64 ++++++++++--------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 86c2b8f4b1..05339f3e91 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -19,26 +19,28 @@ You don't need to read this article if you use Windowed hosting in most scenario * If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. * If you want to provide a more custom user experience (UX) and want to use Visual hosting. +The different approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements, as follows: + | Approach | Description | Optimized for | |---|---|---| -| Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | -| Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | +| [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily) | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | +| [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff) | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout) | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | + +These approaches have different requirements, constraints, and benefits. +* Windowed hosting is simpler to implement than Visual hosting. +* Visual hosting requires all the API calls that Windowed hosting requires, and has additional requirements for it to render properly. + +Details are below. -These approaches have different requirements, constraints, and benefits. Windowed hosting is simpler to implement than Visual hosting. Visual hosting requires all the API calls that Windowed hosting requires, and Visual hosting has additional requirements for it to render properly. The API lists are linked to in the sections below: +The supported API lists are linked to in the sections below: * [APIs for Windowed hosting](#apis-for-windowed-hosting) * [APIs for Window to Visual hosting](#apis-for-window-to-visual-hosting) * [APIs for Visual hosting](#apis-for-visual-hosting) -## Scenarios for selecting the hosting approach - -The different approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements. - - - -#### Windowed hosting: For displaying content quickly and easily +## Windowed hosting: For displaying content quickly and easily _Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window; that is, an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. @@ -47,8 +49,8 @@ The benefit of this is that some of the Input/Output commands are handled for yo For general information about Window management and `HWND` functionality, see [About Windows](/windows/win32/winmsg/about-windows). - -###### Advantages + +#### Advantages * Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. @@ -59,20 +61,20 @@ For general information about Window management and `HWND` functionality, see [A * You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. - -###### Disadvantages + +#### Disadvantages Windowed hosting mode can run into DPI issues in some scenarios, such as sharing a user data folder across different applications. - -###### APIs for Windowed hosting + +#### APIs for Windowed hosting For a list of APIs that can be used when configuring WebView2 for Windowed hosting (or for Window to Visual hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. - -#### Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff + +## Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff _Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI issues that can result when using Windowed mode. @@ -85,8 +87,8 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical * [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. - -###### Advantages + +#### Advantages * Different apps that share a WebView2 user data folder can have different DPI awareness. @@ -97,20 +99,20 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical * Changing monitor scale when hosting a WebView2 in a VSTO Add-in no longer sporadically hang the application. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. - -###### Disadvantages + +#### Disadvantages Enabling Window to Visual hosting mode removes support for pen input and handwriting. - -###### APIs for Window to Visual hosting + +#### APIs for Window to Visual hosting For a list of APIs that can be used when configuring WebView2 Window to Visual hosting (or for Windowed hosting), see [Rendering WebView2 in non-framework apps](./overview-features-apis.md#rendering-webview2-in-non-framework-apps) in _Overview of WebView2 features and APIs_. - -#### Visual hosting: For more granular control over layout + +## Visual hosting: For more granular control over layout When using _Visual hosting_, your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. @@ -119,16 +121,16 @@ In Visual hosting, content is embedded to a given location on the application. T If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ based on what currently has focus, such as a keyboard. - -###### Advantages and disadvantages + +#### Advantages and disadvantages Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. For example, with Visual hosting, when the user resizes the window, you must define how the WebView control scales in relation to the whole webpage, such as making the WebView scale twice as much as the app. - -###### APIs for Visual hosting + +#### APIs for Visual hosting For a list of APIs that can be used when configuring WebView2 in a Visual hosting environment, see [Rendering WebView2 using Composition](./overview-features-apis.md#rendering-webview2-using-composition) in _Overview of WebView2 features and APIs_. From 6a669951b5e2e148bbabfa502496063bf7b326aa Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 19:19:33 -0700 Subject: [PATCH 15/37] move long h2 links from table to topmost list --- .../concepts/windowed-vs-visual-hosting.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 05339f3e91..b6ec31b87d 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -11,9 +11,11 @@ ms.date: 09/23/2024 # Windowed vs. Visual hosting of WebView2 There are three options for hosting the Microsoft Edge WebView2 control in your app: -* The Windowed hosting mode. -* The Window to Visual hosting mode. -* The Visual hosting mode. +* [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily) +* [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff) +* [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout) + +Details are below. You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: * If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. @@ -23,16 +25,14 @@ The different approaches for hosting the WebView2 control in your app are simila | Approach | Description | Optimized for | |---|---|---| -| [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily) | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff) | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | -| [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout) | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | +| Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | +| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. * Windowed hosting is simpler to implement than Visual hosting. * Visual hosting requires all the API calls that Windowed hosting requires, and has additional requirements for it to render properly. -Details are below. - The supported API lists are linked to in the sections below: * [APIs for Windowed hosting](#apis-for-windowed-hosting) * [APIs for Window to Visual hosting](#apis-for-window-to-visual-hosting) From 1d0c69ab2b9202efcce18fee2d19d9d14d596642 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 19:23:03 -0700 Subject: [PATCH 16/37] . --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b6ec31b87d..0d50f09fe5 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -11,9 +11,9 @@ ms.date: 09/23/2024 # Windowed vs. Visual hosting of WebView2 There are three options for hosting the Microsoft Edge WebView2 control in your app: -* [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily) -* [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff) -* [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout) +* [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily). +* [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff). +* [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout). Details are below. From 4b4c791e913b0982ef0fb9375dc4d7f99a932edf Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Mon, 23 Sep 2024 19:26:44 -0700 Subject: [PATCH 17/37] DPI: consider Window to Visual hosting --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 0d50f09fe5..9d67ff69bc 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -18,7 +18,7 @@ There are three options for hosting the Microsoft Edge WebView2 control in your Details are below. You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: -* If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. +* If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. In that case, consider Window to Visual hosting. * If you want to provide a more custom user experience (UX) and want to use Visual hosting. The different approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements, as follows: From ae9919ef5e98d1afdf63ec206816c84b13149efe Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Tue, 24 Sep 2024 07:00:02 -0700 Subject: [PATCH 18/37] apply champnic cmts --- .../concepts/windowed-vs-visual-hosting.md | 58 +++++++++++++------ 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 9d67ff69bc..e1dbd6ee8d 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -15,8 +15,6 @@ There are three options for hosting the Microsoft Edge WebView2 control in your * [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff). * [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout). -Details are below. - You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: * If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. In that case, consider Window to Visual hosting. * If you want to provide a more custom user experience (UX) and want to use Visual hosting. @@ -29,6 +27,13 @@ The different approaches for hosting the WebView2 control in your app are simila | Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | + + These approaches have different requirements, constraints, and benefits. * Windowed hosting is simpler to implement than Visual hosting. * Visual hosting requires all the API calls that Windowed hosting requires, and has additional requirements for it to render properly. @@ -42,7 +47,7 @@ The supported API lists are linked to in the sections below: ## Windowed hosting: For displaying content quickly and easily -_Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window; that is, an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView component to access web content. +_Windowed hosting_ means that in your app, WebView2 content is hosted directly in a window; that is, an HWND. The WebView2 HWND inherits many default properties from the operating system (OS). The WebView2 control takes input from the OS, and the OS sends the input to the WebView2 control. You can have multiple HWNDs in your app that will each be used as a WebView2 component to access web content. The benefit of this is that some of the Input/Output commands are handled for you by the OS or by the framework. However, you will still need to handle some aspects of window management. @@ -52,11 +57,13 @@ For general information about Window management and `HWND` functionality, see [A #### Advantages -* Windowed hosting allows for a solution that quickly displays web content without having to include features for inputs, outputs, and accessibility. +* Windowed hosting allows for a solution that quickly displays web content without having to implement functionality for inputs, outputs, and accessibility. + +* Owned and child windows (such as menus and context menus) automatically scale to match the app's parent `HWND` scaling. -* Zooming and rasterization scales (such as menus and context menus) automatically scale to the app's parent `HWND`. Windowed hosting also handles how the WebView control manages being focused and tabbing in/out of itself when it reaches the final element. +* Windowed hosting handles how the WebView2 control manages being focused and tabbing in or out of itself when pressing **Tab** reaches the final element. -* The app handles keyboard accelerators and keyboard shortcuts when focus is on the WebView. For example, pressing **Ctrl+C** in a WebView will be interpreted as trying to copy content in the WebView, and not pressing **Ctrl** and **C** separately. +* The app handles keyboard accelerators and keyboard shortcuts when focus is on the WebView2. For example, pressing **Ctrl+C** in a WebView2 will be interpreted as trying to copy content in the WebView2, not interpreted as pressing **Ctrl** and **C** separately. * You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. @@ -64,7 +71,7 @@ For general information about Window management and `HWND` functionality, see [A #### Disadvantages -Windowed hosting mode can run into DPI issues in some scenarios, such as sharing a user data folder across different applications. +Windowed hosting mode can run into DPI issues in some scenarios, such as when sharing a user data folder (and therefor sharing a browser process) across different applications with different DPI awareness. @@ -76,11 +83,11 @@ For a list of APIs that can be used when configuring WebView2 for Windowed hosti ## Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff -_Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI issues that can result when using Windowed mode. +_Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI and input issues that can result when using Windowed mode. -Window to Visual hosting does not require use of the Visual hosting APIs. +Window to Visual hosting does not require you to use WebView2 Visual hosting APIs. -To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL`. +To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL` before initializing your WebView2. In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are `DirectComposition` and `Windows.UI.Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are visuals that are exposed through the `DirectComposition` and `Windows.UI.Composition` APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See: * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. @@ -94,15 +101,20 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical * Different apps that share a WebView2 user data folder can have different integrity levels. -* Different apps that share a WebView2 user data folder will no longer be able to cause each other to hang. +* Different apps that share a WebView2 user data folder won't potentially cause each other to hang. -* Changing monitor scale when hosting a WebView2 in a VSTO Add-in no longer sporadically hang the application. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. +* Changing monitor scale when hosting a WebView2 in a VSTO Add-in doesn't sporadically hang the application. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. + #### Disadvantages -Enabling Window to Visual hosting mode removes support for pen input and handwriting. +Enabling Window to Visual hosting mode removes support for Windows Shell Handwriting (pen input) within the WebView2. @@ -114,19 +126,29 @@ For a list of APIs that can be used when configuring WebView2 Window to Visual h ## Visual hosting: For more granular control over layout -When using _Visual hosting_, your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. +When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. -In Visual hosting, content is embedded to a given location on the application. This location must handle how content will scale and behave in an app when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting will need the app to manage the composition-based rendering, when it receives any user interactions. For more information about Visual hosting, see [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps). +In Visual hosting, content is embedded at a given location in the application. This location must handle how content will scale and behave when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting requires the app to manage the composition-based rendering when it receives any user interactions. If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ based on what currently has focus, such as a keyboard. +If your WebView2 app uses Visual hosting, spatial inputs (such as mouse, touch, or pen) are sent to the app's `HWND`, not sent directly to the WebView2. The app should forward this spatial input to the WebView2 if the position of the input is over the WebView2, _not_ based on what currently has focus. + +See also: +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) in Windows > App development docs. + #### Advantages and disadvantages Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. -For example, with Visual hosting, when the user resizes the window, you must define how the WebView control scales in relation to the whole webpage, such as making the WebView scale twice as much as the app. +For example, when the user resizes the window, you must define how the WebView2 control scales in relation to the whole webpage, such as making the WebView2 scale twice as much as the app. + @@ -138,7 +160,7 @@ For a list of APIs that can be used when configuring WebView2 in a Visual hostin ## Compatibility and constraints -Key compatibility limitations include the operating system and rendering in framework and non-framework apps. +Key compatibility limitations include the operating system and rendering in framework and non-framework apps. @@ -158,6 +180,6 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. -* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) in Windows > App development docs. * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. * [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. From e1ecec7bfaab41909bdcd11cfa1220a917ace9bf Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 13:57:37 -0700 Subject: [PATCH 19/37] unlink initial list of modes --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index e1dbd6ee8d..a8c103c80a 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -11,9 +11,9 @@ ms.date: 09/23/2024 # Windowed vs. Visual hosting of WebView2 There are three options for hosting the Microsoft Edge WebView2 control in your app: -* [Windowed hosting: For displaying content quickly and easily](#windowed-hosting-for-displaying-content-quickly-and-easily). -* [Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff](#window-to-visual-hosting-for-a-similar-experience-as-windowed-hosting-with-added-benefits-and-tradeoff). -* [Visual hosting: For more granular control over layout](#visual-hosting-for-more-granular-control-over-layout). +* The Windowed hosting mode. +* The Window to Visual hosting mode. +* The Visual hosting mode. You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: * If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. In that case, consider Window to Visual hosting. From 2ca4895993c40b4fd34919550de7c99286ff9660 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:03:07 -0700 Subject: [PATCH 20/37] clarify cases recomm --- .../webview2/concepts/windowed-vs-visual-hosting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index a8c103c80a..5b5c52e2a7 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -16,8 +16,8 @@ There are three options for hosting the Microsoft Edge WebView2 control in your * The Visual hosting mode. You don't need to read this article if you use Windowed hosting in most scenarios. Windowed hosting is a good starting point for most apps. Read this article: -* If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. In that case, consider Window to Visual hosting. -* If you want to provide a more custom user experience (UX) and want to use Visual hosting. +* If you are using Windowed hosting in uncommon scenarios and are experiencing persistent issues with DPI and scaling. In this case, consider Window to Visual hosting. +* If you want to provide a more custom user experience (UX). In this case, consider Visual hosting. The different approaches for hosting the WebView2 control in your app are similar in functionality, but they suit different needs depending on the app requirements, as follows: From 7654254047e949f13983094cc1a2037035549c87 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:09:04 -0700 Subject: [PATCH 21/37] consistent ext links --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 5b5c52e2a7..b66d96bb31 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -180,6 +180,6 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. -* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) in Windows > App development docs. -* [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. -* [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows > App development docs. +* [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition docs. +* [Composition visual](/windows/uwp/composition/composition-visual-tree) - Windows App Development > UWP docs. From 336e2236478e37e0983bed97fac57a5a8aa6c00b Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:11:10 -0700 Subject: [PATCH 22/37] trim needless "docs" in ext links list --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b66d96bb31..b586ade56a 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -180,6 +180,6 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. -* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows > App development docs. -* [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition docs. -* [Composition visual](/windows/uwp/composition/composition-visual-tree) - Windows App Development > UWP docs. +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows > App development. +* [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition. +* [Composition visual](/windows/uwp/composition/composition-visual-tree) - Windows App Development > UWP. From b1034cb38d1d549179288b04f0d5b73326dbfda5 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:15:26 -0700 Subject: [PATCH 23/37] simplify/consistent ext link docset --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b586ade56a..b02870c678 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -180,6 +180,6 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Other doc sets: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. -* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows > App development. +* [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows App Development. * [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition. * [Composition visual](/windows/uwp/composition/composition-visual-tree) - Windows App Development > UWP. From 97b62db5c2d331d8578c69871ede4bd82deb0134 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:18:48 -0700 Subject: [PATCH 24/37] remove keyboard accel list item --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b02870c678..5a13f2a584 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -63,8 +63,6 @@ For general information about Window management and `HWND` functionality, see [A * Windowed hosting handles how the WebView2 control manages being focused and tabbing in or out of itself when pressing **Tab** reaches the final element. -* The app handles keyboard accelerators and keyboard shortcuts when focus is on the WebView2. For example, pressing **Ctrl+C** in a WebView2 will be interpreted as trying to copy content in the WebView2, not interpreted as pressing **Ctrl** and **C** separately. - * You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. From c7ee6e8d3c79031137d03410d6363860cf078aca Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 25 Sep 2024 14:23:24 -0700 Subject: [PATCH 25/37] "External:" more transparent than "doc sets" --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 5a13f2a584..f5b8ed221b 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -176,7 +176,7 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft * [Overview of WebView2 features and APIs](./overview-features-apis.md) * [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. -Other doc sets: +External: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows App Development. * [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition. From b748a09c341c97608418575fa4b7d60bf9f85db3 Mon Sep 17 00:00:00 2001 From: "John An (from Dev Box)" Date: Wed, 25 Sep 2024 18:53:23 -0700 Subject: [PATCH 26/37] Updating references to pen input to be Windows Shell Handwriting --- .../concepts/windowed-vs-visual-hosting.md | 26 +++++-------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index e1dbd6ee8d..4ccf64055d 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -24,19 +24,12 @@ The different approaches for hosting the WebView2 control in your app are simila | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that pen input and handwriting is unsupported. | +| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that the Windows Shell Handwriting experience is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | - - These approaches have different requirements, constraints, and benefits. * Windowed hosting is simpler to implement than Visual hosting. -* Visual hosting requires all the API calls that Windowed hosting requires, and has additional requirements for it to render properly. +* Visual hosting requires all the API calls that Windowed hosting requires, and has additional requirements for it to render properly. The supported API lists are linked to in the sections below: * [APIs for Windowed hosting](#apis-for-windowed-hosting) @@ -63,8 +56,6 @@ For general information about Window management and `HWND` functionality, see [A * Windowed hosting handles how the WebView2 control manages being focused and tabbing in or out of itself when pressing **Tab** reaches the final element. -* The app handles keyboard accelerators and keyboard shortcuts when focus is on the WebView2. For example, pressing **Ctrl+C** in a WebView2 will be interpreted as trying to copy content in the WebView2, not interpreted as pressing **Ctrl** and **C** separately. - * You don't have to manage the various composition-based rendering controls (such as Inputs, Outputs, and Accessibility controls) if you don't want to. @@ -103,18 +94,13 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical * Different apps that share a WebView2 user data folder won't potentially cause each other to hang. -* Changing monitor scale when hosting a WebView2 in a VSTO Add-in doesn't sporadically hang the application. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. - +* When hosting a WebView2 in a VSTO Add-in, changing monitor scale won't potentially cause the app to hang. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. #### Disadvantages -Enabling Window to Visual hosting mode removes support for Windows Shell Handwriting (pen input) within the WebView2. +Enabling Window to Visual hosting mode removes support for Windows Shell Handwriting within the WebView2. @@ -128,7 +114,7 @@ For a list of APIs that can be used when configuring WebView2 Window to Visual h When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. -In Visual hosting, content is embedded at a given location in the application. This location must handle how content will scale and behave when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting requires the app to manage the composition-based rendering when it receives any user interactions. +In Visual hosting, WebView2 content is embedded at a given location in the application. This location must handle how content will scale and behave when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting requires the app to manage the composition-based rendering when it receives any user interactions. If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ based on what currently has focus, such as a keyboard. @@ -160,7 +146,7 @@ For a list of APIs that can be used when configuring WebView2 in a Visual hostin ## Compatibility and constraints -Key compatibility limitations include the operating system and rendering in framework and non-framework apps. +Key compatibility limitations include the operating system and rendering in framework and non-framework apps. From 71c5a0f27f881472c71810c3e5ee237ada560ef5 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Thu, 26 Sep 2024 09:34:10 -0700 Subject: [PATCH 27/37] a Visual --- .../webview2/concepts/windowed-vs-visual-hosting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 4082d6f23b..66e5490457 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -24,7 +24,7 @@ The different approaches for hosting the WebView2 control in your app are simila | Approach | Description | Optimized for | |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | -| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that the Windows Shell Handwriting experience is unsupported. | +| Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a Visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that the Windows Shell Handwriting experience is unsupported. | | Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. @@ -74,7 +74,7 @@ For a list of APIs that can be used when configuring WebView2 for Windowed hosti ## Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff -_Window-to-Visual hosting_ means that the WebView2 content is output to a visual that is hosted in an HWND, rather than outputting content to a window directly or to a visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a visual, it avoids some DPI and input issues that can result when using Windowed mode. +_Window-to-Visual hosting_ means that the WebView2 content is output to a Visual that is hosted in an HWND, rather than outputting content to a window directly or to a Visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a Visual, it avoids some DPI and input issues that can result when using Windowed mode. Window to Visual hosting does not require you to use WebView2 Visual hosting APIs. From cffdc7d9ff211aaefb9ad414db135d9aa213b5de Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Fri, 27 Sep 2024 09:43:51 -0700 Subject: [PATCH 28/37] link to handwriting --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 66e5490457..a345443c8d 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -102,6 +102,10 @@ In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical Enabling Window to Visual hosting mode removes support for Windows Shell Handwriting within the WebView2. +See also: +* [Ink input](/windows/win32/input_ink/input-ink-portal) - Windows App Development > User Interaction. +* [shellhandwriting.h header](/windows/win32/api/shellhandwriting/) - Win32 API. + #### APIs for Window to Visual hosting @@ -169,3 +173,5 @@ External: * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) - Windows App Development. * [Basic concepts](/windows/win32/directcomp/basic-concepts) - Windows App Development > DirectComposition. * [Composition visual](/windows/uwp/composition/composition-visual-tree) - Windows App Development > UWP. +* [Ink input](/windows/win32/input_ink/input-ink-portal) - Windows App Development > User Interaction. +* [shellhandwriting.h header](/windows/win32/api/shellhandwriting/) - Win32 API. From dd56310c51370bb7ccd2e6a58ebf3987c5e491fd Mon Sep 17 00:00:00 2001 From: "John An (from Dev Box)" Date: Mon, 30 Sep 2024 16:47:33 -0700 Subject: [PATCH 29/37] Addressing todos about visual hosting. Leaving one remaining because Im not sure what the constraints for framework/non-framework apps is. --- .../concepts/windowed-vs-visual-hosting.md | 15 ++++----------- 1 file changed, 4 insertions(+), 11 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index a345443c8d..b177bb2072 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -116,13 +116,11 @@ For a list of APIs that can be used when configuring WebView2 Window to Visual h ## Visual hosting: For more granular control over layout -When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. +When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. In addition to the window management described for Windowed hosting, Visual hosting places additional requirements on the app to manage the composition-based rendering and route input. -In Visual hosting, WebView2 content is embedded at a given location in the application. This location must handle how content will scale and behave when the user interacts with the application. In addition to the window management described for Windowed hosting, Visual hosting requires the app to manage the composition-based rendering when it receives any user interactions. +Because the WebView2 is part of a visual tree, by default its contents will be rendered at different scales based on the scales of its ancestor visuals. For instance if a WebView2's ancestor visual is scaled 2x, then the WebView2 contents will also be rendered at 2x scale. But because the WebView2 is not scaling its own contents, they will be rendered blurrily. This can be resolved using the Rasterization Scale APIs. The app would disable default visual scaling on the WebView2 and then use the Rasterization Scale APIs to apply the intended visual scaling. This would result in the contents rendering clearly at the correct scale. -If your WebView2 app uses Visual hosting, inputs are routed to the app's `HWND` and must be configured to send the spatial input (such as mouse, touch, or pen) based on positions, _not_ based on what currently has focus, such as a keyboard. - -If your WebView2 app uses Visual hosting, spatial inputs (such as mouse, touch, or pen) are sent to the app's `HWND`, not sent directly to the WebView2. The app should forward this spatial input to the WebView2 if the position of the input is over the WebView2, _not_ based on what currently has focus. +If your WebView2 app uses Visual hosting, no spatial inputs (such as mouse, touch, or pen) are sent to the WebView2 without app management. Input is sent to the app's `HWND`, and the app is responsible for forwarding this spatial input to the WebView2 if the input's position is over the WebView2. The app is also responsible for any necessary transformations of input position into the WebView2's coordinate space. See also: * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) in Windows > App development docs. @@ -133,12 +131,7 @@ See also: Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. -For example, when the user resizes the window, you must define how the WebView2 control scales in relation to the whole webpage, such as making the WebView2 scale twice as much as the app. - +For example, if a user action causes the WebView2 visual tree to scale, the app must adjust the WebView2's scale to render correctly relative to its parent visuals. From 3b535f3528f8f098341935b3cbdcc38d0f38bebf Mon Sep 17 00:00:00 2001 From: "John An (from Dev Box)" Date: Mon, 30 Sep 2024 17:04:44 -0700 Subject: [PATCH 30/37] Addressing final todo regarding constraints --- .../webview2/concepts/windowed-vs-visual-hosting.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b177bb2072..45d6c607fc 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -143,7 +143,7 @@ For a list of APIs that can be used when configuring WebView2 in a Visual hostin ## Compatibility and constraints -Key compatibility limitations include the operating system and rendering in framework and non-framework apps. +Key compatibility limitations include the operating system and rendering in framework and non-framework apps. @@ -154,6 +154,12 @@ All hosting modes are supported wherever WebView2 is supported; that is, Windows See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. + +#### Framework Constraints + +`CreateCoreWebView2CompositionController` does not support WinAppSDK visuals (Microsoft.UI.Composition). + + ## See also From 107537c834f1b3b7d65435c9daa50d953a001045 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Tue, 1 Oct 2024 08:22:42 -0700 Subject: [PATCH 31/37] Writer pass on resolved todos --- .../concepts/windowed-vs-visual-hosting.md | 36 ++++++++++++++----- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 45d6c607fc..b20887ab4d 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -1,6 +1,6 @@ --- title: Windowed vs. Visual hosting of WebView2 -description: Deciding whether to have your app use Windowed, Window to Visual, or Visual hosting of the WebView2 control. Hosting WebView2 in windowed or visual environments. +description: Deciding whether to have your app use Windowed, Window to Visual, or Visual hosting of the WebView2 control. Hosting WebView2 in Windowed or Visual environments. author: MSEdgeTeam ms.author: msedgedevrel ms.topic: conceptual @@ -80,7 +80,7 @@ Window to Visual hosting does not require you to use WebView2 Visual hosting API To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL` before initializing your WebView2. -In Window-to-Visual hosting and Visual hosting, a _visual_ is a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are `DirectComposition` and `Windows.UI.Composition`. The "visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are visuals that are exposed through the `DirectComposition` and `Windows.UI.Composition` APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See: +In Window-to-Visual hosting and Visual hosting, a _Visual_ is a basic graphical unit that can be used to compose graphical experiences on Windows. The Windows graphics APIs that expose this functionality and are relevant to WebView2 are `DirectComposition` and `Windows.UI.Composition`. The "Visual" in "Visual hosting" can be any one of `IDCompositionVisual`, `IDCompositionTarget`, or `Windows.UI.Composition.Visual`, which are Visuals that are exposed through the `DirectComposition` and `Windows.UI.Composition` APIs. (Window to Visual hosting uses `IDCompositionVisual` specifically.) See: * [Basic concepts](/windows/win32/directcomp/basic-concepts) in the Windows App Development > DirectComposition docs. * [Composition visual](/windows/uwp/composition/composition-visual-tree) in the Windows App Development > UWP docs. @@ -116,11 +116,26 @@ For a list of APIs that can be used when configuring WebView2 Window to Visual h ## Visual hosting: For more granular control over layout -When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. In addition to the window management described for Windowed hosting, Visual hosting places additional requirements on the app to manage the composition-based rendering and route input. +When using _Visual hosting_, your host app receives spatial input (such as mouse or touch input) from the user, and forwards this input to the WebView2 control. Visual hosting requires the app to do the same window management as Windowed hosting, but has additional window management requirements regarding: +* Scaling the contents. +* Routing spatial inputs (such as mouse, touch, or pen). -Because the WebView2 is part of a visual tree, by default its contents will be rendered at different scales based on the scales of its ancestor visuals. For instance if a WebView2's ancestor visual is scaled 2x, then the WebView2 contents will also be rendered at 2x scale. But because the WebView2 is not scaling its own contents, they will be rendered blurrily. This can be resolved using the Rasterization Scale APIs. The app would disable default visual scaling on the WebView2 and then use the Rasterization Scale APIs to apply the intended visual scaling. This would result in the contents rendering clearly at the correct scale. -If your WebView2 app uses Visual hosting, no spatial inputs (such as mouse, touch, or pen) are sent to the WebView2 without app management. Input is sent to the app's `HWND`, and the app is responsible for forwarding this spatial input to the WebView2 if the input's position is over the WebView2. The app is also responsible for any necessary transformations of input position into the WebView2's coordinate space. + +#### Requirements for scaling the contents + +Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at the scale of its ancestor Visual. For example, if a WebView2's ancestor Visual is scaled 2x, then the WebView2's contents are also rendered at 2x scale. But because the WebView2 is not scaling its own contents, they're blurry. + +To resolve this, the app can disable default Visual scaling on the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. + + + +#### Requirements for routing spatial inputs (mouse, touch, or pen) + +If your WebView2 app uses Visual hosting, no spatial inputs (such as mouse, touch, or pen) are sent to the WebView2 control, unless the app manages such input. Input is sent to the app's `HWND`, and the app is responsible for forwarding this spatial input to the WebView2, if the input's position is over the WebView2. + +The app is also responsible for any necessary transformation of input positions into the WebView2's coordinate space. + See also: * [Using the Visual layer in desktop apps](/windows/apps/desktop/modernize/visual-layer-in-desktop-apps) in Windows > App development docs. @@ -131,7 +146,7 @@ See also: Visual hosting allows for (and requires) more granular control of layout. When using this approach, the app needs specific handling of window management and rendering APIs. -For example, if a user action causes the WebView2 visual tree to scale, the app must adjust the WebView2's scale to render correctly relative to its parent visuals. +For example, if a user action causes the WebView2's Visual tree to scale, the app must adjust the WebView2's scale to render correctly relative to its parent Visuals. @@ -151,13 +166,14 @@ Key compatibility limitations include the operating system and rendering in fram All hosting modes are supported wherever WebView2 is supported; that is, Windows 10 and later, and certain Windows Server versions. Windows 7, 8 and 8.1 are no longer supported; Windows 7 and Windows 8 only support Windowed hosting, not Visual hosting. -See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. +See also: +* [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. -#### Framework Constraints +#### Framework constraints -`CreateCoreWebView2CompositionController` does not support WinAppSDK visuals (Microsoft.UI.Composition). +`CreateCoreWebView2CompositionController` does not support WinAppSDK Visuals; that is, Visual objects in the `Microsoft.UI.Composition` namespace, described in [Enhance UI with the Visual layer (Windows App SDK/WinUI 3)](https://learn.microsoft.com/windows/apps/windows-app-sdk/composition). @@ -166,6 +182,8 @@ See [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft * [Overview of WebView2 features and APIs](./overview-features-apis.md) * [Windows 7 and 8](../index.md#windows-7-and-8) in _Introduction to Microsoft Edge WebView2_. + External: * [About Windows](/windows/win32/winmsg/about-windows) - Window management and `HWND` functionality. From 157494b647b5f53c9e71ba6266e313a53130465f Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Tue, 1 Oct 2024 08:27:50 -0700 Subject: [PATCH 32/37] linkfix --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b20887ab4d..5dc83e9c12 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -173,7 +173,7 @@ See also: #### Framework constraints -`CreateCoreWebView2CompositionController` does not support WinAppSDK Visuals; that is, Visual objects in the `Microsoft.UI.Composition` namespace, described in [Enhance UI with the Visual layer (Windows App SDK/WinUI 3)](https://learn.microsoft.com/windows/apps/windows-app-sdk/composition). +`CreateCoreWebView2CompositionController` does not support WinAppSDK Visuals; that is, Visual objects in the `Microsoft.UI.Composition` namespace, described in [Enhance UI with the Visual layer (Windows App SDK/WinUI 3)](/windows/apps/windows-app-sdk/composition). From e16319dd15ee485c83043d5d3d94e754045393df Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 2 Oct 2024 05:21:55 -0700 Subject: [PATCH 33/37] incorp final rvw/approval cmts --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 5dc83e9c12..de8892a1ed 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -6,7 +6,7 @@ ms.author: msedgedevrel ms.topic: conceptual ms.service: microsoft-edge ms.subservice: webview -ms.date: 09/23/2024 +ms.date: 10/02/2024 --- # Windowed vs. Visual hosting of WebView2 @@ -124,9 +124,9 @@ When using _Visual hosting_, your host app receives spatial input (such as mouse #### Requirements for scaling the contents -Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at the scale of its ancestor Visual. For example, if a WebView2's ancestor Visual is scaled 2x, then the WebView2's contents are also rendered at 2x scale. But because the WebView2 is not scaling its own contents, they're blurry. +Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at a scale that's based on the scales of all of its ancestor Visuals. For example, if a WebView2's ancestor Visual is scaled (zoomed) 2x, then the WebView2's contents are also rendered at 2x scale. If the WebView2's parent Visual is scaled 2x and that Visual's parent is also scaled 2x, then the WebView2 is scaled 4x. But because the WebView2 is not scaling its own contents, they're blurry. -To resolve this, the app can disable default Visual scaling on the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. +To resolve this, the app can undo the default Visual scaling of the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. From 443020adf19d11876a7dbb39a84978b9a4f7978a Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 2 Oct 2024 05:36:06 -0700 Subject: [PATCH 34/37] enjoys benefits --- .../webview2/concepts/windowed-vs-visual-hosting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index de8892a1ed..b409b8cfd7 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -74,9 +74,9 @@ For a list of APIs that can be used when configuring WebView2 for Windowed hosti ## Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff -_Window-to-Visual hosting_ means that the WebView2 content is output to a Visual that is hosted in an HWND, rather than outputting content to a window directly or to a Visual directly. By hosting content in an HWND, Window to Visual hosting mode enjoys the same ease of adoption benefits as Windowed mode, but by actually displaying content using a Visual, it avoids some DPI and input issues that can result when using Windowed mode. +_Window-to-Visual hosting_ means that the WebView2 content is outputted to a Visual that is hosted in an HWND, rather than outputting content to a window directly or to a Visual directly. By hosting content in an HWND, Window to Visual hosting is easy to use, like Windowed hosting, but by displaying content by using a Visual, Window-to-Visual hosting avoids some DPI and input issues that can result when using Windowed hosting. -Window to Visual hosting does not require you to use WebView2 Visual hosting APIs. +Window to Visual hosting doesn't require you to use the WebView2 Visual hosting APIs. To enable Window to Visual hosting, the environment variable `COREWEBVIEW2_FORCED_HOSTING_MODE` must be set to the value `COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL` before initializing your WebView2. From 1ae2507995a896f7dfd17c76b4267716299cc01c Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 2 Oct 2024 05:51:49 -0700 Subject: [PATCH 35/37] isn't --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index b409b8cfd7..5863316bbb 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -124,7 +124,7 @@ When using _Visual hosting_, your host app receives spatial input (such as mouse #### Requirements for scaling the contents -Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at a scale that's based on the scales of all of its ancestor Visuals. For example, if a WebView2's ancestor Visual is scaled (zoomed) 2x, then the WebView2's contents are also rendered at 2x scale. If the WebView2's parent Visual is scaled 2x and that Visual's parent is also scaled 2x, then the WebView2 is scaled 4x. But because the WebView2 is not scaling its own contents, they're blurry. +Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at a scale that's based on the scales of all of its ancestor Visuals. For example, if a WebView2's ancestor Visual is scaled (zoomed) 2x, then the WebView2's contents are also rendered at 2x scale. If the WebView2's parent Visual is scaled 2x and that Visual's parent is also scaled 2x, then the WebView2 is scaled 4x. But because the WebView2 isn't scaling its own contents, they're blurry. To resolve this, the app can undo the default Visual scaling of the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. From b60e5791306af1922530e78c3e072ba04ad53655 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 2 Oct 2024 06:21:54 -0700 Subject: [PATCH 36/37] break up "by but by" sentence --- microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 5863316bbb..1631a26940 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -74,7 +74,7 @@ For a list of APIs that can be used when configuring WebView2 for Windowed hosti ## Window to Visual hosting: For a similar experience as Windowed hosting, with added benefits and tradeoff -_Window-to-Visual hosting_ means that the WebView2 content is outputted to a Visual that is hosted in an HWND, rather than outputting content to a window directly or to a Visual directly. By hosting content in an HWND, Window to Visual hosting is easy to use, like Windowed hosting, but by displaying content by using a Visual, Window-to-Visual hosting avoids some DPI and input issues that can result when using Windowed hosting. +_Window-to-Visual hosting_ means that the WebView2 content is outputted to a Visual that is hosted in an HWND, rather than outputting content to a window directly or to a Visual directly. By hosting content in an HWND, Window to Visual hosting is easy to use, in the same ways as Windowed hosting. But by displaying content by using a Visual, Window-to-Visual hosting avoids some DPI and input issues that can result when using Windowed hosting. Window to Visual hosting doesn't require you to use the WebView2 Visual hosting APIs. From 918a03e9e337441d5052d758dc051521d4debe33 Mon Sep 17 00:00:00 2001 From: Michael Hoffman Date: Wed, 2 Oct 2024 13:07:57 -0700 Subject: [PATCH 37/37] apply 3 final nic cmts --- .../webview2/concepts/windowed-vs-visual-hosting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md index 1631a26940..cfb95d01b9 100644 --- a/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md +++ b/microsoft-edge/webview2/concepts/windowed-vs-visual-hosting.md @@ -25,7 +25,7 @@ The different approaches for hosting the WebView2 control in your app are simila |---|---|---| | Windowed hosting | The WebView2 control takes input from the operating system (OS). The OS sends the input to the WebView2. | Displaying web content quickly and easily, without having to include features for inputs, outputs, and accessibility. | | Window to Visual hosting | A combination of Windowed and Visual hosting. Similar to Windowed hosting except that WebView2 content is output to a Visual that is hosted in a window rather having content output to the window directly. | A developer experience nearly identical to Windowed hosting, but with improved DPI/scaling handling and the caveat that the Windows Shell Handwriting experience is unsupported. | -| Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over layout. For example, you can control the positioning of the WebView2 control in the page. The app needs to do specific handling of window management and rendering APIs. | +| Visual hosting | Your host app takes spatial input (such as mouse or touch input) from the user. Your app sends this input to the WebView2 control. | More granular control over control composition. The app needs to do specific handling of window management and rendering APIs. | These approaches have different requirements, constraints, and benefits. * Windowed hosting is simpler to implement than Visual hosting. @@ -92,7 +92,7 @@ In Window-to-Visual hosting and Visual hosting, a _Visual_ is a basic graphical * Different apps that share a WebView2 user data folder can have different integrity levels. -* Different apps that share a WebView2 user data folder won't potentially cause each other to hang. +* Different apps that share a WebView2 user data folder won't potentially cause each other to hang due to attached window input queues. * When hosting a WebView2 in a VSTO Add-in, changing monitor scale won't potentially cause the app to hang. See [VSTO Add-ins](/visualstudio/vsto/office-solutions-development-overview-vsto#vsto-add-ins) in _Office solutions development overview (VSTO)_. @@ -126,7 +126,7 @@ When using _Visual hosting_, your host app receives spatial input (such as mouse Per composition-based rendering, a WebView2 control is part of a Visual tree, so by default, it's rendered at a scale that's based on the scales of all of its ancestor Visuals. For example, if a WebView2's ancestor Visual is scaled (zoomed) 2x, then the WebView2's contents are also rendered at 2x scale. If the WebView2's parent Visual is scaled 2x and that Visual's parent is also scaled 2x, then the WebView2 is scaled 4x. But because the WebView2 isn't scaling its own contents, they're blurry. -To resolve this, the app can undo the default Visual scaling of the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. +To resolve this, the app can undo the default Visual scaling of the WebView2, and instead use the Rasterization Scale APIs to apply the intended Visual scaling. This results in the WebView2's contents rendering at the correct scale. See [Rasterization scale](./overview-features-apis.md#rasterization-scale) in _Overview of WebView2 features and APIs_.