다음을 통해 공유


IUIAutomationTextRange를 사용하여 텍스트 범위 액세스 및 조작

이 항목에서는 IUIAutomationTextRange 인터페이스의 속성과 메서드를 사용하여 텍스트 기반 컨트롤의 텍스트 콘텐츠에 액세스하고 조작하는 방법을 설명합니다.

텍스트 범위란?

Microsoft UI 자동화 텍스트 개체 모델은 텍스트 범위의 개념을 기반으로 합니다. 텍스트 범위는 IUIAutomationTextRange 인터페이스를 노출하고 텍스트 기반 컨트롤의 연속된 텍스트 범위를 나타내는 개체입니다. 각 텍스트 범위에는 시작 엔드포인트와 끝 엔드포인트가 모두 있으며 두 엔드포인트 사이의 모든 텍스트 콘텐츠는 범위의 일부로 간주됩니다. 시작 엔드포인트와 끝 엔드포인트가 동일한 위치에 있는 텍스트 범위를 퇴화 (또는 빈) 텍스트 범위라고 합니다. 퇴화 텍스트 범위는 텍스트 삽입 지점의 위치와 같은 컨트롤의 텍스트 내에서 특정 위치를 표시하는 데 사용됩니다.

텍스트 범위 개체 획득

클라이언트 애플리케이션은 IUIAutomationTextPattern 인터페이스의 속성과 메서드를 사용하여 텍스트 범위 개체를 가져옵니다. IUIAutomationTextRangePattern::D cumentRange 속성은 텍스트 기반 컨트롤의 전체 텍스트 콘텐츠를 나타내는 텍스트 범위를 검색하는 반면, 다른 메서드는 선택한 텍스트, 표시되는 텍스트 또는 텍스트에 포함된 개체와 같이 콘텐츠의 일부를 나타내는 텍스트 범위를 가져옵니다.

IUIAutomationTextRangePattern::GetVisibleRangesGetSelection 메서드는 텍스트 범위 개체의 배열을 검색할 수 있습니다. 컨트롤이 겹치는 창이나 다른 개체에 의해 부분적으로 가려지는 경우 GetVisibleRanges 는 부분적으로 표시되는 각 텍스트 줄에 대한 텍스트 범위 개체가 포함된 배열을 반환합니다. 마찬가지로 텍스트 기반 컨트롤이 여러 개의 연결되지 않은 텍스트 범위 선택을 지원하는 경우 GetSelection 은 선택한 각 범위에 대한 텍스트 범위 개체가 포함된 배열을 반환합니다.

IUIAutomationTextRangePattern::RangeFromChild 메서드를 사용하면 클라이언트 애플리케이션이 텍스트 콘텐츠에 포함된 개체를 묶는 텍스트 범위를 검색할 수 있습니다. 클라이언트는 이미지, 테이블 또는 하이퍼링크와 같은 포함된 개체의 IUIAutomationElement 인터페이스 포인터를 지정하고 메서드는 개체를 묶는 텍스트 범위를 반환합니다. 그러나 포함된 개체에 연결된 텍스트가 없으면 메서드는 퇴화 텍스트 범위를 반환합니다.

클라이언트 애플리케이션은 IUIAutomationTextRangePattern::RangeFromPoint 메서드를 사용하여 표시된 텍스트 또는 지정된 화면 좌표에 가장 가까운 포함된 개체의 텍스트 범위를 검색할 수 있습니다.

텍스트 범위에서 텍스트 선택

IUIAutomationTextRange 인터페이스에는 클라이언트 애플리케이션이 텍스트 기반 컨트롤에서 텍스트 선택을 제어할 수 있는 여러 메서드가 포함되어 있습니다.

클라이언트 애플리케이션은 IUIAutomationTextRange::Select 메서드를 사용하여 텍스트 범위에 해당하는 텍스트를 선택하고 텍스트 컨트롤에서 이전 선택 영역(있는 경우)을 제거할 수 있습니다. 퇴화 텍스트 범위를 사용하여 선택을 호출하면 텍스트를 선택하지 않고 삽입 지점이 텍스트 범위의 위치로 이동합니다.

