IAccessible：：accHitTest 方法 (oleacc.h)

项目
02/29/2024

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	自变量无效。

客户端开发人员注意： 尽管如果VT_EMPTY pvarID 的 vt 成员，则服务器返回S_FALSE，但客户端还必须处理VT_EMPTY pvarID-vt> 且返回值S_OK的情况。

注解

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

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

与其他 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 上的 Active Accessibility 1.3 RDK