IAccessible::accNavigate method (oleacc.h)
The IAccessible::accNavigate method traverses to another UI element within a container and retrieves the object. This method is optional.
Syntax
HRESULT accNavigate(
[in] long navDir,
[in] VARIANT varStart,
[out, retval] VARIANT *pvarEndUpAt
);
Parameters
[in] navDir
Type: long
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.
[in] varStart
Type: VARIANT
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 child elements). For more information about initializing the VARIANT, see How Child IDs Are Used in Parameters.
[out, retval] pvarEndUpAt
Type: VARIANT*
[out, retval] Address of a VARIANT structure that receives information about the destination object. The following table describes the information that is returned in pvarEnd.
| vt member | Value member |
|---|---|
|
None. There was no UI element in the specified direction. |
|
lVal contains the child ID of the UI element. |
|
pdispVal contains the address of the UI element's IDispatch. |
Return value
Type: HRESULT
If successful, returns S_OK.
If not successful, returns one of the values in the table that follows, or another standard COM error code. Servers return these values, but clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values and Return Values.
| Error | Description |
|---|---|
|
No screen element was found in the specified direction. |
|
The object does not support this method. |
|
An argument is not valid. |
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 return 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
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.
Server Example
The following example shows a possible implementation of the method for a custom list box whose list items are child elements.
// m_pControl is the control that returns this accessible object.
// m_pStdAccessibleObject is the standard accessible object for the window
// that contains the control.
HRESULT STDMETHODCALLTYPE AccServer::accNavigate(
long navDir,
VARIANT varStart,
VARIANT *pvarEndUpAt)
{
// Default value.
pvarEndUpAt->vt = VT_EMPTY;
if (varStart.vt != VT_I4)
{
return E_INVALIDARG;
}
switch (navDir)
{
case NAVDIR_FIRSTCHILD:
if (varStart.lVal == CHILDID_SELF)
{
pvarEndUpAt->vt = VT_I4;
pvarEndUpAt->lVal = 1;
}
else // Starting with child.
{
return S_FALSE;
}
break;
case NAVDIR_LASTCHILD:
if (varStart.lVal == CHILDID_SELF)
{
pvarEndUpAt->vt = VT_I4;
pvarEndUpAt->lVal = m_pControl->GetCount();
}
else // Starting with child.
{
return S_FALSE;
}
break;
case NAVDIR_NEXT:
case NAVDIR_DOWN:
if (varStart.lVal != CHILDID_SELF)
{
pvarEndUpAt->vt = VT_I4;
pvarEndUpAt->lVal = varStart.lVal + 1;
// Out of range.
if (pvarEndUpAt->lVal > m_pControl->GetCount())
{
pvarEndUpAt->vt = VT_EMPTY;
return S_FALSE;
}
}
else // Call through to method on standard object.
{
return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
}
break;
case NAVDIR_PREVIOUS:
case NAVDIR_UP:
if (varStart.lVal != CHILDID_SELF)
{
pvarEndUpAt->vt = VT_I4;
pvarEndUpAt->lVal = varStart.lVal - 1;
// Out of range.
if (pvarEndUpAt->lVal <1)
{
pvarEndUpAt->vt = VT_EMPTY;
return S_FALSE;
}
}
else // Call through to method on standard object.
{
return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
}
break;
// Unsupported directions.
case NAVDIR_LEFT:
case NAVDIR_RIGHT:
if (varStart.lVal == CHILDID_SELF)
{
return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
}
else
{
pvarEndUpAt->vt = VT_EMPTY;
return S_FALSE;
}
break;
}
return S_OK;
};
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Target Platform | Windows |
| Header | oleacc.h |
| Library | Oleacc.lib |
| DLL | Oleacc.dll |
| Redistributable | Active Accessibility 1.3 RDK on Windows NT 4.0 with SP6 and later and Windows 95 |