Интерфейс ITextRange (tom.h)

Объекты ITextRange — это мощные средства редактирования и привязки данных, которые позволяют программе выделять текст в истории, а затем просматривать или изменять этот текст.

Наследование

Интерфейс ITextRange наследуется от интерфейса IDispatch . ITextRange также имеет следующие типы элементов:

Методы

Интерфейс ITextRange содержит следующие методы.

ITextRange::CanEdit Определяет, можно ли изменить указанный диапазон.
ITextRange::CanPaste Определяет, можно ли вставить объект данных с использованием указанного формата в текущий диапазон.
ITextRange::ChangeCase Изменяет регистр букв в этом диапазоне в соответствии с параметром Type.
ITextRange::Collapse Сворачивает указанный текстовый диапазон в вырожденную точку в начале или конце диапазона.
ITextRange::Copy Копирует текст в объект данных.
ITextRange::Cut Вырезает обычный или форматированный текст в объект данных или буфер обмена в зависимости от параметра pVar.
ITextRange::D elete Имитирует клавиши DELETE и BACKSPACE с нажатием клавиши CTRL и без нее.
ITextRange::EndOf Перемещает концы этого диапазона в конец последней перекрывающейся единицы в диапазоне.
ITextRange::Expand Расширяет этот диапазон таким образом, чтобы все содержащиеся в нем частичные единицы были полностью автономными.
ITextRange::FindText Выполняет поиск текста, заданного параметром bstr, до числа символов. Начальная позиция и направление также задаются параметром Count, а критерии соответствия задаются флагами.
ITextRange::FindTextEnd Выполняет поиск строки bstr до count символов, начиная с end cp диапазона.
ITextRange::FindTextStart Выполняет поиск по строке bstr до числа символов, начиная с начального cp (cpFirst) диапазона.
ITextRange::GetChar Возвращает символ в начальной позиции диапазона.
ITextRange::GetDuplicate Возвращает дубликат этого объекта диапазона.
ITextRange::GetEmbeddedObject Извлекает указатель на внедренный объект в начале указанного диапазона, то есть в cpFirst. Диапазон должен быть либо точкой вставки, либо выбрать только внедренный объект.
ITextRange::GetEnd Возвращает позицию конечного символа диапазона.
ITextRange::GetFont Возвращает объект ITextFont с атрибутами символов указанного диапазона.
ITextRange::GetFormattedText Возвращает объект ITextRange с отформатированным текстом указанного диапазона.
ITextRange::GetIndex Извлекает индекс истории параметра Unit в указанной позиции начального символа диапазона.
ITextRange::GetPara Возвращает объект ITextPara с атрибутами абзаца указанного диапазона.
ITextRange::GetPoint Извлекает экранные координаты для позиции начального или конечного символа в текстовом диапазоне, а также внутристрочного положения.
ITextRange::GetStart Возвращает начальную позицию символа диапазона.
ITextRange::GetStoryLength Возвращает количество символов в истории диапазона.
ITextRange::GetStoryType Получение типа истории диапазона.
ITextRange::GetText Возвращает обычный текст в этом диапазоне. Свойство Text является свойством по умолчанию интерфейса ITextRange.
ITextRange::InRange Определяет, находится ли этот диапазон внутри или в том же тексте, что и указанный диапазон.
ITextRange::InStory Определяет, совпадает ли история этого диапазона с историей указанного диапазона.
ITextRange::IsEqual Определяет, имеет ли этот диапазон те же позиции символов и историю, что и для указанного диапазона.
ITextRange::Move Перемещает точку вставки вперед или назад на указанное количество единиц. Если диапазон является неразрожденным, диапазон сворачивается до точки вставки на обоих концах, в зависимости от количества, а затем перемещается.
ITextRange::MoveEnd Перемещает конечную позицию диапазона.
ITextRange::MoveEndUntil Перемещает конец диапазона к позиции первого найденного символа, который находится в наборе символов, заданном в Cset, при условии, что символ находится в пределах count символов конца диапазона.
ITextRange::MoveEndWhile Перемещает конец диапазона либо число символов, либо только мимо всех смежных символов, которые находятся в наборе символов, заданном параметром Cset, в зависимости от того, какой из значений меньше.
ITextRange::MoveStart Перемещает начальную позицию диапазона на указанное количество единиц в указанном направлении.
ITextRange::MoveStartUntil Перемещает начальную позицию диапазона позиции первого найденного символа, который находится в наборе символов, заданном параметром Cset, при условии, что символ находится в строке Count символов начальной позиции.
ITextRange::MoveStartWhile Перемещает начальную позицию диапазона либо число символов, либо только мимо всех смежных символов, которые находятся в наборе символов, заданном параметром Cset, в зависимости от того, какой из значений меньше.
ITextRange::MoveUntil Выполняет поиск первого символа в наборе символов, заданном Cset, до числа символов. При обнаружении символа диапазон свернут до этой точки. Начало поиска и направление также указываются параметром Count.
ITextRange::MoveWhile Начинается с указанного конца диапазона и выполняет поиск, в то время как символы принадлежат к набору, указанному в Cset, а число символов меньше или равно Count.
ITextRange::P aste Вставляет текст из указанного объекта данных.
ITextRange::ScrollIntoView Прокручивает указанный диапазон в представление.
ITextRange::Select Задает начальную и конечную позиции, а также значения истории активного выделенного фрагмента, соответствующие позициям этого диапазона.
ITextRange::SetChar Задает символ в начальной позиции диапазона.
ITextRange::SetEnd Задает конечную позицию диапазона.
ITextRange::SetFont Задает атрибуты символов этого диапазона в соответствии с атрибутами указанного объекта ITextFont.
ITextRange::SetFormattedText Задает форматированный текст этого текста диапазона в форматированный текст указанного диапазона.
ITextRange::SetIndex Изменяет этот диапазон на указанную единицу истории.
ITextRange::SetPara Задает атрибуты абзаца этого диапазона, соответствующие атрибутам указанного объекта ITextPara.
ITextRange::SetPoint Изменяет диапазон на основе указанной точки в точке или вверх (в зависимости от расширения) точки (x, y), выровненной в соответствии с Типом.
ITextRange::SetRange Настраивает конечные точки диапазона в соответствии с указанными значениями.
ITextRange::SetStart Задает позицию символа для начала этого диапазона.
ITextRange::SetText Задает текст в этом диапазоне.
ITextRange::StartOf Перемещает конец диапазона в начало первой перекрывающейся единицы в диапазоне.

