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

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. В модели событий JavaBeans после отправки уведомления об событии все слушатели должны быть уведомлены перед любыми дальнейшими изменениями источника события. Более того, порядок доставки не гарантируется.

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

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

Теперь предположим, что компонент, показанный справа, изменяет тот же самый документ. Опять же, документ отправляет 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 см. на странице The Swing Connection и, в частности, статье The Element Interface.

Поля

StreamDescriptionProperty

static final String StreamDescriptionProperty

Имя свойства для описания потока, используемого для инициализации документа. Это следует использовать, если документ был инициализирован из потока и что-то известно о потоке.

См. также:

Значения константных полей

TitleProperty

static final String TitleProperty

Имя свойства для заголовка документа, если он есть.

См. также:

Значения константных полей

Методы

getLength

int getLength()

Возвращает количество символов содержимого, в настоящее время находящегося в документе.

Возвращает:

количество символов >= 0

addDocumentListener

void addDocumentListener(DocumentListener listener)

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

Параметры:

listener - наблюдатель для регистрации

См. также:

removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener

void removeDocumentListener(DocumentListener listener)

Удаляет данного наблюдателя из списка уведомлений, чтобы он больше не получал обновлений об изменениях.

Параметры:

listener - наблюдатель для регистрации

См. также:

addDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener

void addUndoableEditListener(UndoableEditListener listener)

Регистрирует данного наблюдателя, чтобы он начинал получать уведомления при выполнении отменяемых изменений в документе.

Параметры:

listener - наблюдатель для регистрации

См. также:

UndoableEditEvent

removeUndoableEditListener

void removeUndoableEditListener(UndoableEditListener listener)

Удаляет данного наблюдателя из списка уведомлений, чтобы он больше не получал обновлений.

Параметры:

listener - наблюдатель для регистрации

См. также:

UndoableEditEvent

getProperty

Object getProperty(Object key)

Получает свойства, связанные с документом.

Параметры:

key - ключ свойства, не являющийся null

Возвращает:

свойства

См. также:

putProperty(Object, Object)

putProperty

void putProperty(Object key,
                 Object value)

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

Параметры:

key - ключ свойства, не являющийся null

value - значение свойства

См. также:

getProperty(Object)

remove

void remove(int offs,
            int len)
     throws BadLocationException

Параметры:

offs - смещение от начала >= 0

len - количество символов для удаления >= 0

Исключения:

BadLocationException - некоторая часть диапазона удаления не являлась допустимой частью документа. Местоположение в исключении – это первая обнаруженная невалидная позиция.

См. также:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

void insertString(int offset,
                  String str,
                  AttributeSet a)
           throws BadLocationException

Параметры:

offset - смещение в документе для вставки содержимого >= 0. Все позиции, отслеживающие изменения в или после данной позиции, сместятся.

str - вставляемая строка

a - атрибуты для сопоставления с вставляемым содержимым. Может быть null, если атрибутов нет.

Исключения:

BadLocationException - заданная позиция вставки не является допустимой позицией в документе

См. также:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

getText

String getText(int offset,
               int length)
        throws BadLocationException

Извлекает текст, содержащийся в заданной части документа.

Параметры:

offset - смещение в документе, представляющее желаемый старт текста >= 0

length - длина желаемой строки >= 0

Возвращает:

текст, в строке длиной >= 0

Исключения:

BadLocationException - часть заданного диапазона не являлась допустимой частью документа. Местоположение в исключении – это первая обнаруженная невалидная позиция.

getText

void getText(int offset,
             int length,
             Segment txt)
      throws BadLocationException

  int nleft = doc.getDocumentLength();
   Segment text = new Segment();
   int offs = 0;
   text.setPartialReturn(true);
   while (nleft > 0) {
       doc.getText(offs, nleft, text);
       // do someting with text
       nleft -= text.count;
       offs += text.count;
   }

Параметры:

offset - смещение в документе, представляющее желаемый старт текста >= 0

length - длина желаемой строки >= 0

txt - объект Segment для возврата текста

Исключения:

BadLocationException - часть заданного диапазона не являлась допустимой частью документа. Местоположение в исключении – это первая обнаруженная невалидная позиция.

getStartPosition

Position getStartPosition()

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

Возвращает:

позицию

getEndPosition

Position getEndPosition()

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

Возвращает:

позицию

createPosition

Position createPosition(int offs)
                 throws BadLocationException

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

Параметры:

offs - смещение от начала документа >= 0

Возвращает:

позицию

Исключения:

BadLocationException - если заданная позиция не представляет действительное местоположение в связанном документе

getRootElements

Element[] getRootElements()

Возвращает:

корневой элемент

getDefaultRootElement

Element getDefaultRootElement()

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

Возвращает:

корневой элемент

render

void render(Runnable r)

Позволяет безопасно отобразить модель в присутствии конкурентности, если модель поддерживает асинхронное обновление. Указанный runnable будет выполнен таким образом, что позволит ему безопасно прочитать модель без изменений во время выполнения runnable. Сам runnable не должен вносить никаких изменений.

Параметры:

r - Runnable для отображения модели