widget:webview - Luakit

# Luakit Documentation / Classes / widget:webview

# 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 (text, case_sensitive, forwards, wrap)

Begin searching the contents of the webview.

This will end any current search, as if `clear_search()` had been called.

#### Parameters

- text
  Type: string
  The text to search for.
- case_sensitive
  Type: boolean
  Whether the search should be case-sensitive.
- forwards
  Type: boolean
  Search direction; `true` for forwards, `false` for backwards.
- wrap
  Type: boolean
  Whether searching should wrap at the beginning and end of the document.

### 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:clear_search ()

Finish searching the contents of the webview. This will cause all highlighted matches within the webview to be un-highlighted.

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

### "link-hover"

Deprecated: use `property::hovered_uri` signal instead

Emitted when the mouse cursor is moved over a link.

#### Parameters

- uri
  Type: string
  The hovered URI.

### "link-unhover"

Deprecated: use `property::hovered_uri` signal instead

Emitted when the mouse cursor was over a link and is moved off.

#### Parameters

- uri
  Type: string
  The just-unhovered URI.

### "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.

### "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