컨트롤이 여러 개의 연결되지 않은 텍스트 범위 선택을 지원하는 경우 클라이언트는 IUIAutomationTextRange::AddToSelectionRemoveFromSelection 메서드를 사용하여 선택한 텍스트 범위의 컬렉션에 텍스트 범위를 추가하고 제거합니다. 컨트롤이 선택한 텍스트 범위를 한 번에 하나만 지원하지만 선택 연산으로 인해 여러 개의 비연속 텍스트 범위가 선택되는 경우 메서드는 E_INVALIDOPERATION 오류를 반환하거나 현재 선택 영역을 확장하거나 자른다. 클라이언트 애플리케이션은 IUIAutomationTextPattern::SupportedTextSelection 속성을 확인하여 컨트롤이 단일 또는 여러 텍스트 범위 선택을 지원하는지 또는 전혀 선택하지 않는지 여부를 검색할 수 있습니다.

텍스트 기반 컨트롤이 텍스트 삽입을 지원하는 경우 컨트롤의 퇴화 텍스트 범위에서 IUIAutomationTextRange::AddToSelection 또는 RemoveFromSelection 을 호출하면 삽입 지점이 이동하지만 텍스트를 선택하지 않습니다.

텍스트 범위에서 텍스트 검색

클라이언트 애플리케이션은 IUIAutomationTextRange::GetText 메서드를 사용하여 텍스트 범위의 일반 텍스트를 검색할 수 있습니다. 일반 텍스트에는 캐리지 리턴 및 LRM(유니코드 왼쪽에서 오른쪽 표시)과 같은 원본 텍스트에 있는 모든 컨트롤 문자가 포함됩니다. 일반 텍스트에는 원본 텍스트에 있을 수 있는 HTML과 같은 태그 태그가 포함되지 않습니다. 또한 원본 텍스트의 모든 이스케이프 코드는 일반 텍스트와 동등한 값으로 변환됩니다. 예를 들어 " "는 단순 공백 문자로 변환됩니다.

포함된 개체가 텍스트 범위에 걸쳐 있는 경우 일반 텍스트에는 개체의 내부 텍스트가 포함되지만 대체 텍스트(포함된 개체의 name 속성)는 포함되지 않습니다. 자세한 내용은 UI 자동화 포함된 개체를 노출하는 방법을 참조하세요.

IUIAutomationTextRange::FindText 메서드는 특정 문자열에 대한 텍스트 범위를 검색하고, 있는 경우 문자열을 포함하는 새 텍스트 범위를 반환합니다.

텍스트 범위에서 텍스트 특성 검색

텍스트 특성은 텍스트 기반 컨트롤에서 텍스트의 서식 스타일을 결정하고 전경색, 글머리 기호 스타일, 글꼴 크기 등의 항목을 포함합니다. UI 자동화 다양한 텍스트 특성을 지원하고 지원되는 각 특성에 대한 식별자를 정의합니다. 클라이언트 애플리케이션은 특성 값을 받는 VARIANT 구조체에 대한 포인터와 함께 IUIAutomationTextRange::GetAttributeValue 메서드 호출에서 특성 식별자를 지정하여 특정 텍스트 특성의 값에 대한 텍스트 범위를 쿼리할 수 있습니다. UI 자동화 지원하는 각 텍스트 특성에 대한 자세한 내용은 텍스트 특성 식별자를 참조하세요.

GetAttributeValue에서 검색한 값은 전체 텍스트 범위에서 특성의 값을 나타냅니다. 범위의 모든 텍스트가 지정된 특성에 대해 동일한 값을 공유하는 경우 해당 값은 GetAttributeValue에서 반환됩니다. 그러나 특성 값이 텍스트 범위에 따라 달라지면 GetAttributeValueReservedMixedAttribute 개체라는 정적 토큰 개체에 대한 IUnknown 포인터를 반환합니다. 특성 값이 텍스트 범위에 따라 달라지는지 여부를 검색하려면 클라이언트 애플리케이션에서 GetAttributeValue 결과를 IUIAutomation::ReservedMixedAttributeValue 속성에서 검색된 ReservedMixedAttribute 개체와 비교해야 합니다.

