IAccessible::accLocation

Article
03/28/2008

The IAccessible::accLocation method retrieves the specified object's current screen location. All visual objects must support this method; sound objects do not support it.

HRESULT accLocation(
long* pxLeft,long* pyTop, long* pcxWidth,long* pcyHeight,VARIANTvarID);

Parameters

pxLeft and pyTop
[out] Address of the variables that receive the x and y coordinates of the upper-left boundary of the object's location, in physical screen coordinates.
pcxWidth and pcyHeight
[out] Address of the variables that receive the object's width and height, in pixels.
varID
[in] Specifies whether the location that the server returns should be that of the object or that of one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.

Return Values

If successful, returns S_OK. Clients must always check output parameters to ensure that they contain valid values.

If not successful, returns the following value or another standard COM error code. For more information, see Checking IAccessible Return Values.

Error	Description
DISP_E_MEMBERNOTFOUND	The object does not support this method.
E_INVALIDARG	An argument is invalid.

Remarks

This method retrieves the object's bounding rectangle. If the object has a non-rectangular shape, then this method returns the smallest rectangle that completely encompasses the entire object region. For non-rectangular objects, the coordinates of the object's bounding rectangle could fail if tested with IAccessible::accHitTest. Examples of such non-rectangular objects are 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. 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 more information, see Navigation Through Hit Testing and Screen Location.

Note This method returns width and height. If you want the right and bottom coordinates, calculate them using right = left + width, and bottom = top + height.

Server Example

The following example shows a possible implementation of the method for a custom list box whose list items are child elements. For the list box itself, the call is passed to the standard accessible object, which returns the screen coordinates of the window.

// m_pStdAccessibleObject is the standard accessible object for the control window.
// m_pControl is the object that represents the control. Its GetItemRect method 
//   retrieves the screen coordinates of the specified item in a zero-based collection.
//
HRESULT STDMETHODCALLTYPE AccServer::accLocation( 
    long *pxLeft,
    long *pyTop,
    long *pcxWidth,
    long *pcyHeight,
    VARIANT varChild)
{
    *pxLeft = 0;
    *pyTop = 0;
    *pcxWidth = 0;
    *pcyHeight = 0;
    if (varChild.vt != VT_I4)
    {
        return E_INVALIDARG;
    }
    if (varChild.lVal == CHILDID_SELF)
    {
        return m_pStdAccessibleObject->accLocation(pxLeft, pyTop, pcxWidth, pcyHeight, varChild);
    }
    else
    {
        RECT rect;
        if (m_pControl->GetItemRect(varChild.lVal - 1, &rect;) == FALSE)
        {
            return E_INVALIDARG;
        }
        else
        {
            *pxLeft = rect.left;
            *pyTop = rect.top;
            *pcxWidth = rect.right - rect.left;
            *pcyHeight = rect.bottom - rect.top;
            return S_OK;	
        }
    }
};

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.

Share via