From 88458f7354e904a50ed1389869266437ba084533 Mon Sep 17 00:00:00 2001
From: Po Lu <luangruo@yahoo.com>
Date: Sat, 20 Nov 2021 14:57:22 +0800
Subject: [PATCH] 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.
---
 doc/lispref/commands.texi |  9 +++++++++
 doc/lispref/display.texi  |  1 +
 lisp/xwidget.el           | 11 +++++++----
 3 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1509c200e0d..cc9c41623dc 100644
--- 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 12257fda54b..08426032e09 100644
--- 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 91580efa49a..5b465dad3d5 100644
--- 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*")))
-- 
2.39.5