- \n
- Part 1: Introduction to Edge and WebView2<\/a><\/li>\n
- Part 2: Creating a WebView2 component<\/li>\n
- Part 3: Navigation and other events<\/a><\/li>\n
- Part 4: Performing navigation with custom data and headers<\/a><\/li>\n
- Part 5: Executing JavaScript code<\/a><\/li>\n
- Part 6: Printing a web page<\/a><\/li>\n<\/ul>\n<\/div>\n
The API overview<\/h2>\n
The WebView2 SDK contains the following APIs:<\/p>\n
- \n
- Global functions, such as CreateCoreWebView2EnvironmentWithOptions()<\/a> that creates a WebView2 environment with a custom version of Edge, user data directory and\/or additional options, GetAvailableCoreWebView2BrowserVersionString()<\/a> that retrieves the browser version (including channel name), or CompareBrowserVersion()<\/a> that compares browser version to determine which version is newer, older or same.<\/li>\n
- Interfaces, such as ICoreWebView2Environment<\/a> that represents the WebView2 environment, ICoreWebView2EnvironmentOptions<\/a> that defines options used to create WebView2 Environment, ICoreWebView2<\/a> that represents the actual WebView2 control, ICoreWebView2Controller<\/a> that is the owner of the CoreWebView2 object, and provides support for resizing, showing and hiding, focusing, and other functionality related to windowing and composition, ICoreWebView2Settings<\/a> that defines properties that enable, disable, or modify WebView features.<\/li>\n
- Delegate interfaces, such as ICoreWebView2NavigationStartingEventHandler<\/a> and ICoreWebView2NavigationCompletedEventHandler<\/a>.<\/li>\n
- Event argument interfaces, such as ICoreWebView2NavigationStartingEventArgs<\/a> and ICoreWebView2NavigationCompletedEventArgs<\/a>.<\/li>\n<\/ul>\n
The environment is a container that runs a specific version of the Edge browser, with optional custom browser arguments, and a user data folder.<\/p>\n
In order to create a web view control you must do the following:<\/p>\n
- \n
- Call CreateCoreWebView2EnvironmentWithOptions()<\/tt> to create the web view environment.<\/li>\n
- When the environment is available, use the ICoreWebView2Environment<\/tt> interface to create the web view and its controller by calling CreateCoreWebView2Controller<\/tt>.<\/li>\n
- When the web view controller is available, use the ICoreWebView2Controller<\/tt> interface to retrieve a pointer to the webview, ICoreWebView2*<\/tt> so you can add and remove event handlers. Also, you can retrieve a pointer to the ICoreWebView2Settings<\/tt> interface to modify web view features.<\/li>\n<\/ul>\n
The demo app<\/h2>\n
To see how the WebView2 control works, we will use a very simple MFC application with SDI support. The WebView2 control will be created and display within the view. The application contains a toolbar with buttons to navigate back and forward, to stop or reload a page, and a control to provide the URL. Navigation to the URL starts when you press the ENTER key. With this minimum functionality, the application mimics a browser.<\/p>\n
![\"\"](\"https:\/\/mariusbancila.ro\/blog\/wp-content\/uploads\/2020\/01\/appscreeshot3.png\")
<\/p>\nThe most important classes here are the following:<\/p>\n
- \n
- CMainFrame<\/tt> that represents the main window of the application, that contains the menu, toolbar, and status bar. This is where the toolbar events are handled and processed.<\/li>\n
- CMfcEdgeDemoView<\/tt> is the view in the SDI architecture. It is a window that contains and displays on top of itself the WebView2 control, implemented by the class CWebBrowser<\/tt> that we will see below. The class overrides OnInitialUpdate()<\/tt> to create the web view and DestroyWindow()<\/tt> to destroy it. It also handles the WM_SIZE<\/tt> window message to resize the web view control.<\/li>\n<\/ul>\n
You can check the attached demo projects to look at the source code details.<\/p>\n
Creating the WebView2 control<\/h2>\n
The WebView2 control will be managed by the CWebBrowser<\/tt> class. This class is derived from CWnd<\/tt> and has the following interface:<\/p>\n
class CWebBrowser : public CWnd\n{\npublic:\n enum class CallbackType \n {\n CreationCompleted,\n NavigationCompleted\n };\n\n using CallbackFunc = std::function<void()>;\n\npublic:\n CWebBrowser();\n virtual ~CWebBrowser();\n\n virtual BOOL Create(\n LPCTSTR lpszClassName,\n LPCTSTR lpszWindowName, \n DWORD dwStyle,\n const RECT& rect,\n CWnd* pParentWnd, \n UINT nID,\n CCreateContext* = NULL) override;\n\n BOOL CreateAsync(\n DWORD dwStyle,\n const RECT& rect,\n CWnd* pParentWnd,\n UINT nID,\n CallbackFunc onCreated);\n\n RECT GetBounds();\n void SetBounds(LONG const width, LONG const height) { Resize(width, height); }\n void Resize(LONG const width, LONG const height);\n bool IsWebViewCreated() const;\n\nprotected:\n DECLARE_DYNCREATE(CWebBrowser)\n DECLARE_MESSAGE_MAP()\n\nprivate:\n CWebBrowserImpl* m_pImpl;\n std::map<CallbackType, CallbackFunc> m_callbacks;\n\nprivate:\n void RunAsync(CallbackFunc callback);\n void CloseWebView();\n void RegisterEventHandlers();\n void ResizeToClientArea();\n void NavigateTo(CString url);\n CString NormalizeUrl(CString url);\n\n static CString GetInstallPath();\n static CString GetInstallPathFromRegistry(bool const searchWebView = true);\n static CString GetInstallPathFromDisk(bool const searchWebView = true);\n static CString GetUserDataFolder();\n\n void InitializeWebView();\n HRESULT OnCreateEnvironmentCompleted(HRESULT result, ICoreWebView2Environment* environment);\n HRESULT OnCreateWebViewControllerCompleted(HRESULT result, ICoreWebView2Controller* controller);\n bool HandleWindowMessage(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam, LRESULT* result);\n BOOL CreateHostWindow(LPCTSTR lpszClassName, LPCTSTR lpszWindowName, DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID);\n static PCTSTR GetWindowClass();\n static LRESULT CALLBACK WndProcStatic(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam);\n};<\/pre>\nThe Create()<\/tt> method is an overload from CWnd<\/tt>. However, you can only use this if you want to initiate the creation of the web view and then forget about it. If you need to do something after the web view was created then you need to properly utilize the asynchronous API of the WebView2. The method CreateAsync()<\/tt> is initiating the creation of the web view and registers a callback that will be invoked when the web view creation is completed.<\/p>\n
struct CWebBrowserImpl\n{\n wil::com_ptr<ICoreWebView2Environment> m_webViewEnvironment;\n wil::com_ptr<ICoreWebView2> m_webView;\n wil::com_ptr<ICoreWebView2Controller> m_webController;\n wil::com_ptr<ICoreWebView2Settings> m_webSettings;\n};\n\nCWebBrowser::CWebBrowser():m_pImpl(new CWebBrowserImpl())\n{\n m_callbacks[CallbackType::CreationCompleted] = nullptr;\n m_callbacks[CallbackType::NavigationCompleted] = nullptr;\n}\n\nCWebBrowser::~CWebBrowser()\n{\n SetWindowLongPtr(m_hWnd, GWLP_USERDATA, 0);\n CloseWebView();\n delete m_pImpl;\n}\n\nBOOL CWebBrowser::CreateHostWindow(\n LPCTSTR lpszClassName,\n LPCTSTR lpszWindowName,\n DWORD dwStyle,\n const RECT& rect,\n CWnd* pParentWnd,\n UINT nID)\n{\n if (lpszClassName == nullptr)\n lpszClassName = GetWindowClass();\n\n if (!CWnd::Create(lpszClassName, lpszWindowName, dwStyle, rect, pParentWnd, nID))\n return FALSE;\n\n ::SetWindowLongPtr(m_hWnd, GWLP_USERDATA, (LONG_PTR)this);\n\n return TRUE;\n}\n\nBOOL CWebBrowser::CreateAsync(\n DWORD dwStyle,\n const RECT& rect,\n CWnd* pParentWnd, \n UINT nID,\n CallbackFunc onCreated)\n{\n if (!CreateHostWindow(nullptr, nullptr, dwStyle, rect, pParentWnd, nID))\n return FALSE;\n\n m_callbacks[CallbackType::CreationCompleted] = onCreated;\n\n InitializeWebView();\n\n return TRUE;\n}<\/pre>\nThere are three steps here:<\/p>\n
- \n
- Create a parent (host) window. The purpose of this window is have a message queue that we will use to process callbacks. When an event occurs, we post a message to the queue. The window procedure will process the message and invoke the appropriate callback. In this example, we have defined the CallbackType<\/tt> enumeration that provides two types of callbacks: one for completing the navigation, and one for completing the creation of the view.<\/li>\n
- Register a callback function to be invoked when the web view has been created.<\/li>\n
- Initialize the web view.<\/li>\n<\/ol>\n
To initialize the web view we must call the CreateCoreWebView2EnvironmentWithOptions()<\/tt> method with the following arguments:<\/p>\n
- \n
- The path to the installation folder of Edge. If this is null, the component should automatically locate the installation of Edge and use that. In practice, providing null does not work well, and the component is not able to detect the browser.<\/li>\n
- The patch to the user data folder. If this is null, a subfolder in the current folder will be created. Beware that if your application is installed in Program Files, it will not be able to create it. Invoking this method will result in an access denied error (0x80070005 which is a HRESULT<\/tt> value for ERROR_ACCESS_DENIED<\/tt>). Therefore, make sure you provide a user folder to a writable location.<\/li>\n
- Optional environment options (as ICoreWebView2EnvironmentOptions*<\/tt>) to change the behavior of the web view.<\/li>\n
- A handler for the result of the asynchronous operation, that will be invoked if the environment was successfully created.<\/li>\n<\/ul>\n
If this function fails, it returns an error code. For instance, 0x80070002 (HRESULT for ERROR_FILE_NOT_FOUND<\/tt>) means that the WebView2 component was not found.<\/p>\n
It is important to note that the WebView2 environment as well as all the other WebView2 objects are single threaded and have dependencies on Windows components that require COM to be initialized for a single-threaded apartment. Therefore, the application is required to call CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED)<\/tt> before calling the CreateCoreWebView2EnvironmentWithOptions()<\/tt> function. Failure to do so, will result in an CO_E_NOTINITIALIZED<\/tt> error. In the attached demo project, this call is performed in the CMfcEdgeDemoApp::InitInstance()<\/tt> method.<\/p>\n
The initialization function of the CWebBrowser<\/tt> class can be implemented as follows:<\/p>\n
void CWebBrowser::CloseWebView()\n{\n if (m_pImpl->m_webView)\n {\n m_pImpl->m_webController->Close();\n\n m_pImpl->m_webController = nullptr;\n m_pImpl->m_webView = nullptr;\n m_pImpl->m_webSettings = nullptr;\n }\n\n m_pImpl->m_webViewEnvironment = nullptr;\n}\n\nvoid CWebBrowser::InitializeWebView()\n{\n CloseWebView();\n\n CString subFolder = GetInstallPath();\n CString appData = GetUserDataFolder();\n ICoreWebView2EnvironmentOptions* options = nullptr;\n\n HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(\n subFolder, \n appData,\n options,\n Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(\n this, \n &CWebBrowser::OnCreateEnvironmentCompleted).Get());\n\n if (!SUCCEEDED(hr))\n {\n CString text;\n if (hr == HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND))\n {\n text = L\"Cannot found the Edge browser.\";\n }\n else\n {\n text = L\"Cannot create the webview environment.\";\n }\n\n ShowFailure(hr, text);\n }\n}<\/pre>\nWhen the creation of the environment completes successfully, the provided callback is invoked. The first argument of the handler is a HRESULT<\/tt>, and the second is a pointer to the ICoreWebView2Environment<\/tt> interface that defines the environment. This pointer can be used to create the web view by calling CreateCoreWebView2Controller()<\/tt>. This method has two parameters: the handle of the parent window and a callback that will be invoked when the web view creation completes. The implementation of this function is as follows:<\/p>\n
HRESULT CWebBrowser::OnCreateEnvironmentCompleted(\n HRESULT result, \n ICoreWebView2Environment* environment)\n{\n CHECK_FAILURE(result);\n CHECK_FAILURE(environment->QueryInterface(IID_PPV_ARGS(&m_pImpl->m_webViewEnvironment)));\n CHECK_FAILURE(m_pImpl->m_webViewEnvironment->CreateCoreWebView2Controller(\n m_hWnd, \n Callback<ICoreWebView2CreateCoreWebView2ControllerCompletedHandler>(\n this, \n &CWebBrowser::OnCreateWebViewControllerCompleted).Get()));\n\n return S_OK;\n}<\/pre>\nThe callback OnCreateWebViewControllerCompleted<\/tt> is invoked with two arguments: a HRESULT<\/tt> value that indicates the success of the operation and a pointer to the ICoreWebView2Controller<\/tt> interfaces that defines the controller for the web view. This pointer can be used to get a pointer to the ICoreWebView2<\/tt> interface. This, in turn, can be used to add and remove event handlers and invoke various methods such as navigation. The implementation is as follows:<\/p>\n
HRESULT CWebBrowser::OnCreateWebViewControllerCompleted(\n HRESULT result, \n ICoreWebView2Controller* controller)\n{\n if (result == S_OK)\n {\n if (controller != nullptr)\n {\n m_pImpl->m_webController = controller;\n CHECK_FAILURE(controller->get_CoreWebView2(&m_pImpl->m_webView));\n\n CHECK_FAILURE(m_pImpl->m_webView->get_Settings(&m_pImpl->m_webSettings));\n\n RegisterEventHandlers();\n\n ResizeToClientArea();\n }\n\n auto callback = m_callbacks[CallbackType::CreationCompleted];\n if (callback != nullptr)\n RunAsync(callback);\n }\n else\n {\n ShowFailure(result, L\"Cannot create webview environment.\");\n }\n\n return S_OK;\n}<\/pre>\nWe will look at handling events in the next installment. What you can see here is that when the creation completes we invoke the callback the user passed when initiating the asynchronous creation of the web view. However, the invocation is not done directly. Instead, a message is posted to the web view’s parent window message queue. When this message is processed, the callback is actually invoked.<\/p>\n
void CWebBrowser::RunAsync(CallbackFunc callback)\n{\n auto* task = new CallbackFunc(callback);\n PostMessage(MSG_RUN_ASYNC_CALLBACK, reinterpret_cast<WPARAM>(task), 0);\n}\n\nLRESULT CALLBACK CWebBrowser::WndProcStatic(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)\n{\n if (auto app = (CWebBrowser*)::GetWindowLongPtr(hWnd, GWLP_USERDATA))\n {\n LRESULT result = 0;\n if (app->HandleWindowMessage(hWnd, message, wParam, lParam, &result))\n {\n return result;\n }\n }\n\n return ::DefWindowProc(hWnd, message, wParam, lParam);\n}\n\nbool CWebBrowser::HandleWindowMessage(\n HWND, UINT message, WPARAM wParam, LPARAM lParam, LRESULT* result)\n{\n *result = 0;\n \n switch (message)\n {\n case WM_SIZE:\n {\n if (lParam != 0)\n {\n ResizeToClientArea();\n return true;\n }\n }\n break;\n case MSG_RUN_ASYNC_CALLBACK:\n {\n auto* task = reinterpret_cast<CallbackFunc*>(wParam);\n (*task)();\n delete task;\n return true;\n }\n break;\n }\n\n return false;\n}<\/pre>\nHaving a pointer to the ICoreWebView2<\/tt> and ICoreWebView2Controller<\/tt> interfaces, we can also implement the other methods from the public interface of the CWebBrowser<\/tt> class.<\/p>\n
RECT CWebBrowser::GetBounds()\n{\n RECT rc{0,0,0,0};\n if (m_pImpl->m_webController)\n {\n m_pImpl->m_webController->get_Bounds(&rc);\n }\n\n return rc;\n}\n\nvoid CWebBrowser::Resize(LONG const width, LONG const height)\n{\n SetWindowPos(nullptr, 0, 0, width, height, SWP_NOMOVE| SWP_NOREPOSITION);\n}\n\nCString CWebBrowser::GetLocationURL()\n{\n CString url;\n if (m_pImpl->m_webView)\n {\n wil::unique_cotaskmem_string uri;\n m_pImpl->m_webView->get_Source(&uri);\n\n if (wcscmp(uri.get(), L\"about:blank\") == 0)\n {\n uri = wil::make_cotaskmem_string(L\"\");\n }\n\n url = uri.get();\n }\n\n return url;\n}\n\nCString CWebBrowser::NormalizeUrl(CString url)\n{\n if (url.Find(_T(\":\/\/\")) < 0)\n {\n if (url.GetLength() > 1 && url[1] == ':')\n url = _T(\"file:\/\/\") + url;\n else\n url = _T(\"http:\/\/\") + url;\n }\n\n return url;\n}\n\nvoid CWebBrowser::NavigateTo(CString url)\n{\n m_pImpl->m_webView->Navigate(NormalizeUrl(url));\n}\n\nvoid CWebBrowser::Navigate(CString const & url, CallbackFunc onComplete)\n{\n if (m_pImpl->m_webView)\n { \n m_callbacks[CallbackType::NavigationCompleted] = onComplete;\n NavigateTo(url);\n }\n}\n\nvoid CWebBrowser::Stop()\n{\n if (m_pImpl->m_webView)\n {\n m_pImpl->m_webView->Stop();\n }\n}\n\nvoid CWebBrowser::Reload()\n{\n if (m_pImpl->m_webView)\n {\n m_pImpl->m_webView->Reload();\n }\n}\n\nvoid CWebBrowser::GoBack()\n{\n if (m_pImpl->m_webView)\n {\n BOOL possible = FALSE;\n m_pImpl->m_webView->get_CanGoBack(&possible);\n if(possible)\n m_pImpl->m_webView->GoBack();\n }\n}\n\nvoid CWebBrowser::GoForward()\n{\n if (m_pImpl->m_webView)\n {\n BOOL possible = FALSE;\n m_pImpl->m_webView->get_CanGoForward(&possible);\n if (possible)\n m_pImpl->m_webView->GoForward();\n }\n}<\/pre>\nWe will discuss the details about events and navigation in the next post.<\/p>\n
What is left to show here is how the CWebBrowser<\/tt> is used from the SDI’s view, which you can see below:<\/p>\n
void CMfcEdgeDemoView::OnInitialUpdate()\n{\n CView::OnInitialUpdate();\n\n this->ModifyStyleEx(WS_EX_CLIENTEDGE | WS_EX_WINDOWEDGE, 0, 0);\n this->ModifyStyle(WS_CAPTION | WS_SYSMENU | WS_MAXIMIZEBOX | WS_MINIMIZEBOX | WS_THICKFRAME | WS_BORDER, 0, 0);\n\n m_pWebBrowser = std::make_unique<CWebBrowser>();\n\n if (m_pWebBrowser != nullptr)\n {\n CRect rectClient;\n GetClientRect(rectClient);\n\n m_pWebBrowser->CreateAsync(\n WS_VISIBLE | WS_CHILD,\n rectClient,\n this,\n 1,\n [this]() {\n m_pWebBrowser->Navigate(L\"https:\/\/bing.com\", nullptr);\n });\n }\n}\n\nBOOL CMfcEdgeDemoView::DestroyWindow()\n{\n m_pWebBrowser.reset();\n\n return CView::DestroyWindow();\n}\n\nvoid CMfcEdgeDemoView::OnSize(UINT nType, int cx, int cy)\n{\n CView::OnSize(nType, cx, cy);\n\n CRect rectClient;\n GetClientRect(rectClient);\n\n if (m_pWebBrowser != nullptr)\n m_pWebBrowser->Resize(cx, cy);\n}<\/pre>\n - Optional environment options (as ICoreWebView2EnvironmentOptions*<\/tt>) to change the behavior of the web view.<\/li>\n
- CMfcEdgeDemoView<\/tt> is the view in the SDI architecture. It is a window that contains and displays on top of itself the WebView2 control, implemented by the class CWebBrowser<\/tt> that we will see below. The class overrides OnInitialUpdate()<\/tt> to create the web view and DestroyWindow()<\/tt> to destroy it. It also handles the WM_SIZE<\/tt> window message to resize the web view control.<\/li>\n<\/ul>\n
- When the environment is available, use the ICoreWebView2Environment<\/tt> interface to create the web view and its controller by calling CreateCoreWebView2Controller<\/tt>.<\/li>\n
- Interfaces, such as ICoreWebView2Environment<\/a> that represents the WebView2 environment, ICoreWebView2EnvironmentOptions<\/a> that defines options used to create WebView2 Environment, ICoreWebView2<\/a> that represents the actual WebView2 control, ICoreWebView2Controller<\/a> that is the owner of the CoreWebView2 object, and provides support for resizing, showing and hiding, focusing, and other functionality related to windowing and composition, ICoreWebView2Settings<\/a> that defines properties that enable, disable, or modify WebView features.<\/li>\n
![\"\"](\"https:\/\/mariusbancila.ro\/blog\/wp-content\/uploads\/2020\/01\/appscreeshot4.jpg\")
<\/p>\n![\"\"](\"https:\/\/mariusbancila.ro\/blog\/wp-content\/uploads\/2020\/01\/edgewebviewpath.png\")
<\/p>\n![\"\"](\"https:\/\/mariusbancila.ro\/blog\/wp-content\/uploads\/2020\/01\/edgwebvieweregistry.png\")
<\/li>\n