Class # DesktopHTMLViewer --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Description Renders HTML and provides basic navigation features.

Warning

Using this control on Linux with certain types of hardware can cause it to draw the contents improperly. Should you encounter this, see `this note` for a resolution.

## Properties

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |--------------------------------------------------------------|------------------------------------------------------------|-----------|--------| | `Active` | `Boolean` | ✓ | | | `AllowAutoDeactivate` | `Boolean` | | | | `AllowTabStop` | `Boolean` | | | | `CanGoBack` | `Boolean` | ✓ | | | `CanGoForward` | `Boolean` | ✓ | | | `Enabled` | `Boolean` | | | | `Handle` | `Ptr` | ✓ | | | `Height` | `Integer` | | | | `Index` | `Integer` | | | | `Left` | `Integer` | | | | `LockBottom` | `Boolean` | | | | `LockLeft` | `Boolean` | | | | `LockRight` | `Boolean` | | | | `LockTop` | `Boolean` | | | | `MouseCursor` | `MouseCursor` | | | | `Name` | `String` | ✓ | | | `PanelIndex` | `Integer` | | | | `Parent` | `Object` | | | | `Scope` | `Integer` | ✓ | | | `TabIndex` | `Integer` | | | | `Tooltip` | `String` | | | | `Top` | `Integer` | | | | `Transparent` | `Boolean` | | | | `UserAgent` | `String` | | | | `Visible` | `Boolean` | | | | `Width` | `Integer` | | | | `Window` | `DesktopWindow` | ✓ | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|--------| | `AcceptFileDrop` | FileType As `String` | | | | `AcceptPictureDrop` | | | | | `AcceptRawDataDrop` | Type As `String` | | | | `AcceptTextDrop` | | | | | `Cancel` | | | | | `Close` | | | | | `DrawInto` | g As `Graphics`, x As `Integer`, y As `Integer` | | | | `ExecuteJavaScript` | js As `String` | | | | `ExecuteJavaScriptSync` | js As `String` | `Variant` | | | `GoBack` | | | | | `GoForward` | | | | | `IsAvailable` | | `Boolean` | | | `LoadPage` | Source As `String`, RelativeTo As `FolderItem` | | | | | File As `FolderItem` | | | | `LoadURL` | URL As `String` | | | | `Print` | showPrintDialog As `Boolean` = `True` | | | | `PrintToPDF` | file As `FolderItem` | | | | `Refresh` | immediately As `Boolean` = `False` | | | | | x As `Integer`, y As `Integer`, width As `Integer`, height As `Integer`, immediately As `Boolean` = `False` | | | | `SetFocus` | | | | | `ZoomTextIn` | | | | | `ZoomTextOut` | | | | ## Events

table-centered_column_4

| Name | Parameters | Returns | |----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|------------------------------------| | `CancelLoad` | URL As `String` | `Boolean` | | `Closing` | | | | `DocumentBegin` | URL As `String` | | | `DocumentComplete` | URL As `String` | | | `DocumentProgressChanged` | URL As `String`, PercentageComplete As `Integer` | | | `Error` | ErrorNumber As `Integer`, ErrorMessage As `String` | | | `FocusLost` | | | | `FocusReceived` | | | | `JavaScriptRequest` | method As `String`, parameters() As `Variant` | String | | `KeyDown` | Key As `String` | `Boolean` | | `KeyUp` | Key As `String` | | | `NewWindow` | url As `String` | DesktopHTMLViewer | | `Opening` | | | | `PrintComplete` | | | | `PrintError` | error As `RuntimeException` | | | `SecurityChanged` | IsSecure As `Boolean` | | | `StatusChanged` | NewStatus As `String` | | | `TitleChanged` | NewTitle As `String` | | ## Property descriptions

forsearch

DesktopHTMLViewer.Active **Active** As `Boolean` > Indicates whether the `control` is active. > > Active is `False` when the control's window is not in the foreground. When a `DesktopWindow` is deactivated, its controls are automatically deactivated unless `AllowAutoDeactivate` is set to `False`. > > This property is read-only.

forsearch

