javax.swing.text
Interface Document

All Known Subinterfaces:
StyledDocument sample code for javax.swing.text.StyledDocument definition code for javax.swing.text.StyledDocument
All Known Implementing Classes:
AbstractDocument sample code for javax.swing.text.AbstractDocument definition code for javax.swing.text.AbstractDocument , DefaultStyledDocument sample code for javax.swing.text.DefaultStyledDocument definition code for javax.swing.text.DefaultStyledDocument , HTMLDocument sample code for javax.swing.text.html.HTMLDocument definition code for javax.swing.text.html.HTMLDocument , PlainDocument sample code for javax.swing.text.PlainDocument definition code for javax.swing.text.PlainDocument

public interface Document

The Document is a container for text that serves as the model for swing text components. The goal for this interface is to scale from very simple needs (a plain text textfield) to complex needs (an HTML or XML document, for example).

Content

At the simplest level, text can be modeled as a linear sequence of characters. To support internationalization, the Swing text model uses unicode characters. The sequence of characters displayed in a text component is generally referred to as the component's content.

To refer to locations within the sequence, the coordinates used are the location between two characters. As the diagram below shows, a location in a text document can be referred to as a position, or an offset. This position is zero-based.

The following text describes this graphic.

In the example, if the content of a document is the sequence "The quick brown fox," as shown in the preceding diagram, the location just before the word "The" is 0, and the location after the word "The" and before the whitespace that follows it is 3. The entire sequence of characters in the sequence "The" is called a range.

The following methods give access to the character data that makes up the content.

Structure

Text is rarely represented simply as featureless content. Rather, text typically has some sort of structure associated with it. Exactly what structure is modeled is up to a particular Document implementation. It might be as simple as no structure (i.e. a simple text field), or it might be something like diagram below.

Diagram shows Book->Chapter->Paragraph

The unit of structure (i.e. a node of the tree) is referred to by the Element interface. Each Element can be tagged with a set of attributes. These attributes (name/value pairs) are defined by the AttributeSet interface.

The following methods give access to the document structure.

Mutations

All documents need to be able to add and remove simple text. Typically, text is inserted and removed via gestures from a keyboard or a mouse. What effect the insertion or removal has upon the document structure is entirely up to the implementation of the document.

The following methods are related to mutation of the document content:

Notification

Mutations to the Document must be communicated to interested observers. The notification of change follows the event model guidelines that are specified for JavaBeans. In the JavaBeans event model, once an event notification is dispatched, all listeners must be notified before any further mutations occur to the source of the event. Further, order of delivery is not guaranteed.

Notification is provided as two separate events, DocumentEvent, and UndoableEditEvent. If a mutation is made to a Document through its api, a DocumentEvent will be sent to all of the registered DocumentListeners. If the Document implementation supports undo/redo capabilities, an UndoableEditEvent will be sent to all of the registered UndoableEditListeners. If an undoable edit is undone, a DocumentEvent should be fired from the Document to indicate it has changed again. In this case however, there should be no UndoableEditEvent generated since that edit is actually the source of the change rather than a mutation to the Document made through its api.

The preceeding text describes this graphic.

Referring to the above diagram, suppose that the component shown on the left mutates the document object represented by the blue rectangle. The document responds by dispatching a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic, which maintains a history buffer.

Now suppose that the component shown on the right mutates the same document. Again, the document dispatches a DocumentEvent to both component views and sends an UndoableEditEvent to the listening logic that is maintaining the history buffer.

