master 7269bdd 21/35: Improve detail of load-changed xwidget events

[Lars Ingebrigtsen]

branch: master
commit 7269bdd5998a9c524b40ae7406013194b95cb6ed
Author: Po Lu <luangruo@yahoo.com>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Improve detail of load-changed xwidget events
    
    * src/xwidget.c (webkit_view_load_changed_cb): Improve event detail.
    * etc/NEWS: Document changes.
    * doc/lispref/commands.texi: Document Xwidget events.
    * doc/lispref/display.texi (Xwidgets): Add reference to Xwidget events.
---
 doc/lispref/commands.texi | 62 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/lispref/display.texi  |  3 +++
 etc/NEWS                  |  8 ++++++
 src/xwidget.c             | 23 ++++++++++++------
 4 files changed, 88 insertions(+), 8 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index b38a83b..ca59475 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1176,6 +1176,7 @@ intended by Lisp code to be used as an event.
 * Repeat Events::               Double and triple click (or drag, or down).
 * Motion Events::               Just moving the mouse, not pushing a button.
 * Focus Events::                Moving the mouse between frames.
+* Xwidget Events::              Events generated by xwidgets.
 * Misc Events::                 Other events the system can generate.
 * Event Examples::              Examples of the lists for mouse events.
 * Classifying Events::          Finding the modifier keys in an event symbol.
@@ -1871,6 +1872,67 @@ sequence---that is, after a prefix key---then Emacs 
reorders the events
 so that the focus event comes either before or after the multi-event key
 sequence, and not within it.
 
+@node Xwidget Events
+@subsection Xwidget events
+
+Xwidgets (@pxref{Xwidgets}) can send events to update Lisp programs on
+their status.  These events are dubbed @code{xwidget-events}, and
+contain various data describing the nature of the change.
+
+@table @code
+@cindex @code{xwidget-event} event
+@item (xwidget-event @var{kind} @var{xwidget} @var{arg})
+This event is sent whenever some kind of update occurs in
+@var{xwidget}.  There are several types of updates, which are
+identified by @var{kind}.
+
+@cindex @code{load-changed} xwidget events
+An xwidget event with @var{kind} set to @code{load-changed} indicates
+that the @var{xwidget} has reached a particular point of the
+page-loading process.  When these events are sent, @var{arg} will
+contain a string that futher describes the status of the widget.
+
+@cindex @samp{"load-finished"} in xwidgets
+When @var{arg} is @samp{"load-finished"}, it means the xwidget has
+finished processing whatever page-loading operation that it was
+previously performing.
+
+@cindex @samp{"load-started"} in xwidgets
+Otherwise, if it is @samp{"load-started"}, then the widget has begun a
+page-loading operation.
+
+@cindex @samp{"load-redirected"} in xwidgets
+If @var{arg} is @samp{"load-redirected"}, it means the widget has
+encountered and followed a redirect during the page-loading operation.
+
+@cindex @samp{"load-committed"} in xwidgets
+If @var{arg} is @samp{"load-committed"}, then the widget has committed
+to a given URL during the page-loading operation.  This means that the
+URL is the final URL that will be rendered by @var{xwidget} during the
+current page-loading operation.
+
+@cindex @code{download-callback} xwidget events
+An event with @var{kind} set to @code{download-callback} indicates
+that a download of some kind has been completed.
+
+In these events, there can be arguments after @var{arg}, which itself
+indicates the URL that the download file was retrieved from: the first
+argument after @var{arg} indicates the MIME type of the download, as a
+string, while the second such argument contains the full file path to
+the downloaded file.
+
+@cindex @code{download-started} xwidget events
+An event with @var{kind} set to @code{download-started} indicates that
+a download has been started.  In these events, @var{arg} contains the
+URL of the file that is currently being downloaded.
+
+@cindex @code{javascript-callback} xwidget events
+An event with @var{kind} set to @code{javascript-callback} contains
+JavaScript callback data.  These events are used internally by
+@code{xwidget-webkit-execute-script}.
+
+@end table
+
 @node Misc Events
 @subsection Miscellaneous System Events
 
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index eab2c56..2fb89d7 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6784,6 +6784,9 @@ xwidget object, and then use that object as the display 
specifier
 in a @code{display} text or overlay property (@pxref{Display
 Property}).
 
+  Embedded widgets can send events notifying Lisp code about changes
+occurring within them.  (@pxref{Xwidget Events}).
+
 @defun make-xwidget type title width height arguments &optional buffer
 This creates and returns an xwidget object.  If
 @var{buffer} is omitted or @code{nil}, it defaults to the current
diff --git a/etc/NEWS b/etc/NEWS
index a64312f..9a660ed 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -740,6 +740,14 @@ what the widget will actually receive.
 
 On GTK+, only key and function key events are implemented.
 
++++
+** `load-changed' xwidget events are now more detailed.
+In particular, they can now have different arguments based on the
+state of the WebKit widget.  `load-finished' is sent when a load has
+completed, `load-started' when a load first starts, `load-redirected'
+after a redirect, and `load-committed' when the WebKit widget first
+commits to the load.
+
 
 * Changes in Emacs 29.1 on Non-Free Operating Systems
 
diff --git a/src/xwidget.c b/src/xwidget.c
index 49645b8..5f0dd26 100644
--- a/src/xwidget.c
+++ b/src/xwidget.c
@@ -868,17 +868,24 @@ webkit_view_load_changed_cb (WebKitWebView *webkitwebview,
                              WebKitLoadEvent load_event,
                              gpointer data)
 {
-  switch (load_event) {
-  case WEBKIT_LOAD_FINISHED:
+  struct xwidget *xw = g_object_get_data (G_OBJECT (webkitwebview),
+                                         XG_XWIDGET);
+
+  switch (load_event)
     {
-      struct xwidget *xw = g_object_get_data (G_OBJECT (webkitwebview),
-                                              XG_XWIDGET);
-      store_xwidget_event_string (xw, "load-changed", "");
+    case WEBKIT_LOAD_FINISHED:
+      store_xwidget_event_string (xw, "load-changed", "load-finished");
+      break;
+    case WEBKIT_LOAD_STARTED:
+      store_xwidget_event_string (xw, "load-changed", "load-started");
+      break;
+    case WEBKIT_LOAD_REDIRECTED:
+      store_xwidget_event_string (xw, "load-changed", "load-redirected");
+      break;
+    case WEBKIT_LOAD_COMMITTED:
+      store_xwidget_event_string (xw, "load-changed", "load-committed");
       break;
     }
-  default:
-    break;
-  }
 }
 
 /* Recursively convert a JavaScript value to a Lisp value. */