From 7269bdd5998a9c524b40ae7406013194b95cb6ed Mon Sep 17 00:00:00 2001 From: Po Lu Date: Sat, 6 Nov 2021 09:45:06 +0800 Subject: [PATCH] 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 b38a83b4fe0..ca594759f84 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 eab2c56dffa..2fb89d76b41 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 a64312f7fa3..9a660edee8d 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 49645b8b6fd..5f0dd2644a1 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. */ -- 2.39.2