If the history buffer is then rolled back (i.e. the last UndoableEdit undone), a DocumentEvent is sent to both views, causing both of them to reflect the undone mutation to the document (that is, the removal of the right component's mutation). If the history buffer again rolls back another change, another DocumentEvent is sent to both views, causing them to reflect the undone mutation to the document -- that is, the removal of the left component's mutation.

The methods related to observing mutations to the document are:

Properties

Document implementations will generally have some set of properties associated with them at runtime. Two well known properties are the StreamDescriptionProperty, which can be used to describe where the Document came from, and the TitleProperty, which can be used to name the Document. The methods related to the properties are:

For more information on the Document class, see The Swing Connection and most particularly the article, The Element Interface.

See Also:
DocumentEvent sample code for javax.swing.event.DocumentEvent definition code for javax.swing.event.DocumentEvent , DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener , UndoableEditEvent sample code for javax.swing.event.UndoableEditEvent definition code for javax.swing.event.UndoableEditEvent , UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener , Element sample code for javax.swing.text.Element definition code for javax.swing.text.Element , Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position , AttributeSet sample code for javax.swing.text.AttributeSet definition code for javax.swing.text.AttributeSet

Field Summary
static String sample code for java.lang.String definition code for java.lang.String StreamDescriptionProperty sample code for javax.swing.text.Document.StreamDescriptionProperty definition code for javax.swing.text.Document.StreamDescriptionProperty
          The property name for the description of the stream used to initialize the document.
static String sample code for java.lang.String definition code for java.lang.String TitleProperty sample code for javax.swing.text.Document.TitleProperty definition code for javax.swing.text.Document.TitleProperty
          The property name for the title of the document, if there is one.
 
Method Summary
 void addDocumentListener sample code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener) (DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener  listener)
          Registers the given observer to begin receiving notifications when changes are made to the document.
 void addUndoableEditListener sample code for javax.swing.text.Document.addUndoableEditListener(javax.swing.event.UndoableEditListener) definition code for javax.swing.text.Document.addUndoableEditListener(javax.swing.event.UndoableEditListener) (UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener  listener)
          Registers the given observer to begin receiving notifications when undoable edits are made to the document.
 Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position createPosition sample code for javax.swing.text.Document.createPosition(int) definition code for javax.swing.text.Document.createPosition(int) (int offs)
          This method allows an application to mark a place in a sequence of character content.
 Element sample code for javax.swing.text.Element definition code for javax.swing.text.Element getDefaultRootElement sample code for javax.swing.text.Document.getDefaultRootElement() definition code for javax.swing.text.Document.getDefaultRootElement() ()
          Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
 Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position getEndPosition sample code for javax.swing.text.Document.getEndPosition() definition code for javax.swing.text.Document.getEndPosition() ()
          Returns a position that represents the end of the document.
 int getLength sample code for javax.swing.text.Document.getLength() definition code for javax.swing.text.Document.getLength() ()
          Returns number of characters of content currently in the document.
 Object sample code for java.lang.Object definition code for java.lang.Object getProperty sample code for javax.swing.text.Document.getProperty(java.lang.Object) definition code for javax.swing.text.Document.getProperty(java.lang.Object) (Object sample code for java.lang.Object definition code for java.lang.Object  key)
          Gets the properties associated with the document.
 Element sample code for javax.swing.text.Element definition code for javax.swing.text.Element [] getRootElements sample code for javax.swing.text.Document.getRootElements() definition code for javax.swing.text.Document.getRootElements() ()
          Returns all of the root elements that are defined.
 Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position getStartPosition sample code for javax.swing.text.Document.getStartPosition() definition code for javax.swing.text.Document.getStartPosition() ()
          Returns a position that represents the start of the document.
 String sample code for java.lang.String definition code for java.lang.String getText sample code for javax.swing.text.Document.getText(int, int) definition code for javax.swing.text.Document.getText(int, int) (int offset, int length)
          Fetches the text contained within the given portion of the document.
 void getText sample code for javax.swing.text.Document.getText(int, int, javax.swing.text.Segment) definition code for javax.swing.text.Document.getText(int, int, javax.swing.text.Segment) (int offset, int length, Segment sample code for javax.swing.text.Segment definition code for javax.swing.text.Segment  txt)
          Fetches the text contained within the given portion of the document.
 void insertString sample code for javax.swing.text.Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet) definition code for javax.swing.text.Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet) (int offset, String sample code for java.lang.String definition code for java.lang.String  str, AttributeSet sample code for javax.swing.text.AttributeSet definition code for javax.swing.text.AttributeSet  a)
          Inserts a string of content.
 void putProperty sample code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object) definition code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object) (Object sample code for java.lang.Object definition code for java.lang.Object  key, Object sample code for java.lang.Object definition code for java.lang.Object  value)
          Associates a property with the document.
 void remove sample code for javax.swing.text.Document.remove(int, int) definition code for javax.swing.text.Document.remove(int, int) (int offs, int len)
          Removes a portion of the content of the document.
 void removeDocumentListener sample code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener) (DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener  listener)
          Unregisters the given observer from the notification list so it will no longer receive change updates.
 void removeUndoableEditListener sample code for javax.swing.text.Document.removeUndoableEditListener(javax.swing.event.UndoableEditListener) definition code for javax.swing.text.Document.removeUndoableEditListener(javax.swing.event.UndoableEditListener) (UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener  listener)
          Unregisters the given observer from the notification list so it will no longer receive updates.
 void render sample code for javax.swing.text.Document.render(java.lang.Runnable) definition code for javax.swing.text.Document.render(java.lang.Runnable) (Runnable sample code for java.lang.Runnable definition code for java.lang.Runnable  r)
          Allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously.
 

