IAccessible2

Please add a summary to this article.
1.0
66
Introduced
Gecko 1.9
Inherits from: IAccessible Last changed in Gecko 1.9 (Firefox 3)

Method overview

[propget] HRESULT attributes([out] BSTR attributes );
[propget] HRESULT extendedRole([out] BSTR extendedRole );
[propget] HRESULT extendedStates([in] long maxExtendedStates, [out, size_is(,maxExtendedStates), length_is(, nExtendedStates)] BSTR extendedStates, [out] long nExtendedStates );
[propget] HRESULT groupPosition([out] long groupLevel, [out] long similarItemsInGroup, [out] long positionInGroup );
[propget] HRESULT indexInParent([out] long indexInParent );
[propget] HRESULT locale([out] IA2Locale locale );
[propget] HRESULT localizedExtendedRole([out] BSTR localizedExtendedRole );
[propget] HRESULT localizedExtendedStates([in] long maxLocalizedExtendedStates, [out, size_is(,maxLocalizedExtendedStates), length_is(, nLocalizedExtendedStates)] BSTR localizedExtendedStates, [out] long nLocalizedExtendedStates );
[propget] HRESULT nExtendedStates([out] long nExtendedStates );
[propget] HRESULT nRelations([out] long nRelations );
[propget] HRESULT relation([in] long relationIndex, [out] IAccessibleRelation relation );
[propget] HRESULT relations([in] long maxRelations, [out, size_is(maxRelations), length_is( nRelations)] IAccessibleRelation relations, [out] long nRelations );
HRESULT role([out] long role );
HRESULT scrollTo([in] enum IA2ScrollType scrollType );
HRESULT scrollToPoint([in] enum IA2CoordinateType coordinateType, [in] long x, [in] long y );
[propget] HRESULT states([out] AccessibleStates states );
[propget] HRESULT uniqueID([out] long uniqueID );
[propget] HRESULT windowHandle([out] HWND windowHandle );

Methods

attributes()

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

[propget] HRESULT attributes(
  [out] BSTR attributes
);
Parameters
attributes
Return value

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

extendedRole()

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.

[propget] HRESULT extendedRole(
  [out] BSTR extendedRole
);
Parameters
extendedRole
Return value

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

extendedStates()

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.

[propget] HRESULT extendedStates(
  [in] long maxExtendedStates,
  [out, size_is(,maxExtendedStates), length_is(, nExtendedStates)] BSTR extendedStates,
  [out] long nExtendedStates
);
Parameters
maxExtendedStates
This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
extendedStates
This array is allocated by the server. Free it with CoTaskMemFree.
nExtendedStates
The number of extended states returned; the size of the returned array.
Return value

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

groupPosition()

Returns grouping information. Used for tree items, list items, tab panel labels, radio buttons, and so on. Also used for collections of non-text objects.

[propget] HRESULT groupPosition(
  [out] long groupLevel,
  [out] long similarItemsInGroup,
  [out] long positionInGroup
);
Parameters
groupLevel
1 based, 0 indicates that this value is not applicable.
similarItemsInGroup
1 based, 0 indicates that this value is not applicable.
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 value

S_FALSE if no values are valid. S_OK if at least one value is valid.

indexInParent()

Returns the index of this object in its parent object.

[propget] HRESULT indexInParent(
  [out] long indexInParent
);
Parameters
indexInParent
0 based; -1 indicates there is no parent; the upper bound is the value returned by the parent's IAccessible::get_accChildCount.
Return value

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

locale()

Returns the IA2Locale of the accessible object.

[propget] HRESULT locale(
  [out] IA2Locale locale
);
Parameters
locale
Return value

S_OK.

localizedExtendedRole()

Returns the localized extended role.

[propget] HRESULT localizedExtendedRole(
  [out] BSTR localizedExtendedRole
);
Parameters
localizedExtendedRole
Return value

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

localizedExtendedStates()

Returns the localized extended states() (array of strings).

[propget] HRESULT localizedExtendedStates(
  [in] long maxLocalizedExtendedStates,
  [out, size_is(,maxLocalizedExtendedStates), length_is(, nLocalizedExtendedStates)] BSTR localizedExtendedStates,
  [out] long nLocalizedExtendedStates
);
Parameters
maxLocalizedExtendedStates
This parameter is ignored. Refer to @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
localizedExtendedStates
This array is allocated by the server. Free it with CoTaskMemFree.
nLocalizedExtendedStates
The number of localized extended states returned; the size of the returned array.
Return value

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

nExtendedStates()

Returns the number of extended states.

[propget] HRESULT nExtendedStates(
  [out] long nExtendedStates
);
Parameters
nExtendedStates
Return value

S_OK.

nRelations()

Returns the number of accessible relations for this object.

[propget] HRESULT nRelations(
  [out] long nRelations
);
Parameters
nRelations
Return value

S_OK.

relation()

Returns one accessible relation for this object.

[propget] HRESULT relation(
  [in] long relationIndex,
  [out] IAccessibleRelation relation
);
Parameters
relationIndex
0 based.
relation
Return value

E_INVALIDARG if bad [in] passed, [out] value is null. S_OK.

relations()

Returns multiple accessible relations for this object.

[propget] HRESULT relations(
  [in] long maxRelations,
  [out, size_is(maxRelations), length_is( nRelations)] IAccessibleRelation relations,
  [out] long nRelations
);
Parameters
maxRelations
Maximum size of the array allocated by the client.
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 @ref _arrayConsideration "Special Consideration when using Arrays" for more details.
nRelations
Actual number of relations in the returned array (not more than maxRelations)
Return value

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

role()

Returns the role of an IAccessible2 object.

HRESULT role(
  [out] long role
);
Parameters
role
The role of an IAccessible2 object.
Return value

S_OK.

scrollTo()

Makes an object visible on the screen.

HRESULT scrollTo(
  [in] enum IA2ScrollType scrollType
);
Parameters
scrollType
Defines where the object should be placed on the screen.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

scrollToPoint()

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

HRESULT scrollToPoint(
  [in] enum IA2CoordinateType coordinateType,
  [in] long x,
  [in] long y
);
Parameters
coordinateType
Specifies whether the coordinates are relative to the screen or the parent object.
x
Defines the x coordinate.
y
Defines the y coordinate.
Return value

E_INVALIDARG if bad [in] passed. S_OK.

states()

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.

[propget] HRESULT states(
  [out] AccessibleStates states
);
Parameters
states
Return value

S_OK.

uniqueID()

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, for example 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.
[propget] HRESULT uniqueID(
  [out] long uniqueID
);
Parameters
uniqueID
Return value

S_OK.

windowHandle()

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.

[propget] HRESULT windowHandle(
  [out] HWND windowHandle
);
Parameters
windowHandle
Return value

S_OK.

Remarks

When you have a reference to an IAccessible and require a reference to an IAccessible2 use QueryService as follows:

// pAcc is a reference to the accessible object's IAccessible interface.
IServiceProvider *pService = NULL;
hr = pAcc->QueryInterface(IID_IServiceProvider, (void **)&pService);
if(SUCCEEDED(hr)) {
  IAccessible2 *pIA2 = NULL;
  hr = pService->QueryService(IID_IAccessible, IID_IAccessible2, (void**)&pIA2);
  if (SUCCEEDED(hr) && pIA2) {
    // The control supports IAccessible2.
    // pIA2 is the reference to the accessible object's IAccessible2 interface.
  }
}

See also