---

22.7.11 Xwidget events

Xwidgets (see Embedded Native Widgets) can send events to update Lisp programs on their status. These events are dubbed xwidget-events, and contain various data describing the nature of the change.

(xwidget-event kind xwidget arg)

This event is sent whenever some kind of update occurs in xwidget. There are several types of updates, identified by their kind.

It is a special event (see Special Events), which should be handled by adding a callback to an xwidget that is called whenever an xwidget event for xwidget is received.

You can add a callback by setting the callback of an xwidget’s property list, which should be a function that accepts xwidget and kind as arguments.

load-changed

This xwidget event indicates that the xwidget has reached a particular point of the page-loading process. When these events are sent, arg will contain a string that further describes the status of the widget:

‘load-started’

This means the widget has begun a page-loading operation.

‘load-finished’

This means the xwidget has finished processing whatever page-loading operation that it was previously performing.

‘load-redirected’

This means the xwidget has encountered and followed a redirect during the page-loading operation.

‘load-committed’

This means the xwidget has committed to a given URL during the page-loading operation, i.e. the URL is the final URL that will be rendered by xwidget during the current page-loading operation.

download-callback

This event indicates that a download of some kind has been completed.

In the above events, there can be arguments after arg, which itself indicates the URL from which the download file was retrieved: the first argument after arg indicates the MIME type of the download, as a string, while the second argument contains the full file name of the downloaded file.

download-started

This event indicates that a download has been started. In these events, arg contains the URL of the file that is currently being downloaded.

javascript-callback

This event contains JavaScript callback data. These events are used internally by xwidget-webkit-execute-script.

(xwidget-display-event xwidget source)

This event is sent whenever an xwidget requests that another xwidget be displayed. xwidget is the xwidget that should be displayed, and source is the xwidget that asked to display xwidget.

It is also a special event which should be handled through callbacks. You can add such a callback by setting the display-callback of source’s property list, which should be a function that accepts xwidget and source as arguments.

xwidget’s buffer will be set to a temporary buffer. When displaying the widget, care should be taken to replace the buffer with the buffer in which the xwidget will be displayed, using set-xwidget-buffer (see Embedded Native Widgets).