Using TEdgeBrowser Component and Changes to the TWebBrowser Component

From RAD Studio
Jump to: navigation, search

Go Up to VCL


RAD Studio 10.4 Sydney brings support for working with web content through the Chromium-based Edge WebView2 browser control in VCL applications via the new TEdgeBrowser component.

TEdgeBrowser supersedes TWebBrowser, which uses the Internet Explorer WebBrowser browser control. However, TWebBrowser remains in the VCL component set, with some notable changes.

Preparing to use the Edge Browser component

Because TWebBrowser uses the Operating System-supplied Internet Explorer WebBrowser browser control there is no preparation required; it will work wherever Windows has the Internet Explorer control available.

On the contrary, Microsoft Edge is not an Operating System component at the time. Because of this, you need to ensure that these items are installed on your computer before you can run an application that uses it:

This applies to compiling and executing the application on your development machine, and also on the end user’s machine.

With both these installed, the TEdgeBrowser will function and use the Edge WebView2 browser control to render web content.

The new public property UserDataFolder allows the developer to define the folder to be used for the cache. This property needs to be set before enabling the component by navigating to a URL.

Note: Microsoft has modified the loading code disabling the ability to initialize the WebView2 control in a background thread. Now the initialization takes place in the main UI thread on the first call to Navigate.

Installing the Edge WebView2 SDK package via GetIt

To install the Microsoft WebView2 package, open the GetIt package manager window in the RAD Studio IDE and search for the corresponding entry:

Get It edgeview.png

After you accept the license, GetIt will download the package and copy the two WebView2 loader DLLs, for 32 and 64 bit, to the corresponding Redist folders, as the GetIt log indicates:

EdgeView2 installed.png

You can copy those files to your target EXE directories, or to a folder on your path, or follow the steps in the section below “Project Configuration for WebView2 loader DLLs”.

Manually Installing the Edge WebView2 SDK package from NuGet

The Edge WebView2 browser control is available from NuGet at https://www.nuget.org/packages/Microsoft.Web.WebView2 under the name Microsoft.Web.WebView2.

On this page, https://nuget.info/packages/Microsoft.Web.WebView2/1.0.1774.30, you can click the Download package link to download microsoft.web.webview2.1.0.1774.30.nupkg.

A .nupkg file is really just a .zip file with a different file extension so you can rename it to microsoft.web.webview2.1.0.1774.30.zip and extract the content with the Windows File Explorer, or use 7zip to extract the content and retrieve the required file.

The file you need from the package is WebView2Loader.dll. If you are building a Win32 app you should take build\x86\WebView2Loader.dll, and if you are building a Win64 app you should take build\x64\WebView2Loader.dll.

Project Configuration for WebView2 loader DLLs

Wherever you choose to place the WebView2 loader DLLs you will need to set up a post-build event to copy it into your project’s output directory.

For a Win32 target the post-build event should look something like:

  copy /Y "common_DLL_folder_path\x86\WebView2Loader.dll" $(OUTPUTDIR)

For a Win64 target use:

  copy /Y "common_DLL_folder_path\x64\WebView2Loader.dll" $(OUTPUTDIR)

Use a Custom WebView2 version

By default, the component uses the current version of the WebView2 control on the system. You can use a specific version by setting the new public property BrowserExecutableFolder to point to the location of the library.

Using the Edge Browser component

You can use the TEdgeBrowser component in a similar way you use a TWebBrowser because a number of TEdgeBrowser's methods and properties are much the same to those of TWebBrowser’s methods and properties.

Drop the component on a VCL form and size it as appropriate.

To navigate to a URL simply pass that URL to the Navigate method.

Note that the WebView2 control is created asynchronously. You can instigate the creation either by calling the Navigate method or by calling the CreateWebView method. At any point, you can tell if the control has been successfully created by using the WebViewCreated property.

This is a minimal example of a running application with a single line of code and not other configuration settings:

Form5Button1.png

Additionally, you can use an OnCreateWebViewCompleted event handler which gets called when control creation completes, either successfully or unsuccessfully.

If there is no OnCreateWebViewCompleted event handler and the WebView2 browser control cannot be initiated, then an EEdgeError exception raises on the main thread but synchronized onto the main thread from a worker thread.

