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
display text or overlay property (see The
Embedded widgets can send events notifying Lisp code about changes occurring within them. (see Xwidget events).
make-xwidgettype 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:
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.
This function returns
t if object is an xwidget,
This function returns
t if object is an xwidget that
hasn’t been killed, and
This function kills xwidget, by removing it from its buffer and releasing window system resources it holds.
This function returns the property list of xwidget.
set-xwidget-plistxwidget plist ¶
This function replaces the property list of xwidget with a new property list given by plist.
This function returns the buffer of xwidget. If xwidget
has been killed, it returns
set-xwidget-bufferxwidget buffer ¶
This function sets the buffer of xwidget to 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.
xwidget-webkit-goto-urixwidget 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.
xwidget-webkit-execute-scriptxwidget script ¶
This function causes the browser widget specified by xwidget to
xwidget-webkit-execute-script-rvxwidget 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
default was omitted.
This function returns the title of xwidget as a string.
xwidget-resizexwidget width height ¶
This function resizes the specified xwidget to the size widthxheight pixels.
This function returns the desired size of xwidget as a list of
(width height). The dimensions are in
This function returns the attributes of xwidget as a vector of
[type title width height].
The attributes are usually determined by
make-xwidget when the
xwidget is created.
set-xwidget-query-on-exit-flagxwidget 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-
Emacs will query the user, otherwise it will not.
This function returns the current setting of xwidgets
query-on-exit flag, either
xwidget-perform-lispy-eventxwidget 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.
xwidget-webkit-searchquery 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
Display the next search result in xwidget. This function will
signal an error if a search query has not been already started in
wrap-around was non-
was called, then the search will restart from the beginning of the
document when its end is reached.
Display the previous search result in xwidget. This function
signals an error if a search query has not been already started in
wrap-around was non-
was called, then the search will restart from the end of the
document when its beginning is reached.
Finish a search operation started with
xwidget. If there is no query currently ongoing, this function
signals an error.
xwidget-webkit-load-htmlxwidget 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.
xwidget-webkit-goto-historyxwidget 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.
xwidget-webkit-back-forward-listxwidget &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
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
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
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.
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.
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.