Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.swing.text
Interface Document

All Known Subinterfaces:
  StyledDocument

All Known Implementing Classes:
  AbstractDocument

public abstract 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.

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`, `AttributeSet`

Field Summary
`static java.lang.String` | `StreamDescriptionProperty` The property name for the description of the stream used to initialize the document.
`static java.lang.String` | `TitleProperty` The property name for the title of the document, if there is one.

Method Summary
`void` | `addDocumentListener(DocumentListener listener)` Registers the given observer to begin receiving notifications when changes are made to the document.
`void` | `addUndoableEditListener(UndoableEditListener listener)` Registers the given observer to begin receiving notifications when undoable edits are made to the document.
`Position` | `createPosition(int offs)` Returns a position that will track change as the document is altered.
`Element` | `getDefaultRootElement()` Returns the root element that views should be based upon, unless some other mechanism for assigning views to element structures is provided.
`Position` | `getEndPosition()` Returns a position that represents the end of the document.
`int` | `getLength()` Returns number of characters of content currently in the document.
`java.lang.Object` | `getProperty(java.lang.Object key)` Gets properties associated with the document.
`Element[]` | `getRootElements()` Returns all of the root elements that are defined.
`Position` | `getStartPosition()` Returns a position that represents the start of the document.
`java.lang.String` | `getText(int offset, int length)` Fetches the text contained within the given portion of the document.
`void` | `getText(int offset, int length, Segment txt)` Fetches the text contained within the given portion of the document.
`void` | `insertString(int offset, java.lang.String str, AttributeSet a)` Inserts a string of content.
`void` | `putProperty(java.lang.Object key, java.lang.Object value)` Puts a new property on the list.
`void` | `remove(int offs, int len)` Removes a portion of the content of the document.
`void` | `removeDocumentListener(DocumentListener listener)` Unregisters the given observer from the notification list so it will no longer receive change updates.
`void` | `removeUndoableEditListener(UndoableEditListener listener)` Unregisters the given observer from the notification list so it will no longer receive updates.
`void` | `render(java.lang.Runnable r)` This allows the model to be safely rendered in the presence of currency, if the model supports being updated asynchronously.

Field Detail

### StreamDescriptionProperty

    public static final 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.

### TitleProperty

    public static final java.lang.String TitleProperty

  The property name for the title of the document, if there is one.

Method Detail

### getLength

    public int getLength()

  Returns number of characters of content currently in the document.
  Returns:
    number of characters >= 0

### addDocumentListener

    public void addDocumentListener(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)`

### removeDocumentListener

    public void removeDocumentListener(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)`

### addUndoableEditListener

    public void addUndoableEditListener(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`

### removeUndoableEditListener

    public void removeUndoableEditListener(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`

### getProperty

    public java.lang.Object getProperty(java.lang.Object key)

  Gets properties associated with the document. Allows one to store things like the document title, author, etc.
  Parameters:
    `key` - a non-null property
  Returns:
    the properties

### putProperty

    public void putProperty(java.lang.Object key,
                            java.lang.Object value)

  Puts a new property on the list.
  Parameters:
    `key` - the non-null property key
    `value` - the property value

### remove

    public void remove(int offs,
                       int len)
                throws BadLocationException

  Removes 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 >= 0
    `len` - the number of characters to remove >= 0
  Throws:
    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`, `DocumentListener`

### insertString

    public void insertString(int offset,
                             java.lang.String str,
                             AttributeSet a)
                      throws BadLocationException

  Inserts 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. Does nothing with null or empty strings.
  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 - the given insert position is not a valid position within the document
  See Also:
    `DocumentEvent`, `DocumentListener`

### getText

    public java.lang.String getText(int offset,
                                    int length)
                             throws 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 - 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

    public void getText(int offset,
                        int length,
                        Segment txt)
                 throws 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
    `txt` - the Segment object to return the text in
  Throws:
    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

    public 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

    public 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

    public Position createPosition(int offs)
                            throws BadLocationException

  Returns 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:
    `offs` - the offset from the start of the document >= 0
  Returns:
    the position
  Throws:
    BadLocationException - if the given position does not represent a valid location in the associated document

### getRootElements

    public Element[] getRootElements()

  Returns all of the root elements that are defined.
  Returns:
    the root element

### getDefaultRootElement

    public 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

    public void render(java.lang.Runnable r)

  This allows the model to be safely rendered in the presence of currency, 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Swing 1.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,
Palo Alto, California, 94303, U.S.A. All Rights Reserved.