---

41.19 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 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 The display Property).

Embedded widgets can send events notifying Lisp code about changes occurring within them. (see Xwidget events).

Function: make-xwidget type title width height arguments &optional buffer related ¶

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. related is used internally by the WebKit widget, and specifies another WebKit widget that the newly created widget should share settings and subprocesses with.

The xwidget that is returned will be killed alongside its buffer (see Killing Buffers). You can also kill it using kill-xwidget. Once it is killed, the xwidget may continue to exist as a Lisp object and act as a display property until all references to it are gone, but most actions that can be performed on live xwidgets will no longer be available.

Function: xwidgetp object ¶

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

Function: xwidget-live-p object ¶

This function returns t if object is an xwidget that hasn’t been killed, and nil otherwise.

Function: kill-xwidget xwidget ¶

This function kills xwidget, by removing it from its buffer and releasing window system resources it holds.

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. If xwidget has been killed, it returns nil.

Function: set-xwidget-buffer xwidget buffer ¶

This function sets the buffer of xwidget to buffer.

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.

Function: xwidget-perform-lispy-event xwidget event frame ¶

Send an input event event to xwidget. The precise action performed is platform-specific. See Input Events.

You can optionally pass the frame on which the event was generated via frame. On X11, modifier keys in key events will not be considered if frame is nil, and the selected frame is not an X-Windows frame.

On GTK, only keyboard and function key events are supported. Mouse, motion, and click events are dispatched to the xwidget without going through Lisp code, and as such shouldn’t require this function to be called.

Function: xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around ¶

Start an incremental search on the WebKit widget xwidget with the string query as the query. case-insensitive denotes whether or not the search is case-insensitive, backwards determines if the search is performed backwards towards the start of the document, and wrap-around determines whether or not the search terminates at the end of the document.

If the function is called while a search query is already present, then the query specified here will replace the existing query.

To stop a search query, use xwidget-webkit-finish-search.

Function: xwidget-webkit-next-result xwidget ¶

Display the next search result in xwidget. This function will signal an error if a search query has not been already started in xwidget through xwidget-webkit-search.

If wrap-around was non-nil when xwidget-webkit-search was called, then the search will restart from the beginning of the document when its end is reached.

Function: xwidget-webkit-previous-result xwidget ¶

Display the previous search result in xwidget. This function signals an error if a search query has not been already started in xwidget through xwidget-webkit-search.

If wrap-around was non-nil when xwidget-webkit-search was called, then the search will restart from the end of the document when its beginning is reached.

Function: xwidget-webkit-finish-search xwidget ¶

Finish a search operation started with xwidget-webkit-search in xwidget. If there is no query currently ongoing, this function signals an error.

Function: xwidget-webkit-load-html xwidget text &optional base-uri ¶

Load text, a string, into xwidget, which should be a WebKit xwidget. Any HTML markup in text will be processed by xwidget while rendering the text.

Optional argument base-uri, which should be a string, specifies the absolute location of the web resources referenced by text, to be used for resolving relative links in text.

Function: xwidget-webkit-goto-history xwidget rel-pos ¶

Make xwidget, a WebKit widget, load the rel-posth element in its navigation history.

If rel-pos is zero, the current page will be reloaded instead.

Function: xwidget-webkit-back-forward-list xwidget &optional limit ¶

Return the navigation history of xwidget, up to limit items in each direction. If not specified, limit defaults to 50.

The returned value is a list of the form (back here forward), where here is the current navigation item, while back is a list of items containing the items recorded by WebKit before the current navigation item, and forward is a list of items recorded after the current navigation item. back, here and forward can all be nil.

When here is nil, it means that no items have been recorded yet; if back or forward are nil, it means that there is no history recorded before or after the current item respectively.

Navigation items are themselves lists of the form (idx title uri). In these lists, idx is an index that can be passed to xwidget-webkit-goto-history, title is the human-readable title of the item, and uri is the URI of the item. The user should normally have no reason to load uri manually to reach a specific history item. Instead, idx should be passed as an index to xwidget-webkit-goto-history.

Function: xwidget-webkit-estimated-load-progress xwidget ¶

Return an estimate of how much data is remaining to be transferred before the page displayed by the WebKit widget xwidget is fully loaded.

The value returned is a float ranging between 0.0 and 1.0.

Function: xwidget-webkit-set-cookie-storage-file xwidget file ¶

Make the WebKit widget xwidget store cookies in file.

file must be an absolute file name. The new setting will also affect any xwidget that was created with xwidget as the related argument to make-xwidget, and widgets related to those as well.

If this function is not called at least once on xwidget or a related widget, xwidget will not store cookies on disk at all.

Function: xwidget-webkit-stop-loading xwidget ¶

Terminate any data transfer still in progress in the WebKit widget xwidget as part of a page-loading operation. If a page is not being loaded, this function does nothing.