Field Detail

StreamDescriptionProperty sample code for javax.swing.text.Document.StreamDescriptionProperty

static final String sample code for java.lang.String definition code for java.lang.String  StreamDescriptionProperty
The property name for the description of the stream used to initialize the document. This should be used if the document was initialized from a stream and anything is known about the stream.

See Also:
Constant Field Values

TitleProperty sample code for javax.swing.text.Document.TitleProperty

static final String sample code for java.lang.String definition code for java.lang.String  TitleProperty
The property name for the title of the document, if there is one.

See Also:
Constant Field Values
Method Detail

getLength sample code for javax.swing.text.Document.getLength() definition code for javax.swing.text.Document.getLength()

int getLength()
Returns number of characters of content currently in the document.

Returns:
number of characters >= 0

addDocumentListener sample code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener)

void addDocumentListener(DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener  listener)
Registers the given observer to begin receiving notifications when changes are made to the document.

Parameters:
listener - the observer to register
See Also:
removeDocumentListener(javax.swing.event.DocumentListener) sample code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener)

removeDocumentListener sample code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.removeDocumentListener(javax.swing.event.DocumentListener)

void removeDocumentListener(DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener  listener)
Unregisters the given observer from the notification list so it will no longer receive change updates.

Parameters:
listener - the observer to register
See Also:
addDocumentListener(javax.swing.event.DocumentListener) sample code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener) definition code for javax.swing.text.Document.addDocumentListener(javax.swing.event.DocumentListener)

addUndoableEditListener sample code for javax.swing.text.Document.addUndoableEditListener(javax.swing.event.UndoableEditListener) definition code for javax.swing.text.Document.addUndoableEditListener(javax.swing.event.UndoableEditListener)

void addUndoableEditListener(UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener  listener)
Registers the given observer to begin receiving notifications when undoable edits are made to the document.

Parameters:
listener - the observer to register
See Also:
UndoableEditEvent sample code for javax.swing.event.UndoableEditEvent definition code for javax.swing.event.UndoableEditEvent

removeUndoableEditListener sample code for javax.swing.text.Document.removeUndoableEditListener(javax.swing.event.UndoableEditListener) definition code for javax.swing.text.Document.removeUndoableEditListener(javax.swing.event.UndoableEditListener)

void removeUndoableEditListener(UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener  listener)
Unregisters the given observer from the notification list so it will no longer receive updates.

Parameters:
listener - the observer to register
See Also:
UndoableEditEvent sample code for javax.swing.event.UndoableEditEvent definition code for javax.swing.event.UndoableEditEvent

getProperty sample code for javax.swing.text.Document.getProperty(java.lang.Object) definition code for javax.swing.text.Document.getProperty(java.lang.Object)

