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 包含子標識碼。
在子物件內。	VT_DISPATCH	pdispVal 設定為子物件的 IDispatch 介面指標

傳回值

類型： HRESULT

如果成功，則傳回 S_OK。

如果未成功，則傳回下表中的其中一個值，或另一個標準 COM 錯誤碼。伺服器會傳回這些值，但客戶端必須一律檢查輸出參數，以確保它們包含有效的值。如需詳細資訊，請參閱檢查 IAccessible 傳回值。

錯誤	Description
S_FALSE	點超出物件的界限。 pvarID 的 vt 成員VT_EMPTY。
DISP_E_MEMBERNOTFOUND	物件不支援這個方法。
E_INVALIDARG	引數無效。

用戶端開發人員的注意事項： 雖然伺服器S_FALSE如果 pvarID 的 vt 成員VT_EMPTY，用戶端也必須處理 pvarID-vt> VT_EMPTY且傳回值S_OK的情況。

備註

如果測試點位於其中一個物件的子系上，而且這個子系支援 IAccessible 介面本身，這個方法應該會傳回 IAccessible 介面指標。不過，客戶端應該準備好處理 IAccessible 介面指標或子標識碼。如需詳細資訊，請參閱參數中使用子標識符的方式。

因為 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
程式庫	Oleacc.lib
Dll	Oleacc.dll
可轉散發套件	sp6 和更新版本和 Windows 95 Windows NT 4.0 上的 Active Accessibility 1.3 RDK