From Xojo Documentation
Jump to: navigation, search

Class (inherits from RectControl)

Renders HTML and provides basic navigation features.

CancelLoad Error SecurityChanged
Close KeyDown StatusChanged
DocumentBegin KeyUp TitleChanged
DocumentComplete NewWindow
DocumentProgressChanged Open

Active ReadOnlyProperty.png LockBottom Scope ReadOnlyProperty.png
AutoDeactivate LockLeft TabIndex
CanGoBack ReadOnlyProperty.png LockRight TabStop
CanGoForward ReadOnlyProperty.png LockTop Top
Enabled MouseCursor TrueWindow ReadOnlyProperty.png
Handle ReadOnlyProperty.png MouseX ReadOnlyProperty.png UserAgent
Height MouseY ReadOnlyProperty.png Visible
HelpTag Name Width
Index ReadOnlyProperty.png PanelIndex Window ReadOnlyProperty.png
IsAvailable ReadOnlyProperty.png Parent
Left Renderer ReadOnlyProperty.png

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


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

Webkit on Windows

You can use WebKit on Windows by setting the Renderer property to WebKit (1). Using WebKit on Windows adds the entire WebKit engine to your application, increasing its size by about 20MB.

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

When using WebKit on Windows, HTMLViewer.Handle returns a pointer to the cef_browser_t struct.

Windows IE Version

On Windows, the Native Renderer is probably using an older version of the Internet Explorer renderer. This may result in web pages that do not display or work as you expect. You can tell Windows to use a newer version of the IE rendering engine with a Registry setting. This is how you can change it using Xojo:

Dim reg As New RegistryItem("HKEY_CURRENT_USER\SOFTWARE\Microsoft")
reg = reg.AddFolder("Internet Explorer")
reg = reg.AddFolder("Main")
reg = reg.AddFolder("FeatureControl")
reg.Value(App.ExecutableFile.Name) = &h2af9 ' IE 11 renderer

Windows Performance

On Windows, the Native Renderer might not use the GPU by default, which may result in slower rendering speeds depending on what you are displaying. You can enable it via the Registry:

Dim reg As New RegistryItem("HKEY_CURRENT_USER\SOFTWARE\Microsoft")
reg = reg.AddFolder("Internet Explorer")
reg = reg.AddFolder("Main")
reg = reg.AddFolder("FeatureControl")
reg = reg.AddFolder("FEATURE_GPU_RENDERING")
reg.Value(App.ExecutableFile.Name) = 1

Linux Support

If it is available, the Linux HTMLViewer uses WebKit (libwebkitgtk version 1). If it is not available, it uses libgtkhtml. Most newer Linux distributions should have the WebKit library installed. This includes Ubuntu 8.x and above.

Ubuntu 12 and higher only include WebKit v3 and does not provide any backward compatible versions. In order to use HTMLViewer on these versions of Ubuntu, you need to install WebKit version 1:

 sudo apt-get install libwebkitgtk-1.0.0

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).


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

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


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

ProgressBar1.Value = 0
ProgressBar1.Visible = True

In the DocumentProgressChanged event, increment the value of the ProgressBar. 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
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 HTMLViewer'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 TextField to display the status of the load process. In the HTMLViewer's StatusChanged event handler, set the value of this TextField. 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.

Dim w As New MainWindow
Title = "New Window" //Title property of new window
Return w.HTML
Personal tools

Starting Out
Dig Deeper
More Help