DesktopHTMLViewer.AllowAutoDeactivate **AllowAutoDeactivate** As `Boolean` Determines whether the control should be deactivated (on macOS) when the parent window is deactivated. The default is `True`.

forsearch

DesktopHTMLViewer.AllowTabStop **AllowTabStop** As `Boolean` > If `True`, the control is in the Tab Order and accepts the focus when the user tabs into it. The default is `True`. If `False`, the user cannot tab into it to give it the focus. However, the control can gain the focus by other means, such as the user's clicking on it or by setting the focus in code. > > This example removes the control from the Tab Order: > > ``` xojo > Me.AllowTabStop = False > ```

forsearch

DesktopHTMLViewer.CanGoBack **CanGoBack** As `Boolean` > If `True`, it indicates that there is a prior page that can be navigated to using `GoBack`. > > This property is read-only. > > This code in the `DocumentComplete` event handler disables a Back button if there is no prior page: > > ``` xojo > BackButton.Enabled = Me.CanGoBack > ```

forsearch

DesktopHTMLViewer.CanGoForward **CanGoForward** As `Boolean` > If `True`, it indicates that there is a next page that can be navigated to using `GoForward`. > > This property is read-only. > > This code in the `DocumentComplete` event handler disables a Forward button if there is no next page: > > ``` xojo > ForwardButton.Enabled = Me.CanGoForward > ```

forsearch

DesktopHTMLViewer.Enabled **Enabled** As `Boolean` > Determines if the control should be enabled when the owning window is opened. > > A disabled control cannot be clicked and cannot receive the focus. > > This example disables the control. > > ``` xojo > Me.Enabled = False > ```

forsearch

DesktopHTMLViewer.Handle **Handle** As `Ptr` > Returns a handle to the control. > > This property is read-only. > > For interfacing with Mac APIs using `Declares`, **DesktopControl.Handle** returns NSViews (except for `DesktopToolbar`). > > On Windows returns the HWND of the control. > > On Linux it returns a GtkWidget. > > The following gets a handle to the control. > > ``` xojo > Var p As Ptr = Me.Handle > ```

forsearch

DesktopHTMLViewer.Height **Height** As `Integer` > The height (in points) of the control. > > This example sets the height of the control to 100: > > ``` xojo > Me.Height = 100 > ```

forsearch

DesktopHTMLViewer.Index **Index** As `Integer` > If the control is used in a control set, this specifies the control's index in the set.

forsearch

DesktopHTMLViewer.Left **Left** As `Integer` > The distance from the left side of the control to the left side of its containing window or container. > > The following example moves the control 100 points from the left side of the window: > > ``` xojo > Me.Left = 150 > ```

forsearch

DesktopHTMLViewer.LockBottom **LockBottom** As `Boolean` > Determines whether the bottom edge of the control should stay at a set distance from the bottom edge of the parent control, if there is one, or the owning window. > > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockBottom = True > ```

forsearch

DesktopHTMLViewer.LockLeft **LockLeft** As `Boolean` > Determines whether the left edge of the control should stay at a set distance from the left edge of the parent control, if there is one, or the owning window. > > LockLeft and Locktop default to `True` when you add a new control to a window. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockLeft* has no effect unless *LockRight* is `True`. > > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockLeft = True > ```

forsearch

