Интерфейс Document

Document — это контейнер для текста, который служит моделью для текстовых компонентов Swing. Цель этого интерфейса — охватить как самые простые потребности (обычное текстовое поле), так и сложные (например, документ HTML или XML).

Содержимое

На самом простом уровне текст можно представить в виде линейной последовательности символов. Для поддержки интернационализации текстовая модель Swing использует символы Unicode. Последовательность символов, отображаемая в текстовом компоненте, обычно называется содержимым компонента.

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

В примере, если содержимым документа является последовательность «The quick brown fox», показанная на предыдущей диаграмме, местоположение непосредственно перед словом «The» равно 0, а местоположение после слова «The» и перед следующим за ним пробелом равно 3. Вся последовательность символов в слове «The» называется диапазоном.

Следующие методы предоставляют доступ к символьным данным, составляющим содержимое.

• getLength()
• getText(int, int)
• getText(int, int, javax.swing.text.Segment)

Структура

Текст редко представлен просто как неструктурированное содержимое. Обычно с текстом связана структура определённого типа. Конкретная моделируемая структура зависит от реализации Document. Это может быть как отсутствие структуры (например, простое текстовое поле), так и структура, подобная показанной на диаграмме ниже.

Единица структуры (то есть узел дерева) обозначается интерфейсом Element. Каждому Element можно назначить набор атрибутов. Эти атрибуты (пары имя/значение) определяются интерфейсом AttributeSet.

Следующие методы предоставляют доступ к структуре документа.

• getDefaultRootElement()
• getRootElements()

Изменения

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

Следующие методы связаны с изменением содержимого документа:

• insertString(int, java.lang.String, javax.swing.text.AttributeSet)
• remove(int, int)
• createPosition(int)

Уведомления

Об изменениях в Document необходимо уведомлять заинтересованных наблюдателей. Уведомления об изменениях соответствуют правилам модели событий, определённым для JavaBeans. Согласно модели событий JavaBeans, после отправки уведомления о событии необходимо уведомить всех слушателей, прежде чем в источнике события произойдут какие-либо дальнейшие изменения. Кроме того, порядок доставки не гарантируется.

Уведомления предоставляются в виде двух отдельных событий: DocumentEvent и UndoableEditEvent. Если изменение вносится в Document через его API, всем зарегистрированным DocumentListeners отправляется DocumentEvent. Если реализация Document поддерживает отмену и повтор изменений, всем зарегистрированным UndoableEditListeners отправляется UndoableEditEvent. Если отменяемое изменение отменено, Document должен сгенерировать DocumentEvent, чтобы указать, что он снова изменился. Однако в этом случае не следует генерировать UndoableEditEvent, поскольку источником изменения является само это изменение, а не изменение, внесённое в Document через его API.

Согласно диаграмме выше, предположим, что компонент слева изменяет объект документа, представленный синим прямоугольником. Документ отвечает отправкой DocumentEvent обоим представлениям компонентов и отправляет UndoableEditEvent слушающей логике, которая ведёт буфер истории.

Теперь предположим, что компонент справа изменяет тот же документ. Документ снова отправляет DocumentEvent обоим представлениям компонентов и отправляет UndoableEditEvent слушающей логике, которая ведёт буфер истории.

Если затем выполнить откат буфера истории (то есть отменить последнее UndoableEdit), обоим представлениям отправляется DocumentEvent, и они отражают отменённое изменение документа (то есть удаление изменения, внесённого правым компонентом). Если снова выполнить откат буфера истории, отменив ещё одно изменение, обоим представлениям отправляется ещё один DocumentEvent, и они отражают отменённое изменение документа — то есть удаление изменения, внесённого левым компонентом.

Методы, связанные с отслеживанием изменений документа:

• addDocumentListener(DocumentListener)
• removeDocumentListener(DocumentListener)
• addUndoableEditListener(UndoableEditListener)
• removeUndoableEditListener(UndoableEditListener)

Свойства

Реализации Document обычно имеют некоторый набор свойств, связанных с ними во время выполнения. Два хорошо известных свойства — StreamDescriptionProperty, с помощью которого можно описать источник, из которого был получен Document, и TitleProperty, с помощью которого можно задать имя Document. С этими свойствами связаны следующие методы:

