Метод IAccessible::accNavigate (oleacc.h)

Статья
08/25/2023

Метод IAccessible::accNavigate выполняет переход к другому элементу пользовательского интерфейса в контейнере и извлекает объект . Этот метод является необязательным.

Примечание Метод accNavigate не рекомендуется использовать. Клиенты должны использовать другие методы и свойства, такие как AccessibleChildren, get_accChild, get_accParent и IEnumVARIANT.

Синтаксис

HRESULT accNavigate(
  [in]          long    navDir,
  [in]          VARIANT varStart,
  [out, retval] VARIANT *pvarEndUpAt
);

Параметры

[in] navDir

Тип: long

Указывает направление навигации. Это направление находится в пространственном порядке, например влево или вправо, или в логическом порядке, например в следующем или предыдущем. Это значение является одной из констант навигации.

[in] varStart

Тип: VARIANT

Указывает, является ли начальным объектом навигации сам объект или один из дочерних объектов объекта. Этот параметр является либо CHILDID_SELF (для начала с объекта), либо является дочерним идентификатором (для запуска из одного из дочерних элементов объекта). Дополнительные сведения об инициализации VARIANT см. в разделе Использование дочерних идентификаторов в параметрах.

[out, retval] pvarEndUpAt

Тип: VARIANT*

[out, retval] Адрес структуры VARIANT , которая получает сведения о целевом объекте. В следующей таблице описаны сведения, возвращаемые в pvarEnd.

Член vt	Элемент value
VT_EMPTY	Нет. В указанном направлении не было элемента пользовательского интерфейса.
VT_I4	lVal содержит дочерний идентификатор элемента пользовательского интерфейса.
VT_DISPATCH	pdispVal содержит адрес IDispatch элемента пользовательского интерфейса.

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

Тип: HRESULT

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

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

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

Навигация, как пространственная, так и логическая, всегда ограничена элементами пользовательского интерфейса в контейнере. При пространственной навигации клиенты переходют только к элементу, который имеет одноуровневый элемент начального объекта (varStart). В зависимости от флага навигации, используемого с логической навигацией, клиенты переходить либо к дочернему объекту, либо к одноуровневой части начального объекта.

Метод accNavigate извлекает элементы пользовательского интерфейса с определенным расположением экрана и невидимые объекты, не имеющие определенного расположения экрана.

Этот метод не изменяет выделение или фокус. Чтобы изменить фокус или выбрать объект, используйте IAccessible::accSelect.

Чтобы предотвратить циклическое переключение при обходе элементов экрана, accNavigate возвращает S_FALSE с VT_EMPTY при указании NAVDIR_NEXT в последнем элементе или NAVDIR_PREVIOUS в первом элементе.

Как и в случае с другими методами и функциями IAccess , клиенты могут получать ошибки для указателей интерфейса IAccess из-за действия пользователя. Дополнительные сведения см. в разделе Получение ошибок для указателей интерфейса IAccessible.

Некоторые системные элементы пользовательского интерфейса, такие как меню, пункты меню и всплывающие меню, позволяют переходить к невидимым объектам. Однако другие системные элементы пользовательского интерфейса не поддерживают эту функцию. Серверы могут выбирать, следует ли поддерживать переход к невидимым объектам, и могут пропускать или предоставлять их.

Клиентские приложения должны возвращать возвращаемые значения после процесса при использовании accNavigate для навигации между объектами. Цель этапов постобработки — предоставить клиентам указатель интерфейса IAccess и дочерний идентификатор, чтобы они могли использовать методы и свойства IAccess для элемента пользовательского интерфейса.

В следующих таблицах описаны возможные сценарии для IAccessible::accNavigate на основе следующих критериев:

Определенная отправная точка (независимо от того, начинаете ли вы с полного объекта или простого элемента);
Возвращенный результат ( IDispatch или идентификатор дочернего VT_I4)
Постобработка, которую должны выполнять клиентские приложения, чтобы иметь указатель интерфейса IAccessible и идентификатор дочернего элемента.

Для этих таблиц предположим, что startID и endID являются VT_I4 дочерними идентификаторами (простыми элементами), а pStartAcc и pEndAcc — VT_I4 с CHILDID_SELF (полными объектами).

