Использование IUIAutomationTextRange для доступа к диапазону текста и управления им

В этом разделе описывается использование свойств и методов интерфейса IUIAutomationTextRange для доступа к текстовому содержимому текстового элемента управления и управления им.

Что такое диапазон текста?

Текстовая объектная модель Microsoft модель автоматизации пользовательского интерфейса основана на концепции текстового диапазона. Текстовый диапазон — это объект, который предоставляет интерфейс IUIAutomationTextRange и представляет непрерывный диапазон текста в текстовом элементе управления. Каждый текстовый диапазон имеет начальную и конечную конечную точку, а все текстовое содержимое между двумя конечными точками считается частью диапазона. Текстовый диапазон, начальная и конечная точка которого находятся в одном расположении, называется вырожденным (или пустым) текстовым диапазоном. Диапазон вырожденного текста используется для пометки определенного расположения в тексте элемента управления, например расположения точки вставки текста.

Получение объектов диапазона текста

Клиентские приложения получают объекты диапазона текста с помощью свойств и методов интерфейса IUIAutomationTextPattern . Свойство IUIAutomationTextRangePattern::D ocumentRange извлекает диапазон текста, представляющий все текстовое содержимое текстового элемента управления, в то время как другие методы получают диапазоны текста, представляющие определенную часть содержимого, например выделенный текст, видимый текст или объект, внедренный в текст.

Методы IUIAutomationTextRangePattern::GetVisibleRanges и GetSelection могут извлекать массивы объектов текстового диапазона. Если элемент управления частично скрыт перекрывающимся окном или другим объектом, GetVisibleRanges возвращает массив, содержащий объект текстового диапазона для каждой частично видимой строки текста. Аналогичным образом, если текстовый элемент управления поддерживает выделение нескольких несвязанных диапазонов текста, GetSelection возвращает массив, содержащий объект диапазона текста для каждого выделенного диапазона.

Метод IUIAutomationTextRangePattern::RangeFromChild позволяет клиентскому приложению получить текстовый диапазон, включающий объект, внедренный в текстовое содержимое. Клиент указывает указатель интерфейса IUIAutomationElement внедренного объекта, например изображения, таблицы или гиперссылки, а метод возвращает текстовый диапазон, который заключает объект . Однако если внедренный объект не имеет связанного с ним текста, метод возвращает диапазон вырожденного текста.

Клиентское приложение может использовать метод IUIAutomationTextRangePattern::RangeFromPoint для получения текстового диапазона для видимого текста или внедренного объекта, ближайшего к указанным координатам экрана.

Выделение текста в текстовом диапазоне

Интерфейс IUIAutomationTextRange включает ряд методов, которые позволяют клиентскому приложению управлять выделением текста в текстовом элементе управления.

Клиентские приложения могут использовать метод IUIAutomationTextRange::Select , чтобы выделить текст, соответствующий текстовому диапазону, и удалить предыдущий выделенный фрагмент ,если таковой имеется, из элемента управления "Текст". Вызов команды Select с вырожденным текстовым диапазоном перемещает точку вставки в расположение текстового диапазона без выделения текста.

Если элемент управления поддерживает выделение нескольких несвязанных диапазонов текста, клиент может использовать методы IUIAutomationTextRange::AddToSelection и RemoveFromSelection , чтобы добавить диапазоны текста в коллекцию выделенных текстовых диапазонов и удалить их из них. Если элемент управления одновременно поддерживает только один выделенный диапазон текста, но операция выделения приведет к выделению нескольких несвязанных текстовых диапазонов, метод возвращает ошибку E_INVALIDOPERATION либо расширяет или усекает текущее выделение. Клиентское приложение может определить, поддерживает ли элемент управления выбор одного или нескольких диапазонов текста или вообще ни одного, проверив свойство IUIAutomationTextPattern::SupportedTextSelection .

Если текстовый элемент управления поддерживает вставку текста, вызов IUIAutomationTextRange::AddToSelection или RemoveFromSelection в диапазоне вырожденного текста в элементе управления перемещает точку вставки, но не выделяет текст.

Получение текста из диапазона текста

Клиентские приложения могут использовать метод IUIAutomationTextRange::GetText для получения обычного текста текстового диапазона. Обычный текст включает все управляющие символы, найденные в исходном тексте, такие как возврат каретки и метка Юникода слева направо (LRM). Обычный текст не содержит тегов разметки, таких как HTML, которые могут присутствовать в исходном тексте. Кроме того, все escape-коды в исходном тексте преобразуются в эквиваленты обычного текста. Например, "" преобразуется в простой символ пробела.

