IRawElementProviderFragment::Navigate Method

Retrieves the Microsoft UI Automation element in a specified direction within the UI Automation tree.

Syntax

HRESULT Navigate(      
    NavigateDirection direction,
    IRawElementProviderFragment **pRetVal
);

Parameters

• direction
  [in] A member of the NavigateDirection enumerated type that specifies the direction in which to navigate.
• pRetVal
  [out, retval] The address of a variable that receives a pointer to the IRawElementProviderFragment interface of the UI Automation element in the specified direction, or NULL if there is no element in that direction. This parameter is passed uninitialized.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The UI Automation server's implementations of this method define the structure of the UI Automation tree.

Navigation must be supported upward to the parent, downward to the first and last child, and laterally to the next and previous siblings, as applicable.

Each child node has only one parent and must be placed in the chain of siblings reached from the parent by FirstChild and LastChild.

Relationships among siblings must be identical in both directions: if A is B's PreviousSibling, then B is A's NextSibling. A FirstChild has no PreviousSibling, and a LastChild has no NextSibling.

Fragment roots do not enable navigation to a parent or siblings; navigation among fragment roots is handled by the default window providers. Elements in fragments must navigate only to other elements within that fragment.

Example

The following example shows an implementation for a list item provider. The member variables for the parent, previous sibling, and next sibling providers were initialized when the list was created.

HRESULT STDMETHODCALLTYPE ListItemProvider::Navigate(NavigateDirection direction, IRawElementProviderFragment ** pRetVal)
{
    if (pRetVal == NULL) 
    {
        return E_INVALIDARG;
    }

    IRawElementProviderFragment* pFrag = NULL;
    switch(direction)
    {
        case NavigateDirection_Parent:
            pFrag = (IRawElementProviderFragment*)m_parentProvider;       
            break;

        case NavigateDirection_NextSibling:
            pFrag = (IRawElementProviderFragment*)m_nextSiblingProvider;
            break;

        case NavigateDirection_PreviousSibling:  
            pFrag = (IRawElementProviderFragment*)m_previousSiblingProvider;
            break;
    }
    *pRetVal = pFrag;
    if (pFrag != NULL) 
    {
        pFrag->AddRef();
    }
    return S_OK;
}              

See Also

IRawElementProviderFragment