모든 UI 자동화 텍스트 특성을 지원하기 위해 텍스트 기반 컨트롤이 필요하지는 않습니다. 클라이언트가 IUIAutomationTextRange::GetAttributeValue 메서드를 호출하고 지원되지 않는 특성의 식별자를 전달하는 경우 메서드는 ReservedNotSupported 개체라는 정적 토큰 개체에 대한 IUnknown 포인터를 반환합니다. 특정 특성이 지원되는지 여부를 검색하려면 클라이언트 애플리케이션이 GetAttributeValue의 결과를 IUIAutomation::ReservedNotSupportedValue 속성에서 검색된 ReservedNotSupported 개체와 비교해야 합니다.

클라이언트 애플리케이션은 IUIAutomationTextRange::FindAttribute 메서드를 사용하여 특정 텍스트 특성이 있는 텍스트의 텍스트 범위를 검색할 수 있습니다. 찾은 경우 메서드는 일치하는 텍스트를 포함하는 새 텍스트 범위를 반환합니다. FindAttribute는 텍스트가 표시되지 않더라도 일치하는 텍스트에 대한 텍스트 범위를 반환합니다.

텍스트 범위에서 포함된 개체 검색

텍스트 범위에는 테이블, 이미지, 하이퍼링크 등과 같은 포함된 개체가 포함될 수 있습니다. 클라이언트 애플리케이션은 IUIAutomationTextRange::GetChildren 메서드를 호출하여 범위에 포함된 모든 개체의 컬렉션을 검색할 수 있습니다. 범위와 겹치지만 완전히 묶이지 않는 포함된 개체도 컬렉션에 포함됩니다. 범위에 포함된 개체가 없는 경우 GetChildren 는 빈 컬렉션을 검색합니다.

텍스트 기반 컨트롤의 공급자에 따라 달라지지만 GetChildren 메서드는 일반적으로 포함된 요소의 자식을 반환하지 않습니다. 예를 들어 텍스트 범위에 여러 자식 셀이 있는 표가 포함된 경우 GetChildren 메서드는 일반적으로 셀 요소가 아닌 table 요소만 반환합니다.

성능 또는 아키텍처상의 이유로 GetChildren은 텍스트 범위의 모든 포함된 개체에 대해 IUIAutomationElement 개체를 검색하지 못할 수 있습니다. 대신 공급자는 가상화된 항목을 포함하는 컬렉션을 반환할 수 있습니다. 자세한 내용은 가상화된 항목 작업을 참조하세요.

텍스트 범위 조작

IUIAutomationTextRange 인터페이스는 텍스트 기반 컨트롤에서 텍스트 범위를 조작하고 탐색하는 여러 메서드를 제공합니다. IUIAutomationTextRange::Move, MoveEndpointByUnitExpandToEnclosingUnit 메서드는 텍스트 범위 또는 해당 엔드포인트 중 하나를 지정된 텍스트 단위(예: 문자, 단어, 단락 등)로 이동합니다. 자세한 내용은 UI 자동화 텍스트 단위를 참조하세요.

이름에도 불구하고 ExpandToEnclosingUnit 메서드가 반드시 텍스트 범위를 확장할 필요는 없습니다. 대신 범위가 지정된 텍스트 단위를 정확하게 포함하도록 엔드포인트를 이동하여 텍스트 범위를 "정규화"합니다. 범위가 지정된 단위보다 작으면 확장되거나 지정된 단위보다 긴 경우 줄입니다. 다음 다이어그램에서는 ExpandToEnclosingUnit 이 범위의 엔드포인트를 이동하여 텍스트 범위를 정규화하는 방법을 보여 줍니다.

