Документация интерфейса

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

Содержимое

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

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

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

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

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

Структура

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

Единицей структуры (т.е. узлом дерева) является интерфейс 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, будет отправлено событие DocumentEvent всем зарегистрированным DocumentListeners. Если реализация Document поддерживает возможности отмены/повторного выполнения, будет отправлено событие UndoableEditEvent всем зарегистрированным UndoableEditListener. Если действие, подлежащее отмене, отменено, из документа должно быть отправлено событие DocumentEvent, чтобы указать, что он снова изменился. В этом случае не должно генерироваться UndoableEditEvent, так как это действие является источником изменения, а не изменением в Document, произведённым через его API.

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

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

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

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

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

Свойства

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

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

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

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

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

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

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

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

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

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

Интерфейс Document отвечает за перевод линейного представления символов в операции с элементами. Каждая реализация Document определяет структуру элементов.

Класс PlainDocument

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

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

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

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

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

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

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

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

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

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

Класс Default StyledDocument

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

Рисунок 7 показывает, как те же самые элементы могут отображаться в содержимом.

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

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

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

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

Этот оператор приведет к результату, показанному на рисунке 9.

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

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

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

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

Класс StyledDocument

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

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

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

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

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

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

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

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

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

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

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

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