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

public interface 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)

Структура

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

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

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

• getDefaultRootElement()
• getRootElements()

Изменения

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

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

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

Уведомления

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

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

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

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

Если буфер истории отменяет последнее действие (т.е. отменяется последнее 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)

Для получения дополнительной информации о классе Document, см. Swing Connection и, в частности, статью Element Interface.