#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

cUntilCallback	Callback condition
nTimeoutMs	Maximum 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

Definition at line 183 of file AccessibilityTools.hxx.

References x.

Referenced by test::AccessibleTestBase::dumpA11YTree(), and test::AccessibleEventPosterHelper::setWindow().

◆ 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

Referenced by test::SwAccessibleTestBase::getAllChildren().

◆ 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

xCtx	An accessible context object to start the search from
role	The role of the object to look up.
name	The 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.

AccessibilityTools::getAccessibleObjectForName(

css::accessibility::AccessibleRole::PUSH_BUTTON, u"Insert");

AccessibilityTools::getAccessibleObjectForName

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.

Definition: AccessibilityTools.cxx:94

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

xCtx	An accessible context to start the search from.
role	The role of the first ancestor to match.
name	The name of the first ancestor to match.
Ts...args	Additional 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:

AccessibilityTools::getAccessibleObjectForName(
    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

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

◆ 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

Referenced by test::AccessibleTestBase::activateMenuItem(), and getAccessibleObjectForRole().

◆ 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

xCtx	A XAccessibleContext on which compare the name
name	The string to compare to

Returns: true if xCtx name matches name.

This is conceptually equivalent to

xCtx->getAccessibleName() == name

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

nTimeoutMs Time 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:

Static Public Member Functions

Static Public Attributes

Static Private Member Functions

Detailed Description

Member Function Documentation

◆ Await()

◆ debugAccessibleStateSet()

◆ debugName() [1/5]

◆ debugName() [2/5]

◆ debugName() [3/5]

◆ debugName() [4/5]

◆ debugName() [5/5]

◆ debugString() [1/4]

◆ debugString() [2/4]

◆ debugString() [3/4]

◆ debugString() [4/4]

◆ equals() [1/2]

◆ equals() [2/2]

◆ getAccessibleObjectForName() [1/4]

◆ getAccessibleObjectForName() [2/4]

◆ getAccessibleObjectForName() [3/4]

◆ getAccessibleObjectForName() [4/4]

◆ getAccessibleObjectForPredicate() [1/2]

◆ getAccessibleObjectForPredicate() [2/2]

◆ getAccessibleObjectForRole() [1/2]

◆ getAccessibleObjectForRole() [2/2]

◆ getEventIdName()

◆ getRelationTypeName()

◆ getRoleName()

◆ nameEquals() [1/2]

◆ nameEquals() [2/2]

◆ Wait()

Member Data Documentation

◆ MAX_CHILDREN