Комментарии

Несколько текстовых диапазонов могут быть активными и совместно работать над одной и той же историей и развиваться вместе с историей. Например, если один текстовый диапазон удаляет указанный текст перед другим текстовым диапазоном, последний отслеживает изменение. В этом смысле текстовые диапазоны похожи на закладки Microsoft Word, которые также отслеживают изменения редактирования. Однако закладки не могут изменять текст, а текстовые диапазоны — . Кроме того, диапазоны позволяют управлять текстом без изменения выделенного фрагмента или буфера обмена, которые являются ценными для конечных пользователей. Интерфейс ITextSelection наследуется от ITextRange и добавляет некоторые методы и свойства, ориентированные на пользовательский интерфейс, как описано в разделе ITextSelection.

Текстовый диапазон можно просмотреть с помощью методов, основанных на положениях символов. В частности, диапазон текста характеризуется следующими особенностями:

• Первая позиция символа cpFirst, которая указывает на точку вставки непосредственно перед первым символом (относительно начала истории) в диапазоне.
• Позиция пределаcpLim, которая указывает на точку вставки сразу после последнего символа в диапазоне.

Первый персонаж в истории имеет cpFirst = ноль. Если аргумент cp имеет значение больше, чем число символов в истории, вместо него используется количество символов в истории. Если аргумент CP отрицательный, вместо него используется ноль. Для тех, кто знаком с Microsoft Visual Basic для приложений, вызовите свойство cpFirstStart и свойство cpLimEnd (хотя начальная позиция диапазона также является концом).

