Class widget:webview

WebKitGTK+ webview widget
This module is only available from the UI process Lua state.

Creating a new webview widget

To create a new webview widget, use the widget constructor:

local view = widget{ type = "webview" }

print(type(view)) -- Prints "widget"
print(view.type)  -- Prints "webview"

Destroying a webview widget

view:destroy()

Methods

view:search_next ()

Focus the next occurrence of the text in the webview.

view:search_previous ()

Focus the previous occurrence of the text in the webview.

view:go_back ()

Load the previous item in the webview history.

Return Values

  • boolean
    Whether the history item was loaded.

view:go_forward ()

Load the next item in the webview history.

Return Values

  • boolean
    Whether the history item was loaded.

view:can_go_back ()

Determine whether the webview has a previous history item.

Return Values

  • boolean
    Whether the webview has a previous history item.

view:can_go_forward ()

Determine whether the webview has a subsequent history item.

Return Values

  • boolean
    Whether the webview has a subsequent history item.

view:eval_js (script, options)

Asynchronously run a string of JavaScript code in the context of the webview. The JavaScript will run even if the enable_javascript property of the webview is false, as it is run within a separate JavaScript script world.

To evaluate a string of JavaScript, provide a callback function within the options table:

view:eval_js("document.body.clientHeight", { callback = function (ret, err)
    assert(not err, err) -- Check for any error
    msg.info("The document height is %d pixels", ret)
end })

Calling options

The following keys can be set in the options argument:

  • source : A string to be used in error messages.
  • no_return : A boolean; if false, no result or error will be returned.
  • callback : A callback function.

Parameters

  • script
    Type: string
    The JavaScript string to evaluate.
  • options
    Type: table
    Additional arguments.

view:load_string (string, content_uri)

Load the given string string into the webview, and set the webview URI to content_uri. This replaces the existing contents of the webview.

In order to display an error page, it's recommended to use the error_page module. This module automatically implements a number of features, such as preventing user styles or userscripts from interfering with error pages, and error pages using this module have a consistent theme.

Parameters

  • string
    Type: string
    The string to load into the webview.
  • content_uri
    Type: string
    The URI to display.

view:reload ()

Reload the current contents of the webview.

view:reload_bypass_cache ()

Reload the current contents of the webview, without using any cached data.

view:stop ()

Stop any current load operation within the within the webview. If there is no such operation, this method does nothing. Otherwise, the load-failed signal will be emitted with "cancelled" as the failure reason.

view:ssl_trusted ()

Determine whether any problems have been found with the certificate associated with the contents of the webview.

If the contents of the webview were not loaded over HTTPS, nil is returned.

The return value is valid after load-status is emitted on the webview with the "committed" status.

Return Values

  • boolean?
    false if any problems have been found, true if no problems were found, and nil if the contents of the webview were not loaded over HTTPS.

view:show_inspector ()

Show the web inspector for the webview.

view:close_inspector ()

Close the web inspector for the webview.

view:allow_certificate ()

Allow a certificate.

Properties

view.inspector

Type: boolean
Read-only
Whether the web inspector is open for the webview.

view.uri

Type: string
Default: "about:blank"
Read-write
The URI of the current web page.

view.hovered_uri

Type: string?
Read-only
The URI of the link the mouse cursor is currently hovering over, or nil if the mouse cursor is not currently hovering over a link.

view.source

Type: any type
Read-only
The source of the current web page.

view.session_state

Type: string
Read-write
The session state of the current web page.

view.stylesheets

Type: table
Read-only
The stylesheets of the webview.

view.history

Type: table
Read-only
The history of the webview.

view.scroll

Type: table
Read-only
The scroll of the webview.

view.favicon

Type: widget
Read-only
The favicon of the webview.

view.certificate

Type: string
Read-only
The certificate of the webview.

view.allow_file_access_from_file_urls

Type: boolean
Default: false
Read-write
Whether file:// access is allowed for file:// URIs.

view.allow_universal_access_from_file_urls

Type: boolean
Default: false
Read-write
Whether Javascript running in the file:// scheme is allowed to access content from any origin.

view.hardware_acceleration_policy

Type: string
Read-write
The policy for using hardware acceleration. Can be one of "on-demand", "always", and "never".

Signals

"scheme-request::*"

Emitted when the webview attempts to load a URI on a custom URI scheme. The signal detail is always present and is equal to the URI scheme.

Example

A signal scheme-request::foo will be emitted on a webview in response to a foo:// load attempt. To display content for this request, return a string with the content to display, as well as (optionally) the content MIME type.

The type of content to display isn't limited to HTML or other textual formats; images and other binary content types are acceptable, as long as the MIME type parameter is returned.

Parameters

  • uri
    Type: string
    The URI that the webview is attempting to load.

