|
<< Нажмите, чтобы показать Содержание >> Закладки в документах ТРВ-Редактора (TRichView) |
Каждому элементу может быть присвоена закладка – невидимая метка, которую можно использовать для перехода к указанной части документа.
В терминологии компонента такой объект называется «checkpoint» («контрольная точка»), но в этой справке мы будем пользоваться более традиционной терминологией.
▪название;
▪тег (такой же, как у элементов документа)
▪флажок RaiseEvent; если RaiseEvent=True, то TRichView вызывает событие OnCheckpointVisible когда закладка становится видимой (обычно в результате прокрутки окна компонента); эта функциональность работает в компоненте TRichView и не работает в TRichViewEdit (в текущей версии).
Ограничения
▪названия закладки не должны содержать символы #0, #1 и #2; в противном случае возможно сохранение некорректных документов в формате RVF;
▪следующие названия зарезервированы и не должны использоваться: '_footnoteN', '_endnoteN', '_sidenoteN', где N любое целое число.
Вы можете переключиться в режим показа закладок: включите опцию rvoShowCheckpoints в TRichView.Options. По умолчанию закладки отображаются в виде пунктирных горизонтальных линий с небольшим кружком в верхнем левом углу соответствующего элемента документа. Отображение закладок полезно в режиме редактирования.
Цвета закладок:
▪RichView.Style.CheckpointColor для обычных закладок (clGreen по умолчанию)
▪RichView.Style.CheckpointEvColor для закладок, у которых свойство RaiseEvent=True (clLime по умолчанию)
Вы можете рисовать закладки по-своему, см. TRVStyle.OnDrawCheckpoint.
Закладка обычно используется для определения её вертикальной координаты (относительно верха области документа) и прокрутки документа таким образом, чтобы связанный с этой закладкой элемент стал видимым. Существуют и другие интересные применения закладок.
Вы можете добавить закладку в конец документа, используя метод AddCheckpoint.
При добавлении нового элемента в конец документа последняя добавленная закладка связывается с этим элементом. Таким образом, TRichView может содержать любое количество закладок, связанных с элементами, и только одну закладку в конце документа.
Вы можете изменить свойства закладки с помощью метода SetCheckpointInfo и удалить её с помощью метода RemoveCheckpoint.
Остальные методы можно разделить на две группы:
1.Методы, возвращающие информацию о закладке. Эти методы возвращают значение, имеющее тип TCheckpointData.
2.Методы, извлекающие свойства закладки из значения TCheckpointData.
TCheckpointData является указателем. Если нижеперечисленные методы возвращают nil, значит такой закладки нет, элемент не связан с закладкой, и т.п.
▪GetFirstCheckpoint, GetNextCheckpoint(CheckpointData), GetLastCheckpoint, GetPrevCheckpoint(CheckpointData) позволяют получить список всех закладок в документе (за исключением закладок ячейках таблиц, см. ниже);
▪GetItemCheckpoint(ItemNo) возвращает закладку, связанную с указанным элементом документа;
▪GetCheckpointByNo(No) возвращает закладку по её номеру;
▪FindCheckpointByName(Name) возвращает первую закладку с указанным названием;
▪FindCheckpointByTag(Tag) возвращает первую закладку с указанным тегом;
▪событие OnCheckpointVisible (Sender: TRichView; CheckpointData: TCheckpointData); это событие происходит когда:
oRichView.CPEventKind = cpeWhenVisible и некоторая закладка (имеющая RaiseEvent=True) становится видимой (пример применения: в TRichView можно отмечать изображения закладками; когда изображение становится видимым, можно отобразить информацию о нём в отдельном окне)
oRichView.CPEventKind = cpeAsSectionStart; В этом режиме гарантируется, что последнее событие генерируется для видимой закладки или для закладки над видимой областью (пример применения: вы можете отмечать начало глав вашего документа закладками и создать оглавление в компоненте TListBox (один элемент TListBox = одна глава = закладка с RaiseEvent=True); если вы будете подсвечивать элемент TListBox, связанный с закладкой из последнего события, то в этом TListBox всегда будет подсвечено название главы, видимой в TRichView).
▪GetCheckpointInfo(CheckpointData, Tag, Name, RaiseEvent) возвращает тег, название и флажок RaiseEvent закладки;
▪GetCheckpointXY(CheckpointData, X,Y), GetCheckpointYEx(CheckpointData): TRVCoord получение координат закладки (наиболее полезна координата Y; вы можете передать её в метод RichView.ScrollTo);
▪GetCheckpointItemNo(CheckpointData) : Integer возвращает номер элемента документа, связанного с указанной закладкой; для закладки в самом конце документа (не связанной с элементом) возвращает -1.
▪GetCheckpointNo(CheckpointData): Integer возвращает номер закладки;
▪GetCheckpointY(no): TRVCoord – то же что GetCheckpointYEx(GetCheckpointByNo(No));
Первая группа методов содержит операции редактирования, аналогичные SetCheckpointInfo и RemoveCheckpoint:
▪SetCheckpointInfoEd устанавливает закладку у указанного элемента (операция редактирования);
▪RemoveCheckpointEd удаляет закладку у указанного элемента (операция редактирования).
Вторая группа включает методы, работающие с элементом документа, находящимся в позиции каретки (если каретка между элементами, то они работают с элементом слева):
▪GetCurrentCheckpoint возвращает закладку элемента в позиции каретки;
▪SetCurrentCheckpointInfo устанавливает/изменяет закладку у элемента в позиции каретки (операция редактирования);
▪RemoveCurrentCheckpoint удаляет закладку у элемента в позиции каретки (операция редактирования);
Третья группа включает методы, работающие с закладкой в позиции каретки:
▪InsertCheckpoint вставляет закладку в позицию каретки (то есть устанавливает/изменяет закладку у элемента справа от каретки; если каретка находился посередине текстового элемента, метод предварительно разделяет этот элемент на два в позиции каретки (операция редактирования);
▪GetCheckpointAtCaret возвращает закладку, находящуюся точно в позиции каретки;
▪RemoveCheckpointAtCaret удаляет закладку, находящуюся точно в позиции каретки (операция редактирования).
В HTML, закладки сохраняются как якоря (<a name>). Может быть использовано либо название, либо номер закладки, см. HTMLSaveProperties.UseCheckpointNames. Ссылки на закладки начинаются с символа '#'. При импорте HTML, якоря импортируются как закладки. Опционально, атрибуты "id" HTML-элементов могут быть импортированы как закладки, см. HTMLReadProperties.IDAsCheckpoints.
В RTF и DocX, закладки сохраняются как RTF/DocX-закладки нулевой длины (с использованием названий закладок). При импорте RTF или DocX, начало RTF/DocX-закладки импортируется как закладка ТРВ-Редактора (с использованием названий закладок). При чтении RTF или DocX, гиперссылки на закладки импортируются как гиперссылки, начинающиеся с символа '#'. При записи RTF или DocX, гиперссылки, начинающиеся с символа '#' сохраняются как гиперссылки на закладки.
В RTF и DocX есть ограничения на длину и состав символов названия закладки. TRichView автоматически корректирует названия закладок при сохранении в эти форматы, но не корректирует гиперссылки на закладки. Поэтому, если вы работаете с файлами RTF и DocX, следует ограничить названия закладок, не допуская несовместимые названия.
Перечисление всех закладок в документе (за исключением закладок в ячейках таблиц). Этот метод очень быстр даже для больших документов, поскольку все закладки организованы в специальный список.
var Tag: TRVTag;
Name: TRVUnicodeString;
RaiseEvent: Boolean;
CheckpointData: TCheckpointData;
begin
CheckpointData := MyRichView.GetFirstCheckPoint;
while CheckpointData<>nil do begin
MyRichView.GetCheckpointInfo(CheckpointData,Tag,Name,RaiseEvent);
// обработка этой закладки
...
CheckpointData := MyRichView.GetNextCheckpoint(CheckpointData);
end;
end;
Перечисление всех закладок в документе, включая закладки в ячейках таблиц.
procedure EnumCheckpoints(RVData: TCustomRVData);
var i,r,c: Integer;
table: TRVTableItemInfo;
Tag: TRVTag;
Name: TRVUnicodeString;
RaiseEvent: Boolean;
CheckpointData: TCheckpointData;
begin
for i := 0 to RVData.ItemsCount-1 do begin
CheckpointData := RVData.GetItemCheckpoint(i);
if CheckpointData<>nil then begin
RVData.GetCheckpointInfo(CheckpointData,Tag,Name,RaiseEvent);
// обработка этой закладки
...
end;
if RVData.GetItem(i) is TRVTableItemInfo then
begin
table := TRVTableItemInfo(RVData.GetItem(i));
for r := 0 to table.RowCount-1 do
for c := 0 to table.ColCount-1 do
if table.Cells[r,c]<>nil then
EnumCheckpoints(table.Cells[r,c].GetRVData);
end;
end;
end;
Вызов:
EnumCheckpoints(MyRichView.RVData);
Во втором примере метод RVData.GetCheckpointXY возвратит координаты закладки относительно верхнего левого угла этого объекта RVData (это может быть левый верхний угол ячейки). Чтобы получить абсолютные координаты этой контрольной точки в документе (для MyRichView.ScrollTo), необходимо получить координаты верхнего левого угла этого объекта RVData (TCustomRVFormattedData(RVData).GetOriginEx(X,Y)), относительные координаты закладки (TCustomRVFormattedData(RVData).GetCheckpointXY(X,Y)) и сложить их.
Свойства и события TRVStyle:
CheckpointColor, CheckpointEvColor, OnDrawCheckpoint
Свойства TRichView:
События TRichView:
Методы TRichView:
AddCheckpoint, SetCheckpointInfo, RemoveCheckpoint,·GetFirstCheckpoint, GetNextCheckpoint, GetItemCheckpoint, GetCheckpointByNo, FindCheckpointByName, FindCheckpointByTag, GetCheckpointInfo, GetCheckpointXY, GetCheckpointYEx, GetCheckpointItemNo, GetCheckpointNo, GetCheckpointY
Методы TRichViewEdit:
GetCurrentCheckpoint, SetCheckpointInfoEd, RemoveCheckpointEd