IAccessible2

Method overview

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

• IAccessible