Share via

IAccessible::accNavigate

  • Article

The IAccessible::accNavigate method traverses to another user interface (UI) element within a container and retrieves the object. All visual objects must support this method.

For more information on COM parameter attributes, allocating memory, and freeing memory, see Definitions of Parameter Attributes.

HRESULT accNavigate(
  long navDir,
  VARIANT varStart,
  VARIANT* pvarEnd
);

Parameters

  • navDir
    [in] Specifies the direction to navigate. This direction is in spatial order, such as left or right, or logical order, such as next or previous. This value is one of the navigation constants.
  • varStart
    [in] Specifies whether the starting object of the navigation is the object itself or one of the object's children. This parameter is either CHILDID_SELF (to start from the object) or a child ID (to start from one of the object's children). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
  • pvarEnd
    [out, retval] Address of a VARIANT structure that receives information about the destination object. The following table describes the information returned in pvarEnd.
    vt member Value member
    VT_EMPTY None. There wasn't a UI element in the specified direction.
    VT_I4 lVal contains the child ID of the UI element.
    VT_DISPATCH pdispVal contains the address of the UI element's IDispatch interface.

Return Values

If successful, returns S_OK.

If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values andReturn Values.

Error Description
S_FALSE No screen element was found in the specified direction.
DISP_E_MEMBERNOTFOUND The object does not support this method.
E_INVALIDARG An argument is invalid.

Remarks

Navigation, both spatial and logical, is always restricted to the UI elements within a container. With spatial navigation, clients navigate only to a sibling of the starting object (varStart). Depending on the navigational flag used with logical navigation, clients navigate to either a child or to a sibling of the starting object.

The accNavigate method retrieves UI elements that have a defined screen location, and invisible objects that do not have a defined screen location.

This method does not change the selection or focus. To change the focus or to select an object, use IAccessible::accSelect.

To prevent looping when traversing screen elements, accNavigate returns S_FALSE with VT_EMPTY when you specify NAVDIR_NEXT on the last element, or NAVDIR_PREVIOUS on the first element.

As with other IAccessible methods and functions, clients might receive errors for IAccessible interface pointers because of a user action. For more information, see Receiving Errors for IAccessible Interface Pointers.

Some system-defined UI elements such as menus, menu items, and pop-up menus allow navigation to invisible objects. However, other system-defined UI elements do not support this. Servers can choose whether to support navigating to invisible objects and can either skip over or expose them.

Client applications must post-process return values when using accNavigate to navigate between objects. The goal of the post-processing steps is to give clients an IAccessible interface pointer and a child ID so that they can use the IAccessible methods and properties for a UI element.

The following tables describe possible scenarios for IAccessible::accNavigate, based on the following criteria:

  • A defined starting point (whether you are starting with a full object or a simple element)
  • The result returned (an IDispatch or a VT_I4 child ID)
  • The post-processing that client applications will need to perform to have an IAccessible interface pointer and a child ID

For these tables, assume that startID and endID are VT_I4 child IDs (simple elements), and pStartAcc and pEndAcc are VT_I4 with CHILDID_SELF (full objects).

This table describes the following NAVDIR_ flags: NEXT, PREVIOUS, LEFT, RIGHT, UP, and DOWN. For more information about navigation flags, see Navigation Constants.

Starting point Result returned Post-processing for the return value
pStartAcc, startID VT_I4 endID Call get_accChild on pStartAcc passing endID. Follow normal procedures outlined in get_accChild.
pStartAcc, startID VT_DISPATCH pEndAcc Use the standard procedures for converting an IDispatch interface pointer to an IAccessible interface pointer for pEndAcc.
pStartAcc, CHILDID_SELF VT_I4 endID Call get_accParent on pStartAcc, passing CHILDID_SELF to get the IAccessible interface pointer of the parent for endID.

Then, call get_accChild on that IAccessible interface pointer, passing endID. Follow normal procedures outlined in get_accChild.
pStartAcc, CHILDID_SELF VT_DISPATCH pEndAcc Use the standard procedures for converting an IDispatch interface pointer to an IAccessible interface pointer for pEndAcc.

The following table describes navigation flags NAVDIR_FIRSTCHILD and NAVDIR_LASTCHILD. It does not include entries for navigating to a first or last child when the starting point is a simple element because simple elements cannot have children.

Starting point Result returned Post-processing for the return value
pStartAcc, CHILDID_SELF VT_I4 endID Call get_accChild on pStartAcc, passing endID. Follow normal procedures outlined in get_accChild.
pStartAcc, CHILDID_SELF VT_DISPATCH pEndAcc Use the standard procedures for converting an IDispatch interface pointer to an IAccessible interface pointer for pEndAcc.

For more information, see Object Navigation Properties and Methods.

Requirements

**  Windows NT/2000/XP/Server 2003:** Included in Windows 2000 and later.
**  Windows 95/98/Me:** Included in Windows 98 and later.
**  Redistributable:** Requires Active Accessibility 1.3 RDK on Windows NT 4.0 SP6 and Windows 95.
**  Header:** Declared in Oleacc.h.
**  Library:** Use Oleacc.lib.

See Also

VARIANT Structure, IDispatch Interface, IAccessible::accSelect, Object Navigation Properties and Methods