Метод 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 содержит идентификатор дочернего элемента.
В дочернем объекте.	VT_DISPATCH	pdispVal задается для указателя интерфейса IDispatch дочернего объекта.

Возвращаемое значение

Тип: HRESULT

Возвращает значение S_OK, если операция завершилась успешно.

В случае успеха возвращает одно из значений в следующей таблице или другой стандартный код ошибки COM. Серверы возвращают эти значения, но клиенты должны всегда проверка выходные параметры, чтобы убедиться, что они содержат допустимые значения. Дополнительные сведения см. в разделе Проверка возвращаемых значений IAccessible.

Ошибка	Описание
S_FALSE	Точка находится за пределами объекта . Элемент vtpvarID — VT_EMPTY.
DISP_E_MEMBERNOTFOUND	Объект не поддерживает этот метод.
E_INVALIDARG	Аргумент является недопустимым.

Примечание для разработчиков клиентов: Хотя серверы возвращают S_FALSE, если член vtpvarID является VT_EMPTY, клиенты также должны обрабатывать случай, когда pvarID-vt> является VT_EMPTY, а возвращаемое значение — S_OK.

Если проверяемая точка находится на одном из дочерних элементов объекта и этот дочерний элемент поддерживает сам интерфейс IAccessible , этот метод должен возвращать указатель интерфейса IAccessible . Однако клиенты должны быть готовы к обработке указателя интерфейса IAccess или дочернего идентификатора. Дополнительные сведения см. в разделе Использование дочерних идентификаторов в параметрах.

Так как accLocation возвращает ограничивающий прямоугольник, не все точки в этом прямоугольнике будут находиться в пределах фактических границ объекта . Некоторые точки в ограничивающем прямоугольнике могут не находиться в объекте . Для непрямоугольных объектов, таких как элементы представления списка в режиме больших значков, где один элемент имеет прямоугольник для значка и другой прямоугольник для текста значка, координаты ограничивающего прямоугольника объекта, полученного методом IAccessible::accLocation , могут завершиться ошибкой при тестировании с помощью accHitTest .

Как и в случае с другими методами и функциями IAccess , клиенты могут получать ошибки для указателей интерфейса IAccess из-за действия пользователя. Дополнительные сведения см. в разделе Получение ошибок для указателей интерфейса 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
Header	oleacc.h
Библиотека	Oleacc.lib
DLL	Oleacc.dll
Распространяемые компоненты	Активные специальные возможности 1.3 RDK в Windows NT 4.0 с пакетом обновления 6 (SP6) и более поздних версий и Windows 95