• getProperty(java.lang.Object)
• putProperty(java.lang.Object, java.lang.Object)

Обзор и советы по программированию

Element — важный интерфейс, используемый при создании Document. Он позволяет описывать различные структурные части документа, такие как абзацы, строки текста и даже элементы списков (в документах HTML). Концептуально интерфейс Element отражает некоторые особенности документов SGML. Поэтому, если вы знакомы с SGML, вам, возможно, уже понятны некоторые особенности интерфейса Element в Swing.

В модели документов текстового API Swing интерфейс Element определяет структурную часть Document, например абзац, строку текста или элемент списка в документе HTML.

Каждый Element является либо ветвью, либо листом. Если элемент является ветвью, метод isLeaf() возвращает false. Если элемент является листом, isLeaf() возвращает true.

У ветвей может быть любое количество дочерних элементов. У листьев дочерних элементов нет. Чтобы определить количество дочерних элементов ветви, можно вызвать getElementCount(). Чтобы определить родительский элемент Element, можно вызвать getParentElement(). У корневых элементов нет родителей, поэтому вызов getParentElement() для корневого элемента возвращает null.

Element представляет определённую область в Document, начинающуюся со startOffset и заканчивающуюся непосредственно перед endOffset. Начальное смещение элемента-ветви обычно совпадает с начальным смещением его первого дочернего элемента. Аналогично, конечное смещение элемента-ветви обычно совпадает с конечным смещением его последнего дочернего элемента.

Каждому Element соответствует AttributeSet, доступ к которому можно получить, вызвав getAttributes(). В Element AttributeSet по сути представляет собой набор пар ключ/значение. Эти пары обычно используются для разметки, например для определения цвета переднего плана элемента, размера шрифта и так далее. Однако определение того, что хранится в AttributeSet, зависит от модели и разработчика.

Получить корневой Element (или элементы) Document можно, вызвав методы getDefaultRootElement() и getRootElements(), определённые в интерфейсе Document.

Интерфейс Document отвечает за преобразование линейного представления символов в операции Element. Определение структуры Element зависит от реализации Document.

Класс PlainDocument

Класс PlainDocument определяет структуру Element, в которой у корневого узла есть дочерний узел для каждой строки текста в модели. На рисунке 1 показано, как две строки текста будут представлены в PlainDocument.

На рисунке 2 показано, как эти же две строки текста могут соответствовать фактическому содержимому:

Вставка текста в PlainDocument

Как уже упоминалось, PlainDocument содержит корневой Element, который, в свою очередь, содержит Element для каждой строки текста. При вставке текста в PlainDocument он создаёт необходимые Elements, чтобы для каждого символа новой строки существовал Element. Для примера предположим, что вы хотите вставить символ новой строки со смещением 2 на рисунке 2 выше. Для этого можно использовать метод Document insertString() со следующим синтаксисом:

document.insertString(2, "\n", null);

После вызова метода insertString() структура Element будет выглядеть так, как показано на рисунке 3.

В качестве другого примера предположим, что вы хотите вставить шаблон «new\ntext\n» со смещением 2, как показано ранее на рисунке 2. Результат этой операции показан на рисунке 4.

На предыдущих иллюстрациях после вставки изменяются имена Elements строк, чтобы соответствовать номерам строк. Обратите внимание, что при этом AttributeSets остаются прежними. Например, на рисунке 2 AttributeSet строки 2 совпадает с AttributeSet строки 4 на рисунке 4.

Удаление текста из PlainDocument

Удаление текста приводит к изменению структуры, если удаляемый фрагмент охватывает более одной строки. Рассмотрим удаление семи символов, начиная со смещения 1, показанного ранее на рисунке 3. В этом случае Element, представляющий строку 2, полностью удаляется, так как соответствующая ему область целиком входит в удаляемый фрагмент. Elements, представляющие строки 1 и 3, объединяются, поскольку лишь частично входят в удаляемый фрагмент. В результате получаем:

Класс DefaultStyledDocument

Класс DefaultStyledDocument, используемый для форматированного текста, содержит ещё один уровень Elements. Этот дополнительный уровень необходим, чтобы каждый абзац мог содержать текст с различными стилями. В двух абзацах, показанных на рисунке 6, первый абзац содержит два стиля, а второй — три.

