Skip to main content

39.18 Embedded Native Widgets

Emacs is able to display native widgets, such as GTK+ WebKit widgets, in Emacs buffers when it was built with the necessary support libraries and is running on a graphical terminal. To test whether Emacs supports display of embedded widgets, check that the xwidget-internal feature is available (see Named Features).

To display an embedded widget in a buffer, you must first create an xwidget object, and then use that object as the display specifier in a display text or overlay property (see Display Property).

function make-xwidget type title width height arguments \&optional buffer​

This creates and returns an xwidget object. If buffer is omitted or nil, it defaults to the current buffer. If buffer names a buffer that doesn’t exist, it will be created. The type identifies the type of the xwidget component, it can be one of the following:

webkit​

The WebKit component.

The width and height arguments specify the widget size in pixels, and title, a string, specifies its title.

function xwidgetp object​

This function returns t if object is an xwidget, nil otherwise.

function xwidget-plist xwidget​

This function returns the property list of xwidget.

function set-xwidget-plist xwidget plist​

This function replaces the property list of xwidget with a new property list given by plist.

function xwidget-buffer xwidget​

This function returns the buffer of xwidget.

function get-buffer-xwidgets buffer​

This function returns a list of xwidget objects associated with the buffer, which can be specified as a buffer object or a name of an existing buffer, a string. The value is nil if buffer contains no xwidgets.

function xwidget-webkit-goto-uri xwidget uri​

This function browses the specified uri in the given xwidget. The uri is a string that specifies the name of a file or a URL.

function xwidget-webkit-execute-script xwidget script​

This function causes the browser widget specified by xwidget to execute the specified JavaScript script.

function xwidget-webkit-execute-script-rv xwidget script \&optional default​

This function executes the specified script like xwidget-webkit-execute-script does, but it also returns the script’s return value as a string. If script doesn’t return a value, this function returns default, or nil if default was omitted.

function xwidget-webkit-get-title xwidget​

This function returns the title of xwidget as a string.

function xwidget-resize xwidget width height​

This function resizes the specified xwidget to the size widthxheight pixels.

function xwidget-size-request xwidget​

This function returns the desired size of xwidget as a list of the form (width height). The dimensions are in pixels.

function xwidget-info xwidget​

This function returns the attributes of xwidget as a vector of the form [type title width height]. The attributes are usually determined by make-xwidget when the xwidget is created.

function set-xwidget-query-on-exit-flag xwidget flag​

This function allows you to arrange that Emacs will ask the user for confirmation before exiting or before killing a buffer that has xwidget associated with it. If flag is non-nil, Emacs will query the user, otherwise it will not.

function xwidget-query-on-exit-flag xwidget​

This function returns the current setting of xwidgets query-on-exit flag, either t or nil.