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:

• Document
• AbstractDocument

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

Fields

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

Constructors

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 FooListeners 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:

• Constant Field Values

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:

• Constant Field Values

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:

• Document.insertString(int, String, AttributeSet)

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:

• Document.getDefaultRootElement()

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