Debian Codegraph @

include/test/a11y/accessibletestbase.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
10 #pragma once
11
12 #include <test/testdllapi.hxx>
13
14 #include <deque>
15 #include <string>
16
17 #include <com/sun/star/accessibility/AccessibleRole.hpp>
18 #include <com/sun/star/accessibility/XAccessible.hpp>
19 #include <com/sun/star/accessibility/XAccessibleAction.hpp>
20 #include <com/sun/star/accessibility/XAccessibleContext.hpp>
21 #include <com/sun/star/awt/XDialog2.hpp>
22 #include <com/sun/star/awt/XWindow.hpp>
23 #include <com/sun/star/frame/XDesktop2.hpp>
24 #include <com/sun/star/lang/XComponent.hpp>
25 #include <com/sun/star/uno/Reference.hxx>
26 #include <comphelper/OAccessible.hxx>
27
28 #include <vcl/ITiledRenderable.hxx>
29
30 #include <rtl/ustring.hxx>
31 #include <test/bootstrapfixture.hxx>
32 #include <test/a11y/eventposter.hxx>
33
34 #include "AccessibilityTools.hxx"
35
36 namespace test
37 {
38 class OOO_DLLPUBLIC_TEST AccessibleTestBase : public test::BootstrapFixture
39 {
40 private:
41 void collectText(const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext,
42 rtl::OUStringBuffer& buffer, bool onlyChildren = false);
43
44 protected:
45 css::uno::Reference<css::frame::XDesktop2> mxDesktop;
46 css::uno::Reference<css::lang::XComponent> mxDocument;
47 css::uno::Reference<css::awt::XWindow> mxWindow;
48
49 static bool isDocumentRole(const sal_Int16 role);
50
51 virtual void load(const rtl::OUString& sURL);
52 virtual void loadFromSrc(const rtl::OUString& sSrcPath);
53 void close();
54 rtl::Reference<comphelper::OAccessible> getWindowAccessible();
55 virtual css::uno::Reference<css::accessibility::XAccessibleContext>
56 getDocumentAccessibleContext();
57
58 static css::uno::Reference<css::accessibility::XAccessibleContext> getPreviousFlowingSibling(
59 const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext);
60 static css::uno::Reference<css::accessibility::XAccessibleContext> getNextFlowingSibling(
61 const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext);
62
63 /** Collects contents of @p xContext in a dummy markup form */
64 OUString
65 collectText(const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext);
66
67 /** Collects contents of the current document */
68 OUString collectText() { return collectText(getDocumentAccessibleContext()); }
69
70 void documentPostKeyEvent(int nType, int nCharCode, int nKeyCode)
71 {
72 vcl::ITiledRenderable* pTiledRenderable
73 = dynamic_cast<vcl::ITiledRenderable*>(mxDocument.get());
74 CPPUNIT_ASSERT(pTiledRenderable);
75 pTiledRenderable->postKeyEvent(nType, nCharCode, nKeyCode);
76 }
77
78 static css::uno::Reference<css::accessibility::XAccessibleContext> getFirstRelationTargetOfType(
79 const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext,
80 css::accessibility::AccessibleRelationType relationType);
81
82 /**
83 * @brief Tries to list all children of an accessible
84 * @param xContext An XAccessibleContext object
85 * @returns The list of all children (but no more than @c AccessibilityTools::MAX_CHILDREN)
86 *
87 * This fetches children of @p xContext. This would ideally just be the same than iterating
88 * over children the regular way up to @c AccessibilityTools::MAX_CHILDREN, but unfortunately
89 * some components (Writer, Impress, ...) do not provide all their children the regular way and
90 * require specifics to include them.
91 *
92 * There is no guarantee on *which* children are returned if there are more than
93 * @c AccessibilityTools::MAX_CHILDREN -- yet they will always be the same in a given context.
94 */
95 virtual std::deque<css::uno::Reference<css::accessibility::XAccessibleContext>>
96 getAllChildren(const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext);
97
98 void dumpA11YTree(const css::uno::Reference<css::accessibility::XAccessibleContext>& xContext,
99 const int depth = 0);
100 void dumpA11YTree(const css::uno::Reference<css::accessibility::XAccessible>& xAccessible,
101 const int depth = 0);
102
103 css::uno::Reference<css::accessibility::XAccessibleContext>
104 getItemFromName(const css::uno::Reference<css::accessibility::XAccessibleContext>& xMenuCtx,
105 std::u16string_view name);
106 bool
107 activateMenuItem(const css::uno::Reference<css::accessibility::XAccessibleAction>& xAction);
108 /* just convenience not to have to query accessibility::XAccessibleAction manually */
109 bool activateMenuItem(const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx)
110 {
111 return activateMenuItem(css::uno::Reference<css::accessibility::XAccessibleAction>(
112 xCtx, css::uno::UNO_QUERY_THROW));
113 }
114
115 /* convenience to get a menu item from a list of menu item names. Unlike
116 * getItemFromName(context, name), this requires subsequently found items to implement
117 * XAccessibleAction, as each but the last item will be activated before looking for
118 * the next one, to account for the fact menus might not be fully populated before being
119 * activated. */
120 template <typename... Ts>
121 css::uno::Reference<css::accessibility::XAccessibleContext>
122 getItemFromName(const css::uno::Reference<css::accessibility::XAccessibleContext>& xMenuCtx,
123 std::u16string_view name, Ts... names)
124 {
125 auto item = getItemFromName(xMenuCtx, name);
126 CPPUNIT_ASSERT(item.is());
127 activateMenuItem(item);
128 return getItemFromName(item, names...);
129 }
130
131 /* convenience to activate an item by its name and all its parent menus up to xMenuCtx.
132 * @see getItemFromName() */
133 template <typename... Ts>
134 bool
135 activateMenuItem(const css::uno::Reference<css::accessibility::XAccessibleContext>& xMenuCtx,
136 Ts... names)
137 {
138 auto item = getItemFromName(xMenuCtx, names...);
139 CPPUNIT_ASSERT(item.is());
140 return activateMenuItem(item);
141 }
142
143 /* convenience to activate an item by its name and all its parent menus up to the main window
144 * menu bar */
145 template <typename... Ts> bool activateMenuItem(Ts... names)
146 {
147 auto menuBar = AccessibilityTools::getAccessibleObjectForRole(
148 css::uno::Reference<css::accessibility::XAccessibleContext>(getWindowAccessible()),
149 css::accessibility::AccessibleRole::MENU_BAR);
150 CPPUNIT_ASSERT(menuBar.is());
151 return activateMenuItem(menuBar, names...);
152 }
153
154 /**
155 * @brief Gets the focused accessible object at @p xAcc level or below
156 * @param xAcc An accessible object
157 * @returns The accessible context of the focused object, or @c nullptr
158 *
159 * Finds the accessible object context at or under @p xAcc that has the focused state (and is
160 * showing). Normally only one such object should exist in a given hierarchy, but in all cases
161 * this function will return the first one found.
162 *
163 * @see AccessibilityTools::getAccessibleObjectForPredicate()
164 */
165 static css::uno::Reference<css::accessibility::XAccessibleContext>
166 getFocusedObject(const css::uno::Reference<css::accessibility::XAccessibleContext>& xCtx);
167
168 static inline css::uno::Reference<css::accessibility::XAccessibleContext>
169 getFocusedObject(const css::uno::Reference<css::accessibility::XAccessible>& xAcc)
170 {
171 return getFocusedObject(xAcc->getAccessibleContext());
172 }
173
174 /**
175 * @brief Navigates through focusable elements using the Tab keyboard shortcut.
176 * @param xRoot The root element to look for focused elements in.
177 * @param role The accessible role of the element to tab to.
178 * @param name The accessible name of the element to tab to.
179 * @param pEventPosterHelper Pointer to a @c EventPosterHelper instance, or @c nullptr to obtain
180 * it from @p xRoot.
181 * @returns The element tabbed to, or @c nullptr if not found.
182 *
183 * Navigates through focusable elements in the top level containing @p xRoot using the Tab
184 * keyboard key until the focused elements matches @p role and @p name.
185 *
186 * Note that usually @p xRoot should be the toplevel accessible, or at least contain all
187 * focusable elements within that window. It is however *not* a requirement, but only elements
188 * actually inside it will be candidate for a match, and thus if focus goes outside it, it might
189 * lead to not finding the target element.
190 *
191 * If @p pEventPosterHelper is @c nullptr, this function will try to construct one from
192 * @p xRoot. @see EventPosterHelper.
193 */
194 static css::uno::Reference<css::accessibility::XAccessibleContext>
195 tabTo(const css::uno::Reference<css::accessibility::XAccessible>& xRoot, const sal_Int16 role,
196 const std::u16string_view name,
197 const EventPosterHelperBase* pEventPosterHelper = nullptr);
198
199 static bool tabTo(const css::uno::Reference<css::accessibility::XAccessible>& xRoot,
200 const css::uno::Reference<css::accessibility::XAccessibleContext>& xChild,
201 const EventPosterHelperBase* pEventPosterHelper = nullptr);
202
203 #if !defined(MACOSX)
204 /* Dialog handling */
205 class Dialog : public test::AccessibleEventPosterHelper
206 {
207 private:
208 bool mbAutoClose;
209 css::uno::Reference<css::awt::XDialog2> mxDialog2;
210 rtl::Reference<comphelper::OAccessible> mpAccessible;
211
212 public:
213 Dialog(const css::uno::Reference<css::awt::XDialog2>& xDialog2, bool bAutoClose = true);
214 virtual ~Dialog();
215
216 void setAutoClose(bool bAutoClose) { mbAutoClose = bAutoClose; }
217
218 css::uno::Reference<css::accessibility::XAccessible> getAccessible() const
219 {
220 return mpAccessible;
221 }
222
223 void close(sal_Int32 result = VclResponseType::RET_CANCEL);
224
225 css::uno::Reference<css::accessibility::XAccessibleContext>
226 tabTo(const sal_Int16 role, const std::u16string_view name)
227 {
228 return AccessibleTestBase::tabTo(getAccessible(), role, name, this);
229 }
230
231 bool tabTo(const css::uno::Reference<css::accessibility::XAccessibleContext>& xChild)
232 {
233 return AccessibleTestBase::tabTo(getAccessible(), xChild, this);
234 }
235 };
236
237 class DialogWaiter
238 {
239 public:
240 virtual ~DialogWaiter() {}
241
242 /**
243 * @brief Waits for the associated dialog to close
244 * @param nTimeoutMs Maximum delay to wait the dialog for
245 * @returns @c true if the dialog closed, @c false if timeout was reached
246 *
247 * @throws css::uno::RuntimeException if an unexpected dialog popped up instead of the
248 * expected one.
249 * @throws Any exception that the user callback supplied to awaitDialog() might have thrown.
250 */
251 virtual bool waitEndDialog(sal_uInt64 nTimeoutMs = 3000) = 0;
252 };
253
254 /**
255 * @brief Helper to call user code when a given dialog opens
256 * @param name The title of the dialog window to wait for
257 * @param callback The user code to run when the given dialog opens
258 * @param bAutoClose Whether to automatically cancel the dialog after the user code finished, if
259 * the dialog is still there. You should leave this to @c true unless you
260 * know exactly what you are doing, see below.
261 * @returns A @c DialogWaiter wrapper on which call waitEndDialog() after having triggered the
262 * dialog in some way.
263 *
264 * This function makes it fairly easy and safe to execute code once a dialog pops up:
265 * @code
266 * auto waiter = awaitDialog(u"Special Characters", [this](Dialog &dialog) {
267 * // for example, something like this:
268 * // something();
269 * // CPPUNIT_ASSERT(dialog.tabTo(...));
270 * // CPPUNIT_ASSERT(somethingElse);
271 * // dialog.postKeyEventAsync(0, awt::Key::RETURN);
272 * });
273 * CPPUNIT_ASSERT(activateMenuItem(u"Some menu", u"Some Item Triggering a Dialog..."));
274 * CPPUNIT_ASSERT(waiter->waitEndDialog());
275 * @endcode
276 *
277 * @note The user code might actually be executed before DialogWaiter::waitEndDialog() is
278 * called. It is actually likely to be called at the time the call that triggers the
279 * dialog happens. However, as letting an exception slip in a event handler is likely to
280 * cause problems, exceptions are forwarded to the DialogWaiter::waitEndDialog() call.
281 * However, note that you cannot rely on something like this:
282 * @code
283 * int foo = 0;
284 * auto waiter = awaitDialog(u"Some Dialog", [&foo](Dialog&) {
285 * CPPUNIT_ASSERT_EQUAL(1, foo);
286 * });
287 * CPPUNIT_ASSERT(activateMenuItem(u"Some menu", u"Some Item Triggering a Dialog..."));
288 * foo = 1; // here, the callback likely already ran as a result of the
289 * // Scheduler::ProcessEventsToIdle() call that activateMenuItem() did.
290 * CPPUNIT_ASSERT(waiter->waitEndDialog());
291 * @endcode
292 *
293 * @warning You should almost certainly always leave @p bAutoClose to @c true. If it is set to
294 * @c false, you have to take extreme care:
295 * - The dialog will not be canceled if the user code raises an exception.
296 * - If the dialog is run through Dialog::Execute(), control won't return to the test
297 * body until the dialog is closed. This means that the only ways to execute code
298 * until then is a separate thread or via code dispatched by the main loop.
299 * Thus, you have to make sure you DO close the dialog some way or another yourself
300 * in order for the test code to terminate at some point.
301 * - If the dialog doesn't use Dialog::Execute() but is rather similar to a second
302 * separate window (e.g. non-modal), you might still have to close the dialog before
303 * closing the test document is possible without a CloseVetoException -- which might
304 * badly break the test run.
305 */
306 static std::shared_ptr<DialogWaiter> awaitDialog(const std::u16string_view name,
307 std::function<void(Dialog&)> callback,
308 bool bAutoClose = true);
309 #endif //defined(MACOSX)
310
311 public:
312 virtual void setUp() override;
313 virtual void tearDown() override;
314 };
315 }
316
317 /* vim:set shiftwidth=4 softtabstop=4 expandtab cinoptions=b1,g0,N-s cinkeys+=0=break: */