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

@@ -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

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

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*")))