Merge branch 'gather-dbus-marshalers' into 'main'

Document changes to the XML interfaces; integrate XML docs into the devel-docs

See merge request GNOME/at-spi2-core!120

21 files changed, 182 insertions, 84 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a0f0a917..e959de65 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -56,8 +56,8 @@ opensuse-x86_64:
     - meson install -C _build
     - mkdir /tmp/test+dir+with+funny+chars
     - export XDG_RUNTIME_DIR=/tmp/test+dir+with+funny+chars # See https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/48
-    - dbus-run-session -- ci/run-registryd-tests.sh
-    - dbus-run-session -- ci/run-tests.sh
+    - xvfb-run --auto-servernum dbus-run-session -- ci/run-registryd-tests.sh
+    - xvfb-run --auto-servernum dbus-run-session -- ci/run-tests.sh
   artifacts:
     reports:
       junit:
@@ -127,7 +127,7 @@ asan-build:
     - CC=clang meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build .
     - meson compile -C _build
     - meson install -C _build
-    - dbus-run-session -- ci/run-tests.sh
+    - xvfb-run --auto-servernum dbus-run-session -- ci/run-tests.sh
   artifacts:
     name: "at-spi2-core-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
     when: always
@@ -152,8 +152,8 @@ coverage:
     - meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build .
     - meson compile -C _build
     - meson install -C _build
-    - dbus-run-session -- ci/run-registryd-tests.sh
-    - dbus-run-session -- ci/run-tests.sh
+    - xvfb-run --auto-servernum dbus-run-session -- ci/run-registryd-tests.sh
+    - xvfb-run --auto-servernum dbus-run-session -- ci/run-tests.sh
     - mkdir -p public
     - grcov _build --source-dir ./ --prefix-dir ../ --output-type cobertura --branch --ignore-not-existing -o coverage.xml
     - grcov _build --source-dir ./ --prefix-dir ../ --output-type html --branch --ignore-not-existing -o public/coverage
@@ -184,31 +184,20 @@ reference:
     MESON_EXTRA_FLAGS: "--buildtype=release -Ddocs=true"
   script:
     - meson setup ${MESON_EXTRA_FLAGS} --prefix /usr _build .
-    - ninja -C _build doc/atk doc/libatspi
+    - ninja -C _build doc/atk doc/libatspi devel-docs/devel-docs
     - mkdir _reference
     - mv _build/doc/libatspi _reference/libatspi
     - mv _build/doc/atk _reference/atk
+    - mv _build/devel-docs/devel-docs  _reference/devel-docs
   artifacts:
     paths:
       - _reference
-
-devel-docs:
-  stage: docs
-  extends:
-  extends:
-    - '.container.opensuse@x86_64'
-    - '.fdo.distribution-image@opensuse'
-  needs: ['opensuse-container@x86_64']
-  script:
-    - bash -x ./ci/gen-devel-docs.sh
-  artifacts:
-    paths:
-      - public
+      - "_build/meson-logs"
 
 # Publish the test coverage report
 pages:
   stage: deploy
