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

  • Статья

Описание рекомендаций и соглашений по реализации ITextProvider, ITextProvider2 и ITextRangeProvider, включая сведения о свойствах и методах. Шаблон элемента управления Текст позволяет приложениям и элементам управления предоставлять простую текстовую объектную модель, позволяя клиентам получать текстовое содержимое, текстовые атрибуты и внедренные объекты из текстовых элементов управления.

Для поддержки шаблона элемента управления Текст элементы управления реализуют интерфейсы ITextProvider и ITextProvider2 . Типы элементов управления, которые должны поддерживать шаблон элемента управления "Текст" , включают типы элементов управления "Изменить" и "Документ ", а также любые другие типы элементов управления, позволяющие пользователю вводить текст или выбирать текст, доступный только для чтения.

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

Интерфейсы ITextProvider и ITextProvider2 включают ряд методов для получения текстовых диапазонов. Текстовый диапазон — это объект, представляющий непрерывный диапазон текста или несколько несвязанных диапазонов текста в текстовом контейнере. Один метод ITextProvider получает диапазон текста, представляющий весь документ, а другие — диапазоны текста, представляющие определенную часть документа, например выделенный текст, видимый текст или объект, внедренный в текст.

Объект текстового диапазона представлен шаблоном элемента управления TextRange , который реализуется через интерфейс ITextRangeProvider . Шаблон элемента управления TextRange предоставляет методы и свойства, используемые для предоставления сведений о тексте в диапазоне, перемещения конечных точек диапазона, выбора или отмены выбора текста, прокрутки диапазона в представление и т. д.

Дополнительные сведения о шаблонах элементов управления Text и TextRange см. в разделе Поддержка текстового содержимого модель автоматизации пользовательского интерфейса.

Начиная с Windows 8.1 поставщики могут реализовывать интерфейс ITextRangeProvider2. Это позволяет вызывать контекстные меню, связанные с текстовым диапазоном. Это поддерживает такие сценарии, как автозамена текста или выбор кандидатов в редакторе метода ввода (IME).

В этом разделе содержатся следующие подразделы.

Правила и соглашения реализации

При реализации шаблона элемента управления "Текст" обратите внимание на следующие рекомендации и соглашения.

  • Любой элемент управления, обеспечивающий доступ к тексту (например, ввод текста или выбор текста только для чтения), должен поддерживать шаблон элемента управления Текст .
  • Шаблон элемента управления "Текст" можно использовать с любым элементом пользовательского интерфейса, который представляет текст, даже со статической меткой на стандартном элементе управления "Кнопка". Однако он не является обязательным для статических элементов управления текстом, которые не могут быть выбраны или не имеют точки вставки.
  • Чтобы текст был полностью доступен, элементы управления, реализующие ITextProvider , также должны поддерживать интерфейс IValueProvider . IValueProvider дополняет ITextProvider , предоставляя программный способ изменения текста. Он также обеспечивает более высокую совместимость с клиентскими приложениями со специальными возможностями, в том числе на основе устаревших технологий, таких как Microsoft Active Accessibility. При реализации обоих шаблонов элементов управления события TextChanged (UIA_Text_TextChangedEventId) и AutomationPropertyChanged (UIA_AutomationPropertyChangedEventId) эквивалентны для свойства Value (UIA_ValueValuePropertyId). Оба события должны поддерживаться.
  • Шаблон элемента управления "Текст" поддерживает только один поток текста и одно окно просмотра для каждого элемента управления. Если приложение предлагает несколько представлений документов в панелях, каждое представление (элемент управления) должно поддерживать ITextProvider независимо.
  • Метод ITextProvider::GetSelection может возвращать один текстовый диапазон, представляющий текущий выделенный текст. Если элемент управления поддерживает выделение нескольких несмежных диапазонов текста, метод GetSelection должен возвращать массив, содержащий один интерфейс ITextRangeProvider для каждого выделенного диапазона текста.
  • Шаблон элемента управления "Текст " представляет точку вставки в виде вырожденного (пустого) текстового диапазона. Метод ITextProvider::GetSelection должен возвращать диапазон вырожденного текста, если точка вставки существует и текст не выделен. Дополнительные сведения см. в разделе Взаимодействие с системой Caret.
  • Метод ITextProvider::GetVisibleRanges может возвращать один текстовый диапазон, если непрерывный диапазон текста виден в окне просмотра, или может возвращать массив несвязанных текстовых диапазонов, представляющих несколько частично видимых строк текста.
  • Метод ITextProvider::RangeFromChild должен возвращать вырожденный диапазон, если дочерний элемент не содержит текста. Так как внедренный объект может содержать текст, метод RangeFromChild не всегда может возвращать диапазон вырожденного текста. Дополнительные сведения см. в разделе Как модель автоматизации пользовательского интерфейса предоставляет внедренные объекты.
  • Метод ITextProvider::RangeFromPoint выполняет проверку попадания в области документа, используя указанные экранные координаты. Результирующий текстовый диапазон должен соответствовать точке вставки или выделенному фрагменту, который будет результатом щелчка по расположению в указанных координатах экрана. Например, если изображение находится в указанных координатах экрана, результирующий диапазон текста должен совпадать с текстовым диапазоном, который будет получен методом ITextProvider::RangeFromChild для изображения. Аналогичным образом, если клиентское приложение запрашивает диапазон текста для расположения в центре курсора системы (точка вставки), результирующий текстовый диапазон должен совпадать с расположением системного курсора.
  • Свойство ITextProvider::D ocumentRange всегда должно предоставлять диапазон текста, включающий весь текст, поддерживаемый соответствующей реализацией ITextProvider .
  • Событие UIA_Text_TextChangedEventId должно вызываться после изменения текста, даже если изменение не отображается в окне просмотра. Например, поставщик должен вызывать событие, даже если пользователь вставит тот же текст на выделенный текст.
  • При изменении выделения текста или при перемещении точки вставки (курсора) между текстом необходимо вызывать UIA_Text_TextSelectionChangedEventId .

