IAccessible2 API: IAccessible2 Interface Reference

This interface exposes the primary set of information about an IAccessible2 enabled accessible object. More...

import "Accessible2.idl";

Inheritance diagram for IAccessible2:

Public Member Functions
HRESULT	nRelations ([out, retval] long *nRelations)
	Returns the number of accessible relations for this object. More...

HRESULT	relation ([in] long relationIndex,[out, retval] IAccessibleRelation **relation)
	Returns one accessible relation for this object. More...

HRESULT	relations ([in] long maxRelations,[out, size_is(maxRelations), length_is(nRelations)] IAccessibleRelation relations,[out, retval] long nRelations)
	Returns multiple accessible relations for this object. More...

HRESULT	role ([out, retval] long *role)
	Returns the role of an IAccessible2 object. More...

HRESULT	scrollTo ([in] enum IA2ScrollType scrollType)
	Makes an object visible on the screen. More...

HRESULT	scrollToPoint ([in] enum IA2CoordinateType coordinateType,[in] long x,[in] long y)
	Moves the top left of an object to a specified location. More...

HRESULT	groupPosition ([out] long groupLevel,[out] long similarItemsInGroup,[out, retval] long *positionInGroup)
	Returns grouping information. More...

HRESULT	states ([out, retval] AccessibleStates *states)
	Returns the bit strip containing any IAccessible2 states. More...

HRESULT	extendedRole ([out, retval] BSTR *extendedRole)
	Returns the extended role. More...

HRESULT	localizedExtendedRole ([out, retval] BSTR *localizedExtendedRole)
	Returns the localized extended role. More...

HRESULT	nExtendedStates ([out, retval] long *nExtendedStates)
	Returns the number of extended states. More...

HRESULT	extendedStates ([in] long maxExtendedStates,[out, size_is(, maxExtendedStates), length_is(,nExtendedStates)] BSTR extendedStates,[out, retval] long nExtendedStates)
	Returns the extended states (array of strings). More...

HRESULT	localizedExtendedStates ([in] long maxLocalizedExtendedStates,[out, size_is(, maxLocalizedExtendedStates), length_is(,nLocalizedExtendedStates)] BSTR localizedExtendedStates,[out, retval] long nLocalizedExtendedStates)
	Returns the localized extended states (array of strings). More...

HRESULT	uniqueID ([out, retval] long *uniqueID)
	Returns the unique ID. More...

HRESULT	windowHandle ([out, retval] HWND *windowHandle)
	Returns the window handle for the parent window which contains this object. More...

HRESULT	indexInParent ([out, retval] long *indexInParent)
	Returns the index of this object in its parent object. More...

HRESULT	locale ([out, retval] IA2Locale *locale)
	Returns the IA2Locale of the accessible object. More...

HRESULT	attributes ([out, retval] BSTR *attributes)
	Returns the attributes specific to this object, such as a cell's formula. More...

Detailed Description

This interface exposes the primary set of information about an IAccessible2 enabled accessible object.

This interface must always be provided for objects that support some portion of the collection of the IAccessible2 interfaces.

Please refer to Changing between Accessible Interfaces for special considerations related to use of the MSAA IAccessible interface and the set of IAccessible2 interfaces.

Member Function Documentation

HRESULT IAccessible2::attributes ( [out, retval] BSTR * attributes )

get

Returns the attributes specific to this object, such as a cell's formula.

Parameters

[out] attributes

Return values

S_OK
S_FALSE	returned if there is nothing to return, [out] value is NULL

HRESULT IAccessible2::extendedRole ( [out, retval] BSTR * extendedRole )

get

Returns the extended role.

An extended role is a role which is dynamically generated by the application. It is not predefined by the IAccessible2 specification.

Parameters

[out] extendedRole

Return values

S_OK
S_FALSE	if there is nothing to return, [out] value is NULL

HRESULT IAccessible2::extendedStates	(	[in] long	maxExtendedStates,
		[out, size_is(, maxExtendedStates), length_is(,nExtendedStates)] BSTR *	extendedStates,
		[out, retval] long *	nExtendedStates
	)

get

Returns the extended states (array of strings).

An extended state is a state which is dynamically generated by the application. It is not predefined by the IAccessible2 specification.

