interface ICoreWebView2Controller
Note
This reference is no longer being maintained. For the latest API reference, see WebView2 API Reference.
interface ICoreWebView2Controller
: public IUnknown
The owner of the CoreWebView2
object that provides support for resizing, showing and hiding, focusing, and other functionality related to windowing and composition.
Summary
Members | Descriptions |
---|---|
add_AcceleratorKeyPressed | Adds an event handler for the AcceleratorKeyPressed event. |
add_GotFocus | Adds an event handler for the GotFocus event. |
add_LostFocus | Adds an event handler for the LostFocus event. |
add_MoveFocusRequested | Adds an event handler for the MoveFocusRequested event. |
add_ZoomFactorChanged | Adds an event handler for the ZoomFactorChanged event. |
Close | Closes the WebView and cleans up the underlying browser instance. |
get_Bounds | The WebView bounds. |
get_CoreWebView2 | Gets the CoreWebView2 associated with this CoreWebView2Controller . |
get_IsVisible | The IsVisible property determines whether to show or hide the WebView2. |
get_ParentWindow | The parent window provided by the app that this WebView is using to render content. |
get_ZoomFactor | The zoom factor for the WebView. |
MoveFocus | Moves focus into WebView. |
NotifyParentWindowPositionChanged | This is a notification separate from Bounds that tells WebView that the main WebView parent (or any ancestor) HWND moved. |
put_Bounds | Sets the Bounds property. |
put_IsVisible | Sets the IsVisible property. |
put_ParentWindow | Sets the parent window for the WebView. |
put_ZoomFactor | Sets the ZoomFactor property. |
remove_AcceleratorKeyPressed | Removes an event handler previously added with add_AcceleratorKeyPressed . |
remove_GotFocus | Removes an event handler previously added with add_GotFocus . |
remove_LostFocus | Removes an event handler previously added with add_LostFocus . |
remove_MoveFocusRequested | Removes an event handler previously added with add_MoveFocusRequested . |
remove_ZoomFactorChanged | Remove an event handler previously added with add_ZoomFactorChanged . |
SetBoundsAndZoomFactor | Updates Bounds and ZoomFactor properties at the same time. |
The CoreWebView2Controller
owns the CoreWebView2
, and if all references to the CoreWebView2Controller
go away, the WebView is closed.
Members
add_AcceleratorKeyPressed
Adds an event handler for the AcceleratorKeyPressed
event.
public HRESULT add_AcceleratorKeyPressed(ICoreWebView2AcceleratorKeyPressedEventHandler * eventHandler, EventRegistrationToken * token)
AcceleratorKeyPressed
runs when an accelerator key or key combo is pressed or released while the WebView is focused. A key is considered an accelerator if either of the following conditions are true.
Ctrl or Alt is currently being held.
The pressed key does not map to a character.
A few specific keys are never considered accelerators, such as Shift. The Escape
key is always considered an accelerator.
Auto-repeated key events caused by holding the key down also triggers this event. Filter out the auto-repeated key events by verifying the KeyEventLParam
or PhysicalKeyStatus
event args.
In windowed mode, the event handler is run synchronously. Until you run Handled()
on the event args or the event handler returns, the browser process is blocked and outgoing cross-process COM requests fail with RPC_E_CANTCALLOUT_ININPUTSYNCCALL
. All CoreWebView2
API methods work, however.
In windowless mode, the event handler is run asynchronously. Further input do not reach the browser until the event handler returns or Handled()
is run, but the browser process is not blocked, and outgoing COM requests work normally.
It is recommended to run Handled(TRUE)
as early as are able to know that you want to handle the accelerator key.
// Register a handler for the AcceleratorKeyPressed event.
CHECK_FAILURE(m_controller->add_AcceleratorKeyPressed(
Callback<ICoreWebView2AcceleratorKeyPressedEventHandler>(
[this](
ICoreWebView2Controller* sender,
ICoreWebView2AcceleratorKeyPressedEventArgs* args) -> HRESULT {
COREWEBVIEW2_KEY_EVENT_KIND kind;
CHECK_FAILURE(args->get_KeyEventKind(&kind));
// We only care about key down events.
if (kind == COREWEBVIEW2_KEY_EVENT_KIND_KEY_DOWN ||
kind == COREWEBVIEW2_KEY_EVENT_KIND_SYSTEM_KEY_DOWN)
{
UINT key;
CHECK_FAILURE(args->get_VirtualKey(&key));
// Check if the key is one we want to handle.
if (std::function<void()> action =
m_appWindow->GetAcceleratorKeyFunction(key))
{
// Keep the browser from handling this key, whether it's autorepeated or
// not.
CHECK_FAILURE(args->put_Handled(TRUE));
// Filter out autorepeated keys.
COREWEBVIEW2_PHYSICAL_KEY_STATUS status;
CHECK_FAILURE(args->get_PhysicalKeyStatus(&status));
if (!status.WasKeyDown)
{
// Perform the action asynchronously to avoid blocking the
// browser process's event queue.
m_appWindow->RunAsync(action);
}
}
}
return S_OK;
})
.Get(),
&m_acceleratorKeyPressedToken));
add_GotFocus
Adds an event handler for the GotFocus
event.
public HRESULT add_GotFocus(ICoreWebView2FocusChangedEventHandler * eventHandler, EventRegistrationToken * token)
GotFocus
runs when WebView has focus.
add_LostFocus
Adds an event handler for the LostFocus
event.
public HRESULT add_LostFocus(ICoreWebView2FocusChangedEventHandler * eventHandler, EventRegistrationToken * token)
LostFocus
runs when WebView loses focus. In the case where MoveFocusRequested
event is run, the focus is still on WebView when MoveFocusRequested
event runs. LostFocus
only runs afterwards when code of the app or default action of MoveFocusRequested
event set focus away from WebView.
add_MoveFocusRequested
Adds an event handler for the MoveFocusRequested
event.
public HRESULT add_MoveFocusRequested(ICoreWebView2MoveFocusRequestedEventHandler * eventHandler, EventRegistrationToken * token)
MoveFocusRequested
runs when user tries to tab out of the WebView. The focus of the WebView has not changed when this event is run.
// Register a handler for the MoveFocusRequested event.
// This event will be fired when the user tabs out of the webview.
// The handler will focus another window in the app, depending on which
// direction the focus is being shifted.
CHECK_FAILURE(m_controller->add_MoveFocusRequested(
Callback<ICoreWebView2MoveFocusRequestedEventHandler>(
[this](
ICoreWebView2Controller* sender,
ICoreWebView2MoveFocusRequestedEventArgs* args) -> HRESULT {
if (!g_autoTabHandle)
{
COREWEBVIEW2_MOVE_FOCUS_REASON reason;
CHECK_FAILURE(args->get_Reason(&reason));
if (reason == COREWEBVIEW2_MOVE_FOCUS_REASON_NEXT)
{
TabForwards(-1);
}
else if (reason == COREWEBVIEW2_MOVE_FOCUS_REASON_PREVIOUS)
{
TabBackwards(int(m_tabbableWindows.size()));
}
CHECK_FAILURE(args->put_Handled(TRUE));
}
return S_OK;
})
.Get(),
&m_moveFocusRequestedToken));
add_ZoomFactorChanged
Adds an event handler for the ZoomFactorChanged
event.
public HRESULT add_ZoomFactorChanged(ICoreWebView2ZoomFactorChangedEventHandler * eventHandler, EventRegistrationToken * token)
ZoomFactorChanged
runs when the ZoomFactor
property of the WebView changes. The event may run because the ZoomFactor
property was modified, or due to the user manually modifying the zoom. When it is modified using the ZoomFactor
property, the internal zoom factor is updated immediately and no ZoomFactorChanged
event is triggered. WebView associates the last used zoom factor for each site. It is possible for the zoom factor to change when navigating to a different page. When the zoom factor changes due to a navigation change, the ZoomFactorChanged
event runs right after the ContentLoading
event.
// Register a handler for the ZoomFactorChanged event.
// This handler just announces the new level of zoom on the window's title bar.
CHECK_FAILURE(m_controller->add_ZoomFactorChanged(
Callback<ICoreWebView2ZoomFactorChangedEventHandler>(
[this](ICoreWebView2Controller* sender, IUnknown* args) -> HRESULT {
double zoomFactor;
CHECK_FAILURE(sender->get_ZoomFactor(&zoomFactor));
std::wstring message = L"WebView2APISample (Zoom: " +
std::to_wstring(int(zoomFactor * 100)) + L"%)";
SetWindowText(m_appWindow->GetMainWindow(), message.c_str());
return S_OK;
})
.Get(),
&m_zoomFactorChangedToken));
Close
Closes the WebView and cleans up the underlying browser instance.
public HRESULT Close()
Cleaning up the browser instance releases the resources powering the WebView. The browser instance is shut down if no other WebViews are using it.
After running Close
, all methods fail and event handlers stop running. Specifically, the WebView releases the associated references to any associated event handlers when Close
is run.
Close
is implicitly run when the CoreWebView2Controller
loses the final reference and is destructed. But it is best practice to explicitly run Close
to avoid any accidental cycle of references between the WebView and the app code. Specifically, if you capture a reference to the WebView in an event handler you create a reference cycle between the WebView and the event handler. Run Close
to break the cycle by releasing all event handlers. But to avoid the situation, it is best to both explicitly run Close
on the WebView and to not capture a reference to the WebView to ensure the WebView is cleaned up correctly.
// Close the WebView and deinitialize related state. This doesn't close the app window.
void AppWindow::CloseWebView(bool cleanupUserDataFolder)
{
DeleteAllComponents();
if (m_controller)
{
m_controller->Close();
m_controller = nullptr;
m_webView = nullptr;
}
m_webViewEnvironment = nullptr;
if (cleanupUserDataFolder)
{
// For non-UWP apps, the default user data folder {Executable File Name}.WebView2
// is in the same directory next to the app executable. If end
// developers specify userDataFolder during WebView environment
// creation, they would need to pass in that explicit value here.
// For more information about userDataFolder:
// https://video2.skills-academy.com/microsoft-edge/webview2/reference/win32/webview2-idl#createcorewebview2environmentwithoptions
WCHAR userDataFolder[MAX_PATH] = L"";
// Obtain the absolute path for relative paths that include "./" or "../"
_wfullpath(
userDataFolder, GetLocalPath(L".WebView2", true).c_str(), MAX_PATH);
std::wstring userDataFolderPath(userDataFolder);
std::wstring message = L"Are you sure you want to clean up the user data folder at\n";
message += userDataFolderPath;
message += L"\n?\nWarning: This action is not reversible.\n\n";
message += L"Click No if there are other open WebView instances.\n";
if (MessageBox(m_mainWindow, message.c_str(), L"Cleanup User Data Folder", MB_YESNO) ==
IDYES)
{
CHECK_FAILURE(DeleteFileRecursive(userDataFolderPath));
}
}
}
get_Bounds
The WebView bounds.
public HRESULT get_Bounds(RECT * bounds)
Bounds are relative to the parent HWND
. The app has two ways to position a WebView.
Create a child
HWND
that is the WebView parentHWND
. Position the window where the WebView should be. Use(0, 0)
for the top-left corner (the offset) of theBounds
of the WebView.Use the top-most window of the app as the WebView parent HWND. For example, to position WebView correctly in the app, set the top-left corner of the Bound of the WebView.
The values of Bounds
are limited by the coordinate space of the host.
get_CoreWebView2
Gets the CoreWebView2
associated with this CoreWebView2Controller
.
public HRESULT get_CoreWebView2(ICoreWebView2 ** coreWebView2)
get_IsVisible
The IsVisible
property determines whether to show or hide the WebView2.
public HRESULT get_IsVisible(BOOL * isVisible)
If IsVisible
is set to FALSE
, the WebView2 is transparent and is not rendered. However, this does not affect the window containing the WebView2 (the HWND
parameter that was passed to CreateCoreWebView2Controller
). If you want that window to disappear too, run ShowWindow
on it directly in addition to modifying the IsVisible
property. WebView2 as a child window does not get window messages when the top window is minimized or restored. For performance reason, developer should set IsVisible
property of the WebView to FALSE
when the app window is minimized and back to TRUE
when app window is restored. App window does this by handling SC_MINIMIZE and SC_RESTORE
command upon receiving WM_SYSCOMMAND
message.
void ViewComponent::ToggleVisibility()
{
BOOL visible;
m_controller->get_IsVisible(&visible);
m_isVisible = !visible;
m_controller->put_IsVisible(m_isVisible);
}
get_ParentWindow
The parent window provided by the app that this WebView is using to render content.
public HRESULT get_ParentWindow(HWND * parentWindow)
This API initially returns the window passed into CreateCoreWebView2Controller
.
get_ZoomFactor
The zoom factor for the WebView.
public HRESULT get_ZoomFactor(double * zoomFactor)
Note
Changing zoom factor may cause window.innerWidth
, window.innerHeight
, both, and page layout to change. A zoom factor that is applied by the host by running ZoomFactor
becomes the new default zoom for the WebView. The zoom factor applies across navigations and is the zoom factor WebView is returned to when the user chooses Ctrl+0. When the zoom factor is changed by the user (resulting in the app receiving ZoomFactorChanged
), that zoom applies only for the current page. Any user applied zoom is only for the current page and is reset on a navigation. Specifying a zoomFactor
less than or equal to 0
is not allowed. WebView also has an internal supported zoom factor range. When a specified zoom factor is out of that range, it is normalized to be within the range, and a ZoomFactorChanged
event is triggered for the real applied zoom factor. When the range normalization happens, the ZoomFactor
property reports the zoom factor specified during the previous modification of the ZoomFactor
property until the ZoomFactorChanged
event is received after WebView applies the normalized zoom factor.
MoveFocus
Moves focus into WebView.
public HRESULT MoveFocus(COREWEBVIEW2_MOVE_FOCUS_REASON reason)
WebView gets focus and focus is set to correspondent element in the page hosted in the WebView. For Programmatic reason, focus is set to previously focused element or the default element if no previously focused element exists. For Next
reason, focus is set to the first element. For Previous
reason, focus is set to the last element. WebView changes focus through user interaction including selecting into a WebView or Tab into it. For tabbing, the app runs MoveFocus with Next or Previous to align with Tab and Shift+Tab respectively when it decides the WebView is the next element that may exist in a tab. Or, the app runs IsDialogMessage
as part of the associated message loop to allow the platform to auto handle tabbing. The platform rotates through all windows with WS_TABSTOP
. When the WebView gets focus from IsDialogMessage
, it is internally put the focus on the first or last element for tab and Shift+Tab respectively.
while (GetMessage(&msg, nullptr, 0, 0))
{
if (!TranslateAccelerator(msg.hwnd, hAccelTable, &msg))
{
// Calling IsDialogMessage handles Tab traversal automatically. If the
// app wants the platform to auto handle tab, then call IsDialogMessage
// before calling TranslateMessage/DispatchMessage. If the app wants to
// handle tabbing itself, then skip calling IsDialogMessage and call
// TranslateMessage/DispatchMessage directly.
if (!g_autoTabHandle || !IsDialogMessage(GetAncestor(msg.hwnd, GA_ROOT), &msg))
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
}
if (wParam == VK_TAB)
{
// Find out if the window is one we've customized for tab handling
for (size_t i = 0; i < m_tabbableWindows.size(); i++)
{
if (m_tabbableWindows[i].first == hWnd)
{
if (GetKeyState(VK_SHIFT) < 0)
{
TabBackwards(i);
}
else
{
TabForwards(i);
}
return true;
}
}
}
void ControlComponent::TabForwards(int currentIndex)
{
// Find first enabled window after the active one
for (size_t i = currentIndex + 1; i < m_tabbableWindows.size(); i++)
{
HWND hwnd = m_tabbableWindows.at(i).first;
if (IsWindowEnabled(hwnd))
{
SetFocus(hwnd);
return;
}
}
// If this is the last enabled window, tab forwards into the WebView.
m_controller->MoveFocus(COREWEBVIEW2_MOVE_FOCUS_REASON_NEXT);
}
void ControlComponent::TabBackwards(int currentIndex)
{
// Find first enabled window before the active one
for (int i = currentIndex - 1; i >= 0; i--)
{
HWND hwnd = m_tabbableWindows.at(i).first;
if (IsWindowEnabled(hwnd))
{
SetFocus(hwnd);
return;
}
}
// If this is the last enabled window, tab forwards into the WebView.
CHECK_FAILURE(m_controller->MoveFocus(COREWEBVIEW2_MOVE_FOCUS_REASON_PREVIOUS));
}
NotifyParentWindowPositionChanged
This is a notification separate from Bounds
that tells WebView that the main WebView parent (or any ancestor) HWND
moved.
public HRESULT NotifyParentWindowPositionChanged()
This is needed for accessibility and certain dialogs in WebView to work correctly.
if (message == WM_MOVE || message == WM_MOVING)
{
m_controller->NotifyParentWindowPositionChanged();
return true;
}
put_Bounds
Sets the Bounds
property.
public HRESULT put_Bounds(RECT bounds)
// Update the bounds of the WebView window to fit available space.
void ViewComponent::ResizeWebView()
{
SIZE webViewSize = {
LONG((m_webViewBounds.right - m_webViewBounds.left) * m_webViewRatio * m_webViewScale),
LONG((m_webViewBounds.bottom - m_webViewBounds.top) * m_webViewRatio * m_webViewScale) };
RECT desiredBounds = m_webViewBounds;
desiredBounds.bottom = LONG(
webViewSize.cy + m_webViewBounds.top);
desiredBounds.right = LONG(
webViewSize.cx + m_webViewBounds.left);
m_controller->put_Bounds(desiredBounds);
if (m_compositionController)
{
POINT webViewOffset = {m_webViewBounds.left, m_webViewBounds.top};
if (m_dcompDevice)
{
CHECK_FAILURE(m_dcompRootVisual->SetOffsetX(float(webViewOffset.x)));
CHECK_FAILURE(m_dcompRootVisual->SetOffsetY(float(webViewOffset.y)));
CHECK_FAILURE(m_dcompRootVisual->SetClip(
{0, 0, float(webViewSize.cx), float(webViewSize.cy)}));
CHECK_FAILURE(m_dcompDevice->Commit());
}
else if (m_wincompCompositor)
{
if (m_wincompRootVisual != nullptr)
{
numerics::float2 size = {static_cast<float>(webViewSize.cx),
static_cast<float>(webViewSize.cy)};
m_wincompRootVisual.Size(size);
numerics::float3 offset = {static_cast<float>(webViewOffset.x),
static_cast<float>(webViewOffset.y), 0.0f};
m_wincompRootVisual.Offset(offset);
winrtComp::IInsetClip insetClip = m_wincompCompositor.CreateInsetClip();
m_wincompRootVisual.Clip(insetClip.as<winrtComp::CompositionClip>());
}
}
}
}
put_IsVisible
Sets the IsVisible
property.
public HRESULT put_IsVisible(BOOL isVisible)
if (message == WM_SYSCOMMAND)
{
if (wParam == SC_MINIMIZE)
{
// Hide the webview when the app window is minimized.
m_controller->put_IsVisible(FALSE);
}
else if (wParam == SC_RESTORE)
{
// When the app window is restored, show the webview
// (unless the user has toggle visibility off).
if (m_isVisible)
{
m_controller->put_IsVisible(TRUE);
}
}
}
put_ParentWindow
Sets the parent window for the WebView.
public HRESULT put_ParentWindow(HWND parentWindow)
This causes the WebView to re-parent the main WebView window to the newly provided window.
put_ZoomFactor
Sets the ZoomFactor
property.
public HRESULT put_ZoomFactor(double zoomFactor)
remove_AcceleratorKeyPressed
Removes an event handler previously added with add_AcceleratorKeyPressed
.
public HRESULT remove_AcceleratorKeyPressed(EventRegistrationToken token)
remove_GotFocus
Removes an event handler previously added with add_GotFocus
.
public HRESULT remove_GotFocus(EventRegistrationToken token)
remove_LostFocus
Removes an event handler previously added with add_LostFocus
.
public HRESULT remove_LostFocus(EventRegistrationToken token)
remove_MoveFocusRequested
Removes an event handler previously added with add_MoveFocusRequested
.
public HRESULT remove_MoveFocusRequested(EventRegistrationToken token)
remove_ZoomFactorChanged
Remove an event handler previously added with add_ZoomFactorChanged
.
public HRESULT remove_ZoomFactorChanged(EventRegistrationToken token)
SetBoundsAndZoomFactor
Updates Bounds
and ZoomFactor
properties at the same time.
public HRESULT SetBoundsAndZoomFactor(RECT bounds, double zoomFactor)
This operation is atomic from the perspective of the host. After returning from this function, the Bounds
and ZoomFactor
properties are both updated if the function is successful, or neither is updated if the function fails. If Bounds
and ZoomFactor
are both updated by the same scale (for example, Bounds
and ZoomFactor
are both doubled), then the page does not display a change in window.innerWidth
or window.innerHeight
and the WebView renders the content at the new size and zoom without intermediate renderings. This function also updates just one of ZoomFactor
or Bounds
by passing in the new value for one and the current value for the other.
void ViewComponent::SetScale(float scale)
{
RECT bounds;
CHECK_FAILURE(m_controller->get_Bounds(&bounds));
double scaleChange = scale / m_webViewScale;
bounds.bottom = LONG(
(bounds.bottom - bounds.top) * scaleChange + bounds.top);
bounds.right = LONG(
(bounds.right - bounds.left) * scaleChange + bounds.left);
m_webViewScale = scale;
m_controller->SetBoundsAndZoomFactor(bounds, scale);
}