DesktopHTMLViewer

From Xojo Documentation

Class (inherits from DesktopUIControl)

Renders HTML and provides basic navigation features.

Events
CancelLoad Error MouseDrag
Closing FocusLost MouseUp
ConstructContextualMenu FocusReceived NewWindow
ContextualMenuItemSelected JavaScriptRequest Opening
DocumentBegin KeyDown SecurityChanged
DocumentComplete KeyUp StatusChanged
DocumentProgressChanged MouseDown TitleChanged


Properties
Active fa-lock-32.png Left TabIndex
AllowAutoDeactivate LockBottom Tooltip
AllowTabStop LockLeft Top
CanGoBack fa-lock-32.png LockRight Transparent
CanGoForward fa-lock-32.png LockTop UseSandbox
Enabled MouseCursor UserAgent
Handle fa-lock-32.png Name fa-lock-32.png Visible
Height PanelIndex Width
Index fa-lock-32.png Parent Window fa-lock-32.png
IsAvailable fa-lock-32.png Scope fa-lock-32.png


Methods
AcceptFileDrop DrawInto LoadURL
AcceptPictureDrop ExecuteJavaScript Print
AcceptRawDataDrop ExecuteJavaScriptSync Refresh
AcceptTextDrop GoBack SetFocus
Cancel GoForward ZoomTextIn
Close LoadPage ZoomTextOut

Notes

On macOS, the HTMLViewer supports getting and setting a custom user agent string and increasing or decreasing the font size.

Exchanging Data With JavaScript

A JavaScript executed via ExecuteJavaScript or ExecuteJavaScriptSync can call executeInXojo() or executeInXojoSync() to pass data back to the HTMLViewer via the JavaScriptRequest event. Both can be passed any number of parameters though the first parameter must be a string. For all subsequent parameters, only strings and numbers are supported. The executeInXojo() method is asynchronous and thus will not receive a value returned by the JavaScriptRequest event. The executeInXojoSync() method is synchronous and thus should be called as a function as it will receive the value returned by the JavaScriptRequest event.

App Transport Security

Starting with MacOS 10.11 and Xojo 2018r4, your apps have to use secure "https" connections or you will get this error: "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection". You can work around this by providing a plist with your app to indicate what non-secure URLs you are using. For more information:

Webkit on Windows

To make plugins available to the DesktopHTMLViewer on Windows, create a folder called WebKitPlugins within your Libs folder in your application folder and place the plugins you need there.

The Handle property returns a pointer to the cef_browser_t struct.

Linux Support

If it is available, the Linux HTMLViewer uses WebKit (libwebkitgtk version 3).

Refer to the Resources:System_Requirements#64-bit Configuration for Running 32-bit_Apps section for commands that you can use to install libwebkitgtk v3 on various Linux distributions.

On Linux, HTMLViewer.Handle returns the GtkScrolledWindow that hosts the WebKitWebView control (please refer to the WebKitGTK site for information on how to use this system control).

Sample Code

To implement a simple web browser, create a window with a large DesktopHTMLViewer control. Set its LockLeft, LockTop, LockRight, and LockBottom properties so that it resizes as the user resizes the window. Use a DesktopTextField as the URL entry area and a DesktopButton as the browser's Go button. That is, the user clicks Go to display the URL entered into the DesktopTextField.

In this example, the HTMLViewer is named “HTML”. The following code is in the Pressed event of the DesktopButton:

HTML.LoadURL(TextField.Text)

You can use a DesktopProgressBar to indicate that the web page is loading. In the DesktopHTMLViewer's DocumentBegin event, initialize and show the DesktopProgressBar with the code:

ProgressBar1.Value = 0
ProgressBar1.Visible = True

In the DocumentProgressChanged event, increment the value of the DesktopProgressBar. This event handler is passed the value of PercentageComplete (0 to 100).

If percentageComplete = -1 Then // if it cannot be determined
ProgressBar1.Maximum = 0 // display indeterminate progress
Else
ProgressBar1.Maximum = 100
End if

ProgressBar1.Value = percentageComplete

In the DocumentComplete event handler, hide the ProgressBar with the line:

ProgressBar1.Visible = False

When the title of the web page has been received, you can display it in the window's Title bar using the DesktopHTMLViewer's TitleChanged event. It is passed the new title in the String parameter newTitle. Update the window title with the line:

Title = newTitle

Use a second DesktopTextField to display the status of the load process. In the HTMLViewer's StatusChanged event handler, set the value of this DesktopTextField. This event handler is passed the current status in the String parameter, NewStatus. Display this string with the following line in the StatusChanged event:

TextField1.Text = NewStatus

If a new browser window is supposed to open, you need to insert some code to handle this event. For example, the user clicks a link that is supposed to display the new page in another window. Use the NewWindow event handler to create the window. The following code assumes that the browser is contained in a window called MainWindow.

Var w As New MainWindow
Title = "New Window" //Title property of new window
w.Show
Return w.HTML

See Also

HTTPSocket and URLConnection classes