Если внедренный объект охватывает диапазон текста, обычный текст включает внутренний текст объекта, но не альтернативный текст (свойство name внедренного объекта). Дополнительные сведения см. в разделе Как модель автоматизации пользовательского интерфейса предоставляет внедренные объекты.

Метод IUIAutomationTextRange::FindText выполняет поиск определенной строки в текстовом диапазоне и, если она найдена, возвращает новый текстовый диапазон, охватывающий строку.

Получение атрибутов текста из текстового диапазона

Атрибуты текста определяют стиль форматирования текста в текстовом элементе управления и включают такие элементы, как цвет переднего плана, стиль маркеров, размер шрифта и т. д. модель автоматизации пользовательского интерфейса поддерживает ряд текстовых атрибутов и определяет идентификатор для каждого поддерживаемого атрибута. Клиентское приложение может запрашивать текстовый диапазон для значения определенного текстового атрибута, указывая идентификатор атрибута в вызове метода IUIAutomationTextRange::GetAttributeValue вместе с указателем на структуру VARIANT , получающую значение атрибута. Подробные сведения о каждом текстовом атрибуте, который модель автоматизации пользовательского интерфейса поддерживает, см. в разделе Идентификаторы атрибутов текста.

Значение, полученное методом GetAttributeValue , представляет значение атрибута во всем текстовом диапазоне. Если все тексты в диапазоне имеют одно и то же значение для указанного атрибута, это значение возвращается методом GetAttributeValue. Однако если значение атрибута зависит от текстового диапазона, GetAttributeValue возвращает указатель IUnknown на объект статического токена, называемый объектом ReservedMixedAttribute . Чтобы определить, меняется ли значение атрибута в текстовом диапазоне, клиентское приложение должно сравнить результаты GetAttributeValue с объектом ReservedMixedAttribute, полученным из свойства IUIAutomation::ReservedMixedAttributeValue .

Текстовый элемент управления не требуется для поддержки всех модель автоматизации пользовательского интерфейса текстовых атрибутов. Если клиент вызывает метод IUIAutomationTextRange::GetAttributeValue и передает идентификатор неподдерживаемого атрибута, метод возвращает указатель IUnknown на статический объект маркера, называемый объектом ReservedNotSupported . Чтобы определить, поддерживается ли определенный атрибут, клиентское приложение должно сравнить результаты GetAttributeValue с объектом ReservedNotSupported , полученным из свойства IUIAutomation::ReservedNotSupportedValue .

Клиентские приложения могут использовать метод IUIAutomationTextRange::FindAttribute для поиска текста в текстовом диапазоне с определенным атрибутом текста. Если он найден, метод возвращает новый текстовый диапазон, охватывающий соответствующий текст. Обратите внимание, что FindAttribute возвращает диапазон текста для сопоставления текста, даже если текст не виден.

Получение внедренных объектов из текстового диапазона

Текстовый диапазон может включать внедренные объекты, такие как таблицы, изображения, гиперссылки и т. д. Клиентское приложение может получить коллекцию всех внедренных объектов в диапазоне, вызвав метод IUIAutomationTextRange::GetChildren . Внедренные объекты, которые перекрываются с диапазоном, но не полностью заключены в него, также включаются в коллекцию. Если диапазон не содержит внедренных объектов, GetChildren извлекает пустую коллекцию.

Хотя это зависит от поставщика текстового элемента управления, метод GetChildren обычно не возвращает дочерних элементов внедренных элементов. Например, если текстовый диапазон содержит таблицу с несколькими дочерними ячейками, метод GetChildren обычно возвращает только элемент таблицы, а не элементы ячейки.

По соображениям производительности или архитектуры GetChildren может не получить объекты IUIAutomationElement для всех внедренных объектов в текстовом диапазоне. Вместо этого поставщик может вернуть коллекцию, содержащую виртуализированные элементы. Дополнительные сведения см. в статье Работа с виртуализированными элементами.

Управление текстовым диапазоном

Интерфейс IUIAutomationTextRange предоставляет несколько методов для управления текстовыми диапазонами и навигации по текстовым диапазонам. Методы IUIAutomationTextRange::Move, MoveEndpointByUnit и ExpandToEnclosingUnit перемещают текстовый диапазон или одну из его конечных точек на указанную единицу текста, например символ, слово, абзац и т. д. Дополнительные сведения см. в разделе модель автоматизации пользовательского интерфейса текстовых единиц.

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

