Display web content in a QML scene More...
Import Statement: | import com.canonical.Oxide 1.15 |
Instantiates: | OxideQQuickWebView |
WebView is the central class that applications use to embed web content in a QML scene.
Applications can load web content by setting url or calling loadHtml. Load progress can be observed by monitoring the loading property, listening to events from loadEvent and observing the loadProgress property.
The WebView API contains basic navigation actions in the form of goBack, goForward, reload and stop.
The security status of the WebView is provided via securityStatus. If a certificate error is encountered when trying to establish a secure connection to a site, then this is signalled to the application via certificateError. In some cases, this provides the application with an opportunity to abort or continue the connection.
WebView doesn't provide any auxilliary user interfaces (JS dialogs, context menu etc) by itself. It is currently the application's responsibility to provide these as QML components by setting the alertDialog, beforeUnloadDialog, confirmDialog, contextMenu, filePicker, popupMenu and promptDialog properties.
A structure that represents the frames within a currently displayed document is provided via the rootFrame property. This allows applications to send messages to user scripts that it has injected in to them.
The WebView provides APIs to allow applications to implement session-restore type functionality (currentState, restoreState and restoreType).
There is an API that allows applications to intercept content-initiated navigations, which is useful for implementing web applications (navigationRequested). There is also an API to allow web content to open new web views (newViewRequested).
It is possible for applications to implement private browsing functionality by creating WebViews with the incognito property set to true.
The API provides various signals to allow web content to request permission to access various resources, such as location (via geolocationPermissionRequested), media capture devices (via mediaAccessPermissionRequested) and the system's notification API (via notificationPermissionRequested).
alertDialog : Component |
beforeUnloadDialog : Component |
This indicates content that has been blocked in this WebView.
Possible values are:
Constant | Description |
---|---|
WebView.ContentTypeNone | (0) No content is blocked |
WebView.ContentTypeMixedDisplay | Passive mixed content was blocked on this page. This will only happen if WebPreferences::canDisplayInsecureContent is set to false. The application can temporarily override this by calling setCanTemporarilyDisplayInsecureContent. |
WebView.ContentTypeMixedScript | Active mixed content was blocked on this page. This will only happen if WebPreferences::canRunInsecureContent is set to false. The application can temporarily override this by calling setCanTemporarilyRunInsecureContent. |
This QML property was introduced in OxideQt 1.2.
confirmDialog : Component |
context : WebContext |
The WebContext to use for this WebView. This can be set during construction - attempts to change it afterwards will be ignored.
If the application doesn't set this, then WebView will use the application default WebContext (Oxide::defaultWebContext).
The application should ensure that the provided WebContext outlives this WebView. Deleting the WebContext whilst the WebView is still alive may cause some features to stop working.
If this WebView is created as a request to open a new window (via newViewRequested), then the WebContext will be inherited from the opening WebView. Setting this will have no effect.
Attempts to set this when Oxide::processModel is Oxide.ProcessModelSingleProcess will be ignored. Only the default WebContext can be used in single process mode.
contextMenu : Component |
This QML property was introduced in OxideQt 1.8.
This is the serialized state of the WebView. If this WebView is deleted, it will be possible to restore it by passing the serialized state to restoreState when constructing a new WebView.
This property is currently not notifiable.
This QML property was introduced in OxideQt 1.4.
This indicates the editing commands that are currently active and available via the executeEditingCommand function for this WebView.
Possible values are:
Constant | Description |
---|---|
WebView.NoCapability | (0) No editing commands are available |
WebView.UndoCapability | The EditingCommandUndo command is active |
WebView.RedoCapability | The EditingCommandRedo command is active |
WebView.CutCapability | The EditingCommandCut command is active |
WebView.CopyCapability | The EditingCommandCopy command is active |
WebView.PasteCapability | The EditingCommandPaste command is active |
WebView.EraseCapability | The EditingCommandErase command is active |
WebView.SelectAllCapability | The EditingCommandSelectAll command is active |
This QML property was introduced in OxideQt 1.12.
See also executeEditingCommand.
filePicker : Component |
findController : FindController |
The WebView's FindController instance. Please refer to the documentation for FindController for more details about how to use it.
This QML property was introduced in OxideQt 1.8.
Whether fullscreen has been granted to this webview.
Applications should set this to true in response to a request from web content to enter fullscreen mode (via the fullscreenRequested signal) if it entered fullscreen. Doing this will cause Oxide to indicate to web content that it is now fullscreen, and will result in the fullscreen element occupying the whole webview.
Applications should set this to false again in response to a request from web content to leave fullscreen mode or if the application exits fullscreen.
Note: Oxide does not control the fullscreen mode of the application window. It is the responsibility of the application to do this, and it is the responsibility of the application to hide its UI when entering fullscreen.
hoveredUrl : url |
When using a pointing device, this indicates the URL of the link currently under the pointer. If no link is under the pointer, then this will be null.
This will also indicate the URL of a link focused by the keyboard.
This QML property was introduced in OxideQt 1.12.
icon : url |
The URL of the favicon for the current page. This will correspond to the URL specified by the <link rel="icon"> element if it exists in the page, else it will fallback to <domain>/favicon.ico if the page is loaded over http: or https:.
The application is responsible for downloading the icon. The icon specified by this property is not guaranteed to exist.
There is currently no support for other favicon types (<link rel="apple-touch-icon"> or <link rel="apple-touch-icon-precomposed">).
Whether the webview is in incognito mode. This can be set by the application during construction - attempts to change it afterwards will be ignored.
The default is false.
Incognito webviews won't save browsing activity such as network cache, cookies and local storage. They also won't reveal currently saved items to web pages.
If this WebView is created as a request to open a new window (via newViewRequested), then the incognito setting will be inherited from the opening WebView. Setting this will have no effect.
The current load progress as a percentage. The value of this can range between 0 and 100.
When loading is false, this will be 100.
This property indicates whether a load is currently in progress.
Note: The notifier signal for this property is loadingStateChanged rather than the expected loadingChanged.
locationBarController : LocationBarController |
This is the LocationBarController instance for this WebView. Please refer to the documentation for LocationBarController for more information about how to use it.
This QML property was introduced in OxideQt 1.5.
The maximum permitted zoom factor. Attempts to set zoomFactor to a value greater than this will be ignored.
This QML property was introduced in OxideQt 1.15.
See also zoomFactor.
messageHandlers : list<ScriptMessageHandler> |
The list of script message handlers attached to this webview. These can handle messages from user scripts injected in to frames inside this webview that aren't handled by a ScriptMessageHandler attached to the destination WebFrame.
The minimum permitted zoom factor. Attempts to set zoomFactor to a value less than this will be ignored.
This QML property was introduced in OxideQt 1.15.
See also zoomFactor.
navigationHistory : NavigationHistory |
The navigation history for this webview. Please refer to the documentation for NavigationHistory for more information about how to use this.
popupMenu : Component |
preferences : WebPreferences |
The WebPreferences object used to customize the behaviour of this WebView. Please refer to the documentation for WebPreferences for more information about how to use this.
This always returns a valid WebPreferences instance.
The default WebPreferences instance is a child of this WebView.
Applications can set this to a different WebPreferences instance. If the provided instance does not have a parent, then this WebView will set itself as the parent. When setting a new WebPreferences instance, the old instance will be deleted if this WebView is its parent.
If this WebView is created as a request to open a new window (via newViewRequested), then the default WebPreferences will be copied from the one provided by the opening WebView.
If this view's WebPreferences instance is deleted, a default WebPreferences instance will be recreated automatically for this WebView.
promptDialog : Component |
request : NewViewRequest |
This should be set during construction of a WebView created in response to newViewRequested. Please refer to the documentation for newViewRequested.
This is a write-only property. Reads from it always return null.
This should be set during construction of a WebView to restore the state from a previous session. To do this, the application can set this to the serialized state obtained from currentState in a previous session.
If this WebView is created as a request to open a new window (via newViewRequested), then setting this has no effect.
This is a write-only property. Reads from it always return an empty string.
This QML property was introduced in OxideQt 1.4.
This should be set during construction of a WebView in conjunction with restoreState. It defines the type of restore, which may affect things like cache policy.
Possible values are:
Constant | Description |
---|---|
WebView.RestoreCurrentSession | This WebView is being restored from a WebView that was closed in this session. |
WebView.RestoreLastSessionExitedCleanly | This WebView is being restored from a WebView closed at the end of the previous session. |
WebView.RestoreLastSessionCrashed | This WebView is being restored from a WebView |
This is a write-only property. Reads from it always return RestoreLastSessionExitedCleanly.
This QML property was introduced in OxideQt 1.4.
securityStatus : SecurityStatus |
The security status for this WebView. Please refer to the documentation for SecurityStatus for more information about how to use this.
This QML property was introduced in OxideQt 1.2.
The title of the currently displayed page. This is based on the <title> tag or document.title.
touchSelectionController : TouchSelectionController |
The WebView's TouchSelectionController instance. Please refer to the documentation for TouchSelectionController for more details about how to use it.
This QML property was introduced in OxideQt 1.12.
url : url |
The visible URL. This is the URL that a web browser should display in its addressbar.
This will indicate the pending URL if a navigation is in progress and the navigation is application initiated, or it is renderer initiated and this webview hasn't been accessed by another webview.
Writing a URL to this property will initiate a new navigation.
Note: Applications should not base any policy or security decisions on the value of this property.
This is the current state of the process used for running web content in this WebView.
Possible values are:
Constant | Description |
---|---|
WebView.WebProcessRunning | The web content process is running normally. This value is also used if this WebView doesn't yet have a web content process. |
WebView.WebProcessKilled | The web content process has been killed by the system or a signal sent to it. This might happen as a result of low memory or application lifecycle management. |
WebView.WebProcessCrashed | The web content process has crashed or otherwise exited abnormally. |
WebView.WebProcessUnresponsive | The web content process is no longer responding to events. The timeout for triggering this is currently set to 5s. |
If Oxide::processModel is Oxide.ProcessModelSingleProcess, this will only ever be WebProcessRunning or WebProcessUnresponsive
This QML property was introduced in OxideQt 1.8.
The page-zoom factor for this WebView. This is 1 by default.
Changes to this will also propagate to other webviews displaying a page from the same host. The zoom factor will persist for the remainder of the session.
When the WebView is navigated to a new host, the zoom factor is either restored to the default or restored to the last defined zoom factor for the new host.
Attempts to set the zoom factor to a value that is less than minimumZoomFactor or greater than maximumZoomFactor will be ignored.
This QML property was introduced in OxideQt 1.15.
See also minimumZoomFactor and maximumZoomFactor.
void certificateError(CertificateError error) |
This signal is emitted when an error is encountered with the X.509 certificate provided by a server when trying to establish a secure connection. Please refer to the documentation for CertificateError for more information about how to use it.
The ownership of error is passed to the QML engine. This means that applications can respond to this asynchronously for errors that are overridable.
This QML signal was introduced in OxideQt 1.2.
This signal is emitted when a web page calls window.close(). As calling window.close() is destructive, the application must respond to this by deleting the webview.
Note: Web pages can only delete windows that they created, unless WebPreferences::allowScriptsToCloseWindows is set to true.
This QML signal was introduced in OxideQt 1.4.
void downloadRequested(DownloadRequest request) |
This signal is a request for the application to download the resource specified by request. Please refer to the documentation for DownloadRequest for more information about how to use it.
request is owned by the QML engine and will be garbage collected when it goes out of scope.
void frameAdded(WebFrame frame) |
This signal is used to indicate that frame was added to the frame tree for this webview.
void frameRemoved(WebFrame frame) |
This signal is used to indicate that frame was removed from the frame tree for this webview.
This signal indicates that web content has requested to change the fullscreen state.
If fullscreen is true, then this is a request to enter fullscreen mode. If the application permits this then it should make its window fullscreen, hide all of its UI, and respond by setting the fullscreen property to true.
If fullscreen is false, then this is a request to exit fullscreen mode. In this case, the application should un-fullscreen its window, unhide all of its UI and respond by setting the fullscreen property to false.
void geolocationPermissionRequested(GeolocationPermissionRequest request) |
This signal indicates that the page inside this webview would like to access the current location. Please refer to the documentation for PermissionRequest for more information about how to use it.
The ownership of request is passed to the QML engine. This means that applications can respond to this asynchronously. request will be garbage collected when it goes out of scope.
void httpAuthenticationRequested(HttpAuthenticationRequest request) |
This signal is a request for HTTP authentication credentials. Please refer to the documentation for HttpAuthenticationRequest for more information about how to use it.
This QML signal was introduced in OxideQt 1.9.
This signal indicates that the web content inside this webview triggered a console message, either via a call to console.log() or because of some message logged inside Blink.
message provides the actual message. The source of the message is indicated by sourceId and lineNumber.
level indicates the severity level of the message. It can be one of the following values:
Constant | Value |
---|---|
WebView.LogSeverityVerbose | |
WebView.LogSeverityInfo | |
WebView.LogSeverityWarning | |
WebView.LogSeverityError |
void loadEvent(LoadEvent event) |
This signal is used to notify the application of load events in the main frame. Please refer to the documentation for LoadEvent for more information about how to use it.
event is owned by the QML engine and will be garbage collected when it goes out of scope.
void mediaAccessPermissionRequested(MediaAccessPermissionRequest request) |
This signal indicates that the page inside this webview would like to access media capture devices because of a call to MediaDevices.getUserMedia(). Please refer to the documentation for MediaAccessPermissionRequest for more information about how to use it.
The ownership of request is passed to the QML engine. This means that applications can respond to this asynchronously. request will be garbage collected when it goes out of scope.
This QML signal was introduced in OxideQt 1.8.
void navigationRequested(NavigationRequest request) |
This signal indicates that web content would like to navigate this webview. Please refer to the documentation for NavigationRequest for more information about how to use it.
If NavigationRequest::disposition is set to something other than NavigationRequest::DispositionCurrentTab, then this is part of a request to open a new webview. If the application allows this request, then newViewRequested will be signalled afterwards to tell the application when to create a new webview.
The application must respond to this synchronously.
void newViewRequested(NewViewRequest request) |
This signal indicates that the application should create a new webview, either as a result of web content calling window.open() or a link click with modifier keys pressed. Please refer to the documentation for NewViewRequest for more information about how to use it.
The application must respond to this by constructing a new WebView, and passing request to the request property during construction.
If the application doesn't connect to this signal, then all requests to open a new webview will be converted to navigations in this webview.
Note: Applications that support creating new webviews must also connect to closeRequested.
void notificationPermissionRequested(PermissionRequest request) |
This signal indicates that the page inside this webview would like to use the notification API. Please refer to the documentation for PermissionRequest for more information about how to use it.
Note that PermissionRequest::embedder behaves differently for notification permission requests - it will be equal to PermissionRequest::origin.
The ownership of request is passed to the QML engine. This means that applications can respond to this asynchronously. request will be garbage collected when it goes out of scope.
This QML signal was introduced in OxideQt 1.11.
This is the response to a call to prepareToClose. proceed is a hint that indicates whether the application should proceed to delete the webview.
If proceed is false, then this means that the site caused a beforeunload dialog to appear and the user declined the attempt to leave the page. This is a hint that the application shouldn't proceed to delete the webview.
This QML signal was introduced in OxideQt 1.4.
void addMessageHandler(ScriptMessageHandler handler) |
Add handler to the list of script message handlers attached to this view. If handler is already attached to another WebView or WebFrame, then this will return without making any changes.
If handler is already attached to this view then it will be moved to the end of the list.
This view will assume ownership of handle by setting itself as the parent.
If handle is deleted whilst it is attached to this view, then it will automatically be detached.
Execute the editing command defined by command. If the specified command is not defined as currently active by editingCapabilities, this will have no effect.
Possible values for command are:
Constant | Description |
---|---|
WebView.EditingCommandUndo | Undo the previous change |
WebView.EditingCommandRedo | Redo the last undone change |
WebView.EditingCommandCut | Delete the text that is currently selected, copying it to the clipboard in the process |
WebView.EditingCommandCopy | Copy the currently selected text to the clipboard |
WebView.EditingCommandPaste | Paste the contents of the clipboard at the current cursor position |
WebView.EditingCommandErase | Delete the text that is currently selected |
WebView.EditingCommandSelectAll | Select all of the text in the editor |
This QML method was introduced in OxideQt 1.8.
void loadHtml(string html, url baseUrl = undefined) |
Load the HTML specified by html in to this WebView. It will be loaded as a percent encoded data: URL with the mediatype set to "text/html;charset=UTF-8".
If baseUrl is specified, the provided URL will be used as the security origin for the page.
Causes Oxide to run the current page's beforeunload handler if there is one. This should be called by applications before the WebView is deleted.
The response to this will be delivered asynchronously by the prepareToCloseResponse signal.
This QML method was introduced in OxideQt 1.4.
Reload the page that is currently displayed in the WebView.
void removeMessageHandler(ScriptMessageHandler handler) |
Remove handler from the list of script message handlers attached to this view.
This will unparent handler, giving ownership of it back to the application.
Calling this allows the WebView to temporarily display passive mixed content. This will only have an effect if blockedContent indicates that passive mixed content is currently being blocked.
The effect of this call is temporary - passive mixed content will be disallowed the next time a navigation is committed inside this WebView.
Calling this triggers a reload of the page.
This QML method was introduced in OxideQt 1.2.
Calling this allows the WebView to temporarily run active mixed content. This will only have an effect if blockedContent indicates that active mixed content is currently being blocked.
The effect of this call is temporary - active mixed content will be disallowed the next time a navigation is committed inside this WebView.
Calling this triggers a reload of the page.
This QML method was introduced in OxideQt 1.2.
Terminate the current web process. This call is asynchronous and won't wait for the process to die before returning.
This function is useful for terminating web content processes that have become unresponsive.
Calling this when Oxide::processModel is Oxide.ProcessModelSingleProcess will result in the calling process being killed.
This QML method was introduced in OxideQt 1.19.