-  needs: [ coverage, reference, devel-docs ]
+  needs: [ coverage, reference ]
   script:
     - mv _reference/* public/
   artifacts:
diff --git a/atk-adaptor/bridge.c b/atk-adaptor/bridge.c
index e5b6399d..a2b1de83 100644
--- a/atk-adaptor/bridge.c
+++ b/atk-adaptor/bridge.c
@@ -869,8 +869,6 @@ signal_filter (DBusConnection *bus, DBusMessage *message, void *user_data)
       result = DBUS_HANDLER_RESULT_HANDLED;
       if (!strcmp (member, "KeystrokeListenerRegistered"))
         handle_device_listener_registered (bus, message, user_data);
-      else if (!strcmp (member, "DeviceListenerRegistered"))
-        handle_device_listener_registered (bus, message, user_data);
       else
         result = DBUS_HANDLER_RESULT_NOT_YET_HANDLED;
     }
diff --git a/atspi/atspi-types.h b/atspi/atspi-types.h
index b6c28b49..cb762616 100644
--- a/atspi/atspi-types.h
+++ b/atspi/atspi-types.h
@@ -145,7 +145,7 @@ typedef struct _AtspiKeySet
  * which means in some cases they may already have been delivered to the
  * application before the AT client receives the notification.
  * @ATSPI_KEYLISTENER_SYNCHRONOUS: Events are delivered synchronously, before the
- * currently focussed application sees them.
+ * currently focused application sees them.
  * @ATSPI_KEYLISTENER_CANCONSUME: Events may be consumed by the AT client.  Presumes and
  * requires #ATSPI_KEYLISTENER_SYNCHRONOUS, incompatible with #ATSPI_KEYLISTENER_NOSYNC.
  * @ATSPI_KEYLISTENER_ALL_WINDOWS: Events are received not from the application toolkit layer, but
diff --git a/ci/container_builds.yml b/ci/container_builds.yml
index e8050afb..564e614f 100644
--- a/ci/container_builds.yml
+++ b/ci/container_builds.yml
@@ -13,7 +13,7 @@ include:
 variables:
   # When branching change the suffix to avoid conflicts with images
   # from the main branch
-  BASE_TAG: "2022-09-27.0-main"
+  BASE_TAG: "2022-12-09.1-main"
   RUST_STABLE: "1.64.0"
 
 .container.opensuse@x86_64:
@@ -51,6 +51,9 @@ variables:
       python310-python-dbusmock
       tar
       wget
+      which
+      xorg-x11-devel
+      xvfb-run
     FDO_DISTRIBUTION_EXEC: >-
       bash ci/install-rust.sh ${RUST_STABLE} x86_64-unknown-linux-gnu &&
       pip3 install gi-docgen sphinx sphinx_rtd_theme
diff --git a/ci/gen-devel-docs.sh b/ci/gen-devel-docs.sh
deleted file mode 100644
index dd2b011a..00000000
--- a/ci/gen-devel-docs.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/sh
-
-set -eu
-
-mkdir -p public/devel-docs
-sphinx-build devel-docs public/devel-docs
-
diff --git a/ci/run-registryd-tests.sh b/ci/run-registryd-tests.sh
index 863041c4..8d577a6c 100755
--- a/ci/run-registryd-tests.sh
+++ b/ci/run-registryd-tests.sh
@@ -5,7 +5,8 @@ set -eu
 echo "About to run the tests.  First we'll launch a gnome-session DBus mock."
 
 python3 -m dbusmock --session org.gnome.SessionManager /org/gnome/SessionManager org.gnome.SessionManager &
-sleep 1
+
+gdbus wait --session --timeout 10 org.gnome.SessionManager
 
 gdbus call --session \
       --dest org.gnome.SessionManager \
diff --git a/ci/run-tests.sh b/ci/run-tests.sh
index 7dcbb7df..9676e749 100755
--- a/ci/run-tests.sh
+++ b/ci/run-tests.sh
@@ -5,7 +5,8 @@ set -eu
 echo "About to run the tests.  First we'll launch a gnome-session DBus mock."
 
 python3 -m dbusmock --session org.gnome.SessionManager /org/gnome/SessionManager org.gnome.SessionManager &
-sleep 1
+
+gdbus wait --session --timeout 10 org.gnome.SessionManager
 
 gdbus call --session \
       --dest org.gnome.SessionManager \
diff --git a/devel-docs/gitlab-ci.rst b/devel-docs/gitlab-ci.rst
index 63fac032..abde2be3 100644
--- a/devel-docs/gitlab-ci.rst
+++ b/devel-docs/gitlab-ci.rst
@@ -220,6 +220,7 @@ Note that **clang-format likes to re-order includes alphabetically**
 within chunks separated by blank lines:
 
 .. code:: c
+
    #include <dbus/dbus.h>
    
    #include "de-marshaller.h"
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 61f9809e..8e34027b 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -7,6 +7,7 @@ Development guide for the accessibility infrastructure
    gitlab-ci
    roadmap
    toolkits
+   xml-changes
    :maxdepth: 1
    :caption: Contents:
 
@@ -24,6 +25,7 @@ General documentation
 
 - :doc:`roadmap`
 - :doc:`toolkits`
+- :doc:`xml-changes`
 
 Refactoring and cleanup
 -----------------------
diff --git a/devel-docs/meson.build b/devel-docs/meson.build
new file mode 100644
index 00000000..d8978fcc
--- /dev/null
+++ b/devel-docs/meson.build
@@ -0,0 +1,42 @@
+gdbus_codegen = find_program('gdbus-codegen',
+                             native: true,
+                             required: get_option('docs'))
+
+sphinx_build = find_program('sphinx-build',
+                            native: true,
+                            required: get_option('docs'))
+
+interfaces_rst_sources = []
+interfaces_xml = []
+
+foreach i: introspection_sources
+  # /foo/bar/baz.xml -> doc-baz.rst
+  doc_name = 'doc-' + fs.replace_suffix(fs.name(i), '.rst')
+  interfaces_rst_sources += doc_name
+
+  interfaces_xml += join_paths(meson.project_source_root(), 'xml', i)
+endforeach
+
+interfaces_rst = custom_target(
+  'interfaces_rst',
+  input: interfaces_xml,
+  output: interfaces_rst_sources,
+  command: [ gdbus_codegen, '--generate-rst', 'doc', '@INPUT@']
+)
+
+docs_sources = [
+  'atk-deprecations.rst',
+  'de-controller.rst',
+  'gitlab-ci.rst',
+  'index.rst',
+  'roadmap.rst',
+  'toolkits.rst',
+  'xml-changes.rst',
+]
+
+custom_target(
+  'devel_docs',
+  input: docs_sources + interfaces_rst,
+  output: 'devel-docs',
+  command: [ sphinx_build, meson.current_source_dir(), '@OUTPUT@' ],
+)
diff --git a/devel-docs/xml-changes.rst b/devel-docs/xml-changes.rst
new file mode 100644
index 00000000..cf49b4ba
--- /dev/null
+++ b/devel-docs/xml-changes.rst
@@ -0,0 +1,63 @@
+Changes to the DBus XML interfaces
+==================================
+
+The `XML descriptions of DBus interfaces
+<https://gitlab.gnome.org/GNOME/at-spi2-core/-/tree/main/xml>`_ and
+the actual C code that implements them have gone out of sync in the
+past.  During the process of `auditing the XML and C code
+<https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/75>`_ to ensure
+they match each other, changes have been needed in the XML
+definitions.
+
+**Assumptions for toolkits:** Regretfully, both the in-tree XML files
+and the introspected XML you get from DBus have been out of sync with
+the C code.  We are fixing this so that they always stay in sync:
+
+* Make the XML files the single source of truth...
+
+* By making sure the XML matches the C code, which is the ground truth
+  before this auditing project began...
+
+* And by making sure that the introspected XML matches the XML files
+  in-tree.
+
+* Along the way, document all the XML interfaces properly.
+
+This document is a list of changes that we've made to the XML
+interfaces since 2022/Jun (starting with version 2.45.90).  If you
+generate code based on the XML, keep an eye on this document.
+
+The changes here are about **method signatures**.  Changes to the
+documentation are not listed, since they do not affect generated code.
+The changes are listed in reverse chronological order (newest first).
+
+* add8abce - 2022/12/09 - ``DeviceEventListener.xml`` - Remove unused signals
+  ``DeviceListenerRegistered`` and ``DeviceListenerDeregistered``.
+
+* 9096b760 - 2022/12/09 - ``DeviceEventController.xml`` -  fix the signature
+  of the ``types`` argument in the ``RegisterKeystrokeListener``
+  method; it's ``u`` now as it is a bitmask, not an array.
+
+* 55934a59 - 2022/12/05 - ``DeviceEventController.xml`` - remove unused method
+  ``DeregisterDeviceEventListener``.
+
+* 9b96a257 - 2022/12/05 - ``DeviceEventController.xml`` - remove unused method
+  ``RegisterDeviceEventListener``.
+
+* cb10a4c9 - 2022/12/05 - ``DeviceEventController.xml`` - remove unused method
+  ``GetDeviceEventListeners``.
+
+* f0781465 - 2022/08/26 - ``Event.xml`` - Fix the signature of all
+  signals.  See https://gitlab.gnome.org/GNOME/at-spi2-core/-/issues/74
+
+* 01d624b1 - 2022/08/11 - ``Application.xml`` - document the ``GetLocale`` method as not
+  used.
+
+* 26835da29 - 2022/08/04 - ``Event.xml`` - Add an ``Announcement`` signal to the
+  ``org.a11y.atspi.Event.Object`` interface.
+
+* 0412902f - 2022/07/01 - ``DeviceEventListener.xml``: add missing signals
+  ``KeystrokeListenerRegistered``, ``KeystrokeListenerDeregistered``
+
+* ae6eb3bd - 2022/07/01 - ``DeviceEventController.xml``: add missing
+  methods ``GetKeystrokeListeners``.
diff --git a/meson.build b/meson.build
index 44f109f6..b386aa29 100644
--- a/meson.build
+++ b/meson.build
@@ -6,10 +6,12 @@ project('at-spi2-core', 'c',
           'warning_level=1',
           'c_std=c99',
         ],
-        meson_version: '>= 0.56.2')
+        meson_version: '>= 0.60.0')
 
 add_project_arguments([ '-D_POSIX_C_SOURCE=200809L', '-D_DEFAULT_SOURCE' ], language: 'c')
 
+fs = import('fs')
+
 atspi_gir_ns = 'Atspi'
 
 cc = meson.get_compiler('c')
@@ -204,6 +206,7 @@ subdir('tests')
 
 if get_option('docs')
   subdir('doc')
+  subdir('devel-docs')
 endif
 
 if xgettext.found()
diff --git a/registryd/de-types.h b/registryd/de-types.h
index 656aded1..bfdac085 100644
--- a/registryd/de-types.h
+++ b/registryd/de-types.h
@@ -33,8 +33,6 @@ typedef enum
 {
   Accessibility_KEY_PRESSED_EVENT,
   Accessibility_KEY_RELEASED_EVENT,
-  Accessibility_BUTTON_PRESSED_EVENT,
-  Accessibility_BUTTON_RELEASED_EVENT,
 } Accessibility_EventType;
 
 typedef enum
diff --git a/registryd/deviceeventcontroller-x11.c b/registryd/deviceeventcontroller-x11.c
index d5cae611..5bf37e5d 100644
--- a/registryd/deviceeventcontroller-x11.c
+++ b/registryd/deviceeventcontroller-x11.c
@@ -42,11 +42,11 @@
 
 #include <dbus/dbus.h>
 
-#include "de-marshaller.h"
 #include "de-types.h"
 #include "display.h"
 #include "event-source.h"
 #include "keymasks.h"
+#include "marshal-dbus.h"
 #include "paths.h"
 
 #include "deviceeventcontroller.h"
@@ -418,32 +418,6 @@ spi_dec_ungrab_mouse (gpointer data)
 #endif
 
 static void
-spi_dec_init_mouse_listener (SpiDEController *dec)
-{
-#ifdef GRAB_BUTTON
-  Display *display = spi_get_display ();
-
-  if (display)
-    {
-      if (XGrabButton (display, AnyButton, AnyModifier,
-                       spi_get_root_window (),
-                       True, ButtonPressMask | ButtonReleaseMask,
-                       GrabModeSync, GrabModeAsync, None, None) != Success)
-        {
-#ifdef SPI_DEBUG
-          fprintf (stderr, "WARNING: could not grab mouse buttons!\n");
-#endif
-          ;
-        }
-      XSync (display, False);
-#ifdef SPI_DEBUG
-      fprintf (stderr, "mouse buttons grabbed\n");
-#endif
-    }
-#endif
-}
-
-static void
 spi_dec_clear_unlatch_pending (SpiDEController *controller)
 {
   SpiDEControllerPrivate *priv = spi_device_event_controller_get_instance_private (controller);
@@ -1213,8 +1187,6 @@ spi_dec_x11_init (SpiDEController *controller)
   gettimeofday (&priv->last_release_time, NULL);
   spi_controller_register_with_devices (controller);
 
-  spi_dec_init_mouse_listener (controller);
-
   saved_controller = controller;
 }
 
diff --git a/registryd/deviceeventcontroller.c b/registryd/deviceeventcontroller.c
index 466bae22..4f02a54a 100644
--- a/registryd/deviceeventcontroller.c
+++ b/registryd/deviceeventcontroller.c
@@ -38,9 +38,9 @@
 
 #include <dbus/dbus.h>
 
-#include "de-marshaller.h"
 #include "de-types.h"
 #include "keymasks.h"
+#include "marshal-dbus.h"
 #include "paths.h"
 
 #include "deviceeventcontroller.h"
@@ -1232,11 +1232,9 @@ impl_register_keystroke_listener (DBusMessage *message, SpiDEController *control
   dbus_message_iter_next (&iter);
   dbus_message_iter_get_basic (&iter, &types);
   dbus_message_iter_next (&iter);
-  mode = (Accessibility_EventListenerMode *) g_malloc (sizeof (Accessibility_EventListenerMode));
-  if (mode)
-    {
-      spi_dbus_message_iter_get_struct (&iter, DBUS_TYPE_BOOLEAN, &mode->synchronous, DBUS_TYPE_BOOLEAN, &mode->preemptive, DBUS_TYPE_BOOLEAN, &mode->global, DBUS_TYPE_INVALID);
-    }
+  mode = g_new0 (Accessibility_EventListenerMode, 1);
+  spi_dbus_message_iter_get_struct (&iter, DBUS_TYPE_BOOLEAN, &mode->synchronous, DBUS_TYPE_BOOLEAN, &mode->preemptive, DBUS_TYPE_BOOLEAN, &mode->global, DBUS_TYPE_INVALID);
+
 #ifdef SPI_DEBUG
   fprintf (stderr, "registering keystroke listener %s:%s with maskVal %lu\n",
            dbus_message_get_sender (message), path, (unsigned long) mask);
diff --git a/registryd/de-marshaller.c b/registryd/marshal-dbus.c
index 8c65bfe7..8c65bfe7 100644
--- a/registryd/de-marshaller.c
+++ b/registryd/marshal-dbus.c
diff --git a/registryd/de-marshaller.h b/registryd/marshal-dbus.h
index ddaf1360..ddaf1360 100644
--- a/registryd/de-marshaller.h
+++ b/registryd/marshal-dbus.h
diff --git a/registryd/meson.build b/registryd/meson.build
index 961372cf..dfbbe5ce 100644
--- a/registryd/meson.build
+++ b/registryd/meson.build
@@ -2,11 +2,11 @@ atspi_introspection_path = ''
 
 registryd_sources = [
   introspection_generated,
-  'de-marshaller.c',
-  'registry-main.c',
-  'registry.c',
   'deviceeventcontroller.c',
+  'marshal-dbus.c',
   'reentrant-list.c',
+  'registry-main.c',
+  'registry.c',
 ]
 
 registryd_deps = [
diff --git a/xml/Action.xml b/xml/Action.xml
index 4ed3d156..1729562e 100644
--- a/xml/Action.xml
+++ b/xml/Action.xml
@@ -70,11 +70,13 @@
           This typically corresponds to the underlined letter within the widget.
           Example: "n" in a traditional "New..." menu item or the "a" in "Apply" for
           a button.
+
         - The sequence is the full list of keys which invoke the action even if the
           relevant element is not currently shown on screen. For instance, for a menu
           item the sequence is the keybindings used to open the parent menus before
           invoking. The sequence string is colon-delimited. Example: "Alt+F:N" in a
           traditional "New..." menu item.
+
         - The shortcut, if it exists, will invoke the same action without showing
           the component or its enclosing menus or dialogs. Example: "Ctrl+N" in a
           traditional "New..." menu item.
diff --git a/xml/DeviceEventController.xml b/xml/DeviceEventController.xml
index 0fc0730f..c006fe1d 100644
--- a/xml/DeviceEventController.xml
+++ b/xml/DeviceEventController.xml
@@ -1,13 +1,53 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<node>
+<node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
+  <!--
+      org.a11y.atspi.DeviceEventController:
+      @short_description: Legacy interface for keystroke listeners and generation of keyboard/mouse events
+
+      This interface is being replaced by the functions in atspi-device-listener.h.
+  -->
   <interface name="org.a11y.atspi.DeviceEventController">
 
+    <!--
+        RegisterKeystrokeListener:
+        @listener: path of object to be notified when the following keys are pressed
+        @keys: array of (key_code, key_sym, key_string, unused)
+        @mask: modifier mask in X11 style (see Xlib.h)
+        @types: mask of press/release; see the description below.
+        @mode: struct of flags (synchronous, preemptive, global), see the description below.
+
+        The @types can be a mask of the following:
+
+          * KEY_PRESS   = 1 << 0
+          * KEY_RELEASE = 1 << 1
+
+        Note that Orca always passes (KEY_PRESS | KEY_RELEASE).
+
+        The @mode is composed of three flags (see AtspiKeyListenerSyncType):
+
+          * synchronous: Events are delivered synchronously, before
+            the currently focused application sees them.  If false,
+            events may be delivered asynchronously, which means in some
+            cases they may already have been delivered to the
+            application before the AT client receives the notification.
+
+          * preemptive: (called CANCONSUME in AtspiKeyListenerSyncType)
+            Events may be consumed by the AT client.  Requires the synchronous flag to be set.
+
+          * global: (called ALL_WINDOWS in AtspiKeyListenerSyncType)
+            Events are received not from the application toolkit layer,
+            but from the device driver or windowing system subsystem.
+
+        Returns: boolean indicating whether the operation was successful.  This is always
+        TRUE for non-global listeners (c.f. @mode), and may be FALSE for global listeners
+        if the underlying XGrabKey() failed (see spi_dec_x11_grab_key).
+    -->
     <method name="RegisterKeystrokeListener">
       <arg direction="in" name="listener" type="o"/>
       <arg direction="in" name="keys" type="a(iisi)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In1" value="QSpiKeyTypeArray"/>
       <arg direction="in" name="mask" type="u"/>
-      <arg direction="in" name="type" type="au"/>
+      <arg direction="in" name="types" type="u"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In3" value="QSpiEventTypeArray"/>
       <arg direction="in" name="mode" type="(bbb)"/>
       <annotation name="org.qtproject.QtDBus.QtTypeName.In4" value="QSpiEventMode"/>
diff --git a/xml/DeviceEventListener.xml b/xml/DeviceEventListener.xml
index ce22df2b..38c63e67 100644
--- a/xml/DeviceEventListener.xml
+++ b/xml/DeviceEventListener.xml
@@ -16,13 +16,5 @@
       <arg name="listener" type="(souua(iisi)u(bbb))"/>
     </signal>
 
-    <signal name="DeviceListenerRegistered">
-      <arg name="listener" type="(sou)"/>
-    </signal>
-
-    <signal name="DeviceListenerDeregistered">
-      <arg name="listener" type="(sou)"/>
-    </signal>
-
   </interface>
 </node>