DesktopHTMLViewer.LockRight **LockRight** As `Boolean` > Determines whether the right edge of the control should stay at a set distance from the right edge of the parent control, if there is one, or the owning window. > > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockRight = True > ```

forsearch

DesktopHTMLViewer.LockTop **LockTop** As `Boolean` > Determines whether the top edge of the control should stay at a set distance from the top edge of the parent control, if there is one, or the owning window. > > LockTop and LockLeft default to `True` when you add a control to a window. Existing controls will be altered only if LockRight and/or LockBottom are not set. *LockTop* has no effect unless *LockBottom* is `True`. > > This property can be set in the control's Inspector. The following example sets it in code. > > ``` xojo > Me.LockTop = True > ```

forsearch

DesktopHTMLViewer.MouseCursor **MouseCursor** As `MouseCursor` > The cursor to be displayed while the mouse is within the control and both the `DesktopApplication` and `DesktopWindow` class's MouseCursor properties are `Nil`. > > If the `DesktopApplication` class's MouseCursor property is not `Nil` or the `DesktopWindow`'s MouseCursor property is not `Nil`, then any control's MouseCursor property is ignored. You can use a cursor stored in the `Cursors` module. On macOS, you can also obtain a `MouseCursor` from a resource file. > > This line in the Opening event of the control sets the default cursor to the finger pointer. > > ``` xojo > Me.MouseCursor = System.Cursors.FingerPointer > ```

forsearch

DesktopHTMLViewer.Name **Name** As `String` > The name of the control. Set the name of the control in the Inspector. > > This property is read-only.

forsearch

DesktopHTMLViewer.PanelIndex **PanelIndex** As `Integer` > If the control has been placed on a `DesktopTabPanel` or `DesktopPagePanel` control, this is the panel (page/tab) that the control is on. If the control is not on a panel, it returns -1. > > The first panel is numbered zero. If the control has been placed on a panel of a `DesktopTabPanel` or `DesktopPagePanel` control, it returns the panel number. If the control is not on a `DesktopPagePanel` or `DesktopTabPanel`, it returns -1. If you change the PanelIndex to a nonexistent panel, the control will disappear until you give it a PanelIndex value that corresponds to a panel that exists. > > If you are looking to change the currently selected panel (page/tab), use `DesktopPagePanel`. > > This code displays the panel index of the control that is on the page. > > ``` xojo > MessageBox(Me.SelectedPanelIndex.ToString) > ```

forsearch

DesktopHTMLViewer.Parent **Parent** As `Object` > Used to get and set the control's parent control or window. > > If the control is on the window, the Parent will be the `Window`. If the control is on the container, the Parent will be the `container`. If the control is completed enclosed by another control, the Parent will be that `control`. > > If you do not want the enclosing control to be the parent, set the Parent property of that control to `Nil` to make it the `Window`. > > If the parent control is somehow in another window, an `InvalidParentException` will occur. > > The following example sets the parent of the control to the window. > > ``` xojo > Me.Parent = Nil > ```

forsearch

DesktopHTMLViewer.Scope **Scope** As `Integer` > Used to determine whether access to the control is Public (0) or Private (2). The default is Public. > > This property is read-only. > >

> >

> > Note > >

> > This is a designtime-only property and thus can only be set in the Inspector and is not accessible via code. > >

> > If the Scope of a control is set to Private, it cannot be accessed from outside its parent window.

forsearch

DesktopHTMLViewer.TabIndex **TabIndex** As `Integer` > The control's position in the Tab Order. The control with whose TabIndex is 0 will get the focus first. > > On macOS, only controls where you enter data from the keyboard typically get the focus. In order to manually set focus to controls that don't allow keyboard entry, go to System Preferences, click on the Keyboard icon then on the Shortcuts tab and then check the *Use keyboard navigation to move focus between controls* checkbox. > > This example sets the control's TabIndex. > > ``` xojo > Me.TabIndex = 2 > ```

forsearch

DesktopHTMLViewer.Tooltip **Tooltip** As `String` > Text of help message displayed as a Windows or Linux "tooltip" or macOS help tag. > > The tip/tag is displayed when the user hovers the mouse cursor over the control. > > This example adds a tooltip to a control: > > ``` xojo > Me.Tooltip = "Click to bark." > ```

forsearch

DesktopHTMLViewer.Top **Top** As `Integer` > The distance from the top of the control to the top of its containing window or container. > > This example sets the top of the control to 140 points from the top of the window: > > ``` xojo > Me.Top = 140 > ```

forsearch

DesktopHTMLViewer.Transparent **Transparent** As `Boolean` > Determines whether the control is transparent on Windows. The default is `False`. Has no effect on macOS or Linux. > > Transparent controls draw more slowly and use more memory in order to cache the background. Unless you absolutely require transparency, leave this set to `False`. > > For projects that were created prior to 2018r1, this property defaults to `True` to emulate previous behavior. Consider changing it to `False` to improve performance if you do not require transparency.

forsearch

DesktopHTMLViewer.UserAgent **UserAgent** As `String` > Supports getting and setting a custom user agent string. > > UserAgent works on Linux, macOS and Windows. > > This example sets the UserAgent. > > ``` xojo > If Me.IsAvailable Then > Var agent As String > agent = "Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-us) AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16" > Me.UserAgent = agent > End If > ```

forsearch

DesktopHTMLViewer.Visible **Visible** As `Boolean` > Determines whether the control is visible when its owning window is opened. The default is `True`: the control is visible. > > The following code makes the control invisible: > > ``` xojo > Me.Visible = False > ```

forsearch

DesktopHTMLViewer.Width **Width** As `Integer` > The width (in points) of the control. > > The following example resizes the control: > > ``` xojo > Me.Width = 200 > ```

forsearch

DesktopHTMLViewer.Window **Window** As `DesktopWindow` > The control's parent window. > > This property is read-only. > > This code gets the parent window's Title property. > > ``` xojo > MessageBox(Me.Window.Title) > ``` ## Method descriptions

forsearch

DesktopHTMLViewer.AcceptFileDrop **AcceptFileDrop**(FileType As `String`) > Permits documents of type *FileType* to be dropped on the control. *FileType* must be a file type that you defined in via the `FileType` class or the File Type Sets Editor. > > This code in the Opening event makes it possible for the user to drop either a picture or a file that is a jpeg image. The File Type Sets editor was used to define the “image/jpeg” file type. It is one of the “Common File Types” that is available in the editor. > > ``` xojo > Me.AcceptPictureDrop > Me.AcceptFileDrop("image/jpeg") > ```

forsearch

DesktopHTMLViewer.AcceptPictureDrop **AcceptPictureDrop** > Permits pictures to be dropped on the control. > > If a control should accept pictures in a drag and drop, then AcceptPictureDrop needs to be called prior to the drop. Typically, it is in the Opening event of the control itself. For example, the line: > > ``` xojo > Me.AcceptPictureDrop > ``` > > in the Opening event of the control that will receive the dragged pictures is needed. When the picture is dropped, the `DropObject` event is called and this is where you will put your code to handle the drop. > > Opening Event: > > ``` xojo > Me.AcceptPictureDrop > ``` > > DropObject Event: > > ``` xojo > If obj.PictureAvailable Then > Me.Backdrop = obj.Picture > End If > ```

forsearch

DesktopHTMLViewer.AcceptRawDataDrop **AcceptRawDataDrop**(Type As `String`) > Permits data (of the Type specified) to be dropped on the control. > > The following specfies a generic file type defined in the File Type Sets editor. > > ``` xojo > Me.AcceptRawDataDrop("????") > ```

forsearch

DesktopHTMLViewer.AcceptTextDrop **AcceptTextDrop** > Permits text to be dropped on the control. > > This line in the Opening event of a control that can accept dragged text. > > ``` xojo > Me.AcceptTextDrop > ```

forsearch

DesktopHTMLViewer.Cancel **Cancel** > Cancels any current operations. > > ``` xojo > Me.Cancel > ```

forsearch

DesktopHTMLViewer.Close **Close** > Closes a control. > > Closing a control permanently removes the control from memory, making it impossible to access. You can close both non-indexed controls and indexed controls. When you close an indexed control, the indexes for the remaining controls will shift downward so that the indexes start with zero and are consecutive. > > The following code closes the control. When this is executed from a visible control, the control disappears from the window. > > ``` xojo > Me.Close > ```

forsearch

DesktopHTMLViewer.DrawInto **DrawInto**(g As `Graphics`, x As `Integer`, y As `Integer`) > Draws the contents of the control into the specified `Graphics` context. The parameters *x* and *y* are the coordinates of the top, left corner. > >

> >

> > Warning > >

> > Although the DesktopHTMLViewer has this method, it's not supported. > >

forsearch

DesktopHTMLViewer.ExecuteJavaScript **ExecuteJavaScript**(js As `String`) > Asynchronously executes the passed JavaScript in the context of the currently loaded page. > > Attempting to execute JavaScript before the page finishes loading (or if no page is loaded) is undefined and is unlikely to work. > > In order to call JavaScript on Windows, a document must already be loaded into the HTMLViewer. If no document is loaded, an `HTMLViewerException` is raised. > > This code will populate the search field on the wikipedia page (assuming it was previously loaded): > > ``` xojo > Var jsSrc As String > jsSrc = "document.forms[0].elements['search'].value=""xojo"";" > HTMLViewer1.ExecuteJavaScript(jsSrc) > ``` > > This code writes text to the HTML document: > > ``` xojo > Var this As String > this = "document.writeln(""hello"");" > HTMLViewer1.ExecuteJavaScript(this) > ```

forsearch

DesktopHTMLViewer.ExecuteJavaScriptSync **ExecuteJavaScriptSync**(js As `String`) As `Variant` > Synchronously executes the passed JavaScript in the context of the currently loaded page and returns the result. Only strings and numbers may be returned. > > Attempting to execute JavaScript before the page finishes loading (or if no page is loaded) is undefined and is unlikely to work. > > In order to call JavaScript on Windows, a document must already be loaded into the HTMLViewer. If no document is loaded, an `HTMLViewerException` is raised. > >

> >

> > Note > >

> > On Windows when using WebView2, `executeInXojoSync` uses JavaScript Promises to simulate synchronous behavior. Your JavaScript code must use `await` when calling it. For example: `const result = await executeInXojoSync("addNumbers", 2, 3);` > >

forsearch

DesktopHTMLViewer.GoBack **GoBack** > Navigates to the prior page. > > On a back button Pressed event handler, you can write: > > ``` xojo > HTMLViewer1.GoBack > ```

forsearch

DesktopHTMLViewer.GoForward **GoForward** > Navigates to the next page. > > On a forward button Pressed event handler, you can write: > > ``` xojo > HTMLViewer1.GoForward > ```

forsearch

DesktopHTMLViewer.IsAvailable **IsAvailable** As `Boolean` > If `True`, it indicates that the required support libraries required by the control were loaded. > > This property is read-only. > > The engine behind DesktopHTMLViewer is WebKit on macOS and Linux. On Windows, it uses either WebView2 or the Chromium Embedded Framework (CEF), depending on your build settings. > > This example in the Opening event handler calls the IsAvailable property prior to proceeding: > > ``` xojo > If Me.IsAvailable Then > Me.LoadURL("http://www.wikipedia.org") > End If > ```

forsearch

DesktopHTMLViewer.LoadPage **LoadPage**(source As `String`, base As `FolderItem`) > Loads the HTML in *source* into the HTMLViewer. > > Any links or temporary files will be resolved relative to the passed *base* `FolderItem`. > > In this example, the raw HTML is in a `TextArea`: > > ``` xojo > Var f As FolderItem = FolderItem.TemporaryFile.Child("index.html") > HTMLViewer1.LoadPage(TextArea1.Text, f) > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

