LibreOffice Module test (master) 1
Static Public Member Functions | Static Public Attributes | Static Private Member Functions | List of all members
AccessibilityTools Class Reference

#include <AccessibilityTools.hxx>

Static Public Member Functions

static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForPredicate (const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, const std::function< bool(const css::uno::Reference< css::accessibility::XAccessibleContext > &)> &cPredicate)
 
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForPredicate (const css::uno::Reference< css::accessibility::XAccessible > &xAcc, const std::function< bool(const css::uno::Reference< css::accessibility::XAccessibleContext > &)> &cPredicate)
 
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForRole (const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, sal_Int16 role)
 
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForRole (const css::uno::Reference< css::accessibility::XAccessible > &xacc, sal_Int16 role)
 
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForName (const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, const sal_Int16 role, std::u16string_view name)
 Gets a descendant of xCtx (or xCtx itself) that matches the given role and name. More...
 
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForName (const css::uno::Reference< css::accessibility::XAccessible > &xAcc, const sal_Int16 role, std::u16string_view name)
 
template<typename... Ts>
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForName (const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, const sal_Int16 role, std::u16string_view name, Ts... args)
 Gets a descendant of xCtx (or xCtx itself) that matches the last given role and name pair, and has ancestors matching the leading pairs in the given order. More...
 
template<typename... Ts>
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForName (const css::uno::Reference< css::accessibility::XAccessible > &xAcc, const sal_Int16 role, std::u16string_view name, Ts... args)
 
static bool equals (const css::uno::Reference< css::accessibility::XAccessible > &xacc1, const css::uno::Reference< css::accessibility::XAccessible > &xacc2)
 
static bool equals (const css::uno::Reference< css::accessibility::XAccessibleContext > &xctx1, const css::uno::Reference< css::accessibility::XAccessibleContext > &xctx2)
 
static bool nameEquals (const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, const std::u16string_view name)
 Compares the accessible name against a string. More...
 
static bool nameEquals (const css::uno::Reference< css::accessibility::XAccessible > &xAcc, const std::u16string_view name)
 
static OUString getRoleName (const sal_Int16 role)
 
static OUString getEventIdName (const sal_Int16 event_id)
 
static OUString getRelationTypeName (const sal_Int16 rel_type)
 
template<typename T >
static std::string debugString (const css::uno::Reference< T > &x)
 
template<typename T >
static std::string debugString (const T &x)
 
template<typename T >
static std::string debugString (const T *p)
 
template<typename T >
static std::string debugString (T *p)
 
static OUString debugAccessibleStateSet (sal_Int64 p)
 
static bool Await (const std::function< bool()> &cUntilCallback, sal_uInt64 nTimeoutMs=3000)
 Process events until a condition or a timeout. More...
 
static void Wait (sal_uInt64 nTimeoutMs)
 Process events for a given time. More...
 

Static Public Attributes

static const sal_Int32 MAX_CHILDREN = 500
 Maximum number of children to work on. More...
 

Static Private Member Functions

static OUString debugName (css::accessibility::XAccessibleContext *xctx)
 
static OUString debugName (css::accessibility::XAccessible *xacc)
 
static OUString debugName (const css::accessibility::AccessibleEventObject *evobj)
 
static OUString debugName (css::accessibility::XAccessibleAction *xAct)
 
static OUString debugName (css::accessibility::XAccessibleText *xTxt)
 

Detailed Description

Definition at line 35 of file AccessibilityTools.hxx.

Member Function Documentation

◆ Await()

bool AccessibilityTools::Await ( const std::function< bool()> &  cUntilCallback,
sal_uInt64  nTimeoutMs = 3000 
)
static

Process events until a condition or a timeout.

Parameters
cUntilCallbackCallback condition
nTimeoutMsMaximum time in ms to wait for condition
Returns
true if the condition was met, or false if the timeout has been reached.

Processes events until idle, and either until the given condition becomes true or a timeout is reached.

This is similar to Scheduler::ProcessEventsToIdle() but awaits a condition up to a timeout. This is useful if the waited-on condition might happen after the first idle time. The timeout helps in case the condition is not satisfied in reasonable time.

cUntilCallback is called each time the scheduler reaches idle to check whether the condition is met.

Example:

ProcessEvents([&]() { return taskHasRun; });
See also
Scheduler::ProcessEventsToIdle()

Definition at line 716 of file AccessibilityTools.cxx.

References Task::IsActive(), Scheduler::ProcessEventsToIdle(), SAL_WARN_IF, Timer::SetTimeout(), and Timer::Start().

◆ debugAccessibleStateSet()

OUString AccessibilityTools::debugAccessibleStateSet ( sal_Int64  p)
static