При реализации шаблона элемента управления TextRange обратите внимание на следующие рекомендации и соглашения.

  • Все методы шаблона элемента управления TextRange должны выполнять текстовые операции независимо от состояния видимости текста. Видимость текстового диапазона всегда можно определить, запросив текстовый атрибут IsHidden (UIA_IsHiddenAttributeId).
  • Если это возможно, поставщик должен убедиться, что любые изменения текста, такие как удаления, вставки и перемещения, отражаются в связанных объектах диапазона текста (экземпляры интерфейса ITextRangeProvider ) и вызывают событие UIA_Text_TextChangedEventId . Клиенты могут использовать событие в качестве подсказки для подтверждения редакционных изменений, внесенных в текст элемента управления.
  • Все объекты текстового диапазона, используемые методами ITextRangeProvider::Compare, CompareEndpoints и MoveEndpointByRange , должны быть одноранговой частью одной реализации шаблона элемента управления "Текст ".
  • Хотя значение pRetVal , полученное методом ITextRangeProvider::CompareEndpoints , может указывать расстояние между двумя конечными точками в символах (TextUnit_Character). Однако клиентские приложения не должны зависеть от точности pRetVal , превышающей ее положительное или отрицательное значение.
  • Методы ITextRangeProvider::ExpandToEnclosingUnit, Move и MoveEndpointByUnit требуют тщательного рассмотрения указанной текстовой единицы. Дополнительные сведения см. в разделе Управление TextRange по единицам текста.
  • Требования к реализации, связанные с методами ITextRangeProvider::Select, AddToSelection и RemoveFromSelection , см. в разделе Выбор текста в текстовом диапазоне.
  • Методы ITextRangeProvider::FindText и FindAttribute выполняют поиск вперед или назад для одной соответствующей текстовой строки или текстового атрибута. Если совпадение не найдено, они должны возвращать значение NULL .
  • Метод ITextRangeProvider::GetAttributeValue должен возвращать адрес, полученный из функции UiaGetReservedMixedAttributeValue или UiaGetReservedNotSupportedValue , если связанный атрибут зависит от диапазона или если атрибут не поддерживается текстовым элементом управления. Спецификация шаблона элемента управления TextRange не позволяет добавлять новые идентификаторы атрибутов text или изменять способ определения существующих атрибутов.
  • По возможности метод ITextRangeProvider::GetBoundingRectangles должен возвращать массив, содержащий один ограничивающий прямоугольник для каждой полностью или частично видимой строки текста в текстовом диапазоне. Если это невозможно, поставщик может вернуть массив, содержащий ограничивающие прямоугольники только полностью видимых линий; однако это ограничивает возможности клиентского приложения точно описывать, как текст отображается на экране.
  • Метод ITextRangeProvider::GetChildren должен возвращать все дочерние элементы, внедренные в текстовый диапазон, но не требуется возвращать дочерние элементы дочерних элементов. Например, если текстовый диапазон содержит таблицу с несколькими дочерними ячейками, метод GetChildren может возвращать только элемент table, а не элементы ячейки. По соображениям производительности или архитектуры поставщик может не предоставлять все внедренные объекты, размещенные в документе в дереве автоматизации. В этом случае поставщик должен по крайней мере поддерживать перечисление дочерних объектов с помощью метода GetChildren и, как вариант, поддерживать шаблон элемента управления VirtualizedItem для поддержки де-виртуализации.
  • Метод ITextRangeProvider::GetEnclosingElement обычно возвращает поставщик текста, предоставляющий диапазон текста. Однако если поставщик текста поддерживает дочерние объекты, такие как таблицы или гиперссылки, включающий элемент может быть потомком поставщика текста. Элемент, возвращаемый методом GetEnclosingElement , должен быть элементом, ближайшим к заданному текстовому диапазону. Например, если текстовый диапазон находится в ячейке таблицы, метод GetEnclosingElement должен возвращать содержащую ячейку вместо элемента таблицы.
  • Метод ITextRangeProvider::GetText должен возвращать обычный текст в диапазоне. Дополнительные сведения см. в разделе Получение текста из текстового диапазона.
  • Вызов ITextRangeProvider::ScrollIntoView должен выровнять текст в окне просмотра элемента управления текстом в соответствии с параметром alignToTop . Хотя горизонтальное выравнивание не требуется, диапазон текста должен быть виден как по горизонтали, так и по вертикали. При оценке параметра alignToTop поставщик должен учитывать ориентацию элемента управления текстом и направление потока текста. Например, если параметр alignToTop имеет значение TRUE для вертикально ориентированного текстового элемента управления, содержащего текст, который передается справа налево, поставщик должен выровнять диапазон текста по правому краю окна просмотра.
  • При перемещении по документу TextUnit_Line, если текстовый диапазон входит во внедренную таблицу, каждая строка текста в ячейке должна рассматриваться как строка.