На следующем рисунке позиции символов представлены линиями, разделяющими буквы. Соответствующие значения позиции символов задаются под строками. Диапазон, начинающийся с cpFirst = 5 и заканчивающийся cpLim = 7, содержит двухбуквенный слово . Если на этом рисунке показан полный текст в рассказе, длина рассказа равна 30.

Длина диапазона определяется cpLim - cpFirst или эквивалентно значением End — Start. Диапазон с нулевой длиной называется вырожденным или пустым диапазоном и имеет одинаковые значения cp*, то есть cpFirst = cpLim. Примером вырожденного диапазона является текущая точка вставки. Выбор, отличный от NULL, является примером неразрожденного диапазона.

Предположим, что диапазон от 5 до 7, на который указывают затеняемые ячейки на предыдущем рисунке, должен удалить текст (см. раздел Удаление), превращая себя в точку вставки. Диапазон от 25 до 29 автоматически отслеживает его содержимое, а именно текст слова. На следующем рисунке показан результат.

На этом рисунке диапазон для текста теперь автоматически изменен на cpFirst = 23 и cpLim = 27. Владельцу диапазона не нужно беспокоиться об обновлении значений позиции символов диапазона при редактировании.

Имена методов перемещения указывают, какой конец следует переместить, но обратите внимание, что если какой-либо метод пытается переместить один конец диапазона за другой, оба конца перемещаются в целевую позицию. В результате точка вставки находится в целевой позиции. Концепция заключается в том, что cpFirst и cpLim всегда должны подчиняться фундаментальному условию

0 <= cpFirst<= cpLim<= # символы в истории

или эквивалентно для диапазона r, 0 <= r. Start <= r. End <= r. StoryLength, который является тем, что вы ожидаете от названий этих количеств.

Еще одна важная особенность заключается в том, что все истории содержат окончательный символ cr (0xD) в конце. Так что даже пустая история имеет один характер, а именно окончательный CR. Диапазон может выбрать этот символ, но не может стать точкой вставки за его пределами. Чтобы увидеть, как это работает, попробуйте выбрать окончательный cr в документе Word, а затем нажмите клавишу СТРЕЛКА ВПРАВО, чтобы свернуть его. Дерево каталогов будет свернуто до окончательного cr, но cr не может быть удален. Текстовая объектная модель (TOM) работает так же. Итак, если r. Start <= r. End, затем r. End <= (r. StoryLength – 1). Обсуждение удаления cr см. в разделе Удаление.

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

Unit	Значение	Значение
tomCharacter	1	Символ.
tomWord	2	Word.
tomSentence	3	Предложение.
tomParagraph	4	Пункт.
tomLine	5	Линия (отображается).
tomStory	6	Строй.
tomScreen	7	Экран (как для PAGE UP/PAGE DOWN).
tomSection	8	Разделе.
tomColumn	9	Столбец таблицы.
tomRow	10	Строка таблицы.
tomWindow	11	Верхняя левая или нижняя правая часть окна.
tomCell	12	Ячейка таблицы.
tomCharFormat	13	Выполнение постоянного форматирования символов.
tomParaFormat	14	Выполнение постоянного форматирования абзаца.
tomTable	15	Таблица.
tomObject	16	Внедренный объект.

 

Большинство значений Unit понятны. Однако для дополнительной ясности приведены следующие описания.

tomWord

Константой tomWord является конец абзаца или диапазон буквенно-цифровых символов или знаков препинания, включая все последующие пробелы. Чтобы получить представление о tomWord на экране, watch, как перемещается курсор при нажатии клавиш CTRL+СТРЕЛКА ВПРАВО (—>) или CTRL+СТРЕЛКА ВЛЕВО (<—) в Word документе.

tomSentence

