IAccessible::accHitTest 메서드(oleacc.h)
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] xLeft 및 yTop으로 지정된 지점에 표시되는 개체를 식별하는 VARIANT의 주소입니다. pvarID에서 반환되는 정보는 accHitTest 메서드가 호출되는 개체와 관련하여 지정된 지점의 위치에 따라 달라집니다.
| 지점 위치 | vt 멤버 | 값 멤버 |
|---|---|---|
| 개체의 경계 외부 및 개체의 경계 사각형 내부 또는 외부입니다. | VT_EMPTY | 없음 |
| 개체 내에 있지만 자식 요소 또는 자식 개체 내에는 없습니다. | VT_I4 | lVal 이 CHILDID_SELF. |
| 자식 요소 내에서. | VT_I4 | lVal 에는 자식 ID가 포함됩니다. |
| 자식 개체 내에서. | VT_DISPATCH | pdispVal 이 자식 개체의 IDispatch 인터페이스 포인터로 설정됩니다. |
반환 값
형식: HRESULT
성공하면 S_OK를 반환합니다.
성공하지 못하면 다음 테이블의 값 중 하나 또는 다른 표준 COM 오류 코드를 반환합니다. 서버는 이러한 값을 반환하지만 클라이언트는 항상 유효한 값을 포함하도록 출력 매개 변수를 검사 합니다. 자세한 내용은 IAccessible 반환 값 확인을 참조하세요.
| 오류 | Description |
|---|---|
|
점이 개체의 경계를 벗어났습니다. pvarID의 vt 멤버가 VT_EMPTY. |
|
개체는 이 메서드를 지원하지 않습니다. |
|
인수가 잘못된 경우. |
클라이언트 개발자에게 참고: pvarID의 vt 멤버가 VT_EMPTY 경우 서버가 S_FALSE 반환하지만 클라이언트는 pvarID-vt>가 VT_EMPTY 반환 값이 S_OK 경우도 처리해야 합니다.
설명
테스트된 지점이 개체의 자식 중 하나에 있고 이 자식이 IAccessible 인터페이스 자체를 지원하는 경우 이 메서드는 IAccessible 인터페이스 포인터를 반환해야 합니다. 그러나 클라이언트는 IAccessible 인터페이스 포인터 또는 자식 ID를 처리할 준비가 되어 있어야 합니다. 자세한 내용은 매개 변수에서 자식 ID를 사용하는 방법을 참조하세요.
accLocation은 경계 사각형을 반환하므로 해당 사각형의 모든 점이 개체의 실제 범위 내에 있는 것은 아닙니다. 경계 사각형 내의 일부 지점이 개체에 없을 수 있습니다. 단일 항목에 아이콘의 사각형과 아이콘 텍스트에 대한 다른 사각형이 있는 큰 아이콘 모드의 목록 보기 항목과 같은 직사각형이 아닌 개체의 경우 accHitTest 를 사용하여 테스트한 경우 IAccessible::accLocation에서 검색한 개체의 경계 사각형 좌표가 실패할 수 있습니다.
다른 IAccessible 메서드 및 함수와 마찬가지로 클라이언트는 사용자 작업으로 인해 IAccessible 인터페이스 포인터에 대한 오류를 수신할 수 있습니다. 자세한 내용은 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 |
| 헤더 | oleacc.h |
| 라이브러리 | Oleacc.lib |
| DLL | Oleacc.dll |
| 재배포 가능 파일 | SP6 이상 및 Windows 95를 Windows NT 4.0의 활성 접근성 1.3 RDK |