This is therefore difficult to catch without using a global exception handler, for example, a TApplicationEvents component’s OnException event handler, so an OnCreateWebViewCompleted event handler is recommended to simplify this situation.

There are a number of additional events that you can set up event handlers for, which mostly surface events from the underlying WebView2 browser control. For example, when you navigate to a URL the OnNavigationStarting event will fire one or more times based on the target page content. When navigation to a URL concludes the OnNavigationCompleted event fires.

Cache Management

RAD Studio 10.4.2 introduces a new public property: UserDataFolder. This new property allows the developer to define the folder to be used for the cache. This property needs to be set before enabling the component by navigating to a URL.

TEdgeBrowser's tips

Besides TEdgeBrowser is a great tool that allows using the Edge WebView2 browser control, you might find some limitations. So keep in mind the following tips for better performance:

  • Be sure to install the WebView2 Runtime, because the GetIt installer might not be enough even for local development.
  • Microsoft has mainstream distribution for the required WebView2 runtime files, the installer could be found here.

Migrating from TWebBrowser to TEdgeBrowser

In order to move from the traditional TWebBrowser component to the new Edge-based, TEdgeBrowser component you will have to assess which TWebBrowser methods, properties, and events you currently use.

There is some commonality between the exposed interface of TWebBrowser and TEdgeBrowser but it is reasonably limited.

The table below shows the closest 'equivalents' in class members for you to change from and to.

It should be noted that the underlying browser control used by TEdgeBrowser, the WebView2 browser control, exposes many fewer events with a narrower focus than the Internet Explorer WebBrowser browser control underlying the TWebBrowser VCL component.

Methods

TWebBrowser method

TEdgeBrowser method

GoBack

GoBack

GoForward

GoForward

GoHome

No equivalent

GoSearch

No equivalent

Navigate

Navigate

Navigate2

Navigate

Refresh

Refresh

Refresh2

Refresh

Stop

Stop

Quit

CloseBrowserProcess

ClientToWindow

No equivalent

PutProperty

No equivalent

GetProperty

No equivalent

QueryStatusWB

No equivalent

ExecWB

No equivalent

ShowBrowserBar

No equivalent

Properties

TWebBrowser property

TEdgeBrowser property

AddressBar

No equivalent

Application

No equivalent

Busy

No direct equivalent

Container

No equivalent

ControlInterface

DefaultInterface is the ICoreWebView2 interface

DefaultInterface

DefaultInterface is the ICoreWebView2 interface

Document

No equivalent

FullName

No direct equivalent, but you can use BrowserProcessID and some Windows APIs

FullScreen

No equivalent

HWND

No direct equivalent but you can use Handle and some Windows APIs

LocationName

DocumentTitle

LocationURL

LocationURL

MenuBar

No equivalent

Name

No equivalent

Offline

No equivalent

Parent

No equivalent

Path

No direct equivalent, but you can use BrowserProcessID and some Windows APIs

ReadyState

No direct equivalent

RegisterAsBrowser

No equivalent

RegisterAsDropTarget

No equivalent

Resizable

No direct equivalent

Silent

The inverse of DefaultScriptDialogsEnabled along with the OnScriptDialogOpening event

StatusBar

StatusBarEnabled

TheaterMode

No equivalent

ToolBar

No equivalent

TopLevelContainer

No equivalent

Type_

No equivalent

Visible

Visible

Events

TWebBrowser event

TEdgeBrowser event

OnBeforeNavigate2

OnNavigationStarting

OnBeforeScriptExecute

No equivalent

OnClientToHostWindow

No equivalent

OnCommandStateChange

No direct equivalent but you can use OnHistoryChanged

OnDocumentComplete

OnNavigationCompleted

OnDownloadBegin

No equivalent

OnDownloadComplete

No equivalent

OnFileDownload

No equivalent

OnFullScreen

No equivalent

OnMenuBar

No equivalent

OnNavigateComplete2

OnNavigationCompleted

OnNavigateError

OnNavigationComplete, noting the IsSuccess parameter

OnNewProcess

No equivalent

OnNewWindow2

OnNewWindowRequested

OnNewWindow3

OnNewWindowRequested

OnPrintTemplateInstantiation

No equivalent

OnPrintTemplateTeardown

No equivalent

