Debian Codegraph @

tools/dump-events.py

raw
1 #!/usr/bin/python
2 # dump-events.py
3 #
4 # Command-line tool to listen for and display accessibility events for a named
5 # application.
6 #
7 # Usage: dump-events.py <APP_NAME> [EVENT_TYPE]
8 #
9 # Copyright 2026 Igalia, S.L.
10 # Author: Joanmarie Diggs <[email protected]>
11 #
12 # This library is free software; you can redistribute it and/or
13 # modify it under the terms of the GNU Lesser General Public
14 # License as published by the Free Software Foundation; either
15 # version 2.1 of the License, or (at your option) any later version.
16 #
17 # This library is distributed in the hope that it will be useful,
18 # but WITHOUT ANY WARRANTY; without even the implied warranty of
19 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 # Lesser General Public License for more details.
21 #
22 # You should have received a copy of the GNU Lesser General Public
23 # License along with this library; if not, write to the
24 # Free Software Foundation, Inc., Franklin Street, Fifth Floor,
25 # Boston MA 02110-1301 USA.
26
27 # pylint: disable=invalid-name
28 # pylint: disable=wrong-import-position
29
30 """Command-line tool to listen for and display accessibility events for a named application."""
31
32 import signal
33 import sys
34 from types import SimpleNamespace
35
36 import gi
37
38 gi.require_version("Atspi", "2.0")
39 from gi.repository import Atspi, GLib
40
41 _state = SimpleNamespace(
42 app_name="",
43 desktop_app_names=set(),
44 extra_app_names=set(),
45 all_app_names=set(),
46 event_count=0,
47 event_filter="",
48 )
49
50
51 def get_name_and_role(obj):
52 """Get the name and role of an accessible object, falling back on labelled-by."""
53
54 try:
55 name = Atspi.Accessible.get_name(obj) or ""
56 role = Atspi.Accessible.get_role(obj).value_nick
57 except GLib.GError:
58 return "", "(error)"
59
60 if not name:
61 label = _get_name_from_labelled_by(obj)
62 if label:
63 name = f"{label} (from labelled-by)"
64
65 return name, role
66
67
68 def _get_name_from_labelled_by(obj):
69 """Returns the name derived from the labelled-by relation, or empty string."""
70
71 try:
72 relations = Atspi.Accessible.get_relation_set(obj)
73 except GLib.GError:
74 return ""
75
76 for relation in relations:
77 if relation.get_relation_type() != Atspi.RelationType.LABELLED_BY:
78 continue
79 targets = [relation.get_target(i) for i in range(relation.get_n_targets())]
80 names = []
81 for target in targets:
82 try:
83 target_name = Atspi.Accessible.get_name(target) or ""
84 except GLib.GError:
85 target_name = ""
86 if target_name:
87 names.append(target_name)
88 if names:
89 return " ".join(names)
90
91 return ""
92
93
94 def matches_app(obj):
95 """Returns True if obj belongs to the target application."""
96
97 try:
98 app = Atspi.Accessible.get_application(obj)
99 app_name = Atspi.Accessible.get_name(app) or "" if app is not None else ""
100 except GLib.GError:
101 app_name = ""
102 if app_name in _state.all_app_names:
103 return True
104 if _state.app_name.lower() in app_name.lower():
105 _state.all_app_names.add(app_name)
106 if app_name not in _state.desktop_app_names:
107 _state.extra_app_names.add(app_name)
108 return True
109 return False
110
111
112 def on_event(event):
113 """Callback for all accessibility events."""
114
115 if not matches_app(event.source):
116 return
117
118 if _state.event_filter and not event.type.startswith(_state.event_filter):
119 return
120
121 _state.event_count += 1
122
123 name, role = get_name_and_role(event.source)
124 source = f"'{name}' ({role})" if name else f"<unnamed> ({role})"
125
126 detail1 = bool(event.detail1) if "state-changed" in event.type else event.detail1
127
128 print(
129 f"{event.type} src={source}"
130 f" detail1={detail1} detail2={event.detail2}"
131 f" any_data={event.any_data}"
132 )
133
134
135 def get_desktop_apps():
136 """Get all accessible applications from the desktop as (name, object) pairs."""
137
138 apps = []
139 desktop = Atspi.get_desktop(0)
140 for i in range(Atspi.Accessible.get_child_count(desktop)):
141 try:
142 child = Atspi.Accessible.get_child_at_index(desktop, i)
143 name = Atspi.Accessible.get_name(child)
144 if name != "mutter-x11-frames":
145 apps.append((name, child))
146 except GLib.GError:
147 continue
148 return apps
149
150
151 def main():
152 """Starts listening for events from the specified application."""
153
154 if len(sys.argv) < 2:
155 print("Usage: dump-events.py <APP_NAME> [EVENT_TYPE]")
156 print()
157 print("EVENT_TYPE is an optional prefix filter, e.g.:")
158 print(" object:state-changed:focused")
159 print(" object:text-changed")
160 print(" window:")
161 print()
162 apps = get_desktop_apps()
163 print(f"Desktop has {len(apps)} accessible application(s):")
164 for i, (name, _obj) in enumerate(apps):
165 print(f" {i + 1}. {name}")
166 sys.exit(1)
167
168 _state.app_name = sys.argv[1]
169 _state.event_filter = sys.argv[2] if len(sys.argv) > 2 else ""
170
171 apps = get_desktop_apps()
172 matches = [(n, o) for n, o in apps if _state.app_name.lower() in n.lower()]
173 if not matches:
174 print(f"No application matching '{_state.app_name}' found.")
175 print(f"Desktop has {len(apps)} accessible application(s):")
176 for i, (name, _obj) in enumerate(apps):
177 print(f" {i + 1}. {name}")
178 sys.exit(1)
179
180 match_names = [n for n, _o in matches]
181 _state.desktop_app_names = set(match_names)
182 _state.all_app_names = set(match_names)
183 if len(matches) > 1:
184 print(f"Matching applications: {', '.join(match_names)}")
185
186 event_types = [
187 "object:state-changed:",
188 "object:children-changed:",
189 "object:property-change:",
190 "object:text-caret-moved",
191 "object:text-changed:",
192 "window:",
193 ]
194
195 listeners = []
196 for event_type in event_types:
197 listener = Atspi.EventListener.new(on_event)
198 listener.register(event_type)
199 listeners.append(listener)
200
201 filter_msg = f" (filter: {_state.event_filter})" if _state.event_filter else ""
202 print(f"Listening for events from '{_state.app_name}'{filter_msg}. Press Ctrl+C to stop.\n")
203
204 GLib.unix_signal_add(GLib.PRIORITY_HIGH, signal.SIGINT, _on_sigint)
205 Atspi.event_main() # pylint: disable=no-value-for-parameter
206
207
208 def _on_sigint():
209 """Handle Ctrl+C by quitting the event loop."""
210
211 print(f"\nStopped. {_state.event_count} event(s) received.")
212 Atspi.event_quit() # pylint: disable=no-value-for-parameter
213 return GLib.SOURCE_REMOVE
214
215
216 if __name__ == "__main__":
217 main()