IAccessible2 Interface Reference

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

import "Accessible2.idl";

List of all members.


Public Member Functions

HRESULT nRelations ([out, retval] long *nRelations)
 Returns the number of accessible relations for this object.
HRESULT relation ([in] long relationIndex,[out, retval] IAccessibleRelation **relation)
 Returns one accessible relation for this object.
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.
HRESULT role ([out, retval] long *role)
 Returns the role of an IAccessible2 object.
HRESULT scrollTo ([in] enum IA2ScrollType scrollType)
 Makes an object visible on the screen.
HRESULT scrollToPoint ([in] enum IA2CoordinateType coordinateType,[in] long x,[in] long y)
 Moves the top left of an object to a specified location.
HRESULT groupPosition ([out] long *groupLevel,[out] long *similarItemsInGroup,[out, retval] long *positionInGroup)
 Returns grouping information.
HRESULT states ([out, retval] AccessibleStates *states)
 Returns the bit strip containing any IAccessible2 states.
HRESULT extendedRole ([out, retval] BSTR *extendedRole)
 Returns the extended role.
HRESULT localizedExtendedRole ([out, retval] BSTR *localizedExtendedRole)
 Returns the localized extended role.
HRESULT nExtendedStates ([out, retval] long *nExtendedStates)
 Returns the number of extended states.
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).
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).
HRESULT uniqueID ([out, retval] long *uniqueID)
 Returns the unique ID.
HRESULT windowHandle ([out, retval] HWND *windowHandle)
 Returns the window handle for the parent window which contains this object.
HRESULT indexInParent ([out, retval] long *indexInParent)
 Returns the index of this object in its parent object.
HRESULT locale ([out, retval] IA2Locale *locale)
 Returns the IA2Locale of the accessible object.
HRESULT attributes ([out, retval] BSTR *attributes)
 Returns the attributes specific to this IAccessible2 object, such as a cell's formula.

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 IAccessible2 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. 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. 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

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:
To submit feedback on IAccessible2 API Version 1.2.1, please use the Bugzilla interface located at: http://bugs.linuxfoundation.org/. When using Bugzilla please be sure to select IAccessible2 from the list of components. Bugzilla is the preferred method for receiving feedback because it automatically logs one's feedback in the IAccessible2 tracking system without additional human intervention. One may also, however, send email to accessibility-rfc@a11y.org, a publicly archived emailing list. Please address any technical problems you encounter with this document or the resources to which it links, to the Open A11y Webmaster <webmaster@a11y.org>

A stable online reference version of the documentation for IAccessible2 API Version 1.2.1, is available at: http://a11y.org/ia2-spec. A list of known and reported errors in the documentation for IAccessible2 API Version 1.2.1 can be found at: http://a11y.org/ia2-errata

Generated on Fri Jan 21 14:02:45 2011 for IAccessible2 API Version 1.2.1 by  doxygen 1.5.6