Debian Codegraph @

include/test/a11y/AccessibilityTools.hxx

raw
1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4; fill-column: 100 -*- */
2 /*
3 * This file is part of the LibreOffice project.
4 *
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
8 *
9 * This file incorporates work covered by the following license notice:
10 *
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
18 */
19
20 #pragma once
21
22 #include <test/testdllapi.hxx>
23
24 #include <functional>
25 #include <string>
26
27 #include <cppunit/TestAssert.h>
28
29 #include <com/sun/star/accessibility/AccessibleEventObject.hpp>
30 #include <com/sun/star/accessibility/AccessibleRelationType.hpp>
31 #include <com/sun/star/accessibility/XAccessible.hpp>
32 #include <com/sun/star/accessibility/XAccessibleAction.hpp>
33 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
34 #include <com/sun/star/accessibility/XAccessibleText.hpp>
35
36 using css::accessibility::AccessibleRelationType;
37
38 class OOO_DLLPUBLIC_TEST AccessibilityTools
39 {
40 public:
41 /** Maximum number of children to work on. This is especially useful for
42 * Calc which has a million elements, if not more. */
43 static const sal_Int32 MAX_CHILDREN = 500;
44
45 static css::uno::Reference<css::accessibility::XAccessibleContext>
46 getAccessibleObjectForPredicate(
47 const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx,
48 const std::function<
49 bool(const css::uno::Reference<css::accessibility::XAccessibleContext>&)>& cPredicate);
50 static css::uno::Reference<css::accessibility::XAccessibleContext>
51 getAccessibleObjectForPredicate(
52 const css::uno::Reference<css::accessibility::XAccessible>& xAcc,
53 const std::function<
54 bool(const css::uno::Reference<css::accessibility::XAccessibleContext>&)>& cPredicate);
55
56 static css::uno::Reference<css::accessibility::XAccessibleContext> getAccessibleObjectForId(
57 const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx,
58 std::u16string_view sId);
59 static css::uno::Reference<css::accessibility::XAccessibleContext>
60 getAccessibleObjectForId(const css::uno::Reference<css::accessibility::XAccessible>& xacc,
61 std::u16string_view sId);
62
63 static css::uno::Reference<css::accessibility::XAccessibleContext> getAccessibleObjectForRole(
64 const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx, sal_Int16 role);
65 static css::uno::Reference<css::accessibility::XAccessibleContext>
66 getAccessibleObjectForRole(const css::uno::Reference<css::accessibility::XAccessible>& xacc,
67 sal_Int16 role);
68
69 /**
70 * @brief Gets a descendant of @p xCtx (or @p xCtx itself) that matches the given role and name.
71 * @param xCtx An accessible context object to start the search from
72 * @param role The role of the object to look up.
73 * @param name The name of the object to look up.
74 * @returns The found object, or @c nullptr if not found.
75 *
76 * Finds a descendant of @p xCtx (or @p xCtx itself) that matches @p role and @p name.
77 * @code
78 * AccessibilityTools::getAccessibleObjectForName(
79 * css::accessibility::AccessibleRole::PUSH_BUTTON, u"Insert");
80 * @endcode
81 *
82 * @see AccessibilityTools::getAccessibleObjectForPredicate() */
83 static css::uno::Reference<css::accessibility::XAccessibleContext> getAccessibleObjectForName(
84 const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx,
85 const sal_Int16 role, std::u16string_view name);
86 static inline css::uno::Reference<css::accessibility::XAccessibleContext>
87 getAccessibleObjectForName(const css::uno::Reference<css::accessibility::XAccessible>& xAcc,
88 const sal_Int16 role, std::u16string_view name)
89 {
90 return getAccessibleObjectForName(xAcc->getAccessibleContext(), role, name);
91 }
92
93 /**
94 * @brief Gets a descendant of @p xCtx (or @p xCtx itself) that matches the last given role and
95 * name pair, and has ancestors matching the leading pairs in the given order.
96 * @param xCtx An accessible context to start the search from.
97 * @param role The role of the first ancestor to match.
98 * @param name The name of the first ancestor to match.
99 * @param Ts...args Additional role and name pairs of ancestors, ending with the role and name
100 * pair of the target object to match.
101 * @returns The found object, or @c nullptr if not found.
102 *
103 * Specialized version allowing specifying arbitrary objects on the path to the target one. Not
104 * all objects have to be matched, but there have to be ancestors matching in the given order.
105 * This is useful to easily solve conflicts if there are more than one possible match.
106 *
107 * This can be used to find an "Insert" push button inside a panel named "Some group" for
108 * example, as shown below:
109 *
110 * @code
111 * AccessibilityTools::getAccessibleObjectForName(
112 * css::accessibility::AccessibleRole::PANEL, u"Some group",
113 * css::accessibility::AccessibleRole::PUSH_BUTTON, u"Insert");
114 * @endcode
115 *
116 * @note This returns the first match in the object tree when walking it depth-first. Depending
117 * on the tree, this might not be able to find the expected match, e.g. if there is a
118 * first match with intermediate unmatched objects, and the target has the same tree but
119 * without intermediate objects that can be used to refine the search and prevent the
120 * unwanted tree to match. The same issue arises with two identical trees, yet in that
121 * case no walking scenario could solve it automatically anyway.
122 * In such situations, a custom @c getAccessibleObjectForPredicate() call, or successive
123 * lookups interleaved with specific child lookups are likely the best solution.
124 *
125 * @see getAccessibleObjectForPredicate().
126 */
127 /* TODO: reimplement as IDDFS or BFS? Not sure the additional complexity/performance costs
128 * warrant it. */
129 template <typename... Ts>
130 static css::uno::Reference<css::accessibility::XAccessibleContext> getAccessibleObjectForName(
131 const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx,
132 const sal_Int16 role, std::u16string_view name, Ts... args)
133 {
134 auto nChildren = xCtx->getAccessibleChildCount();
135
136 // try self first
137 if (xCtx->getAccessibleRole() == role && nameEquals(xCtx, name))
138 {
139 for (decltype(nChildren) i = 0; i < nChildren && i < MAX_CHILDREN; i++)
140 {
141 if (auto xMatchChild
142 = getAccessibleObjectForName(xCtx->getAccessibleChild(i), args...))
143 return xMatchChild;
144 }
145 }
146
147 // if not found, try at a deeper level
148 for (decltype(nChildren) i = 0; i < nChildren && i < MAX_CHILDREN; i++)
149 {
150 if (auto xMatchChild
151 = getAccessibleObjectForName(xCtx->getAccessibleChild(i), role, name, args...))
152 return xMatchChild;
153 }
154
155 return nullptr;
156 }
157
158 template <typename... Ts>
159 static inline css::uno::Reference<css::accessibility::XAccessibleContext>
160 getAccessibleObjectForName(const css::uno::Reference<css::accessibility::XAccessible>& xAcc,
161 const sal_Int16 role, std::u16string_view name, Ts... args)
162 {
163 return getAccessibleObjectForName(xAcc->getAccessibleContext(), role, name, args...);
164 }
165
166 static bool equals(const css::uno::Reference<css::accessibility::XAccessible>& xacc1,
167 const css::uno::Reference<css::accessibility::XAccessible>& xacc2);
168 static bool equals(const css::uno::Reference<css::accessibility::XAccessibleContext>& xctx1,
169 const css::uno::Reference<css::accessibility::XAccessibleContext>& xctx2);
170
171 /**
172 * @brief Compares the accessible name against a string
173 * @param xCtx A XAccessibleContext on which compare the name
174 * @param name The string to compare to
175 * @returns @c true if @p xCtx name matches @p name.
176 *
177 * This is conceptually equivalent to @code xCtx->getAccessibleName() == name @endcode, but
178 * handles the case OSL debugging is active and inserts a type suffix. Unless you know for
179 * sure the accessible you are comparing is not subject to those suffixes under debugging,
180 * always use this function instead of direct comparison.
181 */
182 static bool nameEquals(const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx,
183 const std::u16string_view name);
184 static bool nameEquals(const css::uno::Reference<css::accessibility::XAccessible>& xAcc,
185 const std::u16string_view name)
186 {
187 return nameEquals(xAcc->getAccessibleContext(), name);
188 }
189
190 static OUString getRoleName(const sal_Int16 role);
191 static OUString getEventIdName(const sal_Int16 event_id);
192 static OUString getRelationTypeName(AccessibleRelationType rel_type);
193
194 template <typename T> static std::string debugString(const css::uno::Reference<T>& x)
195 {
196 return debugString(x.get());
197 }
198
199 template <typename T> static std::string debugString(const T& x) { return debugString(&x); }
200
201 template <typename T> static std::string debugString(const T* p)
202 {
203 /* only the forwarding to debugName() might actually dereference @c p,
204 * and we rely on specializations to be as constant as possible and not
205 * violate the cast here. In practice it'll be the case for all types
206 * handle if we carefully write the specializations. In most case the
207 * specialization could take a const itself if the methods were
208 * properly marked const, but well. */
209 return debugString(const_cast<T*>(p));
210 }
211
212 template <typename T> static std::string debugString(T* p)
213 {
214 CPPUNIT_NS::OStringStream ost;
215
216 ost << "(" << static_cast<const void*>(p) << ")";
217 if (p != nullptr)
218 ost << " " << debugName(p);
219
220 return ost.str();
221 }
222
223 static OUString debugAccessibleStateSet(sal_Int64 p);
224
225 /**
226 * @brief Process events until a condition or a timeout
227 * @param cUntilCallback Callback condition
228 * @param nTimeoutMs Maximum time in ms to wait for condition
229 * @returns @c true if the condition was met, or @c false if the timeout
230 * has been reached.
231 *
232 * Processes events until idle, and either until the given condition
233 * becomes @c true or a timeout is reached.
234 *
235 * This is similar to Scheduler::ProcessEventsToIdle() but awaits a
236 * condition up to a timeout. This is useful if the waited-on condition
237 * might happen after the first idle time. The timeout helps in case the
238 * condition is not satisfied in reasonable time.
239 *
240 * @p cUntilCallback is called each time the scheduler reaches idle to check
241 * whether the condition is met.
242 *
243 * Example:
244 * @code
245 * ProcessEvents([&]() { return taskHasRun; });
246 * @endcode
247 *
248 * @see Scheduler::ProcessEventsToIdle()
249 */
250 static bool Await(const std::function<bool()>& cUntilCallback, sal_uInt64 nTimeoutMs = 3000);
251
252 /**
253 * @brief Process events for a given time
254 * @param nTimeoutMs Time to dispatch events for
255 *
256 * Process events for a given time. This can be useful if waiting is in
257 * order but there is no actual condition to wait on (e.g. expect
258 * something *not* to happen). This similar in spirit to
259 * @c sleep(nTimeoutMs), but dispatches events during the wait.
260 *
261 * This function should be used sparsely because waiting a given time is
262 * rarely a good solution for a problem, but in some specific situations
263 * there is no better alternative (like, again, waiting for something not
264 * to happen).
265 */
266 static void Wait(sal_uInt64 nTimeoutMs);
267
268 private:
269 static OUString debugName(css::accessibility::XAccessibleContext* xctx);
270 static OUString debugName(css::accessibility::XAccessible* xacc);
271 static OUString debugName(const css::accessibility::AccessibleEventObject* evobj);
272 static OUString debugName(css::accessibility::XAccessibleAction* xAct);
273 static OUString debugName(css::accessibility::XAccessibleText* xTxt);
274 };
275
276 CPPUNIT_NS_BEGIN
277 /* How to generate those automatically? We don't want to match all types
278 * not to mess up cppunit for types we don't support */
279 #define AT_ASSERTION_TRAITS(T) \
280 template <> struct assertion_traits<css::uno::Reference<T>> \
281 { \
282 static bool equal(const css::uno::Reference<T>& x, const css::uno::Reference<T>& y) \
283 { \
284 return AccessibilityTools::equals(x, y); \
285 } \
286 \
287 static std::string toString(const css::uno::Reference<T>& x) \
288 { \
289 return AccessibilityTools::debugString(x); \
290 } \
291 }
292
293 AT_ASSERTION_TRAITS(css::accessibility::XAccessible);
294 AT_ASSERTION_TRAITS(css::accessibility::XAccessibleContext);
295
296 #undef AT_ASSERTION_TRAITS
297
298 CPPUNIT_NS_END
299
300 /* vim:set shiftwidth=4 softtabstop=4 expandtab cinoptions=b1,g0,N-s cinkeys+=0=break: */