Parameters

[in]	maxExtendedStates	This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out]	extendedStates	This array is allocated by the server. The client must free it with CoTaskMemFree.
[out]	nExtendedStates	The number of extended states returned; the size of the returned array.

Return values

S_OK
S_FALSE	if there are no states, [out] values are NULL and 0 respectively

HRESULT IAccessible2::groupPosition	(	[out] long *	groupLevel,
		[out] long *	similarItemsInGroup,
		[out, retval] long *	positionInGroup
	)

get

Returns grouping information.

Used for tree items, list items, tab panel labels, radio buttons, etc. Also used for collections of non-text objects.

Parameters

[out]	groupLevel	1 based, 0 indicates that this value is not applicable
[out]	similarItemsInGroup	1 based, 0 indicates that this value is not applicable
[out]	positionInGroup	1 based, 0 indicates that this value is not applicable. This is an index into the objects in the current group, not an index into all the objects at the same group level.

Return values

S_OK	if at least one value is valid
S_FALSE	if no values are valid, [out] values are 0s

Note: This method is meant to describe the nature of an object's containment structure. It's exposed by trees, tree grids, nested lists, nested menus, but not headings, which uses the level object attribute. It is also exposed by radio buttons (with groupLevel == 0).; This is normally not implemented on a combo box to describe the nature of its contents. Normally an AT will get that information from its child list object. However, in some cases when non-edit combo boxes are not able to be structured such that the list is a child of the combo box, this method is implemented on the combo box itself. ATs can use this interface if a child list is not found.

HRESULT IAccessible2::indexInParent ( [out, retval] long * indexInParent )

get

Returns the index of this object in its parent object.

Parameters

[out] indexInParent 0 based; -1 indicates there is no parent; the upper bound is the value returned by the parent's IAccessible::get_accChildCount.

Return values

S_OK
S_FALSE	if no parent, [out] value is -1

HRESULT IAccessible2::locale ( [out, retval] IA2Locale * locale )

get

Returns the IA2Locale of the accessible object.

Parameters

[out] locale

Return values

S_OK

HRESULT IAccessible2::localizedExtendedRole ( [out, retval] BSTR * localizedExtendedRole )

get

Returns the localized extended role.

Parameters

[out] localizedExtendedRole

Return values

S_OK
S_FALSE	if there is nothing to return, [out] value is NULL

HRESULT IAccessible2::localizedExtendedStates	(	[in] long	maxLocalizedExtendedStates,
		[out, size_is(, maxLocalizedExtendedStates), length_is(,nLocalizedExtendedStates)] BSTR *	localizedExtendedStates,
		[out, retval] long *	nLocalizedExtendedStates
	)

get

Returns the localized extended states (array of strings).

Parameters

[in]	maxLocalizedExtendedStates	This parameter is ignored. Refer to Special Consideration when using Arrays for more details.
[out]	localizedExtendedStates	This array is allocated by the server. The client must free it with CoTaskMemFree.
[out]	nLocalizedExtendedStates	The number of localized extended states returned; the size of the returned array.

Return values

S_OK
S_FALSE	if there are no states, [out] values are NULL and 0 respectively

HRESULT IAccessible2::nExtendedStates ( [out, retval] long * nExtendedStates )

get

Returns the number of extended states.

Parameters

[out] nExtendedStates

Return values

S_OK

HRESULT IAccessible2::nRelations ( [out, retval] long * nRelations )

get

Returns the number of accessible relations for this object.

Parameters

[out] nRelations

Return values

S_OK

HRESULT IAccessible2::relation	(	[in] long	relationIndex,
		[out, retval] IAccessibleRelation **	relation
	)

get

Returns one accessible relation for this object.

Parameters

[in]	relationIndex	0 based
[out]	relation

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessible2::relations	(	[in] long	maxRelations,
		[out, size_is(maxRelations), length_is(nRelations)] IAccessibleRelation *	relations,
		[out, retval] long *	nRelations
	)

get

Returns multiple accessible relations for this object.

Parameters

[in]	maxRelations	maximum size of the array allocated by the client
[out]	relations	The array of accessible relation objects. Note that this array is to be allocated by the client and freed when no longer needed. Refer to Special Consideration when using Arrays for more details.
[out]	nRelations	actual number of relations in the returned array (not more than maxRelations)

