11# Background
22
3- In visual hosting, the current cursor image cannot be determined easily by the
4- hosting application easily. For example, if the cursor over the WebView is also
5- over a textbox inside of the WebView, the cursor should usually be IDC_IBEAM.
6- And by default, the cursor is IDC_ARROW. Currently, we return the what the
7- cursor should be as an HCURSOR object (After calling LoadCursor on those IDC
8- values). The hosting application can then use the HCURSOR object to change the
9- current cursor to the correct image.
3+ When an app is using composition hosting to host WebView, the current cursor
4+ image cannot be determined easily by the hosting application. For example, if
5+ the cursor over the WebView is also over a textbox inside of the WebView, the
6+ cursor should usually be IDC_IBEAM. And by default, the cursor is IDC_ARROW.
7+ Currently, we return the what the cursor should be as an HCURSOR object (After
8+ calling LoadCursor on those IDC values). The hosting application can then use
9+ the HCURSOR object to change the current cursor to the correct image.
1010
1111However, Office already has a well established way of using cursors internally
1212by using IDC_* values and there is no easy way to convert the HCURSOR object we
@@ -15,15 +15,21 @@ are returning into an IDC value after it's been created.
1515This new API is to enable hosting applications like Office to get the current
1616IDC value of the cursor instead of the HCURSOR as an option.
1717
18+ Note that this is a COM and .NET spec as WinRT uses a separate enum structure to
19+ identify cursor IDs.
20+
1821
1922# Description
2023
21- The `SystemCursorId` property will return the current system cursor ID reproted
24+ The `SystemCursorId` property will return the current system cursor ID reported
2225by the underlying rendering engine for WebView2. It is not meant to return a
2326value for any custom cursors, such as those defined by CSS.
2427
2528It can be used at any time but will only change after a `CursorChanged` event.
2629
30+ Note that developers should generally use the `Cursor` property to support cases
31+ where there may be custom cursors.
32+
2733
2834# Examples
2935
@@ -59,12 +65,14 @@ CHECK_FAILURE(m_compositionController->add_CursorChanged(
5965
6066See [API Details](#api-details) section below for API reference.
6167
68+
6269# API Details
6370
71+ ```cpp
6472/// This interface is continuation of the
65- /// ICoreWebView2ExperimentalCompositionController interface.
73+ /// ICoreWebView2CompositionController interface.
6674[uuid(279ae616-b7cb-4946-8da3-dc853645d2ba), object, pointer_default(unique)]
67- interface ICoreWebView2ExperimentalCompositionController2 : IUnknown {
75+ interface ICoreWebView2CompositionController2 : ICoreWebView2CompositionController {
6876 /// The current system cursor ID reported by the underlying rendering engine
6977 /// for WebView. For example, most of the time, when the cursor is over text,
7078 /// this will return the int value for IDC_IBEAM. The systemCursorId is only
@@ -79,6 +87,33 @@ interface ICoreWebView2ExperimentalCompositionController2 : IUnknown {
7987 [propget] HRESULT SystemCursorId([out, retval] UINT32* systemCursorId);
8088}
8189
90+ ```c#
91+ namespace Microsoft.Web.WebView2.Core
92+ {
93+ //
94+ // Summary:
95+ // This class is an extension of the CoreWebView2CompositionController class to support composition
96+ // hosting.
97+ public class CoreWebView2CompositionController2 : CoreWebView2CompositionController
98+ {
99+ //
100+ // Summary:
101+ // The current system cursor ID that WebView thinks it should be.
102+ //
103+ // Remarks:
104+ // The current system cursor ID reported by the underlying rendering engine
105+ // for WebView. For example, most of the time, when the cursor is over text,
106+ // this will return the int value for IDC_IBEAM. The SystemCursorId is only
107+ // valid if the rendering engine reports a default Windows cursor resource
108+ // value. See:
109+ // https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-loadcursorw
110+ // Otherwise, if custom CSS cursors are being used, this will return 0.
111+ // To create a Cursor object, create an IntPtr from the returned uint to
112+ // pass into the constructor
113+ public Uint32 SystemCursorId { get; }
114+ }
115+ }
116+
82117# Appendix
83118
84119I expect that most apps will use the get_Cursor API which returns an HCURSOR (Or
0 commit comments