DesktopHTMLViewer.LoadPage **LoadPage**(page As `FolderItem`) > Loads the supplied *page* into the HTMLViewer. *page* must be an actual file and not a folder. > >

> >

> > Warning > >

> > While this should work on Windows, there may be some limitations due to CEF security. These limitations do not apply when using WebView2. > >

> > This example loads an HTML file from disk. The file type has been added using the File Types Set Editor: > > ``` xojo > Var f As FolderItem > > f = FolderItem.ShowOpenFileDialog("text/html") > If f <> Nil Then > HTMLViewer1.LoadPage(f) > End If > ```

forsearch

DesktopHTMLViewer.LoadURL **LoadURL**(URL As `String`) > Loads the passed HTTP URL. Any protocol other than HTTP may or may not work as that is dependent on operating system behavior. > > On macOS, you need to ensure the URL is prefixed with "" or "" in order for it to load. > > This example loads a URL entered by the user in a `DesktopTextField`: > > ``` xojo > Var url As String = URLField.Text > If url.Left(7) <> "http://" Then url = "http://" + url > HtmlViewer1.LoadURL(url) > ```

forsearch

DesktopHTMLViewer.Print **Print**(showPrintDialog As `Boolean` = `True`) > Prints the contents of the HTMLViewer. On Linux, this requires WebKit 1.1.5 or newer. > > This example prints the current page. > > ``` xojo > HTMLViewer1.Print > ```