Return values

S_OK
S_FALSE	if there are no relations, nRelations is set to 0

Note: As a performant alternative, client code should consider using IAccessible2_2::relationTargetsOfType.

HRESULT IAccessible2::role ( [out, retval] long * role )

Returns the role of an IAccessible2 object.

Parameters

[out] role The role of an IAccessible2 object.

Return values

S_OK

Note

For convenience MSAA roles are also passed through this method so the AT doesn't have to also fetch roles through MSAA's get_accRole.
IAccessible2 roles should not be passed through MSAA's get_accRole.
For compatibility with non IAccessible2 enabled ATs, IAccessible2 applications should also add support to get_accRole to return the closest MSAA role or ROLE_SYSTEM_CLIENT (the MSAA defined default role) if there is not a good match.
This method is missing a [propget] prefix in the IDL. The result is the method is named role in generated C++ code instead of get_role.

HRESULT IAccessible2::scrollTo ( [in] enum IA2ScrollType scrollType )

Makes an object visible on the screen.

Parameters

[in] scrollType Defines where the object should be placed on the screen.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessible2::scrollToPoint	(	[in] enum IA2CoordinateType	coordinateType,
		[in] long	x,
		[in] long	y
	)

Moves the top left of an object to a specified location.

Parameters

[in]	coordinateType	Specifies whether the coordinates are relative to the screen or the parent object.
[in]	x	Defines the x coordinate.
[in]	y	Defines the y coordinate.

Return values

S_OK
E_INVALIDARG	if bad [in] passed

HRESULT IAccessible2::states ( [out, retval] AccessibleStates * states )

get

Returns the bit strip containing any IAccessible2 states.

The IAccessible2 states are in addition to the MSAA states and are defined in the IA2States enum.

Parameters

[out] states

Return values

S_OK

HRESULT IAccessible2::uniqueID ( [out, retval] long * uniqueID )

get

Returns the unique ID.

The uniqueID is an identifier for this object, is unique within the current window, and remains the same for the lifetime of the accessible object.

The uniqueID is not related to:

the MSAA objectID which is used by the server to disambiguate between IAccessibles per HWND or
the MSAA childID which is used to disambiguate between children being managed by an IAccessible.

This value is provided so the AT can have access to a unique runtime persistent identifier even when not handling an event for the object.

An example of when this value is useful is if the AT wants to build a cache. The AT could cache the uniqueIDs in addition to other data being cached. When an event is fired the AT could map the uniqueID to its internal model. Thus, if there's a REORDER/SHOW/HIDE event the AT knows which part of the internal structure has been invalidated and can refetch just that part.

This value can also be used by an AT to determine when the current control has changed. If the role is the same for two controls that are adjacent in the tab order, this can be used to detect the new control.

Another use of this value by an AT is to identify when a grouping object has changed, e.g. when moving from a radio button in one group to a radio button in a different group.

One means of implementing this would be to create a factory with a 32 bit number generator and a reuse pool. The number generator would emit numbers starting at 1. Each time an object's life cycle ended, its number would be saved into a reuse pool. The number generator would be used whenever the reuse pool was empty.

Another way to create a unique ID is to generate it from a pointer value, e.g. an object's address. That would be unique because no two active objects can use the same allocated memory space.

Parameters

[out] uniqueID

Return values

S_OK

HRESULT IAccessible2::windowHandle ( [out, retval] HWND * windowHandle )

get

Returns the window handle for the parent window which contains this object.

This is the same window handle which will be passed for any events that occur on the object, but is cached in the accessible object for use when it would be helpful to access the window handle in cases where an event isn't fired on this object.

A use case is when a screen reader is grabbing an entire web page on a page load. Without the availability of windowHandle, the AT would have to get the window handle by using WindowFromAccessibleObject on each IAccessible, which is slow because it's implemented by oleacc.dll as a loop which crawls up the ancestor chain and looks for a ROLE_WINDOW object, mapping that back to a window handle.

Parameters

[out] windowHandle

Return values

S_OK

The documentation for this interface was generated from the following file:

Accessible2.idl

Public Member Functions

Detailed Description

Member Function Documentation