include/test/a11y/AccessibilityTools.hxx

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