Object sample code for java.lang.Object definition code for java.lang.Object  getProperty(Object sample code for java.lang.Object definition code for java.lang.Object  key)
Gets the properties associated with the document.

Parameters:
key - a non-null property key
Returns:
the properties
See Also:
putProperty(Object, Object) sample code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object) definition code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object)

putProperty sample code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object) definition code for javax.swing.text.Document.putProperty(java.lang.Object, java.lang.Object)

void putProperty(Object sample code for java.lang.Object definition code for java.lang.Object  key,
                 Object sample code for java.lang.Object definition code for java.lang.Object  value)
Associates a property with the document. Two standard property keys provided are: StreamDescriptionProperty and TitleProperty. Other properties, such as author, may also be defined.

Parameters:
key - the non-null property key
value - the property value
See Also:
getProperty(Object) sample code for javax.swing.text.Document.getProperty(java.lang.Object) definition code for javax.swing.text.Document.getProperty(java.lang.Object)

remove sample code for javax.swing.text.Document.remove(int, int) definition code for javax.swing.text.Document.remove(int, int)

void remove(int offs,
            int len)
            throws BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException 
Removes a portion of the content of the document. This will cause a DocumentEvent of type DocumentEvent.EventType.REMOVE to be sent to the registered DocumentListeners, unless an exception is thrown. The notification will be sent to the listeners by calling the removeUpdate method on the DocumentListeners.

To ensure reasonable behavior in the face of concurrency, the event is dispatched after the mutation has occurred. This means that by the time a notification of removal is dispatched, the document has already been updated and any marks created by createPosition have already changed. For a removal, the end of the removal range is collapsed down to the start of the range, and any marks in the removal range are collapsed down to the start of the range.

Diagram shows removal of 'quick' from 'The quick brown fox.'

If the Document structure changed as result of the removal, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to a remove.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Parameters:
offs - the offset from the beginning >= 0
len - the number of characters to remove >= 0
Throws:
BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.
See Also:
DocumentEvent sample code for javax.swing.event.DocumentEvent definition code for javax.swing.event.DocumentEvent , DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener , UndoableEditEvent sample code for javax.swing.event.UndoableEditEvent definition code for javax.swing.event.UndoableEditEvent , UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener

insertString sample code for javax.swing.text.Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet) definition code for javax.swing.text.Document.insertString(int, java.lang.String, javax.swing.text.AttributeSet)

void insertString(int offset,
                  String sample code for java.lang.String definition code for java.lang.String  str,
                  AttributeSet sample code for javax.swing.text.AttributeSet definition code for javax.swing.text.AttributeSet  a)
                  throws BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException 
Inserts a string of content. This will cause a DocumentEvent of type DocumentEvent.EventType.INSERT to be sent to the registered DocumentListers, unless an exception is thrown. The DocumentEvent will be delivered by calling the insertUpdate method on the DocumentListener. The offset and length of the generated DocumentEvent will indicate what change was actually made to the Document.

Diagram shows insertion of 'quick' in 'The quick brown fox'

If the Document structure changed as result of the insertion, the details of what Elements were inserted and removed in response to the change will also be contained in the generated DocumentEvent. It is up to the implementation of a Document to decide how the structure should change in response to an insertion.

If the Document supports undo/redo, an UndoableEditEvent will also be generated.

Parameters:
offset - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.
str - the string to insert
a - the attributes to associate with the inserted content. This may be null if there are no attributes.
Throws:
BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException - the given insert position is not a valid position within the document
See Also:
DocumentEvent sample code for javax.swing.event.DocumentEvent definition code for javax.swing.event.DocumentEvent , DocumentListener sample code for javax.swing.event.DocumentListener definition code for javax.swing.event.DocumentListener , UndoableEditEvent sample code for javax.swing.event.UndoableEditEvent definition code for javax.swing.event.UndoableEditEvent , UndoableEditListener sample code for javax.swing.event.UndoableEditListener definition code for javax.swing.event.UndoableEditListener

