IAccessible


The IAccessible interface is the heart of Active Accessibility. Applications provide this Component Object Model (COM) interface on behalf of user interface elements.

The IAccessible interface methods can be organized into the following groups.
Navigation and Hierarchy IAccessible::accNavigate
IAccessible::get_accChild
IAccessible::get_accParent
Property Access IAccessible::accLocation
IAccessible::get_accChildCount
IAccessible::get_accDefaultAction
IAccessible::get_accDescription
IAccessible::get_accHelp
IAccessible::get_accHelpTopic
IAccessible::get_accKeyboardShortcut
IAccessible::get_accName
IAccessible::get_accRole
IAccessible::get_accState
IAccessible::get_accValue
IAccessible::put_accName
IAccessible::put_accValue
Selection and Focus IAccessible::accSelect
IAccessible::get_accFocus
IAccessible::get_accSelection
Miscellaneous IAccessible::accHitTest
IAccessible::accDoDefaultAction

IAccessible::accDoDefaultAction

HRESULT accDoDefaultAction(VARIANT varChild);

Performs the object's default action.

varChild
[in] Value identifying the child whose default action will be invoked. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

You can retrieve the object's DefaultAction property by using the IAccessible::get_accDefaultAction method.

Only controls that perform actions support IAccessible::accDoDefaultAction. Some controls, like edit fields, can have a primary value but not a primary action.

In most cases, the client could also perform this action using standard OLE Automation, as well as carry out any nondefault actions supported by the object. However, this method provides an easy way to identify and perform an object's most commonly used function. Also, with the information provided by the IAccessible::get_accDefaultAction method, you can describe the action to the user even if the application does not ship an OLE Automation type library.

IAccessible::accHitTest

HRESULT accHitTest(long xLeft, long yTop,
    VARIANT * pvarChild);

Retrieves the child object at a given point on the screen.

xLeft and yTop
[in] Screen coordinates of the point to be hit tested.
pvarChild
[out, retval] Address of a VARIANT structure that will contain information describing the child object at the point specified by the xLeft and yTop parameters, if any. If the specified point exists outside the current object's boundaries, the VARIANT structure's vt member is VT_EMPTY. If the point exists within the current object but not within a child object, the vt member is VT_I4 and the lVal member is CHILDID_SELF. Otherwise, the vt member is VT_DISPATCH and the child object's IDispatch interface pointer is set in the pdispVal member.

When this method is used in certain situations, additional usage notes apply. For more information, see Object Navigation.

Note to implementers: This method must not fail for visual objects. Instead, set the vt member of the VARIANT structure to VT_EMPTY. Currently, the only nonvisual objects are sound objects.

See also VARIANT Structure, IDispatch Interface

IAccessible::accLocation

HRESULT accLocation(long * pxLeft, long * pyTop,
    long * pcxWidth, long * pcyHeight, VARIANT varChild);

Retrieves the object's current screen location (if the object was placed on the screen) and optionally, the child element.

pxLeft and pyTop
[out] Specifies the x- and y-coordinates of the upper left boundary of the object's location.
pcxWidth and pcyHeight
[out] Value specifying the object's width and height, in pixels.
varChild
[in] Value identifying the child whose location will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

This method retrieves the object's bounding rectangle. If the object is a region, then this method returns the biggest rectangle encompassing the entire region.

Note to implementers: This method must not fail for visual objects. The only nonvisual objects are sound objects.

IAccessible::accNavigate

HRESULT accNavigate(long navDir,
    VARIANT varStartFromChildOrSelf, VARIANT * pvarEndUpAt);

Retrieves the next or previous sibling or child object in a specified direction.

navDir
[in] Value specifying the direction in which to move. This direction can be in spatial order (such as left or right) or navigational order (such as next or previous). This value is one of the Navigation Constants.
varStartFromChildOrSelf
[in] VARIANT structure that specifies the type of navigation desired. If the vt member is VT_EMPTY, the method retrieves a sibling object. If the vt member is VT_I4 and the lVal member is CHILDID_SELF, the method retrieves a child object.
pvarEndUpAt
[out, retval] Address of a VARIANT structure that will contain information about the destination object. If the vt member is VT_DISPATCH, then the pdispVal member is the address of the destination object's IDispatch interface. If the vt member is VT_I4, then the lVal member is the object ID. If vt is VT_EMPTY, then the call failed.

