IAccessible::accNavigate 메서드(oleacc.h)

  • 아티클

IAccessible::accNavigate 메서드는 컨테이너 내의 다른 UI 요소로 트래버스하고 개체를 검색합니다. 이 메서드는 선택 사항입니다.

참고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(개체에서 시작) 또는 자식 ID(개체의 자식 요소 중 하나에서 시작)입니다. VARIANT를 초기화하는 방법에 대한 자세한 내용은 매개 변수에서 자식 ID를 사용하는 방법을 참조하세요.

[out, retval] pvarEndUpAt

형식: VARIANT*

[out, retval] 대상 개체에 대한 정보를 수신하는 VARIANT 구조체의 주소입니다. 다음 표에서는 pvarEnd에서 반환되는 정보를 설명합니다.

vt 멤버 값 멤버
VT_EMPTY
 없음 지정된 방향에 UI 요소가 없습니다.
VT_I4
 lVal 에는 UI 요소의 자식 ID가 포함됩니다.
VT_DISPATCH
 pdispVal 에는 UI 요소의 IDispatch 주소가 포함되어 있습니다.

반환 값

형식: HRESULT

성공하면 S_OK를 반환합니다.

성공하지 못하면 다음 테이블의 값 중 하나 또는 다른 표준 COM 오류 코드를 반환합니다. 서버는 이러한 값을 반환하지만 클라이언트는 항상 출력 매개 변수를 검사 유효한 값을 포함해야 합니다. 자세한 내용은 IAccessible 반환 값 및 반환 값 확인을 참조하세요.

오류 Description
S_FALSE
 지정된 방향으로 화면 요소를 찾을 수 없습니다.
DISP_E_MEMBERNOTFOUND
 개체는 이 메서드를 지원하지 않습니다.
E_INVALIDARG
 인수가 잘못된 경우.

설명

공간 및 논리적 탐색은 항상 컨테이너 내의 UI 요소로 제한됩니다. 공간 탐색을 사용하면 클라이언트는 시작 개체(varStart)의 형제로만 이동합니다. 논리 탐색에 사용되는 탐색 플래그에 따라 클라이언트는 자식 또는 시작 개체의 형제로 이동합니다.

accNavigate 메서드는 정의된 화면 위치가 있는 UI 요소와 정의된 화면 위치가 없는 보이지 않는 개체를 검색합니다.

이 메서드는 선택 영역이나 포커스를 변경하지 않습니다. 포커스를 변경하거나 개체를 선택하려면 IAccessible::accSelect를 사용합니다.

화면 요소를 트래버스할 때 반복을 방지하기 위해 accNavigate 는 마지막 요소에 NAVDIR_NEXT 지정하거나 첫 번째 요소에 NAVDIR_PREVIOUS 때 VT_EMPTY S_FALSE 반환합니다.

다른 IAccessible 메서드 및 함수와 마찬가지로 클라이언트는 사용자 작업으로 인해 IAccessible 인터페이스 포인터에 대한 오류를 수신할 수 있습니다. 자세한 내용은 IAccessible 인터페이스 포인터에 대한 오류 수신을 참조하세요.

메뉴, 메뉴 항목 및 팝업 메뉴와 같은 일부 시스템 정의 UI 요소는 보이지 않는 개체로의 탐색을 허용합니다. 그러나 다른 시스템 정의 UI 요소는 이를 지원하지 않습니다. 서버는 보이지 않는 개체로의 탐색을 지원할지 여부를 선택할 수 있으며 건너뛰거나 노출할 수 있습니다.

클라이언트 애플리케이션은 accNavigate 를 사용하여 개체 간을 탐색할 때 프로세스 후 반환 값을 반환해야 합니다. 사후 처리 단계의 목표는 클라이언트가 UI 요소에 대해 IAccessible 메서드 및 속성을 사용할 수 있도록 IAccessible 인터페이스 포인터 및 자식 ID를 제공하는 것입니다.

다음 표에서는 다음 조건에 따라 IAccessible::accNavigate에 대한 가능한 시나리오를 설명합니다.

  • 정의된 시작점(전체 개체 또는 단순 요소로 시작하는지 여부)
  • 반환된 결과( IDispatch 또는 VT_I4 자식 ID)
  • IAccessible 인터페이스 포인터와 자식 ID를 갖기 위해 클라이언트 애플리케이션이 수행해야 하는 사후 처리
이러한 테이블의 경우 startID 및 endID 가 자식 ID(단순 요소)를 VT_I4 pStartAcc 및 pEndAcc 가 CHILDID_SELF(전체 개체)로 VT_I4 가정합니다.

이 표에서는 NEXT, PREVIOUS, LEFT, RIGHT, UP 및 DOWN과 같은 NAVDIR_ 플래그에 대해 설명합니다. 탐색 플래그에 대한 자세한 내용은 탐색 상수를 참조하세요.

시작 지점 반환된 결과 반환 값에 대한 사후 처리
pStartAcc, startID endID VT_I4 pStartAcc통과 endID에서 get_accChild 호출합니다. get_accChild 설명된 일반적인 절차를 따릅니다.
pStartAcc, startID VT_DISPATCH pEndAcc IDispatch 인터페이스 포인터를 pEndAcc에 대한 IAccessible 인터페이스 포인터로 변환하기 위한 표준 절차를 사용합니다.
pStartAcc, CHILDID_SELF endID VT_I4 pStartAcc에서 get_accParent 호출하고 CHILDID_SELF 전달하여 endID에 대한 부모의 IAccessible 인터페이스 포인터를 가져옵니다. 그런 다음, 해당 IAccessible 인터페이스 포인터에서 get_accChild 호출하여 endID를 전달합니다. get_accChild 설명된 일반적인 절차를 따릅니다.
pStartAcc, CHILDID_SELF VT_DISPATCH pEndAcc IDispatch 인터페이스 포인터를 pEndAcc에 대한 IAccessible 인터페이스 포인터로 변환하기 위한 표준 절차를 사용합니다.
 

다음 표에서는 탐색 플래그 NAVDIR_FIRSTCHILD 및 NAVDIR_LASTCHILD 설명합니다. 단순 요소에 자식이 있을 수 없으므로 시작점이 단순 요소인 경우 첫 번째 또는 마지막 자식으로 탐색하기 위한 항목은 포함되지 않습니다.

시작 지점 반환된 결과 반환 값에 대한 사후 처리
pStartAcc, CHILDID_SELF endID VT_I4 pStartAcc에서 get_accChild 호출하고 endID를 전달합니다. get_accChild 설명된 일반적인 절차를 따릅니다.
pStartAcc, CHILDID_SELF VT_DISPATCH pEndAcc IDispatch 인터페이스 포인터를 pEndAcc에 대한 IAccessible 인터페이스 포인터로 변환하기 위한 표준 절차를 사용합니다.
 

자세한 내용은 개체 탐색 속성 및 메서드를 참조하세요.

서버 예제

다음 예제에서는 목록 항목이 자식 요소인 사용자 지정 목록 상자에 대한 메서드의 가능한 구현을 보여줍니다. 

// 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
헤더 oleacc.h
라이브러리 Oleacc.lib
DLL Oleacc.dll
재배포 가능 파일 SP6 이상 및 Windows 95를 Windows NT 4.0의 활성 접근성 1.3 RDK

추가 정보

IAccessible

IAccessible::accSelect

IDispatch

개체 탐색 속성 및 메서드

변형