IAccessible：：accNavigate 方法 (oleacc.h)

  • 项目

IAccessible：：accNavigate 方法遍历到容器中的另一个 UI 元素并检索对象。 此方法是可选的。

注意accNavigate 方法已弃用，不应使用。 客户端应使用其他方法和属性，例如 AccessibleChildren、 get_accChild、 get_accParent 和 IEnumVARIANT。
 

语法

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

参数

[in] navDir

类型： long

指定导航方向。 此方向按 空间 顺序（如左或右）或 逻辑 顺序（例如下一个或上一个）。 此值是 导航常量之一。

[in] varStart

类型： VARIANT

指定导航的起始对象是对象本身还是对象的子对象之一。 此参数CHILDID_SELF (从对象) 启动，或者子 ID (从对象的子元素之一) 开始。 有关初始化 VARIANT 的详细信息，请参阅 如何在参数中使用子 ID。

[out, retval] pvarEndUpAt

类型： VARIANT*

[out， retval]接收有关目标对象的信息的 VARIANT 结构的地址。 下表描述了 pvarEnd 中返回的信息。

vt 成员 值成员
VT_EMPTY
 无。 指定方向上没有 UI 元素。
VT_I4
 lVal 包含 UI 元素的子 ID。
VT_DISPATCH
 pdispVal 包含 UI 元素的 IDispatch 的地址。

返回值

类型： HRESULT

如果成功，则返回 S_OK。

如果未成功，则返回下表中的值之一或另一个标准 COM 错误代码。 服务器返回这些值，但客户端必须始终检查输出参数，以确保它们包含有效值。 有关详细信息，请参阅 检查 I 可访问的返回值 和返回值。

错误 说明
S_FALSE
 未在指定方向上找到屏幕元素。
DISP_E_MEMBERNOTFOUND
 对象不支持此方法。
E_INVALIDARG
 自变量无效。

注解

导航（空间和逻辑）始终仅限于容器中的 UI 元素。 使用空间导航，客户端仅导航到开始对象的同级对象 (varStart) 。 根据用于逻辑导航的导航标志，客户端导航到起始对象的子级或同级。

accNavigate 方法检索具有定义的屏幕位置的 UI 元素，以及没有定义屏幕位置的不可见对象。

此方法不会更改所选内容或焦点。 若要更改焦点或选择对象，请使用 IAccessible：：accSelect。

为了防止遍历屏幕元素时循环， accNavigate 在最后一个元素上指定NAVDIR_NEXT或在第一个元素上指定 NAVDIR_PREVIOUS 时返回VT_EMPTY S_FALSE 。

与其他 IAccessible 方法和函数一样，由于用户操作，客户端可能会收到 IAccessible 接口指针的错误。 有关详细信息，请参阅 接收 IAccessible 接口指针的错误。

某些系统定义的 UI 元素（如菜单、菜单项和弹出菜单）允许导航到不可见的对象。 但是，其他系统定义的 UI 元素不支持此功能。 服务器可以选择是否支持导航到不可见对象，并且可以跳过或公开它们。

使用 accNavigate 在对象之间导航时，客户端应用程序必须返回后处理返回值。 后期处理步骤的目的是为客户端提供 IAccessible 接口指针和子 ID，以便他们可以使用 UI 元素的 IAccessible 方法和属性。

下表根据以下条件描述了 IAccessible：：accNavigate 的可能方案：

  • 定义的起点 (是从完整对象还是简单元素开始)
  • 返回的结果 (IDispatch 或VT_I4子 ID)
  • 客户端应用程序需要执行的后处理才能获得 IAccessible 接口指针和子 ID
对于这些表，假设 startID 和 endID 是VT_I4子 ID (简单元素) ，pStartAcc 和 pEndAcc 是VT_I4 CHILDID_SELF (完整的对象) 。

下表描述了以下NAVDIR_标志：NEXT、PREVIOUS、LEFT、RIGHT、UP 和 DOWN。 有关导航标志的详细信息，请参阅 导航常量。

起点 返回的结果 返回值的后处理
pStartAcc，startID VT_I4 endID 在 pStartAcc 上调用 get_accChild passing endID。 遵循 get_accChild 中所述的常规过程。
pStartAcc，startID VT_DISPATCH pEndAcc 使用标准过程将 IDispatch 接口指针转换为 pEndAcc 的 IAccessible 接口指针。
pStartAcc、CHILDID_SELF VT_I4 endID 在 pStartAcc 上调用get_accParent，传递CHILDID_SELF以获取 endID 父级的 IAccessible 接口指针。 然后，在该 IAccessible 接口指针上调用get_accChild，传递 endID。 遵循 get_accChild 中所述的常规过程。
pStartAcc、CHILDID_SELF VT_DISPATCH pEndAcc 使用标准过程将 IDispatch 接口指针转换为 pEndAcc 的 IAccessible 接口指针。
 

下表介绍了 导航标志NAVDIR_FIRSTCHILD 和 NAVDIR_LASTCHILD。 当起始点为简单元素时，它不包括用于导航到第一个或最后一个子元素的条目，因为简单元素不能具有子元素。

起点 返回的结果 返回值的后处理
pStartAcc、CHILDID_SELF VT_I4 endID 在 pStartAcc 上调用 get_accChild，传递 endID。 遵循 get_accChild 中所述的常规过程。
pStartAcc、CHILDID_SELF VT_DISPATCH pEndAcc 使用标准过程将 IDispatch 接口指针转换为 pEndAcc 的 IAccessible 接口指针。
 

有关详细信息，请参阅 对象导航属性和方法。

服务器示例

以下示例演示了自定义列表框方法的可能实现，该自定义列表框的列表项是子元素。 

// 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;
};

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
目标平台 Windows
标头 oleacc.h
Library Oleacc.lib
DLL Oleacc.dll
可再发行组件 具有 SP6 及更高版本和 Windows 95 的 Windows NT 4.0 上的活动辅助功能 1.3 RDK

另请参阅

IAccessible

IAccessible：：accSelect

IDispatch

对象导航属性和方法

VARIANT