forsearch

DesktopHTMLViewer.PrintToPDF **PrintToPDF**(file As `FolderItem`) > Prints the contents of the HTMLViewer as a PDF to the *file* passed. > > This example prints the current page to a PDF file. > > ``` xojo > Var f as FolderItem = SpecialFolder.Desktop.Child("MyReport.PDF") > HTMLViewer1.PrintToPDF(f) > ``` > >

> >

> > Note > >

> > If content is being loaded dynamically when the part of the page becomes visible, it will not appear in the PDF document unless it has been exposed on screen as it will not have loaded yet. > >

forsearch

DesktopHTMLViewer.Refresh **Refresh**(immediately As `Boolean` = `False`) > Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if `True` is passed. > > If you are calling this so frequently that you experience a slowdown in your code, pass `True` for the immediately parameter. > > Calling this method causes the Render event to fire. > > Refresh the entire area immediately: > > ``` xojo > Me.Refresh(True) > ``` ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

DesktopHTMLViewer.Refresh **Refresh**(x As `Integer`, y As `Integer`, width As `Integer`, height As `Integer`, immediately As `Boolean` = `False`) > Redraws the portion specified of the contents of the control the next time the OS redraws the control or immediately if `True` is passed. > > Refresh a portion of the area the next time the OS redraws the control: > > ``` xojo > Me.Refresh(100, 150, 200, 300) > ```