expandtoenclosingunit 호출 전후의 엔드포인트 위치를 보여 주는 다이어그램

텍스트 범위가 텍스트 단위의 시작 부분에서 시작되고 다음 텍스트 단위 경계의 시작 또는 그 이전에 끝나는 경우 끝 엔드포인트는 다음 텍스트 단위 경계로 이동됩니다(이전 그림의 1과 2 참조).

텍스트 범위가 텍스트 단위의 시작 부분에서 시작되고 다음 단위 경계에서 또는 그 이후에 끝나는 경우 끝 엔드포인트는 시작 엔드포인트 이후의 다음 단위 경계로 유지되거나 뒤로 이동됩니다(이전 그림의 3 및 4 참조). 시작 엔드포인트와 끝 엔드포인트 사이에 두 개 이상의 텍스트 단위 경계가 있는 경우 끝 엔드포인트는 시작 엔드포인트 이후의 다음 단위 경계로 뒤로 이동되어 텍스트 범위가 하나의 텍스트 단위로 표시됩니다.

텍스트 범위가 텍스트 단위 중간에 시작되면 시작 엔드포인트가 텍스트 단위의 시작 부분으로 뒤로 이동되고 필요에 따라 끝 엔드포인트가 시작 엔드포인트 이후의 다음 단위 경계로 앞으로 또는 뒤로 이동됩니다(이전 그림의 5~8 참조).

IUIAutomationTextRange::Move 메서드가 호출되면 공급자는 지정된 텍스트 단위로 텍스트 범위를 정규화합니다. 그런 다음 공급자는 지정된 수의 텍스트 단위로 범위를 뒤로 또는 앞으로 이동합니다. 범위를 이동할 때 공급자는 텍스트에 포함된 개체의 경계를 무시합니다. 그러나 단위 경계 자체는 포함된 개체의 존재에 의해 영향을 받을 수 있습니다. 다음 다이어그램에서는 Move 메서드가 포함된 개체 및 텍스트 단위 경계에서 단위 단위로 텍스트 범위를 이동하는 방법을 보여 줍니다.

이동 메서드가 개체 및 텍스트 단위 경계를 넘어 범위 엔드포인트를 이동하는 방법을 보여 주는 다이어그램

IUIAutomationTextRange::MoveEndpointByUnit 메서드는 지정된 텍스트 단위로 엔드포인트 중 하나를 앞으로 또는 뒤로 이동합니다. 다음 그림에서는 엔드포인트가 앞으로 이동하는 방법을 보여 줍니다.

moveendpointbyunit이 범위의 엔드포인트를 이동하는 방법을 보여 주는 다이어그램

IUIAutomationTextRange::MoveEndpointByRange 메서드를 사용하면 클라이언트 애플리케이션이 텍스트 범위의 한 엔드포인트를 두 번째 텍스트 범위의 지정된 엔드포인트와 동일한 위치로 설정할 수 있습니다.

텍스트 범위를 보기로 스크롤

IUIAutomationTextRange::ScrollIntoView 메서드는 텍스트 기반 컨트롤의 뷰포트에 텍스트가 표시되도록 텍스트 범위를 스크롤합니다. ScrollIntoView를 호출할 때 클라이언트는 텍스트를 뷰포트의 위쪽 또는 아래쪽에 맞출지 여부를 지정할 수 있습니다.

텍스트 범위의 묶는 요소 검색

클라이언트 애플리케이션은 IUIAutomationTextRange::GetEnclosingElement 메서드를 사용하여 텍스트 범위를 묶는 가장 안쪽 요소의 IUIAutomation 인터페이스 포인터를 검색할 수 있습니다. 바깥쪽 요소는 일반적으로 텍스트 범위를 제공하는 텍스트 공급자입니다. 그러나 텍스트 공급자가 테이블 또는 하이퍼링크와 같은 자식 요소를 지원하는 경우 묶는 요소는 텍스트 공급자의 하위 요소일 수 있습니다.

