[Emacs-diffs] emacs-25 ef760b8: Document xwidget commands and functions

[Eli Zaretskii]

branch: emacs-25
commit ef760b899ad89f941f552ed2d3ac9e45156f3e3c
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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 ac8988b..dc99d49 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 2d8137e..b5a2150 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}.
 
address@hidden Embedded WebKit Widgets
address@hidden Embedded WebKit Widgets
address@hidden xwidget
address@hidden webkit widgets
address@hidden embedded widgets
+
address@hidden xwidget-webkit-browse-url
address@hidden xwidget-webkit-mode
address@hidden 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 @address@hidden 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 eaba03d..aa98ed4 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
 
address@hidden Xwidgets
address@hidden Embedded Native Widgets
address@hidden xwidget
address@hidden embedded widgets
address@hidden 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
address@hidden 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}).
+
address@hidden 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
address@hidden 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:
+
address@hidden @code
address@hidden webkit-osr
+The WebKit OSR (@dfn{on-stack replacement}) component.
address@hidden table
+
+The @var{width} and @var{height} arguments specify the widget size in
+pixels, and @var{title}, a string, specifies its title.
address@hidden defun
+
address@hidden xwidgetp object
+This function returns @code{t} if @var{object} is an xwidget,
address@hidden otherwise.
address@hidden defun
+
address@hidden xwidget-plist xwidget
+This function returns the property list of @var{xwidget}.
address@hidden defun
+
address@hidden set-xwidget-plist xwidget plist
+This function replaces the property list of @var{xwidget} with a new
+property list given by @var{plist}.
address@hidden defun
+
address@hidden xwidget-buffer xwidget
+This function returns the buffer of @var{xwidget}.
address@hidden defun
+
address@hidden get-buffer-xwidgets buffer
+This function returns a list of xwidget objects associated with the
address@hidden, 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.
address@hidden defun
+
address@hidden xwidget-webkit-goto-uri xwidget uri
+This function browses the specified @var{uri} in the given
address@hidden  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?
address@hidden defun
+
address@hidden xwidget-webkit-execute-script xwidget script
+This function causes the browser widget specified by @var{xwidget} to
+execute the specified JavaScript @code{script}.
address@hidden defun
+
address@hidden xwidget-webkit-execute-script-rv xwidget script &optional default
+This function executes the specified @var{script} like
address@hidden 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
address@hidden was omitted.
address@hidden defun
+
address@hidden xwidget-webkit-get-title xwidget
+This function returns the title of @var{xwidget} as a string.
address@hidden defun
+
address@hidden xwidget-resize xwidget width height
+This function resizes the specified @var{xwidget} to the size
address@hidden@var{height} pixels.
address@hidden defun
+
address@hidden 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.
address@hidden defun
+
address@hidden xwidget-info xwidget
+This function returns the attributes of @var{xwidget} as a vector of
+the form @address@hidden @var{title} @var{width} @var{height}]}.
+The attributes are usually determined by @code{make-xwidget} when the
+xwidget is created.
address@hidden defun
+
address@hidden 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
address@hidden associated with it.  If @var{flag} is address@hidden,
+Emacs will query the user, otherwise it will not.
address@hidden defun
+
address@hidden 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}.
address@hidden defun
+
 @node Buttons
 @section Buttons
 @cindex buttons in buffers
diff --git a/etc/NEWS b/etc/NEWS
index 09bced4..af2dee9 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',