Definition at line 393 of file AccessibilityTools.cxx.

References i, name, and unknownName().

◆ debugName() [1/5]

static OUString AccessibilityTools::debugName ( const css::accessibility::AccessibleEventObject *  evobj)
staticprivate

◆ debugName() [2/5]

static OUString AccessibilityTools::debugName ( css::accessibility::XAccessible *  xacc)
staticprivate

◆ debugName() [3/5]

static OUString AccessibilityTools::debugName ( css::accessibility::XAccessibleAction *  xAct)
staticprivate

◆ debugName() [4/5]

static OUString AccessibilityTools::debugName ( css::accessibility::XAccessibleContext *  xctx)
staticprivate

◆ debugName() [5/5]

static OUString AccessibilityTools::debugName ( css::accessibility::XAccessibleText *  xTxt)
staticprivate

◆ debugString() [1/4]

template<typename T >
static std::string AccessibilityTools::debugString ( const css::uno::Reference< T > &  x)
inlinestatic

◆ debugString() [2/4]

template<typename T >
static std::string AccessibilityTools::debugString ( const T &  x)
inlinestatic

Definition at line 188 of file AccessibilityTools.hxx.

References debugString(), and x.

Referenced by debugString().

◆ debugString() [3/4]

template<typename T >
static std::string AccessibilityTools::debugString ( const T *  p)
inlinestatic

Definition at line 190 of file AccessibilityTools.hxx.

References p.

◆ debugString() [4/4]

template<typename T >
static std::string AccessibilityTools::debugString ( T *  p)
inlinestatic

Definition at line 201 of file AccessibilityTools.hxx.

References p.

◆ equals() [1/2]

static bool AccessibilityTools::equals ( const css::uno::Reference< css::accessibility::XAccessible > &  xacc1,
const css::uno::Reference< css::accessibility::XAccessible > &  xacc2 
)
static

◆ equals() [2/2]

static bool AccessibilityTools::equals ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xctx1,
const css::uno::Reference< css::accessibility::XAccessibleContext > &  xctx2 
)
static

◆ getAccessibleObjectForName() [1/4]

static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForName ( const css::uno::Reference< css::accessibility::XAccessible > &  xAcc,
const sal_Int16  role,
std::u16string_view  name 
)
inlinestatic

Definition at line 76 of file AccessibilityTools.hxx.

References name.

◆ getAccessibleObjectForName() [2/4]

template<typename... Ts>
static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForName ( const css::uno::Reference< css::accessibility::XAccessible > &  xAcc,
const sal_Int16  role,
std::u16string_view  name,
Ts...  args 
)
inlinestatic

Definition at line 149 of file AccessibilityTools.hxx.

References args, and name.

◆ getAccessibleObjectForName() [3/4]

css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForName ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xCtx,
const sal_Int16  role,
std::u16string_view  name 
)
static

Gets a descendant of xCtx (or xCtx itself) that matches the given role and name.

Parameters
xCtxAn accessible context object to start the search from
roleThe role of the object to look up.
nameThe name of the object to look up.
Returns
The found object, or nullptr if not found.

Finds a descendant of xCtx (or xCtx itself) that matches role and name.

css::accessibility::AccessibleRole::PUSH_BUTTON, u"Insert");
static css::uno::Reference< css::accessibility::XAccessibleContext > getAccessibleObjectForName(const css::uno::Reference< css::accessibility::XAccessibleContext > &xCtx, const sal_Int16 role, std::u16string_view name)
Gets a descendant of xCtx (or xCtx itself) that matches the given role and name.
See also
AccessibilityTools::getAccessibleObjectForPredicate()

Definition at line 94 of file AccessibilityTools.cxx.

References getAccessibleObjectForName(), i, MAX_CHILDREN, name, and nameEquals().

Referenced by getAccessibleObjectForName().

◆ getAccessibleObjectForName() [4/4]

template<typename... Ts>
static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForName ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xCtx,
const sal_Int16  role,
std::u16string_view  name,
Ts...  args 
)
inlinestatic

Gets a descendant of xCtx (or xCtx itself) that matches the last given role and name pair, and has ancestors matching the leading pairs in the given order.

Parameters
xCtxAn accessible context to start the search from.
roleThe role of the first ancestor to match.
nameThe name of the first ancestor to match.
Ts...argsAdditional role and name pairs of ancestors, ending with the role and name pair of the target object to match.
Returns
The found object, or nullptr if not found.

Specialized version allowing specifying arbitrary objects on the path to the target one. Not all objects have to be matched, but there have to be ancestors matching in the given order. This is useful to easily solve conflicts if there are more than one possible match.