Return Values

  • string
    The content to display. Embedded NUL bytes are handled correctly.
  • string
    The MIME type of the content. Default: text/html.

"property::*"

Emitted when the value of a webview property may have been updated. For example, the "property::uri" signal is emitted on a webview widget when its uri property changes.

"button-press"

Emitted when a mouse button was pressed with the cursor inside the webview widget.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held at the time of the event.
  • button
    Type: integer
    The number of the button pressed, beginning from 1; i.e. 1 corresponds to the left mouse button.
  • hit_test
    Type: table
    A table representing the type of element under the cursor at the time of the event.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"button-release"

Emitted when a mouse button was released with the cursor inside the webview widget.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held at the time of the event.
  • button
    Type: integer
    The number of the button pressed, beginning from 1; i.e. 1 corresponds to the left mouse button.
  • hit_test
    Type: table
    A table representing the type of element under the cursor at the time of the event.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"button-double-click"

Emitted when a mouse button was double-clicked with the cursor inside the webview widget.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held at the time of the event.
  • button
    Type: integer
    The number of the button pressed, beginning from 1; i.e. 1 corresponds to the left mouse button.
  • hit_test
    Type: table
    A table representing the type of element under the cursor at the time of the event.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"mouse-enter"

Emitted when the mouse cursor enters the webview widget.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"mouse-leave"

Emitted when the mouse cursor leaves the webview widget.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"populate-popup"

Emitted just before the context menu is shown, usually after a right-click. This signal allows Lua code to intercept and modify the menu before it is shown.

Parameters

  • menu
    Type: table
    A table representing the context menu to be shown.

"web-extension-loaded"

Emitted on a webview widget when its associated web process has finished initialization.

"crashed"

Emitted on a webview widget when its associated web process has crashed. The "web-extension-loaded" signal will be emitted afterwards, once a replacement web process has finished initialization.

"load-status"

Emitted on a webview widget when its load status changes.

Parameters

  • status
    Type: string
    The current load status of the webview. Can be one of "provisional", "redirected", "committed", "finished", and "failed".
  • uri
    Type: string or nil
    If the load status is "failed", this will be the failing URI; otherwise, it will be nil.
  • err
    Type: table or nil
    If the load status is "failed", this will be a table with an error code and a human-readable message; otherwise, it will be nil.

"create-web-view"

Emitted on a webview widget when it requests creation of a new webview widget.

Return Values

  • widget[type=webview]
    The newly created webview widget.

"navigation-request"

Emitted on a webview widget before a navigation request is made, in either the main frame or a sub-frame of the webpage.

Parameters

  • uri
    Type: string
    The URI to which navigation is being requested.
  • reason
    Type: string
    The reason for the navigation request. Can be one of "link-clicked", "form-submitted", "back-forward", "reload", "form-resubmitted", and "other".

Return Values

  • boolean
    Return false to prevent the requested navigation from taking place.

"new-window-decision"

Similar to the "navigation-request" signal, the "new-window-decision" signal is emitted on a webview widget when a request to open a new window is made.

Parameters

  • uri
    Type: string
    The URI that will open in the new window, if the request is allowed.
  • reason
    Type: string
    The reason for the navigation request. Can be one of "link-clicked", "form-submitted", "back-forward", "reload", "form-resubmitted", and "other".

Return Values

  • boolean
    Return false to prevent the requested navigation from taking place.

"mime-type-decision"

Similar to the "navigation-request" signal, the "mime-type-decision" signal is emitted on a webview widget after a response has been received for a request, but before loading begins. This signal is emitted for all sub-page resources, such as images and stylesheets.

Parameters

  • uri
    Type: string
    The URI of the resource for which a response has been received.
  • mime
    Type: string
    The MIME type for the resource indicated by the response.

Return Values

  • boolean
    Return false to prevent the requested navigation from taking place.

"favicon"

Emitted when the favicon for the currently loaded webpage becomes available.

"expose"

Emitted when the webview widget is redrawn.

"key-press"

Emitted when a key is pressed while the webview widget has the input focus.

Parameters

  • modifiers
    Type: table
    An array of strings, one for each modifier key held.
  • key
    Type: string
    The key that was pressed, if printable, or a keysym otherwise.

Return Values

  • boolean
    true if the event has been handled and should not be propagated further.

"permission-request"

Emitted when the webview is requesting user permisison to perform some action.

Parameters

  • type
    Type: string
    The type of permission requested. Can be one of "notification", "geolocation", "install-missing-media-plugins", and "user-media".
  • arg
    Type: any type
    Additional information about the permission request. For "user-media" requests, this is a table with boolean audio and video fields. For "install-missing-media-plugins" requests, this is a string description.

Return Values

  • boolean
    true to grant the permission request, and false to deny it. If no value is returned, a default action is used.

Attribution

Copyright

  • 2010 Mason Larobina