OnPrivacyImpactedStateChange

No equivalent

OnProgressChange

No equivalent

OnPropertyChange

No equivalent

OnQuit

No equivalent

OnRedirectXDomainBlocked

No equivalent

OnShowScriptError

No equivalent

OnSetPhishingFilterStatus

No equivalent

OnSetSecureLockIcon

No equivalent

OnStatusBar

No equivalent

OnStatusTextChange

No equivalent

OnTheaterMode

No equivalent

OnThirdPartyUrlBlocked

No equivalent

OnTitleChange

OnDocumentTitleChanged

OnToolBar

No equivalent

OnUpdatePageStatus

No equivalent

OnVisible

No equivalent

OnWebWorkerFinsihed

No equivalent

OnWebWorkerStarted

No equivalent

OnWindowClosing

No equivalent

OnWindowSetHeight

No equivalent

OnWindowSetLeft

No equivalent

OnWindowSetResizable

No equivalent

OnWindowSetTop

No equivalent

OnWindowSetWidth

No equivalent

OnWindowStateChanged

No equivalent

Changes in TWebBrowser

The VCL TWebBrowser component still performs the same job as always, which is to render web content using the Internet Explorer WebBrowser browser control.

However, in addition to this default behaviour TWebBrowser has two new properties; the first property can be used to ask it to apply the newer Edge (Chromium) WebView2 browser control instead. This is achieved by the implementation using an embedded TEdgeBrowser component.

By using the property to use the Edge WebView2 browser control you can immediately benefit from a current, maintained browser, which will have security fixes made available by Microsoft.

However, the flip side of this is that the WebView2 browser control is not an integral part of every Windows installation.

The property SelectedEngine indicates which browser control you desire or require. The supported values are:

  • TWebBrowser.TSelectedEngine.IEOnly: the TWebBrowser functions as it always has, employing the IE WebBrowser control.
  • TWebBrowser.TSelectedEngine.EdgeIfAvailable: the TWebBrowser uses the Edge WebView2 browser control if possible, otherwise it falls back to the traditional IE WebBrowser control.
  • TWebBrowser.TSelectedEngine.EdgeOnly: the TWebBrowser attempts to use the Edge WebView2 browser control, however if this is not possible then no browsing is possible as there is no fallback option.

Some feedback is available via the ActiveEngine property, which offers these values:

  • TWebBrowser.TActiveEngine.None: no browser control is in use; if EdgeOnly was requested via SelectedEngine then the Edge browser could not be instantiated.
  • TWebBrowser.TActiveEngine.NoneYet: no browser control is in use yet, but an attempt is being made to initialize the Edge WebView2 browser control.
  • TWebBrowser.TActiveEngine.IE: the Internet Explorer WebBrowser browser control is in use.
  • TWebBrowser.TActiveEngine.Edge: the Edge WebView2 browser control is in use.
Attention: Just as with the TEdgeBrowser component, in order for TWebBrowser to successfully use the Edge WebView2 browser control there are two requirements:
  • The Edge (Chromium) browser is installed.
  • The Edge WebView2 control loader DLL (part of the Microsoft WebView2 SDK) is available, for example in the directory your project executable is output to.

To install the Microsoft Edge WebView2 control please follow the instructions on the TEdgeBrowser documentation page.

TWebBrowser Dual Personality Capabilities

When using TWebBrowser in its ‘Edge personality’ mode (SelectedEngine was set to either EdgeIfAvailable or EdgeOnly, and ActiveEngine has been changed to Edge) its various properties, methods, and events have been updated to operate as appropriately as they can.

Note that many of these properties, methods, and events are directly from the Internet Explorer WebBrowser control interfaces, so there are a number of them that now either return a default value, or raise an exception when running in Edge mode.

The following lists point out the behavior when running in Edge mode:

Methods

GoBack

Goes to previous page in browser history

GoForward

Goes to next page in browser history

GoHome

Raises an ENotImplemented exception

GoSearch

Raises an ENotImplemented exception

Navigate

The overload with only a URL parameter navigates to that URL, but the other overloads raise an ENotImplemented exception

Refresh

Reloads the current page

Refresh2

Reloads the current page

Stop

Stops the current navigation activity

Quit

Terminates the browser control’s supporting Edge process