Обязательные члены для ITextProvider

Для реализации интерфейса ITextProvider требуются следующие свойства и методы.

Обязательные члены Тип члена Примечания
DocumentRange Свойство Нет
SupportedTextSelection Свойство Нет
GetSelection Метод Нет
GetVisibleRanges Метод Нет
RangeFromChild Метод Нет
RangeFromPoint Метод Нет
UIA_Text_TextChangedEventId Событие Нет
UIA_Text_TextSelectionChangedEventId Событие Нет

 

Для реализации интерфейса ITextProvider2 требуются следующие дополнительные свойства и методы.

Обязательные члены Тип члена Примечания
GetCaretRange Метод Нет
RangeFromAnnotation Метод Нет

 

Обязательные члены для ITextRangeProvider

Для реализации интерфейса ITextRangeProvider требуются следующие свойства и методы.

Обязательные члены Тип члена Примечания
AddToSelection Метод Нет
Clone Метод Нет
Сравнение Метод Нет
CompareEndpoints Метод Нет
ExpandToEnclosingUnit Метод Нет
FindAttribute Метод Нет
FindText Метод Нет
GetAttributeValue Метод Нет
GetBoundingRectangles Метод Нет
GetChildren Метод Нет
GetEnclosingElement Метод Нет
Gettext Метод Нет
Переместить Метод Нет
MoveEndpointByUnit Метод Нет
MoveEndpointByRange Метод Нет
Выберите пункт Метод Нет
ScrollIntoView Метод Нет

 

Для реализации интерфейса ITextRangeProvider2 требуются следующие дополнительные свойства и методы.

Обязательные члены Тип члена Примечания
ShowContextMenu Метод См. раздел "Реализация ShowContextMenu"

 

Шаблон элемента управления TextRange не имеет связанных событий.

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

В этом разделе описывается, как поставщик должен реализовывать различные методы интерфейсов ITextRangeProvider и ITextRangeProvider2 для поддержки шаблона элемента управления TextRange .

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

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

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

схема, показывающая позиции конечных точек диапазона текста до и после вызова expandtoenclosingunit

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

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

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

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

Схема, показывающая, как метод перемещения перемещает конечные точки диапазона между границами объектов и текстовых единиц

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

Схема, показывающая, как moveendpointbyunit перемещает конечную точку диапазона

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

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

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

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

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

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

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

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

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

Реализация ShowContextMenu

В ITextRangeProvider2::ShowContextMenu всегда должно отображаться контекстное меню в начальной конечной точке диапазона. Это должно быть эквивалентно тому, что произойдет, если пользователь нажал клавишу контекстного меню или SHIFT+F10 с точкой вставки в начале диапазона.

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

Взаимодействие с системным курсором

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

Если элемент управления содержит выделенный текст, текущий макет шаблона элемента управления Текст не позволяет напрямую связать расположение точки вставки с определенным текстовым диапазоном. Поставщик должен отслеживать выделение текста и устанавливать расположение точки вставки соответствующим образом. Так как выделение текста обычно выполняется путем перемещения точки вставки, удерживая нажатой клавишу SHIFT или CTRL или и то и другое, поставщик может отслеживать выделение текста, проверяя состояние этих клавиш при каждом изменении выделения.

Так как платформа специальных возможностей обеспечивает встроенную поддержку системного курсора, но не пользовательского курсора, текстовые элементы управления должны по возможности использовать курсор системы. Элементы управления, использующие настраиваемый курсор, могут обеспечить доступность курсора, создав системный курсор с теми же размерами, что и настраиваемый курсор, и размещение системного курсора в том же расположении в пользовательском интерфейсе элемента управления, что и пользовательская курсор, то есть в точке вставки. В качестве альтернативы элемент управления, использующий настраиваемый курсор, может реализовать поставщик Microsoft Active Accessibility для OBJID_CARET предоставлять сведения о специальных возможностях непосредственно для пользовательского курсора.

Дополнительные сведения о системных курсорах см. в разделе Курсоры.

Чтобы проверить, правильно ли ваш элемент управления предоставляет расположение системного курсора, используйте средства "Просмотр и доступность Наблюдателя за событиями ".

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

Типы элементов управления и поддерживаемые ими шаблоны элементов управления

Тип элемента управления "Текст"

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

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

Общие сведения о шаблонах элементов управления модели автоматизации пользовательского интерфейса

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

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