forsearch

DesktopHTMLViewer.SetFocus **SetFocus** > If applicable, sets the focus to the DesktopUIControl. KeyDown events are directed to the control. > > If the control cannot get the focus on the platform on which the application is running, SetFocus does nothing. The SetFocus method of the `DesktopWindow` class or the `ClearFocus` method can be used to remove the focus from the control that currently has the focus, leaving no control with the focus. > >

> >

> > Note > >

> > On macOS, you need Full Keyboard Access turned on in System Preferences (Keyboard-\>Shortcuts) in order to manually set focus to non-text controls. > >

> > The following example in the Opening event sets the focus to the that control. If another control has the focus when this line is executed, then the user sees this control gets the focus. > > ``` xojo > Me.SetFocus > ```

forsearch

DesktopHTMLViewer.ZoomTextIn **ZoomTextIn** > Augments the size of the text used to display the HTML page content. You can use ZoomTextIn several times. > > The reverse action is achieved with the `ZoomTextOut` method. > > This example is the Pressed event of a `DesktopSegmentedButton`: > > ``` xojo > If segmentIndex = 0 Then > HtmlViewer1.ZoomTextIn > ElseIf segmentIndex = 1 Then > HtmlViewer1.ZoomTextOut > End If > ``` > >

> >

> > Note > >

> > On Windows, ZoomTextIn affects all DesktopHTMLViewers displaying content from the same domain. > >

forsearch

DesktopHTMLViewer.ZoomTextOut **ZoomTextOut** > Reduces the size of the text used to display the HTML page content. You can use ZoomTextOut several times. > > The reverse action is achieved with the `ZoomTextIn` method. > > This example is the Pressed event of a `DesktopSegmentedButton`: > > ``` xojo > If itemIndex = 0 Then > HtmlViewer1.ZoomTextIn > ElseIf itemIndex = 1 Then > HtmlViewer1.ZoomTextOut > End If > ``` > >

> >

> > Note > >

> > On Windows, ZoomTextOut affects all DesktopHTMLViewers displaying content from the same domain. > >

## Event descriptions

forsearch

DesktopHTMLViewer.CancelLoad **CancelLoad**(URL As `String`) As `Boolean` > Returns a `Boolean`. Return `True` to cancel loading the page.

forsearch

