Class PlainDocument

java.lang.Object

javax.swing.text.AbstractDocument

javax.swing.text.PlainDocument

All Implemented Interfaces:: Serializable, Document

public class PlainDocument extends AbstractDocument

A plain document that maintains no character attributes. The default element structure for this document is a map of the lines in the text. The Element returned by getDefaultRootElement is a map of the lines, and each child element represents a line. This model does not maintain any character level attributes, but each line can be tagged with an arbitrary set of attributes. Line to offset, and offset to line translations can be quickly performed using the default root element. The structure information of the DocumentEvent's fired by edits will indicate the line structure changes.

The default content storage management is performed by a gapped buffer implementation (GapContent). It supports editing reasonably large documents with good efficiency when the edits are contiguous or clustered, as is typical.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans has been added to the java.beans package. Please see XMLEncoder.

See Also:

Nested Class Summary

Nested classes/interfaces declared in class AbstractDocument

AbstractDocument.AbstractElement, AbstractDocument.AttributeContext, AbstractDocument.BranchElement, AbstractDocument.Content, AbstractDocument.DefaultDocumentEvent, AbstractDocument.ElementEdit, AbstractDocument.LeafElement

Modifier and Type	Class	Description
`class`	`AbstractDocument.AbstractElement`	Implements the abstract part of an element.
`static interface`	`AbstractDocument.AttributeContext`	An interface that can be used to allow MutableAttributeSet implementations to use pluggable attribute compression techniques.
`class`	`AbstractDocument.BranchElement`	Implements a composite element that contains other elements.
`static interface`	`AbstractDocument.Content`	Interface to describe a sequence of character content that can be edited.
`class`	`AbstractDocument.DefaultDocumentEvent`	Stores document changes as the document is being modified.
`static class`	`AbstractDocument.ElementEdit`	An implementation of ElementChange that can be added to the document event.
`class`	`AbstractDocument.LeafElement`	Implements an element that directly represents content of some kind.

Field Summary

Modifier and Type	Field	Description
`static final String`	`lineLimitAttribute`	Name of the attribute that specifies the maximum length of a line, if there is a maximum length.
`static final String`	`tabSizeAttribute`	Name of the attribute that specifies the tab size for tabs contained in the content.

Fields declared in class AbstractDocument

BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName

Modifier and Type	Field	Description
`protected static final String`	`BAD_LOCATION`	Error message to indicate a bad location.
`static final String`	`BidiElementName`	Name of elements used to hold a unidirectional run
`static final String`	`ContentElementName`	Name of elements used to represent content
`static final String`	`ElementNameAttribute`	Name of the attribute used to specify element names.
`protected EventListenerList`	`listenerList`	The event listener list for the document.
`static final String`	`ParagraphElementName`	Name of elements used to represent paragraphs
`static final String`	`SectionElementName`	Name of elements used to hold sections (lines/paragraphs).

Fields declared in interface Document

StreamDescriptionProperty, TitleProperty

Modifier and Type	Field	Description
`static final String`	`StreamDescriptionProperty`	The property name for the description of the stream used to initialize the document.
`static final String`	`TitleProperty`	The property name for the title of the document, if there is one.

Constructor Summary

Constructor	Description
`PlainDocument()`	Constructs a plain text document.
`PlainDocument(AbstractDocument.Content c)`	Constructs a plain text document.

Method Summary

Modifier and Type	Method	Description
`protected AbstractDocument.AbstractElement`	`createDefaultRoot()`	Creates the root element to be used to represent the default document structure.
`Element`	`getDefaultRootElement()`	Gets the default root element for the document model.
`Element`	`getParagraphElement(int pos)`	Get the paragraph element containing the given position.
`void`	`insertString(int offs, String str, AttributeSet a)`	Inserts some content into the document.
`protected void`	`insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)`	Updates document structure as a result of text insertion.
`protected void`	`removeUpdate(AbstractDocument.DefaultDocumentEvent chng)`	Updates any document structure as a result of text removal.