Константой tomSentence описывается строка текста, заканчивающаяся точкой, вопросительным знаком или восклицательным знаком, за которой следует один или несколько пробелов ASCII (от 9 до 0xd и 0x20) или разделитель абзаца Юникода (0x2029). Пробел в конце является частью предложения. Последнее предложение в рассказе не обязательно содержит точку, вопросительный знак или восклицательный знак. Начало истории квалифицируется как начало tomSentence, даже если строка там не квалифицируется как предложение грамматически. Другие предложения должны следовать концу предложения и не могут начинаться с точки, вопросительного знака или восклицательного знака.

tomParagraph

Константа tomParagraph — это строка текста, оканчиваемая знаком конца абзаца (CRLF, CR, VT (для SHIFT+ВВОД), LF, FF или 0x2029). В движках TOM всегда есть знак конца абзаца, допускающий отмену, в конце истории. Таким образом, все истории TOM автоматически имеют по крайней мере один tomWord, один tomSentence и один tomParagraph.

tomLine

Константа tomLine соответствует одной строке текста на дисплее при условии, что дисплей связан с диапазоном. Если с диапазоном не связано ни единое отображение, tomLine обрабатывается как tomParagraph. Выбор автоматически имеет отображение и диапазон, который является дубликатом (см. Раздел GetDuplicate). Другие диапазоны могут не иметь отображения в зависимости от подсистемы TOM и контекста.

Методы, которые перемещают один или оба конца с точки зрения единицы, такие как Move, MoveEnd и MoveStart, зависят от подписанного аргумента Count . За исключением команд геометрического смещения ITextSelection , если значение Count больше нуля, перемещаемые концы перемещаются вперед (к концу истории), а если значение Count меньше нуля, то концы перемещаются назад (к началу). Значение по умолчанию Count для этих методов Перемещения равно 1. Эти методы пытаются переместить единицы подсчета, но перемещение никогда не выходит за пределы истории.

Методы, которые перемещают один или оба конца путем сопоставления символьных строк или строковых шаблонов, таких как MoveWhile, MoveEndWhile и MoveStartWhile, могут перемещаться до максимального числа символов, заданного аргументом Count со знаком. Если значение Count больше нуля, то перемещаемые концы перемещаются вперед, а если значение Count меньше нуля, то концы перемещаются в обратном направлении. Определены два специальных значения Count : tomForward и tomBackward. Эти значения гарантированно достигнут конца и начала истории соответственно. Значение по умолчанию для параметра Count — tomForward.

В методах Move*, которые преобразуют неразрожденный диапазон в вырожденный, например Move, MoveWhile и MoveUntil, cpFirst изменяется, если count является отрицательным, и cpLim изменяется, если count является положительным. После этого перемещения другой конец диапазона также перемещается в новое расположение. Дополнительные сведения о подсчете см. в разделе Об отдельных методах. Для неразрожденных диапазонов методы MoveStart, MoveEnd, MoveStartWhile, MoveEndWhile, MoveStartUntil и MoveEndUntil перемещают начальную позицию (Start) или конечную позицию (End).

Чтобы выбрать единицу, соответствующую непрерывному диапазону, например tomWord, tomSentence и tomParagraph, используйте метод MoveEnd . Чтобы выбрать единицу, соответствующую несвязанному диапазону, например tomObject, используйте метод EndOf , так как следующий объект может возникнуть после существенного промежуточного текста, если он вообще есть. Чтобы выбрать единицу tomCell, диапазон должен находиться внутри таблицы.

Ниже приведены примеры и дальнейшее объяснение аргументов Count и Unit . Обратите внимание, что подсистемы TOM могут поддерживать не все единицы, указанные в таблице выше. Например, полнофункционированные элементы управления редактированием не предлагают концепции разделов, а возвращают E_NOTIMPL при указании tomSection. Однако если подсистема TOM поддерживает единицу, она имеет значение индекса, заданное в таблице.

Приложения обычно не реализуют интерфейс ITextRange . Текстовые решения Майкрософт, такие как элементы управления с расширенным редактированием, реализуют ITextRange как часть реализации TOM.

Приложения могут получить указатель ITextRange , вызвав метод Range .

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	tom.h

См. также раздел

Основные понятия

IDispatch

Текстовая объектная модель

Использование текстовой объектной модели