DesktopHTMLViewer.Closing **Closing** > The control is closing.

forsearch

DesktopHTMLViewer.DocumentBegin **DocumentBegin**(URL As `String`) > Fires when the HTML page is starting to load.

forsearch

DesktopHTMLViewer.DocumentComplete **DocumentComplete**(URL As `String`) > Called when the HTML page is finished loading.

forsearch

DesktopHTMLViewer.DocumentProgressChanged **DocumentProgressChanged**(URL As `String`, percentageComplete As `Integer`) > Fires when the progress has been updated. If *percentageComplete* is -1, the percentage cannot be determined.

forsearch

DesktopHTMLViewer.Error **Error**(errorNumber As `Integer`, errorMessage As `String`) > Fires when an error occurs. > > The errors you receive are the [standard HTTP Status Codes](http://en.wikipedia.org/wiki/List_of_HTTP_status_codes).

forsearch

DesktopHTMLViewer.FocusLost **FocusLost** > The `control` has lost the focus. > >

> >

> > Note > >

> > On macOS, controls other than text fields and lists will accept and lose focus only if the full keyboard access option is enabled in System Preferences/Keyboard. > >

forsearch

DesktopHTMLViewer.FocusReceived **FocusReceived** > The `control` has received the focus and has a selection rectangle around it. > >

> >

> > Note > >

> > On macOS, controls other than text fields and lists will accept focus only if the full keyboard access option is enabled in System Preferences/Keyboard. > >

forsearch

DesktopHTMLViewer.JavaScriptRequest **JavaScriptRequest**(method As `String`, parameters() As `Variant`) As String > Called when a JavaScript executed via `ExecuteJavaScript` or `ExecuteJavaScriptSync` calls ExecuteInXojo or ExecuteInXojoSync. > > A JavaScript executed via `ExecuteJavaScript` or `ExecuteJavaScriptSync` can call **executeInXojo()** or **executeInXojoSync()** to pass data back to the HTMLViewer via this 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 this event. The executeInXojoSync() method is synchronous and thus should be called as a function as it will receive the value returned by this event. > >

> >

> > Note > >

forsearch

DesktopHTMLViewer.KeyDown **KeyDown**(key As `String`) As `Boolean` > The user has pressed the *Key* passed while the `control` has the focus. > > Returning `True` prevents the KeyDown event on the parent control (usually the window) from executing. Returning `False` results in the execution of the KeyDown event of the parent control.

forsearch

DesktopHTMLViewer.KeyUp **KeyUp**(key As `String`) > Fires when the passed *Key* is released in the control that has the focus. > > It is not guaranteed to be the same key that received the KeyDown event.

forsearch

DesktopHTMLViewer.NewWindow **NewWindow**(URL As `String`) As `HTMLViewer` > Called when the HTML on page requests that a URL be opened in a new HTML viewer (a new window or tab depending how the user chooses to open it). > > Returns a new instance of an **HTMLViewer** to load the page in that viewer or `Return` `Nil` when you do not want to allow the window to open.

forsearch

DesktopHTMLViewer.Opening **Opening** > The control is about to be displayed. Use this event to initialize a control. > > The Opening event is called after the Constructor. > > Be warned that initializing control property values using the Constructor instead of the Opening event may result in those property values being overwritten by what is set in the Inspector. For best results, use the Opening event for control initialization rather than the control Constructor. > > If the control is supposed to handle drag and drop, you need to tell it which type of item it needs to be able to handle. The following example informs the control that pictures and files can be dropped on it. The type of the file it needs to support is specified via the File Types Editor. > > ``` xojo > Sub Opening() > Me.AcceptPictureDrop > Me.AcceptFileDrop("JPEG") > End Sub > ```

forsearch

DesktopHTMLViewer.PrintComplete **PrintComplete** > Printing has completed successfully. > >

> >

> > Important > >

> > On Windows, this event works when using `PrintToPDF`, but not with regular printing. > >

forsearch

DesktopHTMLViewer.PrintError **PrintError**(error as `RuntimeException`) > Printing has failed either because it was cancelled by the user or an error of some kind occured. > >

> >

> > Important > >

> > On Windows, this event works when using `PrintToPDF`, but not with regular printing. > >

forsearch

DesktopHTMLViewer.SecurityChanged **SecurityChanged**(isSecure As `Boolean`) > Fires when the document's security has changed. For example, entering a secure web site will cause this event to fire. > > This event is only called on Microsoft Windows.

forsearch

DesktopHTMLViewer.StatusChanged **StatusChanged**(newStatus As `String`) > Fires when the Status text has changed for the window. > > Due to changes made to the CEF3 library (Chromium Embedded Framework) this event is not called on Windows when using CEF. This event is also not called when using WebView2.

forsearch

DesktopHTMLViewer.TitleChanged **TitleChanged**(newTitle As `String`) > Fires when the Title of the Web page has been determined or has changed. ## Notes On macOS, the HTMLViewer supports getting and setting a custom user agent string and increasing or decreasing the font size. WebKit is used for all desktop HTML rendering on macOS and Linux. On Windows, DesktopHTMLViewer uses WebView2 when the WinUI Build Setting is enabled, or when the **HTMLViewer uses WebView2** option is enabled in the Windows Advanced Build Settings. Otherwise, it uses the Chromium Embedded Framework (CEF). --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### 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. On Windows when using WebView2, executeInXojoSync() uses JavaScript Promises to simulate synchronous behavior. Your JavaScript code must use `await` when calling it. For example: `const result = await executeInXojoSync("addNumbers", 2, 3);` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### 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. More information is available in the `Using Non-Secure URLs on macOS and iOS` topic. --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Windows HTML rendering backends On Windows, DesktopHTMLViewer supports two rendering backends: WebView2 and the Chromium Embedded Framework (CEF). WebView2 is always used when the WinUI Build Setting is enabled. For non-WinUI projects, you can enable WebView2 via the **HTMLViewer uses WebView2** option in the Windows Advanced Build Settings. When neither condition applies, CEF is used. To make plugins available to the DesktopHTMLViewer on Windows when using CEF, create a folder called WebKitPlugins within your Libs folder in your application folder and place the plugins you need there. When using CEF, 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 `System Requirements for current release` 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](http://webkitgtk.org) for information on how to use this system control). ### Camera and microphone access When a page is displayed that accesses the camera and/or microphone, they will automatically be accessible on Linux and Windows. However, for them to be accessible on macOS, your app must include an info.plist file with the following two entries: ``` NSCameraUsageDescriptionCamera description. NSMicrophoneUsageDescriptionMicrophone description. ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- #### Drawing issue The DesktopHTMLViewer may not draw its contents properly when using it on Linux on some hardware configurations. Should this happen, turning off hardware acceleration will resolve the issue. To turn off hardware acceleration in the App.Opening event, use the following code: ``` xojo System.EnvironmentVariable("WEBKIT_HARDWARE_ACCELERATION") = "OFF" ```

Note

When running your Xojo app on Linux distros running Wayland the drawing issue above is far more common. Because of this, hardware acceleration is off by default. You can turn it back on if you wish to test your app to see if it has this drawing issue or not.

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ## Sample code ``` xojo Var s As String = HTMLViewer1.ExecuteJavaScriptSync("document.documentElement.innerHTML;") ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 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`: ``` xojo 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: ``` xojo 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). ``` xojo If percentageComplete = -1 Then ' if it cannot be determined ProgressBar1.MaximumValue = 0 ' display indeterminate progress Else ProgressBar1.MaximumValue = 100 End if ProgressBar1.Value = percentageComplete ``` --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In the DocumentComplete event handler, hide the ProgressBar with the line: ``` xojo 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: ``` xojo 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: ``` xojo 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 and the window contains an HTMLBrowser named HTMLBrowser1. ``` xojo Var w As New MainWindow Title = "New Window" ' Title property of new window w.Show Return w.HTMLViewer1 ``` ## Compatibility | | | |-----------------------|---------| | **Project Types** | Desktop | | **Operating Systems** | All |

`DesktopUIControl` parent class; `URLConnection` class