This method retrieves only objects that have a defined screen location. However, the object might be currently clipped or obscured by another object. This method does not change selection or focus. To change focus to or select an object, use the IAccessible::accSelect method. For more information see, Object Navigation.

The NAVDIR_NEXT and NAVDIR_PREVIOUS values will not cause looping. The method will return S_FALSE, after the last or first object is found.

Note to implementers: If the current object does not have any knowledge of peer objects, it should ask its parent object to perform the navigation. If the current object does not have any knowledge of its parent, it should return S_FALSE. Client applications using accNavigate should be aware that the return value they get back may not have been provided by the object itself. For example, if a client asks Object A to navigate to the next object (Object B), Object A may ask its parent to do the navigation. In that case, the client must direct any future queries about Object B (i.e. accLocation) to the parent of Object A (by calling ObjectA.get_accParent) or to Object B itself (by calling ObjectA.get_accParent() and then ParentObject.get_accChild(ChildB). The client will be able to tell that this is necessary if: * The accNavigate call started with the varStart VARIANT set to type = VT_I4 and lVal = CHILDID_SELF (0). * The VARIANT filled in by the accNavigate call (pvarEndUpAt) also has type = VT_I4.

Active Accessibility does not always support navigation to invisible children. Remember that it is OK for an object to support the IAccessible::accNavigate and IAccessible::get_accChild methods for children that are invisible, but that clients cannot expect this. In the section where the proxies are implemented, that menus, menu items, and menu popups allow navigation to invisible children, but that other objects that Active Accessibility proxies may not. You might not be able to navigate to all of an object's children, if they have the flag STATE_SYSTEM_INVISIBLE.

See also VARIANT Structure, IDispatch Interface

IAccessible::accSelect

HRESULT accSelect(long flagsSelect, VARIANT varChild);

Modifies the selection or moves the keyboard focus according to the specified flags.

flagsSelect
[in] Value specifying how to change the current selection. This parameter can be a combination of the values from the SELFLAG enumerated type.
varChild
[in] Value identifying the child that will be selected. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

If the selection can't be placed at the requested location, the server fails the call and returns S_FALSE.

Applications can use this method to perform complex selection operations. For more information, see Selecting Child Objects.

IAccessible::get_accChild

HRESULT get_accChild(VARIANT varChild, IDispatch** ppdispChild);

Retrieves an IDispatch interface address of the child object that has the given child ID or name.

varChild
[in] VARIANT structure that identifies the child to be retrieved. This parameter can be the child ID value (provided by the object) or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
ppdispChild
[out, retval] Address of a pointer variable that will contain the address of the child object's IDispatch interface.

This is the only IAccessible method that fails if the application cannot create an OLE object for the child element being referenced.

Note to implementers: If a container object does not support the IEnumVARIANT interface, its child ID numbers must be sequential positive integers starting with 1. If the object supports IEnumVARIANT, then it can use any method to assign its child ID numbers.

Note to implementers: If a VT_EMPTY is passed in, then an E_INVALIDARG can be returned, while get_accName and get_accRole get passed with VT_EMPTY, the application will get back valid results.

See also IAccessible::get_accParent, Object Navigation, VARIANT Structure, IDispatch Interface, Object and Child Identifiers

IAccessible::get_accChildCount

HRESULT get_accChildCount(long* pcountChildren);

Retrieves the number of children belonging to the current object.

pcountChildren
[out, retval] Address of a variable that will contain the number of child objects belonging to this object. The children can be separate objects or child elements. If the object has no children, this value will be zero.

The number of children in an object can change. An application should watch for EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY events generated by the current object to keep track of possible child count updates.

The children of this object might or might not be objects themselves.

Note to implementers: This method must not fail if no child objects exist. Instead, return S_OK and set the variable at pcountChildren to zero.

IAccessible::get_accDefaultAction

HRESULT get_accDefaultAction(VARIANT varChild,
    BSTR* pszDefaultAction);

Retrieves a string containing a localized sentence that describes the object's default action.

varChild
[in] VARIANT structure that identifies the child whose default action will be retrieved. This parameter can contain the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
pszDefaultAction
[out, retval] Address of a BSTR variable that will contain a string describing the default action for this object, or NULL if this object has no default action.

The retrieved string describes the action that is performed on an object, not what the object does as a result. That is, a toolbar button that prints a document would have a default action of "Press" rather than "Prints the current document." Also, do not confuse an object's default action with its value. For more information, see DefaultAction Property.

Only controls that perform actions support this method.

Note to implementers: Localize the string returned from this property.

See also VARIANT Structure

IAccessible::get_accDescription

HRESULT get_accDescription(VARIANT varChild,
    BSTR* pszDescription);

Retrieves a string containing a sentence that describes the current object.

varChild
[in] Value identifying the child whose description will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
pszDescription
[out, retval] Address of a BSTR variable that will contain the string describing the specified object.

The object description conveys the object's visual appearance to the user. Visual information is key for graphical objects, like toolbar buttons or images. However, the vendor ultimately determines the level of detail provided. For more information about this property, see Description Property.

Note to implementers: Localize this property.

IAccessible::get_accFocus

HRESULT get_accFocus(VARIANT * pvarChild);

Retrieves the child object that currently has the keyboard focus.

pvarChild
[out, retval] Address of a VARIANT structure that will contain information about the retrieved child. If the current object does not contain an object that has keyboard focus, then the vt member is VT_EMPTY. If vt is VT_DISPATCH, then the pdispVal member is the address of the child object's IDispatch interface. If vt is VT_I4, then the lVal member is the child ID.

Only one object or item within a container can have the focus at any one time. The object with the keyboard focus is not necessarily the selected object.

Note to implementers: If the object itself has the keyboard focus, return zero as a VT_I4 type. If a child is an accessible object and has the focus, return the address of its IDispatch interface (a VT_DISPATCH type). Or, if a child has the focus but isn't an accessible object, return the child ID to the child as a VT_I4 type.

See also Accessible Object Selection and Focus, IDispatch Interface

IAccessible::get_accHelp

HRESULT get_accHelp(VARIANT varChild, BSTR * pszHelp);

Retrieves an object's Help property string.

varChild
[in] VARIANT structure that identifies the child whose default action will be retrieved. This parameter can contain the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszHelp
[out, retval] Address of a BSTR variable that will contain the Help property string for the specified object, or NULL if no Help string is available.

An object's Help property is represented in the form of a string that provides some helpful text to associate with the specified object. You can use this helpful text to provide a description of what the object does; contrast this with the Description property, which describes what an object looks like.

Note to implementers: Objects need not support both the IAccessible::get_accHelp and IAccessible::get_accHelpTopic functions, but should support at least one. That is, if they can easily return a string they should support get_accHelp, otherwise they should support get_accHelpTopic. If both are supported, the object need not yield identical information.

Localize this property.

Developers of both servers and clients should be aware that getting information from a Help file might be expensive in terms of time and memory.

See also VARIANT Structure

IAccessible::get_accHelpTopic

HRESULT get_accHelpTopic(BSTR * pszHelpFile,
    VARIANT varChild, long * pidTopic);

Retrieves the full path of the Help file associated with the specified object, as well as the address of the appropriate topic within that file.

pszHelpFile
[out] Address of a BSTR variable that will contain a string describing the fully qualified path of the Help file associated with the specified object, if any.
varChild
[in] VARIANT structure identifying the child whose Help information will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pidTopic
[out, retval] Address of a value identifying the Help file topic associated with the object. This value is used as the "context identifier" to the desired topic.

Note to implementers: Do not localize the string returned from this property.

See also HelpTopic Property

IAccessible::get_accKeyboardShortcut

HRESULT get_accKeyboardShortcut(VARIANT varChild,
    BSTR * pszKeyboardShortcut);

Retrieves an object's KeyboardShortcut property.

varChild
[in] VARIANT structure identifying the child whose keyboard shortcut will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszKeyboardShortcut
[out, retval] Address of a BSTR variable that will contain the keyboard shortcut string, or NULL if no keyboard shortcut is associated with this item.

Note to implementers: Do not localize the string returned from this property.

See also VARIANT Structure

IAccessible::get_accName

HRESULT get_accName(VARIANT varChild, BSTR* pszName);

Retrieves the Name property for this object.

varChild
[in] VARIANT structure identifying the child whose name will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszName
[out, retval] Address of a string containing this object's name.

Note to implementers: If you are using menu or button text for the Name property, strip any ampersands (&) marking keyboard access keys; the information they convey can be provided to the client in response to IAccessible::get_accKeyboardShortcut calls.

Do not localize the string returned from this property.

See also IAccessible::put_accName, VARIANT Structure

IAccessible::get_accParent

HRESULT get_accParent(IDispatch** ppdispParent);

Retrieves the IDispatch interface of the current object's parent.

ppdispParent
[out, retval] Address of a variable that will contain the parent object's IDispatch interface. The variable will be set to NULL if no parent exists or the child cannot access its parent.

Note to implementers: This method must not fail if no parent object exists. Instead, return S_FALSE and set the variable at ppdispParent to NULL.

See also IAccessible::get_accChild, Object Navigation, IDispatch Interface

IAccessible::get_accRole

HRESULT get_accRole(VARIANT varChild, VARIANT * pvarRole);

Retrieves the object's Role property.

varChild
[in] VARIANT structure that identifies the child whose role will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pvarRole
[out, retval] Address of a VARIANT structure that will contain a role constant or a string describing the object's role. If the vt member is VT_I4 , then the lVal member contains the standard role constant. If vt is VT_BSTR, then the bstrVal member contains the description string.

Note to implementers: This method must not fail if no role text exists. Instead, return S_OK and set the vt member of the VARIANT structure at pvarRole to VT_EMPTY. All objects should have a role and role text.

Do not localize the string returned from this property.

See also VARIANT Structure

IAccessible::get_accSelection

HRESULT get_accSelection(VARIANT * pvarChildren);

Retrieves the selected children of this object.

pvarChildren
[out, retval] Address of a VARIANT structure that will contain information about the child object or objects. The vt member will be set to one of the following values, indicating the call's result.
VT_DISPATCH One child was selected and the address of its IDispatch interface is set in the pdispVal member.
VT_EMPTY No objects were selected.
VT_I4 One object was selected. The child ID is set in the lVal member. If lVal is CHILDID_SELF, then the object itself had no children but was selected.
VT_UNKNOWN Multiple objects were selected and the punkVal member contains the address of the IUnknown interface. The client can query this interface for the IEnumVARIANT interface, which it can use to enumerate the selected objects.

Note to implementers: If the object has no children, but is itself selected, set the vt member to VT_I4 and lVal to CHILDID_SELF. If no child is selected, set vt to VT_EMPTY. If multiple children are selected, set vt to VT_UNKNOWN and punkVal to the IUnknown interface pointer of an object that can be used to enumerate the child objects. This object must support the IEnumVARIANT interface.

See also Retrieving Selected Objects and Children, VARIANT Structure, IDispatch Interface

IAccessible::get_accState

HRESULT get_accState(VARIANT varChild,
    VARIANT * pvarState);

Retrieves the current state of the object or child item.

varChild
[in] VARIANT structure identifying the child whose state will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pvarState
[out, retval] VARIANT structure that will contain information describing the object's state. If the vt member is VT_I4, then the lVal member is one or more of the object state constants. If vt is VT_BSTR, then the bstrVal member contains a string describing the object's state.

Note to implementers: Localize the string returned from this property.

It is recommended that you avoid using a string to identify the child; because if the object uses strings, it prevents the use of the default states. It is not recommended that you use this string functionality.

See also State Property, VARIANT Structure

IAccessible::get_accValue

HRESULT get_accValue(VARIANT varChild, BSTR* pszValue);

Retrieves the object's Value property.

varChild
[in] VARIANT structure identifying the child whose value will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszValue
[out, retval] Address of a variable that will contain a localized string containing the object's current value.

See also IAccessible::put_accValue

IAccessible::put_accName

HRESULT put_accName(VARIANT varChild, BSTR szName);

Sets the Name property for this object.

varChild
[in] Value identifying the child whose name will be set. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
szName
[in] String that specifies the name to be associated with this item.

See also IAccessible::get_accName

IAccessible::put_accValue

HRESULT put_accValue(VARIANT varChild, BSTR szValue);

Sets the value of the object's Value property for the current item.

varChild
[in] VARIANT structure identifying the child whose state will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
szValue
[in] String containing the value to assign to the object.

See also VARIANT Structure, IAccessible::get_accValue

© 1997 Microsoft Corporation. All rights reserved. Legal Notices.