Debian Codegraph @

tools/dump-focused-object.py

raw
1 #!/usr/bin/python
2 # dump-focused-object.py
3 #
4 # Command-line tool to dump the focused object and its ancestors.
5 # This tool listens for focus events and displays the accessibility tree
6 # from the application down to the focused object.
7 #
8 # Copyright 2025 Igalia, S.L.
9 # Author: Joanmarie Diggs <[email protected]>
10 #
11 # This library is free software; you can redistribute it and/or
12 # modify it under the terms of the GNU Lesser General Public
13 # License as published by the Free Software Foundation; either
14 # version 2.1 of the License, or (at your option) any later version.
15 #
16 # This library is distributed in the hope that it will be useful,
17 # but WITHOUT ANY WARRANTY; without even the implied warranty of
18 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 # Lesser General Public License for more details.
20 #
21 # You should have received a copy of the GNU Lesser General Public
22 # License along with this library; if not, write to the
23 # Free Software Foundation, Inc., Franklin Street, Fifth Floor,
24 # Boston MA 02110-1301 USA.
25
26 # pylint: disable=invalid-name
27 # pylint: disable=wrong-import-position
28
29 """Command-line tool to dump the focused object and its ancestors."""
30
31 import gi
32
33 gi.require_version("Atspi", "2.0")
34 from gi.repository import Atspi, GLib
35
36
37 def as_string(obj):
38 """Convert an accessible object to a string representation."""
39
40 try:
41 help_text = Atspi.Accessible.get_help_text(obj)
42 except GLib.GError as error:
43 help_text = f"({error})"
44 return (
45 f"{Atspi.Accessible.get_role(obj).value_name} "
46 f"name:'{get_name(obj)}' "
47 f"description:'{get_description(obj)}' "
48 f"help text: '{help_text}'"
49 )
50
51
52 def get_name(obj):
53 """Get the name of an accessible object."""
54
55 name = Atspi.Accessible.get_name(obj)
56 if name:
57 return name
58
59 relations = Atspi.Accessible.get_relation_set(obj)
60 for relation in relations:
61 if relation.get_relation_type() != Atspi.RelationType.LABELLED_BY:
62 continue
63 targets = [relation.get_target(i) for i in range(relation.get_n_targets())]
64 return " ".join([target.name for target in targets])
65
66 return ""
67
68
69 def get_description(obj):
70 """Get the description of an accessible object."""
71
72 description = Atspi.Accessible.get_description(obj)
73 if description:
74 return description
75
76 relations = Atspi.Accessible.get_relation_set(obj)
77 for relation in relations:
78 if relation.get_relation_type() != Atspi.RelationType.DESCRIBED_BY:
79 continue
80 targets = [relation.get_target(i) for i in range(relation.get_n_targets())]
81 return " ".join([target.name for target in targets])
82
83 return ""
84
85
86 def on_event(e):
87 """Handle focus events."""
88
89 if not e.detail1:
90 return
91
92 print(f"\n{as_string(e.source)} is now focused")
93 ancestors = []
94 parent = e.source
95 while parent:
96 grandparent = Atspi.Accessible.get_parent(parent)
97 ancestors.append(as_string(parent))
98 if Atspi.Accessible.get_role(parent) == Atspi.Role.APPLICATION:
99 break
100 parent = grandparent
101
102 ancestors.reverse()
103 indent = 0
104 for ancestor in ancestors:
105 print(f"{' ' * indent}--> {ancestor}")
106 indent += 2
107
108 if Atspi.Accessible.get_role(e.source) == Atspi.Role.TERMINAL:
109 print("Exiting.")
110 Atspi.event_quit()
111
112
113 def main():
114 """Starts the focus dumper and waits for events."""
115
116 listener = Atspi.EventListener.new(on_event)
117 listener.register("object:state-changed:focused")
118 print("Listening for focus events. Return focus to your terminal to exit.")
119 Atspi.event_main()
120
121
122 if __name__ == "__main__":
123 main()