Make xwidget-events special and document xwidget callbacks

Users have always been supposed to use callbacks for handling
xwidget events, but for some reason this has not been
documented until now.

* doc/lispref/commands.texi (Xwidget Events): Document xwidget
callbacks and the special status of `xwidget-event's.

* doc/lispref/display.texi (Xwidgets): Add xwidget property
list functions to the concept index.

* lisp/xwidget.el: Make xwidget events special.

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1509c200e0dfb9045d0792795503f9442afbef4b..cc9c41623dc7da58a98552c60485d48ee1d6c577 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -1886,6 +1886,15 @@ This event is sent whenever some kind of update occurs in
 @var{xwidget}.  There are several types of updates, identified by
 their @var{kind}.
 
+@cindex xwidget callbacks
+It is a special event (@pxref{Special Events}), which should be
+handled by adding a callback to an xwidget that is called whenever an
+xwidget event for @var{xwidget} is received.
+
+You can add a callback by setting the @code{callback} of an xwidget's
+property list, which should be a function that accepts @var{xwidget}
+and @var{kind} as arguments.
+
 @table @code
 @cindex @code{load-changed} xwidget event
 @item load-changed

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 12257fda54b68e64dda26def6708809788506011..08426032e09dd42cba3cffab9595d55c96d03edb 100644 (file)
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6828,6 +6828,7 @@ This function kills @var{xwidget}, by removing it from its buffer and
 releasing window system resources it holds.
 @end defun
 
+@cindex xwidget property list
 @defun xwidget-plist xwidget
 This function returns the property list of @var{xwidget}.
 @end defun

diff --git a/lisp/xwidget.el b/lisp/xwidget.el
index 91580efa49a11b6401dba4138e944eeeafd905b9..5b465dad3d5302f2172c76bb5d084f0b26d32a80 100644 (file)
--- a/lisp/xwidget.el
+++ b/lisp/xwidget.el
@@ -372,10 +372,13 @@ If N is omitted or nil, scroll backwards by one char."
    (xwidget-webkit-current-session)
    "window.scrollTo(pageXOffset, window.document.body.scrollHeight);"))
 
-;; The xwidget event needs to go into a higher level handler
-;; since the xwidget can generate an event even if it's offscreen.
-;; TODO this needs to use callbacks and consider different xwidget event types.
-(define-key (current-global-map) [xwidget-event] #'xwidget-event-handler)
+;; The xwidget event needs to go in the special map.  To receive
+;; xwidget events, you should place a callback in the property list of
+;; the xwidget, instead of handling these events manually.
+;;
+;; See `xwidget-webkit-new-session' for an example of how to do this.
+(define-key special-event-map [xwidget-event] #'xwidget-event-handler)
+
 (defun xwidget-log (&rest msg)
   "Log MSG to a buffer."
   (let ((buf (get-buffer-create " *xwidget-log*")))