ClientToWindow

Raises an ENotImplemented exception

PutProperty

Raises an ENotImplemented exception

GetProperty

Raises an ENotImplemented exception

Navigate2

The overload with only a URL parameter navigates to that URL, but the other overloads raise an ENotImplemented exception

QueryStatusWB

Raises an ENotImplemented exception

ExecWB

Raises an ENotImplemented exception

ShowBrowserBar

Raises an ENotImplemented exception

Read-only Properties

ControlInterface

Returns nil

DefaultInterface

NReturns nil

Application

Returns nil

Parent

Returns nil

Container

Returns nil

Document

Returns nil

TopLevelContainer

Returns True

type_

Returns an empty string

LocationName

Returns the current document title

LocationURL

Returns the current URL

Busy

Returns True when navigation is active, otherwise False

Name

Returns an empty string

HWND

Returns the window handle of the WebView2 browser control

FullName

Returns the full executable path of the Edge browser process being used by the WebView2 control

Path

Returns the full path of the folder of the Edge browser process being used by the WebView2 control

ReadyState

Returns one of a subset of the possible values, based on the state of the Edge control: READYSTATE_UNINITIALIZED, READYSTATE_LOADING or READYSTATE_COMPLETE

Published Read/Write Properties

Visible

Sets and returns the embedded Edge component’s Visible property

StatusBar

Sets and returns the embedded Edge component’s StatusBarEnabled property

StatusText

Ignores set value and returns an empty string

ToolBar

Ignores set value and returns 0

MenuBar

Ignores set value and returns False

FullScreen

Ignores set value and returns False

Offline

Ignores set value and returns False

Silent

Sets and returns the inverse value to/from the embedded Edge component’s DefaultScriptDialogsEnabled property

RegisterAsBrowser

Ignores set value and returns False

RegisterAsDropTarget

Ignores set value and returns False

TheaterMode

Ignores set value and returns False

AddressBar

Ignores set value and returns False

Resizable

Ignores set value and returns True

Events

OnStatusTextChange

Not called

OnProgressChange

Not called

OnCommandStateChange

Fired when the Edge component’s OnHistoryChanged event fires

OnDownloadBegin

Not called

OnDownloadComplete

Not called

OnTitleChange

Fired when the Edge component’s OnDocumentTitleChanged event fires

OnPropertyChange

Not called

OnBeforeNavigate2

Fired when the Edge component’s OnNavigationStarting event fires

OnNewWindow2

Fired when the Edge component’s OnNewWindowRequested event fires

OnNavigateComplete2

Fired when the Edge component’s OnNavigationCompleted event fires

OnDocumentComplete

Fired when the Edge component’s OnNavigationCompleted event fires

OnQuit

Not called

OnVisible

Not called

OnToolBar

Not called

OnMenuBar

Not called

OnStatusBar

Not called

OnFullScreen

Not called

OnTheaterMode

Not Called

OnWindowSetResizable

Not called

OnWindowSetLeft

Not called

OnWindowSetTop

Not called

OnWindowSetWidth

Not called

OnWindowSetHeight

Not called

OnWindowClosing

Not called

OnClientToHostWindow

Not called

OnSetSecureLockIcon

Not called

OnFileDownload

Not called

OnNavigateError

Not called

OnPrintTemplateInstantiation

Not called

OnPrintTemplateTeardown

Not called

OnUpdatePageStatus

Not called

OnPrivacyImpactedStateChange

Not called

OnNewWindow3

Fired when the Edge component’s OnNewWindowRequested event fires

OnSetPhishingFilterStatus

Not called

OnWindowStateChanged

Not called

OnNewProcess

Not called

OnThirdPartyUrlBlocked

Not called

OnRedirectXDomainBlocked

Not called

OnBeforeScriptExecute

Not called

OnWebWorkerStarted

Not called

OnWebWorkerFinsihed

Not called

OnShowScriptError

Not called

New Edge-related Demos

There are new demos installed with the product showcasing the new Edge and the updated TWebBrowser component. You can find them in the following folders:

  • Demos\Object Pascal\VCL\WebBrowser\Edge
  • Demos\Object Pascal\VCL\WebBrowser\InternetExplorer
  • Demos\CPP\VCL\WebBrowser\Edge