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

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

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

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

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

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

Методы 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-коды в исходном тексте преобразуются в эквиваленты обычного текста. Например, "" преобразуется в простой символ пробела.

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

Метод 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 определяет набор именованных значений констант, определяющих типы заметок, поддерживаемых службой автоматизации пользовательского интерфейса. Дополнительные сведения см. в разделе Идентификаторы типов заметок.

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

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

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

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

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

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

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

Получение целевого текста аннотации

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

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

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

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

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

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

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

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

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

Связанные разделы

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

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

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