텍스트 범위 비교 및 복제

IUIAutomationTextRange 인터페이스에는 텍스트 범위를 비교하는 두 가지 메서드가 포함되어 있습니다. IUIAutomationTextRange::Compare 메서드는 두 텍스트 범위의 시작 및 끝 엔드포인트를 비교하고 두 엔드포인트가 동일한 경우 TRUE를 반환합니다. IUIAutomationTextRange::CompareEndpoints 메서드는 두 범위의 시작 또는 끝 엔드포인트를 비교합니다. 엔드포인트가 같으면 반환 값이 0이거나 두 엔드포인트의 상대 위치를 나타내는 양수 값 또는 음수 값입니다.

클라이언트 애플리케이션은 IUIAutomationTextRange::Clone 메서드를 사용하여 텍스트 범위의 정확한 복사본을 만들 수 있습니다. 새 텍스트 범위는 원래 텍스트 범위와 독립적으로 조작할 수 있습니다.

주석 검색

텍스트 기반 컨트롤이 지원하는 경우 텍스트 범위에 주석이 포함될 수 있습니다. 주석에는 다양한 종류가 있습니다. UIAutomationClient.h 헤더 파일은 UI 자동화 지원하는 주석 유형을 식별하는 명명된 상수 값 집합을 정의합니다. 자세한 내용은 주석 형식 식별자를 참조하세요.

일부 종류의 주석은 주석 컨트롤 패턴(IUIAutomationAnnotationPattern 인터페이스)을 지원하는 자동화 요소로 표시됩니다. 다른 종류의 주석은 TextRange 컨트롤 패턴을 통해 노출됩니다. 예를 들어 공급자는 IUIAutomationTextRange::GetAttributeValue 메서드가 AnnotationType_SpellingErrorAnnotationTypes 텍스트 특성과 AnnotationObjects 텍스트 특성에 대해 null 값을 반환하여 간단한 맞춤법 오류 표시기를 노출할 수 있습니다.

텍스트 범위에서 주석 형식 검색

IUIAutomationTextRange::GetAttributeValue 메서드를 사용하여 텍스트 범위에 있는 주석 형식의 목록을 검색할 수 있습니다. 메서드를 호출할 때 UIA_AnnotationTypesAttributeId 텍스트 특성 ID와 VARIANT 형식의 매개 변수에 대한 포인터를 지정합니다. 메서드가 반환될 때 VARIANT 매개 변수에는 텍스트 범위의 각 주석 형식에 대해 하나씩 주석 형식 식별자 목록이 포함됩니다. 자세한 내용은 주석 형식 식별자를 참조하세요.

텍스트 범위에서 모든 주석 검색

텍스트 범위에서 주석을 검색하려면 IUIAutomationTextRange::GetAttributeValue 메서드를 호출하여 UIA_AnnotationObjectsAttributeId 텍스트 특성 ID와 VARIANT 형식의 매개 변수에 대한 포인터를 지정합니다. 메서드가 반환될 때 VARIANT 매개 변수에는 텍스트 범위의 각 주석에 대해 하나씩 자동화 요소의 배열을 나타내는 IUIAutomationElementArray 인터페이스가 포함됩니다. IUIAutomationElementArray::Length 속성은 배열의 요소 수를 나타내고 IUIAutomationElementArray::GetElement 메서드는 특정 요소에 대한 IUIAutomationElement 인터페이스를 검색합니다.

특정 주석에 대한 정보 검색

특정 주석에 대한 정보를 검색하려면 먼저 이전 섹션에서 설명한 대로 주석 요소에 대한 IUIAutomationElement 인터페이스를 검색합니다. 다음으로 컨트롤 패턴 ID가 UIA_AnnotationPatternId IUIAutomationElement::GetCurrentPatternAs 메서드, IID_IUIAutomationAnnotationPattern 인터페이스 식별자 및 주석에 대한 IUIAutomationAnnotation 포인터를 수신하는 변수의 주소를 사용하여 주석에 대한 IUIAutomationAnnotationPattern 인터페이스를 검색합니다. IUIAutomationAnnotation 인터페이스의 속성을 쿼리하여 주석 형식 이름 및 형식 ID, 주석 작성자의 이름, 주석의 날짜 및 시간 및 주석이 추가되는 요소에 대한 IUIAutomationElement 인터페이스를 검색합니다.

