From ef760b899ad89f941f552ed2d3ac9e45156f3e3c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 30 Jan 2016 10:04:13 +0200 Subject: Document xwidget commands and functions * doc/lispref/display.texi (Xwidgets): New section, describes some of the xwidget primitives. * doc/lispref/display.texi (Display): Update the chapter menu. * doc/emacs/misc.texi (Embedded WebKit Widgets): New section. * doc/emacs/emacs.texi (Top): Update the master menu to include the xwidget node. --- doc/emacs/emacs.texi | 1 + doc/emacs/misc.texi | 22 +++++++++ doc/lispref/display.texi | 113 +++++++++++++++++++++++++++++++++++++++++++++++ etc/NEWS | 12 ++--- 4 files changed, 143 insertions(+), 5 deletions(-) diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index ac8988b4020..dc99d493241 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -192,6 +192,7 @@ Advanced Features * Network Security:: Managing the network security. * Document View:: Viewing PDF, PS and DVI files. * EWW:: A web browser in Emacs. +* Embedded WebKit Widgets:: Embedding browser widgets in Emacs buffers. * Shell:: Executing shell commands from Emacs. * Emacs Server:: Using Emacs as an editing server. * Printing:: Printing hardcopies of buffers or regions. diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 2d8137e832f..b5a21500fcb 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -604,6 +604,28 @@ using the command @kbd{M-x eww-open-file}. You can use EWW as the web browser for @code{browse-url}, @pxref{Browse-URL}. For full details, @pxref{Top, EWW,, eww, The Emacs Web Wowser Manual}. +@node Embedded WebKit Widgets +@section Embedded WebKit Widgets +@cindex xwidget +@cindex webkit widgets +@cindex embedded widgets + +@findex xwidget-webkit-browse-url +@findex xwidget-webkit-mode +@cindex Xwidget-WebKit mode + If Emacs was compiled with the appropriate support packages, it is +able to show browser widgets in its buffers. The command @kbd{M-x +xwidget-webkit-browse-url} asks for a URL to display in the browser +widget. The URL normally defaults to the URL at or before point, but +if there is an active region (@pxref{Mark}), the default URL comes +from the region instead, after removing any whitespace from it. The +command then creates a new buffer with the embedded browser showing +the specified URL. The buffer is put in the Xwidget-WebKit mode +(similar to Image mode, @pxref{File Conveniences}), which provides +one-key commands for scrolling the widget, changing its size, and +reloading it. Type @w{@kbd{C-h b}} in that buffer to see the key +bindings. + @node Shell @section Running Shell Commands from Emacs @cindex subshell diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index eaba03d5739..aa98ed40ee5 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -27,6 +27,7 @@ that Emacs presents to the user. * Window Dividers:: Separating windows visually. * Display Property:: Enabling special display features. * Images:: Displaying images in Emacs buffers. +* Xwidgets:: Displaying native widgets in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. * Blinking:: How Emacs shows the matching open parenthesis. @@ -5612,6 +5613,118 @@ except when you explicitly clear it. This mode can be useful for debugging. @end defvar +@node Xwidgets +@section Embedded Native Widgets +@cindex xwidget +@cindex embedded widgets +@cindex webkit browser widget + + 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 +@code{xwidget-internal} feature is available (@pxref{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 @code{display} text or overlay property (@pxref{Display +Property}). + +@defun make-xwidget beg end type title width height arguments &optional buffer +This creates an xwidget object between @var{beg} and @var{end}, buffer +positions in @var{buffer}, and returns the new object. If +@var{buffer} is omitted or @code{nil}, it defaults to the current +buffer. If @var{buffer} names a buffer that doesn't exist, it will be +created. The @var{type} identifies the type of the xwidget component, +it can be one of the following: + +@table @code +@item webkit-osr +The WebKit OSR (@dfn{on-stack replacement}) component. +@end table + +The @var{width} and @var{height} arguments specify the widget size in +pixels, and @var{title}, a string, specifies its title. +@end defun + +@defun xwidgetp object +This function returns @code{t} if @var{object} is an xwidget, +@code{nil} otherwise. +@end defun + +@defun xwidget-plist xwidget +This function returns the property list of @var{xwidget}. +@end defun + +@defun set-xwidget-plist xwidget plist +This function replaces the property list of @var{xwidget} with a new +property list given by @var{plist}. +@end defun + +@defun xwidget-buffer xwidget +This function returns the buffer of @var{xwidget}. +@end defun + +@defun get-buffer-xwidgets buffer +This function returns a list of xwidget objects associated with the +@var{buffer}, which can be specified as a buffer object or a name of +an existing buffer, a string. The value is @code{nil} if @var{buffer} +contains no xwidgets. +@end defun + +@defun xwidget-webkit-goto-uri xwidget uri +This function browses the specified @var{uri} in the given +@var{xwidget}. The @var{uri} is a string that specifies the name of a +file or a URL. @c FIXME: What else can a URI specify in this context? +@end defun + +@defun xwidget-webkit-execute-script xwidget script +This function causes the browser widget specified by @var{xwidget} to +execute the specified JavaScript @code{script}. +@end defun + +@defun xwidget-webkit-execute-script-rv xwidget script &optional default +This function executes the specified @var{script} like +@code{xwidget-webkit-execute-script} does, but it also returns the +script's return value as a string. If @var{script} doesn't return a +value, this function returns @var{default}, or @code{nil} if +@var{default} was omitted. +@end defun + +@defun xwidget-webkit-get-title xwidget +This function returns the title of @var{xwidget} as a string. +@end defun + +@defun xwidget-resize xwidget width height +This function resizes the specified @var{xwidget} to the size +@var{width}x@var{height} pixels. +@end defun + +@defun xwidget-size-request xwidget +This function returns the desired size of @var{xwidget} as a list of +the form @code{(@var{width} @var{height})}. The dimensions are in +pixels. +@end defun + +@defun xwidget-info xwidget +This function returns the attributes of @var{xwidget} as a vector of +the form @code{[@var{type} @var{title} @var{width} @var{height}]}. +The attributes are usually determined by @code{make-xwidget} when the +xwidget is created. +@end defun + +@defun 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 +@var{xwidget} associated with it. If @var{flag} is non-@code{nil}, +Emacs will query the user, otherwise it will not. +@end defun + +@defun xwidget-query-on-exit-flag xwidget +This function returns the current setting of @var{xwidget}s +query-on-exit flag, either @code{t} or @code{nil}. +@end defun + @node Buttons @section Buttons @cindex buttons in buffers diff --git a/etc/NEWS b/etc/NEWS index 09bced4b000..af2dee931f3 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -126,13 +126,15 @@ and can contain escape sequences for command keys, quotes, and the like. * Changes in Emacs 25.1 ++++ ** Xwidgets: a new feature for embedding native widgets inside Emacs buffers. -If you have gtk3 and webkitgtk3 installed, you can access the -embedded webkit browser with `M-x xwidget-webkit-browse-url'. This -opens a new buffer with the embedded browser. The buffer will -have a new mode, `xwidget-webkit-mode' (similar to `image-mode'), -which supports the webkit widget. +If you have gtk3 and webkitgtk3 installed, and Emacs was built with +xwidget support, you can access the embedded webkit browser with `M-x +xwidget-webkit-browse-url'. This opens a new buffer with the embedded +browser. The buffer will have a new mode, `xwidget-webkit-mode' +(similar to `image-mode'), which supports the webkit widget. ++++ *** New functions for xwidget-webkit mode `xwidget-webkit-insert-string', `xwidget-webkit-adjust-size-dispatch', `xwidget-webkit-back', `xwidget-webkit-browse-url', `xwidget-webkit-reload', -- cgit v1.2.1