This can be used to find an "Insert" push button inside a panel named "Some group" for example, as shown below:

css::accessibility::AccessibleRole::PANEL, u"Some group",
css::accessibility::AccessibleRole::PUSH_BUTTON, u"Insert");
Note
This returns the first match in the object tree when walking it depth-first. Depending on the tree, this might not be able to find the expected match, e.g. if there is a first match with intermediate unmatched objects, and the target has the same tree but without intermediate objects that can be used to refine the search and prevent the unwanted tree to match. The same issue arises with two identical trees, yet in that case no walking scenario could solve it automatically anyway. In such situations, a custom getAccessibleObjectForPredicate() call, or successive lookups interleaved with specific child lookups are likely the best solution.
See also
getAccessibleObjectForPredicate().

Definition at line 119 of file AccessibilityTools.hxx.

References args, i, and name.

◆ getAccessibleObjectForPredicate() [1/2]

static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForPredicate ( const css::uno::Reference< css::accessibility::XAccessible > &  xAcc,
const std::function< bool(const css::uno::Reference< css::accessibility::XAccessibleContext > &)> &  cPredicate 
)
static

◆ getAccessibleObjectForPredicate() [2/2]

static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForPredicate ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xCtx,
const std::function< bool(const css::uno::Reference< css::accessibility::XAccessibleContext > &)> &  cPredicate 
)
static

◆ getAccessibleObjectForRole() [1/2]

css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForRole ( const css::uno::Reference< css::accessibility::XAccessible > &  xacc,
sal_Int16  role 
)
static

Definition at line 85 of file AccessibilityTools.cxx.

References getAccessibleObjectForRole().

◆ getAccessibleObjectForRole() [2/2]

static css::uno::Reference< css::accessibility::XAccessibleContext > AccessibilityTools::getAccessibleObjectForRole ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xCtx,
sal_Int16  role 
)
static

◆ getEventIdName()

OUString AccessibilityTools::getEventIdName ( const sal_Int16  event_id)
static

Definition at line 524 of file AccessibilityTools.cxx.

References unknownName().

◆ getRelationTypeName()

OUString AccessibilityTools::getRelationTypeName ( const sal_Int16  rel_type)
static

Definition at line 614 of file AccessibilityTools.cxx.

References unknownName().

Referenced by test::AccessibleTestBase::dumpA11YTree().

◆ getRoleName()

OUString AccessibilityTools::getRoleName ( const sal_Int16  role)
static

Definition at line 211 of file AccessibilityTools.cxx.

References unknownName().

◆ nameEquals() [1/2]

static bool AccessibilityTools::nameEquals ( const css::uno::Reference< css::accessibility::XAccessible > &  xAcc,
const std::u16string_view  name 
)
inlinestatic

Definition at line 173 of file AccessibilityTools.hxx.

References name.

◆ nameEquals() [2/2]

static bool AccessibilityTools::nameEquals ( const css::uno::Reference< css::accessibility::XAccessibleContext > &  xCtx,
const std::u16string_view  name 
)
static

Compares the accessible name against a string.

Parameters
xCtxA XAccessibleContext on which compare the name
nameThe string to compare to
Returns
true if xCtx name matches name.

This is conceptually equivalent to

xCtx->getAccessibleName() == name
const char * name

, but handles the case OSL debugging is active and inserts a type suffix. Unless you know for sure the accessible you are comparing is not subject to those suffixes under debugging, always use this function instead of direct comparison.

Referenced by getAccessibleObjectForName().

◆ Wait()

void AccessibilityTools::Wait ( sal_uInt64  nTimeoutMs)
static

Process events for a given time.

Parameters
nTimeoutMsTime to dispatch events for

Process events for a given time. This can be useful if waiting is in order but there is no actual condition to wait on (e.g. expect something not to happen). This similar in spirit to sleep(nTimeoutMs), but dispatches events during the wait.

This function should be used sparsely because waiting a given time is rarely a good solution for a problem, but in some specific situations there is no better alternative (like, again, waiting for something not to happen).

Definition at line 731 of file AccessibilityTools.cxx.

References Task::IsActive(), Scheduler::ProcessEventsToIdle(), Timer::SetTimeout(), and Timer::Start().

Member Data Documentation

◆ MAX_CHILDREN

const sal_Int32 AccessibilityTools::MAX_CHILDREN = 500
static

Maximum number of children to work on.

This is especially useful for Calc which has a million elements, if not more.

Definition at line 40 of file AccessibilityTools.hxx.

Referenced by getAccessibleObjectForName(), test::AccessibleTestBase::getAllChildren(), and test::SwAccessibleTestBase::getAllChildren().


The documentation for this class was generated from the following files: