Export (0) Print
Expand All

IAccessible::accNavigate method

The IAccessible::accNavigate method traverses to another UI element within a container and retrieves the object. This method is optional.

Note  The accNavigate method is deprecated and should not be used. Clients should use other methods and properties such as AccessibleChildren, get_accChild, get_accParent, and IEnumVARIANT.

Syntax


HRESULT accNavigate(
  [in]           long navDir,
  [in]           VARIANT varStart,
  [out, retval]  VARIANT *pvarEnd
);

Parameters

navDir [in]

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.

varStart [in]

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.

pvarEnd [out, retval]

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 memberValue member
VT_EMPTY

None. There was no 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.

 

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.

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

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 pointResult returnedPost-processing for the return value
pStartAcc, startID VT_I4 endIDCall 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 endIDCall 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 pEndAccUse 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 pointResult returnedPost-processing for the return value
pStartAcc, CHILDID_SELF VT_I4 endIDCall get_accChild on pStartAcc, passing endID. Follow normal procedures outlined in get_accChild.
pStartAcc, CHILDID_SELF VT_DISPATCH pEndAccUse 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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Redistributable

Active Accessibility 1.3 RDK on Windows NT 4.0 with SP6 and later and Windows 95

Header

Oleacc.h

Library

Oleacc.lib

DLL

Oleacc.dll

See also

IAccessible
VARIANT
IDispatch
IAccessible::accSelect
Object Navigation Properties and Methods

 

 

Community Additions

ADD
Show:
© 2014 Microsoft