IAccessible：：accHitTest 方法 (oleacc.h)

项目
03/08/2023

IAccessible：：accHitTest 方法检索在屏幕上特定点显示的子元素或子对象。所有视觉对象都支持此方法，但声音对象不支持。客户端应用程序很少直接调用此方法;若要获取一个点显示的可访问对象，请使用在内部调用此方法的 AccessibleObjectFromPoint 函数。

语法

HRESULT accHitTest(
  [in]          long    xLeft,
  [in]          long    yTop,
  [out, retval] VARIANT *pvarChild
);

参数

[in] xLeft

类型： long

指定已测试的点的屏幕坐标。 x 坐标从左到右增加。请注意，使用屏幕坐标时，原点为屏幕左上角。

[in] yTop

类型： long

指定已测试的点的屏幕坐标。 y 坐标从上到下增加。请注意，使用屏幕坐标时，原点为屏幕左上角。

[out, retval] pvarChild

类型： VARIANT*

[out， retval] VARIANT 的地址，用于标识 xLeft 和 yTop 指定的点中显示的对象。 pvarID 中返回的信息取决于与调用 accHitTest 方法的对象相关的指定点的位置。

点位置	vt 成员	值成员
在对象的边界之外，以及对象边界矩形内部或外部。	VT_EMPTY	无。
在对象中，但不在子元素或子对象内。	VT_I4	lVal CHILDID_SELF。
在子元素中。	VT_I4	lVal 包含子 ID。
在子对象中。	VT_DISPATCH	pdispVal 设置为子对象的 IDispatch 接口指针

返回值

类型： HRESULT

如果成功，则返回 S_OK。

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

错误	说明
S_FALSE	该点不在对象的边界之外。 pvarID 的 vt 成员VT_EMPTY。
DISP_E_MEMBERNOTFOUND	对象不支持此方法。
E_INVALIDARG	自变量无效。

向客户端开发人员记下： 尽管服务器在 pvarID 的 vt 成员VT_EMPTY时返回S_FALSE，但客户端还必须处理 pvarID-vt> VT_EMPTY且返回值S_OK的情况。

注解

如果测试点位于某个对象的子级上，并且此子级支持 IAccessible 接口本身，则此方法应返回 IAccessible 接口指针。但是，应准备好客户端来处理 IAccessible 接口指针或子 ID。有关详细信息，请参阅参数中使用子 ID 的方式。

由于 accLocation 返回边界矩形，因此该矩形中的所有点都位于对象的实际边界内。边界矩形中的某些点可能不在对象上。对于非矩形对象，例如在大型图标模式下的列表视图项，其中单个项具有图标的矩形，而图标文本的另一个矩形则为 IAccessible：：accLocation 检索到的对象边界矩形的坐标（如果通过 accHitTest 进行测试）可能会失败。

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

在某些情况下使用此方法时，会应用其他使用说明。有关详细信息，请参阅 “通过命中测试和屏幕位置导航”。

服务器示例

以下示例代码显示了自定义列表框的可能实现。


// m_pControl is the control that returns this accessible object. 
// m_hwnd is the HWND of the control window. 
//  
HRESULT STDMETHODCALLTYPE AccServer::accHitTest( 
    long xLeft,
    long yTop,
    VARIANT *pvarChild) 

{
    POINT pt;
    pt.x = xLeft;
    pt.y = yTop;

    // Not in our window. 
    if (WindowFromPoint(pt) != m_hwnd)
    {
        pvarChild->vt = VT_EMPTY;
        return S_FALSE;
    }

    else  // In our window; return list item, or self if in blank space. 
    {
        pvarChild->vt = VT_I4;
        ScreenToClient(m_hwnd, &pt);
        // IndexFromY returns the 0-based index of the item at that point, 
        // or -1 if the point is not on any item.
        int index = m_pControl->IndexFromY(pt.y);
        if (index >= 0)
        {
            // Increment, because the child array is 1-based. 
            pvarChild->lVal = index + 1;
        }
        else
        {
            pvarChild->lVal = CHILDID_SELF;

        }
        return S_OK;
    }
};

客户端示例

以下示例函数在 pAcc 所表示列表的屏幕上的指定点选择该项。假定需要单个选择。


HRESULT SelectItemAtPoint(IAccessible* pAcc, POINT point)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    VARIANT varChild;

    HRESULT hr = pAcc->accHitTest(point.x, point.y, &varChild);        
    if ((hr == S_OK) && (varChild.lVal != CHILDID_SELF))
    {
        return pAcc->accSelect((SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION), varChild);
    }
    return S_FALSE;
}

要求


最低受支持的客户端	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