Methods declared in class AbstractDocument

addDocumentListener, addUndoableEditListener, createBranchElement, createLeafElement, createPosition, dump, fireChangedUpdate, fireInsertUpdate, fireRemoveUpdate, fireUndoableEditUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeDocumentListener, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock

Modifier and Type	Method	Description
`void`	`addDocumentListener(DocumentListener listener)`	Adds a document listener for notification of any changes.
`void`	`addUndoableEditListener(UndoableEditListener listener)`	Adds an undo listener for notification of any changes.
`protected Element`	`createBranchElement(Element parent, AttributeSet a)`	Creates a document branch element, that can contain other elements.
`protected Element`	`createLeafElement(Element parent, AttributeSet a, int p0, int p1)`	Creates a document leaf element.
`Position`	`createPosition(int offs)`	Returns a position that will track change as the document is altered.
`void`	`dump(PrintStream out)`	Gives a diagnostic dump.
`protected void`	`fireChangedUpdate(DocumentEvent e)`	Notifies all listeners that have registered interest for notification on this event type.
`protected void`	`fireInsertUpdate(DocumentEvent e)`	Notifies all listeners that have registered interest for notification on this event type.
`protected void`	`fireRemoveUpdate(DocumentEvent e)`	Notifies all listeners that have registered interest for notification on this event type.
`protected void`	`fireUndoableEditUpdate(UndoableEditEvent e)`	Notifies all listeners that have registered interest for notification on this event type.
`int`	`getAsynchronousLoadPriority()`	Gets the asynchronous loading priority.
`protected final AbstractDocument.AttributeContext`	`getAttributeContext()`	Fetches the context for managing attributes.
`Element`	`getBidiRootElement()`	Returns the root element of the bidirectional structure for this document.
`protected final AbstractDocument.Content`	`getContent()`	Gets the content for the document.
`protected final Thread`	`getCurrentWriter()`	Fetches the current writing thread if there is one.
`DocumentFilter`	`getDocumentFilter()`	Returns the `DocumentFilter` that is responsible for filtering of insertion/removal.
`DocumentListener[]`	`getDocumentListeners()`	Returns an array of all the document listeners registered on this document.
`Dictionary<Object,Object>`	`getDocumentProperties()`	Supports managing a set of properties.
`final Position`	`getEndPosition()`	Returns a position that represents the end of the document.
`int`	`getLength()`	Returns the length of the data.
`<T extends EventListener> T[]`	`getListeners(Class<T> listenerType)`	Returns an array of all the objects currently registered as `FooListener`s upon this document.
`final Object`	`getProperty(Object key)`	A convenience method for looking up a property value.
`Element[]`	`getRootElements()`	Gets all root elements defined.
`final Position`	`getStartPosition()`	Returns a position that represents the start of the document.
`String`	`getText(int offset, int length)`	Gets a sequence of text from the document.
`void`	`getText(int offset, int length, Segment txt)`	Fetches the text contained within the given portion of the document.
`UndoableEditListener[]`	`getUndoableEditListeners()`	Returns an array of all the undoable edit listeners registered on this document.
`protected void`	`postRemoveUpdate(AbstractDocument.DefaultDocumentEvent chng)`	Updates any document structure as a result of text removal.
`final void`	`putProperty(Object key, Object value)`	A convenience method for storing up a property value.
`final void`	`readLock()`	Acquires a lock to begin reading some state from the document.
`final void`	`readUnlock()`	Does a read unlock.
`void`	`remove(int offs, int len)`	Removes some content from the document.
`void`	`removeDocumentListener(DocumentListener listener)`	Removes a document listener.
`void`	`removeUndoableEditListener(UndoableEditListener listener)`	Removes an undo listener.
`void`	`render(Runnable r)`	This allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously.
`void`	`replace(int offset, int length, String text, AttributeSet attrs)`	Deletes the region of text from `offset` to `offset + length`, and replaces it with `text`.
`void`	`setAsynchronousLoadPriority(int p)`	Sets the asynchronous loading priority.
`void`	`setDocumentFilter(DocumentFilter filter)`	Sets the `DocumentFilter`.
`void`	`setDocumentProperties(Dictionary<Object,Object> x)`	Replaces the document properties dictionary for this document.
`protected final void`	`writeLock()`	Acquires a lock to begin mutating the document this lock protects.
`protected final void`	`writeUnlock()`	Releases a write lock previously obtained via `writeLock`.

