All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface com.sun.java.swing.text.Document

public interface Document

Container for text that supports editing and provides notification of changes (serves as the model in an MVC relationship). Support is provided to mark up the text with structure that tracks changes. The unit of structure is called an element. Views will typically be built from an element structure. Each element can have an arbitrary set of attributes associated with it. The interface itself is intended to be free of any policy for structure that is provided, as the nature of the document structure should be determined by the implementation. Since it is common for text documents to have lines or paragraphs, there are methods to get this kind of information.

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:

• Logical document structure.
• View projections.
• Lexical token streams.
• Parse trees.
• Conversions to formats other than the native format.
• Modification specifications.
• Annotations.

See Also:

DocumentEvent, DocumentListener, Element, Position, Range, Attributes

addDocumentListener(DocumentListener)

Register the given observer to begin receiving notifications when changes are made to the document.

checkinStickyPosition(Position)

Returns a sticky position that was previously checked out.

checkoutStickyPosition(Position, int)

Gives a position that will track change as the document is altered.

getAttributes()

Properties associated with the document.

getDefaultRootElement()

Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.

getEndPosition()

Gives a position that represents the end of the document.

getLength()

Number of characters of content that is currently contained in the document.

getLineCount()

Return the number of lines contained in the document.

getRootElement(String)

Return a root element of a document structure with the given name.

getStartPosition()

Gives a position that represents the start of the document.

getText(Range)

Fetch the text contained within the given portion of the document.

insertString(int, String, Attributes)

Insert a string of content.

insertString(Position, String, Attributes)

Insert a string of content.

lineToRange(int)

Convert the given line index to a range within the document.

positionToLine(Position)

Convert a position to a line/paragraph number within the document where the line numbers are indexed from 0.

remove(int, int)

Remove a portion of the content of the document.

remove(Range)

Remove a portion of the content of the document.

removeDocumentListener(DocumentListener)

Unregister the given observer from the notification list so they will no longer receive change updates.

setAttributes(Range, Attributes, boolean)

Change the content element attributes used for the given range of existing content in the document.

untrackedPosition(Position, int)

Gives a temporary position that doesn't track change.

 public abstract int getLength()

Number of characters of content that is currently contained in the document.

 public abstract void addDocumentListener(DocumentListener listener)

Register the given observer to begin receiving notifications when changes are made to the document.

Parameters:

listener - the observer to register

See Also:

removeDocumentListener

 public abstract void removeDocumentListener(DocumentListener listener)

Unregister the given observer from the notification list so they will no longer receive change updates.

Parameters:

listener - the observer to register

See Also:

addDocumentListener

 public abstract Attributes getAttributes()

Properties associated with the document. Allows one to store things like the document title, author, etc.

 public abstract void remove(Range rng) throws BadLocation

Remove a portion of the content of the document. This will cause notification to be sent to the observers of the document (unless an exception is thrown).

Parameters:

rng - The portion of the document to remove

Throws: BadLocation

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, DocumentListener

 public abstract void remove(int offs,
                             int len) throws BadLocation

Remove a portion of the content of the document. This will cause notification to be sent to the observers of the document (unless an exception is thrown).

Parameters:

offs - The offset from the begining

len - The number of characters to remove

Throws: BadLocation

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, DocumentListener

 public abstract void insertString(Position pos,
                                   String str,
                                   Attributes a) throws BadLocation

Insert a string of content. This will cause the observers of the the document to be notified, unless an exception is thrown. A position marks a location in the document between items. If the attributes that have been defined exactly match the current attributes defined at the position, the element representing the content at that position will simply be expanded. If the attributes defined are different, a new content element will be created that matches the attributes.

Parameters:

pos - The location in the document to insert the content. 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: BadLocation

The given insert position is not a valid position within the document.

See Also:

DocumentEvent, DocumentListener

 public abstract void insertString(int offset,
                                   String str,
                                   Attributes a) throws BadLocation

Insert a string of content. This will cause the observers of the the document to be notified, unless an exception is thrown. A position marks a location in the document between items. If the attributes that have been defined exactly match the current attributes defined at the position, the element representing the content at that position will simply be expanded. If the attributes defined are different, a new content element will be created that matches the attributes.

Parameters:

offset - The offset into the document to insert the content. 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: BadLocation

The given insert position is not a valid position within the document.

See Also:

DocumentEvent, DocumentListener

 public abstract String getText(Range rng) throws BadLocation

Fetch the text contained within the given portion of the document.

Parameters:

rng - The portion of the document to get the text of

Throws: BadLocation

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.

 public abstract Position getStartPosition()

Gives 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.

 public abstract Position getEndPosition()

Gives 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.

 public abstract void setAttributes(Range rng,
                                    Attributes s,
                                    boolean replace)

Change the content element attributes used for the given range of existing content in the document. All of the attributes defined in the given Attributes argument are applied to the given range. This method can be used to completely remove all content level attributes for the given range by giving an Attributes argument that has no attributes defined and setting replace to true. A write lock is held by this operation, and a DocumentEvent is sent to the listeners after the change has been successfully completed.

Parameters:

rng - The portion of the document to change

s - The attributes to change to. Any attributes defined will be applied to the text for the given range.

replace - Indicates whether or not the previous attributes should be cleared before the new attributes as set. If true, the operation will replace the previous attributes entirely. If false, the new attributes will be merged with the previous attributes.

 public abstract Position checkoutStickyPosition(Position pos,
                                                 int offs)

Gives a position that will track change as the document is altered. If the relative position pos is null, the start of the document will be used.

Parameters:

pos - relative position from which to create. null means the start of the document.

offs - number of characters offset from pos

See Also:

checkinStickyPosition

 public abstract void checkinStickyPosition(Position pos)

Returns a sticky position that was previously checked out. If the position given is not a position previously fetched with checkoutSTickyPosition() it will be ignored.

Parameters:

pos - position being returned.

See Also:

checkoutStickyPosition

 public abstract Position untrackedPosition(Position pos,
                                            int offs)

Gives a temporary position that doesn't track change. These positions are fragile and may be incorrect after the document is edited. They don't need to be returned to the document however.

Parameters:

pos - relative position from which to create. null means the start of the document.

offs - number of characters offset from pos

 public abstract int positionToLine(Position pos) throws BadLocation

Convert a position to a line/paragraph number within the document where the line numbers are indexed from 0.

Parameters:

pos - position to map to a line

Throws: BadLocation

The given position is not a valid location within the document.

 public abstract Range lineToRange(int line)

Convert the given line index to a range within the document. If the given line is invalid, null will be returned.

Parameters:

line - index of the line to be mapped.

 public abstract int getLineCount()

Return the number of lines contained in the document.

 public abstract Element getRootElement(String nm)

Return a root element of a document structure with the given name.

Parameters:

nm - The name of the root element desired

 public abstract Element getDefaultRootElement()

Returns the root element that views should be based upon unless some other mechanism for assigning views to element structures is provided.

All Packages  Class Hierarchy  This Package  Previous  Next  Index