IAccessible::accNavigate

[This is preliminary documentation and subject to change.]

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

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

Parameters

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.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

Remarks

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