Если текстовый диапазон начинается в начале текстового блока и заканчивается в начале или раньше границы следующего текстового блока, конечная конечная точка перемещается на следующую границу текстового блока (см. 1 и 2 на предыдущем рисунке).

Если текстовый диапазон начинается в начале текстового блока и заканчивается на или после следующей границы блока, конечная конечная точка остается или перемещается назад к следующей границе блока после начальной конечной точки (см. 3 и 4 на предыдущем рисунке). Если между начальной и конечной конечными точками имеется несколько единиц текста, конечная конечная точка перемещается назад к следующей границе блока после начальной конечной точки, в результате чего диапазон текста составляет одну единицу текста.

Если текстовый диапазон начинается в середине текстового блока, начальная конечная точка перемещается назад в начало текстового блока, а конечная конечная точка при необходимости перемещается вперед или назад на следующую границу блока после начальной конечной точки (см. 5–8 на предыдущем рисунке).

При вызове метода IUIAutomationTextRange::Move поставщик нормализует диапазон текста по заданной текстовой единице. Затем поставщик перемещает диапазон назад или вперед на указанное количество текстовых единиц. При перемещении диапазона поставщик игнорирует границы всех внедренных объектов в тексте. (Однако наличие внедренного объекта может повлиять на саму границу единицы измерения. На следующей схеме показано, как метод Move перемещает текстовый диапазон между внедренными объектами и границами текстовых единиц.

Метод IUIAutomationTextRange::MoveEndpointByUnit перемещает одну из конечных точек вперед или назад на указанную текстовую единицу. На следующем рисунке показано, как конечная точка перемещается вперед.

Метод IUIAutomationTextRange::MoveEndpointByRange позволяет клиентскому приложению задать одну конечную точку текстового диапазона в том же расположении, что и указанная конечная точка второго текстового диапазона.

Прокрутка текстового диапазона в режиме просмотра

Метод IUIAutomationTextRange::ScrollIntoView прокручивает текстовый диапазон, чтобы текст был виден в окне просмотра текстового элемента управления. При вызове ScrollIntoView клиент может указать, должен ли текст выравнивать по верхнему или нижнему краю окна просмотра.

Получение включающего элемента текстового диапазона

Клиентское приложение может использовать метод IUIAutomationTextRange::GetEnclosingElement для получения указателя интерфейса IUIAutomation самого внутреннего элемента, включающего текстовый диапазон. Включающий элемент обычно является поставщиком текста, предоставляющим диапазон текста. Однако если поставщик текста поддерживает дочерние элементы, такие как таблицы или гиперссылки, включающий элемент может быть потомком поставщика текста.

Сравнение и клонирование диапазонов текста

Интерфейс IUIAutomationTextRange включает два метода сравнения текстовых диапазонов. Метод IUIAutomationTextRange::Compare сравнивает начальную и конечную конечные точки двух текстовых диапазонов и возвращает значение TRUE , если обе конечные точки одинаковы. Метод IUIAutomationTextRange::CompareEndpoints сравнивает начальную или конечную точку двух диапазонов. Возвращаемое значение равно нулю, если конечные точки совпадают, или положительное или отрицательное значение, указывающее относительные позиции двух конечных точек.

Клиентские приложения могут использовать метод IUIAutomationTextRange::Clone для создания точной копии текстового диапазона. С новым текстовым диапазоном можно управлять независимо от исходного диапазона текста.

Получение заметок

Текстовый диапазон может содержать заметки, если текстовый элемент управления поддерживает их. Существует множество различных типов заметок. Файл заголовка UIAutomationClient.h определяет набор именованных значений констант, определяющих типы заметок, поддерживаемые модель автоматизации пользовательского интерфейса. Дополнительные сведения см. в разделе Идентификаторы типов заметки.

Некоторые типы заметок представлены элементом автоматизации, поддерживающим шаблон элемента управления Annotation (интерфейс IUIAutomationAnnotationPattern ). Другие типы заметок предоставляются через шаблон элемента управления TextRange . Например, поставщик может предоставить простой индикатор орфографических ошибок, если метод IUIAutomationTextRange::GetAttributeValue возвращает текстовый атрибут AnnotationTypesAnnotationType_SpellingError и значение NULL для текстового атрибута AnnotationObjects .

Получение типов заметок из текстового диапазона

Список типов заметок, присутствующих в текстовом диапазоне, можно получить с помощью метода IUIAutomationTextRange::GetAttributeValue . При вызове метода укажите идентификатор текстового атрибута UIA_AnnotationTypesAttributeId и указатель на параметр типа VARIANT. При возврате метода параметр VARIANT содержит список идентификаторов типов заметки, по одному для каждого типа заметки в текстовом диапазоне. Дополнительные сведения см. в разделе Идентификаторы типов заметки.

Получение всех заметок из текстового диапазона

Чтобы получить заметки из текстового диапазона, вызовите метод IUIAutomationTextRange::GetAttributeValue , указав идентификатор текстового атрибута UIA_AnnotationObjectsAttributeId и указатель на параметр типа VARIANT. При возврате метода параметр VARIANT содержит интерфейс IUIAutomationElementArray , представляющий массив элементов автоматизации, по одному для каждой заметки в текстовом диапазоне. Свойство IUIAutomationElementArray::Length указывает количество элементов в массиве, а метод IUIAutomationElementArray::GetElement извлекает интерфейс IUIAutomationElement для определенного элемента.

Получение сведений о конкретной заметке

Чтобы получить сведения о конкретной заметке, сначала получите интерфейс IUIAutomationElement для элемента annotation, как описано в предыдущем разделе. Затем получите интерфейс IUIAutomationAnnotationPattern для заметки, вызвав метод IUIAutomationElement::GetCurrentPatternAs с идентификатором шаблона элемента управления UIA_AnnotationPatternId, идентификатором интерфейса IID_IUIAutomationAnnotationPattern и адресом переменной, которая получает указатель IUIAutomationAnnotation для заметки . Запросите свойства интерфейса IUIAutomationAnnotation , чтобы получить имя и идентификатор типа заметки, имя автора заметки, дату и время заметки, а также интерфейс IUIAutomationElement для элемента, для которого выполняется аннотирование.

Получение текста конечного объекта заметки

Как правило, заметка применяется к некоторому подмножество текста в текстовом диапазоне. После получения интерфейса IUIAutomationElement для заметки можно передать интерфейс в метод IUIAutomationTextRange2::RangeFromAnnotation , чтобы получить текстовый диапазон, содержащий текст, который является целевым объектом заметки.

Получение визуальных стилей

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

Метод IUIAutomationTextRange::GetAttributeValue можно использовать для получения имен и идентификаторов стилей визуальных элементов, используемых в текстовом диапазоне. Используйте атрибут UIA_StyleNameAttributeId text для получения имен стилей и UIA_StyleIdAttributeId для получения идентификаторов стилей.

Текстовый элемент управления, поддерживающий стили визуальных элементов, может реализовать шаблон элемента управления Стили , чтобы клиенты могли получать доступ к сведениям о визуальном стиле, используемом элементом управления . Клиенты получают доступ к шаблону элемента управления Styles через интерфейс IUIAutomationStylesPattern . Этот интерфейс можно получить, вызвав метод IUIAutomationElement::GetCurrentPattern или GetCurrentPatternAs , указав UIA_StylesPatternId в качестве идентификатора шаблона элемента управления.

Интерфейс IUIAutomationStylesPattern содержит свойства и методы, предоставляющие следующие сведения о визуальном стиле:

• Имя стиля визуального элемента, например "Обычный" или "Заголовок 1".
• Идентификатор визуального стиля. Дополнительные сведения см. в разделе Идентификаторы стилей.
• Цвет, используемый для заполнения текстового элемента управления.
• Цвет шаблона, используемого для заполнения текстового элемента управления.
• Форма текстового элемента управления.
• Расширенные свойства; то есть список имен и значений стилей, относящихся к элементу управления.

Вызов контекстных меню из текстовых диапазонов

Начиная с Windows 8.1 текстовые диапазоны могут поддерживать интерфейс IUIAutomationTextRange2. Этот интерфейс поддерживает метод ShowContextMenu . Этот метод можно вызвать для вызова любого контекстного меню, связанного с текстовым диапазоном. Сценарий для этого — автозамена текстовых диапазонов или выбор кандидатов IME. В таких случаях появляется контекстное меню, поддерживающее взаимодействие с пользователем.

Связанные темы

Шаблоны элементов управления Text и TextRange

Модель автоматизации пользовательского интерфейса поддержка текстового содержимого

Работа с текстовыми элементами управления