На рисунке 7 показано, как эти же Elements могут соответствовать содержимому.

Вставка текста в DefaultStyledDocument

Как уже упоминалось, DefaultStyledDocument поддерживает структуру Element, в которой корневой Element содержит дочерний Element для каждого абзаца. В свою очередь, каждый из этих Elements абзаца содержит Element для каждого стиля текста в абзаце. Например, предположим, что у вас есть документ с одним абзацем, содержащим два стиля, как показано на рисунке 8.

Если теперь вы захотите вставить символ новой строки со смещением 2, снова воспользуйтесь методом insertString(), как показано ниже:

 styledDocument.insertString(2, "\n",
               styledDocument.getCharacterElement(0).getAttributes());

Результат этой операции показан на рисунке 9.

Важно отметить, что AttributeSet, переданный в insertString(), совпадает с атрибутами Style 1. Если бы AttributeSet, переданный в insertString(), не совпадал с ними, результат был бы таким, как показано на рисунке 10.

Удаление текста из DefaultStyledDocument

Удаление текста из DefaultStyledDocument аналогично удалению текста из PlainDocument. Единственное различие — дополнительный уровень Elements. Рассмотрим, что произойдёт, если удалить два символа со смещения 1 на рисунке 10 выше. Поскольку второй Element абзаца 1 полностью входит в удаляемый фрагмент, он будет удалён. Если атрибуты первого дочернего элемента абзаца 1 совпадают с атрибутами первого дочернего элемента абзаца 2, результат будет таким, как показано на рисунке 11.

Если атрибуты не совпадают, результат будет таким, как показано на рисунке 12.

Класс StyledDocument

Класс StyledDocument предоставляет метод с именем setCharacterAttributes(), позволяющий задать атрибуты символьных Elements в указанном диапазоне:

 public void setCharacterAttributes
         (int offset, int length, AttributeSet s, boolean replace);

Напомним, что на диаграммах в предыдущем разделе все показанные листовые Elements также являлись символьными Elements. Это означает, что метод setCharacterAttributes() можно использовать для задания их атрибутов.

Метод setCharacterAttributes() принимает четыре аргумента. Первый и второй аргументы задают область Document, которую нужно изменить. Третий аргумент указывает новые атрибуты (в виде AttributeSet), а четвёртый определяет, нужно ли добавить новые атрибуты к существующим (значение false) или заменить существующие атрибуты символьного Element новыми (значение true).

Например, предположим, что вы хотите изменить атрибуты первых трёх символов на рисунке 9, показанном ранее. Первому и второму аргументам, переданным в setCharacterAttributes(), будут соответствовать значения 0 и 3. Третьим аргументом будет AttributeSet, содержащий новые атрибуты. В рассматриваемом примере значение четвёртого аргумента не имеет значения.

Поскольку начальное и конечное смещения изменяемой области (0 и 3) совпадают с границами символьных Elements, изменение структуры не требуется. То есть изменятся только атрибуты стиля 1 символьного Element.

Теперь рассмотрим пример, требующий изменения структуры. Вместо первых трёх символов на рисунке 9 изменим первые два. Поскольку конечное смещение изменения (2) не совпадает с границей символьного Element, Element со смещением 2 необходимо разделить так, чтобы смещение 2 стало границей двух Elements. Вызов setCharacterAttributes() с начальным смещением 0 и длиной 2 даёт результат, показанный ранее на рисунке 10.

Изменение атрибутов абзаца в StyledDocument

Класс StyledDocument предоставляет метод с именем setParagraphAttributes(), который можно использовать для изменения атрибутов Element абзаца:

 public void setParagraphAttributes
        (int offset, int length, AttributeSet s, boolean replace);

Этот метод похож на setCharacterAttributes(), но позволяет изменять атрибуты Elements абзацев. Реализация StyledDocument определяет, какие Elements считаются абзацами. DefaultStyledDocument считает Elements абзацев родительскими Elements символьных Elements. Вызов этого метода не приводит к изменению структуры; изменяются только атрибуты Element абзаца.

Рекомендуется ознакомиться с EditorKit и View. View отвечает за отображение определённого Element, а EditorKit отвечает за ViewFactory, которая определяет, какое представление следует создать для данного Element.