|
The SocketTools WebView ActiveX control is designed to provide a
modern embedded browser experience for Windows applications using the
Microsoft Edge (Chromium) rendering engine. Developers who previously
used the legacy WebBrowser control based on Internet Explorer will
find many of the same general concepts apply, including navigation,
script execution, document interaction and event-driven browser integration.
However, this control is not intended to be a drop-in replacement for
the older WebBrowser control and does not emulate Internet Explorer behavior.
Unlike the legacy WebBrowser control, which depended on the Internet Explorer
Trident engine, the WebView control uses the modern Edge WebView2 runtime to
provide improved security, standards compliance, JavaScript compatibility
and support for modern web technologies. This allows applications to
safely embed web content using the same rendering engine used by Microsoft Edge,
providing a more secure and reliable browsing experience for both local
and remote content.
While older applications will require code changes when migrating from
the WebBrowser control, developers familiar with the general browser
hosting model used by Internet Explorer should find the transition
straightforward. The control preserves a traditional Windows programming
model while exposing modern browser functionality through a simplified
ActiveX interface.
Initialization
To create an instance of the browser in your application, the
WebView2 runtime must be available. On modern versions of Windows, the
WebView2 runtime is included as part of the operating system and is
serviced through Windows Update. On older verions of Windows, such as
Windows 7 and Windows 8.1, it may be necessary to install the WebView2
runtime.
Initialize Event
This event occurs after the control has been created by
the form, prior to the browser environment being initialized. Some
properties, such as the DataFolder property, can only be
changed prior to an instance of the WebView control being initialized.
This event allows your application to set properties that define the
behavior of the browser prior to it being created and displayed to the
user. You can also use this event to specify the initial navigation
URL for the browser.
RuntimeAvailable Property
This property can help your application determine if the WebView2
runtime needs to be installed on the local computer.
DataFolder Property
Gets and sets the path to the user data folder used by
the control. By default, the control creates a unique per-session
folder under the current user's local profile. This temporary folder
is removed when the control is unloaded. Providing a specific path the
data folder allows multiple instances of the control to persist and
share session data.
Browser Window
When an instance of the WebView control is created, the rendering
of the browser content is handled entirely by the WebView2 engine.
Appearance
Property
Sets the visual appearance of the control's frame.
BackColor Property
Set the default background color, with support for transparency using
options when the browser window is attached.
BorderStyle Property
Determines whether a border is drawn
around the edge of the control.
ContextMenu Property
Shows or hides the built-in right-click context menu inside the browser view.
StatusBar
Property
Determines if the browser shows status text in the bottom-left
corner.
ZoomLevel Property
Get or set zoom as a percentage for accessibility or kiosk scenarios.
Refresh Method
Forces the browser host and child window to redraw themselves. This
clears the browser cache and causes the browser to reload the current
document and render it again on the display. This can useful if the
window needs to be completely redrawn due to changes in monitor DPI
contexts.
Navigation
The control supports standard HTTP and HTTPS URLs, as well
as local files using the file:// scheme or direct Windows file paths.
When you call a navigation function, the control automatically
normalizes the specified URL, resolving relative paths, encoding
unsafe characters, and converting local paths into properly formatted
file:// URLs as needed. Optional flags allow you to perform additional
safety checks during normalization, such as rejecting unsupported
schemes or disallowing navigation to local files from remote content.
This helps ensure that only trusted content is displayed, and reduces
the risk of mixed-content or cross-origin issues.
Under the hood, navigation is handled by the Microsoft Edge
(Chromium) engine, providing the same secure and standards-compliant
networking stack used by the desktop browser. Connections
automatically negotiate the most secure protocol supported by both
client and server, with full support for HTTP/2 and HTTP/3 when
available. The control also enforces TLS certificate validation and
can report detailed security information for each page, including the
certificate information and encryption strength. This ensures that
applications embedding web content benefit from the same modern
security features as a standalone browser.
AllowNavigation Property
Determines whether the control permits navigation to new URLs.
Navigate Method
Navigate to an Internet or local file URL and render the document.
DocumentText Property
Returns or replaces the current document with the specified HTML or plain text.
FilteredText Property
Returns the current document as plain text with any HTML markup
filtered out, while retaining links and other relevant information. If
your application needs to check a page for specific text, using this
function can simplify that process so you don't need to be concerned
with markup and scripting content.
Reload Method
Reload the current page, optionally clearting the browser cache.
Cancel Method
Cancel the current navigation. This is typically done within an
event handler to tell the browser it should stop loading the document.
GoBack Method
and GoForward Method
Move through the navigation history in the same way that back and
forward buttons work in a browser.
Navigation Events
The control uses event notifications to inform your application
when the user takes certain actions within the browser. These can also
be used by your application to control the browsing experience for the
user. For example, when a user clicks on a link, an event will tell
you that navigation to a new page has started. At that point, you can
evaluate the URL and decide if you want to permit the navigation or
cancel it.
NavigationStarting Event
This event occurs when a new
navigation is beginning.
NavigationCompleted Event
This event occurs when navigation to
a new page has completed. If there was an error, this event will
include the error notification.
HistoryChanged Event
The navigation history has changed, such
as when a user navigates to a new page.
SecurityChanged
This event occurs when the security state of
the current page changes.
Security
The control defaults to using secure HTTPS connections
whenever possible, automatically enforcing modern TLS protocols and
certificate validation. This ensures that data exchanged between the
embedded browser and remote servers is encrypted and protected against
tampering. When a page attempts to load both secure and non-secure
content, commonly referred to as mixed content, the browser may
block or downgrade certain requests to maintain security. Developers
should generally avoid mixing local or insecure resources with secure
pages, as this can lead to unexpected warnings in the embedded
browser. Your application can query detailed information about a
page's security state, including certificate details and encryption
strength, to display status indicators or perform custom validation.
Secure Property
Used to determine if the current document was retrieved using a
secure connection. This can be convenient for providing visual
indicators to users, such as a padlock icon for secure sites. The
security of a site is based on a combination of factors, such as if
TLS was used to retrieve the content, if the certificate is valid and
hasn't expired, and there is no mixed content.
Certificate Property
Returns information about the server's security certificate, if a
secure connection was established.
Encryption
Property
Returns information about the type of encryption used
with a secure connection.
Scripting and Messaging
Web pages displayed in the WebView control can communicate directly with the
host application using the standard window.chrome.webview.postMessage
interface provided by the WebView2 runtime. When a page sends a
message in this way, the control delivers it to the application
through its registered event handler. The message can contain plain
text or structured JSON data, allowing scripts to trigger
application actions or report results back to native code, making
it possible to create interactive hybrid interfaces. For example,
a local HTML dashboard that requests data from your application
or invokes native Windows functionality.
In the opposite direction, the host application can send messages
to the page using the PostWebMessage method. These messages are
received by the page's JavaScript code through an event listener
attached to window.chrome.webview. This provides a simple,
bidirectional channel for exchanging information between native code
and the web environment. Applications can use it to push status
updates, notify the page of user actions, or inject serialized data
without reloading the document. Together, the scripting and messaging
functions enable seamless integration between modern web content and
traditional Windows applications.
AllowScripting Property
Determines if JavaScript execution is permitted in the browser.
Most modern websites depend on JavaScript, so disabling scripting entirely
will prevent many sites from working correctly. However, if you are using
the control to display static content, scripting can be disabled as a
security measure.
AllowMessages Property
Enables or disables message passing between your application and the browser.
Execute Method
Executes JavaScript in the page and retrieve the result synchronously.
AsyncExecute Method
Executes JavaScript in the page asynchronously using an event
notification.
MessageReceived Event
This event occurs when a script running inside the browser sends a
message to the host.
ScriptCompleted Event
This event occurs when an asynchronous script execution completes.
Saving and Printing
The control provides built-in support for saving and
printing the current document using the browser's rendering engine.
Applications can save the displayed content in several formats,
including MHTML, HTML with supporting assets, PDF, or as an image
capture of the current viewport. This makes it easy to archive pages,
export reports, or capture visual output exactly as it appears on
screen. When printing, the control uses the standard print interface
provided by the browser, ensuring consistent output and access to all
installed printers. The print dialog is managed by the WebView runtime
rather than the application itself, providing users with the familiar
print options they would expect from a modern web browser.
SaveDocument Method
Save the current page in a chosen format. This method supports
saving the current document as text only, HTML text, MTHML or as
a PDF. It also supports saving a snapshot of the current browser
viewport as an image file in various formats such as JPEG and PNG.
PrintDocument Method
Show the system print dialog for the current document. This uses
the same general printing interface as the Edge browser.
File Downloads
When a user begins downloading a file, the control generates events
that allow the application to monitor the progress. Because downloads
are handled internally by the WebView runtime, the application does
not need to implement its own network or file transfer logic. This makes
it easy to integrate secure, managed downloads into your application
while retaining information about each file's transfer state.
DownloadStarting Event
A file download has started. This can be
canceled by the application if necessary.
DownloadCompleted Event
A file download has completed.
Browser Session
The control provides functions to manage the browser session,
including setting custom request headers, clearing the cache and
getting the value of headers set by the server in response to a
navigation request.
GetFirstHeader Method
and GetNextHeader Method
Enumerates all of the headers set by the server in response to a
navigation request. This is used after the current navigation has
completed.
GetHeader Method
Get the value of a specific header set by the server.
SetHeader Method
Set a custom request header and its value to be included with
subsequent navigation requests.
UserAgent Property
Get and set the standard User-Agent header value that is sent with every request.
ClearCache Method and
ClearCookies Method and
ClearHistory Method
Clear the cached data, cookies and navigation history for the
current session.
Timeout property
Adjust the amount of time the browser waits for a navigation request to complete.
|