Methods declared in class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Modifier and Type	Method	Description
`protected Object`	`clone()`	Creates and returns a copy of this object.
`boolean`	`equals(Object obj)`	Indicates whether some other object is "equal to" this one.
`protected void`	`finalize()`	Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release.
`final Class<?>`	`getClass()`	Returns the runtime class of this `Object`.
`int`	`hashCode()`	Returns a hash code value for this object.
`final void`	`notify()`	Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()`	Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()`	Returns a string representation of the object.
`final void`	`wait()`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
`final void`	`wait(long timeoutMillis)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis, int nanos)`	Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

Field Details

tabSizeAttribute

public static final String tabSizeAttribute

Name of the attribute that specifies the tab size for tabs contained in the content. The type for the value is Integer.

See Also:

lineLimitAttribute

public static final String lineLimitAttribute

Name of the attribute that specifies the maximum length of a line, if there is a maximum length. The type for the value is Integer.

See Also:

Constructor Details

PlainDocument

public PlainDocument()

Constructs a plain text document. A default model using GapContent is constructed and set.

PlainDocument

public PlainDocument(AbstractDocument.Content c)

Constructs a plain text document. A default root element is created, and the tab size set to 8.

Parameters:: c - the container for the content

Method Details

insertString

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

Inserts some content into the document. Inserting content causes a write lock to be held while the actual changes are taking place, followed by notification to the observers on the thread that grabbed the write lock.

This method is thread safe, although most Swing methods are not. Please see Concurrency in Swing for more information.

Specified by:

insertString in interface Document

Overrides:

insertString in class AbstractDocument

Parameters:

offs - the starting offset >= 0

str - the string to insert; does nothing with null/empty strings

a - the attributes for the inserted content

Throws:

BadLocationException - the given insert position is not a valid position within the document

See Also:

getDefaultRootElement

public Element getDefaultRootElement()

Gets the default root element for the document model.

Specified by:

getDefaultRootElement in interface Document

Specified by:

getDefaultRootElement in class AbstractDocument

Returns:

the root

See Also:

createDefaultRoot

protected AbstractDocument.AbstractElement createDefaultRoot()

Creates the root element to be used to represent the default document structure.

Returns:: the element base

getParagraphElement

public Element getParagraphElement(int pos)

Get the paragraph element containing the given position. Since this document only models lines, it returns the line instead.

Specified by:: getParagraphElement in class AbstractDocument
Parameters:: pos - the starting offset >= 0
Returns:: the element

insertUpdate

protected void insertUpdate(AbstractDocument.DefaultDocumentEvent chng, AttributeSet attr)

Updates document structure as a result of text insertion. This will happen within a write lock. Since this document simply maps out lines, we refresh the line map.

Overrides:: insertUpdate in class AbstractDocument
Parameters:: chng - the change event describing the dit; attr - the set of attributes for the inserted text

removeUpdate

protected void removeUpdate(AbstractDocument.DefaultDocumentEvent chng)

Updates any document structure as a result of text removal. This will happen within a write lock. Since the structure represents a line map, this just checks to see if the removal spans lines. If it does, the two lines outside of the removal area are joined together.

Overrides:: removeUpdate in class AbstractDocument
Parameters:: chng - the change event describing the edit

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.