В этой таблице описаны следующие NAVDIR_ флаги: NEXT, PREVIOUS, LEFT, RIGHT, UP и DOWN. Дополнительные сведения о флагах навигации см. в разделе Константы навигации.

Начальная точка	Возвращен результат	Постобработка возвращаемого значения
pStartAcc, startID	VT_I4 endID	Вызовите get_accChildдля pStartAcc, передав endID. Следуйте обычным процедурам, описанным в get_accChild.
pStartAcc, startID	VT_DISPATCH pEndAcc	Используйте стандартные процедуры для преобразования указателя интерфейса IDispatch в указатель интерфейса IAccessible для pEndAcc.
pStartAcc, CHILDID_SELF	VT_I4 endID	Вызовите get_accParentв pStartAcc, передав CHILDID_SELF, чтобы получить указатель интерфейса IAccessible родительского элемента для endID. Затем вызовите get_accChild для указателя интерфейса IAccessible , передав endID. Следуйте обычным процедурам, описанным в get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Используйте стандартные процедуры для преобразования указателя интерфейса IDispatch в указатель интерфейса IAccessible для pEndAcc.

В следующей таблице описаны флаги навигации NAVDIR_FIRSTCHILD и NAVDIR_LASTCHILD. Он не включает записи для перехода к первому или последнему дочернему элементу, когда начальная точка является простым элементом, так как простые элементы не могут иметь дочерних элементов.

Начальная точка	Возвращен результат	Постобработка возвращаемого значения
pStartAcc, CHILDID_SELF	VT_I4 endID	Вызовите get_accChildв pStartAcc, передав endID. Следуйте обычным процедурам, описанным в get_accChild.
pStartAcc, CHILDID_SELF	VT_DISPATCH pEndAcc	Используйте стандартные процедуры для преобразования указателя интерфейса IDispatch в указатель интерфейса IAccessible для pEndAcc.

Дополнительные сведения см. в разделе Свойства и методы навигации по объектам.

Пример сервера

В следующем примере показана возможная реализация метода для настраиваемого списка, элементы которого являются дочерними элементами.


// m_pControl is the control that returns this accessible object. 
// m_pStdAccessibleObject is the standard accessible object for the window 
//    that contains the control. 

HRESULT STDMETHODCALLTYPE AccServer::accNavigate( 
    long navDir,
    VARIANT varStart,
    VARIANT *pvarEndUpAt)
{
    // Default value. 
    pvarEndUpAt->vt = VT_EMPTY;

    if (varStart.vt != VT_I4)
    {
        return E_INVALIDARG;
    }

    switch (navDir)
    {
    case NAVDIR_FIRSTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = 1;
        }
        else  // Starting with child. 
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_LASTCHILD:
        if (varStart.lVal == CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = m_pControl->GetCount();
        }
        else  // Starting with child.           
        {
            return S_FALSE;
        }
        break;

    case NAVDIR_NEXT:   
    case NAVDIR_DOWN:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal + 1;
            // Out of range. 
            if (pvarEndUpAt->lVal > m_pControl->GetCount())
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

    case NAVDIR_PREVIOUS:
    case NAVDIR_UP:
        if (varStart.lVal != CHILDID_SELF)
        {
            pvarEndUpAt->vt = VT_I4;
            pvarEndUpAt->lVal = varStart.lVal - 1;
            // Out of range. 
            if (pvarEndUpAt->lVal <1)
            {
                pvarEndUpAt->vt = VT_EMPTY;
                return S_FALSE;
            }
        }
        else  // Call through to method on standard object. 
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        break;

     // Unsupported directions. 
    case NAVDIR_LEFT:
    case NAVDIR_RIGHT:
        if (varStart.lVal == CHILDID_SELF)
        {
            return m_pStdAccessibleObject->accNavigate(navDir, varStart, pvarEndUpAt);
        }
        else 
        {
            pvarEndUpAt->vt = VT_EMPTY;
            return S_FALSE;
        }
        break;
    }
    return S_OK;
};

Требования

Требование	Значение
Минимальная версия клиента	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