Skip to content

Commit fe8893d

Browse files
maxwellmyersmaxwellmyers
authored
Create FindOnPage.md
1 parent e86d856 commit fe8893d

1 file changed

Lines changed: 382 additions & 0 deletions

File tree

‎FindOnPage.md‎

Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
# WebView2Find API
2+
3+
## Background
4+
5+
The WebView2Find API provides methods and events to support text finding and navigation within a WebView2 control.
6+
It allows developers to initiate find operations, navigate between find results, and customize various find configurations.
7+
8+
## Examples
9+
10+
11+
#### Description
12+
To initiate a find operation within a WebView2 control, developers can utilize the `StartFindOnPage` method.
13+
This method allows specifying the find term and configuring other find parameters using the `ICoreWebView2FindConfiguration` interface.
14+
15+
#### Create/Specify a Find Configuration
16+
17+
18+
19+
```cpp
20+
ICoreWebView2FindConfiguration CreateFindConfiguration()
21+
{
22+
ICoreWebView2Environment5 environment = webView2Control.GetEnvironment();
23+
ICoreWebView2FindConfiguration configuration;
24+
environment.CreateFindConfiguration(out configuration);
25+
configuration.FindTerm = "example";
26+
configuration.FindDirection = COREWEBVIEW2_FIND_DIRECTION.COREWEBVIEW2_FIND_DIRECTION_FORWARD;
27+
configuration.IsCaseSensitive = false;
28+
configuration.ShouldMatchWord = false;
29+
return configuration;
30+
}
31+
```
32+
33+
### Start a Find Operation
34+
35+
36+
```cpp
37+
//! [StartFindOnPage]
38+
void AppWindow::StartFindOnPage(const std::wstring& findTerm)
39+
{
40+
// Get the find interface
41+
auto find = webView2Control.GetFind();
42+
43+
// Create find configuration
44+
auto configuration = CreateFindConfiguration();
45+
46+
// Start the find operation
47+
find.StartFind(configuration, OnFindOperationCompleted);
48+
}
49+
//! [StartFindOnPage]
50+
```
51+
### Stop an existing find operation
52+
#### Description
53+
To stop an ongoing find operation within a WebView2 control, developers can use the `StopFind` method of the `ICoreWebView2Find` interface.
54+
```cpp
55+
//! [StopFind]
56+
void AppWindow::StopFind()
57+
{
58+
// Get the find interface
59+
auto find = webView2Control.GetFind();
60+
61+
// Stop the find operation
62+
find.StopFind();
63+
}
64+
//! [StopFind]
65+
```
66+
67+
### Retrieve the Number of Matches
68+
69+
#### Description
70+
To retrieve the total number of matches found during a find operation within a WebView2 control, developers can utilize the `GetMatchCount` method.
71+
72+
73+
```cpp
74+
//! [GetMatchCount]
75+
void AppWindow::GetMatchCount()
76+
{
77+
// Get the find interface
78+
auto find = webView2Control.GetFind();
79+
80+
// Get the match count
81+
LONG matchCount;
82+
find.GetMatchesCount(&matchCount);
83+
84+
// Update UI or handle matchCount
85+
}
86+
//! [GetMatchCount]
87+
```
88+
89+
### Retrieve the Index of the Active Match
90+
91+
#### Description
92+
Developers can retrieve the index of the currently active match within a WebView2 control using the `GetActiveMatchIndex` method.
93+
94+
95+
```cpp
96+
//! [GetActiveMatchIndex]
97+
void AppWindow::GetActiveMatchIndex()
98+
{
99+
// Get the find interface
100+
auto find = webView2Control.GetFind();
101+
102+
// Get the active match index
103+
LONG activeMatchIndex;
104+
find.GetActiveMatchIndex(&activeMatchIndex);
105+
106+
// Update UI or handle activeMatchIndex
107+
}
108+
//! [GetActiveMatchIndex]
109+
```
110+
111+
### Navigate to the Next Match
112+
113+
#### Description
114+
To navigate to the next match found during a find operation within a WebView2 control, developers can use the `FindNext` method.
115+
116+
117+
```cpp
118+
//! [FindNext]
119+
void AppWindow::FindNext()
120+
{
121+
// Get the find interface
122+
auto find = webView2Control.GetFind();
123+
124+
// Find the next occurrence
125+
find.FindNext();
126+
}
127+
//! [FindNext]
128+
```
129+
130+
### Navigate to the Previous Match
131+
132+
#### Description
133+
To navigate to the previous match found during a find operation within a WebView2 control, developers can use the `FindPrevious` method.
134+
135+
136+
```cpp
137+
//! [FindPrevious]
138+
void AppWindow::FindPrevious()
139+
{
140+
// Get the find interface
141+
auto find = webView2Control.GetFind();
142+
143+
// Find the previous occurrence
144+
find.FindPrevious();
145+
}
146+
//! [FindPrevious]
147+
```
148+
149+
#### Handle Match Count Changes
150+
151+
```cpp
152+
void OnMatchCountChanged(LONG matchesCount)
153+
{
154+
// Handle match count changes
155+
// Update UI elements or perform actions based on the new match count
156+
}
157+
```
158+
#### Handle Active Match Index Changes
159+
```cpp
160+
void OnActiveMatchIndexChanged(ICoreWebView2* sender, ICoreWebView2StagingFindActiveMatchIndexChangedEventArgs* args)
161+
{
162+
// Handle active match index changes
163+
// Update UI to reflect the change in the active match index
164+
}
165+
```
166+
167+
#### Handle Find Operation Completion
168+
169+
```cpp
170+
void OnFindOperationCompleted(HRESULT value, LONG activeMatchIndex, LONG matchesCount)
171+
{
172+
// Handle find operation completion
173+
// Update UI elements, display search results, or handle errors
174+
}
175+
```
176+
## API Details
177+
```csharp
178+
/// Specifies the direction of find Parameters.
179+
[v1_enum]
180+
typedef enum COREWEBVIEW2_FIND_DIRECTION {
181+
/// Specifies a forward find in the document.
182+
COREWEBVIEW2_FIND_DIRECTION_FORWARD,
183+
/// Specifies a backwards find in the document.
184+
COREWEBVIEW2_FIND_DIRECTION_BACKWARD
185+
} COREWEBVIEW2_FIND_DIRECTION;
186+
/// Interface defining the find configuration.
187+
/// This interface provides the necessary methods and properties to configure a find operation.
188+
[uuid(4A6ED732-DF08-4449-8949-3632A4DEBFCD), object, pointer_default(unique)]
189+
interface ICoreWebView2FindConfiguration : IUnknown {
190+
/// Gets the find term used for the find operation.
191+
/// \return The find term.
192+
[propget] HRESULT FindTerm([out, retval] LPWSTR* value);
193+
/// Sets the find term to be used for the find operation.
194+
/// \param[in] value The find term.
195+
[propput] HRESULT FindTerm([in] LPCWSTR value);
196+
/// Gets the direction of the find operation (forward or backward).
197+
/// \return The find direction.
198+
[propget] HRESULT FindDirection([out, retval] COREWEBVIEW2_FIND_DIRECTION* value);
199+
/// Sets the direction for the find operation.
200+
/// \param[in] value The find direction.
201+
[propput] HRESULT FindDirection([in] COREWEBVIEW2_FIND_DIRECTION value);
202+
/// Determines if the find operation is case sensitive.
203+
/// \return TRUE if the find is case sensitive, FALSE otherwise.
204+
[propget] HRESULT IsCaseSensitive([out, retval] BOOL* value);
205+
/// Sets whether the find operation should be case sensitive.
206+
/// \param[in] value TRUE to make the find case sensitive, FALSE otherwise.
207+
[propput] HRESULT IsCaseSensitive([in] BOOL value);
208+
/// Determines if only whole words should be matched during the find operation.
209+
/// \return TRUE if only whole words should be matched, FALSE otherwise.
210+
[propget] HRESULT ShouldMatchWord([out, retval] BOOL* value);
211+
/// Sets whether to only match whole words during the find operation.
212+
[propput] HRESULT ShouldMatchWord([in] BOOL value);
213+
/// Gets the state of whether all matches are highlighted.
214+
/// \return TRUE if all matches are highlighted, FALSE otherwise.
215+
[propget] HRESULT ShouldHighlightAllMatches([out, retval] BOOL* value);
216+
/// Sets the state to either highlight all matches or not.
217+
[propput] HRESULT ShouldHighlightAllMatches([in] BOOL value);
218+
/// Determines if the currently active match is highlighted.
219+
/// \return TRUE if the active match is highlighted, FALSE otherwise.
220+
[propget] HRESULT ShouldHighlightActiveMatch([out, retval] BOOL* value);
221+
/// Sets whether to highlight the currently active match.
222+
[propput] HRESULT ShouldHighlightActiveMatch([in] BOOL value);
223+
/// Checks if a custom user interface is desired by end developer.
224+
/// If TRUE, the default Find bar is not displayed.
225+
/// \return TRUE if using a custom UI, FALSE if using the default.
226+
[propget] HRESULT UseCustomUI([out, retval] BOOL* value);
227+
/// Sets whether to use a custom UI for the Find operation.
228+
[propput] HRESULT UseCustomUI([in] BOOL value);
229+
/// Gets the index of the currently active match.
230+
/// If there's no active find session but an attempt is made to change the active match index:
231+
/// The function might crash if the global_match_id isn't found in the map.
232+
/// It will clear any active match highlighting if there's a previously active frame.
233+
/// It will either select a new active match or return an error through the callback if the frame associated with the match isn't valid.
234+
/// \return The active match index.
235+
[propget] HRESULT ActiveMatchIndex([out, retval] LONG* value);
236+
/// Sets the index for the active match.
237+
[propput] HRESULT ActiveMatchIndex([in] LONG value);
238+
/// Gets the total count of matches found in the current document based on the last find criteria.
239+
/// \return The total count of matches.
240+
[propget] HRESULT MatchesCount([out, retval] LONG* value);
241+
/**
242+
* Passes the current highlighting settings to the underlying Mojo.
243+
*
244+
* This function retrieves the current text highlighting settings set by the user
245+
* or the default system and ensures that they are used during any subsequent text
246+
* find or highlight operations. This includes settings related to highlighting
247+
* all matches, the active match, and any custom UI preferences.
248+
*
249+
* Users should call this function after changing any highlight settings to ensure
250+
* that they are applied properly in the system.
251+
*/
252+
HRESULT PassHighlightSettings();
253+
}
254+
/// Handles the event that's fired when the match count changes.
255+
[uuid(623EFBFB-A19E-43C4-B309-D578511D24AB), object, pointer_default(unique)]
256+
interface ICoreWebView2FindMatchCountChangedEventHandler : IUnknown {
257+
/// Provides the event args when the match count changes.
258+
HRESULT Invoke(LONG matchesCount);
259+
}
260+
/// Handles the event that's fired when the active match index changes.
261+
[uuid(623EFBF9-A19E-43C4-B309-D578511D24A9), object, pointer_default(unique)]
262+
interface ICoreWebView2FindActiveMatchIndexChangedEventHandler : IUnknown {
263+
/// Provides the event args when the active match index changes.
264+
/// \param sender The sender of this event, representing the current instance of ICoreWebView2Find.
265+
/// \param args The event args that contain the new active match index.
266+
HRESULT Invoke(
267+
[in] ICoreWebView2* sender,
268+
[in] ICoreWebView2FindActiveMatchIndexChangedEventArgs* args);
269+
}
270+
/// Handles the event that's fired when the find operation completes.
271+
[uuid(2604789D-9553-4246-8E21-B9C74EFAD04F), object, pointer_default(unique)]
272+
interface ICoreWebView2FindOperationCompletedHandler : IUnknown {
273+
/// Provides the event args when the find operation completes.
274+
HRESULT Invoke(HRESULT value, LONG activeMatchIndex, LONG matchesCount);
275+
}
276+
// Interface defining the find configuration.
277+
[uuid(4A6ED732-DF08-4449-8949-3632A4DEBFCD), object, pointer_default(unique)]
278+
interface ICoreWebView2FindConfiguration : IUnknown {
279+
// Gets or sets the find term used for the find operation.
280+
[propget] HRESULT FindTerm([out, retval] LPWSTR* value);
281+
[propput] HRESULT FindTerm([in] LPCWSTR value);
282+
// Gets or sets the direction of the find operation (forward or backward).
283+
[propget] HRESULT FindDirection([out, retval] COREWEBVIEW2_FIND_DIRECTION* value);
284+
[propput] HRESULT FindDirection([in] COREWEBVIEW2_FIND_DIRECTION value);
285+
// Gets or sets whether the find operation is case sensitive.
286+
[propget] HRESULT IsCaseSensitive([out, retval] BOOL* value);
287+
[propput] HRESULT IsCaseSensitive([in] BOOL value);
288+
// Gets or sets whether to only match whole words during the find operation.
289+
[propget] HRESULT ShouldMatchWord([out, retval] BOOL* value);
290+
[propput] HRESULT ShouldMatchWord([in] BOOL value);
291+
// Gets the state of whether all matches are highlighted.
292+
// \return TRUE if all matches are highlighted, FALSE otherwise.
293+
[propget] HRESULT ShouldHighlightAllMatches([out, retval] BOOL* value);
294+
// Sets the state to either highlight all matches or not.
295+
[propput] HRESULT ShouldHighlightAllMatches([in] BOOL value);
296+
// Determines if the currently active match is highlighted.
297+
// \return TRUE if the active match is highlighted, FALSE otherwise.
298+
[propget] HRESULT ShouldHighlightActiveMatch([out, retval] BOOL* value);
299+
// Sets whether to highlight the currently active match.
300+
[propput] HRESULT ShouldHighlightActiveMatch([in] BOOL value);
301+
// Checks if a custom user interface is desired by end developer.
302+
// If TRUE, the default Find bar is not displayed.
303+
// \return TRUE if using a custom UI, FALSE if using the default.
304+
[propget] HRESULT UseCustomUI([out, retval] BOOL* value);
305+
// Sets whether to use a custom UI for the Find operation.
306+
[propput] HRESULT UseCustomUI([in] BOOL value);
307+
// Gets the index of the currently active match.
308+
// If there's no active find session but an attempt is made to change the active match index:
309+
// The function might crash if the global_match_id isn't found in the map.
310+
// It will clear any active match highlighting if there's a previously active frame.
311+
// It will either select a new active match or return an error through the callback if the frame associated with the match isn't valid.
312+
// \return The active match index.
313+
[propget] HRESULT ActiveMatchIndex([out, retval] LONG* value);
314+
// Sets the index for the active match.
315+
[propput] HRESULT ActiveMatchIndex([in] LONG value);
316+
// Gets the total count of matches found in the current document based on the last find criteria.
317+
// \return The total count of matches.
318+
[propget] HRESULT MatchesCount([out, retval] LONG* value);
319+
/**
320+
* Passes the current highlighting settings to the underlying Mojo.
321+
*
322+
* This function retrieves the current text highlighting settings set by the user
323+
* or the default system and ensures that they are used during any subsequent text
324+
* find or highlight operations. This includes settings related to highlighting
325+
* all matches, the active match, and any custom UI preferences.
326+
*
327+
* Users should call this function after changing any highlight settings to ensure
328+
* that they are applied properly in the system.
329+
*/
330+
HRESULT PassHighlightSettings();
331+
}
332+
// Interface providing methods and properties for finding and navigating through text in the web view.
333+
[uuid(7C49A8AA-2A17-4846-8207-21D1520AABC0), object, pointer_default(unique)]
334+
interface ICoreWebView2Find : IUnknown {
335+
// Initiates a find using the specified configuration.
336+
HRESULT StartFind([in] ICoreWebView2FindConfiguration* configuration,
337+
ICoreWebView2FindOperationCompletedHandler* handler);
338+
// Navigates to the next match in the document.
339+
HRESULT FindNext();
340+
// Navigates to the previous match in the document.
341+
HRESULT FindPrevious();
342+
// Stops the current 'Find' operation and hides the Find bar.
343+
HRESULT StopFind();
344+
// Registers an event handler for the FindCompleted event.
345+
// This event is raised when a find operation completes, either by finding all matches, navigating to a match, or by being stopped.
346+
// \param eventHandler The event handler to be added.
347+
// \return A token representing the added event handler. This token can be used to unregister the event handler.
348+
HRESULT add_FindOperationCompleted(
349+
[in] ICoreWebView2FindOperationCompletedHandler* eventHandler,
350+
[out] EventRegistrationToken* token);
351+
// Unregisters an event handler from the FindCompleted event.
352+
// \param token The token of the event handler to be removed, obtained during the registration of the event handler.
353+
HRESULT remove_FindOperationCompleted([in] EventRegistrationToken token);
354+
// Registers an event handler for the MatchCountChanged event.
355+
// This event is raised when the total count of matches in the document changes due to a new find operation or changes in the document.
356+
// \param eventHandler The event handler to be added.
357+
// \return A token representing the added event handler. This token can be used to unregister the event handler.
358+
HRESULT add_MatchCountChanged(
359+
[in] ICoreWebView2FindMatchCountChangedEventHandler* eventHandler,
360+
[out] EventRegistrationToken* token);
361+
// Unregisters an event handler from the MatchCountChanged event.
362+
// \param token The token of the event handler to be removed, obtained during the registration of the event handler.
363+
HRESULT remove_MatchCountChanged([in] EventRegistrationToken token);
364+
// Registers an event handler for the ActiveMatchIndexChanged event.
365+
// This event is raised when the index of the currently active match changes.
366+
// This can happen when the user navigates to a different match or when the active match is changed programmatically.
367+
// \param eventHandler The event handler to be added.
368+
// \return A token representing the added event handler. This token can be used to unregister the event handler.
369+
HRESULT add_ActiveMatchIndexChanged(
370+
[in] ICoreWebView2FindActiveMatchIndexChangedEventHandler* eventHandler,
371+
[out] EventRegistrationToken* token);
372+
// Unregisters an event handler from the ActiveMatchIndexChanged event.
373+
// \param token The token of the event handler to be removed, obtained during the registration of the event handler.
374+
HRESULT remove_ActiveMatchIndexChanged([in] EventRegistrationToken token);
375+
}
376+
```
377+
378+
# Appendix
379+
380+
This API specification focuses on providing developers with the necessary information to integrate text finding and navigation functionalities into WebView2 applications.
381+
It emphasizes the usage of interfaces such as `ICoreWebView2Find` and `ICoreWebView2FindConfiguration` to perform find operations effectively.
382+
For more detailed implementation notes and examples, developers can refer to the WebView2 documentation and sample code provided by Microsoft.

0 commit comments

Comments
 (0)