javax.swing.text

Интерфейсный Документ

Все Известные Подынтерфейсы:

StyledDocument

Все Известные Классы с реализацией:

AbstractDocument, DefaultStyledDocument, HTMLDocument, PlainDocument

public interface Document

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

Контент

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

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

В примере, если контент документа является последовательностью "Быстрая коричневая лиса," как показано в предыдущей схеме, расположение непосредственно перед тем, как слово "The" 0, и расположение после слова "The" и перед пробелом, который следует, это 3. Вся последовательность символов в последовательности вызывала диапазон.

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

• getLength ()
• getText (интервал, интервал)
• getText (интервал, интервал, Сегмент)

Структура

Текст редко представляется просто как невыразительный контент. Скорее тексту обычно связывали своего рода структуру с этим. Точно то, какая структура моделируется, до определенной реализации Документа. Это не могло бы быть столь же просто как никакая структура (то есть простое текстовое поле), или это могло бы быть что-то как схема ниже.

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

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

• getDefaultRootElement
• getRootElements

Мутации

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

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

• insertString (интервал, Строка, AttributeSet)
• удалите (интервал, интервал)
• createPosition (интервал)

Уведомление

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

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

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

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

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

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

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

Свойства

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

• getProperty (Объект)
• putProperty (Объект, Объект)

Для получения дополнительной информации по Document класс, см. Соединение Swing и наиболее особенно статью, Интерфейс Элемента.

См. Также:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener, Element, Position, AttributeSet

Полевая Сводка

Поля

Модификатор и Тип	Поле и Описание
static String	StreamDescriptionProperty Имя свойства для описания потока, используемого, чтобы инициализировать документ.
static String	TitleProperty Имя свойства для заголовка документа, если есть тот.

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
void	addDocumentListener(DocumentListener listener) Регистрирует данного наблюдателя, чтобы начать получать уведомления, когда изменения производятся в документе.
void	addUndoableEditListener(UndoableEditListener listener) Регистрирует данного наблюдателя, чтобы начать получать уведомления, когда невыполнимые редактирования делаются к документу.
Позиция	createPosition(int offs) Этот метод позволяет приложению отмечать место в последовательности символьного контента.
Элемент	getDefaultRootElement() Возвращает корневой элемент, на котором представления должны быть основаны, если некоторый другой механизм для того, чтобы присвоить представления структурам элемента не обеспечивается.
Позиция	getEndPosition() Возвращает позицию, которая представляет конец документа.
int	getLength() Число возвратов символов контента в настоящий момент в документе.
Объект	getProperty(Object key) Связали свойства с документом.
Элемент[]	getRootElements() Возвраты все корневые элементы, которые определяются.
Позиция	getStartPosition() Возвращает позицию, которая представляет запуск документа.
Строка	getText(int offset, int length) Выбирает текст, содержавший в пределах данной части документа.
void	getText(int offset, int length, Segment txt) Выбирает текст, содержавший в пределах данной части документа.
void	insertString(int offset, String str, AttributeSet a) Вставляет строку контента.
void	putProperty(Object key, Object value) Связывает свойство с документом.
void	remove(int offs, int len) Удаляет часть контента документа.
void	removeDocumentListener(DocumentListener listener) Нерегистрирует данного наблюдателя от списка уведомления, таким образом, он больше не будет получать обновления изменения.
void	removeUndoableEditListener(UndoableEditListener listener) Нерегистрирует данного наблюдателя от списка уведомления, таким образом, он больше не будет получать обновления.
void	render(Runnable r) Позволяет модели быть безопасно представленной в присутствии параллелизма, если модель поддерживает быть обновленным асинхронно.

Полевая Деталь

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)

удалить

void remove(int offs,
          int len)
            throws BadLocationException

Удаляет часть контента документа. Это вызовет DocumentEvent типа DocumentEvent. EventType. УДАЛИТЕ, чтобы быть отправленными зарегистрированному DocumentListeners, если исключение не выдается. Уведомление будет отправлено слушателям, вызывая removeUpdate метод на DocumentListeners.

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

Если структура Документа, измененная как результат удаления, детали того, какие Элементы были вставлены и удалены в ответ на изменение, будет также содержаться в сгенерированном DocumentEvent. Это до реализации Документа, чтобы решить, как структура должна измениться в ответ на удаление.

Если Документ будет поддерживать отмену/восстановление, то UndoableEditEvent будет также сгенерирован.

Параметры:

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

len - число символов, чтобы удалить> = 0

Броски:

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

См. Также:

DocumentEvent, DocumentListener, UndoableEditEvent, UndoableEditListener

insertString

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

Вставляет строку контента. Это вызовет DocumentEvent типа DocumentEvent. EventType. ВСТАВЬТЕ, чтобы быть отправленными зарегистрированному DocumentListers, если исключение не выдается. DocumentEvent поставят, вызывая insertUpdate метод на DocumentListener. Смещение и длина сгенерированного DocumentEvent укажут на то, что изменение было фактически произведено в Документе.

Если структура Документа, измененная как результат вставки, детали того, какие Элементы были вставлены и удалены в ответ на изменение, будет также содержаться в сгенерированном DocumentEvent. Это до реализации Документа, чтобы решить, как структура должна измениться в ответ на вставку.

Если Документ будет поддерживать отмену/восстановление, то UndoableEditEvent будет также сгенерирован.

Параметры:

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

str - строка, чтобы вставить

a - атрибуты, чтобы связаться со вставленным контентом. Это может быть нулем, если нет никаких атрибутов.

Броски:

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

Выбирает текст, содержавший в пределах данной части документа.

Если partialReturn свойство на txt параметре будет ложью, то данные, возвращенные в Сегменте, будут всей длиной, которую требуют, и можете, или, возможно, не копия в зависимости от того, как данные хранились. Если partialReturn свойство является истиной, только количество текста, который может быть возвращен, не создавая копию, возвращается. Используя частичные возвраты даст лучшую производительность для ситуаций, где значительные части документа сканируются. Следующее является примером использования частичного возврата, чтобы получить доступ ко всему документу:

  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 - объект Сегмента возвратить текст в

Броски:

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

getStartPosition

Position getStartPosition()

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

Возвраты:

позиция

getEndPosition

Position getEndPosition()

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

Возвраты:

позиция

createPosition

Position createPosition(int offs)
                        throws BadLocationException

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

Параметры:

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

Возвраты:

позиция

Броски:

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

getRootElements

Element[] getRootElements()

Возвраты все корневые элементы, которые определяются.

Обычно будет только одна структура документа, но интерфейс поддерживает создание произвольного числа структурных проекций по текстовым данным. У документа могут быть многократные корневые элементы, чтобы поддерживать многократные структуры документа. Некоторые примеры могли бы быть:

• Текстовое направление.
• Лексические маркерные потоки.
• Деревья синтаксического анализа.
• Преобразования в форматы кроме собственного формата.
• Спецификации модификации.
• Аннотации.

Возвраты:

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

getDefaultRootElement

Element getDefaultRootElement()

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

Возвраты:

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

рендеринг

void render(Runnable r)

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

Параметры:

r - a Runnable используемый, чтобы представить модель