getText sample code for javax.swing.text.Document.getText(int, int) definition code for javax.swing.text.Document.getText(int, int)

String sample code for java.lang.String definition code for java.lang.String  getText(int offset,
               int length)
               throws BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException 
Fetches the text contained within the given portion of the document.

Parameters:
offset - the offset into the document representing the desired start of the text >= 0
length - the length of the desired string >= 0
Returns:
the text, in a String of length >= 0
Throws:
BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException - some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getText sample code for javax.swing.text.Document.getText(int, int, javax.swing.text.Segment) definition code for javax.swing.text.Document.getText(int, int, javax.swing.text.Segment)

void getText(int offset,
             int length,
             Segment sample code for javax.swing.text.Segment definition code for javax.swing.text.Segment  txt)
             throws BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException 
Fetches the text contained within the given portion of the document.

If the partialReturn property on the txt parameter is false, the data returned in the Segment will be the entire length requested and may or may not be a copy depending upon how the data was stored. If the partialReturn property is true, only the amount of text that can be returned without creating a copy is returned. Using partial returns will give better performance for situations where large parts of the document are being scanned. The following is an example of using the partial return to access the entire document:



   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;
   }

 

Parameters:
offset - the offset into the document representing the desired start of the text >= 0
length - the length of the desired string >= 0
txt - the Segment object to return the text in
Throws:
BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException - Some portion of the given range was not a valid part of the document. The location in the exception is the first bad position encountered.

getStartPosition sample code for javax.swing.text.Document.getStartPosition() definition code for javax.swing.text.Document.getStartPosition()

Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position  getStartPosition()
Returns a position that represents the start of the document. The position returned can be counted on to track change and stay located at the beginning of the document.

Returns:
the position

getEndPosition sample code for javax.swing.text.Document.getEndPosition() definition code for javax.swing.text.Document.getEndPosition()

Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position  getEndPosition()
Returns a position that represents the end of the document. The position returned can be counted on to track change and stay located at the end of the document.

Returns:
the position

createPosition sample code for javax.swing.text.Document.createPosition(int) definition code for javax.swing.text.Document.createPosition(int)

Position sample code for javax.swing.text.Position definition code for javax.swing.text.Position  createPosition(int offs)
                        throws BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException 
This method allows an application to mark a place in a sequence of character content. This mark can then be used to tracks change as insertions and removals are made in the content. The policy is that insertions always occur prior to the current position (the most common case) unless the insertion location is zero, in which case the insertion is forced to a position that follows the original position.

Parameters:
offs - the offset from the start of the document >= 0
Returns:
the position
Throws:
BadLocationException sample code for javax.swing.text.BadLocationException definition code for javax.swing.text.BadLocationException - if the given position does not represent a valid location in the associated document

getRootElements sample code for javax.swing.text.Document.getRootElements() definition code for javax.swing.text.Document.getRootElements()

Element sample code for javax.swing.text.Element definition code for javax.swing.text.Element [] getRootElements()
Returns all of the root elements that are defined.

Typically there will be only one document structure, but the interface supports building an arbitrary number of structural projections over the text data. The document can have multiple root elements to support multiple document structures. Some examples might be:

Returns:
the root element

getDefaultRootElement sample code for javax.swing.text.Document.getDefaultRootElement() definition code for javax.swing.text.Document.getDefaultRootElement()

Element sample code for javax.swing.text.Element definition code for javax.swing.text.Element  getDefaultRootElement()
Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.

Returns:
the root element

render sample code for javax.swing.text.Document.render(java.lang.Runnable) definition code for javax.swing.text.Document.render(java.lang.Runnable)

void render(Runnable sample code for java.lang.Runnable definition code for java.lang.Runnable  r)
Allows the model to be safely rendered in the presence of concurrency, if the model supports being updated asynchronously. The given runnable will be executed in a way that allows it to safely read the model with no changes while the runnable is being executed. The runnable itself may not make any mutations.

Parameters:
r - a Runnable used to render the model