IAccessible::accHitTest

Article
03/28/2008

The IAccessible::accHitTest method retrieves the child element or child object at a given point on the screen. All visual objects support this method; sound objects do not support it.

For more information about COM parameter attributes, allocating memory, and freeing memory, see Definitions of Parameter Attributes.

HRESULT accHitTest(
longxLeft, longyTop,VARIANT*pvarID);

Parameters

xLeft and yTop
[in] Specifies the physical screen coordinates of the point hit tested. When using screen coordinates, note that the origin is the upper-left corner of the screen. The x coordinates increase from left to right; the y coordinates increase from top to bottom.

pvarID
[out, retval] Address of a VARIANT structure that identifies the object at the point specified by xLeft and yTop. The information returned in pvarID depends on the location of the specified point in relation to the object whose accHitTest method is being called.

Point location	vt member	Value member
Outside of the object's boundaries, and either inside or outside of the object's bounding rectangle	VT_EMPTY	None
Within the object but not within a child element or a child object	VT_I4	lVal is CHILDID_SELF.
Within a child element	VT_I4	lVal contains the child ID.
Within a child object	VT_DISPATCH	pdispVal is set to the child object's IDispatch interface pointer.

Return Values

If successful, returns S_OK.

If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error	Description
S_FALSE	The point is outside of the object's boundaries. The vt member of pvarID is VT_EMPTY.
DISP_E_MEMBERNOTFOUND	The object does not support this method.
E_INVALIDARG	An argument is invalid.

Note to client developers Although servers return S_FALSE if the vt member of pvarID is VT_EMPTY, clients must also handle the case where pvarID->vt is VT_EMPTY and the return value is S_OK.

Remarks

If the tested point is on one of the object's children, and this child supports the IAccessible interface itself, this method should return an IAccessible interface pointer. However, clients should be prepared to handle an IAccessible interface pointer or a child ID. For more information, see How Child IDs Are Used in Parameters.

Because accLocation returns a bounding rectangle, not all points in that rectangle will be within the actual bounds of the object. Some points within the bounding rectangle may not be on the object. For non-rectangular objects, such as list view items in large-icon mode where a single item has a rectangle for the icon and another rectangle for the text of the icon, the coordinates of the object's bounding rectangle retrieved by IAccessible::accLocation could fail if tested with accHitTest.

As with other IAccessible methods and functions, clients might receive errors for IAccessible interface pointers because of a user action. For more information, see Receiving Errors for IAccessible Interface Pointers.

When this method is used in certain situations, additional usage notes apply. For more information, see Navigation Through Hit Testing and Screen Location.

Server Example

The following example code shows a possible implementation for a custom list box.

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

Client Example

The following example function selects the item at a specified point on the screen within the list represented by pAcc. It is assumed that a single selection is wanted.

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

Requirements

**  Windows NT/2000/XP/Server 2003:** Included in Windows 2000 and later.
**  Windows 95/98/Me:** Included in Windows 98 and later.
**  Redistributable:** Requires Active Accessibility 1.3 RDK on Windows NT 4.0 SP6 and Windows 95.
**  Header:** Declared in Oleacc.h.
**  Library:** Use Oleacc.lib.

Partager via