주석 대상 텍스트 검색

일반적으로 주석은 텍스트 범위의 일부 텍스트 하위 집합에 적용됩니다. 주석에 대한 IUIAutomationElement 인터페이스를 검색한 후 IUIAutomationTextRange2::RangeFromAnnotation 메서드에 인터페이스를 전달하여 주석의 대상인 텍스트가 포함된 텍스트 범위를 검색할 수 있습니다.

비주얼 스타일 검색

공급자는 스타일 컨트롤 패턴을 구현하여 특정 스타일, 채우기 색, 채우기 패턴 또는 도형이 있는 UI 요소를 설명합니다. 이러한 스타일이 자주 있는 문서의 요소를 설명할 때 특히 유용합니다. 이와 같은 스타일은 장애가 있는 고객에게 유용한 정보를 전달하는 경우가 많습니다. 예를 들어 스타일은 특정 문자열을 문서의 제목으로 설명하거나 특정 순서도 개체를 다이아몬드 또는 원으로 설명할 수 있습니다.

IUIAutomationTextRange::GetAttributeValue 메서드를 사용하여 텍스트 범위에서 사용되는 비주얼 스타일의 이름과 식별자를 검색할 수 있습니다. UIA_StyleNameAttributeId 텍스트 특성을 사용하여 스타일 이름을 검색하고 UIA_StyleIdAttributeId 스타일 식별자를 검색합니다.

시각적 스타일을 지원하는 텍스트 기반 컨트롤은 스타일 컨트롤 패턴을 구현하여 클라이언트가 컨트롤에서 사용하는 비주얼 스타일에 대한 정보에 액세스할 수 있도록 할 수 있습니다. 클라이언트는 IUIAutomationStylesPattern 인터페이스를 통해 스타일 컨트롤 패턴에 액세스합니다. IUIAutomationElement::GetCurrentPattern 또는 GetCurrentPatternAs 메서드를 호출하고 UIA_StylesPatternId 컨트롤 패턴 식별자로 지정하여 이 인터페이스를 검색할 수 있습니다.

IUIAutomationStylesPattern 인터페이스에는 비주얼 스타일에 대한 다음 정보를 제공하는 속성 및 메서드가 포함되어 있습니다.

  • "Normal" 또는 "Heading 1"과 같은 비주얼 스타일의 이름입니다.
  • 비주얼 스타일의 식별자입니다. 자세한 내용은 스타일 식별자를 참조하세요.
  • 텍스트 기반 컨트롤을 채우는 데 사용되는 색입니다.
  • 텍스트 기반 컨트롤을 채우는 데 사용되는 패턴의 색입니다.
  • 텍스트 기반 컨트롤의 모양입니다.
  • 확장 속성; 즉, 컨트롤별 스타일 이름 및 값 목록입니다.

텍스트 범위에서 상황에 맞는 메뉴 호출

Windows 8.1 텍스트 범위는 IUIAutomationTextRange2 인터페이스를 지원할 수 있습니다. 이 인터페이스는 ShowContextMenu 메서드를 지원합니다. 이 메서드를 호출하여 텍스트 범위와 연결된 상황에 맞는 메뉴를 호출할 수 있습니다. 이 시나리오는 텍스트 범위 또는 IME 후보 선택 영역의 자동 고침입니다. 이러한 경우 사용자 상호 작용을 지원하는 상황에 맞는 메뉴가 나타납니다.

텍스트 및 TextRange 컨트롤 패턴

텍스트 콘텐츠에 대한 UI 자동화 지원

텍스트 기반 컨트롤 작업